MCIMX8QM-MEK 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 following layers supplied with Wind River Linux:
  oe-core
  meta-imx
  meta-freescale

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-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) 2024 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 can be used for this BSP/Machine.


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 $kernel_addr Image

4.1.3 Download DTB
------------------
For MCIMX8QM-MEK board:
	If you want to connect HDMI monitor to MIPI DSI1(J4) or DSI0(J9):
	# tftp $fdt_addr imx8qm-mek.dtb

	If you want to connect HDMI monitor to HDMI TX (J6):
	# tftp $fdt_addr imx8qm-mek-hdmi.dtb

	If you want to connect 2 HDMI monitors to HDMI TX (J6) and HDMI RX (J1):
	# tftp $fdt_addr imx8qm-mek-hdmi-in.dtb

	If you want to connect OLED screen to MIPI DSI1(J4) or DSI0(J9):
	# tftp $fdt_addr imx8qm-mek-dsi-rm67191.dtb

	If you want to connect OV5640 MIPI camera to MIPI CSI1(J5) or CSI0(J10):
	# tftp $fdt_addr imx8qm-mek-ov5640.dtb

4.1.4 Download and load firmware
--------------------------------
For MCIMX8QM-MEK board:
	If you want to connect HDMI monitor to HDMI TX (J6):
	# tftp ${hdp_addr} hdmitxfw.bin
	# hdp load ${hdp_addr}

	If you want to connect 2 HDMI monitors to HDMI TX (J6) and HDMI RX (J1):
	# tftp ${hdp_addr} hdmitxfw.bin
	# hdp load ${hdp_addr}
	# tftp ${hdprx_addr} hdmirxfw.bin
	# hdprx load ${hdprx_addr}

4.1.5 Set bootargs and boot the system
--------------------------------------

	# setenv bootargs console=<$console_port> root=/dev/nfs rw \
		 nfsroot=<nfs server>:<nfs root> \
		 ip=<target IP>::<gateway>:<netmask>::eth0:off \
		 video=HDMI-A-1:1920x1080-32@60
	# booti $kernel_addr - $fdt_addr

Note: for MCIMX8QM-MEK board, $kernel_addr="0x8a0000000", $fdt_addr="0x8d0000000"
	$console_port = "ttyLP0,115200"
      The kernel image will become larger if more kernel code is compiled into kernel image.
      So, please increase "fdt_addr" value by putting dtb file at higher address if you encounter with kernel booting failed.


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:

For MCIMX8QM-MEK board:
	# echo enabled > /sys/class/tty/ttyLP0/power/wakeup
	# echo mem > /sys/power/state

5.4 Graphics
------------

5.5 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-graphics --dl-layers

<2> Setup environment and create a build directory:

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

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

	bitbake wrlinux-image-std-sato

Note: For GPU support please refer to the instructions in README.proprietary

5.6 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

5.7 PCIe
--------

All the imx8 platforms support PCIe feature.
The PCIe bus is provided through the M.2 connector.

Can choose the below PCIe peripheral to validate:

	Intel Corporation Wireless 7265

Can validate using the following steps:

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

	KERNEL_FEATURES:append = " features/iwlwifi/iwlwifi.scc"

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

Built and install them:

	# bitbake wrlinux-image-glibc-xxx

Copy relevant WiFi card firmware (Intel 7265 WiFi firmware: iwlwifi-7265D-10.ucode)
of to /lib/firmware of the target image.

Execute the following commands to validate the WiFi cards:

	# ifconfig wlan<idx> up
	# iw wlan<idx> scan
	# iw dev wlan<idx> connect <AP essid>
	# dhclient wlan<idx>
	# ping <AP address> -i wlan<idx> -c 5

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

5.8 FLEXCAN (MCIMX8QXP-MEK & MCIMX8QM-MEK)
------------------------------------------

Detail verification commands as below:

        # ip link set can0 up type can bitrate 500000 dbitrate 8000000 fd on
        # ip link set can1 up type can bitrate 500000 dbitrate 8000000 fd on
        # candump can0 &
        # cansend can1 5A1#11.22.33.44.55.66.77.88
        # ip -d -s link show can0
        # ip -d -s link show can1

If can0 dumps data from can1, FLEXCAN feature works fine.

5.9 CAAM
--------

Running OpenSSL benchmarking tests with AF_ALG engine:

root@nxp-imx8:~# modprobe algif_hash
root@nxp-imx8:~# modprobe algif_skcipher
root@nxp-imx8:~# modprobe algif_rng
root@nxp-imx8:~# modprobe algif_aead
root@nxp-imx8:~# 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 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

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)
===================================

Note: The wic image generated by default is not bootable. You need to refer to
README.proprietary for instructions on how to create a bootable wic image.

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/singleindex.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/deploy/images/<bsp name>/ ,such as:

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

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

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

1) Burn WIC image

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

2) Set environment variable for booting system

FOR MCIMX8QM-MEK board:

u-boot=>setenv fdt_file imx8qm-mek.dtb
u-boot=>setenv bootfile Image
u-boot=>setenv bootargs "root=/dev/mmcblk1p2 rootwait rw rootdelay=5 console=${console},${baudrate} earlycon ip=dhcp"
u-boot=>setenv bootcmd "fatload mmc 1:1 $loadaddr $bootfile; fatload mmc 1:1 $fdt_addr $fdt_file; booti $loadaddr - $fdt_addr";
u-boot=>run bootcmd

8. USB OTG
==========

This section only describs how to verify usb otg feature on MCIMX8QM-MEK board.

8.1 Host Mode
-------------

Connect usb disk with usb typec port(J17) on MCIMX8QM-MEK board.
Usb disk is detected, and then confirm the speed with command as below:

	# lsusb -t
	/:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=/1p, 5000M
	    |__ Port 1: Dev 2, If 0, Class=Mass Storage, Driver=usb-storage, 5000M
	/:  Bus 01.Port 1: Dev 1, Class=root_hub, Driver=/1p, 480M

8.2 Device Mode
---------------

Connect the usb typec port(J17) to PC host, and then run below commands:

	# modprobe libcomposite

	# mkdir /sys/kernel/config/usb_gadget/g1
	# cd /sys/kernel/config/usb_gadget/g1

	# echo 0x1fc9 > idVendor
	# echo 0x12cf > idProduct

	# mkdir strings/0x409
	# echo 123456ABCDEF > strings/0x409/serialnumber
	# echo NXP > strings/0x409/manufacturer
	# echo "NXP iMX USB Composite Gadget" > strings/0x409/product

	# mkdir configs/c.1
	# mkdir configs/c.1/strings/0x409

	# echo 5 > configs/c.1/MaxPower
	# echo 0xc0 > configs/c.1/bmAttributes

	# mkdir functions/mass_storage.1
	# dd if=/dev/zero of=/root/g_mass_file bs=512K count=1000
	# echo /root/g_mass_file > functions/mass_storage.1/lun.0/file
	# ln -s functions/mass_storage.1 configs/c.1/

	# mkdir functions/acm.1
	# ln -s functions/acm.1 configs/c.1

	# mkdir functions/ncm.1
	# echo 20 > functions/ncm.1/qmult
	# ln -s functions/ncm.1 configs/c.1

	# echo 5b120000.usb > UDC

After running above commands, MCIMX8QM-MEK board works as a usb mass storage device.

9 Optee-test
------------

Because optee os is integrated into the bootloader image, and due to license reasons,
we don't support building the bootloader by default. Therefore, before using optee
features, you need to refer to section 8 ("Build Bootloader") to compile an WIC image
with the bootloader.

1) Burn WIC image
# bitbake wrlinux-image-std
# dd if=wrlinux-image-<std-sato/std>-nxp-imx8.wic of=/dev/your_sd_dev

2) run optee testing sample 
# xtest