2.4 Feature Support Matrix................................................................................................................................................ 8
2.5 Open, Fixed and Known Issues................................................................................................................................. 10
Chapter 3 LS1028A BSP user guide................................................................. 12
3.1.2 Host system requirements........................................................................................................................... 12
3.1.3 Download and assemble LS1028A BSP images......................................................................................... 13
3.1.4 Deploy LS1028A BSP images on board...................................................................................................... 14
3.1.4.3 Option 2 - Deploy BSP images directly to the storage device on a board.................................... 20
3.2 How to build LS1028A BSP with Flexbuild.................................................................................................................24
3.3 Procedure to run secure boot.....................................................................................................................................32
Chapter 4 Linux kernel...................................................................................... 37
4.1 Configuring and building............................................................................................................................................ 38
4.2.4 Low Power Universal Asynchronous Receiver/Transmitter (LPUART)........................................................ 51
4.2.5 Flex Serial Peripheral Interface (FlexSPI)................................................................................................... 54
4.2.6 Real Time Clock (RTC)............................................................................................................................... 56
4.2.7 Queue Direct Memory Access Controller (qDMA)...................................................................................... 58
4.2.8 Serial Advanced Technology Attachment (SATA)........................................................................................61
4.2.10 Universal Serial Bus Interfaces................................................................................................................. 76
4.2.10.1 USB 3.0 Host/Peripheral Linux Driver User Manual...................................................................76
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
3
Page 4
Introduction
Chapter 1
Introduction
About QorIQ LS1028A BSP
LS1028A BSP is a complete Linux kit for NXP LS1028A SoC and its reference and evaluation boards.
It is a hybrid form of a Linux distribution because it combines the following major components to form a complete Linux system.
• NXP boot loader: U-Boot, based on denx.de plus patches
• NXP Linux kernel, based on kernel.org upstream plus patches.
• NXP added user space components.
• Ubuntu standard user space file set (user land), including compilers and cross compiler.
The use of Ubuntu user land is what makes LS1028A BSP a hybrid. It is not entirely an Ubuntu distribution because it uses an
NXP kernel, but it still uses Ubuntu user space files. This hybrid is possible because NXP ARM SoC's are standards-based so
programs like bash and thousands of others run without being recompiled.
The benefit of using Ubuntu user land is the easy availability of thousands of standard Linux user space packages. The experience
of using the LS1028A BSP is similar to using Ubuntu, but the kernel, firmware, and some special NXP packages are managed
separately.
Accessing LS1028A BSP
LS1028A BSP is distributed via
There are two ways to use the LS1028A BSP, as an integration and as a source of individual components.
LS1028A BSP as an integration
Using the link above, notice the flexbuild component. You can clone it and run a script to create and install LS1028A BSP onto
a mass storage device as an integration, ready for use on an NXP reference or evaluation board. You can build NXP components
from source using a script called flex-builder or install from binaries of NXP components using flex-installer.
LS1028A BSP as components
The same link shows git repositories for individual components, for example the LS1028A BSP Linux kernel. If you clone and
examine this git, you will see a conventional kernel source tree. You can compile the kernel using make in the normal way, like a
kernel.org kernel. However, notice the configuration fragment in arch/arm64/configs. See Linux kernel on page 37.
Having git access to components is helpful if you assemble your own Linux distribution or wish to form a hybrid with a user land
other than Ubuntu’s.
LS1028A BSP git tags
LS1028A BSP git repositories use git tags to indicate component revisions that have been release tested together. Use the git
tag command to examine them and choose a tag to check out.
LS1028A BSP Relies on Mass Storage Devices
Ubuntu user land is very convenient for evaluation because it is possible to use the command apt-get install on the standard
Ubuntu components you need. It also provides native development tools.
nxp.com.
But this richness means that the user space file is large, too large for RAM disks.
Therefore, LS1028A BSP requires installation to and use of a mass storage device such as
• SD card
• USB flash drive
• USB hard drive
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
4
NXP Semiconductors
Page 5
Reference documentation
• SATA drive, spinning, or SSD (for boards with a SATA port)
• eMMC flash (when available on board)
LS1028A BSP provides scripts that populate a mass storage device with the needed files. These scripts can run on a Linux PC.
It is especially simple to use an SD card or USB flash drive because they are the easiest to move between a Linux PC and the
NXP board.
1.1 Reference documentation
The table below lists and explains the additional documents and resources that you can refer to for more information on the
LS1028A SoC and LS1028A board (RDB and QDS).
Some of the documents listed below may be available only under a non-disclosure agreement (NDA). To request access to these
documents, contact your local field applications engineer or sales representative.
Table 1. Reference documentation
DocumentDescriptionLink/How to access
QorIQ LS1028A Reference ManualProvides a detailed description about the
LS1028A QorIQ multicore processor and
its features, such as memory map, serial
interfaces, power supply, chip features,
and clock information.
QorIQ LS1028A Reference Design Board
Getting Started Guide
— Supports serial interfaces with frame synchronization, such as I2S
and codec interfaces
LPUART
FlextimerSupport in Linux
Performance monitorPerf events support in Linux
CANTx/Rx support in Linux
Read/write support in U-Boot
2.5 Open, Fixed and Known Issues
This section contains Fixed and Open issue tables:
• Table2: Fixed/closed issues: Contains Issues which have a software fix that has been integrated into this Release or the
issues are root cause and fix is outside the scope of this release.
• Table3: Open/known issues: Contains Issues which have do not currently have a resolution. Workaround suggestions are
provided wherever possible.
Table 3. Fixed issues
IDDescriptionStatus
QLINUX-10979LS1028ARDB - flextimer: no 'ftm_alarm' under /sys/
devices/platform/soc/2800000.ftm0/
Table continues on the next page...
Fixed
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
10
NXP Semiconductors
Page 11
Table 3. Fixed issues (continued)
Open, Fixed and Known Issues
QLINUX-10857
LS1028ARDB GPU: few demos such as OpenGLES (for
Fixed
example, tutorial4_es20) and OpenVG (for example, tiger)
hang
QLINUX-11094LS1028A: There is IOMMU call trace when running
Fixed
802.1AS with linuxptp
QUBOOT-4813LS1028AQDS - DSPI does not work under U-BootFixed
QLINUX-11091LS1028ARDB: Linux IPv4 Forward Performance with
Fixed
switch port is much lower than PRL
QLINUX-11152LS1028ARDB: Kernel does not reboot after kill watchdog
Fixed
process
QLINUX-11391LS1028ARDB: System hangs when add switch port to
Fixed
bridge when connect switch port to TFTP server
QUBOOT-4990LS1028ARDB: SATA does not workFixed
Table 4. Open/Known issues
IDDescription
QLINUX-11337LS1028A: Time gate accuracy does not reach PRL
QLINUX-11394LS1028ARDB: video playback using GStreamer hang quickly on weston
QLINUX-11423LS1028AQDS: Kernel booting failed using LPUART U-Boot
NOTE
PPA is replaced by ‘TF-A’, that is, Trusted Firmware for ARM in this release.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
11
Page 12
LS1028A BSP user guide
Chapter 3
LS1028A BSP user guide
This section provides LS1028ARDB-specific information on switch setting configurations, U-Boot environment variable settings
as well as supported binaries. It also provides a description of the virtual banks and flash and memory map layouts.
For more information on the LS1028ARDB refer to the QorIQ LS1028A Reference Design Board Reference Manual and the QorIQ
LS1028A Reference Design Board Getting Started Guide.
3.1 LS1028A BSP Quick Start
3.1.1 Introduction
The following sections describe the procedure to download and assemble BSP images and then to deploy these images on to
LS1028ARDB. For more information on the different components of the board and on how to configure and boot the board, see
QorIQ LS1028A Reference Design Board Getting Started Guide.
3.1.2
• Ubuntu 18.04 should be installed on the host machine.
• If this requirement is not fulfilled, see “Emulate Ubuntu 18.04 environment using Docker container” topic below.
• For root users, there is no limitation for the build. For non-root users, obtain sudo permission by running the command
• To build the target Ubuntu userland for arm64/armhf arch, the user's network environment must have access to the remote
Emulate Ubuntu 18.04 environment using Docker container (optional)
If a Linux distribution other than Ubuntu 18.04 is installed on the host machine, perform the following steps to create an Ubuntu
18.04 Docker container to emulate the environment.
• Install Docker on the host machine. See https://docs.docker.com/engine/installation/ for information on how to install Docker
• To build the Ubuntu userland, the user must have sudo permission for Docker commands or the user must be added to a
Host system requirements
sudoedit /etc/sudoers and adding a line <user-account-name> ALL=(ALL:ALL) NOPASSWD: ALL in /etc/sudoers.
Ubuntu official server.
on the host machine.
group called “ docker” as specified below.
Change current group to “ docker”
$ sudo newgrp – docker
NOTE
User can run the command cut -d: -f1 /etc/group | sort to check if docker group is included in the list
of all the available groups.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
12
NXP Semiconductors
Page 13
LS1028A BSP Quick Start
Restart service
$ sudo service docker restart
• Logout from current terminal session, then login again to ensure user can run docker ps -a.
• The user's network environment must have access to the remote Ubuntu official server.
• Run flex-builder command for docker as given in the next section.
3.1.3 Download and assemble LS1028A BSP images
In this BSP Quick Start Guide, the build framework Flexbuild is used. Flexbuild contains three scripts: flex-builder, flex-installer,
and flex-mkdistrorfs. In this section, “Download and assemble LS1028A BSP images” flex-builder is used to generate an Ubuntu
userland.
In the next section, “Deploy LS1028A BSP images on board,” the script flex-installer is used to deploy Ubuntu userland to a storage
device (SD, USB, or SATA). In addition, flex-installer is used to deploy a boot partition and firmware images to the same storage
device.
The boot partition contains a Linux kernel image and device tree blob. Firmware images include RCW (Reset Configuration Word),
U-Boot and a FIT image. For a complete list of the boot partition components and the firmware components see LS1028A BSP
Memory Layout on page 34.
See Build tools on page 35 for more information on flexbuild.
To download and assemble LS1028A BSP images, perform the steps below:
1. Download the flexbuild source tarball and set up flexbuild environment.
• Go to www.nxp.com and click the “Download” button to download flexbuild source tarball named
“flexbuild_<version>.tgz”. It is required to login and sign a license agreement before downloading the tarball.
• Set up flexbuild environment.
$ tar xvzf flexbuild_<version>.tgz
$ cd flexbuild
$ source setup.env
Run the following two commands in addition to the above three commands only when building BSP in Docker
container.
$ flex-builder docker (This command emulates Ubuntu 18.04 environment on the host machine.)
$ source setup.env (Again, setup the flexbuild environment after entering Docker container.)
2. Download prebuilt images for boot partition and NXP-specific components tarball.
3. Generate LS1028A BSP Ubuntu userland, untar the prebuilt components tarball, and merge them into target userland.
• Generate Ubuntu arm64 userland.
$ flex-builder -i mkrfs -a arm64
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
13
Page 14
LS1028A BSP user guide
• Extract app components.
$ tar xvzf app_components_LS_arm64.tgz -C build/apps
• Extract kernel modules (e.g., cryptodev).
$ sudo tar xvzf lib_modules_LS_arm64_<kernel_version>.tgz -C build/rfs/
rootfs_ubuntu_bionic_LS_arm64/lib/modules
• Merge all components packages and kernel modules into target userland and compress ubuntu arm64 rootfs as .tgz
tarball.
$ flex-builder -i merge-component -a arm64
$ flex-builder -i compressrfs -a arm64
• Exit, if using Docker.
$ exit (optional, this command exits from docker when building in docker)
• If the Linux host machine is in a subnet that needs HTTP proxy to access external Internet, set environment
variable http_proxy and https_proxy as follows.
NOTE
Add the following proxy settings in ~/.bashrc
# No authentication:
export http_proxy=http://<domain>:<port>
export https_proxy=http://<domain>:<port>
# With authentication:
export http_proxy=http://<account>:<password>@<domain>:<port>
export https_proxy=http://<account>:<password>@<domain>:<port>
# Set no_proxy variable to bypass proxy for some local servers:
export no_proxy="localhost,<local-server1>,<local-server2>"
NOTE
Only Ubuntu userland is the default file system with full system test (various firmwares and images are verified
based on Ubuntu userland) in formal LS1028A BSP release. Although other non-official userland (Debian, CentOS,
buildroot-based tiny distro, etc) can be generated and composed with the common LS1028A BSP boot partition
(containing Linux kernel, DTBs, distro boot scripts, etc) by flexbuild, that is optional part besides the formal Ubuntu
userland and there is no guarantee for other userlands as of now.
3.1.4 Deploy LS1028A BSP images on board
This section assumes that the LS1028A BSP images have been assembled as given in “Download and assemble LS1028A BSP
images”. There are two options for deploying LS1028A BSP images on the reference board:
1. Use a removable storage device such as an SD card, connect it to a local Linux host machine and deploy LS1028A BSP
images on to the removable storage device. Then, connect this removable storage device to a reference board. This
option is typically useful when the user has local access to a reference board and has a local Linux host machine.
2. If the user does not have access to a local host machine and/or a local reference board, LS1028A BSP images can be
directly deployed to the storage device that is plugged into the board. This option is typically useful when a remote Linux
host server is used, and/or the user is accessing the reference board remotely. For this option, a network connection to
the reference board is required.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
14
NXP Semiconductors
Page 15
LS1028A BSP Quick Start
The deployment covers how to program LS1028A BSP composite firmware for "FlexSPI NOR flash boot", "SD boot", and "eMMC
boot". It also covers how to deploy boot partition images and Ubuntu userland on different storage media (SD/USB/SATA).
NOTE
SD/USB/SATA capacity must be at least 8 GB.
Table 5. LS1028A BSP storage location
Boot sourceComposite firmwareKernel image and DTBUbuntu rootfs
FlexSPI NOR flashFlexSPI NOR flashSD/USB/SATA Partition 2
SDSD "raw partition"
"Boot Partition"
SD/USB/SATA Partition 3
"Rootfs Partition"
eMMCeMMC
3.1.4.1 LS1028ARDB reference information
This section provides general information about LS1028ARDB which may come in handy as a reference while completing steps
for deploying BSP that follow.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
16
(0x0080_0000_0000
-0x00FF_FFFF_FFFF)
NXP Semiconductors
Page 17
LS1028A BSP Quick Start
Supported boot options
LS1028ARDB supports the following boot options:
• FlexSPI NOR flash (referred to as "FSPI" or "FSPI flash" in the following sections). CS refers to Chip Select.
• eMMC
• SD card (SDHC1)
On-board switch options
The RDBs have user selectable switches for evaluating different boot options for the LS1028A device as given in the table below
('0' is OFF, '1' is ON).
Boot sourceSW2[1:8]SW3[1:8]SW5[1:8]
FSPI NOR (default)1111_10001111_00000011_1001
SD Card (SDHC1)1000_10001111_00000011_1001
eMMC1001_10001111_00000011_1001
In addition to the above switch settings, make sure the following jumper settings are correct.
Table 7. LS1028ARDB jumper settings
JumperTypeName/functionDescription
J61x2-pin connectorTA_BB_EN enable
Open: TA_BB_TMP_DETECT_B pin is High
(default value)
Shorted: TA_BB_TMP_DETECT_B pin is Low
J71x2-pin connectorVBAT_EN
Open: Disable battery backup for TA_BB_VDD
(default value)
Shorted: Enable battery backup for TA_BB_VDD
J271x2-pin connectorPROG_MTR voltage control (for
NXP use only)
Open: PROG_MTR pin is powered off (default
value)
Shorted: PROG_MTR pin is powered by OVDD
(1.8 V)
J281x2-pin connectorTA_PROG_SFP voltage control
(for NXP use only)
Open: TA_PROG_SFP pin is powered off
(default value)
Shorted: TA_PROG_SFP pin is powered by
OVDD (1.8 V)
FlexSPI NOR Flash Chip-select
FlexSPI NOR flash is a simple and convenient destination for deploying images so it is frequently used.
The benefit of this feature is that it allows more than one set of images to be independently deployed to the one NOR flash. This
is very helpful during development because you can use the U-Boot image in one chip-select to program an image set into a
different chip-select. If the new images are flawed, the old images are still functional to let you deploy corrected images.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
17
Page 18
LS1028A BSP user guide
The logic on the board usually allows the NOR flash to be accessed from different CS (chip select) option. Each CS is connected
to dedicated flash devices. U-Boot prints which CS is loaded from. The output looks like following.
NOTICE: Fixed DDR on board
NOTICE: 4 GB DDR4, 32-bit, CL=11, ECC on
NOTICE: BL2: v1.5(release):LSDK-18.12-8-gaf6a777e
NOTICE: BL2: Built : 03:34:46, Feb 18 2019
NOTICE: BL31: v1.5(release):LSDK-18.12-8-gaf6a777e
NOTICE: BL31: Built : 03:35:28, Feb 18 2019
NOTICE: Welcome to LS1028 BL31 Phase
Given below are the steps to deploy LS1028A BSP images on to the reference board using a removable storage device (SD/USB/
SATA). Option 1 can be used when the user has access to a local Linux host machine and to a local reference board. For this
option, the storage device is plugged into the host machine and programmed. Once the programming is complete, the storage
device is removed from the host machine and then inserted into the reference board.
1. Connect the removable storage device to the local Linux host machine.
2. The boot partition and rootfs images that were assembled during “Download and assemble LS1028A BSP images” will
be available under “flexbuild_<version>” directory on the host machine. The images have following naming format:
• Boot partition:
—
bootpartition_LS_arm64_<version> or bootpartition_LS_arm64_<version>.tgz (64-bit)
• rootfs:
—
rootfs_ubuntu_bionic_LS_arm64 or rootfs_ubuntu_bionic_LS_arm64.tgz (64-bit)
3. Setup the environment for flex-installer to run:
$ cd flexbuild
$ source setup.env
4. Execute flex-installer with appropriate arguments to deploy LS1028A BSP images to the storage device.
• The SD/USB/SATA storage drive in the Linux PC is detected as /dev/sdX, where X is a letter such as a, b, c.
Make sure to choose the correct device name, because data on this device will be replaced.
• Use the command cat /proc/partitions to see a list of devices and their sizes to make sure that the correct
device names have been chosen.
• If the Linux host machine supports read/write SD card directly without an extra SD card reader device, the
device name of SD card is typically mmcblk0.
5. After a successful installation, the message “installation finished successfully” appears. Execute the following command
to unmount all mounted partitions of the target device.
Example:
$ sudo umount /run/media/sdX
6. Unplug removable storage device from the Linux host and plugin into the reference board.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
19
Page 20
LS1028A BSP user guide
7. Make sure the DIP switch settings on the board enable booting from FlexSPI NOR (or eMMC / SD card). (Refer to “Onboard switch options” in the preceding section for switch settings.)
8. Power-on the board and stop autoboot to enter the U-Boot prompt.
9. Program/update the composite firmware to FlexSPI NOR flash (or eMMC / SD card) as described below.
Note: <filename> in below steps refers to firmware_ls1028ardb_uboot_xspiboot.img for FlexSPI NOR flash boot source,
firmware_ls1028ardb_uboot_sdboot.img for SD card, and firmware_ls1028ardb_uboot_emmcboot.img for eMMC as
boot source.
• Load firmware image from storage media.
Storage mediaCommand in U-Boot
USB
SATA
SD
eMMC
• If FlexSPI NOR flash is to be used as boot source execute the commands below to program the FlexSPI NOR flash.
=> sf probe 0:0; sf erase 0 +$filesize; sf write a0000000 0 $filesize
=> qixis_reset
• If SD card is to be used as boot source execute the commands below to program the SD card.
• If eMMC is to be used as boot source execute the commands below to program the onboard eMMC.
=> usb start
=> load usb 0:2 a0000000 <filename>
=> load scsi 0:2 a0000000 <filename>
=> load mmc 0:2 a0000000 <filename>
=> load mmc 1:2 a0000000 <filename>
=> mmc dev 1; mmc write a0000000 8 0x25000
where, 0x25000 is number of blocks (max) on eMMC that are required to write the eMMC composite firmware. Each
block is 512 bytes size.
Reboot with eMMC as boot source.
=> qixis_reset emmc
10. The system will automatically boot up BSP Ubuntu distro available from the removable storage device.
3.1.4.3
Option 2 - Deploy BSP images directly to the storage device on
a board
If the user does not have a local Linux host machine that can connect to a removable media, and/or the user does not have local
access to a reference board, the user can directly deploy BSP images to the storage device on a reference board. The reference
board may be accessed by the user remotely. For this option, a network connection to the reference board is required.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
20
NXP Semiconductors
Page 21
LS1028A BSP Quick Start
1. Reboot the reference board from FlexSPI NOR CS0 (or SD card / eMMC) and let it boot automatically.
• If the DIP switch settings are configured to be default, the board will boot from FlexSPI NOR flash CS0 (or SD card /
eMMC) using the composite firmware which is present on the reference board by default.
2. After the reference board boots automatically, check whether the reference board boots TinyDistro or whether it boots
Ubuntu distribution. TinyDistro is a non-customizable prebuilt ramdisk rootfs deployed in flash media on the reference
board. This rootfs fits into the firmware image on flash and is therefore called tiny.
• If the reference board boots TinyDistro, proceed to step #4.
• If the reference board boots Ubuntu distribution, it means that an older Ubuntu distribution may already be present
on the storage device that is plugged into the reference board. In this case, go to step #3 first, to force the board to
boot TinyDistro.
3. Force the reference board to boot TinyDistro.
• Reboot the board and stop autoboot to enter U-Boot prompt in FlexSPI NOR flash (or SD card / eMMC).
• If FlexSPI NOR is the boot source, run the following command to force the reference board to boot TinyDistro
present on FlexSPI NOR flash.
$ run qspi_bootcmd
• If SD card is the boot source, run the following commands to force the reference board to boot TinyDistro present on
SD card.
$ run sd_bootcmd
• If eMMC is the boot source, run the following commands to force the reference board to boot TinyDistro present on
eMMC.
$ run emmc_bootcmd
4. Login to TinyDistro as “root” and bring up a network interface.
$ udhcpc -i <port name in TinyDistro>
For LS1028ARDB, in TinyDistro as well as in Ubuntu distribution, by default, only one Ethernet port is enabled as a standard
Kernel Ethernet Interface.
For LS1028ARDB, this interface is named as Eth0 in TinyDistro and is labeled as 1G MAC0 on chassis front panel as
shown in diagram below.
5. Use flex-installer to create and format the partitions for storage device (USB/SATA/SD).
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
21
Page 22
LS1028A BSP user guide
Storage DeviceCommands in Linux
USB$ flex-installer -i pf -d /dev/sdX
SATA$ flex-installer -i pf -d /dev/sdX
SD$ flex-installer -i pf -d /dev/mmcblk0
eMMC$ flex-installer -i pf -d /dev/mmcblk1
WARNING
• The USB/SATA storage drive in the Linux PC is detected as /dev/sdX, where X is a letter such as a, b, c. Make
sure to choose the correct device name, because data on this device will be replaced.
• Use the command cat /proc/partitions to see a list of devices and their sizes to make sure that the correct
device names have been chosen.
6. Download and deploy two tarballs (boot partition and Ubuntu userland) to USB/SATA/SD storage device. These tarballs
were assembled during the “Download and Assemble BSP Images” step.
Storage DeviceCommands in Linux
USB
SATA
SD
a. $ cd /run/media/sdX3
b. Download bootpartition_<arch>_<version>.tgz and
rootfs_ubuntu_<codename>_<arch>_<timestamp>.tgz using the wget or
scp command.
c. $ flex-installer -b bootpartition_<arch>_lts_<version>.tgz -r
7. Reboot the board with BSP images. The system will automatically boot Ubuntu userland. Login using root/root or user/
user.
8. After the above steps are completed, the reference board is ready to boot the latest Ubuntu userland. Optionally, to make
sure that the reference board boots using the latest firmware, user may choose to update firmware using steps below:
• FlexSPI NOR firmware
a. Reboot the board from FlexSPI NOR flash CS0 and stop autoboot to enter U-Boot prompt.
b. Download the BSP NOR composite firmware for LS1028ARDB using the command
c. Under U-Boot, download the firmware via TFTP to the reference board.
=> tftp a0000000 firmware_ls1028ardb_uboot_xspiboot.img
=> sf probe 0:0; sf erase 0 +$filesize; sf write a0000000 0 $filesize
=> qixis_reset
In the steps above, the contents of the FlexSPI NOR flash are overwritten with the new FlexSPI NOR firmware. The
board is rebooted using the FlexSPI NOR flash.
• SD firmware
a. Reboot the board from FlexSPI NOR flash CS0 (or SD card / eMMC) and stop autoboot to enter U-Boot
prompt.
b. Download the BSP SD composite firmware for LS1028ARDB using the command
where, 0x25000 is number of blocks (max) on eMMC that are required to write the eMMC composite
firmware. Each block is 512 bytes size.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
23
Page 24
LS1028A BSP user guide
d. Reboot with eMMC as boot source.
=> qixis_reset emmc
In the steps above, the contents of the eMMC are overwritten with the new eMMC firmware. The board is then
rebooted using the onboard eMMC.
3.2 How to build LS1028A BSP with Flexbuild
Flexbuild provides cmdline for various build scenarios. The LS1028A BSP Quick Start on page 12 section introduces how to build
the LS1028A BSP distro userland with prebuilt boot partition and component tarballs for quick deployment on the target board.
This section introduces detailed steps to build LS1028A BSP with Flexbuild.
Click here to download flexbuild source tarball in the name format flexbuild_<version>.tgz
$ tar xvzf flexbuild_<version>.tgz
$ cd flexbuild
$ source setup.env
$ flex-builder -h
Build TF-A with RCW and U-Boot in Flexbuild
Layerscape platforms support TF-A (Trusted Firmware-A) which provides a reference implementation of secure world software
for Armv7-A and Armv8-A.
flex-builder can automatically build the dependent RCW, U-Boot, OPTEE and CST when building ATF to generate bl2 and fip
images for Layerscape platforms.
Use the commands below to build uboot-based ATF image in Flexbuild.
In case users modify RCW source code (in packages/firmware/rcw) or specify different RCW binary rather than
the default one, run 'flex-builder -c rcw' to regenerate RCW binary, then reconfigure rcw_<boottype> variable in
configs/board/<machine>/manifest.
NOTE
If RCW or U-Boot source code is updated since last build, make sure clean the obsolete image by commands 'rm
-rf build/firmware/u-boot/<machine>' and/or 'rm -rf build/firmware/rcw/<machine>', then re-build ATF by command
'flex-builder -c atf -m <machine> -b <boottype>'
The '-s' option is used for secure boot, OPTEE and FUSE_PROVISIONING are not enabled by default, change
CONFIG_BUILD_OPTEE=n to y and/or change CONFIG_FUSE_PROVISIONING=n to y in configs/build_lsdk.cfg
to enable it if necessary.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
24
NOTE
NXP Semiconductors
Page 25
How to build LS1028A BSP with Flexbuild
Build Linux kernel with Flexbuild
Besides building LS1028A BSP kernel in stand-alone way (see Configuring and building on page 38), it is easy to automatically
build LS1028A BSP kernel with flex-builder.
To build kernel using the default tree/branch/tag configurations specified in configs/build_lsdk.cfg:
$ flex-builder -c linux # for 64-bit mode of all armv8 Layerscape platforms by
default
$ flex-builder -c linux -a arm64 # for 64-bit mode of all armv8 Layerscape platforms by
default
To build kernel with specified tree/branch/tag and additional fragment config:
Usage:
$ flex-builder -c linux:<kernel-repo>:<branch|tag> -a arm64 -B fragment:<custom>.config
Example:
$ flex-builder -c linux:linux:linux-4.14-ls1028a-early-access -a arm64 -B fragment:lttng.config
$ flex-builder -c linux:linux:ls1028a-early-access-bsp0.2 -a arm64
User can put a custom kernel fragment config file (given named test.config) in flexbuild/packages/linux/<kernel-repo>/arch/arm64/
configs directory, then run the command below to compile kernel as per the default defconfig, lsdk.config and the additional
test.config.
$ flex-builder -c linux -a arm64 -B fragment:test.config
(if -a <arch> is not specified, arm64 arch is used by default)
$ flex-builder -c linux:custom -a arm64 (optional, customize kernel config in interactive
menu)
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
$ flex-builder -c linux -a arm64
25
Page 26
LS1028A BSP user guide
Build LS1028A BSP composite firmware and boot partition
LS1028A BSP composite firmware consists of atf bl2, atf bl3 fip frimware, bootloader environment, secure headers, Ethernet
MAC/PHY firmware, dtb, kernel and tiny ramdisk rfs, etc. This composite firmware can be programmed at offset 0x0 in flash device
or at offset block# 8 in SD/eMMC card.
To generate LS1028A BSP composite firmware for Layerscape platform, directly run the following command:
To generate LS1028A BSP boot partition tarball, run the command as below:
$ flex-builder -i mkbootpartition -a arm64
or
$ flex-builder -i mkbootpartition -a arm64 -s (for secure boot)
The command above will generate all needed images including kernel image, dtb, distro boot script, flex_linux_<arch>.itb, small
ramdiskrfs, etc. Flex-builder automatically builds the dependent images if they are not present.
How to build application components in Flexbuild
The following commands are some examples of building application components.
Usage:
$ flex-builder -c <component> -a <arch> # build single application component for specified <arch>
Example:
$ flex-builder -c apps # build all apps components for arm64 arch
$ flex-builder -c tsntool # build tsntool component for arm64 arch
$ flex-builder -c wayland # build wayland component for arm64 arch
$ flex-builder -c weston # build weston component for arm64 arch
$ flex-builder -c cst # build cst component, needed for secure boot
(arm64 is the default arch if -a <arch> is not specified)
To add new application component in Flexbuild, follow the steps below:
1. Add new <component> to apps_repo_list and set CONFIG_BUILD_<component>=y in configs/build_xx.cfg.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
26
NXP Semiconductors
Page 27
How to build LS1028A BSP with Flexbuild
2. Configure url/branch/tag/commit info for new <component_name>in configs/build_xx.cfg, default remote. Component git
repository is specified by GIT_REPOSITORY_URL by default if <component>_url is not specified, user also can directly
create the new component git repository in packages/apps directory.
3. Add build support of new component in packages/apps/Makefile..
4. Run flex-builder -c <component-name> -a <arch>' to build the new component.
5. Run flex-builder -i merge-component -a <arch> to merge the new component package into target distro userland.
How to update existing Linux kernel with new custom kernel for Ubuntu on target board in case of non secure boot
User can quickly install custom kernel and lib modules after Ubuntu had been deployed in SD card on target board in case of non
secure boot, follow the steps below.
After modify Linux kernel source code in $FBDIR/packages/linux/<kernel-repo> on demand, rebuild kernel
as below
$ flex-builder -c linux:custom (optional, to customize kernel config in interactive menu)
$ flex-builder -c linux
$ flex-builder -i mkbootpartition -a arm64
The new kernel image tarball $FBDIR/build/images/linux_4.14_LS_arm64_<timestamp>.tgz will be generated.
Then login Ubuntu system on target board, update kernel image (take LS1028ARDB for example) as below:
root@localhost:/# dhclient -i eno0
root@localhost:~# cd /
root@localhost:/# wget <path>/linux_4.14_LS_arm64_<timestamp>.tgz (or by scp command)
root@localhost:/# tar xf linux_4.14_LS_arm64_<timestamp>.tgz
root@localhost:/# reboot
System will reboot and automatically boot to Ubuntu with new custom kernel.
Rebuild images after modifying the source code of NXP user space components locally
Flexbuild supports building specific components after the source code is changed. Flexbuild then deploys the changes to the
target board.
1. Modify source code of user space components in the directory packages/apps/<apps-component> on demand.
2. Clean old build footprint under user space component.
$ make clean -C $FBDIR/packages/apps/<app-component>
$ rm -rf $FBDIR/build/apps/components_LS_arm64
3. Build the user space component and generate the compressed component tarball.
$ flex-builder -c <apps-component> -a arm64
$ flex-builder -i compressapps -a arm64
4. Upload and deploy the newly generated app_components_LS_arm64.tgz to target board on which Ubuntu distro had been
installed in SD card.
=> run sd_bootcmd (or run xspi_bootcmd to enter Tiny distro Linux environment)
Download app_components_LS_arm64.tgz via wget or scp command
root@TinyDistro:~# tar xf app_components_LS_arm64.tgz
root@TinyDistro:~# cp -a components_LS_arm64/* /run/media/mmcblk0p3
root@TinyDistro:~# reboot
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
27
Page 28
LS1028A BSP user guide
How to generate a custom Ubuntu root filesystem with custom additional package list on x86 host machine
In Flexbulid, there are two default additional package lists for Ubuntu/Debian: additional_packages_list_moderate, and
additional_packages_list_tiny.
$ flex-builder -i mkrfs -a arm64 (as per additional_packages_list_moderate with more packages for
Ubuntu rootfs by default)
$ flex-builder -i mkrfs -r ubuntu:tiny -a <arch> (as per additional_packages_list_tiny with less
packages for Ubuntu rootfs)
$ flex-builder -i mkrfs -r ubuntu -a <arch> -B <custom_packages_list>
Optionally, if you do not want to use default Ubuntu userland in certain use cases, you can generate Debian, CentOS or buildrootbased tiny userland by following instruction by Flexbuild, for examples:
$ flex-builder -i mkrfs -r debian:tiny:stretch -a arm64 (generate arm64 tiny Debian stretch rootfs as
per configs/ubuntu/additional_packages_list_tiny)
$ flex-builder -i mkrfs -r centos -a arm64 (generate arm64 LE CentOS rootfs as per configs/
centos/distro.cfg)
$ flex-builder -i mkrfs -r buildroot:tiny -a arm64 (generate arm64 LE buildroot userland as per
qoriq_arm64_tiny_defconfig)
$ flex-builder -i mkrfs -r buildroot:moderate -a arm64 (generate arm64 LE buildroot userland as per
qoriq_arm64_moderate_defconfig)
$ flex-builder -i mkrfs -r buildroot:custom -a arm64 (generate arm64 LE buildroot userland as per
custom qoriq_arm64_moderate_defconfig)
$ flex-builder -i mkrfs -r buildroot:custom -a arm64:be (generate arm64 big-endian buildroot userland
with custom qoriq_arm64_moderate_defconfig)
$ flex-builder -i mkrfs -r buildroot:imaevm -a arm64 (generate arm64 LE initramfs userland with
qoriq_arm64_imaevm_defconfig used for secure boot with IMA EVM)
To install a new package to build/rfs/rootfs_ubuntu_bionic_LS_arm64 filesystem, run the following commands:
How to add a new custom machine based on LS1028A BSP release in flexbuild
Assumption: Adding a new custom machine named LS1043AXX based on LS1043A SoC
1. Run flex-builder -i repo-fetch to fetch all git repositories of LS1028A BSP components for the first time
2. Add new machine support in U-Boot and ATF, example:
$ cd packages/firmware/u-boot
$ git checkout LSDK-18.12 -b LSDK-18.12-LS1043AXX
Add necessary U-Boot patches in U-boot tree and commit the patches in this branch for new machine. Add necessary ATF
patches in ATF tree and commit the patches in this branch for new machine. Assume that you have added packages/
firmware/u-boot/configs/ls1043axx_tfa_defconfig and added CONFIG_MACHINE_LS1043AXX=y in configs/
build_lsdk.cfg, then run commands below to build TF-A image based on U-Boot for SD boot on LS1043AXX
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
28
NXP Semiconductors
Page 29
How to build LS1028A BSP with Flexbuild
3. Add new machine support in Linux kernel, take LSDK-18.12 for example:
$ cd packages/linux/linux
$ git checkout LSDK-18.12-V4.14 -b LSDK-18.12-V4.14-LS1043AXX
Now, you can add kernel patches and submit the patches in this branch for the new machine, then make a tag as below.
$ git tag LSDK-18.12-V4.14-LS1043AXX
Assume that you have added a new ls1043axx.dts in packages/linux/linux/arch/arm64/boot/dts directory, run as below to
build kernel image for new LS1043AXX
5. Build all other images for new custom machine with Ubuntu userland if required as below:
$ flex-builder -i mkrfs -a arm64
$ flex-builder -c apps -a arm64
$ flex-builder -i mkbootpartition -a arm64
$ flex-builder -i merge-component -a arm64
$ flex-builder -i compressrfs -a arm64
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
29
Page 30
LS1028A BSP user guide
Finally, install bootpartition_arm64_lts_<version>.tgz and rootfs_ubuntu_<codename>_<arch>.tgz to SD/USB/SATA
storage drive on LS1043AXX machine by flex-installer as below:
How to install distro to SD/USB/SATA storage drive
Use the LS1028A BSP flex-installer to install all the release binaries and distro userland onto a storage media (e.g. SD/eMMC
card, USB/SATA disk) on the Linux host machine or on the target board.
Follow the instructions below:
Step 1: Plug SD/USB/SATA storage device to Linux Host machine or target board
Step 2: Install LS1028A BSP distro
• If the prebuilt distro tarball generated by Flexbuild is available on Linux host machine, run the following command:
sdx should be the actual device name on the host machine, for example: sdb, sdc, mmcblk0, etc.
• If the user wants to modify source code and build a custom LS1028A BSP distro with flexbuild, use the commands below on
the Linux host machine:
$ flex-builder -c linux:custom -a <arch> # customize kernel config in interactive menu
$ flex-builder -c linux -a <arch>
$ flex-builder -i mkfw -m <machine> -b <boottype>
$ flex-builder -i mkrfs -a <arch>
$ flex-builder -c apps -a <arch>
$ flex-builder -i merge-component -a <arch>
$ flex-builder -i mkbootpartition -a <arch>
$ flex-installer -b build/images/bootpartition_LS_arm64_lts_4.14 -r build/rfs/
rootfs_ubuntu_bionic_LS_arm64 -d /dev/sdx
• If the user wants to install disrto rootfs directly onto SD/USB/SATA disk on QorIQ board on which Linux is unavailable,
download the prebuilt lsdk_linux_<arch>_LS_tiny.itb image using the command:
• After booting and logging in to Linux on the target board, download the prebuilt distro tarballs generated by Flexbuild and
install using the commands below:
$ flex-installer -i pf -d /dev/sdx
$ cd /run/media/{mmcblk0p3 or sdx3}, then download distro images to SD/USB/SATA storage disk via
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
Step 3: Power on or reboot the target board after finishing the distro installation, the system will enter boot loader (U-Boot) and
automatically scan boot configuration script from the attached SD/USB/SATA disk and boot the target LS1028A BSP distro if found,
otherwise it falls back to boot from Flexspi-NOR flash with tiny ramdisk distro.
How to program firmware to SD/Flexspi-NOR flash media
For SD card (on all platforms):
•
1. Download the prebuilt image (take LS1028ARDB for example):
— Option 1: Load the prebuilt image from SD card in U-Boot:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
34
Table continues on the next page...
NXP Semiconductors
Page 35
Build tools
Table 8. Flash layout (continued)
Ramdisk RFS32MB0x020000000x10000
Storage layout on SD/USB/SATA for LS1028A BSP images deployment
With LS1028A BSP flex-installer, the LS1028A BSP distro can be installed into an SD/USB/SATA storage disk which should have
at least 8GB of memory space.
Table 9. Storage Layout on SD/USB/SATA for LS1028A BSP Image Deployment
Region 1
(4KB)
MBR/GPTRCW
Region 2
(RAW)
64MB
Firmware
U-Boot or UEFI
TF-A firmware
Secure boot headers
FMan/DP firmware
QE/uQE firmware
Eth PHY firmware
MC firmware
DPC firmware
DPL firmware
DTB
lsdk_linux_<arch>.itb
Region 3
(Partition-1 FAT32)
20MB
EFI
BOOTAA64.EFI
grub.cfg
Region 4
(Partition-2 EXT4)
1GB
Boot partition
kernel image
DTB
lsdk_linux_<arch>.itb
distro boot scripts
secure headers
other
Region 5
(Partition-3 EXT4)
Remaining space
RootFS partition
Ubuntu
or
Ubuntu-Core
or
CentOS
or
Debian
3.5 Build tools
Flexbuild is a component-oriented build framework and integrated platform with capabilities of flexible, easy-to-use, scalable
system build and distro installation. With flex-builder CLI tool, users can build various components (Linux, U-Boot, RCW, TF-A
and miscellaneous custom userspace applications) and distro userland to generate composite firmware, hybrid rootfs with
customable userland. The following are Flexbuild's main features:
• Automatically build Linux, U-Boot, TF-A, RCW and miscellaneous user space applications.
• Generate machine-specific composite firmware for various boot types: SD/QSPI/NOR/NAND boot, secure boot, U-Boot.
• Support integrated management with repo-fetch, repo-branch, repo-commit, repo-tag, repo-update for git repositories of all
components.
• Support cross build on x86 Ubuntu 18.04 host machine for aarch64/armhf arch target.
• Support native build on aarch64/armhf machine for ARM arch target.
• Support creating an Ubuntu docker container and building LSDK inside it when the host machine is using CentOS, RHEL,
Fedora, SUSE, Debian, non-18.04 Ubuntu, etc.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
35
Page 36
LS1028A BSP user guide
• Scalability of integrating various components of both system firmware and user space applications.
• Capability of generating custom aarch64/armhf Ubuntu userland integrated configurable packages and proprietary
components.
Flexbuild can separately build each component or automatically build all components, it generates the boot firmware (RCW, UBoot, PHY firmware, kernel image, and ramdiskrfs), lsdk_linux_<arch>_tiny.itb, and the Ubuntu userland containing the specified
packages and application components.
NOTE
Since LSDK-18.06, upgrading of toolchain is required for U-Boot v2018.03 or later, if your host machine is not a
Ubutnu 18.04 system, there are two ways to use Ubuntu 18.04 toolchain as below:
• Run sudo do-release-upgrade command to upgrade existing Ubuntu 16.04 to Ubuntu 18.04
• Run flex-builder docker command on the existing non Ubuntu 18.04 host to create a ubuntu 18.04 docker
container in which GCC 7.3.0 is available, then build LSDK in docker.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
36
NXP Semiconductors
Page 37
Chapter 4
Linux kernel
Introduction
The Linux kernel is a monolithic Unix-like computer operating system kernel. It is the central part of Linux operating systems that
are extensively used on PCs, servers, handheld devices and various embedded devices such as routers, switches, wireless access
points, set-top boxes, smart TVs, DVRs, and NAS appliances. It manages tasks/applications running on the system and manages
system hardware. A typical Linux system looks like this:
The Linux kernel was created in 1991 by Linus Torvalds and released as an open source project under GNU General Public
License(GPL) version 2. It rapidly attracted developers around the world. In 2015 the Linux kernel has received contributions from
nearly 12,000 programmers from more than 1,200 companies. The software is officially released on http://www.kernel.org website
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
Figure 2. Typical Linux System
37
Page 38
Linux kernel
through downloadable packages and GIT repositories. A general Linux kernel introduction from kernel.org can also be found at
Kernel Releases and relationship with Layerscape SDK
There are different Linux kernel releases coming from different sources. Below we listed the ones that are related to the LSDK
kernel.
Kernel.org official kernel releases
Mainline
•
Mainline tree is maintained by Linus Torvalds. It's the tree where all new features are introduced and where all the exciting
new development happens. New mainline kernels are released every 2-3 months.
Longterm (LTS)
•
There are usually several "longterm maintenance" kernel releases provided for the purposes of backporting bugfixes for older
kernel trees. Only important bugfixes are applied to such kernels and they don't usually see very frequent releases, especially
for older trees.
Refer to https://www.kernel.org/category/releases.html for the current maintained Longterm releases.
Linaro LSK kernel release
Linaro is an open organization focused on improving Linux on ARM. They are also providing a Linux kernel release called Linaro
Stable Kernel (LSK). It is based on kernel.org Longterm kernel releases and included ARM related features developed by Linaro.
Normally these features are generic kernel features for the ARM architecture. Please refer to https://wiki.linaro.org/LSK for more
information about the LSK releases.
NXP Layerscape SDK kernel
NXP’s SDK kernel often contains patches that are not upstream yet so essentially the LSDK kernel is an enhanced Linaro LSK
which is in turn an enhanced kernel.org LTS. In order to fully utilize the ARM open source eco-system. The kernel versions provided
in NXP LSDK will be chosen from the kernel.org Longterm releases to include the important bugfixes backported. It will also
include generic ARM kernel features provided by the Linaro LSK release which could be important for some users.
Getting the LSDK kernel source code
With Layerscape SDK, NXP owned/updated software components are published on github. You can use git commands to get the
latest kernel source code.
• Install git command if not there already. For example, on Ubuntu:
Configuring and building the Linux kernel is controlled by the Kbuild sub-system. You can find documents describing the internal
of Kbuild sub-system under the Documentation/kbuild/ folder in the Linux source code tree if you are adding new files or new
configure options to the kernel. Otherwise as a user of Linux kernel, you probably only want to know how to fine tune the kernel
configuration base on your system requirements and build new kernel image with updated configuration. These are done through
make commands, below we will talk about make commands you probably need to know as a kernel user.
Configuring and building
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
38
NXP Semiconductors
Page 39
Configuring and building
Environment setting for cross-compiling
This following settings are applicable when you are configuring and building kernel on a different architecture from the target. For
example, compiling an ARMv8 kernel on an X86 computer. If you are compiling the kernel natively on a machine of the same
architecture as the target, you should skip this chapter.
• Install the cross compiler of your distribution
• Specify the target architecture in ARCH environment variable
• Specify the prefix (and path) of a cross compiler in CROSS_COMPILE environment variable
For the shell environment variables exported above, you can also include them directly in each make command you use. E.g. $
ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make {targets}. Exporting them will save effort if you are using make in
kernel frequently.
Configuring kernel
The current kernel configuration for a kernel source tree will be kept in a hidden file named .config at the top level of the kernel
source code after you changed the configuration with any of the make config command variants. You can copy it directly from one
kernel source tree to another with the same kernel version to duplicate the configuration exactly. Also, you can edit it with a text
editor, in which you can see a list of CONFIG_* symbols corresponding to each of the kernel configure option.
The following targets from the Linux kernel Kbuild framework are used to load the default kernel configuration for LS1028A BSP:
• defconfig/${PLATFORM}_defconfig
Create the .config file by using the default config options of the architecture or platform defined in the arch/$ARCH/configs/
directory. This normally includes all the device drivers needed for the architecture or platform.
• ${FRAGMENT}.config
Merge a configuration fragment that enables certain features into the .config file.
Specific command to load the default configuration of different platforms for LS1028A BSP will be:
• For Layerscape ARMv8 platforms in 64bit mode:
$ make defconfig lsdk.config
• For Layerscape ARMv7 platforms:
$ make multi_v7_defconfig multi_v7_lpae.config lsdk.config
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
39
Page 40
Linux kernel
• For Layerscape ARMv8 platforms in 32bit mode:
$ make multi_v7_defconfig multi_v7_lpae.config multi_v8.config lsdk.config
To further fine tune the configuration base on your system need you can use the following make commands.
• $ make menuconfig
Choose configure options in text based color menus, radiolists & dialogs. It is a good way to navigate through all the selectable
kernel configure options in a well-organized human-readable hierarchy and you can get a description of every option when
it is highlighted by selecting the <Help> button. In the device driver part of this User’s Manual we also provided the path to
the configure options needed for a feature to work in the menuconfig.
• $ make ${FRAGMENT}.config
You can also utilize this capability to enable options for a specific feature in your custom kernel configuration quickly without
selecting each one of them in the menuconfig. In the device driver part of this User’s Manual, we listed the CONFIG_* symbols
needed by a specific feature/driver. Put these symbols with “=y” or “=m” depending on if you want these features/drivers to
be built-in or built as loadable kernel module into a ${FEATURE}.config file under arch/$ARCH/configs/ directory. Run $
make ${FEATURE}.config command, it will enable all these listed kernel configure options together.
Building kernel
Building the kernel is simple.
• To build kernel images and device tree images.
make
• To build loadable kernel modules:
make modules
You can supply -j <NUM> option to the above make commands to spin NUM concurrent threads to reduce build time on multicore
systems.
After a successful build:
• Compiled kernel images are in arch/${ARCH}/boot/ folder.
• Compiled device trees (dtb files) are in arch/${ARCH}/boot/dts folder.
• Compiled kernel modules are spread out in driver folders. You can extract them to a specific folder (e.g. /folder/to/install) by
using command:
$ make modules_install INSTALL_MOD_PATH=/folder/to/install
Install new kernel and modules
The path or naming convention of kernel images and modules are different for different Linux distributions. The following
instructions are based on the convention of LS1028A BSP.
Using the flex-build scripts
• Copy kernel image, dtb and kernel modules from your kernel tree to the staging folder of the flexbuild script (Skip if you are
using the flexbuild -c linux to build the kernel directly).
• Regenerate the boot partition and rootfs (for commands below: ${ARCH} = arm32 | arm64)
$ flex-builder -i mkbootpartition -a ${ARCH}
$ flex-builder -i merge-component -a ${ARCH}
$ flex-builder -i compressrfs -a ${ARCH}
• Use flex-installer to deploy the updated boot partition and rootfs to the device following the LS1028A BSP Quick Start on page
12.
Update the target filesystem directly
This can be more convenient if you are compiling the kernel on the target device locally or you can easily update the filesystem
of target device remotely (e.g. using scp, tftp, or etc.).
• Copy your Image file to /boot folder on the target using cp if compiled locally; Use any available remote update approach if
compiled remotely.
• Copy dtb files to /boot folder on the target using cp if compiled locally; Use any available remote update approach to do the
same if compiled remotely.
• Update kernel modules. (Note: kernel modules are required to be updated when you updated the kernel image).
— If you compiled the kernel on the target device locally. Use the command below:
$ make modules_install
— If you compiled the kernel remotely. Do the following:
◦ Install the modules into a temporary folder (e.g. /tmp/lsdk/).
$ make modules_install INSTALL_MOD_PATH=/tmp/lsdk/
◦ Transfer the lib/ directory from the temporary location above to the target device using any file transfer approach
and put it in the / path of the filesystem.
4.2
Device Drivers
4.2.1 CAAM Direct Memory Access (DMA)
Description
The CAAM DMA module implements a DMA driver that uses the CAAM DMA controller to provide both SG and MEMCPY DMA
capability to be used by the platform. It is based on the CAAM JR interface that must be enabled in the kernel config as a
prerequisite for the CAAM DMA driver.
The driver is based on the DMA engine framework and it is located under the DMA Engine support category in the kernel config
menu.
Kernel Configure Options
Tree Overview
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
41
Page 42
Linux kernel
To enable the CAAM DMA module, set the following options for make menuconfig:
-*- Cryptographic API --->
[*] Hardware crypto devices --->
<*> Freescale CAAM-Multicore driver backend
<*> Freescale CAAM Job Ring driver backend
Device Drivers --->
<*> DMA Engine support --->
<*> CAAM DMA engine support
NOTE
Be aware that the CAAM DMA driver depends on the CAAM and CAAM JR drivers, which also have to be enabled.
Identifier
The following configure identifier is used in kernel source code and default configuration files.
OptionValuesDefault ValueDescription
CONFIG_CRYPTO_DEV_FS
y/m/nnCAAM DMA engine support
L_CAAM_DMA
Device Tree Node
Below is an example device tree node required by this feature.
caam_dma {
compatible = "fsl,sec-v5.4-dma";
};
Source Files
The following source file is related to this feature in the Linux kernel.
Source FileDescription
drivers/dma/caam_dma.cThe CAAM DMA driver
Verification in Linux
On a successful probing, the driver will print the following message in dmesg:
[ 1.443940] caam-dma 1700000.crypto:caam_dma: caam dma support with 4 job rings
Additionally, you can also run the following commands:
ls -l /sys/class/dma/
total 0
lrwxrwxrwx 1 root root 0 Jan 1 1970 dma0chan0 -> ../../devices/platform/soc/1700000.crypto/
The above configuration is self explanatory except a few:
If you set the 'noverify' parameter to 0 it will not perform check of the copied buffer at the end of each testing round. This should
be used for performance testing. Set the 'noverify' parameter to 1 for functional testing.
Set the 'dmatest' parameter to 0 to test the memcpy functionality and to 1 to test the sg functionality.
Perform the test
To perform the test simply run the command:
$ echo 1 > /sys/module/dmatest/parameters/run
Depending on the type of test performed (sg/memcpy) the output may vary. Here is an example of output obtained with the above
parameters:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
43
Page 44
Linux kernel
Description
The enhanced secured host controller (eSDHC) provides an interface between the host system and the SD/SDIO cards and
eMMC devices.
The eSDHC device driver supports either kernel built-in or module.
Kernel Configure Options
Tree View
Kernel Configure Options Tree ViewDescription
Device Drivers --->
<*> MMC/SD/SDIO card support --->
<*> MMC block device driver
(8) Number of minors per block device
[*] Use bounce buffer for simple hosts
Enables SD/MMC block device driver support
Enables NXP eSDHC driver support
*** MMC/SD/SDIO Host Controller Drivers ***
<*> Secure Digital Host Controller Interface
support
<*> SDHCI platform and OF driver helper
[*] SDHCI OF support for the NXP eSDHC
controller
Compile-time Configuration Options
OptionValuesDefault ValueDescription
CONFIG_MMCy/nyEnable SD/MMC bus protocol
CONFIG_MMC_BLOCKy/nyEnable SD/MMC block device
driver support
CONFIG_MMC_BLOCK_MIN
integer8Number of minors per block
ORS
CONFIG_MMC_BLOCK_BO
y/nyEnable continuous physical
UNCE
CONFIG_MMC_SDHCIy/nyEnable generic sdhc interface
CONFIG_MMC_SDHCI_PLTFMy/nyEnable common helper
CONFIG_MMC_SDHCI_OF_
y/nyEnable NXP eSDHC support
ESDHC
Source Files
The driver source is maintained in the Linux kernel source tree.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
44
device
memory for transmit
function support for sdhci
platform and OF drivers
NXP Semiconductors
Page 45
Source FileDescription
drivers/mmc/host/sdhci.cLinux SDHCI driver support
drivers/mmc/host/sdhci-pltfm.cLinux SDHCI platform devices support driver
MMC read: dev # 0, block # 0, count 2 ... 2 blocks read: OK
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
45
Page 46
Linux kernel
=> cmp.l 81000000 82000000 100
Total of 256 word(s) were the same
=>
Verification in Linux
Set U-Boot environment
=> setenv hwconfig sdhc
The linux booting log
......
[ 3.913163] sdhci: Secure Digital Host Controller Interface driver
[ 3.919339] sdhci: Copyright(c) Pierre Ossman
[ 3.931467] sdhci-pltfm: SDHCI platform and OF driver helper
[ 3.938900] sdhci-esdhc 1560000.esdhc: No vmmc regulator found
[ 3.944728] sdhci-esdhc 1560000.esdhc: No vqmmc regulator found
[ 3.978676] mmc0: SDHCI controller on 1560000.esdhc [1560000.esdhc] using ADMA 64-bit
[ 4.197784] mmc0: new high speed SDHC card at address b368
[ 4.203502] mmcblk0: mmc0:b368 SDC 7.45 GiB
Partition the card with fdisk
~# fdisk /dev/mmcblk0
Welcome to fdisk (util-linux 2.26.2).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Device does not contain a recognized partition table.
Created a new DOS disklabel with disk identifier 0x5a5f34b3.
Command (m for help): n
Partition type
p primary (0 primary, 0 extended, 4 free)
e extended (container for logical partitions)
Select (default p):
Using default response p.
Partition number (1-4, default 1):
First sector (2048-15628287, default 2048):
Last sector, +sectors or +size{K,M,G,T,P} (2048-15628287, default 15628287):
Created a new partition 1 of type 'Linux' and of size 7.5 GiB.
Command (m for help): w
The partition table has been altered.
Calling ioctl() [ 410.501876] mmcblk0: p1
to re-read partition table.
Syncing disks.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
46
NXP Semiconductors
Page 47
Disklabel type: dos
Disk identifier: 0x5a5f34b3
Device Boot Start End Sectors Size Id Type
/dev/mmcblk0p1 2048 15628287 15626240 7.5G 83 Linux
Format the card with mkfs
~# mkfs.ext2 /dev/mmcblk0p1
mke2fs 1.42.9 (28-Dec-2013)
Discarding device blocks: [ 37.611042] random: nonblocking pool is initialized
done
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
Stride=0 blocks, Stripe width=0 blocks
488640 inodes, 1953280 blocks
97664 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=2000683008
60 block groups
32768 blocks per group, 32768 fragments per group
8144 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632
Device Drivers
Allocating group tables: done
Writing inode tables: done
Writing superblocks and filesystem accounting information: done
~#
Mount, read, and write
~# mount /dev/mmcblk0p1 /mnt/
~# ls /mnt/
lost+found
~# cp -r /lib /mnt/
~# sync
~# ls /mnt/
lib lost+found
~# umount /dev/mmcblk0p1
~# ls /mnt/
~#
Known Bugs, Limitations, or Technical Issues
1. Call trace of more than 120 seconds task blocking when running iozone to test card performance. This is not issue and
use below command to disable the warning.
echo 0 > /proc/sys/kernel/hung_task_timeout_secs
2. Layerscape boards could not provide a power cycle to SD card but according to SD specification, only a power cycle could
reset the SD card working on UHS-I speed mode. When the card is on UHS-I speed mode, this hardware problem may
cause unexpected result after board reset. The workaround is using power off/on instead of reset when using SD UHS-I
card.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
47
Page 48
Linux kernel
3. Transcend 8G class 10 SDHC card has some compatibility issue. It is observed it could not work on 50 MHz high-speed
mode on LS2 boards, but other brand SD cards (Sandisk, Kingston, Sony ...) worked fine. Reducing SD clock frequency
could also resolve the issue. The workaround is using other kind SD cards instead.
4. After sleep of LS1046ARDB, the card will get below interrupt timeout issue. This is hardware issue. CMD18 (multiple blocks
read) has hardware interrupt timeout issue.
mmc0: Timeout waiting for hardware interrupt.
5. Linux MMC stack does not have SD UHS-II support currently. It could not handle SD UHS-II card well. If UHS-I support is
enabled in eSDHC dts node, the driver may make SD UHS-II card enter 1.8v mode. Only a power cycle could reset the
card, so use power off/on instead of reset for SD UHS-II card if UHS-I support is enabled in eSDHC dts node.
6. For LS1012ARDB RevD and later versions, I2C reading for DIP switch setting is not reliable so U-Boot could not enable/
disable SDHC2 automatically. If SDHC2 is used, "esdhc1" should be set in U-Boot hwconfig environment to enable it
manually.
4.2.3
IEEE 1588
Description
From IEEE-1588 perspective, the components required are:
1. IEEE-1588 extensions to the ENETC driver and Felix switch driver.
2. A stack application for IEEE-1588 protocol.
IEEE 1588 device driver supports either kernel built-in or module.
Kernel Configure Options
Tree View
1. ENETC
Kernel Configure Tree View OptionsDescription
Device Drivers --->
[*] Network device support --->
[*] Ethernet driver support --->
[*] Freescale devices
<*> ENETC PF driver
-*- ENETC PTP clock driver
[*] ENETC hardware timestamping support
Enable 1588 driver for ENETC
2. Felix switch
Kernel Configure Tree View OptionsDescription
Device Drivers --->
[*] Network device support --->
[*] Ethernet driver support --->
[*] Microsemi devices
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
48
Enable 1588 driver for Felix switch
NXP Semiconductors
Page 49
Device Drivers
Kernel Configure Tree View OptionsDescription
<*> FELIX switch driver
[*] FELIX switch PTP clock support
Compile-time Configuration Options
1. ENETC
OptionValuesDefault ValueDescription
CONFIG_FSL_ENETCy/n/myEnable ENETC driver support
CONFIG_FSL_ENETC_PTP
y/n/myEnables PTP driver support
_CLOCK
FSL_ENETC_HW_TIMESTA
y/nyEnable timestamping support
MPING
2. Felix switch
OptionValuesDefault ValueDescription
CONFIG_MSCC_FELIX_SWI
TCH
CONFIG_MSCC_FELIX_SWI
y/n/myEnable Felix switch driver
support
y/n/mnEnables PTP driver support
TCH_PTP_CLOCK
Source Files
The driver source is maintained in the Linux kernel source tree.
The slave side would print synchronization messages.
Note:
•
For Felix switch, ptp4l works on both, CPU port with bridge case and CPU port without bridge case. However, ptp4l should
only work on L2 Ethernet protocol with -2 option for CPU port with bridge case.
Known Bugs, Limitations, or Technical Issues
• The Felix switch interrupt had not been implemented in driver. Polling method in work queue was used instead temporary
for timestamping support.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
50
NXP Semiconductors
Page 51
Device Drivers
• The Felix switch extraction is working on all packets. Therefore, the L2 forwarding in CPU port with bridge case is actually
software forwarding, not hardware forwarding.The frame identifying should be supported so that extraction works only on
PTP packets.
4.2.4 Low Power Universal Asynchronous Receiver/Transmitter
(LPUART)
Description
Low Power Universal asynchronous receiver/transmitter (LPUART) is a high speed and low-power UART. Refer to below table for
the NXP SoCs that can support LPUART.
SoCNum of LPUART module
LS1021A6
LS1043A6
U-Boot ConfigurationCompile time options
Below are major U-Boot configuration options related to this feature defined in platform specific config files under include/configs/
directory.
1. Boot up U-Boot from bank0, and update rcw and U-Boot for LPUART support to bank4, first copy the rcw and U-Boot binary
to the TFTP directory.
2. Please refer to the platform deploy document to update the rcw and U-Boot.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
52
NXP Semiconductors
Page 53
Device Drivers
3. After all is updated, run U-Boot command to switch to alt bank, then will bring up the new U-Boot to the LPUART console.
CPU: Freescale LayerScape LS1020E, Version: 1.0, (0x87081010)
Clock Configuration:
CPU0(ARMV7):1000 MHz,
Bus:300 MHz, DDR:800 MHz (1600 MT/s data rate),
Reset Configuration Word (RCW):
00000000: 0608000a 00000000 00000000 00000000
00000010: 60000000 00407900 e0025a00 21046000
00000020: 00000000 00000000 00000000 08038000
00000030: 00000000 001b7200 00000000 00000000
I2C: ready
Board: LS1021ATWR
CPLD: V2.0
PCBA: V1.0
VBank: 0
DRAM: 1 GiB
Using SERDES1 Protocol: 48 (0x30)
Flash: 0 Bytes
MMC: FSL_SDHC: 0
EEPROM: NXID v16777216
PCIe1: Root Complex no link, regs @ 0x3400000
PCIe2: disabled
In: serial
Out: serial
Err: serial
SATA link 0 timeout.
AHCI 0001.0300 1 slots 1 ports ? Gbps 0x1 impl SATA mode
flags: 64bit ncq pm clo only pmp fbss pio slum part ccc
Found 0 device(s).
SCSI: Net: eTSEC1 is in sgmii mode.
eTSEC2 is in sgmii mode.
eTSEC1, eTSEC2 [PRIME], eTSEC3
=>
Verification in Linux
1. After uboot startup, set the command line parameter to pass to the linux kernel including console=ttyLP0,115200 in
boootargs. For deploy the ramdisk as rootfs, the bootargs can be set as: "set bootargs root=/dev/ram0 rw
console=ttyLP0,115200"
=> set bootargs root=/dev/ram0 rw console=ttyLP0,115200
Uncompressing Linux... done, booting the kernel.
Booting Linux on physical CPU 0xf00
Linux version 3.12.0+ (xxx@rock) (gcc version 4.8.3 20131202 (prerelease) (crosstool-NG
linaro-1.13.1-4.8-2013.12 - LinaroGCC 2013.11) ) #664 SMP Tue Jun 24 15:30:45 CST 2014
CPU: ARMv7 Processor [410fc075] revision 5 (ARMv7), cr=30c73c7d
CPU: PIPT / VIPT nonaliasing data cache, VIPT aliasing instruction cache
Machine: Freescale Layerscape LS1021A, model: LS1021A TWR Board
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
53
Page 54
Linux kernel
Memory policy: ECC disabled, Data cache writealloc
PERCPU: Embedded 7 pages/cpu @8901c000 s7936 r8192 d12544 u32768
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 520720
Kernel command line: root=/dev/ram rw console=ttyLP0,115200
PID hash table entries: 4096 (order: 2, 16384 bytes)
[...]
ls1021atwr login: root
root@ls1021atwr:~#
2. After the kernel boot up to the console, you can type any shell command in the LPUART TERMINAL.
4.2.5 Flex Serial Peripheral Interface (FlexSPI)
U-Boot Configuration
Make sure your boot mode support FlexSPI.
Use FlexSPI boot mode to boot on board, please check the board user manual and boot from FlexSPI. (or some other boot mode
decide by your board.)
Following Config options needs to be enabled for FlexSPI.
• CONFIG_NXP_FSPI=y
• CONFIG_FSPI_AHB_EN_4BYTE=y
• CONFIG_SYS_FSPI_AHB_INIT=y
Kernel Configure Tree View Options
Device Drivers --->
Memory Technology Device (MTD) support
RAM/ROM/Flash chip drivers --->
< > Detect flash chips by Common Flash Interface (CFI) probe
< > Detect non-CFI AMD/JEDEC-compatible flash chips
< > Support for RAM chips in bus mapping
< > Support for ROM chips in bus mapping
< > Support for absent chips in bus mapping
Self-contained MTD device drivers --->
<*> Support most SPI Flash chips (AT26DF, M25P, W25X, ...)
< > NAND Device Support -- <*> SPI-NOR device support --->
the framework for SPI-NOR support
<*> NXP Flex SPI controller
CONFIG_SPI_NXP_FLEXSPI:
This enabled support for the FlexSPI controller in master mode.
-> Memory Technology Device (MTD) support (MTD [=y])
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
54
NXP Semiconductors
Page 55
-> SPI-NOR device support (MTD_SPI_NOR [=y])
Depends on: MTD [=y] && MTD_SPI_NOR [=y]
Compile-time Configuration Options
ConfigValuesDefualt ValueDescription
Device Drivers
CONFIG_SPI_NXP_FLEXSPIy/ny
CONFIG_MTD_SPI_NOR_BAS
E
y/ny
Enable FlexSPI module
Enables the framework for
SPI-NOR
Verification in U-Boot
=> sf probe 0:0
SF: Detected mt35xu512g with page size 256 Bytes, erase size 128 KiB, total 64 MiB
=> sf erase 0 100000
SF: 1048576 bytes @ 0x0 Erased: OK
=> sf write 82000000 0 1000
SF: 4096 bytes @ 0x0 Written: OK
=> sf read 81100000 0 1000
SF: 4096 bytes @ 0x0 Read: OK
=> cm.b 81100000 82000000 1000
Total of 4096 byte(s) were the same
~ # mtd_debug erase /dev/mtd0 0x00000000 1048576
Erased 1048576 bytes from address 0x00000000 in flash
Write the FlexSPI flash
~ # dd if=/bin/ls.coreutils of=tp bs=4096 count=1
~ # mtd_debug write /dev/mtd0 0 4096 tp
Copied 4096 bytes from tp to address 0x00000000 in flash
Read the FlexSPI flash
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
55
Page 56
Linux kernel
~ # mtd_debug read /dev/mtd0 0 4096 dump_file
Copied 4096 bytes from address 0x00000000 in flash to dump_file
Check Read and Write
Use compare tools(yacto has tools named diff).
~ # diff tp dump_file
~ #
If diff command has no print log, the FlexSPI verification is passed.
4.2.6 Real Time Clock (RTC)
Linux SDK for QorIQ Processors
Description
Provides the RTC function.
Kernel Configure Tree View Options
Kernel Configure Tree View OptionsDescription
Device Drivers->
Real Time Clock-->
[*] Set system time from RTC on
startup and resume (new)
(rtc0) RTC used to set the system
time (new)
<[*] /sys/class/rtc/rtcN (sysfs)
<[*] /proc/driver/rtc (procfs for
rtc0)
<[*] /dev/rtcN (character devices)
Enable RTC driver
Compile-time Configuration Options
OptionValuesDefault ValueDescription
CONFIG_RTC_LIBy/m/nyEnable RTC lib
CONFIG_RTC_CLASSy/m/nyEnable generic RTC class
support
CONFIG_RTC_HCTOSYSy/nySet the system time from
RTC when startup and
resume
CONFIG_RTC_HCTOSYS_D
EVICE
CONFIG_RTC_INTF_SYSFS y/m/nyEnable RTC to use sysfs
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
56
"rtc0"RTC used to set the system
time
Table continues on the next page...
NXP Semiconductors
Page 57
Device Drivers
Table continued from the previous page...
OptionValuesDefault ValueDescription
CONFIG_RTC_INTF_PROCy/m/nyUse RTC through the proc
interface
CONFIG_RTC_INTF_DEVy/m/nyEnable RTC to use /dev
interface
Source Files
The driver source is maintained in the Linux kernel source tree.
...
rtc-ds3232 1-0068: rtc core: registered ds3232 as rtc0
MC object device driver dpaa2_rtc registered
rtc-ds3232 0-0068: setting system clock to 2000-01-01 00:00:51 UTC (946684851)
...
NOTE: Please refer to the related DTS file to enable the RTC driver before building.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
57
Page 58
Linux kernel
For example, LS2080AQDS board, should enable the below option:
<*> Dallas/Maxim DS3232
Change the RTC time in Linux Kernel
~ # ls /dev/rtc -l
lrwxrwxrwx 1 root root 4 Jan 11 17:55 /dev/rtc -> rtc0
~ # date
Sat Jan 1 00:01:38 UTC 2000
~ # hwclock
Sat Jan 1 00:01:41 2000 0.000000 seconds
~ # date 011115502011
Tue Jan 11 15:50:00 UTC 2011
~ # hwclock -w
~ # hwclock
Tue Jan 11 15:50:36 2011 0.000000 seconds
~ # date 011115502010
Mon Jan 11 15:50:00 UTC 2010
~ # hwclock -s
~ # date
Tue Jan 11 15:50:49 UTC 2011
~ #
NOTE: Before using the rtc driver, make sure the /dev/rtc node in your file system is
correct. Otherwise, you need to make correct node for /dev/rtc
4.2.7
Queue Direct Memory Access Controller (qDMA)
The qDMA controller transfers blocks of data between one source and one destination. The blocks of data transferred can be
represented in memory as contiguous or noncontiguous using scatter/gather table(s). Channel virtualization is supported through
enqueuing of DMA jobs to, or dequeuing DMA jobs from, different work queues.
QDMA can support Layerscape platform with DPAA1 or DPAA2.
QDMA for platform with DPAA1
Kernel Configure Options
Below are the configure options need to be set/unset while doing "make menuconfig" for kernel.
Kernel Configure Tree View OptionsDescription
Device Drivers --->
[*] DMA Engine support ---> --->
<*> Freescale qDMA engine support
Support the Freescale qDMA engine with command queue and
legacy mode.
Channel virtualization is supported through enqueuing of DMA
jobs to,
or dequeuing DMA jobs from, different work queues.
This module can be found on Freescale LS SoCs.
Identifier
Below are the configure identifiers which are used in kernel source code and default configuration files.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
58
NXP Semiconductors
Page 59
OptionValuesDefault ValueDescription
CONFIG_FSL_QDMAy/m/nnqDMA driver
Device Tree Binding
Device Tree Node
Below is an example device tree node required by this feature. Note that it may has differences among platforms.
4.2.8 Serial Advanced Technology Attachment (SATA)
Description
The driver supports NXP native SATA controller.
Module Loading
SATA driver supports either kernel built-in or module.
Device Drivers
Kernel Configure Tree View OptionsDescription
Enables SATA controller support on ARM-based SoCs
Device Drivers--->
<*> Serial ATA and Parallel ATA drivers --->
--- Serial ATA and Parallel ATA drivers
<*> AHCI SATA support
<*> Freescale QorIQ AHCI SATA
support
Compile-time Configuration Options
OptionValuesDefault ValueDescription
CONFIG_SATA_AHCI=yy/m/nyEnables SATA controller
CONFIG_SATA_AHCI_QORI
y/m/nyEnables SATA controller
Q=y
Source Files
The driver source is maintained in the Linux kernel source tree.
Source FileDescription
drivers/ata/ahci_qoriq.cPlatform AHCI SATA support
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
61
Page 62
Linux kernel
Test Procedure
Please follow the following steps to use USB in Simics
(1) Boot up the kernel
...
fsl-sata ffe18000.sata: Sata FSL Platform/CSB Driver init
scsi0 : sata_fsl
ata1: SATA max UDMA/133 irq 74
fsl-sata ffe19000.sata: Sata FSL Platform/CSB Driver init
scsi1 : sata_fsl
ata2: SATA max UDMA/133 irq 41
...
(2) The disk will be found by kernel.
...
ata1: Signature Update detected @ 504 msecs
ata2: No Device OR PHYRDY change,Hstatus = 0xa0000000
ata2: SATA link down (SStatus 0 SControl 300)
ata1: SATA link up 1.5 Gbps (SStatus 113 SControl 300)
ata1.00: ATA-8: WDC WD1600AAJS-22WAA0, 58.01D58, max UDMA/133
ata1.00: 312581808 sectors, multi 0: LBA48 NCQ (depth 16/32)
ata1.00: configured for UDMA/133
scsi 0:0:0:0: Direct-Access ATA WDC WD1600AAJS-2 58.0 PQ: 0 ANSI: 5
sd 0:0:0:0: [sda] 312581808 512-byte logical blocks: (160 GB/149 GiB)
sd 0:0:0:0: Attached scsi generic sg0 type 0
sd 0:0:0:0: [sda] Write Protect is off
sd 0:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO
or FUA
sda: sda1 sda2 sda3 sda4 < sda5 sda6 >
sd 0:0:0:0: [sda] Attached SCSI disk
(3)play with the disk according to the following log.
[root@ls1046 root]# fdisk -l /dev/sda
Disk /dev/sda: 160.0 GB, 160041885696 bytes
255 heads, 63 sectors/track, 19457 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Device Boot Start End Blocks Id System
/dev/sda1 1 237 1903671 83 Linux
/dev/sda2 238 480 1951897+ 82 Linux swap
/dev/sda3 481 9852 75280590 83 Linux
/dev/sda4 9853 19457 77152162+ f Win95 Ext'd (LBA)
/dev/sda5 9853 14655 38580066 83 Linux
/dev/sda6 14656 19457 38572033+ 83 Linux
[root@ls1046 root]#
[root@ls1046 root]# mke2fs /dev/sda1
mke2fs 1.41.4 (27-Jan-2009)
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
65280 inodes, 261048 blocks
13052 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=268435456
8 block groups
32768 blocks per group, 32768 fragments per group
8160 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
This filesystem will be automatically checked every 22 mounts or
180 days, whichever comes first. Use tune2fs -c or -i to override.
[root@ls1046 root]#
[root@ls1046 root]# mkdir sata
[root@ls1046 root]# mount /dev/sda1 sata
[root@ls1046 root]# ls sata/
lost+found
[root@ls1046 root]# cp /bin/busybox sata/
[root@ls1046 root]# umount sata/
[root@ls1046 root]# mount /dev/sda1 sata/
[root@ls1046 root]# ls sata/
busybox lost+found
[root@ls1046 root]# umount sata/
[root@ls1046 root]# mount /dev/sda3 /mnt
[root@ls1046 root]# df
Filesystem 1K-blocks Used Available Use% Mounted on
rootfs 852019676 794801552 13937948 99% /
/dev/root 852019676 794801552 13937948 99% /
tmpfs 1036480 52 1036428 1% /dev
shm 1036480 0 1036480 0% /dev/shm
/dev/sda3 74098076 4033092 66300956 6% /mnt
Device Drivers
Known Bugs, Limitations, or Technical Issues
• CDROM is not supported due to the silicon limitation
4.2.9
Security Engine (SEC)
SEC Device Drivers
Introduction and Terminology
The Linux kernel contains a Scatterlist Crypto API driver for the NXP SEC v4.x, v5.x security hardware blocks.
It integrates seamlessly with in-kernel crypto users, such as IPsec, in a way that any IPsec suite that configures IPsec tunnels
with the kernel will automatically use the hardware to do the crypto.
SEC v5.x is backward compatible with SEC v4.x hardware, so one can assume that subsequent SEC v4.x references include
SEC v5.x hardware, unless explicitly mentioned otherwise.
SEC v4.x hardware is known in Linux kernel as 'caam', after its internal block name: Cryptographic Accelerator and Assurance
Module.
There are several HW interfaces ("backends") that can be used to communicate (i.e. submit requests) with the engine, their
availability depends on the SoC:
• Register Interface (RI) - available on all SoCs (though access from kernel is restricted on DPAA2 SoCs)
Its main purpose is debugging (for e.g. single-stepping through descriptor commands), though it is used also for RNG
initialization.
• Job Ring Interface (JRI) - legacy interface, available on all SoCs; on most SoCs there are 4 rings
Note: there are cases when fewer rings are accessible / visible in the kernel - for e.g. when firmware like Primary
Protected Application (PPA) reserves one of the rings.
• Queue Interface (QI) - available on SoCs implementing DPAA v1.x (Data Path Acceleration Architecture)
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
63
Page 64
Linux kernel
Requests are submitted indirectly via Queue Manager (QMan) HW block that is part of DPAA1.
• Data Path SEC Interface (DPSECI) - available on SoCs implementing DPAA v2.x
Similar to QI, requests are submitted via Queue Manager (QMan) HW block; however, the architecture is different instead of using the platform bus, the Management Complex (MC) bus is used, MC firmware performing needed
configuration to link DP* objects - see DPAA2 Linux Software chapter for more details.
NXP provides device drivers for all these interfaces. Current chapter is focused on JRI, though some general / common topics
are also covered. For QI and DPSECI backends and compatible frontends, please refer to the dedicated chapters: for DPAA1,
Security Engine for DPAA2.
On top of these backends, there are the "frontends" - drivers that sit between the Linux Crypto API and backend drivers. Their
main tasks are to:
• register supported crypto algorithms
• process crypto requests coming from users (via the Linux Crypto API) and translate them into the proper format understood
by the backend being used
• forward the CAAM engine responses from the backend being used to the users
Note: It is obvious that QI and DPSECI backends cannot co-exist (they can be compiled in the same "multi-platform" kernel image,
however run-time detection will make sure only the proper one is active). However, JRI + QI and JRI + DPSECI are valid
combinations, and both backends will be active if enabled; if a crypto algorithm is supported by both corresponding frontends (for
e.g. both caamalg and caamalg_qi register cbc(aes)), a user requesting cbc(aes) will be bound to the implementation having the
highest "crypto algorithm priority". If the user wants to use a specific implementation:
• it is possible to ask for it explicitly by using the specifc (unique) "driver name" instead of the generic "algorithm name" - please
see official Linux kernel Crypto API documentation (section Crypto API Cipher References And Priority); currently default
priorities are: 3000 for JRI frontend and 2000 for QI and DPSECI frontends
• crypto algorithm priority could be changed dynamically using the "Crypto use configuration API" (provided that
CONFIG_CRYPTO_USER is enabled); one of the tools available that is capable to do this is "Linux crypto layer configuration
tool" and an example of increasing the priority of QI frontend based implementation of
echainiv(authenc(hmac(sha1),cbc(aes))) algorithm is:
$ ./crconf update driver "echainiv-authenc-hmac-sha1-cbc-aes-caam-qi" type 3 priority 5000
Figure 3. Linux kernel - SEC device drivers overview
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
64
NXP Semiconductors
Page 65
Device Drivers
Source Files
The drivers source code is maintained in the Linux kernel source tree, under drivers/crypto/caam. Below is a non-exhaustive list
of files, mapping to Security Engine (SEC)(some files have been omitted since their existence is justified only by driver logic /
design):
Source File(s)DescriptionModule name
ctrl.[c,h]Init (global settings, RNG, power
caam
management etc.)
desc.hHW description (CCSR registers etc.)N/A
desc_constr.hInline append - descriptor construction
CAAM device drivers can be compiled either built-in or as modules (with the exception of DPSECI backend, which is always builtin). See section Source Files on page 65 for the list of module names and section Kernel Configuration on page 65 for how
kernel configuration looks like and a mapping between menu entries and modules and / or functionalities enabled.
Kernel Configuration
CAAM device drivers are located in the "Cryptographic API" -> "Hardware crypto devices" sub-menu in the kernel configuration.
Depending on the target platform and / or configuration file(s) used, the output will be different; below is an example taken from
NXP Layerscape SDK for ARMv8 platforms with default options:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
Enable CAAM device drivers, options:
• basic platform driver: Freescale CAAM-Multicore platformdriver backend (SEC); all non-DPAA2 sub-options depend on
it
Table continues on the next page...
65
Page 66
Linux kernel
Table continued from the previous page...
Kernel Configure Tree View OptionsDescription
driver
<*> Freescale CAAM Job Ring driver
backend (SEC)
(9) Job Ring size
[ ] Job Ring interrupt coalescing
<*> Register algorithm
implementations with the Crypto API
<*> Queue Interface as Crypto API
backend
<*> Register hash algorithm
implementations with Crypto API
<*> Register public key
cryptography implementations with Crypto API
<*> Register caam device for
hwrng API
<M> QorIQ DPAA2 CAAM (DPSECI) driver
See linux/Documentation/devicetree/bindings/crypto/fsl-sec4.txt file in the Linux kernel tree for more info.
How to test the drivers
To test the drivers, under the "Cryptographic API -> Cryptographic algorithm manager" kernel configuration sub-menu,
ensure that run-time self tests are not disabled, i.e. the "Disable run-time self tests" entry is not set
(CONFIG_CRYPTO_MANAGER_DISABLE_TESTS=n). This will run standard test vectors against the drivers after they register
supported algorithms with the kernel crypto API, usually at boot time. Then run test on the target system. Below is a snippet
extracted from the boot log of ARMv8-based LS1046A platform, with JRI and QI enabled:
[...]
platform caam_qi: Linux CAAM Queue I/F driver initialised
caam 1700000.crypto: Instantiated RNG4 SH1
caam 1700000.crypto: device ID = 0x0a11030100000000 (Era 8)
caam 1700000.crypto: job rings = 4, qi = 1, dpaa2 = no
alg: No test for authenc(hmac(sha224),ecb(cipher_null)) (authenc-hmac-sha224-ecb-cipher_null-caam)
alg: No test for authenc(hmac(sha256),ecb(cipher_null)) (authenc-hmac-sha256-ecb-cipher_null-caam)
alg: No test for authenc(hmac(sha384),ecb(cipher_null)) (authenc-hmac-sha384-ecb-cipher_null-caam)
alg: No test for authenc(hmac(sha512),ecb(cipher_null)) (authenc-hmac-sha512-ecb-cipher_null-caam)
alg: No test for authenc(hmac(md5),cbc(aes)) (authenc-hmac-md5-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(md5),cbc(aes))) (echainiv-authenc-hmac-md5-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha1),cbc(aes))) (echainiv-authenc-hmac-sha1-cbc-aes-caam)
alg: No test for authenc(hmac(sha224),cbc(aes)) (authenc-hmac-sha224-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha224),cbc(aes))) (echainiv-authenc-hmac-sha224-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha256),cbc(aes))) (echainiv-authenc-hmac-sha256-cbc-aes-caam)
alg: No test for authenc(hmac(sha384),cbc(aes)) (authenc-hmac-sha384-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha384),cbc(aes))) (echainiv-authenc-hmac-sha384-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha512),cbc(aes))) (echainiv-authenc-hmac-sha512-cbc-aes-caam)
alg: No test for authenc(hmac(md5),cbc(des3_ede)) (authenc-hmac-md5-cbc-des3_ede-caam)
alg: No test for echainiv(authenc(hmac(md5),cbc(des3_ede))) (echainiv-authenc-hmac-md5-cbc-des3_edecaam)
alg: No test for echainiv(authenc(hmac(sha1),cbc(des3_ede))) (echainiv-authenc-hmac-sha1-cbc-des3_edecaam)
alg: No test for echainiv(authenc(hmac(sha224),cbc(des3_ede))) (echainiv-authenc-hmac-sha224-cbcdes3_ede-caam)
alg: No test for echainiv(authenc(hmac(sha256),cbc(des3_ede))) (echainiv-authenc-hmac-sha256-cbcdes3_ede-caam)
alg: No test for echainiv(authenc(hmac(sha384),cbc(des3_ede))) (echainiv-authenc-hmac-sha384-cbcdes3_ede-caam)
alg: No test for echainiv(authenc(hmac(sha512),cbc(des3_ede))) (echainiv-authenc-hmac-sha512-cbcdes3_ede-caam)
alg: No test for authenc(hmac(md5),cbc(des)) (authenc-hmac-md5-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(md5),cbc(des))) (echainiv-authenc-hmac-md5-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(sha1),cbc(des))) (echainiv-authenc-hmac-sha1-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(sha224),cbc(des))) (echainiv-authenc-hmac-sha224-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(sha256),cbc(des))) (echainiv-authenc-hmac-sha256-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(sha384),cbc(des))) (echainiv-authenc-hmac-sha384-cbc-des-caam)
alg: No test for echainiv(authenc(hmac(sha512),cbc(des))) (echainiv-authenc-hmac-sha512-cbc-des-caam)
alg: No test for authenc(hmac(md5),rfc3686(ctr(aes))) (authenc-hmac-md5-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(md5),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-md5-rfc3686-ctr-aescaam)
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
67
Page 68
Linux kernel
alg: No test for authenc(hmac(sha1),rfc3686(ctr(aes))) (authenc-hmac-sha1-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha1),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha1-rfc3686-ctraes-caam)
alg: No test for authenc(hmac(sha224),rfc3686(ctr(aes))) (authenc-hmac-sha224-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha224),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha224-rfc3686ctr-aes-caam)
alg: No test for authenc(hmac(sha256),rfc3686(ctr(aes))) (authenc-hmac-sha256-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha256),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha256-rfc3686ctr-aes-caam)
alg: No test for authenc(hmac(sha384),rfc3686(ctr(aes))) (authenc-hmac-sha384-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha384),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha384-rfc3686ctr-aes-caam)
alg: No test for authenc(hmac(sha512),rfc3686(ctr(aes))) (authenc-hmac-sha512-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha512),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha512-rfc3686ctr-aes-caam)
caam algorithms registered in /proc/crypto
alg: No test for authenc(hmac(md5),cbc(aes)) (authenc-hmac-md5-cbc-aes-caam-qi)
alg: No test for echainiv(authenc(hmac(md5),cbc(aes))) (echainiv-authenc-hmac-md5-cbc-aes-caam-qi)
alg: No test for echainiv(authenc(hmac(sha1),cbc(aes))) (echainiv-authenc-hmac-sha1-cbc-aes-caam-qi)
alg: No test for authenc(hmac(sha224),cbc(aes)) (authenc-hmac-sha224-cbc-aes-caam-qi)
alg: No test for echainiv(authenc(hmac(sha224),cbc(aes))) (echainiv-authenc-hmac-sha224-cbc-aes-caamqi)
alg: No test for echainiv(authenc(hmac(sha256),cbc(aes))) (echainiv-authenc-hmac-sha256-cbc-aes-caamqi)
alg: No test for authenc(hmac(sha384),cbc(aes)) (authenc-hmac-sha384-cbc-aes-caam-qi)
alg: No test for echainiv(authenc(hmac(sha384),cbc(aes))) (echainiv-authenc-hmac-sha384-cbc-aes-caamqi)
alg: No test for echainiv(authenc(hmac(sha512),cbc(aes))) (echainiv-authenc-hmac-sha512-cbc-aes-caamqi)
alg: No test for authenc(hmac(md5),cbc(des3_ede)) (authenc-hmac-md5-cbc-des3_ede-caam-qi)
alg: No test for echainiv(authenc(hmac(md5),cbc(des3_ede))) (echainiv-authenc-hmac-md5-cbc-des3_edecaam-qi)
alg: No test for echainiv(authenc(hmac(sha1),cbc(des3_ede))) (echainiv-authenc-hmac-sha1-cbc-des3_edecaam-qi)
alg: No test for echainiv(authenc(hmac(sha224),cbc(des3_ede))) (echainiv-authenc-hmac-sha224-cbcdes3_ede-caam-qi)
alg: No test for echainiv(authenc(hmac(sha256),cbc(des3_ede))) (echainiv-authenc-hmac-sha256-cbcdes3_ede-caam-qi)
alg: No test for echainiv(authenc(hmac(sha384),cbc(des3_ede))) (echainiv-authenc-hmac-sha384-cbcdes3_ede-caam-qi)
alg: No test for echainiv(authenc(hmac(sha512),cbc(des3_ede))) (echainiv-authenc-hmac-sha512-cbcdes3_ede-caam-qi)
alg: No test for authenc(hmac(md5),cbc(des)) (authenc-hmac-md5-cbc-des-caam-qi)
alg: No test for echainiv(authenc(hmac(md5),cbc(des))) (echainiv-authenc-hmac-md5-cbc-des-caam-qi)
alg: No test for echainiv(authenc(hmac(sha1),cbc(des))) (echainiv-authenc-hmac-sha1-cbc-des-caam-qi)
alg: No test for echainiv(authenc(hmac(sha224),cbc(des))) (echainiv-authenc-hmac-sha224-cbc-des-caamqi)
alg: No test for echainiv(authenc(hmac(sha256),cbc(des))) (echainiv-authenc-hmac-sha256-cbc-desi-caamqi)
alg: No test for echainiv(authenc(hmac(sha384),cbc(des))) (echainiv-authenc-hmac-sha384-cbc-des-caamqi)
alg: No test for echainiv(authenc(hmac(sha512),cbc(des))) (echainiv-authenc-hmac-sha512-cbc-des-caamqi)
platform caam_qi: algorithms registered in /proc/crypto
caam_jr 1710000.jr: registering rng-caam
caam 1700000.crypto: caam pkc algorithms registered in /proc/crypto
[...]
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
68
NXP Semiconductors
Page 69
Device Drivers
Crypto algorithms support
Algorithms Supported in the linux kernel scatterlist Crypto API
The Linux kernel contains various users of the Scatterlist Crypto API, including its IPsec implementation, sometimes referred to
as the NETKEY stack. The driver, after registering supported algorithms with the Crypto API, is therefore used to process perpacket symmetric crypto requests and forward them to the SEC hardware.
Since SEC hardware processes requests asynchronously, the driver registers asynchronous algorithm implementations with the
crypto API: ahash, ablkcipher, and aead with CRYPTO_ALG_ASYNC set in .cra_flags.
Different combinations of hardware and driver software version support different sets of algorithms, so searching for the driver
name in /proc/crypto on the desired target system will ensure the correct report of what algorithms are supported.
Authenticated Encryption with Associated Data (AEAD) algorithms
These algorithms are used in applications where the data to be encrypted overlaps, or partially overlaps, the data to be
authenticated, as is the case with IPsec and TLS protocols. These algorithms are implemented in the driver such that the hardware
makes a single pass over the input data, and both encryption and authentication data are written out simultaneously. The AEAD
algorithms are mainly for use with IPsec ESP (however there is also support for TLS 1.0 record layer encryption).
CAAM drivers currently supports offloading the following AEAD algorithms:
• "stitched" AEAD: all combinations of { NULL, CBC-AES, CBC-DES, CBC-3DES-EDE, RFC3686-CTR-AES } x HMAC-{MD-5,
SHA-1,-224,-256,-384,-512}
• "true" AEAD: generic GCM-AES, GCM-AES used in IPsec: RFC4543-GCM-AES and RFC4106-GCM-AES
• TLS 1.0 record layer encryption using the "stitched" AEAD cipher suite CBC-AES-HMAC-SHA1
Encryption algorithms
The CAAM driver currently supports offloading the following encryption algorithms.
Authentication algorithms
The CAAM driver's ahash support includes keyed (hmac) and unkeyed hashing algorithms.
Asymmetric (public key) algorithms
Currently, RSA is the only public key algorithm supported.
Random Number Generation
caamrng frontend driver supports random number generation services via the kernel's built-in hwrng interface when implemented
in hardware. To enable:
1. verify that the hardware random device file, e.g., /dev/hwrng or /dev/hwrandom exists. If it doesn't exist, make it with:
$ mknod /dev/hwrng c 10 183
2. verify /dev/hwrng doesn't block indefinitely and produces random data:
$ rngtest -C 1000 < /dev/hwrng
3. verify the kernel gets entropy:
$ rngtest -C 1000 < /dev/random
If it blocks, a kernel entropy supplier daemon, such as rngd, may need to be run. See linux/Documentation/hw_random.txt for
more info.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
69
Page 70
Linux kernel
Table 10. Algorithms supported by each interface / backend
Algorithm name / BackendJob Ring InterfaceQueue InterfaceDPSEC Interface
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
70
NXP Semiconductors
Page 71
Table 10. Algorithms supported by each interface / backend (continued)
Algorithm name / BackendJob Ring InterfaceQueue InterfaceDPSEC Interface
Device Drivers
authenc(hmac(md5),rfc3686(
ctr(aes)))
authenc(hmac(sha1),rfc3686(
ctr(aes)))
authenc(hmac(sha224),rfc36
86(ctr(aes)))
authenc(hmac(sha256),rfc36
86(ctr(aes)))
authenc(hmac(sha384),rfc36
86(ctr(aes)))
authenc(hmac(sha512),rfc36
86(ctr(aes)))
authenc(hmac(md5),ecb(ciph
er_null))
authenc(hmac(sha1),ecb(ciph
er_null))
authenc(hmac(sha224),ecb(ci
pher_null))
authenc(hmac(sha256),ecb(ci
pher_null))
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
Yes (also seqiv)Yes (also seqiv)Yes (also seqiv)
YesNoNo
YesNoNo
YesNoNo
YesNoNo
authenc(hmac(sha384),ecb(ci
YesNoNo
pher_null))
authenc(hmac(sha512),ecb(ci
YesNoNo
pher_null))
gcm(aes)YesYesYes
rfc4543(gcm(aes))YesYesYes
rfc4106(gcm(aes))YesYesYes
cbc(aes)YesYesYes
cbc(des3_ede)YesYesYes
cbc(des)YesYesYes
ctr(aes)YesYesYes
rfc3686(ctr(aes))YesYesYes
xts(aes)YesYesYes
hmac(md5)YesNoYes
hmac(sha1)YesNoYes
hmac(sha224)YesNoYes
hmac(sha256)YesNoYes
Table continues on the next page...
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
71
Page 72
Linux kernel
Table 10. Algorithms supported by each interface / backend (continued)
Algorithm name / BackendJob Ring InterfaceQueue InterfaceDPSEC Interface
hmac(sha384)YesNoYes
hmac(sha512)YesNoYes
md5YesNoYes
sha1YesNoYes
sha224YesNoYes
sha256YesNoYes
sha384YesNoYes
sha512YesNoYes
CAAM Job Ring backend driver specifics
CAAM Job Ring backend driver (caam_jr) implements and utilizes the job ring interface (JRI) for submitting crypto API service
requests from the frontend drivers (caamalg, caamhash, caam_pkc, caamrng) to CAAM engine.
CAAM drivers have a few options, most notably hardware job ring size and interrupt coalescing. They can be used to fine-tune
performance for a particular use case.
The option Freescale CAAM-Multicore platform driver backend enables the basic platform driver (caam). All (non-DPAA2) suboptions depend on this.
The option Freescale CAAM Job Ring driver backend (SEC) enables the Job Ring backend (caam_jr).
The sub-option Job Ring Size allows the user to select the size of the hardware job rings; if requests arrive at the driver enqueue
entry point in a bursty nature, the bursts' maximum length can be approximated etc. One can set the greatest burst length to save
performance and memory consumption.
The sub-option Job Ring interrupt coalescing allows the user to select the use of the hardware’s interrupt coalescing feature.
Note that the driver already performs IRQ coalescing in software, and zero-loss benchmarks have in fact produced better results
with this option turned off. If selected, two additional options become effective:
• Job Ring interrupt coalescing count threshold (CRYPTO_DEV_FSL_CAAM_INTC_THLD)
Selects the value of the descriptor completion threshold, in the range 1-256. A selection of 1 effectively defeats the coalescing
feature, and any selection equal or greater than the selected ring size will force timeouts for each interrupt.
• Job Ring interrupt coalescing timer threshold (CRYPTO_DEV_FSL_CAAM_INTC_TIME_THLD)
Selects the value of the completion timeout threshold in multiples of 64 SEC interface clocks, to which, if no new descriptor
completions occur within this window (and at least one completed job is pending), then an interrupt will occur. This is selectable
in the range 1-65535.
The options to register to Crypto API, hwrng API respectively, allow the frontend drivers to register their algorithm capabilities with
the corresponding APIs. They should be deselected only when the purpose is to perform Crypto API requests in software (on the
GPPs) instead of offloading them on SEC engine.
caamhash frontend (hash algorithms) may be individually turned off, since the nature of the application may be such that it prefers
software (core) crypto latency due to many small-sized requests.
caam_pkc frontend (public key / asymmetric algorithms) can be turned off too, if needed.
caamrng frontend (Random Number Generation) may be turned off in case there is an alternate source of entropy available to
the kernel.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
72
NXP Semiconductors
Page 73
Device Drivers
Verifying driver operation and correctness
Other than noting the performance advantages due to the crypto offload, one can also ensure the hardware is doing the crypto
by looking for driver messages in dmesg.
The driver emits console messages at initialization time:
caam algorithms registered in /proc/crypto
caam_jr 1710000.jr: registering rng-caam
caam 1700000.crypto: caam pkc algorithms registered in /proc/crypto
If the messages are not present in the logs, either the driver is not configured in the kernel, or no SEC compatible device tree
node is present in the device tree.
Incrementing IRQs in /proc/interrupts
Given a time period when crypto requests are being made, the SEC hardware will fire completion notification interrupts on the
corresponding Job Ring:
If the number of interrupts fired increment, then the hardware is being used to do the crypto.
If the numbers do not increment, then first check the algorithm being exercised is supported by the driver. If the algorithm is
supported, there is a possibility that the driver is in polling mode (NAPI mechanism) and the hardware statistics in debugfs
(inbound / outbound bytes encrypted / protected - see below) should be monitored.
Verifying the 'self test' fields say 'passed' in /proc/crypto
An entry such as the one below means the driver has successfully registered support for the algorithm with the kernel crypto API:
name : cbc(aes)
driver : cbc-aes-caam
module : kernel
priority : 3000
refcnt : 1
selftest : passed
internal : no
type : givcipher
async : yes
blocksize : 16
min keysize : 16
max keysize : 32
ivsize : 16
geniv : <built-in>
Note that although a test vector may not exist for a particular algorithm supported by the driver, the kernel will emit messages
saying which algorithms weren't tested, and mark them as 'passed' anyway:
[...]
alg: No test for authenc(hmac(sha224),ecb(cipher_null)) (authenc-hmac-sha224-ecb-cipher_null-caam)
alg: No test for authenc(hmac(sha256),ecb(cipher_null)) (authenc-hmac-sha256-ecb-cipher_null-caam)
[...]
alg: No test for authenc(hmac(md5),cbc(aes)) (authenc-hmac-md5-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(md5),cbc(aes))) (echainiv-authenc-hmac-md5-cbc-aes-caam)
alg: No test for echainiv(authenc(hmac(sha1),cbc(aes))) (echainiv-authenc-hmac-sha1-cbc-aes-caam)
[...]
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
73
Page 74
Linux kernel
alg: No test for authenc(hmac(sha512),rfc3686(ctr(aes))) (authenc-hmac-sha512-rfc3686-ctr-aes-caam)
alg: No test for seqiv(authenc(hmac(sha512),rfc3686(ctr(aes)))) (seqiv-authenc-hmac-sha512-rfc3686-ctraes-caam)
[...]
Examining the hardware statistics registers in debugfs
When using the JRI or QI backend, performance monitor registers can be checked, provided CONFIG_DEBUG_FS is enabled
in the kernel’s configuration. If debugfs is not automatically mounted at boot time, then a manual mount must be performed in
order to view these registers. This normally can be done with a superuser shell command:
$ mount -t debugfs none /sys/kernel/debug
Once done, the user can read controller registers in /sys/kernel/debug/1700000.crypto/ctl. It should be noted that debugfs will
provide a decimal integer view of most accessible registers provided, with the exception of the KEK/TDSK/TKEK registers; those
registers are long binary arrays, and should be filtered through a binary dump utility such as hexdump.
Specifically, the CAAM hardware statistics registers available are:
fault_addr, or FAR (Fault Address Register): - holds the value of the physical address where a read or write error occurred.
fault_detail, or FADR (Fault Address Detail Register): - holds details regarding the bus transaction where the error occurred.
fault_status, or CSTA (CAAM Status Register): - holds status information relevant to the entire CAAM block.
For more information see section "Performance Counter, Fault and Version ID Registers" in the Security (SEC) Reference Manual
(SECRM) of each SoC (available on company's website).
Note: for QI backend there is also qi_congested: SW-based counter that shows how many times queues going to / from CAAM
to QMan hit the congestion threshold.
Kernel configuration to support CAAM device drivers
Using the driver
Once enabled, the driver will forward kernel crypto API requests to the SEC hardware for processing.
Running IPsec
The IPsec stack built-in to the kernel (usually called NETKEY) will automatically use crypto drivers to offload crypto operations to
the SEC hardware. Documentation regarding how to set up an IPsec tunnel can be found in corresponding open source IPsec
suite packages, e.g. strongswan.org, openswan, setkey, etc. DPAA2-specific section contains a generic helper script to configure
IPsec tunnels.
Running OpenSSL
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
74
NXP Semiconductors
Page 75
Device Drivers
Please see Hardware Offloading with OpenSSL for more details on how to offload OpenSSL cryptographic operations in the
SEC crypto engine (via cryptodev).
Executing custom descriptors
SEC drivers have public descriptor submission interfaces corresponding to the following backends:
dev: contains the job ring device that is to process this request.
desc: descriptor that initiated the request, same as “desc” being argued to caam_jr_enqueue.
cbk: pointer to a callback function to be invoked upon completion of this request. This has the form: callback(struct device *dev,
u32 *desc, u32 stat, void *arg)
areq: optional pointer to a user argument for use at callback time.
caam_qi_enqueue()
Name
caam_qi_enqueue — Enqueue a frame descriptor (FD) into a QMan frame queue. Returns 0 if OK, -EIO if it cannot map the
caller's S/G array, -EBUSY if QMan driver fails to enqueue the FD for some reason.
Synopsis
int caam_qi_enqueue(struct device *qidev, struct caam_drv_req *req);
Arguments
qidev: contains the queue interface device that is to process this request.
req: pointer to the request structure the driver application should fill while submitting a job to driver, containing a callback function
and its parameter, Queue Manager S/Gs for input and output, a per-context structure containing the CAAM shared descriptor etc.
dpaa2_caam_enqueue()
Name
dpaa2_caam_enqueue — Enqueue a frame descriptor (FD) into a QMan frame queue. Returns 0 if OK, -EBUSY if QMan driver
fails to enqueue the FD for some reason or if congestion is detected.
Synopsis
int dpaa2_caam_enqueue(struct device *dev, struct caam_request *req);
Arguments
dev: DPSECI device.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
75
Page 76
Linux kernel
req: pointer to the request structure the driver application should fill while submitting a job to driver, containing a callback function
and its parameter, Queue Manager S/Gs for input and output, a per-context structure containing the CAAM shared descriptor etc.
Please refer to the source code for usage examples.
Supporting Documentation
DPAA1-specific SEC details - Queue Interface (QI)
DPAA2-specific SEC details - Data Path SEC Interface (DPSECI)
4.2.10 Universal Serial Bus Interfaces
4.2.10.1 USB 3.0 Host/Peripheral Linux Driver User Manual
Description
The driver supports xHCI SuperSpeed (SS) Dual-Role-Device (DRD) controller
Main features of xHCI controller
• Supports operation as a standalone USB xHCI host controller
• USB dual-role operation and can be configured as host or device
• Supports operation as a standalone single port USB
• Supports eight programmable, bidirectional USB endpoints
Modes of Operation
• Host Mode: SS/HS/FS/LS
• Device Mode: SS/HS/FS
NOTE
Super-speed operation is not supported when OTG is enabled
NOTE
This document explains working of HS Host and HS Device in Linux
Module Loading
The default kernel configuration enables support for USB_DWC3 as built-in kernel module.
Kernel Configure Tree View Options
Kernel Configure Tree View OptionsDescription
Enables USB host controller support
Device Drivers--->
USB support --->
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
76
Table continues on the next page...
NXP Semiconductors
Page 77
Table continued from the previous page...
Kernel Configure Tree View OptionsDescription
[*] Support for Host-side USB
Enables XHCI Host Controller Driver and transaction
Device Drivers--->
USB support --->
<*> xHCI HCD (USB 3.0) support
translator
Device Drivers
Device Drivers--->
USB support --->
<*> USB Mass Storage support
[ ] USB Mass Storage verbose debug
<*> Sound card support --->
<*> Advanced Linux Sound Architecture --->
<*> OSS Mixer API
<*> OSS PCM (digital audio) API
[*] OSS PCM (digital audio) API Include plugin system
[*] Support old ALSA API
[*] USB sound devices --->
<*> USB Audio/MIDI driver
Device Drivers--->
USB support --->
<*> USB Gadget Support --->
<M> USB Gadget Drivers
< > USB functions configurable through
configfs
< > Gadget Zero (DEVELOPMENT)
<M> Ethernet Gadget (with CDC Ethernet
support)
[*] RNDIS support
[ ] Ethernet Emulation Model (EEM)
support
< > Network Control Model (NCM) support
< > Gadget Filesystem
< > Function Filesystem
<M> Mass Storage Gadget
< > Serial Gadget (with CDC ACM and CDC
OBEX support)
Enable support for USB mass storage devices. This is the
driver needed for USB flash devices, and memory sticks
Enables support for USB Audio devices. This driver is needed
for USB microphone.
Note: Required only for USB Gadget/Peripheral Support
• Enable driver for peripheral/device controller
• Enable Ethernet Gadget Client driver
• Enable Mass Storage Client driver
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
Table continues on the next page...
77
Page 78
Linux kernel
Table continued from the previous page...
Kernel Configure Tree View OptionsDescription
Device Drivers--->
<*> DesignWare USB3 DRD Core Support
DWC3 Mode Selection (Dual Role mode)
--->
Enable XHCI DRD Core Support
Compile-time Configuration Options
OptionValuesDefault ValueDescription
CONFIG_USBy/m/nyEnables USB host
controller
CONFIG_USB_XHCI_
y/m/nyEnables XHCI HCD
HCD
CONFIG_USB_DWC3y/m/nyEnables DWC3
Controller
CONFIG_USB_GADGETy/m/nnEnables USB
peripheral device
CONFIG_USB_ETHy/m/nnEnable Ethernet style
communication
CONFIG_USB_MASS_
STORAGE
m/nnEnable USB Mass
Storage disk drive
CONFIG_SOUNDy/m/nyEnables Sound Card
Support
CONFIG_SNDy/m/nyEnables ALSA
(Advanced Linux
Sound Architecture)
CONFIG_SND_MIXER
_OSS
CONFIG_SND_PCM_
OSS
y/m/nyEnables OSS Mixer
API
y/m/nyEnables OSS PCM
(digital audio) API
CONFIG_SND_PCM_
y/nyEnables OSS PCM
OSS_PLUGINS
CONFIG_SND_SUPP
y/nyEnables old ALSA API
ORT_OLD_API
CONFIG_SND_USBy/nnEnables USB sound
CONFIG_SND_USB_A
y/m/nnEnables USB Audio/
UDIO
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
78
(digital audio) API Include plugin system
devices
MIDI driver
NXP Semiconductors
Page 79
NOTE: USB Audio configuration options default value is listed for LS1021A platform.
Source Files
The driver source is maintained in the Linux kernel source tree in below files
Following are serial console logs that appear during bootup if dr_mode set to host in device-tree
usbcore: registered new interface driver usbfs
usbcore: registered new interface driver hub
usbcore: registered new device driver usb
xhci-hcd xhci-hcd.0.auto: xHCI Host Controller
xhci-hcd xhci-hcd.0.auto: new USB bus registered, assigned bus number 1
xhci-hcd xhci-hcd.0.auto: irq 125, io mem 0x03100000
hub 1-0:1.0: USB hub found
hub 1-0:1.0: 1 port detected
xhci-hcd xhci-hcd.0.auto: xHCI Host Controller
xhci-hcd xhci-hcd.0.auto: new USB bus registered, assigned bus number 2
hub 2-0:1.0: USB hub found
hub 2-0:1.0: 1 port detected
usbcore: registered new interface driver usb-storage
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
79
Page 80
Linux kernel
Following are serial-console logs after connecting a USB flash drive
For High-Speed Device attach
usb 1-1.2: new high-speed USB device number 3 using xhci-hcd
usb-storage 1-1.2:1.0: USB Mass Storage device detected
scsi0 : usb-storage 1-1.2:1.0
scsi 0:0:0:0: Direct-Access SanDisk Cruzer 7.01 PQ: 0 ANSI: 0 CCS
sd 0:0:0:0: [sda] 1957887 512-byte logical blocks: (1.00 GB/955 MiB)
sd 0:0:0:0: Attached scsi generic sg0 type 0
sd 0:0:0:0: [sda] Write Protect is off
sd 0:0:0:0: [sda] No Caching mode page found
sd 0:0:0:0: [sda] Assuming drive cache: write through
sd 0:0:0:0: [sda] No Caching mode page found
sd 0:0:0:0: [sda] Assuming drive cache: write through
sda: sda1
sd 0:0:0:0: [sda] No Caching mode page found
sd 0:0:0:0: [sda] Assuming drive cache: write through
sd 0:0:0:0: [sda] Attached SCSI removable disk
For Super-Speed Device attach
# usb 2-1: new SuperSpeed USB device number 2 using xhci-hcd
usb 2-1: Parent hub missing LPM exit latency info. Power management will be impacted.
usb-storage 2-1:1.0: USB Mass Storage device detected
scsi0 : usb-storage 2-1:1.0
scsi 0:0:0:0: Direct-Access SanDisk Extreme 0001 PQ: 0 ANSI: 6
sd 0:0:0:0: [sda] 31277232 512-byte logical blocks: (16.0 GB/14.9 GiB)
sd 0:0:0:0: Attached scsi generic sg0 type 0
sd 0:0:0:0: [sda] Write Protect is off
sd 0:0:0:0: [sda] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
sda:
sd 0:0:0:0: [sda] Attached SCSI removable disk
FAT-fs (sda): Volume was not properly unmounted. Some data may be corrupt. Please run fsck.
Make filesystem and mount connected USB flash drive using below commands
root@freescale /$ fdisk -l
Disk /dev/sda: 16.0 GB, 16013942784 bytes
255 heads, 63 sectors/track, 1946 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Device Boot Start End Blocks Id System
/dev/sda1 1 1946 15631213+ 83 Linux
root@freescale /$
root@freescale /$ df
Filesystem 1K-blocks Used Available Use% Mounted on
shm 516684 0 516684 0% /dev/shm
rwfs 512 0 512 0% /mnt/rwfs
root@freescale /$
root@freescale /$
root@freescale /$
root@freescale /$
root@freescale /$ fdisk /dev/sda
The number of cylinders for this disk is set to 1946.
There is nothing wrong with that, but this is larger than 1024,
and could in certain setups cause problems with:
1) software that runs at boot time (e.g., old versions of LILO)
2) booting and partitioning software from other OSs
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
80
NXP Semiconductors
Page 81
(e.g., DOS FDISK, OS/2 FDISK)
Command (m for help): d
Selected partition 1
Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-1946, default 1): Using default value 1
Last cylinder or +size or +sizeM or +sizeK (1-1946, default 1946): Using default value 1946
Command (m for help): w
The partition table has been alter sda: sda1
ed!
[ 39.987594] g_mass_storage gadget: Mass Storage Function, version: 2009/09/11
[ 39.994822] g_mass_storage gadget: Number of LUNs=1
[ 39.989240] lun0: LUN: file: /home/backing_file_20mb
[ 39.994367] g_mass_storage gadget: Mass Storage Gadget, version: 2009/09/11
[ 39.990902] g_mass_storage gadget: userspace failed to provide iSerialNumber
[ 39.987547] g_mass_storage gadget: g_mass_storage ready
Attached ***USB3.0 only*** gadget cable to host and you will get below message. Now Storage is ready to use.
g_mass_storage gadget: super-speed config #1: Linux File-Backed Storage
Speaker and Microphone
Device Drivers
1. Aplay utility can be used to list the available sound cards e.g. Here Jabra 410 USB speaker is detected as a second sound
card and can be addressed as –D hw:1,0 OR –c1:
card 1: USB [Jabra SPEAK 410 USB], device 0: USB Audio [USB Audio] Subdevices: 1/1 Subdevice #0:
subdevice #0
2. Sample wav file can be played using the below command:
[root@freescale ~]$ aplay -D hw:1,0 LYNC_fsringing.wav
Playing WAVE 'LYNC_fsringing.wav' : Signed 16 bit Little Endian, Rate 48000 Hz, Stereo
3. Sample wav file can be recorded using the below command:
[root@freescale ~]$ arecord -f S16_LE -t wav -Dhw:1,0 -r 16000 foobar.wav -d 5
Recording WAVE 'foobar.wav' : Signed 16 bit Little Endian, Rate 16000 Hz, Mono
NOTE: If recorded audio is not played, try to use "-D plughw:1,0" in above command.
4. Audio controls can be checked using the below command, control details and name of the controls can be checked from
output of “amixer –c1” as below:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
84
NXP Semiconductors
Page 85
We will get below messages
[ 28.692611] using random self ethernet address
[ 28.697156] using random host ethernet address
[ 28.694271] usb0: HOST MAC 82:96:69:7e:a5:7d
[ 28.698928] usb0: MAC 72:00:a5:80:2b:e8
[ 28.692586] using random self ethernet address
[ 28.697080] using random host ethernet address
[ 28.691368] g_ether gadget: Ethernet Gadget, version: Memorial Day 2008
[ 28.698028] g_ether gadget: g_ether ready
Make sure USB0 ethernet interface is available after this
root@freescale /$ ifconfig -a
can0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
NOARP MTU:16 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:10
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
Interrupt:158
Attached the cable with Win7 and Configure RNDS interface in windows under "Control Panel -> Network and Internet -> Network
Connections" and set IP Address
Set IP Address in Platform and start Ping
root@freescale /$ ifconfig usb0 10.232.1.11
root@freescale /$
root@freescale /$
root@freescale /$ ping usb 10.232.1.10
PING 10.232.1.10 (10.232.1.10): 56 data bytes
64 bytes from 10.232.1.10: seq=0 ttl=128 time=5.294 ms
64 bytes from 10.232.1.10: seq=1 ttl=128 time=6.101 ms
64 bytes from 10.232.1.10: seq=2 ttl=128 time=4.170 ms
64 bytes from 10.232.1.10: seq=3 ttl=128 time=4.233 ms
Known Bugs, Limitations, or Technical Issues
• Linux only allows one peripheral at one time. Make sure that when one of DWC3 controller is set as peripheral, then the
others should not be set to the same mode.
• For USB host mode, some Pen drives such as Kingston / Transcend / SiliconPower / Samtec might have a compatibility
issue.
• Some USB micro ports might have a OTG3.0 cable compatibility issue. An OTG 2.0 cable and USB standard port will work
fine.
4.2.11
Watchdog
Module Loading
Watchdog device driver support kernel built-in mode.
U-Boot on all boards.
RGMII is only populated
on QDS though,
therefore, this interface
is not functional on
RDB.
0000:00:00.2
Connected internally
(MAC to MAC) to the
Ethernet switch.
This interface can be
used to access remote
hosts connected to
switch ports.
0000:00:00.6Connected internally
(MAC to MAC) to the
Ethernet switch. This
interface is present if bit
851 is set in RCW.
1G SWP0 to
1G SWP3
4 ports on QS(X)GMII
add-on card in slot 2.
N/A0000:00:00.5As of BSP0.3 switch
Note that SWP0 is top
port on QSGMII add-on
card and bottom port on
QSXGMII add-on card.
Interface naming in Linux
The following figure shows how Ethernet ports are presented in Linux.
ports can be used in UBoot both to access
remote hosts (through
enetc#2) and to switch
between external ports.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
89
Page 90
switch
swp3
swp0
swp1
swp2
swp4
swp5
eno2eno3
eno0
eno1
SGMII
x
QSGMII
RGMII
Linux kernel
Figure 5. Linux network interfaces on RDB
RDB portQDS portLinux netdevPCI functionComments
1G MAC1
N/AOn-board port
Internal
Top port with SGMII
add-on card in slot 1
Single port of SXGMII
add-on card in slot 1
Internal
eno0
eno1
eno2
Table continues on the next page...
0000:00:00.0
0000:00:00.1
0000:00:00.2Connected internally
RGMII interface is not
present on RDB board
and the associated
ENETC interface is
disabled in device tree:
&enetc_port1 {
status = "disabled";
};
On QDS this requires
an RCW that explicitly
enables RGMII (bits
833-838 and bits
860-861 must be reset)
(MAC to MAC) to
swp4. This is used to
carry traffic between
the switch and software
running on Arm cores.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
90
NXP Semiconductors
Page 91
Table continued from the previous page...
RDB portQDS portLinux netdevPCI functionComments
Device Drivers
InternalInternal
1G SWP0 to
1G SWP3
4 ports on QS(X)GMII
add-on card in slot 2.
eno3
swp0 to swp30000:00:00.5By default, switching is
Note that SWP0 is top
port on QSGMII add-on
card and bottom port on
QSXGMII add-on card.
InternalInternal
InternalInternal
swp4
swp5
4.2.12.2 ENETC Ethernet controller
0000:00:00.6Connected internally
(MAC to MAC) to
swp5. This is used to
carry switch control
traffic between the
switch and Linux
bridge. This interface is
present if bit 851 is set
in RCW.
not enabled on these
ports. For detail on how
to enable switching
across these ports, see
Felix Ethernet switch.
Connected internally
(MAC to MAC) to eno2.
Connected internally
(MAC to MAC) to eno3.
Kernel Configuration Options
Driver modules
The following table describes the Ethernet driver modules.
DriverDescription
“fsl-enetc”ENETC Physical Function (PF) Ethernet driver
“fsl-enetc-vf”ENETC Virtual Function (VF) Ethernet driver
Config tree view
To enable the ENETC PF and VF driver modules via make menuconfig:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
91
Page 92
Linux kernel
Config option identifiers
OptionValuesDescription
CONFIG_FSL_ENETCy/m/nENETC Physical Function (PF) Ethernet driver
CONFIG_FSL_ENETC_VFy/m/nENETC Virtual Function (VF) Ethernet driver
Device tree node
The ENETC drivers are PCI device drivers, and the ENETC PCI Root Complex Integrated Endpoint (RCIE) is described through
the following PCIe device tree node:
Overview of supported Linux Ethernet driver features:
• PF and VF PCI Endpoint drivers
• Basic net-device features
• Multi-queue support – 1 Rx queue per CPU, 8 Tx queues
• Per Rx/Tx queue group MSI-X support (interrupt vector)
• SMMU support
• Rx H/W checksum offload for L3 INET_CSUM (CHECKSUM_COMPLETE)
• Unicast and multicast MAC filtering H/W offload
2
2
n/a
n/a
• VLAN filtering H/W offload
• VLAN insertion/ extraction H/W offload
• Scatter-gather (S/G) on Rx and Tx
• Jumbo frames of up to 9.6 Kbyte
• Rx flow hashing (RSS)
• Rx flow steering (RFS)
• Statistics and debug H/W counters (ethtool -S) and register dump (ethtool -d)
• VF primary MAC addressconfig and MAC anti-spoofing
• QoS – TC offloading with H/W MQPRIO
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
94
NXP Semiconductors
Page 95
Device Drivers
4.2.12.3 Felix Ethernet switch
4.2.12.3.1 Modules and dependencies
The driver for the LS1028A L2Switch or the Microsemi “Felix” is a two-layer driver: a common driver (shared with the Microsemi
Ocelot switch driver) and a PCI driver built on top of it.
The two driver modules are described in the following table:
ModuleRuntime module dependenciesDescription
mscc_ocelot_common.ko-Common functionalities for both Ocelot
1. Building options must confirm with the fact that the mscc_ocelot_common module dependency must be satisfied before load
mscc_felix.
Config defines
WITCH
TCH
y/m
y/m
1
4.2.12.3.2 Device Tree bindings
For configuring the L2Switch ports and the attached PHYs the driver uses a custom Ethernet device tree binding named port
node. These port nodes can only be defined within the L2Switch PCI device node ‘pci@0,5’. The total number of available switch
ports on LS1028A is six. Depending on board design and port type (internal or external) there are two supported link modes
specified by below switch port device tree bindings.
Required properties:
• reg – identifies the switch port id and can be within the range [0 ... 5]
1) The switch port is an external port connected to a MDIO configurable phy:
For this binding, the follwing properties are required, their bindings already defined in ethernet.txt, under Documentation/devicetree/bindings/net/* in the kernel source tree.
Required:
• phy-handle – reference to a PHY device node for switch ports [0 … 3]. Defined in ethernet.txt.
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
95
Page 96
Linux kernel
• phy-connection-type – operation mode of PHY; for example, for LS1028ARDB this property should be set to “qsgmii”
2) The swicth port is an internal port, or, in some cases, has a fixed-link external connection:
In this case, the switch port node defines a fixed link connection, as specified by "fixed-link.txt", under Documentation/devicetree/bindings/net/* in the kernel source tree.
Required:
• fixed-link – used primarily for ports #4 and #5 as they are internally (inside the SoC) MAC-to-MAC connected to the
ENETC (Ethernet controller) endpoints ENETC PF2 (that is, ENETC Port 2) and ENETC PF6 (that is, ENETC Port 3),
respectively. The "fixed-link" node is defined in "fixed-link.txt".
The only optional property is cpu-ethernet, custom for internal ports, and it is a phandle to an Ethernet node representing a
network device physically connected to one of the switch ports. This property enables the CPU port function on the designated
switch port. The CPU port function allows injecting frames on a specific switch port, the injected frames bypass the switch frame
processing core. Consequently, it also allows extraction of specific control or normal Ethernet frames. The property should only
be used for the SoC internal switch ports, ports #4 and #5, as they are MAC-to-MAC connected to corresponding ENETC ports.
Example
The below example enables all switch ports and configures the CPU port function on port #5. Ports 0 to 3 are connected to QSGMII
PHY, while ports 4 and 5 are configured in fixed link mode:
A successful driver probe will produce the following output in the boot log:
[1.074990] mscc_felix 0000:00:00.5: Felix Switch Driver - version 0.3 probed
If the driver is successfully probed, each switch port defined in the device tree will have its own network device interface. After
udev applies the networking rules, the switch network interfaces are renamed to swpX, where X represents the port number.
NOTE
If CPU port function is enabled on any switch port, the network device connected to it must be ready or else the
driver probing will fail.
4.2.12.3.3.2 Connecting to the host CPU
On the LS1028A SoC, the L2Switch is connected to the host CPU via two SoC internal MAC-to-MAC port connections between
the switch and corresponding ENETC Ethernet endpoints:
• ENETC PF2 (or ENETC Port 2) and switch port #4
• ENETC PF6 (or ENETC Port 3) and switch port #5
Besides these MAC-to-MAC connections with the host CPU, the L2Switch IP allows for a single switch port to work in CPU port
mode.
The following table summarizes the differences between CPU and non-CPU port modes:
FeatureCPU portNon-CPU port
Allows frame injection/extractionYesNo
Tags frames with custom headerYesNo
Destination for control frames,for example, STPYesNo
PTP offloadYesNo
Flow controlNoYes
Requires peer net device as proxy
1
1. In non-CPU mode the user needs to use the peer network interface to send and receive packets instead of the actual switch
port interface. In CPU port mode, the user will use the net device interface of the switch port or the bridge interface.
The below figure shows the connection of the L2Switch with the host CPU:
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
NoYes
97
Page 98
Linux kernel
Figure 6. Connecting L2Switch with host CPU
4.2.12.3.3.2.1 CPU port mode
The CPU port works by providing the means for the host CPU to choose a switch destination port for a frame and address control
frames from known protocols, such as, STP. When this mode is enabled on one of the internal switch ports the user may use the
Linux network interface assigned to that port as:
• standalone network interface - see CPU port without bridge on page 102
• child interface for a bridge interface - see CPU port with simple bridge configuration and L2 forwarding support on page
99
The two important features of CPU mode are: frame injection and frame extraction.
Frame injection
By using a custom tag or injection header prepended before the Ethernet frame header, the driver can instruct the L2Switch to
forward the frame on a specific port and bypass the frame analyzer. The analyzer determines the destination port, QoS class,
and VLAN classification for the frame through normal frame processing including lookups in the MAC table and VLAN table.
The tagged frame transmission is done from the peer network endpoint device. The peer net device is designated by the cpu-ethernet device tree property. On reception the L2Switch will strip the header, apply the frame updates (for example, write
timestamp on PTP frames) and put the frame on the egress queue of the destination port.
Once configured for injection the switch port accepts only tagged frames.
Frame extraction
The L2Switch can intercept a variety of control frames or just normal frames (unicast or multicast) and redirect them to the CPU
port. When a frame exits the CPU port it is also prepended, similarly to injection, by a custom tag or extraction header. This header
needs to be stripped off and decoded by the switch driver to extract the ingress switch port number on which the frame was
received.
Once configured for extraction the switch port emits only tagged frames.
4.2.12.3.3.2.2
If one of the two SoC internal ports works in non-CPU port mode then the decision to forward the frame to the host CPU or accept
a frame from it depends exclusively on the frame analyzer and the MAC and VLAN tables. As mentioned earlier, the frames
transiting a non-CPU port are not carrying any custom tags. In this mode only, the peer net device port (that is, ENETC port) acts
98
Non-CPU port mode
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
Page 99
Device Drivers
like a proxy for the switch port, therefore, the user is required to use the peer’s Linux network interface for sending and receiving
packets from/to the switch.
4.2.12.3.3.3 L2Switch configuration examples
4.2.12.3.3.3.1 CPU port with simple bridge configuration and L2 forwarding support
The below figure describes the basic setup required to test the switch with CPU port configuration and L2 forwarding at the same
time.
Figure 7. Basic L2Switch config with bridge interface
The setup can be explained as follows:
• Remote host with IP 192.168.2.2 connected to SWP0
• All swp0 ... swp5 interfaces are grouped under the bridge interface br0
• The br0 interface must be configured with an IP address; in this example the IP is 192.168.2.1
• The swp5 represents the CPU port that can be used to monitor the traffic from L2Switch side
• The eno3 represents the ENETC Port 3 internally connected to SWP5 over a 1G link
• Both swp5 and eno3 net interfaces must be up
• The eno2 (ENETC Port 2 with TSN capabilities) can be also brought up and assigned an IP address
• The L2Switch provides external connectivity for eno2 through internal SWP4 in non-CPU mode
The following script configures the L2Switch for the above setup:
• Creates a bridge interface br0
• For each interface:
— sets the MAC address
— adds it to the bridge interface
— brings up the interface
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
NXP Semiconductors
99
Page 100
Linux kernel
• Brings up the eno2 and eno3 ENETC interfaces
• Assigns the bridge, switch port interfaces and eno3 to the same net namespace (swns)
#!/bin/bash
#
# Simple switch configuration
#
# Assume both ENETC and Felix drivers are already loaded
#
# Create bridge namespace
ip netns add $SW_NETNS
# Create bridge device in net namespace
$EXEC_SWNS ip link add name $BRIDGE type bridge
$EXEC_SWNS ip link set $BRIDGE up
# Configure switch ports
# * set MAC address
# * bring up interface
# * move net device into the bridge net namespace
# * set bridge device as master
swps=($(ls /sys/bus/pci/devices/0000:00:00.5/net/))
nr=${#swps[@]}
for (( i=0; i<$nr; i++ ))
do
echo "adding ${swps[$i]} to brigde .."
ip link set ${swps[$i]} address $MAC_ROOT:$(echo "${swps[$i]}" | tr -dc '0-9')
ip link set ${swps[$i]} netns $SW_NETNS
$EXEC_SWNS ip link set ${swps[$i]} master $BRIDGE
$EXEC_SWNS ip link set ${swps[$i]} up
done
# bring up ENETC ports connected to switch ports
enetc2=$(ls /sys/bus/pci/devices/0000:00:00.2/net/)
ip link set $enetc2 up
# move ENETC port connected to switch CPU port in bridge ns
enetc3=$(ls /sys/bus/pci/devices/0000:00:00.6/net/)
ip link set $enetc3 netns $SW_NETNS
$EXEC_SWNS ip link set $enetc3 up
# Check configuration
$EXEC_SWNS bridge link show
The script output appears as follows:
br0: port 1(swp0) entered blocking state
br0: port 1(swp0) entered disabled state
device swp0 entered promiscuous mode
mscc_felix 0000:00:00.5 swp0: Unsupported PHY speed: 0
Vitesse VSC8514 1f8100000:10: attached PHY driver [Vitesse VSC8514] (mii_bus:phy_addr=1f8100000:10,
irq=POLL)
br0: port 1(swp0) entered blocking state
br0: port 1(swp0) entered forwarding state
Layerscape LS1028A BSP User Guide, Rev. 0.3, 04/2019
100
NXP Semiconductors
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.