MCIMX8M-EVK 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 <[email protected]> or your support representative for more
information on submitting changes.

Building the nxp-imx8 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.

The right to copy, distribute or otherwise make use of this software may
be licensed only pursuant to the terms of an applicable Wind River license
agreement. No license to Wind River intellectual properly rights is granted
herein. All rights not licensed by Wind River are reserved by Wind River.

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

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-imx8/kernel-source
	# git whatchanged standard/base..


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

4.1 NFS Root File System
------------------------

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

4.1.2 Download kernel
---------------------

	# tftp 0x40480000 Image

4.1.3 Download DTB
------------------

	If you want to use HDMI connector (J1001) as output:
	# tftp 0x43000000 fsl-imx8mq-evk-b3.dtb

	If you want to use IMX-MIPI-HDMI on J1501 as output:
	# tftp 0x43000000 fsl-imx8mq-evk-dcss-adv7535-b3.dtb

	If you want to use MX8-DSI-OLED1 on J1501 as output:
	# tftp 0x43000000 fsl-imx8mq-evk-dcss-rm67191-b3.dtb

4.1.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 \
		 video=HDMI-A-1:1920x1080-32@60
	# booti 0x40480000 - 0x43000000

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

5.1 HDMI
--------------

To enable HDMI as the default framebuffer device, add:

	video=HDMI-A-1:1920x1080-32@60

to the bootargs parameter of U-Boot.

5.2 USB feature
---------------

5.2.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.3 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.4 DMA
-------

In wrlinux project, the version of sdma firmware which comes from linux-firmware
is 4.2, and there is a newer version 4.4 in the NXP i.mx SDK. Because of license issue,
the new version firmware can't be integrated into wrlinux product. If customer want to
use version 4.4 firmware, execute the following commands:

1) Download the firmware from URL:
	$ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.0.bin

2) Extract the firmware from the binary file:
	$ chmod 777 firmware-imx-8.0.bin
	$ ./firmware-imx-8.0.bin

3) You need to read and accept the EULA, and press y to continue. Then copy
firmwares to your rootfs:
	$ cd firmware-imx-8.0
	$ cp firmware/sdma/sdma-imx7d.bin path_to_your_rootfs/lib/firmware/sdma/

5.5 Bluetooth
-------------

Bluetooth functionality is provided by the on-board Murata LBEE5U91CQ-TEMP module
with QCA6174A chip inside.

5.5.1 Usage and verification
----------------------------
To run Bluetooth with BlueZ stack, execute the following commands:

	# hciattach /dev/ttymxc2 qca 3000000 flow -b -t 120
	# hciconfig hci0 up
	# hciconfig hci0 noscan
	# hciconfig hci0
        Expected UP_RUNNING
	# hcitool scan --flush
		Scanning ...
		<BT_ADDR>       "Another Bluetooth device"
	# hciconfig hci0 piscan

Service discovery:

	# sdptool browse <BT_ADDR>

Establish connection with another Bluetooth device and ping it:

	# l2ping -c 5 <BT_ADDR>

NOTE: The firmware for bluetooth is not integrated into wrlinux because of
the license issue. Please execute the following commands to copy firmware to
rootfs by manual:

1) Download the firmware from URL:
	$ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-qca-2.0.3.bin

2) Extract the firmware from the binary file:
	$ chmod 777 firmware-qca-2.0.3.bin
	$ ./firmware-qca-2.0.3.bin

3) You need to read and accept the EULA, and press y to continue. Then copy
firmwares to your rootfs:
	$ cd firmware-qca-2.0.3
	$ cp 1CQ_QCA6174A_LEA_2.0/* path_to_your_rootfs/ -rf

4) Please check if the file "rampatch_tlv_3.2.tlv" is in path_to_your_rootfs/lib/firmware.

5.6 Graphics
------------

5.6.1 Xwayland
--------------
If you want to build a xwayland image, please follow the steps as below:

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

	--machines nxp-imx8 --distros wrlinux --dl-layers

<2> Setup environment and create a build directory:

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

<3> Add the following to your local.conf file to configure the project:

	DISTRO ?= "wrlinux-std-sato"
	WRTEMPLATE ?= "feature/weston-demo"

<4> Use the command as below to build a xwayland image:

	bitbake wrlinux-image-glibc-std

5.6.2 GPU
---------
Because of the licesen issue, nxp-imx8 layer doesn't integrate imx8's GPU(GC7000Lite) 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) 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:
	# ./scripts/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

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

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

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

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

<4> Following the instruction in Section 5.5.1 to build a xwayland image.

NOTE:

1) Now the GPU features are only for xwayland image, if building a sato image with
imx8-graphic layer, it will fail.

2) 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.

3) Since some packages which are used to support the graphic feature in
nxp-imx8 is provided via binaries, when you build a nxp-imx8 project with
graphic support, there will be error info as below:
-----------ERROR--------------
ERROR: imx-gpu-viv-1_6.2.2.p0-aarch64-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.7 thermal
-----------

	To check current CPU temperature
	# cd /sys/class/thermal/thermal_zone0
	# cat temp
	51000
	# cat trip_point_0_type
	passive
	# cat trip_point_0_temp
	85000
	# cat trip_point_1_type
	critical
	# cat trip_point_1_temp
	95000

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:

	crashkernel=512M@3000M

For the dump-capture kernel:
Before booting the dump-capture kernel, add "maxcpus=1 cma=128M" to the boot parameter.

NOTE: Use Image as a secondary kernel. It can be found in the
tmp-glibc/deploy/images/nxp-imx8/ 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:

http://www.yoctoproject.org/docs/2.2/mega-manual/mega-manual.html#creating-partitioned-images

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

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

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

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

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

1) Burn WIC image

# dd if=wrlinux-image-glibc-std-sato-nxp-imx8.wic of=/dev/your_sd_dev

2) Prepare the bootloader image imx-boot-imx8mqevk-sd.bin. User can build
   a SDK for imx8mq by executing the commands as below:

$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
$DISTRO=fsl-imx-wayland MACHINE=imx8mqevk source fsl-setup-release.sh -b build-wayland
$bitbake fsl-image-qt5-validation-imx

3) The imx-boot-imx8mqevk-sd.bin in SDK can be found in build-wayland/tmp/deploy/images/imx8mqevk/,
   and then use the command as below to burn it to SD card:

# dd if=imx-boot-imx8mqevk-sd.bin of=/dev/your_sd_dev bs=1k seek=33 conv=fsync