NXP LS1046 Boards


1. About this document
======================
This document describes the 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-ls1046 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 tree for individual recipes is under the LICENSE
stated in each recipe (.bb file) unless other 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      |      Y      |      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="'.

3. Board Specific Patches
=========================

To get a list of patches applied to the kernel specific to this BSP
along with patch descriptions use git whatchanged on the default
kernel (git whatchanged <kernel_type>..<bsp_name>). For example:

	# cd tmp-glibc/work-shared/<bsp_name>/kernel-source
	# git whatchanged standard/base..HEAD

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

The typical u-boot settings apply to these boards. You will need to use
setenv, printenv and saveenv, to configure, display and store respectively
your network configuration details and kernel command line. In order to
TFTP a kernel, you need at a minimum to set the following:

	- ipaddr
	- gatewayip
	- netmask
	- serverip
	- loadaddr
	- dtbfile
	- dtbaddr
	- ethaddr
	- eth1addr

Target specifics are usually set in the "bootargs" variable, and the
kernel image is set in the "kernelfile" variable. Don't forget that if you
want these values to be available after a power cycle you will need to run
the saveenv command.

Typically convenience macros exist that will create a complete bootargs
command line for the kernel based on variables that contain individual
settings.  Since these macros exist as env variables themselves, they
may or may not be present depending on who installed and configured
u-boot for the board.

The console device for the board is ttyS0 at 115200 baud. For the DTB
address, 0x90000000 was used with success by Wind River. The load address
must be high enough to not interfere with kernel decompression. A value
of 0x81000000 was used with success for all kernels tested by Wind River.

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

Example settings for the monitor (u-boot) are shown below:

nfsboot=setenv bootargs root=/dev/nfs rw nfsroot=$serverip:$rootpath \
ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname:$netdev:off \
console=$consoledev,$baudrate $othbootargs;tftp $kernel_addr_r $kernelfile; \
tftp $fdt_addr_r $fdtfile;booti $kernel_addr_r - $fdt_addr_r
ethaddr=00:04:9F:02:00:FD
eth1addr=00:04:9F:02:01:FD
eth2addr=00:04:9F:02:02:FD
kernel_addr_r=0x81000000
fdt_addr_r=0x90000000
gatewayip=192.168.1.1
netmask=255.255.255.0
ipaddr=192.168.1.100
serverip=192.168.1.2
netdev=eth0
kernelfile=Image
fdtfile=fsl-ls1046-rdb-sdk.dtb
rootpath=/tftpboot/rootfs
consoledev=ttyS0
baudrate=115200
othbootargs=earlycon=uart8250,mmio,0x21c0500

4.2 Booting from SPI flash
--------------------------
4.2.1 On-Board SPI Flash vbank Configuration
------------------------------------------
The LS1046ARDB provides two QSPI flash memories (part number: S25FS512SDSMFI011) 
for storing images (RCW/UBoot/kernel/PPA/FMan microcode):
 - Flash memory connected to chip select 0 (CS0): Represents the default virtual bank (bank 0)
 - Flash memory connected to chip select 1 (CS1): Represents the alternative virtual bank (bank 4)
Below description shows the memory addresses (memory map) for storing board configuration data on 
virtual bank 0 and virtual bank 4.

Virtual bank 0:
Start address 	End address 	Image 						Maximum size
0x0_4000_0000 	0x0_400F_FFFF 	RCW + PBI 					1 MB
0x0_4010_0000 	0x0_401F_FFFF 	U-Boot image 					1 MB
0x0_4020_0000 	0x0_402F_FFFF 	U-Boot environment 				1 MB
0x0_4030_0000 	0x0_403F_FFFF 	Reserved 					1 MB
0x0_4040_0000 	0x0_404F_FFFF 	Primary Protected Application (PPA) 		1 MB
0x0_4050_0000 	0x0_406F_FFFF 	Unified extensible firmware interface (UEFI) 	2 MB
0x0_4070_0000 	0x0_408F_FFFF 	Secure boot header + bootscript 		2 MB
0x0_4090_0000 	0x0_40FF_FFFF 	Fman microcode 					7 MB
0x0_4100_0000 	0x0_43FF_FFFF 	FIT image 					48 MB

Virtual bank 4:
Start address 	End address 	Image 						Maximum size
0x0_4400_0000 	0x0_440F_FFFF 	RCW + PBI 					1 MB
0x0_4410_0000 	0x0_441F_FFFF 	U-Boot image 					1 MB
0x0_4420_0000 	0x0_442F_FFFF 	U-Boot environment 				1 MB
0x0_4430_0000 	0x0_443F_FFFF 	Reserved 					1 MB
0x0_4440_0000 	0x0_444F_FFFF 	Primary Protected Application (PPA)		1 MB
0x0_4450_0000 	0x0_446F_FFFF 	Unified extensible firmware interface (UEFI)	2 MB
0x0_4470_0000 	0x0_448F_FFFF 	Secure boot header + bootscript 		2 MB
0x0_4490_0000 	0x0_44FF_FFFF 	Fman microcode					7 MB
0x0_4500_0000 	0x0_47FF_FFFF 	FIT image 					48 MB

4.2.2 Programming a new bootloader
----------------------------------

By default, an existing U-Boot is run in bank 0 after the system is powered on or
after a hard reset is performed. To flash U-Boot to the alternate bank, first
switch to bank 0 by performing a hard reset or by typing reset. Then use the
following commands to flash a new U-Boot into the alternate bank and then switch
to that alternate bank where the new U-Boot is flashed:

=>tftp 82000000 u-boot.bin-qspi
=>sf probe 0:1
=>sf erase 100000 +$filesize
=>sf write 82000000 100000 $filesize
=>cpld reset altbank

In the LS1046ARDB, you can program a new RCW to the QSPI flash memory.
To program a new RCW, first switch to QSPI bank 0 by either performing
a hard reset or typing reset. Next, load the new RCW to RAM by downloading
it via TFTP and then copying it to flash offset 0x0, which is the offset
address of RCW in the QSPI flash memory. Then, run the following commands
at the U-Boot prompt to program the RCW to the QSPI flash memory and reset
to the alternate bank:

=>tftp 82000000 <rcw_file_name>.bin
=>sf probe 0:1
=>sf erase 0 +$filesize
=>sf write 82000000 0 $filesize
=>cpld reset altbank

To program a new microcode, first switch to QSPI bank 0 by either performing
a hard reset or typing cpld reset. Next, load the new microcode to RAM by
downloading it via TFTP and then writing it to flash offset 0x300000, which
is the offset of microcode in the QSPI flash memory. Then, run the following
commands at the U-Boot prompt to program the microcode to the boot device:
=>tftp 83000000 <ucode_file_name>.bin
=>sf probe 0:1
=>sf erase 900000 +$filesize
=>sf write 83000000 900000 $filesize
=>cpld reset altbank

To program a PPA firmware, first switch to QSPI bank 0 by either performing
a hard reset or typing cpld reset. Next, load the new microcode to RAM by
downloading it via TFTP and then writing it to flash offset 0x300000, which
is the offset of firmware in the QSPI flash memory. Then, run the following
commands at the U-Boot prompt to program the microcode to the boot device:
=>tftp 83000000 ppa.itb
=>sf probe 0:1
=>sf erase 400000 +$filesize
=>sf write 83000000 400000 $filesize
=>cpld reset altbank

NOTE:
1. You can use the sf probe 0:0 to program the microcode to the current bank.
2. uboot can be build with:
$ bitbake u-boot-qoriq
After build, the binary can be found at:
tmp-glibc/deploy/images/nxp-ls1046/u-boot.bin-qspi
3. rcw can be build with:
$ bitbake rcw
After build, the binary can be found at:
tmp-glibc/deploy/images/nxp-ls1046/rcw/ls1046ardb
4. ppa firmware can be build with:
$ bitbake ppa
After build, the binary can be found at:
tmp-glibc/deploy/images/nxp-ls1046/ppa.itb
5.fman ucode can be download from:
from git://github.com/qoriq-open-source/fm-ucode.git

4.2.3 Set board switch
----------------------

Board can boot from SPI flash by setting sw5[1:8] as '00100010'.


4.3 NAND Flash Root File System
-------------------------------
4.3.1 Generate the boot image:
------------------------------
Configure your project with the following options to enable necessary kernel
options:
        --templates feature/yaffs2-utils

After build, program the image into flash with following command:
For ubifs filesystems:
	# flash_erase /dev/mtd0 0 0
	# ubiattach /dev/ubi_ctrl -m 0
	# ubimkvol /dev/ubi0 -N root -s 480MiB
	# mkdir /mnt/ubifs
	# mount -t ubifs ubi0:root /mnt/ubifs
	# tar xfj wrlinux-image-glibc-std-nxp-ls1046.tar.bz2 --numeric-owner -C /mnt/ubifs/
	# umount /mnt/ubifs/

The followings are for YAFFS2 filesystem:

	# flash_erase /dev/mtd0 0 0
	# mkdir /mnt/yaffs2
	# mount -t yaffs /dev/mtdblock0 /mnt/yaffs2
	# tar xfj wrlinux-image-glibc-std-nxp-ls1046.tar.bz2 --numeric-owner -C /mnt/yaffs2/
	# umount /mnt/yaffs2/

NOTE: Before writing to the flash memory you need to know its layout, you can
get this kind information by running 'cat /proc/mtd' on your target. please
ensure that an appropriate file system is created to fit the available space.

4.3.2 Deployment
----------------

After loading the kernel, pass kernel arguments as shown:

	ubi.mtd=0 root=ubi0:root rw rootfstype=ubifs console=ttyS0,115200

	or: root=/dev/mtdblock0 rw rootfstype=yaffs console=ttyS0,115200

4.4 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:

WIC image for SD card:
tmp-glibc/deploy/images/nxp-ls1046/wrlinux-image-glibc-std-nxp-ls1046.wic
WIC image for eMMC:
tmp-glibc/deploy/images/nxp-ls1046/wrlinux-image-glibc-std-nxp-ls1046-emmc.wic

Then user can write the output image to a SD card. WIC image contains kernel,
dtb, rootfs and u-boot. User still need to write fman microcode image to SD card
or eMMC by "dd" command.

To change default booting configuration in uboot, user can overwrite following
variable in uboot and save to SD or eMMC by saveenv command:

- kernelfile, define kernel image file name.
- fdtfile, define device-tree image file name.
- othbootargs, define additional booting parameters pass to kernel.

4.4.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-nxp-ls1046.wic of=/dev/your_sd_dev

2) User can find fsl_fman_ucode_ls1046_r1.0_106_4_18.bin
from git://github.com/qoriq-open-source/fm-ucode.git, then burn it with:

# dd if=fsl_fman_ucode_ls1046_r1.0_106_4_18.bin of=/dev/your_sd_dev bs=512 seek=18432 conv=fsync

4.4.2 Burn image to eMMC
------------------------

eMMC is multiplexed with SDHC interface. To access eMMC, user need boot from eMMC
or SPI flash with emmc enabled rcw. The rcw can be build with:
$ bitbake rcw

Then emmc enabled rcw can be found at:
tmp-glibc/deploy/images/nxp-ls1046/rcw/ls1046ardb/RR_FFSSPPPH_1133_5559/rcw_1600_qspiboot_emmc.bin

User can update the rcw into SPI flash and boot from SPI flah. Then transfer the
WIC image for eMMC and fman ucode binary into board, then burn image with:

# dd if=wrlinux-image-glibc-std-nxp-ls1046-emmc.wic of=/dev/mmcblk0
# dd if=fsl_fman_ucode_ls1046_r1.0_106_4_18.bin of=/dev/mmcblk0 bs=512 seek=18432 conv=fsync

4.4.3 Set board switch
----------------------

Board can boot from SD card or eMMC by setting sw5[1:8] as '00100000'.
After power up, if a bootable SD card inserted, then system will boot from SD
card. Otherwise, system will lookup bootloader from eMMC.

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

5.1 IEEE 1588 PTP testing
-------------------------

5.1.1 Introduction
------------------

This testing method is based on PTPd project, only some basic testing commands
have been tested on this BSP because the accurate PTP testing scenario is a bit
complicated according to IEEE PTPv2.

5.1.2 Usage and verification
----------------------------

Two boards are necessary for this case, one for master, another is slave,
the following commands show to use PTP time as stamping mode based on the
peer delay (P2P) mechanism:

     master :
     root@nxp-ls1046:~# ptpd2 -i eth2 -MV
     02:36:18.339405 ptpd2[634].startup (info)      (___) Configuration OK
     02:36:18.340935 ptpd2[634].startup (info)      (___) Successfully acquired lock on /var/run/ptpd2.lock
     02:36:18.341410 ptpd2[634].startup (notice)    (___) PTPDv2 started successfully on eth2 using "masteronly" preset (PID 634)
     02:36:18.341506 ptpd2[634].startup (info)      (___) TimingService.PTP0: PTP service init
     02:36:18.343434, init,
     02:36:18.448931 ptpd2[634].eth2 (notice)    (lstn_init) Now in state: PTP_LISTENING
     02:36:18.449046, lstn_init,  1
     02:36:28.341629 ptpd2[634].eth2 (notice)    (lstn_init) TimingService.PTP0: elected best TimingService
     02:36:28.341749 ptpd2[634].eth2 (info)      (lstn_init) TimingService.PTP0: acquired clock control
     02:36:30.452226 ptpd2[634].eth2 (notice)    (mst) Now in state: PTP_MASTER, Best master: 00049ffffe03cbc9(unknown)/1 (self)
     #Timestamp, State, Clock ID, One Way Delay, Offset From Master, Slave to Master, Master to Slave, Observed Drift, Last packet Received, One Way Delay Mean, One Way Delay Std Dev, Offset From Master Mean, Offset From Master Std Dev, Observed Drift Mean, Observed Drift Std Dev, raw delayMS, raw delaySM

     slave:
     root@nxp-ls1046:~# ptpd2 -i eth3 -sV
     02:39:54.066864 ptpd2[564].startup (info)      (___) Configuration OK
     02:39:54.067923 ptpd2[564].startup (warning)   (___) Interface eth6 seems to be down. PTPd will not operate correctly until it's up.
     02:39:54.068092 ptpd2[564].startup (info)      (___) Successfully acquired lock on /var/run/ptpd2.lock
     02:39:54.068523 ptpd2[564].startup (notice)    (___) PTPDv2 started successfully on eth6 using "slaveonly" preset (PID 564)
     02:39:54.068596 ptpd2[564].startup (info)      (___) TimingService.PTP0: PTP service init
     02:39:54.068711, init,
     02:39:54.069636 ptpd2[564].eth6 (warning)   (init) Interface eth6 seems to be down. PTPd will not operate correctly until it's up.
     02:39:54.070643 ptpd2[564].eth6 (info)      (init) Observed_drift loaded from kernel: 0 ppb
     02:39:54.170948 ptpd2[564].eth6 (notice)    (lstn_init) Now in state: PTP_LISTENING
     02:39:54.171025, lstn_init,  1
     02:40:04.068702 ptpd2[564].eth6 (notice)    (lstn_init) TimingService.PTP0: elected best TimingService
     02:40:04.068818 ptpd2[564].eth6 (info)      (lstn_init) TimingService.PTP0: acquired clock control

5.2. Multilib
-------------

By default, this BSP is configured as a 64-bit kernel and 64-bit userspace
with 32-bit userspace multilib support.

Multilib is also supported by this BSP.

1. To add 32-bit multilib support for an existing project, use:

    bitbake lib32-wrlinux-image-glibc-std

2. To add 32-bit mulilib support for a specific package, use:

    bitbake lib32-<pkg-name>

5.3 kexec/kdump
---------------

To build the boot or capture kernel, use the following option with the configure
command for your project:

     --templates feature/kexec feature/kdump

To reserve a memory region for the capture kernel, pass "crashkernel=512M"
via the U-Boot command line.

NOTES:
1. Use vmlinux as a secondary kernel. It can be found in the directory
   tmp-glibc/work/<bsp name>-wrs-linux/linux-yocto/<kernel version>/linux-<bsp name>-<kernel type>-build/vmlinux

2. 512 MB (the size of the memory reserved for crash kernel) is the
   recommended amount of memory. If you add more features to the kernel, you
   can increase this value to accommodate the capture kernel.

3. Kdump: PCI-MSI and SMP is unsupported in 2nd kernel.
   User needs to append two arguments "pci=nomsi maxcpus=1".
   Since this 2nd kernel operates under significantly constrained
   initialization conditions and is not meant to be a "replacement" kernel.
   Rather it has a single goal -- to enable data collection with respect to
   the issue that impacted the initial kernel, and nothing else.

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

5.4 DPDK
--------
5.4.1 Boot Arguments
--------------------
The following boot arguments can be used in order to obtain the best performance
for DPDK applications:
 default_hugepagesz=2MB hugepagesz=2MB hugepages=448 isolcpus=1-3 bportals=s0 qportals=s0

To use DPDK applications, user need load specific DTB, fsl-ls1046a-rdb-usdpaa.dtb.
The DTB can be found in tmp-glibc/deploy/images/nxp-ls1046/, and it alread
installed into WIC image.

5.4.2 Sample Applications
-----------------------
In order to get the sample applications provided by the DPDK, you need to enable
bsp-extras template. You can use the steps like the following to run the sample
applications. Take the l2fwd as example:
  1. Configure the DPAA platform:
	export DPAA_NUM_RX_QUEUES=1
	export DPAA_FMC_MODE=1
	fmc -c /usr/bin/dpdk-example/extras/dpaa/usdpaa_config_ls1046.xml \
		 -p /usr/bin/dpdk-example/extras/dpaa/usdpaa_policy_hash_ipv4_1queue.xml -a
	mkdir /mnt/hugepages
	mount -t hugetlbfs none /mnt/hugepages

  2. Run the layer 2 forwarding application:
       /usr/bin/dpdk-example/l2fwd -c 0x2 -n 1 -- -p 0x1 -q 1

5.5 LS1026A
-----------

Setting sw3[2] to '0' can disable core 3 and 4 on SOC to make it act as dual
core processor LS1026A.