Scalys TrustBox User manual

1
TrustBox BSP user guide
Description
This technical reference document serves as a guide on
how to build and use the BSP for the Scalys TrustBox.

www.scalys.com
Introduction
This document serves as a technical reference document on how to build the Board Support
Package ( BSP ) for the Scalys TrustBox. It is meant to supplement the available documentation
already provided by NXP[1,2].
The TrustBox features a QorIQ LS1012A processor[ 3 ] that contains a single Arm Cortex-A53 core.
NXP provides two flavours of BSP for this specific processor. The first being the Yocto based Linux
Software Development Kit ( SDK ) for QorIQ processors and the second flavour is the more recently
introduced Layerscape Software Development Kit ( LSDK ). The QorIQ Linux SDK is based upon the
Yocto Project [ 4 ], whilst the LSDK is based on a more disaggregated flex-building environment [ 5 ].
This document assumes the reader has a basic knowledge of platform software and deployment,
and it will not go into too much detail of the actions performed to build the BSP s. This document
currently only describes building the BSP through the LSDK method. Contact Scalys for more
information on the Yocto based SDK . Additionally, NXP intends to update the LSDK regularly,
however this document only focusses on a specific release version. Contact Scalys when updates
are desired.
Rev Date Description
1.4 29thMay,
2019
Improved document structure
1.3 4thMay, 2019 Updated in accordance with new lsdk19.03
1.2 18thOct, 2018 URL and FAQ update
1.1 28thMay,
2018
FAQ update
1.0 18thMay, 2018 First release
Copyright ©2019, Scalys BV Restricted 2

www.scalys.com
BSP User guide
May 29, 2019
Contents
List of Tables 4
1 Preparation 5
1.1 Install the dependencies using the package manager ................. 5
1.1.1 LSDK ........................................ 5
1.2 Git setup .......................................... 5
2 Building images 6
2.1 Quick start with LSDK ................................... 6
2.1.1 Building RFS .................................... 6
2.2 Standalone Linux kernel build .............................. 8
2.3 Building composite firmware image ........................... 8
3 Firmware components 9
3.1 Reset Configuration Word ................................. 9
3.1.1 Building RCW binary ................................ 9
3.1.2 Modifying the Reset Configuration Word .................... 9
3.2 U-boot ............................................ 10
3.2.1 Building U-boot with LSDK ............................ 10
3.2.2 Standalone U-boot build ............................. 10
3.3 PFE ............................................. 10
3.3.1 Building PFE firmware with LSDK ........................ 10
3.4 PPA ............................................. 10
3.4.1 Building PPA firmware .............................. 10
4 TrustBox flash configuration 11
4.1 Primary flash partitioning ................................. 11
4.2 Rescue flash partitioning ................................. 12
5 Installing and updating images 13
5.1 Flashing/updating the RFS on the SD card ....................... 13
5.2 Updating partitions on the primary flash ........................ 13
5.3 Recovering from the rescue flash ............................ 14
6 Configuration necessary for a TFTP boot 15
6.1 TFTP server installation and configuration ....................... 15
6.2 DHCP Server installation and configuration ....................... 16
7 Frequently asked questions 17
7.1 What is the default login of the LSDK/QorIQ SDK? ................... 17
7.2 How to connect to the TrustBox? ............................. 17
7.2.1 Serial port connection ............................... 17
7.2.2 SSH connection .................................. 17
7.3 Why doesn’t my TrustBox seem to accept my commands on the serial port? . . . . 17
7.4 Why doesn’t my TrustBox produce any output data on the serial interface? ..... 18
7.5 The ethernet interfaces of the Packet Forwarding Engine (PFE) are not working? . 18
7.6 Bluetooth can’t find any devices? ............................. 18
Copyright ©2019, Scalys BV Restricted 3

www.scalys.com
BSP User guide
May 29, 2019
7.7 PPA related kernel crash ................................. 19
A References 20
B List of Acronyms 21
List of Tables
4.1 Primary NOR flash Partitioning ................................ 11
Copyright ©2019, Scalys BV Restricted 4

www.scalys.com
BSP User guide
May 29, 2019
1
Preparation
This document assumes the system used to build the BSP is a newly installed OS.
1.1 Install the dependencies using the package manager
A list of additional packages used throughout this user guide are as follows:
•curl
•git
•gawk
•wget
•tftpd
•tftp
•isc-dhcp-server
•nfs-kernel-server
•gcc-aarch64-linux-gnu
•device-tree-compiler
•libncurses5-dev
•libncursesw5-dev
•docker.io
You can install them through your package manager using the following command:
sudo apt-get install curl git gawk wget tftpd tftp isc-dhcp-server nfs-kernel-server \
gcc-aarch64-linux-gnu docker.io device-tree-compiler libncursesw5-dev libncurses5-dev
1.1.1 LSDK
The LSDK build has been verified to work on Debian 9.8.
1.2 Git setup
# Setup username and email for git if not already done
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
Copyright ©2019, Scalys BV Restricted 5

www.scalys.com
BSP User guide
May 29, 2019
2
Building images
2.1 Quick start with LSDK
2.1.1 Building RFS
The following stepwise guide primarily follows the steps given in the LSDK documentation. More in-
depth information regarding the LSDK flexbuild environment can be found in the NXP manual[ 2 ] and
the REAMDE.md file found in step 6below. For compatibility reasons we will choose to use an
Ubuntu 18.04 Docker container in the flex-build environment, which allows for the use of Linux
distros other than Ubuntu 18.04 on the host machine.
In the this section we will build our LSDK Root File System ( RFS ) which includes the Linux kernel
and device tree. Note that only a subset of the default LSDK commands is supported for the
TrustBox.
1. Begin with creating a working directory in your home directory:
mkdir -p ~/trustbox/ && cd ~/trustbox
2. Setup Docker on the host machine. If not already installed, then do so from your package
manager. Add your user to the docker group.
sudo addgroup --system docker
sudo usermod -aG docker <accountname>
sudo gpasswd -a <accountname> docker
sudo service docker restart
Make sure to logout once to apply the changes to your user.
3. Clone bsp-lsdk repository from the Scalys github page to your working directory:
git clone https://github.com/Scalys/bsp-lsdk.git
4. Switch to the release branch:
cd bsp-lsdk && git checkout trustbox-1903
5. Manually download the flexbuild_lsdk1903.tgz tar-ball[ 6 ] from the NXP webpage and put it
into the bsp-lsdk directory:
•Source: Layerscape Software Development Kit (rev 19.03) 86.1 KB
•flexbuild_lsdk1903.tgz
•MD5 Signature 1efc3535b0255b088c0956e9c4ae3371
mv flexbuild_lsdk1903.tgz ~/trustbox/bsp-lsdk/flexbuild_lsdk1903.tgz
6. Run the construct.sh script. It will unpack the flexbuild_lsdk1903.tgz archive and apply the
TrustBox support patches:
Copyright ©2019, Scalys BV Restricted 6

Chapter 2. Building images www.scalys.com
./construct.sh
7. Enter the build environment.
source setup.env
flex-builder docker
source setup.env
8. Build the generic RFS for with additional packages. Modify the ’packages_trustbox’ file to
add/remove custom packages. It can be found in ’configs/ubuntu/’.
flex-builder -i mkrfs -m trustbox -r ubuntu:main -B packages_trustbox
9. Build the Linux kernel:
flex-builder -c linux -m trustbox
Alternatively, append the ’-B menuconfig’ argument to modify the default configuration or
use ’-B fragment:"defconfig <custom.config>"’ to specify custom configuration files.
10. The next step is compiling apps:
flex-builder -c apps -m trustbox
11. Merge components into the RFS:
flex-builder -i merge-component -m trustbox
12. Leave the docker environment
exit
Now that we have a RFS prepared, we have the option to go directly to section 5.1 in order to
prepare the SD card for the TrustBox or continue with the following sections to build and modify
U-boot and the Linux kernel.
Copyright ©2019, Scalys BV Restricted 7

Chapter 2. Building images www.scalys.com
2.2 Standalone Linux kernel build
Modifying the Linux kernel to your requirements is recommended to do within the flexbuild. Refer
to the official NXP guide[ 2 ] to get more details on how to accomplish this. In this section we will
show how to build a Linux kernel in a stand-alone fashion.
Start by cloning the correct Linux kernel repository (with the appropriate branch) from the Scalys
github page. For this example we take the kernel used in the LSDK with the TrustBox patches, so
make sure you also use the associated RFSfor it to work.
git clone https://github.com/Scalys/linux-qoriq.git -b trustbox-1903 && cd linux-qoriq/
Configure the kernel:
CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 make defconfig lsdk.config trustbox.config
Optionally, we can now configure and modify the kernel manually with:
CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 make menuconfig
Build the kernel:
CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 make -j 8
Convert the kernel image to the uImage format:
CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 mkimage -A arm64 -O linux -T kernel -C gzip \
-a 0x80080000 -e 0x80080000 -n Linux -d arch/arm64/boot/Image.gz uImage
Install the generated files in the RFS, e.g. on the SD card:
sudo cp uImage <path_to_rfs>/boot/uImage
sudo cp arch/arm64/boot/dts/freescale/trustbox.dtb <path_to_rfs>/boot/trustbox.dtb
sudo CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 make INSTALL_MOD_PATH=<path_to_rfs> modules_install
2.3 Building composite firmware image
Composite firmware consists of rcw, pbi, u-boot, Ethernet MAC/PHY firmware and PPA image. To
generate LSDK composite firmware for Layerscape platform, directly run the following command:
flex-builder -i mkfw -m trustbox -b qspi
Finally you can find composite firmware at build/images/trustbox/. This image can be programmed
at offset 0x0 in flash device manually or by using the special command that implemented in
U-boot environment (see section 5.2). Standalone firmware components also can be found at
build/images/trustbox/components.
Copyright ©2019, Scalys BV Restricted 8

www.scalys.com
BSP User guide
May 29, 2019
3
Firmware components
3.1 Reset Configuration Word
The LS1012A processor requires a valid Reset Configuration Word Reset Configuration Word ( RCW )
in order to be successfully initialized at boot time. The current revisions of the processor support
reading the RCW from two sources only. Namely an external QSPI flash device and an internal
hardcoded source. The TrustBox by default selects the QSPI device as the RCW source. The RCW
is a set of 64 bytes, which define how the LS1012A and its interfaces are configured. The Pre-Boot
Loader ( PBL ) reads these 64 bytes along with any appended Pre-Boot Instructions Pre-Boot
Instructions (PBI) from the chosen source.
The TrustBox by default comes with an RCW configuration with the following main features:
•SATA configuration on the M.2. port;
•I2C and DSPI configured on the 26-pins header.
3.1.1 Building RCW binary
To build the RCW binary in LSDK, direclty run the following command:
flex-builder -c rcw -m trustbox
Then you can find binaries at build/firmware/rcw/trustbox/. Directory N_SSNH_3308 contains the
RCW binaries that configure M.2 in compilance with SATA, binaries from N_SSNP_3305 configure
M.2 as PCI-e. Digits in the file names mean maximal processor frequency. For example file located
at N_SSNH_3308/rcw_800.bin.swapped configures M.2 connector as SATA and sets maximal
LS1012A frequency at 800MHz.
Note: Only files marked as swapped are suitable for RCW rewriting!
3.1.2 Modifying the Reset Configuration Word
When the two default RCW options are not sufficient we can modify it using the following steps:
1. Clone rcw repository from the Scalys github page:
git clone https://github.com/Scalys/rcw.git -b trustbox 1903 && cd rcw/trustbox
2. Create your own .rcw source with the settings you need (at your own risk!). Any .rcw file
from rcw/trustbox/N_SSN* may be used as example.
3. Add RCW source path to rcw/qspi_swap_list.txt file.
4. Then enter rcw/trustbox directory and run the following command:
make
5. On success you will get two RCW binaries. Remember that the only swapped binaries are
suitable for rewriting.
Copyright ©2019, Scalys BV Restricted 9

Chapter 3. Firmware components www.scalys.com
3.2 U-boot
3.2.1 Building U-boot with LSDK
The flexbuild build system supports the command to build a U-boot image, starting from this
version it is available for the TrustBox machine:
flex-builder -c uboot -m trustbox -b qspi
The corresponding binary can be found at build/firmware/u-boot/trustbox/.
3.2.2 Standalone U-boot build
Download the Scalys U-boot repository:
git clone https://github.com/Scalys/u-boot-qoriq.git -b trustbox-1903 && cd u-boot-qoriq
Choose the corresponding TrustBox configuration:
ARCH=aarch64 CROSS_COMPILE=aarch64-linux-gnu- make trustbox_qspi_defconfig
Optionally run menuconfig and change any options you neeed:
ARCH=aarch64 CROSS_COMPILE=aarch64-linux-gnu- make menuconfig
Build U-boot image:
ARCH=aarch64 CROSS_COMPILE=aarch64-linux-gnu- make -j 8
3.3 PFE
3.3.1 Building PFE firmware with LSDK
Direclty run the following command:
flex-builder -c qoriq-engine-pfe-bin -m trustbox
3.4 PPA
3.4.1 Building PPA firmware
Direclty run the following command:
flex-builder -c ppa-generic -m trustbox
Copyright ©2019, Scalys BV Restricted 10