i.MX7D Sabre Board Support Package

1. About this document
======================

This document describes common and non-hardware specific information.
Please refer to README.hardware for hardware specific information.

Dependencies
------------
This layer depends on the oe-core version supplied with Wind River
Linux and the wr-kernel layer.

Maintenance
-----------
This layer is maintained by Wind River Systems, Inc.
Contact <support@windriver.com> or your support representative for more
information on submitting changes.

Building the nxp-imx7 layer
---------------------------
This layer and wr-kernel layer should be added to bblayers.conf. This
is done automatically when using the Wind River configure wrapper.

License
-------
Copyright (C) 2023 Wind River Systems, Inc.

Source code included in the tree for individual recipes is under the LICENSE
stated in the associated recipe (.bb file) unless otherwise stated.

The metadata is under the following license unless otherwise stated.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

2. BSP Kernel and Distros
=========================

The following table summarizes the valid Wind River Linux distros for this BSP.
'Y' in each content cell stands for supported; 'N' stands for not supported:

  +--------------+-------------+------------------+-------------------+--------------+
  | valid/distro |   wrlinux   | wrlinux-graphics | wrlinux-installer | wrlinux-tiny |
  +--------------+-------------+------------------+-------------------+--------------+
  |    valid     |      Y      |        Y         |         N         |       N      |
  +--------------+-------------+------------------+-------------------+--------------+

For the supported kernel type for this BSP, please check the TARGET_SUPPORTED_KTYPES
by running 'bitbake -e virtual/kernel | grep "^TARGET_SUPPORTED_KTYPES="'.

Note: The preempt-rt ktype is available for this BSP/Machine at this time.

3. Board Specific Patches
=========================
To get a list of patches applied to the kernel specific to this BSP,
along with patch descriptions, use git to see what changed on the default
kernel (git whatchanged <kernel_type>..<bsp_name>). For example:

	# cd tmp-glibc/work-shared/nxp-imx7/kernel-source
	# git whatchanged standard/base..


4. Boot Instructions
====================

4.1 MMC/SD Boot
---------------
User can use the OpenEmbedded Image Creator, wic, to create the properly
partitioned image on a SD card. The wic command
generates partitioned images from existing OpenEmbedded build artifacts.
User can refer to the below URL to get more WIC details:

https://docs.yoctoproject.org/4.0.5/dev-manual/common-tasks.html#creating-partitioned-images-using-wic

This BSP supports disk images for SD card.
After build the project, user will get a WIC image under the directory
tmp-glibc/deploy/images/<bsp name>/ ,such as:

tmp-glibc/deploy/images/nxp-imx7/wrlinux-image-std-nxp-imx7.wic

Then user can write the output image to a SD card.

4.2 NFS Root File System
------------------------

4.2.1 Prepare Kernel, DTB, NFS and TFTP servers
-----------------------------------------------
The files in the following example can be found in <buildprj>/tmp-glibc/deploy/images/nxp-imx7
and are copied to the export directory of the TFTP server.

4.2.2 Download kernel
---------------------

	# tftp ${loadaddr} zImage

4.2.3 Download DTB
------------------

	# tftp ${fdt_addr} imx7d-sdb.dtb

4.2.4 Set bootargs and boot the system
--------------------------------------

	# setenv bootargs console=ttymxc0,115200 root=/dev/nfs rw \
		 nfsroot=<nfs server>:<nfs root>,v3,tcp \
		 ip=<target IP>::<gateway>:<netmask>::eth0:off
	# bootz ${loadaddr} - ${fdt_addr}

Note: for MCIMX7D-SDB board, $loadaddr="0x80800000", $fdt_addr="0x87000000"

5. Features
===========

5.1 Static PM
-------------

The debug UART can be set as a wakeup source with:
	# echo enabled > /sys/class/tty/ttymxc0/power/wakeup
	# echo mem > /sys/power/state

5.2 CPU frequency
------------------

CPU frequency scaling allows the clock speed of the CPU to be changed on the fly.

	# echo powersave > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
	# cat /proc/cpuinfo

5.3 ANATOP thermal
-------------------

	To check current CPU temperature
	# cd /sys/class/thermal/thermal_zone0
	# cat temp
	39821
	# cat trip_point_0_type
	passive
	# cat trip_point_0_temp
	95000

5.4 Audio
---------
Play audio messages:

For imx7d, enable Output Mixer PCM like the following:
amixer sset 'Right Output Mixer PCM' on
amixer sset 'Left Output Mixer PCM' on

	# aplay -Dhw:0,0 stereo1644s.wav


5.5 PCIe
--------

Since the PCIe connector on-board only exports PETP0/N0, PERP0/N0 and 3.3V
pins, any mini-PCIe devices that use other PCIe pins won't be supported.
The following PCIe peripherals are validated:

	Intel Centrino Advanced-N 6205
	Intel Centrino Wireless-N 1030

The PCIe driver does not support hotplug and suspend/resume.

5.6 WiFi
--------

Due to the LICENSE issue, we can't provide the firmware files in wrlinux,
You can get these firmware files from imx7d SDK v5.15.32 rootfs: /lib/firmware/brcm/
brcmfmac4339-sdio.bin & brcmfmac4339-sdio.txt
or you can contact with Murata in the web https://wireless.murata.com/

We validated the WiFi module by the firmware version:
	BCM4339/2 wl0: Feb  7 2018 06:16:29 version 6.37.39.92 (r683655 CY)

5.7 CAAM
--------

Running OpenSSL benchmarking tests with AF_ALG engine:

root@nxp-imx7:~# modprobe algif_hash
root@nxp-imx7:~# modprobe algif_skcipher
root@nxp-imx7:~# modprobe algif_rng
root@nxp-imx7:~# modprobe algif_aead
root@nxp-imx7:~# openssl speed -engine afalg -multi 8 -elapsed -evp aes-128-cbc


6. kexec/kdump
==============

For discussion purposes, some useful terminology will be described here.

boot kernel - the first one that you start and supports kexec, from u-boot
	      for instance
capture kernel - the kernel that you reboot into after a boot kernel crash

To build the boot kernel, use the following configure option to configure
the project:

     --templates feature/kdump feature/kexec

To reserve a memory region for capture kernel, you need to pass the bootargs argument "crashkernel"
as follow:

    crashkernel=256M@2256M

For dump-capture kernel:
Before boot dump-capture kernel, please add "maxcpus=1" to the boot parameter.
Note: please use zImage as a secondary kernel. It can be found in the
  tmp-glibc/deploy/images/nxp-imx7/
directory.

For more detailed info about kdump, please refer to Documentation/kdump/kdump.txt
in the kernel source tree.

7.1 Burn images to SD card
--------------------------

To burn uboot and WIC images to SD card, user need to execute command:
# dd if=wrlinux-image-std-nxp-imx7.wic of=/dev/your_sd_dev

7.2 Set uboot env
-----------------

Board can boot automatically by set the below uboot environment variables:

For i.mx7d
=> setenv bootfile zImage; setenv fdtfile imx7d-sdb.dtb;  setenv loadaddr 0x80800000; setenv fdtaddr 0x87000000;
=> setenv bootargs 'root=/dev/mmcblk1p2 rw rootdelay=5 console=ttymxc0,115200n8'
=> setenv bootcmd 'fatload mmc 0:1 $loadaddr $bootfile; fatload mmc 0:1 $fdtaddr $fdtfile; bootz $loadaddr - $fdtaddr';
=> saveenv; run bootcmd;