i.MX6Q Sabre-SD/i.MX6SX Sabre-SDB 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-imx6 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) 2019 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-cgl | wrlinux-ovp |
  +--------------+-------------+-------------+-------------+
  |    valid     |      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 not 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-imx6/kernel-source
	# git whatchanged standard/base..


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

4.1 MMC/SD Boot
---------------
Please refer to section 7 "Creating Partitioned Images(WIC)" in this document to
make a bootable MMC/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-imx6
and are copied to the export directory of the TFTP server.

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

	# tftp 0x12000000 zImage

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

	# tftp 0x18000000 zImage-imx6q-sabresd.dtb

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

	For i.MX6Q/S:
	# setenv bootargs console=ttymxc0,115200 root=/dev/nfs rw \
		 nfsroot=<nfs server>:<nfs root>,v3,tcp \
		 ip=<target IP>::<gateway>:<netmask>::eth0:off \
		 video=mxcfb0:dev=ldb,LDB-XGA,if=RGB666
	# bootz 0x12000000 - 0x18000000

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

Some peripherals and drivers have been tested using the libraries and testcases
in the imx-lib and imx-test packages. These two packages are included in the 
Freescale SDK.  You can build them under the Freescale openembedded-core layer of the
meta-fsl-arm environment. Please reference https://github.com/Freescale/meta-fsl-arm
for build details.  

After the build completes: 

* all testcases are installed to ${fsl_target_rootfs}/unit_tests, 
* all needed libs are installed to ${fsl_target_rootfs}/usr/lib, 
* all needed firmware is installed to ${fsl_target_rootfs}/lib/firmware/vpu, 
  where fsl_target_rootfs parameter points to the path of the root filesystem after 
  building the freescale SDK.

Copy the testcases to the image of the i.MX6Q Board: (assuming the target
image has been properly deployed to an MMC/SD card as in described in section 3.2):

	# cp ${fsl_target_rootfs}/unit_tests /mnt/sd -rf
	# cp ${fsl_target_rootfs}/usr/lib/libvpu.* /mnt/sd/usr/lib/ -rf
	# cp ${fsl_target_rootfs}/usr/lib/libipu.* /mnt/sd/usr/lib/ -rf
	# cp ${fsl_target_rootfs}/lib/firmware/vpu /mnt/sd/lib/firmware/ -rf
	# umount /mnt/sd


5.1 fbdev HDMI
--------------

To enable HDMI as the default framebuffer device, add:

	video=mxcfb0:dev=hdmi,1920x1080M@60,if=RGB24

to the bootargs parameter of U-Boot.

5.2 VPU
-------

To test VPU support, ensure that the HDMI is the default fbdev. Please refer to 
section 5.1, above, to set the bootargs of U-Boot, then execute the following 
commands:

	# cd /unit_tests/VPU
	# ./mxc_vpu_test.out -D "-i ./akiyo.mp4 -f 0 -t 1"

5.3 V4L2 output/capture and camera
----------------------------------

Enable HDMI as the default fbdev as stated in section 5.1, above, then execute
the following commands:

	# cd /unit_tests/V4L2
	# ./mxc_v4l2_overlay.out -iw 640 -ih 480 -ow 640 -oh 480 -m 0 -di /dev/video1 -fg

5.4 USB feature
---------------

5.4.1 USB OTG Usage and verification
------------------------------------

1. Verify the OTG device mode

Plug in cable B and connect to the host machine.

Board configuration:

	# ifconfig usb0 192.168.1.10

Host machine configuration:

	# sudo ifconfig usb0 192.168.1.100
	# ping 192.168.1.10 -c 2
	PING 192.168.1.10 (192.168.1.10) 56(84) bytes of data.
	64 bytes from 192.168.1.10: icmp_req=1 ttl=64 time=2.06 ms
	64 bytes from 192.168.1.10: icmp_req=2 ttl=64 time=0.286 ms
	...

2. Switch to OTG host mode

Replace cable B with cable A.


5.5 Audio
---------

5.5.1 Audio capture and playback(WM8962)
----------------------------------------

1. Capture

Set the parameters to assign the codec and then record an audio message:

	For i.MX6Q/S:
	# amixer set 'MIXINR IN3R' on
	# amixer set 'INPGAR IN3R' on

2. Playback

	For i.MX6Q/S:
	# amixer cset name='Headphone Volume' 127

5.5.2 Audio HDMI playback
-------------------------

Connect the board to an HDMI display with an HDMI cable,
then enable fbdev HDMI as in section 5.1, above.

Play the recorded audio messages:

	# aplay -Dhw:1,0 record.wav

Note:
On imx6sx platform, it is need to used version 3.4 sdma firmware for supporting
audio feature. In wrlinux project, the sdma firmware version is 3.3, so
it is need to copy version 3.4 sdma firmware from SDK rootfs.
On imx6q platform, audio feature works fine based on version 3.3 sdma firmware.
But it is recommend customer to use version 3.4 sdma firmware.

5.6 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.7 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.8 Backlight
--------------

	# echo 0 > /sys/class/backlight/backlight/brightness

5.9 ANATOP thermal
-------------------

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

5.10 Touch Screen
-----------------

	# mtdev-test /dev/input/event0

5.11 PCIe
--------

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

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

can be validated using the following steps:

Simply add line as follows to ${buildprj}/build/conf/local.conf:

	KERNEL_FEATURES_append = " features/iwlwifi/iwlwifi.scc"

Include the following lines in your local.conf:

	LINUX_KERNEL_TYPE = "standard"
	KERNEL_FEATURES_append = " features/iwlwifi/iwlwifi.scc"

This will include the iwlwifi and mac80211 kernel modules in
the root filesystem.

Built and install them:

	# bitbake wrlinux-image-glibc-xxx

Copy relevant WiFi card firmware (Intel 6205 WiFi firmware: iwlwifi-6000g2a-5.ucode)
of to /lib/firmware of the target image.

Execute the following commands to validate the WiFi cards:

	# ifconfig wlan0 up
	# iwconfig wlan0 essid <AP essid>
	# dhclient wlan0
	# ping <AP address> -i wlan0 -c 1

NOTE: the PCIe driver does not support hotplug and suspend/resume.

5.12 Graphics/GPU
-----------------

If you want to build a project with i.mx6 GPU graphic support, please
follow the steps as below:

Setup program and create a build directory by using the following arguments:

	--machines nxp-imx6 --distros wrlinux-std-sato --dl-layers

Setup environment and create a build directory:

	$ . ./environment-setup-<host>-wrlinuxsdk-linux
	$ . ./oe-init-build-env <build>

If you want to build an Weston image, please add the following line to your local.conf:

	WRTEMPLATE ?= "feature/weston-demo"

Generate imx6 graphic layer:
Because of the licesen issue, nxp-imx6 layer doesn't integrate imx6's GPU or VPU
hardware acceleration related packages into WRlinux product. So, if customer wants
to run hardware graphic feature, please generate graphic with script scripts/generate-graphic-layer.sh.
Detail steps as below:
<1>. Download SDK package(L4.14.78_1.0.0_MX6QDLSOLOX) with below command
	# mkdir imx-yocto-bsp
	# cd imx-yocto-bsp
	# repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-sumo -m imx-4.14.78-1.0.0_ga.xml
	# repo sync

<2>. Run script scripts/generate-graphic-layer.sh and input correct parameter
	# ./generate-graphic-layer.sh -h
	 Usage: source generate-graphic-layer.sh
	    Optional parameters: [-s source-dir] [-d destination-dir] [-h]

	    * [-s source-dir]: Source directory where the graphic layer come from
	    * [-d destination-dir]: Destination directory where the graphic will be merged into
	    * [-h]: help

	# ./generate-graphic-layer.sh -s <nxp-sdk download directory>/imx-yocto-bsp/sources -d <wrlinux project directory>/layer/nxp-imx6/

<3> Read WARNING information carefully, and then input 'y' if you want to generate imx6 graphic layer

Use the command as below to add i.mx6 GPU graphic layer:

	bitbake-layers add-layer path_to_WRLinux_product/layers/nxp-imx6/imx6-graphic

Use the command as below to build rootfs:

	bitbake wrlinux-image-glibc-std-sato

NOTE:

1. You must change the configuration to allow downloading of packages from the
internet. Change BB_NO_NETWORK ?= "1" to BB_NO_NETWORK ?= "0" in the file
${buildprj}/conf/local.conf.

2. Since some packages which are used to support the graphic feature in
nxp-imx6 is provided via binaries, when you build a nxp-imx6 project with
graphic support, there will be error info as below:
-----------ERROR--------------
ERROR: imx-gpu-viv-1_6.2.2.p0-aarch32-r0 do_unpack: To use 'imx-gpu-viv' you need to accept the Freescale EULA at 'path_to_WRLinux_product/layers/meta-freescale/EULA'. Please read it and in case you accept it, write: ACCEPT_FSL_EULA = "1" in your local.conf.
------------------------------
Please read the Freescale EULA file carefully, in case you accept it, write:
ACCEPT_FSL_EULA = "1" to your local.conf file to continue the building.

5.13 Tune
-----------------
This BSP uses "armv7athf-neon" as the default tune. It supports both
cortexa9 and cortexa7, but may not have the best optimization. If you use
this BSP for the boards "i.MX 6Quad SABRE-SD" and "i.MX 6SoloX SABRE-SD", and
want better optimization from tune, change DEFAULTTUNE from "armv7athf-neon" 
to "cortexa9thf-neon" locally in ${projectdir}/conf/local.conf.

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

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

* boot kernel - the first kernel 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, enable kexec and kdump in your local.conf file:

	WRTEMPLATE = "feature/kexec feature/kdump"	

6.1 kdump
---------

For the boot kernel:
To reserve a memory region for the capture kernel, you need to pass the bootargs 
argument "crashkernel" to the boot kernel as follow:
 - Without graphic hardware accelerator
for I.MX6Q:
    crashkernel=256M@512M
for I.MX6SX:
    crashkernel=256M@2304M

 - With graphic hardware accelerator
for I.MX6Q:
    crashkernel=512M@400M
for I.MX6SX:
    crashkernel=400M@2204M

For the dump-capture kernel:
Before booting the dump-capture kernel, add "maxcpus=1 cma=16M" to the boot parameter.
NOTE: Use zImage as a secondary kernel. It can be found in the
tmp-glibc/deploy/images/nxp-imx6/ directory.

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

7. Creating Partitioned Images(WIC)
===================================

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://www.yoctoproject.org/docs/2.6/mega-manual/mega-manual.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-imx6/wrlinux-image-glibc-std-sato-nxp-imx6-imx6q.wic
tmp-glibc/deploy/images/nxp-imx6/wrlinux-image-glibc-std-sato-nxp-imx6-imx6sx.wic

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

Since this BSP doesn't have a firmware to read the uboot from a partition table,
WIC image only contains kernel, dtb and rootfs. We still need to write U-boot
image to SD card directly by "dd" command.

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

To burn uboot and WIC images to SD card, user need to execute command:

For i.mx6q:
# dd if=wrlinux-image-glibc-std-sato-nxp-imx6-imx6q.wic of=/dev/your_sd_dev

For i.mx6sx:
# dd if=wrlinux-image-glibc-std-sato-nxp-imx6-imx6sx.wic of=/dev/your_sd_dev

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

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

For i.mx6q:

=> setenv bootfile zImage; setenv fdtfile imx6q-sabresd.dtb;  setenv loadaddr 0x12000000; setenv fdtaddr 0x18000000;

=> setenv bootargs 'root=/dev/mmcblk1p2 rw rootdelay=5 console=ttymxc0,115200n8'

=> setenv bootcmd 'fatload mmc 1:1 $loadaddr $bootfile; fatload mmc 1:1 $fdtaddr $fdtfile; bootz $loadaddr - $fdtaddr';

=> saveenv; run bootcmd;

For i.mx6sx

=> setenv bootfile zImage; setenv fdtfile imx6sx-sdb.dtb;  setenv loadaddr 0x80800000; setenv fdtaddr 0x83000000;

=> setenv bootargs 'root=/dev/mmcblk2p2 rw rootdelay=5 console=ttymxc0,115200n8'

=> setenv bootcmd 'fatload mmc 2:1 $loadaddr $bootfile; fatload mmc 2:1 $fdtaddr $fdtfile; bootz $loadaddr - $fdtaddr';

=> saveenv; run bootcmd;