QorIQ LS1012A BSP v0.5

Transcription

1 NXP Semiconductors Document Number: QORIQLS1012ABSP05 Rev. 0, Dec 2016 QorIQ LS1012A BSP v0.5

2 Contents Contents Chapter 1 SDK Overview What's New Components Known Issues...9 Chapter 2 Getting Started Yocto SDK File System Images fsl-image-minimal fsl-image-mfgtool fsl-image-full fsl-image-core fsl-image-virt Essential Build Instructions Install the SDK Host Environment Setup Poky Builds Additional Instructions for Developers Customizing U-Boot Customizing Linux Kernel Patching Packages Extract Source Code Customize Root Filesystem Native Packages Standalone Toolchain Shared State(sstate) Cache Yocto FAQ BitBake User Manual Chapter 3 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Introduction Basic Host Set-up Target Board Set-up Optimzing Boot Flow (Fast Boot) Supported Boards LS1012ARDB Overview Switch Settings U-Boot Environment Variables U-Boot Environment Variable "hwconfig" Configuring U-Boot Network Parameters RCW (Reset Configuration Word) and Ethernet Interfaces System Memory Map Flash Bank Usage Programming a New U-Boot, RCW, and PPA Firmware Deployment NXP Semiconductors

3 Contents Ramdisk Deployment from TFTP Ramdisk Deployment from Flash NFS Deployment SD Deployment Check 'Link Up' for Serial Ethernet Interfaces Basic Networking Ping Test FRDM-LS1012A Switch Settings U-Boot Environment Variables U-Boot Environment Variable "hwconfig" Configuring U-Boot Network Parameters RCW (Reset Configuration Word) and Ethernet Interfaces System Memory Map Flash Bank Usage Programming a New U-Boot and RCW Deployment Ramdisk Deployment from TFTP Ramdisk Deployment from Flash NFS Deployment Check 'Link Up' for Serial Ethernet Interfaces Basic Networking Ping Test Chapter 4 System Recovery Environment Setup Environment Setup (Common) Image Recovery Recover system with already working U-Boot Recover system using CodeWarrior Flash Programmer Chapter 5 About Yocto Project Yocto Project Quick Start Application Development Toolkit User's Guide Board Support Packages - Developer's Guide Yocto Project Development Manual Yocto Project Linux Kernel Development Manual Yocto Project Profiling and Tracing Manual Yocto Project Reference Manual Chapter 6 Linux Kernel Drivers Audio SAI User Manual LS1012A DMA Controller Enhanced Direct Memory Access Driver (ARM) edma User Manual Enhanced Secured Digital Host Controller (esdhc) esdhc Driver User Manual PCI Express Interface Controller PCIe Linux Driver EDAC Driver User Manual PCIe Advanced Error Reporting User Manual PCIe Remove and Rescan User Manual PCIe Endpoint User Manual NXP Semiconductors 3

4 Contents 6.5 Packet Forward Engine (PFE) Network Driver Introduction Overview Purpose Features High level decomposition and data flow NAPI support Interrupt coalescing Checksum offloading Scatter gather support Ethtool support Real Time Clock (off-chip) RTC Driver User Manual (Linux BSP) SATA Controller NXP Native SATA User Manual Serial Peripheral Interface DSPI Device Driver User Manual DSPI Device Driver User Manual Universal Serial Bus Interfaces USB 2.0 Host Driver USB 2.0 Host Driver User Manual USB Gadget Network Driver User Manual USB Gadget for Network Devices USB 3.0 Host/Peripheral Linux Driver User Manual USB 3.0 Host/Peripheral Linux Driver User Manual Watchdog Timers Watchdog Device Driver User Manual Chapter 7 Additional Linux Use Cases Power Management Power Management User Manual CPU Frequency Switching User Manual System Monitor Power Monitor User Manual Thermal Monitor User Manual Web-based System Monitor User Guide Real Time Application Note Real Time Application Note Chapter 8 Linux User Space OpenSSL Offload User's Guide Overview OpenSSL Software architecture OpenSSL s ENGINE Interface NXP solution for OpenSSL hardware offloading Building OpenSSL with hardware offloading support Nginx offloading with OpenSSL Valid TLS Ciphersuites based on TLS protocol version Chapter 9 Boot Loaders Primary Protected Application (PPA) User's Guide Introduction NXP Semiconductors

5 Contents Rationale and Scope References Definitions Boot Flow Architecture LS1043A/LS1012A Boot Flow Loading and Initializing the PPA How to Call SMC/PSCI functions PSCI Function List PSCI_VERSION CPU_ON CPU_OFF CPU_SUSPEND AFFINITY_INFO SYSTEM_OFF SYSTEM_RESET PSCI Return Code Values PSCI Functions Implemented, by SoC SMC Function List Function Count - SMC Function Count - SMC Get UUID Get Revision Building the PPA System Considerations When Calling SMC & PSCI Functions Secure Boot: PBL Based Platforms Introduction Secure Boot Process Pre-Boot Phase ISBC Phase Flow SRKs Key Revocation Alternate Image support ESBC with CSF Header ESBC Phase Boot script Where to place the boot script? Chain of Trust Chain of Trust with Confidentiality Next Executable Phase CST Tool KEY GENERATION gen_keys gen_drv_drbg gen_otpmk_drbg CSF HEADER GENERATION Default Usage Verbose Mode Public Key/ SRK Hash Generation Only Key Extension Image Hash Generation Help Code Signing Tool Walkthrough Product execution Getting started NXP Semiconductors 5

6 Contents Environment for Secure Boot SDK Images required for the demo Chain of Trust Other Images Required for demo Bootscript and Signing the images Running secure boot (Chain of Trust) Chain of Trust with Confidentiality Other Images Required for demo Encap Bootscript Decap Bootscript Creating CSF Headers Running secure boot (Chain of Trust with Confidentiality) NAND Secure Boot (Chain of Trust) Running NAND Secure boot (Chain of Trust) NAND Secure Boot (Chain of Trust with Confidentiality) Running NAND Secure boot (Chain of Trust with Confidentiality) Troubleshooting CSF Header Data Structure Definition ISBC Validation error codes ESBC Validation error codes Address Map used for demo Useful U-Boot and CCS Commands Trust Architecture and SFP Information QCVS Tool Usage Chapter 10 Virtualization KVM/QEMU KVM/QEMU Release Notes KVM for ARM Architecture Users Guide and Reference Introduction to KVM and QEMU Overview Organization of this Document Virtual Machine Overview Introduction to KVM and QEMU Device Tree Overview References For More Information Building QEMU and KVM Overview Building Linux with KVM Building QEMU Creating a host Linux root filesystem Using QEMU and KVM Overview of Using QEMU Virtual Machine Memory Virtual network interfaces VMs and the Linux Scheduler Virtual machine reference VM Overview Memory Map of Virtual I/O Devices Virtual machine state at initialization Virtual CPUs VGIC Debugging virtual machines NXP Semiconductors

7 Contents QEMU Monitor QEMU GDB Stub KVM/QEMU How-to's Quick-start Steps to Build and Deploy KVM Using Yocto Quick-start Steps to Run KVM Using Hugetlbfs How to Use Virtual Network Interfaces Using Virtio How to use vhost-net with virtio Debugging: How to Examine Initial Virtual Machine State with QEMU Debugging: How to Profile Virtualization Overhead with KVM NXP Semiconductors 7

8 SDK Overview What's New Chapter 1 SDK Overview 1.1 What's New NXP Digital Networking is pleased to announce the release of LS1012A BSP v0.5 supporting LS1012A rev 1.0 processor on RDB and FRDM boards.. This is the follow on release to SDK v0.4 release. The additional functionalities supported in this release are Checksum offload to PFE hardware, 2.5G SGMII Ethernet support (QDS only), memcpy offload to CAAM's DMA, PSCI enabled for 32-bit, power management support in 32-bit kernel, support for Rev D RDB and Rev C FRDM. For more information on QorIQ LS1012A see the QorIQ LS1012A Low Power Communication Processor summary page. 1.2 Components Top-level components in LS1012A SDK Yocto GNU Toolchain U-Boot Boot Loader Linux Kernel and Virtualization Linux Kernel and Device Drivers Reduced system boot time Yocto and Toolchain Yocto/Poky 2.0 "jethro" gcc-linaro-4.9-r , glibc-linaro-2.20-r , binutils-linaro-2.25-r , gdb U-Boot Boot Loader U-Boot ARMv8 core Primary Protected Application (PPA) Non-secure boot, Generic Timers, DDR, I2C, QSPI flash, UART1, USB 3 mass storage & Gadget, PFE based Ethernet support LS1012A RDB : DSPI, esdhc, PCIe, SATA, USB 2 mass storage, Secure Boot (QSPI as source) Linux Kernel Core, Virtualization Linux kernel Real Time ARMv8: AARCH64, 64-bit effective addressing, Kernel-based Virtual Machine (KVM) ARMv8: AARCH32 (Components not supported in 32 bit mode - PPA, Power Management, Real Time, Linux kernel Crypto driver, Secure Boot) Linux Kernel Device Drivers 8 NXP Semiconductors

9 SDK Overview Known Issues Crypto driver supporting SEC 5 (CAAM) DDR, DUART, DSPI, I2C PFE Ethernet (Packet Rx/Tx) PHY support: RGMII, SGMII SAI/I2S UART, USB 3 mass storage Watchdog LS1012A RDB : DSPI, esdhc, PCIe, PHY (RGMII), SATA, USB 2 mass storage 1.3 Known Issues ID Description Disposition Opened in Resolved in Workaround QLINUX-6520 QLINUX-5894 QLINUX-5875 QUBOOT-1682 QLINUX-5883 QLINUX-5841 Latency is beyond 125us when testing rt_ptsema on LS1012ARDB. The latency when running cyclictest is heavier with ipfwd run. Kernel call trace during rt_fully_pistress_t est run. Checkpatch Errors in PFE module. The ppfe port does not work after power management is entered and exited repeatedly. Linux IPfwd for small frame size has more degradation compared with SDK v0.2 on LS1012ARDB. Open LS1012A BSP v0.5 Open LS1012A BSP v0.5 Open LS1012A BSP v0.5 Open LS1012A BSP v0.5 Open LS1012A BSP v0.5 Open LS1012A BSP v0.5 Table continues on the next page... NXP Semiconductors 9

10 SDK Overview Known Issues QLINUX-6522 The kernel could not resume and call trace when testing PM on LS1012ARDB. Table continued from the previous page... Open LS1012A BSP v0.5 QLINUX-6529 Sec self for CE and Neon tested failed on ls1012ardb-32bit. Open LS1012A BSP v0.5 QLINUX-5768 LS1012:rmmod of PFE modules crashes the kernel. Open LS1012A SDK v0.2 QSDK-3237 LS1012A PPA: PPA binary is not getting detected with BSP 0.5 firmware. Resolved LS1012A BSP v0.5 LS1012A BSP v0.5 QLINUX-5876 Kernel Call Trace while testing ce_sec_tcrypto_a es with 32-bit kernel. Resolved LS1012A SDK v0.4 LS1012A BSP v0.5 QLINUX-5877 Error message DMA Error appears while testing sec_tcrypto_3des and sec_tcrypto_aes with 32-bit kernel. Resolved LS1012A SDK v0.4 LS1012A BSP v0.5 QLINUX-5878 Kernel hang when testing sec_tcrypto_des with 32-bit kernel. Resolved LS1012A SDK v0.4 LS1012A BSP v0.5 QLINUX-6508 Kernel crashes during boot with 64K pagesize. Resolved LS1012A SDK v0.4 LS1012A BSP v0.5 Table continues on the next page NXP Semiconductors

11 SDK Overview Known Issues Table continued from the previous page... QUBOOT-1737 If code warrior is used to program u- boot or RCW, the flash gets into invalid state. Resolved LS1012A SDK v0.3 Latest CodeWarrior Release Use Code-Warrior to program the 64 MB SDK image (LS1012) thereby programming the entire flash. After power recycle, the board will start functioning. QUBOOT-1691 USB 3.0 USB Harddisk enumeration issue is faced with certain disks. Resolved/ Duplicate LS1012A SDK v0.3 LS1012A BSP v0.5 QSDK-2982 Inconsistent behavior while reading QSPI using U-boot cmds "sf read" and "md" commands. Not an Issue LS1012A SDK v0.3 LS1012A BSP v0.5 QLINUX-5849 Jumboframe floodping causes call trace with 64- bit kernel. Resolved LS1012A SDK v0.3 LS1012A BSP v0.5 NXP Semiconductors 11

12 Getting Started SDK File System Images Chapter 2 Getting Started Yocto Project is an open-source collaboration project for embedded Linux developers. Yocto Project uses the Poky build system to make Linux images. For complete information about Yocto Project, see SDK File System Images This section describes the file system images that can be built using standard Yocto Project recipes included with the NXP SDK. The file system images contain the programs, scripts, and other files that make up Linux user space. There are five standard images. They are described in the following sections. In the SDK installation directory, look in meta-freescale/recipes-fsl/images for files that define these images. Where to start: fsl-image-full contains a rich set of standard Linux features and all special NXP SDK-specific features. It is the best starting point for exploration and evaluation fsl-image-minimal: A Barebones Starting Point for Products Contents: This is a barebones image. It contains a small file set that allows Linux to boot and little else. Purpose: This image is intended as a starting point for product development. Users may add packages to it to form an image that targets their particular project or purpose. Packages may be added by editing conf/local.conf and adding new packages to be built and installed via IMAGE_INSTALL_append = " package1 package2 etc" Then, rebuild the image using bitbake. The result will be an image that is small enough for simple flash devices and is narrowly focused on a specific goal. Users must add packages to fsl-image-minimal to make it useful. Thus it is not intended for out-of-the-box evaluation. Instead, use it as the basis for targeted images for your specific product fsl-image-mfgtool: A Small Flash Image for Managing Disks and Larger Images Contents: This is a small image that NXP preprograms into the flash on development boards. On many boards, the image is stored in a NOR flash and is loaded into a RAM disk when Linux boots. It contains disk management functions as described in the next section. Purpose: This image is intended to help users to load much larger images onto disks or disk-like devices such as SDHC cards or USB thumb drives. Thus, this image contains networking support to transfer images and also standard Linux disk and file system manipulation commands. NXP preloads fsl-image-full (see below) onto disks on development boards that have them. For these boards, fsl-imagemfgtool can be used to restore the larger disk image if it becomes corrupted. 12 NXP Semiconductors

13 Getting Started SDK File System Images Users will find that it is often convenient to work with larger images and may wish to install fsl-image-full onto a disk-type device and use it with NXP development boards that do not come with a disk drive. The networking and disk management commands that NXP supplies are standard Linux commands. They are, in fact, identical on all architectures and thus are not unique to NXP. Users with Linux experience will find them familiar. They include: ifconfig, ip, route, etc. (configure networking) ftp (transfer files via the network) scp (another way to transfer files via the network) date and rdate (set date and time) fdisk (partition disks and disk-type devices) mkfs (make file systems) tar (extract file system images, and more) fsck (check file systems) mount/umount (mount and umount file systems) fsl-image-full: A Full-Featured Image, Useful Out-of-Box Contents: This is a large image that contains many standard Linux commands and features including native (target-resident) versions of the GNU tools including gcc and gdb. If you boot this image, the resulting Linux environment will be much like a command-line on a full desktop-type Linux system rather than an embedded system. Purpose: While this type of image may not be appropriate for a final embedded product, it can be very helpful for many development and evaluation tasks. The reason is the full set of standard Linux facilities that are already present in the image. In fact, users may find that they can use this image instead of installing the Yocto Project-based NXP SDK onto a development system, at least initially. For this reason, fsl-image-full is preinstalled on the disk drives of NXP development boards that have disks. For example, the image is complete enough that the standard Linux open source command sequence configure; make stands a decent chance of working for arbitrary open source packages that do not happen to be on the image already. To be clear, the NXP SDK is a Yocto Project/Poky-derived embedded distribution. However, the Yocto Project standard Linux package set is large enough that if one enables a lot of the available packages, the result begins to have the feel of desk top Linux. NXP added the special NXP-specific packages, and the result is fsl-image-full. It is intended for out-of-the-box evaluation because it is rather complete fsl-image-core: A Small Image with NXP-Specific Packages Present Contents: This is a small image somewhat like fsl-image-minimal except it contains all of the NXP-specific SDK packages. Purpose: This image is useful for evaluating the NXP-specific software packages in the context of a file system image that is much more embedded-oriented than fsl-image-full. NXP Semiconductors 13

14 Getting Started Essential Build Instructions Embedded file system images contain fewer helpful tools and utilities by definition. They are intended to support an embedded product s functionality rather than a developer s tasks. Thus, it can be convenient to begin with fsl-image-core for evaluation and planning and then later narrowly extend fsl-image-minimal to support your embedded product fsl-image-virt: An image for KVM deployment Contents: This is an image which contains the specific packages needed to enable virtualization. Purpose: This image is useful for virtualization scenarios (KVM, libvirt, lxc). It contains: the guest root filesystem the guest image (uimage format for Power based architectures and zimage for ARM based architectures) QEMU all necessary libraries and tools for libvirt and lxc support 2.2 Essential Build Instructions The following sections are essential to the build process and must be performed when using Yocto Project to build the SDK. In order to install the SDK, prepare the host environment, setup Poky, and perform builds, follow the instructions in the subsequent sections. When these steps are completed, the build process will be complete. Linux images that have been built will be found in the following directory: build_<machine>/tmp/deploy/images/<machine> See Additional Instructions for Developers for more information on using Yocto Project Install the SDK How to install Yocto Project on the host machine. 1. Mount the ISO on your machine: $ sudo mount -o loop LS1012A-SDK-<target>-<yyyymmdd>-yocto.iso /mnt/cdrom 2. As a non-root user, install Yocto Project: $ /mnt/cdrom/install 3. When you are prompted to input the install path, ensure that the current user has the correct permission for the install path. There is no uninstall script. To uninstall Yocto Project, you can remove the <yocto_install_path>/ls1012a-sdk-<yyyymmdd>yocto directory manually. NOTE * The source ISO contains the package source tarballs and yocto recipes. It can be installed and used to do non-cache build. * The cache ISO contains the pre-built cache binaries. To avoid a long time build, you can install the source ISO and the cache ISO in the same installation folder. * The image ISO includes all prebuilt images: flash images, standalone toolchain installer, HD rootfs images and small images. * The source ISO can be used separately. The core ISO and the source ISO should work together. 14 NXP Semiconductors

15 Getting Started Essential Build Instructions Prepare the Host Environment Yocto Project requires some packages to be installed on the host. The following steps are used to prepare the Yocto Project environment. 1. In general, Yocto Project can work on most recent Linux distributions with Python or greater(excluding python3 which is not supported), git or greater, tar-1.24 or greater and required packages installed. The default Python is not 2.7.x on some Linux distros, e.g. CentOS 6.5 installs python Please follow below instructions to install the Python 2.7.x in custom path instead of override the system default python, the override may cause system utilities breaking. $ wget [NOTE: Python and python can be used as well.] $ tar -xf Python tar.xz $ cd Python $./configure --prefix=/opt/python $ make $ sudo make install Please run below export command to ensure python 2.7.x is used for Yocto build. $ export PATH=/opt/python-2.7.6/bin:$PATH Yocto Project supports typical Linux distributions:ubuntu, Fedora, CentOS, Debian, OpenSUSE, etc. More Linux distributions are continually being verified. This SDK has been verified on following Linux distributions: Ubuntu 14.04, centos ,debian 8.2, Fedora 22 and OpenSUSE 13.2 For a list of the Linux distributions tested by the Yocto Project community see SANITY_TESTED_DISTROS in poky/metayocto/conf/distro/poky.conf. The following is the detailed package list on the CentOS hosts: $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat SDL-devel xterm For the Fedora hosts: $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ ccache perl-data-dumper perl-text-parsewords perl-thread-queue socat \ findutils which SDL-devel xterm For Ubuntu and Debian hosts: $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \ build-essential chrpath socat libsdl1.2-dev xterm Extra packages are needed for Ubuntu-64b: $ sudo apt-get install lib32z1 lib32ncurses5 lib32bz2-1.0 ia32-libs lib32ncurses5-dev For OpenSUSE host: $ sudo zypper install python gcc gcc-c++ libtool subversion git chrpath automake make wget diffstat makeinfo freeglut-devel libsdl-devel NXP Semiconductors 15

16 Getting Started Essential Build Instructions Set Up Poky Source the following poky script to set up your environment for your particular Freescale platform. This script needs to be run once for each terminal, before you begin building source code. $../fsl-setup-env -m <machine> For example: $../fsl-setup-env -m ls1012afrdm The following shows the usage text for the fsl-setup-env command: Usage: $../fsl-setup-env -h Usage:. fsl-setup-env -m <machine> Supported machines: ls1012afrdm-32b ls1012afrdm ls1012ardb-32b ls1012ardb Optional parameters: * [-m machine]: the target machine to be built. * [-b path]: non-default path of project build folder. * [-j jobs]: number of jobs for make to spawn during the compilation stage. * [-t tasks]: number of BitBake tasks that can be issued in parallel. * [-d path]: non-default path of DL_DIR (downloaded source) * [-c path]: non-default path of SSTATE_DIR (shared state Cache) * [-g]: enable Carrier Grade Linux * [-l]: lite mode. To help conserve disk space, deletes the building directory once the package is built. * [-h]: help Builds How to set up a cross compile environment and perform builds Follow these steps to do builds using Yocto Project. Be sure to set up the host environment before doing these steps. 1. $ cd <sdk-install-dir>/build_<machine> 2. $ bitbake <image-target> Where <image-target> is one of the following: fsl-image-minimal: contains basic packages to boot up a board fsl-image-core: contains common open source packages and FSL specific packages. fsl-image-full: contains all packages in the full package list. fsl-image-kernelitb: A FIT image comprising the Linux image, dtb and rootfs image. fsl-image-mfgtool: contains all the user space apps needed to deploy the fsl-image-flash image to a USB stick, hard drive, or other large physical media. fsl-image-virt: contains toolkit to interact with the virtualization capabilities of Linux fsl-toolchain: the cross compiler binary package package-name(u-boot): build a specific package Contents of the Built Images Directory: 16 NXP Semiconductors

17 Getting Started Additional Instructions for Developers A Yocto build produces images that will be located in the following directory: <sdk-install-dir>/build_<machine>/tmp/deploy/images/<machine>/ The following list shows the typical directory/image files (exact contents depend on the setting of the <IMAGE_FSTYPES> variable): fsl-image-<machine>.ext2.gz.u-boot - ramdisk image that can be loaded with U-Boot fsl-image-<machine>.ext2.gz - gzipped ramdisk image fsl-image-<machine>.tar.gz - gzipped tar archive of the image kernel-<machine>.itb - kernel (itb). Image-<machine>.bin - kernel binary of the image u-boot-<machine>.bin - U-Boot binary image that can be programmed into board Flash Image-<machine>.dtb - device tree binary (dtb). rcw/*/rcw_*.bin - rcw 2.3 Additional Instructions for Developers This section describes additional "How To" instructions for getting started with Yocto Project. Each set of instructions is aimed towards developers that are interested in modifying and configuring the source beyond the default build. Each section will describe instructions on how to use Yocto Project to achieve a specific development task Customizing U-Boot How to Configure and Rebuild U-Boot To Modify U-boot Configuration Modify UBOOT_CONFIG. Values for UBOOT_CONFIG are listed in <sdk-install-dir>/sources/meta-freescale/conf/ machine/ <machine>.conf. E.g. UBOOT_CONFIG??= "qspi" To Modify U-Boot Source Code If source code has already been installed, please skip steps 1 & 2 and proceed modifying source code. 1. $ bitbake -c cleansstate u-boot NOTE Other helpful bitbake cleaning commands: bitbake -c clean <target> Removes work directory in build_<machine>/tmp/work bitbake -c cleansstate <target> Removes work directory in build_<machine>/tmp/work Removes cache files in <sdk-install-dir>/sstate-cache/ directory. 2. $ bitbake -c patch u-boot 3. $ cd <S> and modify the source code NOTE Use bitbake -e u-boot grep ^S= to get value of <S>. NXP Semiconductors 17

18 Getting Started Additional Instructions for Developers To Rebuild U-Boot Image: 1. $ cd build_<machine> 2. $ bitbake -c compile -f u-boot 3. $ bitbake u-boot NOTE U-Boot image can be found in build_<machine>/tmp/deploy/images/<machine>/ Linux Kernel How to Configure and Rebuild the Linux Kernel 1. Modify kernel source code a. $ bitbake -c cleansstate virtual/kernel b. $ bitbake -c patch virtual/kernel c. $ cd <S> and change the source code NOTE Use bitbake -e <package-name> grep ^S= get the value of <S>. 2. Change the kernel defconfig a. $ update KERNEL_DEFCONFIG variable in meta-freescale/conf/machine/<machine>.conf 3. Change dts a. $ update KERNEL_DEVICETREE variable in meta-freescale/conf/machine/<machine>.conf 4. Do menuconfig a. $ bitbake -c menuconfig virtual/kernel NOTE If you are going to reuse this new kernel configuration for future builds, tell menuconfig to "Save Configuration to Alternate File" and give it an absolute path of /tmp/my-defconfig. If you do not do this, the new defconfig file will be removed when doing a clean/cleansstate/cleanall for kernel. NOTE This runs the normal kernel menuconfig within the Yocto environment. If the kernel configure UI cannot open, edit /<yocto_install_path>/build_<machine>_.../conf/local.conf and add the following based on your environment (prior to issuing the bitbake command). For a non-x11 environment: OE_TERMINAL = "screen" The following commands can be used for the other environments: For a GNOME environment (default): OE_TERMINAL = "gnome" For a KDE environment: OE_TERMINAL = "konsole" For non-gnome and non-kde environments: OE_TERMINAL = "xterm" 18 NXP Semiconductors

19 Getting Started Additional Instructions for Developers 5. Rebuild Kernel image a. $ cd build_<machine> b. $ bitbake -c compile -f virtual/kernel c. $ bitbake virtual/kernel NOTE Kernel images can be found in build_<machine>/tmp/deploy/images/<machine>/ Patching Packages How to Patch and Rebuild a Package 1. $ cd <sdk-install-dir>/build_<machine> 2. $ bitbake -c cleansstate <package-name> 3. $ cd <RECIPE_FOLDER> NOTE Use bitbake <package-name> -e grep ^FILE_DIR to get the value of <RECIPE_FOLDER> 4. $ mkdir -p <RECIPE_FOLDER>/files 5. Copy patch into <RECIPE_FOLDER>/files 6. Modify <BB_FILE> and add follow content in package-name-<version>.bb file SRC_URI += "file://<name-of-patch1> \ file://<name-of-patch2> \... \ file://<name-of-patchn>" 7. Rebuild this package: $ bitbake <package-name> Extract Source Code How to Extract the Source Code for a Package To extract the source code of a package, do the following: 1. $ bitbake -c cleansstate <package-name> 2. $ bitbake -c patch <package-name> 3. $ cd <S> NOTE Use bitbake -e <package-name> grep ^S= to get the value of <S>. For example, to do a U-boot of a LS1012AFRDM processor. 1. $ bitbake -c cleansstate u-boot 2. $ bitbake -c patch u-boot NOTE U-boot source code is installed in the folder: build_ls1012afrdm/tmp/work/ls1012afrdmfsl-linux/u-boot-qoriq/ git-r0/ NXP Semiconductors 19

20 Getting Started Additional Instructions for Developers Customize Root Filesystem How to Customize a Root Filesystem Packages included in a rootfs can be customized by editing the corresponding recipe: fsl-image-mfgtool:sources/meta-freescale/recipes-fsl/images/fsl-image-mfgtool.bb fsl-image-core:sources/meta-freescale/recipes-fsl/images/fsl-image-core.bb fsl-image-full:sources/meta-freescale/recipes-fsl/images/fsl-image-full.bb fsl-image-virt: sources/meta-freescale/recipes-fsl/images/fsl-image-virt.bb fsl-image-minimal:sources/meta-freescale/recipes-fsl/images/fsl-image-minimal.bb fsl-image-kernelitb:sources/meta-freescale/recipes-fsl/images/fsl-image-kernelitb.bb fsl-toolchain:sources/meta-freescale/recipes-fsl/images/fsl-tooichain.bb The rootfs type can be customized by setting the IMAGE_FSTYPES variable in the above recipes. Supported rootfs types include the following: cpio cpio.gz cpio.xz cpio.lzma cramfs ext2 ext2.gz ext2.gz.u-boot ext2.bz2.u-boot ext3 ext3.gz.u-boot ext2.lzma jffs2 live squashfs squashfs-lzma ubi tar tar.gz tar.bz2 tar.xz Path of source tarballs and patches: Package source tarballs are in the folder named sources, which is in the same folder level as build_<machine>. Patches are in the corresponding recipe folder Specify the preferred version of package: <PREFERRED_VERSION_pkgname> is used to configure the required version of a package. If <PREFERRED_VERSION> is not defined, Yocto will pick up the recent version. For example, to downgrade Samba from to 3.1.0: add PREFERRED_VERSION_samba = "3.1.0" in meta-freescale/conf/machine/<machine>.conf Rebuild rootfs: $ bitbake <image-target> Native Packages How to Build Native Packages for the Host Native packages such as cst-native are supported in Yocto. To build a native package, do the following: $ bitbake cst-native 20 NXP Semiconductors

21 Getting Started Additional Instructions for Developers NOTE The binaries can be found in build_<machine>/tmp/sysroots/x86_64-linux Standalone toolchain Build and install the standalone toolchain with Yocto: 1. $../fsl-setup-env -m <machine> 2. $ bitbake fsl-toolchain 3. $ cd build_<machine>/tmp/deploy/sdk 4. $./fsl-qoriq-glibc-<host-system>-<core>-toolchain-<release>.sh NOTE The default installation path for standalone toolchain is /opt/fsl-qoriq/ls1012a-sdk. The install folder can be specified during the installation procedure. To use the installed toolchain, go the the location where the toolchain is installed and source the environment-setup-<core> file. This will set up the correct path to the build tools and also export some environment variables relevant for development (eg. $CC, $ARCH, $CROSS_COMPILE, $LDFLAGS etc). To invoke the compiler, use the $CC variable (eg. $CC <source files>). NOTE This is a sysrooted toolchain. This means that GCC will start to look for target fragments and libraries (eg. crt*, libgcc.a) starting from the path specified by the sysroot. The default sysroot is preconfigured at build time to point to /opt/fsl-qoriq/<sdk_version>/sysroots/ <target_architecture>. If the toolchain is installed in a location other than the default one (/ opt/fsl-qoriq/), the --sysroot=<path_to_target_sysroot> parameter needs to be passed to GCC. When invoking the compiler through the $CC variable, there is no need to pass the --sysroot parameter as it is already included in the variable (check by running echo $CC) Shared State (sstate) Cache BitBake has the capability to accelerate builds based on previously built output. This is done using "shared state" files which can be thought of as cache objects and this option determines where those files are placed. The shared state cache (sstatecache), as pointed to by SSTATE_DIR. 1. Use the following setting in local.conf: SSTATE_DIR="<absolute_path_of_cache_folder>" e.g. SSTATE_DIR = "/home/yocto/sdk/sstate-cache/" NOTE Some packages have no caches because the ISO uses 4GB of space. Thus, cache size is limited by ISO size. Some packages (e.g. u-boot, kernel, rcw, depmodwrapper-cross, keymaps, base-files, merge-files, shadow-securetty, etc.) have no caches and building them requires about 20 minutes FAQ Frequently Asked Question about Yocto Q: How to install source code, modify source code and rebuild u-boot/kernel?. A: Use the following steps: NXP Semiconductors 21

22 Getting Started Additional Instructions for Developers 1. $ cd <sdk-install-dir>/build_<machine> 2. If the source code has been installed, please skip this step. $ bitbake -c patch <package-name> $ cd <S> and do change NOTE Use bitbake -e <package-name> grep ^S = to get the value of <S>. 3. Modify configure (dts can also be modified): Modify the UBOOT_CONFIG variable in meta-freescale/conf/machine/<machine>.conf or update the KERNEL_DEFCONFIG variable in meta-freescale/conf/machine/<machine>.conf 4. Rebuild images: $ cd <sdk-install-dir>/build_<machine> $ bitbake -c compile -f <package-name> $ bitbake <package-name> NOTE u-boot.bin, Image and dtb files can be found in build_<machine>/tmp/deploy/images/ <machine>. Or set <ARCH> and <CROSS_COMPILE> and build the u-boot/kernel manually Q: How to build u-boot/kernel with debugger (CodeWarrior support)? A: For u-boot: 1. $ cd <sdk-install-dir>/build_<machine> 2. $ bitbake -c cleansstate u-boot 3. Modify the u-boot-qoriq_<version>.bb file and add following content: $ cd meta-freescale/recipes-bsp/u-boot $ add 'EXTRA_OEMAKE += "CONFIG_CW=1"' in u-boot-qoriq_<version>.bb file 4. Rebuild u-boot: $ bitbake u-boot For kernel: 1. $ cd <sdk-install-dir>. 2. If kernel source code is not installed, install the kernel source code first. $ bitbake -c cleansstate virtual/kernel $ bitbake -c patch virtual/kernel 3. Configure kernel to enable CW support: $ bitbake -c menuconfig virtual/kernel Enable Kernel hacking -> Include CodeWarrior kernel debugging in kernel configuration UI. 4. Rebuild kernel: $ bitbake virtual/kernel Q: How to view the content of rootfs A: The expanded rootfs is in <IMAGE_ROOTFS> 22 NXP Semiconductors

23 Getting Started Additional Instructions for Developers NOTE Use bitbake -e <rootfs-name> grep ^IMAGE_ROOTFS= to get the value of <IMAGE_ROOTFS>. Q: How to display packages which are included in current rootfs image? A: There are three methods : $hob $bitbake -e <image-target> grep IMAGE_INSTALL $bitbake -g <image-target> Q: How to add a pre-built binary into the rootfs A: Do the following: 1. $ cd <sdk-install-dir>. 2. Add the files: $ cd meta-freescale/recipes-extended/merge-files Put the files into merge-files/merge/, e.g. put bash into merge-files/merge/usr, bash will be included in usr/ of the new rootfs. 3. Build new rootfs image: $ bitbake <rootfs-target> Q: Example of using dtc to reverse to a dts from a dtb A: Do the following 1. $ export PATH=<path-of-dtc>:$PATH 2. $ dtc -I dtb -O dts -o name-of-dts name-of-dtb Q: How to build fsl-toolchain? A: Do the following 1. $bitbake fsl-toolchain NOTE fsl-qoriq-glibc-x86_64-<target>-toolchain-<version>.sh can be found in build_<machine>/tmp/deploy/sdk/ NOTE fsl-qoriq-glibc-x86_64-<target>-toolchain-<version>.sh runs and the toolchain can be installed in special path Q: Fail to get source tarball of a packages with wget. A: Use the --no-check-certificates optionwhen Yocto uses wget to fetch source tarball from internet, the option is only available when wget was configured at build time with SSH support. Ensure that wget on your host is built with SSH support. Q: How to include toolchain in rootfs? A: The toolchain runs on target board, which is the same exact version as the cross tools in this SDK, is only included in fsl-image-full rootfs, if you want to add toolchain into other rootfs images, do the following: 1. Edit fsl-image-minimal.bb/fsl-image-core.bb/fsl-image-xxx.bb to add packagegroup-core-buildessential in the IMAGE_INSTALL variable. 2. $ bitbake <rootfs-target>. NXP Semiconductors 23

24 Getting Started Additional Instructions for Developers Q: how to use standalone toolchain to build kernel? A: If you want to build the linux kernel using toolchain, you can do the following: 1. cd <toolchain-install-path> 2. source environment-setup-<core>-fsl-linux 3. export LDFLAGS="" 4. cd <linux_source_ path> 5. make mrproper 6../scripts/kconfig/merge_config.sh arch/arm64/configs/defconfig arch/arm64/configs/freescale.config 7. make BitBake User Manual BitBake is a tool for executing tasks and managing metadata. BitBake is, at its simplest, a tool for executing tasks and managing metadata. As such, its similarities to GNU make and other build tools are readily apparent. It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the OpenEmbedded project ( which is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus and Familiar. This document is not available in PDF form. However, you may obtain the latest document at bitbake 24 NXP Semiconductors

25 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Introduction Chapter 3 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) 3.1 Introduction This chapter describes how to deploy U-Boot, Linux kernel and root file system to the NXP Reference Design Board (RDB). The guide starts with generic host and target board pre-requisites. This is followed by board-specifc configuration: Switch Settings U-Boot environment Variables Device Microcodes Management Complex (MC), DPC, DPL Reset Configuration Word (RCW) and Ethernet Interfaces (if applicable) System Memory Map Flash Bank Usage The "Switch Settings" section within each guide shows the default switch settings for the reference design board. If more information is needed beyond the scope of the default configuration, refer to the reference design board's Quick Start Guide and Reference Manual/ User Manual. For reference design boards with more than one QSPI flash, the "Programming a New U-Boot, RCW, Management Complex" section describes how the user can individually or simultaneously update U-Boot, RCW, and Management Complex, DPC, DPL by flashing them to the board's second QSPI flash prior to deployment. Once the board is set-up and configured appropriately, select one of the following deployment methods: Ramdisk deployment from TFTP Ramdisk deployment from Flash NFS deployment Harddisk deployment (if applicable) SD deployment (if applicable) Hypervisor deployment (if applicable) Each of these guides will step you through the deployment method of your choice. 3.2 Basic Host Set-up Since TFTP will be used to download files onto the target board, a TFTP server must be running on your host system. If you are going to use NFS deployment then an NFS server must also be running on your host system. Once TFTP and NFS servers are installed, use the following generic instructions to complete the host set-up: NXP Semiconductors 25

26 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Target Board Set-up 1. Create the tftboot directory. mkdir /tftpboot 2. Copy over kernel, bootloader, and flash filesystem images for your deployment to the /tftpboot directory: cp <yocto_work_dir>/build_<platform>_release/tmp/deploy/images/* /tftpboot 3. Use Yocto Project to generate a tar.gz type file system, and uncompress it in <nfs_root_path>. 4. Edit /etc/exports and add the following line: <nfs_root_path> <target_board_ip> (rw,no_root_squash, async) 5. Edit /etc/xinetd.d/tftp to enable TFTP server: service tftp { disable= no socket_type= dgram protocol= udp wait= yes user= root server= /usr/sbin/in.tftpd server_args= /tftpboot } 6. Restart the nfs and tftp servers on your host: /etc/init.d/xinetd restart /etc/init.d/nfs restart 7. Connect the board to the network. 8. Connect the target to the host via a cross cable serial connection. 9. Open a serial console tool on the host system and set it up to talk to the target board: Select appropriate serial device. Configure the serial port with the following settings: Baud rate = 115,200; Data = 8 bit; Parity = none; Stop = 1 bit; Flow control = none. Power on board and see the console prompt. NOTE (i) The Linux distribution running on your host will determine the specific instructions to use. (ii) Steps 3 and 4 are only necessary when using NFS deployment. 3.3 Target Board Set-up Once the host set-up is complete, follow these steps to set-up and power on the target board: 1. Power off the Target board system if the power is already on. 26 NXP Semiconductors

27 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Target Board Set-up 2. Connect the Target board to the network via an Ethernet port on the board. 3. Connect the Target board to the host machine via the serial port with an RS-232 cable and the joined NXP adaptor cable, if needed. 4. Start the serial console tool on the host system. 5. Verify that all switches and jumpers are setup correctly as described in the board's Reference Manual/User Guide. 6. Power on the board. Below is an example of a typical U-Boot log: U-Boot LS1012A-SDK+g7944a94 (Aug :43: ) SoC: LS1012AE (0x ) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): : : c000000c : c : c I2C: ready DRAM: 510 MiB Using SERDES1 Protocol: (0x3305) SF: Detected S25FS512S_256K with page size 512 Bytes, erase size 128 KiB, total 64 MiB In: serial Out: serial Err: serial Model: LS1012A FREEDOM Board Board: LS1012AFRDM Net: cbus_baseaddr: , ddr_baseaddr: , ddr_phys_baseaddr: class init complete tmu init complete bmu1 init: done bmu2 init: done GPI1 init complete GPI2 init complete HGPI init complete hif_tx_desc_init: Tx desc_base: e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done pfe_firmware_init pfe_load_elf: no of sections: 13 pfe_firmware_init: class firmware loaded pfe_load_elf: no of sections: 10 pfe_firmware_init: tmu firmware loaded ls1012a_configure_serdes 0 ls1012a_configure_serdes 1 pfe_eth0, pfe_eth1 Hit any key to stop autoboot: 0 NOTE If the target board does not have a working U-Boot, see System Recovery on page 54. NXP Semiconductors 27

28 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Optimizing Boot Flow (Fast Boot) 3.4 Optimizing Boot Flow (Fast Boot) Introduction Fast boot means booting the system to Linux prompt in as less time as possible. The exact time is counted from the moment power button is pressed on the board till Linux login prompt comes up. Requirement Many industrial and Internet of Things (IoT) customers are looking for systems with minimal boot-up time. They want their software and stacks to be up and running on top of Linux in no time. This creates a requirement of the system coming onto the Linux prompt as soon as possible. Components Affected Boot time reduction optimizations are done at various places: RCW, U-Boot, Linux and root filesystem. This section talks about the fast boot feature which is included as a part of this release. Enabling Fast boot Fast-boot is enabled by default at all possible places: RCW, U-Boot, Linux and root filesystem. As a result fast-boot in the default boot as a part of latest SDK release. Fast Boot versus Normal Boot Process The user will see some changes in the log which appears on the console when linux is booted. Some of the Linux boot-up messages have been suppressed and they will not be visible anymore. To see all the kernel messages/linux boot-up messages, use the dmesg command. See an example of Linux boot log below: ## Loading kernel from FIT Image at Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0x c Data Size: Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x Entry Point: 0x ## Loading ramdisk from FIT Image at Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0x96bef354 Data Size: Bytes = 23.4 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at Using 'config@1' configuration Trying 'fdt@1' fdt subimage 28 NXP Semiconductors

29 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Description: Flattened Device Tree blob Type: Flat Device Tree Compression: uncompressed Data Start: 0x96bec5f0 Data Size: Bytes = 11.2 KiB Architecture: AArch64 Loading fdt from 0x96bec5f0 to 0x Booting using the fdt blob at 0x Loading Kernel Image... OK Using Device Tree in place at , end ce1 Starting kernel... [ ] Booting Linux on physical CPU 0x0 [ ] Initializing cgroup subsys cpu [ ] Linux version rt8+g19202f1 (jenkins@neptune) (gcc version (prerelease) (Linaro GCC ) ) #1 SMP Mon Aug 22 04:38:44 CST 2016 [ ] CPU: AArch64 Processor [410fd034] revision 4 [ ] Detected VIPT I-cache on CPU0 [ ] alternatives: enabling workaround for ARM erratum [ ] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ ] bootconsole [uart0] enabled [ ] No BMan portals available! [ ] No QMan portals available! [ ] Freescale FM module, FMD API version [ ] Freescale FM Ports module [ ] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ ] fsl-mc bus not found, restool driver registration failed [ ] usb usb1-port1: over-current condition [ ] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ ] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff fb000) rcvd Populating dev cache hwclock: can't open '/dev/misc/rtc': No such file or directory Sun Aug 21 20:53:13 UTC 2016 hwclock: can't open '/dev/misc/rtc': No such file or directory Running postinst /etc/rpm-postinsts/100-sysvinit-inittab... Running postinst /etc/rpm-postinsts/101-inetutils-inetd... Running postinst /etc/rpm-postinsts/102-inetutils-ftpd... update-rc.d: /etc/init.d/run-postinsts exists during rc.d purge (continuing) Removing any system startup links for run-postinsts... INIT: Entering runlevel: 5 Configuring network interfaces... done. Starting system log daemon...0 Starting kernel log daemon...0 Starting internet superserver: xinetd. QorIQ SDK (FSL Reference Distro) 2.0 ls1012afrdm /dev/ttys0 ls1012afrdm login: 3.5 Supported Boards NXP Semiconductors 29

30 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards LS1012ARDB Overview The LS1012A reference design board (RDB) is the high-performance computing, evaluation, and development platform that supports the QorIQ LS1012A processor. This guide provides board-specific configuration and instructions for different methods of deploying U-Boot, Linux kernel and root file system to the target board Switch Settings The RDB has user selectable switches for evaluating different boot options i.e. QSPI Flash 1 for the LS1012A device. Table below lists the default switch settings and the description of these settings. Table 1. Switch configuration SW SW Below are additional switch settings for alternate boot option i.e QSPI Flash2. Table 2. Switch configuration SW SW U-Boot Environment Variables The following sections will guide the users on how to set the U-Boot environment and configure the U-Boot network parameters U-Boot Environment Variable "hwconfig" Environment variable "hwconfig" is used within the U-Boot bootloader to convey information about desired hardware configurations. It is an ordinary environment variable in that: It can be set in the U-Boot prompt using the "setenv" command. It can be removed from the U-Boot environment by setting it to an empty value, i.e. =>setenv hwconfig It can be modified in the U-Boot command prompt using the "editenv" command. It can be saved in the U-Boot environment via the "saveenv" command. Variable "hwconfig" is set to a sequence of option:value entries separated by semicolons.the default setting for for "hwconfig" on LS1012ARDB is as follows: hwconfig = fsl_ddr:bank_intlv=auto 30 NXP Semiconductors

31 Configuring U-Boot Network Parameters Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards To support TFTP based deployments, set up the U-Boot environment once, and save it, so that settings persist on subsequent resets. =>setenv ipaddr <board_ipaddress> =>setenv serverip <tftp_serverip> =>setenv gatewayip <your_gatewayip> =>setenv ethaddr <mac addr0> =>setenv eth1addr <mac addr1> =>setenv ethprime <ethx> =>setenv ethact <ethx> =>setenv netmask x.x =>saveenv NOTE (i) <ethx> is the Ethernet port on the board connected to the Linux boot server. (ii) "netmask" is subnet mask for the Linux boot server's network. Below is one example of the MAC address configuration corresponding to the set up above. Change these values to MAC addresses appropriate for your board. =>setenv ethaddr 00:04:9F:02:00:FD =>setenv eth1addr 00:04:9F:02:01:FD =>saveenv Now the flashed version of U-Boot is ready for performing TFTP based deployments. Possible <ethx> value pfe_eth0 pfe_eth RCW (Reset Configuration Word) and Ethernet Interfaces The following RCW binary is used on the LS1012ARDB board RR_SPNH_3508/PBL_0x35_0x08_800_250_1000_default.bin This RCW enables Boot from QSPI 800MHz Core, 250MHz Platfrom, 1000MT/s DDR SDHC1, SDHC2, I2C1, SerDes Protocol 0x3508 PCIe, SATA, RGMII, SGMII USB System Memory Map In 64-bit u-boot, there is a 1:1 mapping of physical address and effective address. After system startup, the boot loader maps physical address and effective address as shown in the following table: NXP Semiconductors 31

32 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Start Physical Address End Physical Address Memory Type Size 0x00_0000_0000 0x00_00FF_FFFF Secure Boot ROM 1MB 0x00_0100_0000 0x00_0FFF_FFFF CCSR 240MB 0x00_1000_0000 0x00_1000_FFFF OCRAM1 64KB 0x00_1001_0000 0x00_1001_FFFF OCRAM2 64 KB 0x00_4000_0000 0x00_5FFF_FFFF QSPI 512MB 0x00_8000_0000 0x00_FFFF_FFFF DRAM 2GB 0x08_8000_0000 0x0F_FFFF_FFFF DRAM2 30G 0x40_0000_0000 0x47_FFFF_FFFF PCI Express1 32G Flash Bank Usage LS1012ARDB has 2 QSPI flash connected over QSPI contoller. Only one QSPI flash is available at a time depending upon the board switch settings. These switch settings can also be overriden by I2C commands. To protect the default U-Boot in flash1 (aka bank1), it is a convention employed by NXP to deploy work images into the flash2 (aka bank2), and then switch to the flash2 (aka bank2) for testing. Switching to the flash2 (aka bank2) can be done in software using I2C commands and effectively swaps the flash1 (aka bank1) with the flash2 (aka bank2). This protects flash1 and keeps the board bootable under all circumstances. U-Boot g5ab5bba (Jun :56: ) SoC: LS1012AE (0x ) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): : : c000000c : : c2a I2C: ready DRAM: 1022 MiB MMU warning: gd->secure_ram is not maintained, disabled. SEC: RNG instantiated Using SERDES1 Protocol: (0x3508) MMC: FSL_SDHC: 0, FSL_SDHC: 1 SF: Detected S25FS512S_256K with page size 512 Bytes, erase size 128 KiB, total 64 MiB PCIe1: Root Complex no link, 0x In: serial Out: serial Err: serial Model: LS1012A RDB Board Board: LS1012ARDB Version: RevB, boot from QSPI: bank1 SATA link 0 timeout. AHCI slots 1 ports 6 Gbps 0x1 impl SATA mode flags: 64bit ncq pm clo only pmp fbss pio slum part ccc apst Found 0 device(s). SCSI: Net: cbus_baseaddr: , ddr_baseaddr: , ddr_phys_baseaddr: 32 NXP Semiconductors

33 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards class init complete tmu init complete bmu1 init: done bmu2 init: done GPI1 init complete GPI2 init complete HGPI init complete hif_tx_desc_init: Tx desc_base: e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done pfe_firmware_init pfe_load_elf: no of sections: 13 pfe_firmware_init: class firmware loaded pfe_load_elf: no of sections: 10 pfe_firmware_init: tmu firmware loaded ls1012a_configure_serdes 0 pfe_eth0, pfe_eth1 Hit any key to stop autoboot: 0 => How to boot from flash 2 (aka bank2) 1. To check which bank booted, refer to Board: LS1012ARDB Version: RevB, boot from QSPI: bank1" in the U-Boot logs. 2. I2C commands to flash2 bank2 switch i2c mw 0x24 0x7 0xfc; i2c mw 0x24 0x3 0xf5 3. Program QSPI flash as per flash layout 4. To boot from bank2 give reset command. 5. To move back to bank 1 from bank 2, power on/off the board or use i2c mw 0x24 0x3 0xf4 and then give reset command. QSPI flash Layout Image Size Start Address RCW + PBI 1MB 0x4000_0000 U-boot boot loader + PFE binary 1MB 0x4010_0000 U-boot Env 1MB 0x4020_0000 PPA FIT image 2MB 0x4050_0000 Kernel ITB 59MB 0x40A0_ Programming a New U-Boot, RCW, and PPA Firmware The following sections will discuss how to individually update U-Boot and RCW. For specific addresses, please refer to the QSPI Flash Memory Map as a reference. Please refer to Configuring U-Boot Network Parameters to make sure all necessary U-Boot parameters have been set. NXP Semiconductors 33

34 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Programming a New U-Boot. By default, an existing U-Boot is run in flash1 after the system is powered on or after a hard reset is performed. To flash U-Boot to the alternate flash/bank, first switch to flash 1 (bank 0) by performing a hard reset or by typing reset. Then use the following commands to change flash2/bank1 and program a new U-Boot and then switch to that flash2 or alternate bank where the new U-Boot is flashed: =>i2c mw 0x24 0x7 0xfc; i2c mw 0x24 0x3 0xf5 =>tftp 0x <u-boot_file_name>.bin =>sf probe 0:0 =>sf erase 0x $filesize =>sf write 0x x $filesize => reset Programming a New RCW:To program a new RCW, first switch to flash1 (bank 0) by performing a hard reset or by typing reset. Next, load the new RCW to RAM by downloading it via TFTP and then copying it to flash2 at offset 0x Execute the following commands at the U-Boot prompt to program the RCW to flash and reset to alternate bank. =>i2c mw 0x24 0x7 0xfc; i2c mw 0x24 0x3 0xf5 =>tftp 0x <rcw_file_name>.bin =>sf probe 0:0 =>sf erase 0x0 +$filesize =>sf write 0x x0 $filesize => reset NOTE RCW and U-Boot binary must be byte swapped using command (tclsh./byte_swap.tcl u-bootdtb.bin u-boot-dtb_swap.bin 8) Programming a New Primary Protected Application (PPA) Firmware: To program a new PPA firmware, first switch to bank 0 by performing a hard reset or by typing reset. Next, load the new PPA firmware to RAM by downloading it via TFTP and then copying it to flash at address 0x x is the location of PPA firmware in the alternate bank. Then execute the following commands at the U-Boot prompt to program the PPA firmware to flash and reset to alternate bank. => tftp 0x <ppa_file_name>.itb => sf probe 0:0 => sf erase 0x $filesize => sf write 0x x $filesize => reset NOTE All the files which are to be flashed need to be byte-swapped Deployment Each of these guides will step you through the deployment method of your choice. Please refer to the board's NOR Flash Memory Map within Flash Bank Usage as reference for specific addresses Ramdisk Deployment from TFTP 1. Setting U-Boot Environment The images generated by Yocto allow you to perform ramdisk deployment. Before performing ramdisk deployment, the U-Boot environment variables need to be configured. 34 NXP Semiconductors

35 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Refer to Configuring U-Boot Network Parameters to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for ramdisk deployment from TFTP: =>setenv bootargs ttys0, root=/dev/ram0 earlycon=uart8250,mmio,0x21c0500' =>saveenv NOTE ramdisk_size needs to be set if the ramdisk uncompress file size is bigger than default setting. It should be more than ramdisk uncompress file size. The file size information is printed in Yocto build log. 2. Booting Up the System Execute the following commands to TFTP the images to the board, then boot into Linux. =>tftp 0xa <kernel_itb_name> =>bootm 0xa Now the board will boot into Linux using the images generated by Yocto Ramdisk Deployment from Flash Programming the kernel and ramdisk into flash will allow you to boot up the board afterwards without the need to re-download images. 1. Setting U-Boot Environment The images generated by Yocto allow you to perform ramdisk deployment from flash. Before performing ramdisk deployment from flash, the U-Boot environment variables need to be configured. Refer to Configuring U-Boot Network Parameters to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for NFS deployment from flash: =>setenv bootcmd run ramargs; pfe stop; sf probe 0:0; sf read 0x xa x ; bootm 0x Now U-Boot is ready for flash deployment. 2. Programming Kernel ITB to QSPI Flash The kernel should be downloaded to the RAM using TFTP then copied to the flash address <kernel_itb_addr>. At the U- Boot prompt, use the following commands to program the kernel to flash: =>tftp 0x <kernel ITB> =>sf probe 0:0; =>sf erase <kernel_itb_addr> $filesize =>sf write 0x <kernel_itb_addr> $filesize 3. Booting Up the System The kernel can boot up automatically after the board is powered on, or the following command can be used to boot up the board at U-Boot prompt: =>boot or => run ramargs; pfe stop; sf probe 0:0; sf read 0x xa x ; bootm 0x NXP Semiconductors 35

36 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards NFS Deployment 1. Generating File System with Yocto Use Yocto to generate a tar.gz type file system, and uncompress it for NFS deployment. 2. Setting Host NFS Server Environment a. On the Linux host NFS server, add the following line in the file /etc/exports: <nfs_root_path> <board_ipaddress>(rw,no_root_squash,async) b. Restart the NFS service: /etc/init.d/nfs restart 3. Setting U-Boot Environment NOTE nfs_root_path: the NFS root directory path on NFS server. The NFS file system generated by Yocto allows you to perform NFS deployment. Before performing NFS deployment, the U-Boot environment variables need to be configured. Refer to Configuring U-Boot Network Parameters on page 31 to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for NFS deployment: =>setenv bootargs root=/dev/nfs rw nfsroot=<tftp_serverip>:<nfs_root_path> ip=<board_ipaddr>:<tftp_serverip>: <your_gatewayip>:<your_netmask>:<board_name>:eth0:off console=ttys0, =>setenv netdev <ethx> =>saveenv Now U-Boot is ready for NFS deployment. 4. Booting up the System TFTP the kernel image to the board, then boot it up. NOTE <ethx> is the port connected on the Linux boot network. =>tftp kernel.itb; =>bootm :kernel@ :fdt@1 Now the board will boot up with NFS filesystem SD Deployment Partition SD Card 1. Insert SD card into the Linux Host PC. 2. Use the "fdisk" command to repartition the SD card. # fdisk /dev/sdb 3. Use the mkfs.ext2 command to creat the filesystem. #mkfs.ext2 /dev/sdb1 36 NXP Semiconductors

37 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards NOTE When connecting the SD card on Linux host, look for the log messages on the Linux console and accordingly, only format that device (which represents SD card). 1. Insert SD card into the Linux Host PC. 2. Create temp director in host PC and mount the ext2 partition to the temp #mkdir temp #mount /dev/sdb1 temp 3. Copy the FIT Kernel Image to the SD card partition. #cp kernel.itb temp/ 4. Copy the Root File System to the SD card partition. #cp fsl-image-core-ls1043ardb_<release date>.rootfs.tar.gz temp/ #tar xvfz fsl-image-core-ls1043ardb_<release date>.rootfs.tar.gz #rm fsl-image-core-ls1043ardb_<release date>.rootfs.tar.gz temp/ 5. Umount the temp director #umount temp Setting U-Boot Environment Execute the following commands at the U-Boot prompt => setenv bootcmd "ext2load mmc 0 a kernel.itb && bootm a " Using the Ramdisk as the Root File Systemp => setenv bootargs "root=/dev/ram0 earlycon=uart8250,mmio,0x21c0500 console=ttys0,115200" Using the Ext2 Partition of SD card as the Root File Systemp => setenv bootargs "root=/dev/mmcblk0p1 rw earlycon=uart8250,0x21c0500 console=ttys0,115200" Saving the environment =>saveenv Note: The kernel.itb is the name of your FIT Image, you can use the ext2ls command to list it at the U-Boot prompt Check 'Link Up' for Serial Ethernet Interfaces This section provides some basic checks that can be performed in U-Boot to help diagnose the cause of the networking errors when experiencing problems with Ethernet interfaces. Check Communication to External PHY In order to check if U-Boot can communicate with the PHYs on the board, use the U-Boot command mdio list. The U-Boot command mdio list will display all manageable Ethernet PHYs. Example: => mdio list PFE_MDIO: 1 - RealTek RTL8211F <--> pfe_eth1 2 - RealTek RTL8211F <--> pfe_eth0 The results from the mdio list command above show that U-Boot was able to see PHYs on each of the RGMII/SGMII interfaces. NXP Semiconductors 37

38 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Check Link Status for External PHY In order to check the status of a RGMII/SGMII link, use the mdio read command. Since this is a Clause 22 device, we pass two arguments to the mdio read command. mdio read <PHY address> <REGISTER Address> Example: => mdio read pfe_eth0 1 Reading from bus PFE_MDIO PHY at address 2: 1-0x79ad => mdio read pfe_eth1 1 Reading from bus PFE_MDIO PHY at address 1: 1-0x79ad The link partner ( copper side ) link status bit is in Register #1 on the PHY. The 'Link Status' bit is bit #2 (from the left) of the last nibble. In the example above, the nibble of interest is "d" (d = b'1101'), and therefore the 'Link Status' = 1, which means 'link up'. If the link were down this bit would be a "0," and we would see 0x Basic Networking Ping Test U-BOOT The LS1012ARDB has one SGMII and one RGMII. The log below shows how to ping from those 2 interfaces. U-Boot gc (Jun :06: ) SoC: LS1012AE (0x ) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): : : c000000c : : c2a I2C: ready DRAM: 1022 MiB MMU warning: gd->secure_ram is not maintained, disabled. SEC: RNG instantiated Using SERDES1 Protocol: (0x3508) MMC: FSL_SDHC: 0, FSL_SDHC: 1 SF: Detected S25FS512S_256K with page size 512 Bytes, erase size 128 KiB, total 64 MiB PCIe1: Root Complex no link, 0x In: serial Out: serial Err: serial Model: LS1012A RDB Board Board: LS1012ARDB Version: RevB, boot from QSPI: bank1 SATA link 0 timeout. AHCI slots 1 ports 6 Gbps 0x1 impl SATA mode flags: 64bit ncq pm clo only pmp fbss pio slum part ccc apst Found 0 device(s). SCSI: Net: cbus_baseaddr: , ddr_baseaddr: , ddr_phys_baseaddr: class init complete 38 NXP Semiconductors

39 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards tmu init complete bmu1 init: done bmu2 init: done GPI1 init complete GPI2 init complete HGPI init complete hif_tx_desc_init: Tx desc_base: e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done pfe_firmware_init pfe_load_elf: no of sections: 13 pfe_firmware_init: class firmware loaded pfe_load_elf: no of sections: 10 pfe_firmware_init: tmu firmware loaded ls1012a_configure_serdes 0 pfe_eth0, pfe_eth1 Hit any key to stop autoboot: 0 => setenv ethaddr 11:22:33:44:55:55 => setenv eth1addr 11:22:33:44:55:66 => setenv serverip ;setenv ipaddr => ping $serverip Speed detected 3e8 Using pfe_eth0 device host is alive => edit ethact edit: pfe_eth1 => ping $serverip Speed detected 3e8 Using pfe_eth1 device host is alive LINUX To enable PFE in Linux, first stop PFE in U-Boot. In order to do this, first bring the kernel-ls1012a-rdb.itb via PFE interface then type pfe stop command on the U-Boot prompt: => tftp 0xa kernel-ls1012a-rdb.itb Speed detected 3e8 Using pfe_eth1 device TFTP from server ; our IP address is Filename 'kernel-ls1012a-rdb.itb'. Load address: 0xa Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# NXP Semiconductors 39

40 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ############ 5.6 MiB/s done Bytes transferred = (2490f5b hex) => pfe stop Stopping PFE... => bootm 0xa ## Loading kernel from FIT Image at a Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0xa00000dc Data Size: Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x Entry Point: 0x ## Loading ramdisk from FIT Image at a Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: LS2 Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0xa0be9ba4 Data Size: Bytes = 24.7 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at a Using 'config@1' configuration 40 NXP Semiconductors

41 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Trying 'fdt@1' fdt subimage Description: Flattened Device Tree blob Type: Flat Device Tree Compression: uncompressed Data Start: 0xa0be7790 Data Size: 9101 Bytes = 8.9 KiB Architecture: AArch64 Loading fdt from 0xa0be7790 to 0x Booting using the fdt blob at 0x Loading Kernel Image... OK Using Device Tree in place at , end c Starting kernel... [ ] Booting Linux on physical CPU 0x0 [ ] Initializing cgroup subsys cpu [ ] Linux version rt8+g2511ec0 (jenkins@neptune) (gcc version (prerelease) (Linaro GCC ) ) #1 SMP Sat Aug 27 04:44:19 CST 2016 [ ] CPU: AArch64 Processor [410fd034] revision 4 [ ] Detected VIPT I-cache on CPU0 [ ] alternatives: enabling workaround for ARM erratum [ ] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ ] bootconsole [uart0] enabled [ ] No BMan portals available! [ ] No QMan portals available! [ ] Freescale FM module, FMD API version [ ] Freescale FM Ports module [ ] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ ] fsl-mc bus not found, restool driver registration failed [ ] usb usb1-port1: over-current condition [ ] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ ] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff fb000) rcvd Populating dev cache hwclock: can't open '/dev/misc/rtc': No such file or directory Fri Aug 26 20:58:57 UTC 2016 hwclock: can't open '/dev/misc/rtc': No such file or directory Running postinst /etc/rpm-postinsts/100-sysvinit-inittab... Running postinst /etc/rpm-postinsts/101-inetutils-inetd... Running postinst /etc/rpm-postinsts/102-inetutils-ftpd... update-rc.d: /etc/init.d/run-postinsts exists during rc.d purge (continuing) Removing any system startup links for run-postinsts... INIT: Entering runlevel: 5 Configuring network interfaces... done. Starting system log daemon...0 Starting kernel log daemon...0 Starting internet superserver: xinetd. QorIQ SDK (FSL Reference Distro) 2.0 ls1012ardb /dev/ttys0 ls1012ardb login: root root@ls1012ardb:~# find / -name pfe.ko /lib/modules/4.1.8+g4b2f599/kernel/drivers/staging/fsl_ppfe/pfe.ko root@ls1012ardb:~# insmod /lib/modules/4.1.8+g4b2f599/kernel/drivers/staging/fsl_ppfe/pfe.ko [ ] pfe: module is from the staging directory, the quality is unknown, you have been warned. [ ] cbus_baseaddr: ffff , ddr_baseaddr: ffff , ddr_phys_baseaddr: , ddr_size: c00000 [ ] pfe_hw_init NXP Semiconductors 41

42 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards [ ] CLASS version: 20 [ ] TMU version: [ ] BMU1 version: 21 [ ] BMU2 version: 21 [ ] EGPI1 version: 50 [ ] EGPI2 version: 50 [ ] HGPI version: 50 [ ] GPT version: 0 [ ] HIF version: 10 [ ] HIF NOPCY version: 10 [ ] bmu_init(1) done [ ] bmu_init(2) done [ ] class_init() done [ ] tmu_init() done [ ] gpi_init(1) done [ ] gpi_init(2) done [ ] gpi_init(hif) done [ ] bmu_enable(1) done [ ] bmu_enable(2) done [ ] pfe_hif_lib_init [ ] pfe_hif_init [ ] pfe_hif_alloc_descr [ ] pfe_hif_init_buffers [ ] pfe_firmware_init [ ] pfe_load_elf [ ] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff b000) rcvd [ ] PFE binary version: pfe_ls1012a_00_1-dirty [ ] pfe_firmware_init: class firmware loaded 0xa60 0xc [ ] pfe_load_elf [ ] pfe_firmware_init: tmu firmware loaded 0x200 [ ] pfe_ctrl_init [ ] pfe_ctrl_init finished [ ] pfe_eth_init [ ] pfe_eth_mdio_init [ ] pfe_ctrl_timer [ ] libphy: Comcerto MDIO Bus: probed [ ] pfe_phy_init interface 3 [ ] eth0: pfe_eth_init_one: created interface, baseaddr: ffff000000a80000 [ ] pfe_phy_init interface 7 [ ] eth1: pfe_eth_init_one: created interface, baseaddr: ffff000000aa0000 [ ] pfe_debugfs_init root@ls1012ardb:~# ifconfig -a eth0 Link encap:ethernet HWaddr 00:1a:2b:3c:4d:5e BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) eth1 lo Link encap:ethernet HWaddr 00:aa:bb:cc:dd:ee BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Link encap:local Loopback inet addr: Mask: inet6 addr: ::1/128 Scope:Host 42 NXP Semiconductors

43 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards UP LOOPBACK RUNNING MTU:65536 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:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) sit0 Link encap:unspec HWaddr A is insmod a NOARP MTU:1480 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:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) root@ls1012ardb:~# ifconfig eth up [ ] eth1: pfe_eth_open [ ] hif_process_client_req: register client_id 1 [ ] pfe_hif_client_register [ ] eth1: pfe_gemac_init root@ls1012ardb:~# [ ] eth1: Link is Up - 1Gbps/Full - flow control rx/tx root@ls1012ardb:~# root@ls1012ardb:~# root@ls1012ardb:~# root@ls1012ardb:~# ping PING ( ) 56(84) bytes of data. 64 bytes from : icmp_seq=1 ttl=128 time=1.81 ms 64 bytes from : icmp_seq=2 ttl=128 time=0.883 ms ^C ping statistics packets transmitted, 2 received, 0% packet loss, time 1001ms rtt min/avg/max/mdev = 0.883/1.347/1.811/0.464 ms root@ls1012ardb:~# NOTE Yocto users do not need to install the pfe.ko module. However, developers who are building the kernel need to install the pfe.ko module. Once the pfe.ko module is installed, the pfe interfaces will function like normal ethernet interfaces e.g. eth0, eth FRDM-LS1012A Switch Settings No On-Board Switch setting available U-Boot Environment Variables The following sections will guide the users on how to set the U-Boot environment and configure the U-Boot network parameters U-Boot Environment Variable "hwconfig" Environment variable "hwconfig" is used within the U-Boot bootloader to convey information about desired hardware configurations. It is an ordinary environment variable in that: It can be set in the U-Boot prompt using the "setenv" command. It can be removed from the U-Boot environment by setting it to an empty value, i.e. NXP Semiconductors 43

44 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards =>setenv hwconfig It can be modified in the U-Boot command prompt using the "editenv" command. It can be saved in the U-Boot environment via the "saveenv" command. Variable "hwconfig" is set to a sequence of option:value entries separated by semicolons.the default setting for for "hwconfig" on LS1012ARDB is as follows: hwconfig = fsl_ddr:bank_intlv=auto Configuring U-Boot Network Parameters To support TFTP based deployments, set up the U-Boot environment once, and save it, so that settings persist on subsequent resets. =>setenv ipaddr <board_ipaddress> =>setenv serverip <tftp_serverip> =>setenv gatewayip <your_gatewayip> =>setenv ethaddr <mac addr0> =>setenv eth1addr <mac addr1> =>setenv ethprime <ethx> =>setenv ethact <ethx> =>setenv netmask x.x =>saveenv NOTE (i) <ethx> is the Ethernet port on the board connected to the Linux boot server. (ii) "netmask" is subnet mask for the Linux boot server's network. Below is one example of the MAC address configuration corresponding to the set up above. Change these values to MAC addresses appropriate for your board. =>setenv ethaddr 00:04:9F:02:00:FD =>setenv eth1addr 00:04:9F:02:01:FD =>saveenv Now the flashed version of U-Boot is ready for performing TFTP based deployments. Possible <ethx> value pfe_eth0 pfe_eth RCW (Reset Configuration Word) and Ethernet Interfaces The following RCW binary is used on the FRDM-LS1012A board: S_SPNN_3305/PBL_0x33_0x05_800_250_1000_default.bin This RCW enables: Boot from QSPI 800MHz Core, 250MHz Platfrom, 1000MT/s DDR I2C1, SerDes Protocol 0x NXP Semiconductors

45 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards SGMII, SGMII USB System Memory Map In 64-bit u-boot, there is a 1:1 mapping of physical address and effective address. After system startup, the boot loader maps physical address and effective address as shown in the following table: Start Physical Address End Physical Address Memory Type Size 0x00_0000_0000 0x00_00FF_FFFF Secure Boot ROM 1MB 0x00_0100_0000 0x00_0FFF_FFFF CCSR 240MB 0x00_1000_0000 0x00_1000_FFFF OCRAM1 64KB 0x00_1001_0000 0x00_1001_FFFF OCRAM2 64 KB 0x00_4000_0000 0x00_5FFF_FFFF QSPI 512MB 0x00_8000_0000 0x00_FFFF_FFFF DRAM 2GB 0x08_8000_0000 0x0F_FFFF_FFFF DRAM2 30G 0x40_0000_0000 0x47_FFFF_FFFF PCI Express1 32G Flash Bank Usage The FRDM-LS1012A only has one QSPI flash connected over QSPI contoller. U-Boot g1c18d6a (Jun :15: ) SoC: LS1012AE (0x ) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): : : c000000c : c : c I2C: ready DRAM: 510 MiB MMU warning: gd->secure_ram is not maintained, disabled. Using SERDES1 Protocol: (0x3305) SF: Detected S25FS512S_256K with page size 512 Bytes, erase size 128 KiB, total 64 MiB In: serial Out: serial Err: serial Model: LS1012A FREEDOM Board Board: LS1012AFRDM Net: cbus_baseaddr: , ddr_baseaddr: , ddr_phys_baseaddr: class init complete tmu init complete bmu1 init: done bmu2 init: done NXP Semiconductors 45

46 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards GPI1 init complete GPI2 init complete HGPI init complete hif_tx_desc_init: Tx desc_base: e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done pfe_firmware_init pfe_load_elf: no of sections: 13 pfe_firmware_init: class firmware loaded pfe_load_elf: no of sections: 10 pfe_firmware_init: tmu firmware loaded ls1012a_configure_serdes 0 ls1012a_configure_serdes 1 pfe_eth0, pfe_eth1 Hit any key to stop autoboot: 0 QSPI flash Layout Image Size Start Address RCW + PBI 1MB 0x4000_0000 U-boot boot loader + PPFE binary 1MB 0x4010_0000 U-boot Env 1MB 0x4020_0000 PPA FIT image 2MB 0x4050_0000 Kernel ITB 59MB 0x40A0_ Programming a New U-Boot and RCW The following sections will discuss how to individually update U-Boot and RCW. For specific addresses, please refer to the QSPI Flash Memory Map as a reference. Please refer to Configuring U-Boot Network Parameters to make sure all necessary U-Boot parameters have been set. Programming a New U-Boot. Use the commands below to update images: =>tftp 0x <u-boot_file_name>.bin =>sf probe 0:0 =>sf erase 0x xa0000 =>sf write 0x x $filesize => reset The commands above will only program a new U-Boot. Programming a new RCW will be discussed in the next section. Programming a New RCW:Use the commands below to update images: =>tftp 0x <rcw_file_name>.bin =>sf probe 0:0 =>sf erase 0x =>sf write 0x x0 $filesize => reset 46 NXP Semiconductors

47 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Note: RCW and U-Boot binaries must be byte swapped using command (tclsh./byte_swap.tcl u-boot-dtb.bin u-bootdtb_swap.bin 8). The./byte_swap.tcl script is included as a part od the RCW source code Deployment Each of these guides will step you through the deployment method of your choice. Please refer to the board's NOR Flash Memory Map within Flash Bank Usage as reference for specific addresses Ramdisk Deployment from TFTP 1. Setting U-Boot Environment The images generated by Yocto allow you to perform ramdisk deployment. Before performing ramdisk deployment, the U-Boot environment variables need to be configured. Refer to Configuring U-Boot Network Parameters to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for ramdisk deployment from TFTP: =>setenv bootargs ttys0, root=/dev/ram0 earlycon=uart8250,mmio,0x21c0500' =>saveenv NOTE ramdisk_size needs to be set if the ramdisk uncompress file size is bigger than default setting. It should be more than ramdisk uncompress file size. The file size information is printed in Yocto build log. 2. Booting Up the System Execute the following commands to TFTP the images to the board, then boot into Linux. =>tftp 0x <kernel_itb_name> =>bootm 0x NOTE The DDR load address for LS1012ARDB is different from FRDM-LS1012A. Using the wrong address could crash Linux. Now the board will boot into Linux using the images generated by Yocto Ramdisk Deployment from Flash Programming the kernel and ramdisk into flash will allow you to boot up the board afterwards without the need to re-download images. 1. Setting U-Boot Environment The images generated by Yocto allow you to perform ramdisk deployment from flash. Before performing ramdisk deployment from flash, the U-Boot environment variables need to be configured. Refer to Configuring U-Boot Network Parameters to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for NFS deployment from flash: =>setenv bootcmd run ramargs; pfe stop; sf probe 0:0; sf read 0x xa x ; bootm 0x Now U-Boot is ready for flash deployment. 2. Programming Kernel ITB to QSPI Flash NXP Semiconductors 47

48 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards The kernel should be downloaded to the RAM using TFTP then copied to the flash address <kernel_itb_addr>. At the U- Boot prompt, use the following commands to program the kernel to flash: =>tftp 0x <kernel ITB> =>sf probe 0:0; =>sf erase <kernel_itb_addr> $filesize =>sf write 0x <kernel_itb_addr> $filesize 3. Booting Up the System The kernel can boot up automatically after the board is powered on, or the following command can be used to boot up the board at U-Boot prompt: =>boot or => run ramargs; pfe stop; sf probe 0:0; sf read 0x xa x ; bootm 0x NFS Deployment 1. Generating File System with Yocto Use Yocto to generate a tar.gz type file system, and uncompress it for NFS deployment. 2. Setting Host NFS Server Environment a. On the Linux host NFS server, add the following line in the file /etc/exports: <nfs_root_path> <board_ipaddress>(rw,no_root_squash,async) b. Restart the NFS service: /etc/init.d/nfs restart 3. Setting U-Boot Environment NOTE nfs_root_path: the NFS root directory path on NFS server. The NFS file system generated by Yocto allows you to perform NFS deployment. Before performing NFS deployment, the U-Boot environment variables need to be configured. Refer to Configuring U-Boot Network Parameters on page 31 to set the U-Boot environment variables. In addition, execute the following commands at the U-Boot prompt to prepare for NFS deployment: =>setenv bootargs root=/dev/nfs rw nfsroot=<tftp_serverip>:<nfs_root_path> ip=<board_ipaddr>:<tftp_serverip>: <your_gatewayip>:<your_netmask>:<board_name>:eth0:off console=ttys0, =>setenv netdev <ethx> =>saveenv Now U-Boot is ready for NFS deployment. NOTE <ethx> is the port connected on the Linux boot network. 48 NXP Semiconductors

49 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards 4. Booting up the System TFTP the kernel image to the board, then boot it up. =>tftp kernel.itb; =>bootm :kernel@ :fdt@1 Now the board will boot up with NFS filesystem Check 'Link Up' for Serial Ethernet Interfaces This section provides some basic checks that can be performed in U-Boot to help diagnose the cause of the networking errors when experiencing problems with Ethernet interfaces. Check Communication to External PHY In order to check if U-Boot can communicate with the PHYs on the board, use the U-Boot command mdio list. The U-Boot command mdio list will display all manageable Ethernet PHYs. Example: => mdio list PFE_MDIO: 1 - RealTek RTL8211F <--> pfe_eth1 2 - RealTek RTL8211F <--> pfe_eth0 The results from the mdio list command above show that U-Boot was able to see PHYs on each of the SGMII interfaces. Check Link Status for External PHY In order to check the status of a SGMII link, use the mdio read command. Since this is a Clause 22 device, we pass two arguments to the mdio read command. mdio read <PHY address> <REGISTER Address> Example: => mdio read pfe_eth0 1 Reading from bus PFE_MDIO PHY at address 2: 1-0x79ad => mdio read pfe_eth1 1 Reading from bus PFE_MDIO PHY at address 1: 1-0x79ad The link partner ( copper side ) link status bit is in Register #1 on the PHY. The 'Link Status' bit is bit #2 (from the left) of the last nibble. In the above example the nibble of interest is "d" (d = b'1101'), and therefore the 'Link Status' = 1, which means 'link up'. If the link were down this bit would be a "0," and we would see 0x7989. NXP Semiconductors 49

50 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Basic Networking Ping Test U-BOOT The LS1012FRDM has 2 SGMII interfaces. The log below shows how to ping from those 2 interfaces. U-Boot g1c18d6a (Jun :15: ) SoC: LS1012AE (0x ) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): : : c000000c : c : c I2C: ready DRAM: 510 MiB MMU warning: gd->secure_ram is not maintained, disabled. Using SERDES1 Protocol: (0x3305) SF: Detected S25FS512S_256K with page size 512 Bytes, erase size 128 KiB, total 64 MiB In: serial Out: serial Err: serial Model: LS1012A FREEDOM Board Board: LS1012AFRDM Net: cbus_baseaddr: , ddr_baseaddr: , ddr_phys_baseaddr: class init complete tmu init complete bmu1 init: done bmu2 init: done GPI1 init complete GPI2 init complete HGPI init complete hif_tx_desc_init: Tx desc_base: e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done pfe_firmware_init pfe_load_elf: no of sections: 13 pfe_firmware_init: class firmware loaded pfe_load_elf: no of sections: 10 pfe_firmware_init: tmu firmware loaded ls1012a_configure_serdes 0 ls1012a_configure_serdes 1 pfe_eth0, pfe_eth1 Hit any key to stop autoboot: 0 => setenv ethaddr 11:22:33:44:55:55 => setenv eth1addr 11:22:33:44:55:66 => setenv serverip ;setenv ipaddr => edit ethact edit: pfe_eth1 => ping $serverip Speed detected 3e8 Using pfe_eth1 device host is alive 50 NXP Semiconductors

51 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards => edit ethact edit: pfe_eth0 => ping $serverip Speed detected 3e8 Using pfe_eth0 device host is alive => LINUX To enable PFE in Linux, First we need to stop pfe in u-boot but first bring the kernel-ls1012a-frdm.itb via pfe interface, then perform pfe stop On U-Boot prompt: => tftp 0x kernel-ls1012a-frdm.itb Speed detected 3e8 Using pfe_eth0 device TFTP from server ; our IP address is Filename 'kernel-ls1012a-frdm.itb'. Load address: 0x Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# 2.5 MiB/s done Bytes transferred = (26bfe67 hex) => pfe stop Stopping PFE... => bootm 0x ## Loading kernel from FIT Image at Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0x c Data Size: Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x Entry Point: 0x ## Loading ramdisk from FIT Image at Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0x96bef354 NXP Semiconductors 51

52 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards Data Size: Bytes = 23.4 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at Using 'config@1' configuration Trying 'fdt@1' fdt subimage Description: Flattened Device Tree blob Type: Flat Device Tree Compression: uncompressed Data Start: 0x96bec5f0 Data Size: Bytes = 11.2 KiB Architecture: AArch64 Loading fdt from 0x96bec5f0 to 0x Booting using the fdt blob at 0x Loading Kernel Image... OK Using Device Tree in place at , end ce1 Starting kernel... [ ] Booting Linux on physical CPU 0x0 [ ] Initializing cgroup subsys cpu [ ] Linux version rt8+g2511ec0 (jenkins@neptune) (gcc version (prerelease) (Linaro GCC ) ) #1 SMP Sat Aug 27 04:44:19 CST 2016 [ ] CPU: AArch64 Processor [410fd034] revision 4 [ ] Detected VIPT I-cache on CPU0 [ ] alternatives: enabling workaround for ARM erratum [ ] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ ] bootconsole [uart0] enabled [ ] No BMan portals available! [ ] No QMan portals available! [ ] Freescale FM module, FMD API version [ ] Freescale FM Ports module [ ] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ ] fsl-mc bus not found, restool driver registration failed [ ] usb usb1-port1: over-current condition [ ] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ ] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff fb000) rcvd Populating dev cache hwclock: can't open '/dev/misc/rtc': No such file or directory Fri Aug 26 20:58:57 UTC 2016 hwclock: can't open '/dev/misc/rtc': No such file or directory Running postinst /etc/rpm-postinsts/100-sysvinit-inittab... Running postinst /etc/rpm-postinsts/101-inetutils-inetd... Running postinst /etc/rpm-postinsts/102-inetutils-ftpd... update-rc.d: /etc/init.d/run-postinsts exists during rc.d purge (continuing) Removing any system startup links for run-postinsts... INIT: Entering runlevel: 5 Configuring network interfaces... done. Starting system log daemon...0 Starting kernel log daemon...0 Starting internet superserver: xinetd. QorIQ SDK (FSL Reference Distro) 2.0 ls1012afrdm /dev/ttys0 ls1012afrdm login: 52 NXP Semiconductors

53 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Supported Boards root@ls1012afrdm:~# root@ls1012afrdm:~# [ ] eth0: Link is Up - 1Gbps/Full - flow control rx/tx root@ls1012afrdm:~# ping PING ( ) 56(84) bytes of data. 64 bytes from : icmp_seq=1 ttl=128 time=1.92 ms 64 bytes from : icmp_seq=2 ttl=128 time=1.51 ms 64 bytes from : icmp_seq=3 ttl=128 time=1.44 ms ^C ping statistics packets transmitted, 3 received, 0% packet loss, time 2002ms rtt min/avg/max/mdev = 1.440/1.625/1.925/0.214 ms root@ls1012afrdm:~# root@ls1012afrdm:~# ifconfig -a eth0 Link encap:ethernet HWaddr 00:1a:2b:3c:4d:5e inet addr: Bcast: Mask: inet6 addr: fe80::21a:2bff:fe3c:4d5e/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:39 errors:0 dropped:0 overruns:0 frame:0 TX packets:11 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:9165 (8.9 KiB) TX bytes:894 (894.0 B) eth1 Link encap:ethernet HWaddr 00:aa:bb:cc:dd:ee BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) lo Link encap:local Loopback inet addr: Mask: inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 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:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) sit0 Link encap:unspec HWaddr A NOARP MTU:1480 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:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) root@ls1012afrdm:~# NOTE Yocto users do not need to install the pfe.ko module. However, developers who are building the kernel need to install the pfe.ko module. Once the pfe.ko module is installed, the pfe interfaces will function like normal ethernet interfaces e.g. eth0, eth1. NXP Semiconductors 53

54 System Recovery Environment Setup Chapter 4 System Recovery 4.1 Environment Setup Environment Setup (Common) The section describes the related setup for system recovery 1. Required Materials Target board The related recovery image files 2. Host PC setup The host PC should have a serial-terminal program capable of running at 115,200bps, 8-N-1, for communicating with U- Boot running on the target board. 3. Target board setup a. Power off the target board system if the power is already on. b. If U-Boot runs on this board, and U-Boot commands will be used to reflash the U-Boot images, connect the target board to the network via the etsec port on the board. c. Connect the target board to the host machine via the serial port with an RS-232 cable and the joined NXP adapter cable, if needed. d. Set up the serial terminal in the host machine with 115,200bps, 8-N-1, no flow control. e. Verify all the switches and jumpers are set up correctly to default values described in <Hardware configurations> as described in the Switch Settings section of the board's Software Deployment Guide f. Connect the JTAG cable for your CodeWarrior TAP or Gigabit TAP to the board if you will be using the CodeWarrior Flash Programmer to recover the board image. g. Power on the board. 4.2 Image Recovery Recover system with already working U-Boot Target Board Setup 1. Power off the target board system if the power is already on. 2. Connect the target board to the network via the etsec port on the board. 3. Connect the target board to the host machine via the serial port with an RS-232 cable and the joined NXP adaptor cable, if needed. 4. Set up the serial terminal in the host machine with 115,200bps, 8-N-1, no flow control. 5. Verify all the switches and jumpers are setup correctly to default value described in the board's "Switch Settings" section in the board's Software Deployment Guide. 54 NXP Semiconductors

55 System Recovery Image Recovery 6. Power on the board. Refer to the Programming a New U-Boot section in the Software Deployment Guide for the target board to be recovered Recover system using CodeWarrior Flash Programmer Environment Setup Required Materials Target board. CodeWarrior for Power Architecture v10.x (for Windows or Linux) CodeWarrior TAP or Gigabit TAP run control device. The related recovery image files. Host PC setup The host PC is assumed to be running Windows 7, or one of the supported distributions of Linux (refer to the CodeWarrior PA10 Release Notes for the list of supported Linux distributions). This machine should have latest CodeWarrior PA10 installed and working correctly. If the run control device is a CodeWarrior TAP used over USB, then the USB drivers should be installed automatically when the device is plugged in. If the run control device is a CodeWarrior TAP used over Ethernet, or a Gigabit TAP, then both the host PC and TAP should be connected to the network, and communications between them should be verified. Target board setup 1. Power off the Target board system if the power is already on. 2. Connect the Target board to the host machine via the serial port with an RS-232 cable and the joined NXP adaptor cable, if needed. 3. Set up the serial terminal in the host machine with 115,200bps, 8-N-1, no flow control. 4. Verify all the switches and jumpers are set up correctly to default values described in the "Switch Settings" section in the board's Software Deployment Guide. 5. Connect the TAP's JTAG cable to the board. 6. Power on the board. System Recovery 1. Start the CodeWarrior PA10 or ARMv7 IDE. 2. For LS102x targets, see Chapter 3 of Getting Started for ARMv7 Processors.pdf in the CodeWarrior ARMv7 installation for steps on creating a BareBoard Core0 project for the LS102x processor on this target board. For other QorIQ targets, see Quick Start for PA 10 Processors.pdf in the CodeWarrior PA10 installation for steps on creating a BareBoard AMP Core0 project for the QorIQ processor on this target board. In the "Debug Target Settings Page", of the procedure for creating a new project, uncheck the 'Download' option, and enable the 'Download SRAM' option, if available. 3. Select your CodeWarrior TAP or Gigabit TAP as your debug connection type. For CodeWarrior TAP, select USB or Ethernet as the connection medium. 4. Build the project. 5. Bring up the Target Tasks view: go to Window>Show View>Other>Debug>Target Task. 6. Import the Flash Profile: a. In the Target Tasks view, click on the Import button. A file-browser window will appear, showing the "Flash_Programmer" folder. NXP Semiconductors 55

56 System Recovery Image Recovery b. Open the "Flash_Programmer" folder, then the folder associated with the processor family on this target board. c. Select the configuration file for the particular target and flash device to be programmed on this target board, and click OK to import it. This file will appear in the Target Tasks view. 7. In the board's Software Deployment Guide, locate the Flash Bank Usage section for the target board to be recovered. a. Identify the NOR/NAND/SPI flash memory map that applies to the flash to be programmed. For the following steps, if the target flash supports multiple banks, choose the starting addresses for Bank0 or current bank, as appropriate. b. Identify the starting address for the u-boot image. c. Identify the starting address for the RCW image (if applicable). d. Identify the starting address for the PPA image (if applicable). e. Identify the starting address for the ucode/microcode (if applicable). f. Identify the starting address for the dtb image. g. Identify the starting address for the RamDisk image. h. Identify the starting address for the Linux Kernel image. 8. Configure Flash Programmer. a. Double-click on the file name that was imported with the flash profile, to bring up the Flash Programmer Task view. b. Click on 'Add Action'>'Program/Verify'. c. Set 'File Type' to "Binary". d. Click on 'File System' and navigate to the folder containing the u-boot binary image. e. Enable "Erase sectors before program". f. Enable "Apply address offset", and enter the starting address where this binary recovery image will be flashed (see the tables in the previous step for examples). g. (OPTIONAL) Enable 'Verify after program' to verify that the flash programming was successful. h. Repeat steps (starting with Click 'Add Action') above for each binary image file to be programmed into flash. 9. Execute Flash Programming. a. In the Target Tasks view, right-click on the imported filename and select the green Execute button to launch the programmer. b. If Execute is not green, the debugger is not running. The debugger must be running for this flash programmer to work. c. When finished flashing, terminate the debugger. 10.This is the end of the process. Now the boot loader, kernel and root file system are programmed to flash. 11. Reset or power-cycle the board and verify that u-boot appears in the board s serial terminal. 56 NXP Semiconductors

57 About Yocto Project Yocto Project Quick Start Chapter 5 About Yocto Project 5.1 Yocto Project Quick Start The Yocto Project Quick Start explains basic concepts and the use of its core components. Step through a simple example to show how to build a small image and run it using the QEMU emulator. For more information see the Yocto Project Quick Start 5.2 Application Development Toolkit User's Guide The Application Development Toolkit consists of an architecture-specific cross-toolchain and a matching sysroot that are both built by the Yocto Project build system Poky. For more information see the Application Development Toolkit User's Guide located in the following SDK directory: sdk_documentation/pdf/yocto/adt-manual.pdf For more information see the Application Development Toolkit User's Guide 5.3 Board Support Packages - Developer's Guide A Board Support Package (BSP) is a collection of information that defines how to support a particular hardware device, set of devices, or hardware platform. The BSP includes information about the hardware features present on the device and kernel configuration information along with any additional hardware drivers required. For more information see the Board Support Packages - Developer's Guide located in the following SDK directory: sdk_documentation/pdf/yocto/bsp-guide.pdf For more information see the Board Support Packages - Developer's Guide 5.4 Yocto Project Development Manual Use a Yocto Project to develop embedded Linux images and user-space applications to run on targeted devices. For more information see the Yocto Project Development Manual located in the following SDK directory: sdk_documentation/ pdf/yocto/dev-manual.pdf For more information see the Yocto Project Development Manual 5.5 Yocto Project Linux Kernel Development Manual The Yocto Project Linux Kernel Development Manual describes how to work with Linux Yocto kernels and provides some conceptual information on the construction of the Yocto Linux kernel tree. For more information see the Yocto Project Linux Kernel Development Manual located in the following SDK directory: sdk_documentation/pdf/yocto/kernel-dev.pdf NXP Semiconductors 57

58 About Yocto Project Yocto Project Profiling and Tracing Manual For more information see the Yocto Project Linux Kernel Development Manual 5.6 Yocto Project Profiling and Tracing Manual The Yocto Project Profiling and Tracing Manual presents a set of common and generally useful tracing and profiling schemes along with their applications (as appropriate) to each tool. For more information see the Yocto Project Profiling and Tracing Manual located in the following SDK directory: sdk_documentation/pdf/yocto/profile-manual.pdf For more information see the Yocto Project Profiling and Tracing Manual 5.7 Yocto Project Reference Manual The Yocto Project uses the Poky build tool to construct complete Linux images. For more information see the Yocto Project Reference Manual located in the following SDK directory: sdk_documentation/pdf/yocto/poky-ref-manual.pdf For more information see the Yocto Project Reference Manual 58 NXP Semiconductors

59 Linux Kernel Drivers Audio Chapter 6 Linux Kernel Drivers 6.1 Audio SAI User Manual LS1012A Description This document describes how to configure and test SAI audio driver for LS1012A FRDM board. The integrated I2S module is NXP's Synchronous Audio Interface (SAI). The codec is SGTL5000 stereo audio codec. RCW configuration Refer to the below table for the RCW for Audio on the LS1012A FRDM board. Board RCW LS1012A FRDM Bit 364, EC1_EXT_SAI2_TX = 1; Bit 365, EC1_EXT_SAI2_RX =1; Bit , EC1_BASE = 00 Kernel Configure Options Tree View Kernel Configure Tree View Options Device Drivers ---> <*> I2C support ---> [*] Enable compatibility bits for old user-space [*] I2C device interface [*] I2C bus multiplexing support Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches [*] Autoselect pertinent helper modules I2C Hardware Bus support ---> <*> IMX I2C interface Description Enable ALSA SOC driver, I2C driver and EDMA driver. <*> Voltage and Current Regulator Support ---> [*] Regulator debug support [*] Provide a dummy regulator if regulator lookups fail [*] Fixed voltage regulator support <*> Sound card support <*> Advanced Linux Sound Architecture -> [*] OSS PCM (digital audio) API [*] OSS PCM (digital audio) API - Include plugin system [*] Support old ALSA API [*] Verbose procfs contents ALSA for SoC audio support ---> SoC Audio for Freescale CPUs ---> NXP Semiconductors 59

60 Linux Kernel Drivers Audio Kernel Configure Tree View Options Description <*> Synchronous Audio Interface (SAI) module support CODEC drivers ---> <*> Freescale SGTL5000 CODEC <*> ASoC Simple sound card support <*> DMA Engine support ---> <*> Freescale edma engine support support Identifier Below are the configure identifiers which are used in kernel source code and default configuration files. Option Values Default Value Description CONFIG_I2C_IMX y/m/n y I2C driver needed for configuring SGTL5000 CONFIG_SOUND y/m/n y Enable sound card support CONFIG_SND y/m/n y Enable advanced Linux sound architecture supports CONFIG_SND_PCM_OSS y/m/n y Enable OSS digital audio CONFIG_SND_PCM_OSS_ PLUGINS CONFIG_SND_SUPPORT_ OLD_API CONFIG_SND_SOC_FSL_ SAI CONFIG_SND_SOC_GENE RIC_DMAENGINE_PCM CONFIG_SND_SIMPLE_CA RD CONFIG_SND_SOC_SGTL 5000 y/m/n y Support conversion of channels, formats and rates y/m/n y Enable support old ALSA API y/m/n y Enable SAI module support y/m/n y Enable generic dma engine for PCM y/m/n y Enable generic simple sound card support y/m/n y Enable codec sgtl5000 support CONFIG_FSL_EMDA y/m/n y Enable EDMA engine support Source Files The driver source is maintained in the Linux kernel source tree. Source File sound/soc/fsl Description ALSA SOC driver source Verification in Linux 1. The following messages will be shown in the kernel boot process. sgtl a: sgtl5000 revision 0x11 60 NXP Semiconductors

61 Linux Kernel Drivers DMA Controller sgtl a: Using internal LDO instead of VDDD... asoc-simple-card sound: sgtl5000 <-> 2b60000.sai mapping ok... ALSA device list: #0: 2b60000.sai-sgtl If the device nodes don't already exist, create directory /dev/snd/, and create device nodes with the following commands in /dev/snd/ directory. mknod controlc0 c mknod pcmc0d0c c mknod pcmc0d0p c On LS1012A FRDM board, the LineOut interface is J8 and the LineIn interface is J13 4. Run the following aplay commands to test playback. Run the following arecord command to test record. aplay -f S16_LE -r t wav -c 2 44k-16bit-stereo.wav arecord -d 10 -f S16_LE -r t wav -c 2 44k-16bit-stereo-10s.wav aplay -f S16_LE -r t wav -c 2 44k-16bit-stereo-10s.wav 5. Use alsamixer to adjust the volume for playing by the option PCM and recording gain by the option "Mic". Use alsamixer to choose LINE IN or MIC. 6.2 DMA Controller Enhanced Direct Memory Access Driver (ARM) edma User Manual Description The SoC integrates NXP's Enhanced Direct Memory Access module. Slave device such as I2C or SAI can deploy the DMA functionality to accelerate the transfer and release the CPU from heavy load. Kernel Configure Options Tree View Below are the configure options need to be set/unset while doing "make menuconfig" for kernel Kernel Configure Tree View Options Description DMA engine subsystem driver and edma driver support Device Drivers ---> [*] DMA Engine support ---> ---> <*> Freescale edma engine support NXP Semiconductors 61

62 Linux Kernel Drivers DMA Controller Identifier Below are the configure identifiers which are used in kernel source code and default configuration files. Option Values Default Value Description CONFIG_FSL_EDMA y/m/n n edma 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. edma0: edma@2c00000 { }; #dma-cells = <2>; compatible = "fsl,vf610-edma"; reg = <0x0 0x2c x0 0x10000>, <0x0 0x2c x0 0x10000>, <0x0 0x2c x0 0x10000>; interrupts = <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 135 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "edma-tx", "edma-err"; dma-channels = <32>; big-endian; clock-names = "dmamux0", "dmamux1"; clocks = <&platform_clk 1>, <&platform_clk 1>; Device Tree Node Binding for Slave Device Below is the device tree node binding for a slave device which deploy the edma functionality. i2c0: i2c@ { }; #address-cells = <1>; #size-cells = <0>; compatible = "fsl,vf610-i2c"; reg = <0x0 0x x0 0x10000>; interrupts = <GIC_SPI 88 IRQ_TYPE_LEVEL_HIGH>; clock-names = "i2c"; clocks = <&platform_clk 1>; dmas = <&edma0 1 39>, <&edma0 1 38>; dma-names = "tx", "rx"; status = "disabled"; Source Files The following source files are related the this feature in Linux kernel. Table 3. Source Files Source File drivers/dma/fsl-edma.c Description The edma driver file 62 NXP Semiconductors

63 Linux Kernel Drivers DMA Controller Verification in Linux 1. Use the slave device which deploy the edma functionality to verify the edma driver, below is a verification with the I2C salve. root@ls1021aqds:~# i2cdetect 0 WARNING! This program can confuse your I2C bus, cause data loss and worse! I will probe file /dev/i2c-0. I will probe address range 0x03-0x77. Continue? [Y/n] a b c d e f 00: : : : : : : : root@ls1021aqds:~# i2cdump 0 0x69 i a b c d e f abcdef 00: ff ff 5d e 00 e8 03 b5 ff??..]u?u???.???. 10: ff e aa fe 9a ???...???...x 20: ff 00 7f d 60 3c ???..?@??`<??.@. 30: fe 80 c a 00 ff ff ff ff ff ff ff???)...z... 40: ff ff 5d e 00 e8 03 b5 ff??..]u?u???.???. 50: ff e aa fe 9a ???...???...x 60: ff 00 7f d 60 3c ???..?@??`<??.@. 70: fe 80 c a 00 ff ff ff ff ff ff ff???)...z... 80: 07 ff ff 5d e 00 e8 03 b5 ff ff?..]u?u???.???.. 90: e aa fe 9a ???...???...x. a0: ff 00 7f d 60 3c fe??..?@??`<??.@.? b0: 80 c a 00 ff ff ff ff ff ff ff ff??)...z... c0: 07 ff ff 5d e 00 e8 03 b5 ff ff?..]u?u???.???.. d0: e aa fe 9a ???...???...x. e0: ff 00 7f d 60 3c fe??..?@??`<??.@.? f0: 80 c a 00 ff ff ff ff ff ff ff ff??)...z... root@ls1021aqds:~# cat /proc/interrupts CPU0 CPU1 29: 0 0 GIC 29 arch_timer 30: GIC 30 arch_timer 112: GIC 112 fsl-lpuart 120: 32 0 GIC i2c 121: 0 0 GIC i2c 167: 8 0 GIC 167 edma IPI0: 0 1 CPU wakeup interrupts IPI1: 0 0 Timer broadcast interrupts IPI2: Rescheduling interrupts IPI3: 0 0 Function call interrupts IPI4: 2 4 Single function call interrupts IPI5: 0 0 CPU stop interrupts Err: 0 root@ls1021aqds:~# NXP Semiconductors 63

64 Linux Kernel Drivers Enhanced Secured Digital Host Controller (esdhc) 6.3 Enhanced Secured Digital Host Controller (esdhc) esdhc Driver User Manual Description The enhanced SD Host Controller(eSDHC) provides an interface between the host system and MMC/SD cards. The esdhc supports 1/4-bit data modes and bus clock frequency up to 50MHz Module Loading The esdhc device driver support either kernel built-in or module. U-boot Configuration Runtime options Env Variable Env Description Sub option Option Description hwconfig Hardware configuration for u-boot setenv hwconfig sdhc Enable esdhc for the kernel Kernel Configure Options Kernel Configure Tree View Options Kernel Configure Tree View Options Device Drivers ---> <*> MMC/SD/SDIO card support ---> <*> MMC block device driver (8) Number of minors per block device [*] Use bounce buffer for simple hosts Description Enables SD/MMC block device driver support *** MMC/SD/SDIO Host Controller Drivers *** Enables NXP esdhc driver support <*> Secure Digital Host Controller Interface support <*> SDHCI platform and OF driver helper [*] SDHCI OF support for the NXP esdhc controller Compile-time Configuration Options Option Values Default Value Description CONFIG_MMC y/n n Enable SD/MMC bus protocol CONFIG_MMC_BLOCK y/n y Enable SD/MMC block device driver support Table continues on the next page NXP Semiconductors

65 Linux Kernel Drivers Enhanced Secured Digital Host Controller (esdhc) Table continued from the previous page... Option Values Default Value Description CONFIG_MMC_BLOCK_MINORS integer 8 Number of minors per block device CONFIG_MMC_BLOCK_BOUNCE y/n y Enable continuous physical memory for transmit CONFIG_MMC_SDHCI y/n y Enable generic sdhc interface CONFIG_MMC_SDHCI_PLTFM y/n y Enable common helper function support for sdhci platform and OF drivers CONFIG_MMC_SDHCI_OF_ESDHC y/n y Enable NXP esdhc support Device Tree Binding Property Type Status Description compatible String Required Should be 'fsl,esdhc' reg integer Required Register map Default node: qoriq-esdhc-0.dtsi: sdhc: sdhc@ { compatible = "fsl,esdhc"; reg = <0x x1000>; interrupts = < >; clock-frequency = <0>; }; For special platform (T1040 as example): /include/ "qoriq-esdhc-0.dtsi" sdhc@ { compatible = "fsl,t1040-esdhc", "fsl,esdhc"; fsl,iommu-parent = <&pamu0>; fsl,liodn-reg = <&guts 0x530>; /* esdhcliodnr */ sdhci,auto-cmd12; rcpm-wakeup = <&rcpm 0x >; }; NOTE: For different platform, the compatilbe can be different. And the property "sdhci, auto-cmd12" is option. Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/mmc/host/sdhci.c drivers/mmc/host/sdhci-pltfm.c drivers/mmc/host/sdhci-of-esdhc.c Description Linux SDHCI driver support Linux SDHCI platform devices support driver Linux esdhc driver NXP Semiconductors 65

66 Linux Kernel Drivers Enhanced Secured Digital Host Controller (esdhc) User Space Application The following applications will be used during functional or performance testing. Please refer to the SDK UM document for the detailed build procedure. Command Name iozone Description IOzone is a filesystem benchmark tool. The benchmark generates and measures a variety of file operations.the benchmark tests file I/O performance for the following operations: Read, write, re-read, re-write, read backwards, read strided, fread, fwrite, random read, pread,mmap, aio_read, aio_write. Package Name iozone Verification in U-boot The u-boot log: => mmcinfo Device: FSL_ESDHC Manufacturer ID: 3 OEM: 5344 Name: SD02G Tran Speed: Rd Block Len: 512 SD version 2.0 High Capacity: No Capacity: Bus Width: 4-bit => mmc read MMC read: dev # 0, block # 0, count blocks read: OK => mmc part 0 Partition Map for MMC device 0 -- Partition Type: DOS Partition Start Sector Num Sectors Type b Verification in Linux Add environment value => setenv hwconfig sdhc The booting log... sdhci: Secure Digital Host Controller Interface driver sdhci: Copyright(c) Pierre Ossman mmc0: SDHCI controller on ffe2e000.sdhci-of [ffe2e000.sdhci-of] using PIO... mmc0: new SD card at address 87e2 mmcblk0: mmc0:87e2 SD02G 1.89 GiB 66 NXP Semiconductors

67 Linux Kernel Drivers Enhanced Secured Digital Host Controller (esdhc) mmcblk0: p1 Check the disk ~ # fdisk -l /dev/mmcblk0 disk /dev/mmcblk0: 2032 MB, bytes 63 heads, 62 sectors/track, 1016 cylinders Units = cylinders of 3906 * 512 = bytes Device Boot Start End Blocks Id System /dev/mmcblk0p b Win95 FAT32 ~ # Mount the file system and operate the card. ~ # ~ # mkdir /mnt/sd ~ # mount -t vfat /dev/mmcblk0p1 /mnt/sd ~ # ls /mnt/sd/ vim ~ # cp /bin/busybox /mnt/sd ~ # ls /mnt/sd busybox vim ~ # umount /mnt/sd ~ # mount -t vfat /dev/mmcblk0p1 /mnt/sd ~ # ls /mnt/sd busybox vim ~ # Benchmarking ~ # ~ # # iozone -Rab./iosdresult/result -i 0 -i 1 -f test -n 512M -g 1G -r 64K NXP Semiconductors 67

68 Linux Kernel Drivers Enhanced Secured Digital Host Controller (esdhc) Iozone: Performance Test of File I/O Version $Revision: $ Compiled for 32 bit mode. Build: linux-arm Contributors:William Norcott, Don Capps, Isom Crawford, Kirby Collins Al Slater, Scott Rhine, Mike Wisner, Ken Goss Steve Landherr, Brad Smith, Mark Kelly, Dr. Alain CYR, Randy Dunlap, Mark Montague, Dan Million, Jean-Marc Zucconi, Jeff Blomberg, Erik Habbinga, Kris Strecker, Walter Wong. Run began: Wed Feb 16 20:33: Excel chart generation enabled Auto Mode Using minimum file size of kilobytes. Using maximum file size of kilobytes. Record Size 64 KB Command line used: iozone -Rab./iosdresult/result -i 0 -i 1 -f test -n 512M -g 1G -r 64K Output is in Kbytes/sec Time Resolution = seconds. Processor cache size set to 1024 Kbytes. Processor cache line size set to 32 bytes. File stride size set to 17 * record size. random random bkwd record stride KB reclen write rewrite read reread read write read rewrite read fwrite frewrite fread freread NXP Semiconductors

69 Linux Kernel Drivers PCI Express Interface Controller Known Bugs, Limitations, or Technical Issues 1. Call trace when run "iozone" to test SDCARD performace on some platforms workaround:increase the timeout value (in kernel configuration) and decrease the dirty_ratio in proc file system. 1) menuconfig: Kernel hacking (xxx) Default timeout for hung task detection (in seconds) Note: the xxx may be 400 seconds or greater 2) modify 'proce file system': echo xx > /proc/sys/vm/dirty_ratio echo xx > /proc/sys/vm/dirty_background_ratio Note: the xx may be 10 or 5, which meas 10% or 5%, the default is 20%. 2. The platform whose card is required to work on a special transfer mode which is not FS or HS mode needs a special rcw. (e.g. rcw_66_15_1800mhz_emmc_ddr.rcw is for t2080qds emmc DDR mode. Because of pin multiplexing with SPI, SPI would not work when emmc card works on DDR mode) 6.4 PCI Express Interface Controller PCIe Linux Driver Module Loading The MPC85xx/Layerscape PCIE host bridge support code is compiled into the kernel. It is not available as a module. Kernel Configure Tree View Options Kernel Configure Tree View Options Bus support ---> [*] PCI support [*] Message Signaled Interrupts (MSI and MSI-X) Description Enable PCI host bridge and message support Bus support ---> PCI host controller drivers ---> [*] Freescale Layerscape PCIe controller Enable NXP Layerscape PCIe controller Device Drivers ---> [*]Network device support ---> [*]Ethernet device support ---> [*] Intel devices ---> <*> Intel (R) PRO/1000 PCI-Express Gigabit Ethernet support Intel PRO/1000 PCI-Express support Table continues on the next page... NXP Semiconductors 69

70 Linux Kernel Drivers PCI Express Interface Controller Table continued from the previous page... Kernel Configure Tree View Options Device Drivers ---> Description Enable support for Silicon Image 3124/3132 Serial ATA. <*> Serial ATA and Parallel ATA drivers (libata) ---> <*> Silicon Image 3124/3132 SATA support Compile-time Configuration Options Option Values Default Value Description CONFIG_PCI y/n y Enable PCI host bridge CONFIG_PCI_MSI y/n y Message support CONFIG_PCI_LAYERSCAPE y/n y Enable PCI for Layerscape CONFIG_E1000E y/m/n y Enable Intel Pro/1000 driver CONFIG_SATA_SIL y/m/n y Silicon Image SATA support Source Files The driver source is maintained in the Linux kernel source tree. Source File arch/powerpc/sysdev/fsl_pci.c drivers/pci/host/pci-layerscape.c drivers/net/ethernet/intel/e1000e/ drivers/ata/sata_sil.c Description The MPC85XX platform PCIE host bridge support source The Layerscape platform PCIE host bridge support source Intel Pro/1000 driver source code Silicon Image source code SATA Card Test Procedure the user can use command fdisk, mke2fs mount to operate the ide disk. After kernel boots up, please follow the log to operate: [root@px0xx /root]# fdisk -l Disk /dev/sda: 85.8 GB, bytes 255 heads, 63 sectors/track, cylinders Units = cylinders of * 512 = bytes Disk /dev/sda doesn't contain a valid partition table [root@px0xx /root]# fdisk /dev/sda Device contains neither a valid DOS partition table, nor Sun, SGI or OSF disklabel Building a new DOS disklabel. Changes will remain in memory only, 70 NXP Semiconductors

71 Linux Kernel Drivers PCI Express Interface Controller until you decide to write them. After that the previous content won't be recoverable. The number of cylinders for this disk is set to 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 (e.g., DOS FDISK, OS/2 FDISK) Command (m for help): n Command action e extended p primary partition (1-4) p Partition number (1-4): 1 First cylinder ( , default 1): Using default value 1 Last cylinder or +size or +sizem or +sizek ( , default 10443): 100 Command (m for help): w The partition table has been altered! Calling ioctl() to re-read partition table sd 0:0:0:0: [sda] byte hardware sectors (85899 MB) sd 0:0:0:0: [sda] Write Protect is off sd 0:0:0:0: [sda] Asking for cache data failed sd 0:0:0:0: [sda] Assuming drive cache: write through sda: sda1 [root@px0xx /root]# mke2fs /dev/sda1 mke2fs 1.34 (25-Jul-2003) Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) inodes, blocks blocks (5.00%) reserved for the super user First data block=0 7 block groups blocks per group, fragments per group inodes per group Superblock backups stored on blocks: 32768, 98304, Writing inode tables: done Writing superblocks and filesystem accounting information: done This filesystem will be automatically checked every 31 mounts or 180 days, whichever comes first. Use tune2fs -c or -i to override. [root@px0xx /root]# mkdir sda1_test [root@px0xx /root]# mount /dev/sda1 sda1_test/ [root@px0xx /root]# cp /bin/tar sda1_test/ [root@px0xx /root]# NXP Semiconductors 71

72 Linux Kernel Drivers PCI Express Interface Controller Ethernet Card Test Procedure plug Intel Pro/1000e network card into standard PCI-E slot on a board. After linux bootup, ifconfig ethx ip address and netmask, then do ping testing. Tips: x ethernet interface number, an example is as the following for Intel e1000 network card is eth0. For example: After kernel boot up, bring up with the pci Ethernet card ifconfig ethx ip address should not be conficted with other Ethernet port. In Linux window, run ping Known Bugs, Limitations, or Technical Issues LSI-SAS card cannot be used on the second PCIe controller when system enables more than one PCIe controller. Use code modification below to workaround this issue: --- a/arch/powerpc/sysdev/fsl_pci.c ,7 int init fsl_add_bridge(struct platform_device *pdev, int is_primary) printk(kern_warning "Can't get bus-range for %s, assume" " bus 0\n", dev->full_name); - pci_add_flags(pci_reassign_all_bus); + pci_add_flags(pci_enable_proc_domains); hose = pcibios_alloc_controller(dev); if (!hose) return -846,7 int init mpc83xx_add_bridge(struct device_node *dev) " bus 0\n", dev->full_name); } - pci_add_flags(pci_reassign_all_bus); + pci_add_flags(pci_enable_proc_domains); hose = pcibios_alloc_controller(dev); if (!hose) return -ENOMEM; EDAC Driver User Manual Description The EDAC kernel module's goal is to detect and report errors that occur within the computer system running under Linux. Note Currently the EDAC wasn't supported on P5040/P bit. Module Loading Linux EDAC Driver supports kernel built-in or module. 72 NXP Semiconductors

73 Linux Kernel Drivers PCI Express Interface Controller Kernel Configure Options Kernel Configure Tree View Options Kernel Configure Tree View Options Device Drivers ---> <*> EDAC (Error Detection And Correction) reporting --- > <*> Main Memory EDAC (Error Detection And Correction) reporting <*> Freescale MPC83xx / MPC85xx Description Enables EDAC support for 85xx platform Compile-time Configuration Options Option Values Default Value Description CONFIG_EDAC_MM_EDAC y/n y/n Enables EDAC core support CONFIG_EDAC_MPC85XX y/n y/n Enables EDAC NXP 85xx support Device Tree Binding Property Type Status Description compatible String Required Should be 'fsl,qoriq-memory-controller', 'fsl,p4080-pcie' reg integer Required Register map Default node: ddr1: memory-controller@8000 { compatible = "fsl,qoriq-memory-controller-v4.4", "fsl,qoriq-memory-controller"; reg = <0x8000 0x1000>; interrupts = < >; }; /* controller at 0x */ pci0 { compatible = "fsl,p4080-pcie"; device_type = "pci"; #size-cells = <2>; #address-cells = <3>; bus-range = <0x0 0xff>; clock-frequency = < >; interrupts = < >; }; Source Files The driver source is maintained in the Linux kernel source tree. NXP Semiconductors 73

74 Linux Kernel Drivers PCI Express Interface Controller Source File drivers/edac/edac_core.c drivers/edac/mpc85xx_edac.c Description Enables EDAC core support Enables EDAC NXP 85xx support Kernel boot message: EDAC MC: Ver: Freescale(R) MPC85xx EDAC driver, (C) 2006 Montavista Software EDAC MC0: Giving out device to 'MPC85xx_edac' 'mpc85xx_mc_err': DEV mpc85xx_mc_err MPC85xx_edac acquired irq 16 for MC MPC85xx_edac MC err registered EDAC MC1: Giving out device to 'MPC85xx_edac' 'mpc85xx_mc_err': DEV mpc85xx_mc_err MPC85xx_edac acquired irq 16 for MC MPC85xx_edac MC err registered EDAC PCI0: Giving out device to module 'MPC85xx_edac' controller 'mpc85xx_pci_err': DEV 'ffe pcie' (INTERRUPT) MPC85xx_edac acquired irq 16 for PCI Err MPC85xx_edac PCI err registered EDAC PCI1: Giving out device to module 'MPC85xx_edac' controller 'mpc85xx_pci_err': DEV 'ffe pcie' (INTERRUPT) MPC85xx_edac acquired irq 16 for PCI Err MPC85xx_edac PCI err registered EDAC PCI2: Giving out device to module 'MPC85xx_edac' controller 'mpc85xx_pci_err': DEV 'ffe pcie' (INTERRUPT) MPC85xx_edac acquired irq 16 for PCI Err MPC85xx_edac PCI err registered Testing edac driver is start. PCIE error(s) detected PCIE ERR_DR register: 0x PCIE ERR_CAP_STAT register: 0x PCIE ERR_CAP_R0 register: 0x PCIE ERR_CAP_R1 register: 0x PCIE ERR_CAP_R2 register: 0x PCIE ERR_CAP_R3 register: 0x p4080 login: root Password: root]# Test Procedure: root]# root]# cat /proc/interrupts grep EDAC 16: OpenPIC Level [EDAC] MC err, [EDAC] MC err, [EDAC] PCI err, [EDAC] PCI err, [EDAC] PCI err [root@p4080 root]# [root@p4080 root]# 74 NXP Semiconductors

75 Linux Kernel Drivers PCI Express Interface Controller Now, see that whether the total number of interrupt 16 of EDAC is zero or less than twenty. If it is that, EDAC driver is OK PCIe Advanced Error Reporting User Manual Description How to test the PCI Express Advanced Error Reporting (AER) function. Testing the PCIe AER error recovery code in actual environment is quite difficult because it is hard to trigger real hardware errors. So we use a software tool based error injection to fake various kinds of PCIe errors. Kernel Configure Tree View Options Kernel Configure Tree View Options Bus options ---> [*] PCI Express support [*] Root Port Advanced Error Reporting support <*> PCIe AER error injector support Description enable PCI-Express AER and AER-INJECTOR in kernel Kernel compile-time Configuration Options Option Values Default Value Description CONFIG_PCIEAER y/n y Enable AER CONFIG_PCIEAER_INJECT y/n n Enables AER INJECT Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/pci/pcie/aer/*.c Description AER driver support Prepare aer-inject test tool 1, Download aer-inject test utility. 2, Write a test config file e.g. $ vi aer-cfg AER DOMAIN 0001 BUS 1 DEV 0 FN 0 COR_STATUS BAD_TLP HEADER_LOG NOTE: error type can be ["COR_STATUS", "UNCOR_STATUS"] Corrected error can be: ["BAD_TLP", "RCVR", "BAD_DLLP", "REP_ROLL", "REP_TIMER"] NXP Semiconductors 75

76 Linux Kernel Drivers PCI Express Interface Controller Uncorrected non-fatal error can be: ["POISON_TLP", "COMP_TIME", "COMP_ABORT", "UNX_COMP", "ECRC", "UNSUP"] Uncorrected fatal error can be: ["TRAIN", "DLP", "FCP", "RX_OVER", "MALF_TLP"] Test Steps 1, insert a pcie device in PCI slot of board, ensure the pcie device has AER capability, e.g. e1000e PCIe NIC network card. 2, In u-boot prompt, add "pcie_ports=native" in bootargs command-line. => setenv othbootargs pcie_ports=native 3, boot the kernel and filesystem. => tftp uimage;tftp board.dtb; tftp rootfs.ext2.gz.uboot; bootm , check AER device and config # zcat /proc/config.gz grep -i CONFIG_PCIEAER_INJECT CONFIG_PCIEAER_INJECT=y # cat /proc/cmdline root=/dev/ram rw console=ttys0, pcie_ports=native check "pcie_ports=native" has been set. # ls /dev/aer_inject Check if the aer injector device is created. # lspci 00:00.0 Class 0604: 1957: :00.0 Class 0200: 8086:10d3 e.g. here device "01:00.0" is the PCIe NIC e1000 network card in the test scenario. 5, Download aer-inject and aer-cfg from host to test-board $ scp aer-inject aer-cfg root@test-board-ip:~ 6, ensure the pcie device domain-number/bus-number/device-number/function-number in aer-cfg is accordant to those in the output of lspci 7, Run aer-inject, corresponding error information will be reported as below and AER will recover PCIE device according to the type of errors. #./aer-inject aer-cfg example of error report as below: pcieport 0000:00:00.0: AER: Corrected error received: id=0100 e1000e 0000:01:00.0: PCIe Bus Error: severity=corrected, type=data Link Layer, id=0100(receiver ID) e1000e 0000:01:00.0: device [8086:10d3] error status/mask= / e1000e 0000:01:00.0: [ 6] Bad TLP root@p1010rdb:~# 8, The pcie device(e1000e PCIE NIC) should still work after AER error recovery. # ping c 2 -s 64 PING ( ): 64 data bytes 72 bytes from : icmp_seq=0 ttl=64 time=0.272 ms 72 bytes from : icmp_seq=1 ttl=64 time=0.210 ms ping statistics packets transmitted, 2 packets received, 0% packet loss 76 NXP Semiconductors

77 Linux Kernel Drivers PCI Express Interface Controller round-trip min/avg/max/stddev = 0.210/0.241/0.272/0.031 ms Note: On some legacy platforms with legacy PCI conroller(e.g. some non-dpaa platforms), hardware doesn't support Fatal error type for AER, just support Non-Fatal error. Generally, DPAA platforms with new PCIE controller can support both Fatal error and Non-Fatal error PCI-e Remove and Rescan User Manual Description Describes how to remove and rescan a PCI-e device under runtime Linux system. U-boot Configuration Use the default configurations. Kernel Configure Options Use the default configurations, make sure the configure option is set while doing "make menuconfig" for kernel. Kernel Configure Tree View Options Description Device Drivers ---> [*] Network device support---> [*] Ethernet (1000 Mbit) ---> [*] Intel(R) PRO/1000 PCI-Express Gigabit Ethernet support This option enables kernel support for Intel PCI-e e1000e network card Below are the configure identifiers which are used in kernel source code and default configuration files. Option Values Default Value Description CONFIG_E1000E y/n y Intel PCI-e e1000e network card driver Device Tree Binding Use the default dtb file. Verification in Linux Make sure the PCI-e controller which you add the PCI-e e1000e network card to works as RC mode. Use the kernel, dtb and ramdisk rootfs to boot the board. 1. Suppose the PCI-e device under /sys/bus/pci/devices/0001\:03\:00.0 is the Intel PCI-e e1000e network card, recognized as eth0. The /sys/bus/pci/devices/0001\:02\:00.0 is the bus of network card. Configure an ip and ping another host which is in the same subnet, make sure the network card works well. # ls /sys/bus/pci/devices/0001\:03\:00.0/net eth0 # ifconfig eth # ping -I eth Remove the PCI-e network card from system. NXP Semiconductors 77

78 Linux Kernel Drivers PCI Express Interface Controller # echo 1 > /sys/bus/pci/devices/0001\:03\:00.0/remove e1000e 0001:03:00.0 eth0: removed PHC 3. Check whether the PCI-e network card still exist in system. All should fail. # ifconfig eth0 # ls /sys/bus/pci/devices/0001\:03\: Rescan it from the bus. # echo 1 > /sys/bus/pci/devices/0001\:02\:00.0/rescan 5. Check whether the device is rescanned and works well. # ls /sys/bus/pci/devices/0001\:03\:00.0 # ifconfig eth # ping -I eth All the commands of step 5 should success. Known Bugs, Limitations, or Technical Issues The support of PCI-e device remove rescan on powerpc platform is first added in NXP LInux SDK 1.4(kernel version: 3.8.4). If it fail, the PCI-e device will be rescaned, but the driver of the device will fail to loaded PCIE EP Description SKMM (Secure Key Management Module) is Linux user space implementation for accelerating the encryption/decryption operations on the NXP processors with SEC engine. SKMM consists of two parts of software, the host kernel driver and the application on EP side. The host driver interfaces with OpenSSL or sysfs to pass the encryption/decryption operations to EP side by abstract request and the EP application parses the abstract request to do the encryption/decryption operations, pass the results to host side. The key point here is the private key used is only kept in EP side and is invisible to host side. Also the private key(s) is stored in NOR flash using blob mechanism for protecting the key across system power cycles. SKMM has two sub use cases: - SKMM with PCIe data path. (For now, only SKMM with PCIe data path is supported.) For SKMM with PCIe data path, the two boards are connected through the PCIe interface, the requests are sent to EP through PCIe interface. - SKMM with Ethernet data path. Requests are sent to the EP through the Ethernet port. Platforms Supported P4080DS T4240QDS Compiling SKMM code Refer to SDK Documentation provided with this release for installing and using Yocto for Image compilation and building. How to configure and build Host images for PowerPC 1. Change directory to Yocto, execute commands to configure kernel > source./poky/fsl-setup-poky -m <board-type> -j 12 -t NXP Semiconductors

79 Linux Kernel Drivers PCI Express Interface Controller #> bitbake -c menuconfig linux-qoriq-sdk To P4080DS and T4240QDS: Location: -> Device Drivers -> DMA Engine support ->[*] NXP Elo and Elo Plus DMA support (enable the option) [ ] Network: TCP receive copy offload (disable the option) 2. Execute Commands to build uimage with DMA enabled #> bitbake linux-qoriq-sdk 3. Execute Command to generate RFS with kernel modules for host and SKMM application for EP #> bitbake fsl-image-core How to configure and build Host images for X86: NOTE When using X86 as Host of SKMM, need a Linux distribution to be installed to X86 PC, suggested using Ubuntu bit. 1. Change directory to Yocto, then extract the SKMM Host source code as following: #> source./poky/fsl-setup-poky -m <board-type> -j 12 -t 12 #> bitbake -c patch skmmhost 2. The source code will be in tmp/work/<board -type>-fsl_networking-linux/skmmhost/git-r0/git/. Copy the source directory to your X86 Host machine for building. 3. Change the directory to the top of the SKMM Host s source code, execute the command: #> make ARCH=x86_64 KERNEL_DIR=/lib/modules/$(uname -r)/build 4. The driver modules will be built in the current directory, named fsl_crypto.ko and rsa_test.ko. How to configure and build EP kernel: 1. Change the directory to Yocto, then execute commands to configure the kernel: #> source./poky/fsl-setup-poky -m <board-type> -j 12 -t 12 #> bitbake -c menuconfig linux-qoriq-sdk For P4080ds: Location: -> Cryptographic API ->[*] Hardware crypto devices -> < > NXP CAAM-Multicore driver backend (disable the option) -> Device Drivers -> <*> Userspace I/O drivers -> <*> NXP SEC support(disable the option) For T4240qds: Location: -> Cryptographic API NXP Semiconductors 79

80 Linux Kernel Drivers PCI Express Interface Controller ->[*] Hardware crypto devices -> < > NXP CAAM-Multicore driver backend (disable the option) -> Device Drivers -> <*> Userspace I/O drivers -> <*> NXP SEC support(disable the option) -> <*> VFIO Non-Privileged userspace driver framework(enable the option) -> <*> VFIO support for Fresscale PCI Endpoint devices(enable the option) 2. Execute command to build the kernel image #> bitbake linux-qoriq-sdk 3. Execute command to generate RFS with SKMM application for EP #> bitbake fsl-image-core Configure physical connection EP For P4080ds, route the PCIe cable between slot #1 and the Host. For T4240qds, route the PCIe cable between slot #5 and the Host. Host For P4080ds, route the PCIe cable between slot #3 and the EP For X86, route the PCIe cable between X86 PCIe slot with the x4 to x1 connector, and the EP For T4240qds, route the PCIe cable between slot #7 and the EP How to operate EP Store all the images for PowerPC machine on the tftp server. Configure the board IP and tftp server IP on the u-boot environment using following commands, the third step is to reserve memory for SKMM, it couldn t be ignored. For P4080ds as EP 1. #> setenv ipaddr <board ip > #> setenv serverip <tftp server ip > #> setenv bootargs $bootargs usdpaa_mem=256m #> save 2. Program RCW with R_PPPNN_0x5/rcw_ep_1500mhz.bin to flash. 3. Execute following command at u-boot prompt to boot the board #> tftp uimage-<bsp>.bin #> tftp fsl-image-core-<bsp>.ext2.gz.uboot #> tftp c00000 uimage-<bsp>.dtb #> bootm c Once the Linux Image boots, enter username=root and password=root to logon. 5. If the SKMM application is being run for the first time, update private key into Nor flash MTD4. root@p4080:flash_eraseall /dev/mtd4 root@p4080:skmm_$(host) /dev/mtd4 update-key ~/.skmm/rsa_priv3 80 NXP Semiconductors

81 Linux Kernel Drivers PCI Express Interface Controller NOTE skmm_$(host) is the application for different Host. For x86 its name is "skmm_x86_64", for PowerPC its is "skmm_powerpc", please check the application used is correct to Host. 6. Run SKMM application, then EP will wait for request offloaded /dev/mtd4 For T4240qds as EP 1. #> setenv ipaddr <board ip > #> setenv serverip <tftp server ip > #> setenv bootargs $bootargs usdpaa_mem=256m #> save 2. Program RCW with RR_XXSSPRPH_1_28_6_12/rcw_1_28_6_12_pexep_1666MHz.bin #> tftp uimage-<bsp>.bin #> tftp fsl-image-core-<bsp>.ext2.gz.uboot #> tftp c00000 uimage-<bsp>.dtb #> fdt addr $fdtaddr;fdt mknod /localbus/nor #> fdt set reg <0x x >; #> fdt set label "blob"; #> bootm $loadaddr - $fdtaddr; 3. Once the Linux Image boots, enter username=root and password=root to logon. 4. If the SKMM application is being run for the first time, update private key into Nor flash MTD0 root@t4240:flash_eraseall /dev/mtd0 root@t4240:skmm_$(host) /dev/mtd0 update-key ~/.skmm/rsa_priv3 NOTE skmm_$(host) is the application for different Host. For x86 its name is "skmm_x86_64", for PowerPC its is "skmm_powerpc", please check the application used is correct to Host. 5. Run SKMM application, then EP will wait for request offloaded root@t4240:skmm_$(host) /dev/mtd0 How to operate Host 1. boot up PowerPC Host: 2. Configure the board IP and tftp server IP on the u-boot environment using following commands: #> setenv ipaddr <board ip > #> setenv serverip <tftp server ip > #> save 3. Execute following command at u-boot prompt to boot the board #> tftp uimage-<bsp>.bin #> tftp fsl-image-core-<bsp>.ext2.gz.uboot NXP Semiconductors 81

82 Linux Kernel Drivers PCI Express Interface Controller #> tftp c00000 uimage-<bsp>.dtb #> bootm c Once the Linux Image boots, enter username=root and password=root to logon. 5. Insmod the module to start the test process Root #>:insmod /lib/modules/$(uname -r)/extra/fsl_crypto.ko dev_config_file=/etc/skmm/ skmm_crypto.cfg 6. boot up X86 Host 7. There is no specific setup for X86, change directory to c293_skmm_host copied from Yocto, and make sure the modules has been generated. 8. Insert the module to start the test process For PowerPC Host: Root #>:insmod /lib/modules/$(uname -r)/extra/fsl_crypto.ko dev_config_file=/etc/skmm/ skmm_crypto.cfg For X86 Host: root #>:insmod fsl_crypto.ko dev_config_file=crypto.cfg How to test When you complete one of RSA public key test or private key test, you have to reboot both HOST and EP, and reload the fsl_crypto.ko module above, then move on another function test step. For PowerPC as Host RSA public key: Root #>:insmod /lib/modules/$(uname -r)/extra/rsa_test.ko op=rsa_pub RSA private key: Root #>:insmod /lib/modules/$(uname -r)/extra/rsa_test.ko op=rsa_priv3 For x86 as Host RSA_public key: root #>:insmod rsa_test.ko op=rsa_pub RSA private key: root #>:insmod rsa_test.ko op=rsa_priv3 Because PowerPC haven't supported PCIe hotplug yet, removing fsl_crypto.ko module will cause a Host kernel call trace Funtion test result If there was nothing ERROR log printed, it means test result was correct, but if the console prints the words like!!!!! Not matching byte got [xx] original [%0x] at index [xx] (note: xx is a number of 0 to127 ), it means test failed. Performance test RSA pubilc key: Root #>:echo "RSA_PUB_OP_1K" >/sys/fsl_crypto/fsl_crypto_1/test-i/test_name RSA private key: Root #>:echo "RSA_PRV_OP_1K" >/sys/fsl_crypto/fsl_crypto_1/test-i/test_name After console prints the start time and end time, it means the test process is finished, then please use the formula bellow to calculate the performance ops/s (The number of crypto operations in a second): Ops/s = Host cpu Frequency / ((end time start time) / 5000) 82 NXP Semiconductors

83 Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver For example, to P4080ds, Cpu Frequency is 1.5GHz(1.5 x 109) is the number of crypto operations (it is the default setting for performance test), it has been hard code, so it couldn t be modified. 6.5 Packet Forward Engine (PFE) Network Driver Introduction Overview This section describes the Linux driver which enables support for Ethernet on Packet Forward Engine (PFE) hardware. EMACs are part of PFE IP, to receive/transmit packets through EMAC interface it should be accessed through PFE interface by programing it Purpose The purpose of this section is to provide a user guide and configuration details for the PFE driver, and a high-level view of the driver s structure, as well as to describe its major functionalities with a focus on the features provided by the PFE IP Features This section provides an overview of the major PFE features: MAC Layer. MAC Address Filter. Interrupt for Tx/Rx packets. Scatter/Gather support. Interrupt coalescing. TCP/UDP checksum verification and generation High level decomposition and data flow A system level block view, from a network device perspective, may be depicted as follows: NXP Semiconductors 83

84 Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver User application ethtool package iproute2 package Network protocol handler/ioctl interface Linux network stack Eth0 Eth1 HIF/Ethernet client driver Kernel HIF driver layer H HW MAC PFE MAC PHY PHY Figure 1. High level decomposition and data flow block level view The PFE, MAC and PHY are the hardware blocks, the kernel networking stack along with the network driver are running in the Kernel space, and finally ethtool and iproute2 are examples of user space tools used for configuring the network devices. The PFE hardware supports one HIF RX and TX descriptor queues to send and receive packets through PFE. Both network interface traffic is multiplexed and send over HIF queue. User space packages like ethtool and iproute are used to configure the network device parameters. The ethtool interface is extended to provide support for filer programming. The kernel space module for the network driver is the most important block as it communicates with both the user space and the H/W IP to control the processing of packets. The basic functionality of any Ethernet driver is to handle the reception of packets from an ingress port (might include checksum calculation, header verification, etc), as well as the transmission of packets on the egress port (might include checksum re-calculation, header manipulation, etc). There are also the device configuration and control functionalities, and device status reporting. When the Ethernet driver is actually implementing these functionalities, it needs to interact with the core (Kernel) as well as the hardware IP (the Ethernet controller). The PFE Linux kernel module has following two main parts: HIF driver layer:this part of the driver talks with HIF hardware interface and send and receive the packets from it. It receives packets from HIF interface and identifies from which MAC interface it received and send the packet to corresponding client driver queue. Similarly, if there is any pending packet from client queue to transmit packet it takes and inserts the HIF header and put it into the HIF queue. It uses the NAPI to receive packets and send it to corresponding client queues and triggers client to process packets from the queue. HIF/Ethernet client driver: Ethernet client driver is a hardware independent driver and registers with the HIF driver to transmit and receive packet through HIF interface. For each interface one instance of client driver should be register with the HIF driver layer, other side it registers with Linux kernel stack as network interface. Each client driver will have software queues to communicate with HIF driver layer. Each client driver registers with NAPI and indicate packets to the stack through the NAPI poll. 84 NXP Semiconductors

85 Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver NAPI support PFE HIF driver layer uses NAPI handling for Rx path processing, the Linux polling mechanism being triggered by frame receive interrupts. The driver registers irqs for receive and the NAPI (polling) handlers are provided to the Kernel. Similarly, HIF Ethernet client driver also uses NAPI handling to processes software queues and pass them to the Kernel Network stack. On the receive path: When the receive interrupt gets triggered, a softirq for the polling function on Rx is scheduled. The RX_SOFTIRQ thread is raised by the Kernel, and the HIF Rx queues will be processed by the driver's polling function and the incoming packets are being passed to client Rx queues and triggers the client NAPI handling. HIF/Ethernet client NAPI poll receives packets from client Rx queues and passes to the Network stack Interrupt coalescing On a high speed network interface the rate of packet reception and transmission can be as high as the CPUs would be spending most of the time servicing these interrupts. With the interrupt coalescing feature, packets are collected and one single interrupt is generated for multiple packets to avoid flooding the system with interrupts from the Ethernet device. PFE hardware supports hardware coalescing for receive interrupts, complemented by timer-based thresholds. PFE driver provides basic support for setting the coalescing parameters via ethtool -C by implementing the rx-usec option Checksum offloading For large frames, offload of checksum verification saves a significant fraction of the CPU cycles that would otherwise be spent by the TCP/IP stack. IP packet fragmentation and re-assembly, and TCP stream establishment and tear-down are not performed in hardware. On Tx side, PFE hardware provides IPv4/IPv6 and TCP/UDP header checksum generation. On the Rx side, PFE driver lets the Kernel know that checksum verification is not required if valid IP headers or TCP/UDP headers were found and valid sums were verified, by setting the CHECKSUM_UNNECESSARY flag. On Tx side, the checksum is generated (offloaded) for TCP/UDP packets over IPv4 based on the pseudo-header checksum (phcs) provided by the Linux networking stack. PFE Linux driver instructs the stack about its ability to provide partial checksumming, based on the phcs for TCP/UDP packets, by setting the NETIF_F_IP_CSUM device capability flag. PFE hardware doesn t support per packet based checksum calculation control, it should be enabled or disabled for all packets Scatter gather support Scatter-Gather I/O is a method by which a single procedure call sequentially writes data from multiple buffers to a single data stream or reads data from a data stream to multiple buffers. The buffers are given in a vector of buffers. Scatter/gather refers to the process of gathering data from, or scattering data into, the given set of buffers. The I/O can be performed synchronously or asynchronously to this procedure. On the Tx side, PFE HIF interface supports "gathering" big packets from multiple buffers. This ability is signaled by the driver to the Linux network stack by setting the NETIF_F_SG device hardware feature flag. The driver takes into account the number of fragments composing the packet that is going to be transmitted, and places each fragment into consecutive BD ring buffers before issuing the command to start sending the frame. On the Rx side, the PFE HIF interface is capable of "scattering" big packets into multiple fixed size buffers having consecutive buffer descriptors (BDs) Ethtool support Non-exhaustive list of the most notable ethtool commands implemented by PFE Linux driver: NXP Semiconductors 85

86 Linux Kernel Drivers Real Time Clock (off-chip) Commands Description ethtool -C rx-usecs N Set Rx interrupt coalescing in microsecs( usecs ). ethtool -K rx on off tx on off Set UDP/TCP checksum offloading enabled or disabled. ethtool -S Show interface statistics, Linux specific counters and various MAC H/ W counters. 6.6 Real Time Clock (off-chip) RTC Driver User Manual (Linux BSP) Linux SDK for QorIQ Processors Description Provides the RTC function. Kernel Configure Tree View Options Kernel Configure Tree View Options 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) Description Enable RTC driver Compile-time Configuration Options Option Values Default Value Description CONFIG_RTC_LIB y/m/n y Enable RTC lib CONFIG_RTC_CLASS y/m/n y Enable generic RTC class support CONFIG_RTC_HCTOSYS y/n y Set the system time from RTC when startup and resume CONFIG_RTC_HCTOSYS_DEVICE "rtc0" RTC used to set the system time CONFIG_RTC_INTF_SYSFS y/m/n y Enable RTC to use sysfs CONFIG_RTC_INTF_PROC y/m/n y Use RTC through the proc interface Table continues on the next page NXP Semiconductors

87 Linux Kernel Drivers Real Time Clock (off-chip) Table continued from the previous page... Option Values Default Value Description CONFIG_RTC_INTF_DEV y/m/n y Enable RTC to use /dev interface Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/rtc/ Description Linux RTC driver Device Tree Binding Preferred node name: rtc Property Type Status Description compatible string Required Should be "dallas,ds3232" Default node: i2c@3000 { #address-cells = <1>; #size-cells = <0>; compatible = "fsl-i2c"; reg = <0x3000 0x100>; interrupts = <43 2>; interrupt-parent = <&mpic>; dfsrr; rtc@68 { compatible = "dallas,ds3232"; reg = <0x68>; }; }; Verification in Linux Here is the rtc booting log... rtc-ds : rtc core: registered ds3232 as rtc0 MC object device driver dpaa2_rtc registered rtc-ds : setting system clock to :00:51 UTC ( )... NOTE: Please refer to the related DTS file to enable the RTC driver before building. For example, LS2080AQDS board, should enable the below option: <*> Dallas/Maxim DS3232 NXP Semiconductors 87

88 Linux Kernel Drivers SATA Controller 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: seconds ~ # date Tue Jan 11 15:50:00 UTC 2011 ~ # hwclock -w ~ # hwclock Tue Jan 11 15:50: seconds ~ # date 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 6.7 SATA Controller NXP Native SATA Driver User Manual Description The driver supports NXP native SATA controller. Module Loading SATA driver supports either kernel built-in or module. Kernel Configure Tree View Options Device Drivers---> <*> Serial ATA and Parallel ATA drivers ---> --- Serial ATA and Parallel ATA drivers <*> AHCI SATA support <*> Freescale QorIQ AHCI SATA support Description Enables SATA controller support on ARM-based SoCs 88 NXP Semiconductors

89 Linux Kernel Drivers SATA Controller Compile-time Configuration Options Option Values Default Value Description CONFIG_SATA_AHCI=y y/m/n y Enables SATA controller CONFIG_SATA_AHCI_QORIQ=y y/m/n y Enables SATA controller Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/ata/ahci_qoriq.c Description Platform AHCI SATA support 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 (2) The disk will be found by kernel.... ata1: Signature Update 504 msecs ata2: No Device OR PHYRDY change,hstatus = 0xa 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: sectors, multi 0: LBA48 NCQ (depth 16/32) ata1.00: configured for UDMA/133 scsi 0:0:0:0: Direct-Access ATA WDC WD1600AAJS PQ: 0 ANSI: 5 sd 0:0:0:0: [sda] 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@ls2088 root]# fdisk -l /dev/sda Disk /dev/sda: GB, bytes 255 heads, 63 sectors/track, cylinders Units = cylinders of * 512 = bytes Device Boot Start End Blocks Id System /dev/sda Linux /dev/sda Linux swap /dev/sda Linux /dev/sda f Win95 Ext'd (LBA) NXP Semiconductors 89

90 Linux Kernel Drivers Serial Peripheral Interface /dev/sda Linux /dev/sda Linux root]# root]# mke2fs /dev/sda1 mke2fs (27-Jan-2009) Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) inodes, blocks blocks (5.00%) reserved for the super user First data block=0 Maximum filesystem blocks= block groups blocks per group, fragments per group 8160 inodes per group Superblock backups stored on blocks: 32768, 98304, , Writing inode tables: done Writing superblocks and filesystem accounting information: done This filesystem will be automatically checked every 22 mounts or 180 days, whichever comes first. Use tune2fs -c or -i to override. [root@ls2088 root]# [root@ls2088 root]# mkdir sata [root@ls2088 root]# mount /dev/sda1 sata [root@ls2088 root]# ls sata/ lost+found [root@ls2088 root]# cp /bin/busybox sata/ [root@ls2088 root]# umount sata/ [root@ls2088 root]# mount /dev/sda1 sata/ [root@ls2088 root]# ls sata/ busybox lost+found [root@ls2088 root]# umount sata/ [root@ls2088 root]# mount /dev/sda3 /mnt [root@ls2088 root]# df Filesystem 1K-blocks Used Available Use% Mounted on rootfs % / /dev/root % / tmpfs % /dev shm % /dev/shm /dev/sda % /mnt Known Bugs, Limitations, or Technical Issues CDROM is not supported due to the silicon limitation 6.8 Serial Peripheral Interface DSPI Device Driver User Manual 90 NXP Semiconductors

91 Linux Kernel Drivers Serial Peripheral Interface DSPI Device Driver User Manual LS1021-QDS board - U-Boot Configuration Use QSPI boot mode to boot LS1021A-QDS board. SW1[1:8]+SW2[1]=0100_ SW6[1:4]=0b'1111 QDS X-nor card hardware configuration SW1[1:4]=1000 SW4[1:4]=1111 SW3[1:4]=0001 J3: short 1-2, J4: short 1-2. This configuration can make DSPI device and QSPI device work at same time in X-nor card. Kernel Configure Tree View Options Device Drivers ---> [*] SPI support ---> <*> Freescale DSPI controller Device Drivers ---> <*> Memory Technology Device (MTD) support ---> Self-contained MTD device drivers ---> <*> Support for AT45xxx DataFlash Compile-time Configuration Options Config Values Default Value Description CONFIG_SPI_FSL_DSPI y/n y Enable DSPI module CONFIG_MTD_DATAFLASH y/n y Enables MTD devices for DSPI flash Verification in U-Boot LS1021a-qds Verification in U-Boot: => sf probe 1:0 SF: Detected AT45DB021D with page size 256 Bytes, erase size 2 KiB, total 256 KiB => sf erase SF: x0 Erased: OK => sf write SF: x0 Written: OK => sf read SF: x0 Read: OK NXP Semiconductors 91

92 Linux Kernel Drivers Universal Serial Bus Interfaces => cm.b Total of 4096 byte(s) were the same Verification in Linux: The booting log... mtd_dataflash spi0.0: at45db021d (256 KBytes) pagesize 256 bytes (OTP) 6Freescale DSPI master initialized... Erase the DSPI flash ~ # mtd_debug erase /dev/mtd0 0x Erased bytes from address 0x in flash Write the DSPI flash ~ # dd if=/bin/tempfile.debianutils of=tp bs=4096 count=1 ~ # mtd_debug write /dev/mtd tp Copied 4096 bytes from tp to address 0x in flash Read the DSPI flash ~ # mtd_debug read /dev/mtd dump_file Copied 4096 bytes from address 0x 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, the DSPI verification is passed. 6.9 Universal Serial Bus Interfaces USB 2.0 Host Driver USB 2.0 Host Driver User Manual Description The driver supports USB controller in host mode Module Loading The USB Host driver in linux supports either kernel built-in or module driver. U-boot USB driver is always built-in 92 NXP Semiconductors

93 Linux Kernel Drivers Universal Serial Bus Interfaces U-Boot Compile Time Configuration Options U-Boot Configure Options #define CONFIG_HAS_FSL_DR_USB Description Enables USB host Dual Role controller support. Defined inside platform config file: include/configs/<platform.h>. #ifdef CONFIG_HAS_FSL_DR_USB #define CONFIG_USB_EHCI #ifdef CONFIG_USB_EHCI #define CONFIG_CMD_USB #define CONFIG_USB_STORAGE #define CONFIG_USB_EHCI_FSL #define CONFIG_EHCI_HCD_INIT_AFTER_RESET #define CONFIG_CMD_EXT2 CONFIG_SYS_FSL_USB_INTERNAL_UTMI_PHY CONFIG_USB_MAX_CONTROLLER_COUNT Enable internal UTMI Phy support. Required only for SoCs having internal UTMI PHY. Defined inside file: arch/powerpc/include/asm/ config_mpc85xx.h Tell maximum no. of USB controllers in this SoC. Defined inside file: arch/powerpc/include/asm/config_mpc85xx.h U-Boot Source Files The driver source is maintained in the U-boot source in following files Source File drivers/usb/host/ehci-fsl.c common/cmd_usb.c drivers/usb/host/ehci-hcd.c Description EHCI FSL USB host controller driver Common usb command file EHCI USB host controller driver Kernel Configure Tree View Options Kernel Configure Tree View Options Device Drivers---> Description Enables USB host controller support USB support ---> [*] Support for Host-side USB Device Drivers---> Enables EHCI Host Controller Driver and transaction translator. USB support ---> NXP Semiconductors 93

94 Linux Kernel Drivers Universal Serial Bus Interfaces Table continued from the previous page... Kernel Configure Tree View Options Description <*> EHCI HCD (USB 2.0) support -*- Root Hub Transaction Translators (EXPERIMENTAL) [ ] Improved Transaction Translator scheduling [*] Support for Freescale on-chip EHCI USB controller [*] EHCI support for PPC USB controller on OF platform bus <*> OHCI HCD support [*] OHCI support for PPC USB controller on OF platform bus [*] Support big endian HC [*] Support little endian HC [*] OHCI support for PCI-bus USB controllers Compile-time Configuration Options Option Values Default Value Description CONFIG_USB y/m/n y Enables USB host controller CONFIG_USB_EHCI_HCD y/m/n y Enables EHCI HCD CONFIG_USB_EHCI_ROOT_HUB_TT y/n y Enables EHCI to support USB1.1 device CONFIG_USB_OHCI_HCD y/m/n y Enables OHCI HCD Kernel Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/usb/host/ehci-fsl.c arch/powerpc/sysdev/fsl_soc.c drivers/usb/host/ohci_hcd.c Description EHCI USB host controller driver Hook between OF tree and platform device OHCI USB host controller driver Device Tree Binding usb@22000 { #address-cells = <1>; #size-cells = <0>; 94 NXP Semiconductors

95 Linux Kernel Drivers Universal Serial Bus Interfaces compatible = "fsl-usb2-<controller-type>-v<controller version>", "fsl-usb2-<controller-type>"; reg = <0x x1000>; interrupt-parent = <&mpic>; interrupts = <28 0x2>; phy_type = "ulpi"; /* ulpi/utmi/utmi_dual */ dr_mode = "host" /* host, peripheral */ }; NOTE controller-type: dr(dual-role), mph(multi-port-host) controller-version: 1.6, 2.2, or earlier default mode is always host Verification in U-Boot U-boot environment to specify usb phy and usb mode type => setenv hwconfig 'usb<controller-no>:dr_mode=<mode>,phy_type=<phy_type>;<next usb controller>' For example: For socs having single usb controller and ULPI phy => setenv hwconfig 'usb1:dr_mode=host,phy_type=ulpi' For socs having single usb controller and UTMI phy => setenv hwconfig 'usb1:dr_mode=host,phy_type=utmi' For socs having two usb controllers and ULPI phys only => setenv hwconfig 'usb1:dr_mode=host,phy_type=ulpi;usb2:dr_mode=host,phy_type=ulpi' Then use usb start to start the usb device => usb start (Re)start USB... USB: Register NbrPorts 1 USB EHCI 1.00 scanning bus for devices... 2 USB Device(s) found scanning bus for storage devices... 1 Storage Device(s) found => usb dev NXP Semiconductors 95

96 Linux Kernel Drivers Universal Serial Bus Interfaces USB device 0: Vendor: SanDisk Rev: 8.02 Prod: Cruzer Colors+ Type: Removable Hard Disk Capacity: MB = 7.4 GB ( x 512) => usb tree Device Tree: 1 Hub (480 Mb/s, 0mA) u-boot EHCI Host Controller +-2 Mass Storage (480 Mb/s, 500mA) JetFlash Mass Storage Device 63ZOA56O8TZFZ0AC => usb info 1: Hub, USB Revision u-boot EHCI Host Controller - Class: Hub - PacketSize: 64 Configurations: 1 - Vendor: 0x0000 Product 0x0000 Version 1.0 Configuration: 1 - Interfaces: 1 Self Powered 0mA Interface: 0 - Alternate Setting 0, Endpoints: 1 - Class Hub - Endpoint 1 In Interrupt MaxPacket 2048 Interval 255ms 2: Mass Storage, USB Revision JetFlash Mass Storage Device 63ZOA56O8TZFZ0AC - Class: (from Interface) Mass Storage - PacketSize: 64 Configurations: 1 - Vendor: 0x8564 Product 0x1000 Version 17.0 Configuration: 1 - Interfaces: 1 Bus Powered 500mA Interface: 0 - Alternate Setting 0, Endpoints: 2 - Class Mass Storage, Transp. SCSI, Bulk only - Endpoint 1 In Bulk MaxPacket Endpoint 2 Out Bulk MaxPacket 512 => md : cc F,...) : 00c48e a $...P : 083d a00000 b012a502.=8...p@ : d b (..E...@$D : 022b b d $. a : 8012b c b880...(....c : a4c c0 B@...).(..@ : a8c0 448aae : 2800c800 04b a62324 (....`...#$ : 04870a08 a a a0: b 02044c b0: c a " c0: 000c020a 0012b c $.(, d0: b $.`...b e0: 38d0f e03 1d (B...$" f0: 6c d40 41c08011 l!r0....@a NXP Semiconductors

97 Linux Kernel Drivers Universal Serial Bus Interfaces => mw ffffaaaa 100 => md : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa a0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa b0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa c0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa d0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa e0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa f0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa... => usb write USB write: device 0 block # 0, count blocks write: OK => md : fbf3eae6 2feeffbf dbf7775d ff5bebf7.../...w].[ : abefefaf 7dbb3e3b bfffb5bb bfb86a7f...}.>;...j : eff7b68f deaadfff eebf7bff bd7fed1f...{ : ffef7deb e7bfbbef dfeff7df 7f3ffcba..}...? : ab3bfbfe dfdee69b ffe18fd5 ff3e777f.;...>w : da7effef bfabff7f f58ef768 9ffffeff.~...h : cfebf8b0 f1b7dfef e9eefbfe f37bbadb...{ : b7f34ea2 da7efbff dfdff7ff f7effde3..n..~ : fffbebff fe56ff5d 6ffd7ffd ff87efdf...v.]o : b6bfafac ddebfbfb ffacebfd f87bff9f...{ a0: ffebffff ff7e7ff9 aefefd7f 5f7f5ebf...~..._.^ b0: 6fe87e7b fabfdbcf d3faefad 6fbb5e7a o.~{...o.^z c0: f6af86de ffdb7bbf ff5ff6ba bfa4bfdf...{.._ d0: ffbfa87f ffe67fcd efeffb9a 9b7e6a6f...~jo e0: fffcf76f efbfeebb ffaceab1 5cfbfffe...o...\ f0: edebffde e29fefff deaeafdb f97bdff5...{.. => usb read USB read: device 0 block # 0, count blocks read: OK => md : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa : ffffaaaa ffffaaaa ffffaaaa ffffaaaa a0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa b0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa c0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa d0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa e0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa f0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa... => NXP Semiconductors 97

98 Linux Kernel Drivers Universal Serial Bus Interfaces Verification in Linux Kernel configuration for USB memory stick support * Device Drivers---> SCSI Device Support---> SCSI Device Support ---> <*> SCSI disk support * Device Drivers---> SCSI Device Support---> SCSI Device Support ---> <*> SCSI generic support * Device Drivers---> USB Support---> [*] USB Mass Storage Support (The user can enable it either in kernel mode (set option as True) or as module (set option as Module)). * File Systems---> DOS/FAT/NT Filesystems---> <*> MSDOS fs support * File Systems---> DOS/FAT/NT Filesystems---> <*> VFAT(Window-95)fs support * File Systems---> DOS/FAT/NT Filesystems---> VFAT(Window-95)fs support---> Default codepage for FAT * File Systems---> DOS/FAT/NT Filesystems---> VFAT(Window-95)fs support---> Default iocharset for FAT - "iso8859-1" * File Systems---> Partition Types---> [*] Advanced partition selection * File Systems---> Partition Types---> [*] PC BIOS (MSDOS partition tables) support * File Systems---> Native Language Support---> Base native language support---> (iso8859-1) Default NLS Option * File Systems---> Native Language Support---> Base native language support---> <*> Codepage 437 (United States, Canada) * File Systems---> Native Language Support---> Base native language support---> <*> NLS ISO (Latin 1; Western European Languages) plug in memory stick ~ # usb 1-1: new high speed USB device using fsl-ehci and address 2 usb 1-1: configuration #1 chosen from 1 choice scsi6 : SCSI emulation for USB Mass Storage devices scsi 6:0:0:0: Direct-Access SanDisk Cruzer 7.01 PQ: 0 ANSI: 0 CCS sd 6:0:0:0: [sda] byte hardware sectors: (2.00 GB/1.86 GiB) sd 6:0:0:0: [sda] Write Protect is off sd 6:0:0:0: [sda] Assuming drive cache: write through sd 6:0:0:0: [sda] byte hardware sectors: (2.00 GB/1.86 GiB) sd 6:0:0:0: [sda] Write Protect is off sd 6:0:0:0: [sda] Assuming drive cache: write through 98 NXP Semiconductors

99 Linux Kernel Drivers Universal Serial Bus Interfaces sda: sda1 sd 6:0:0:0: [sda] Attached SCSI removable disk sd 6:0:0:0: Attached scsi generic sg0 type 0 scsi 6:0:0:1: CD-ROM SanDisk Cruzer 7.01 PQ: 0 ANSI: 0 sr0: scsi3-mmc drive: 48x/48x tray Uniform CD-ROM driver Revision: 3.20 sr 6:0:0:1: Attached scsi generic sg1 type 5 ~ # fdisk -l Disk /dev/sda: 2000 MB, bytes 64 heads, 63 sectors/track, 969 cylinders Units = cylinders of 4032 * 512 = bytes Device Boot Start End Blocks Id System /dev/sda b Win95 FAT32 ~ # mount -t vfat /dev/sda1 /mnt/cdrom/ ~ # cd /mnt/cdrom/ /mnt/cdrom # ls /mnt/cdrom # cp /usr/sbin/wd_keepalive. /mnt/cdrom # ls wd_keepalive /mnt/cdrom # cd.. /mnt # umount /mnt/cdrom/ ==================================================================================== To create ext2 file-system on USB flash drive, follow below steps: # fdisk /dev/sda Device contains neither a valid DOS partition table, nor Sun, SGI or OSF disklab el Building a new DOS disklabel. Changes will remain in memory only, until you decide to write them. After that the previous content won't be recoverable. Command (m for help): n Command action e extended p primary partition (1-4) NXP Semiconductors 99

100 Linux Kernel Drivers Universal Serial Bus Interfaces p Partition number (1-4): 1 First cylinder (1-1011, default 1): Using default value 1 Last cylinder or +size or +sizem or +sizek (1-1011, default 1011): Using default value 1011 Command (m for help): w The partition table has been altered! Calling ioctl() to re-read partition table sd 2:0:0:0: [sda] Test WP failed, assume Write Enabled sd 2:0:0:0: [sda] Assuming drive cache: write through sda: sda1 [root@p5020 root]# mke2fs /dev/sda1 mke2fs Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) inodes, blocks blocks (5.00%) reserved for the super user First data block=0 Maximum filesystem blocks= block groups blocks per group, fragments per group 8192 inodes per group Superblock backups stored on blocks: 32768, 98304, , Writing inode tables: done Writing superblocks and filesystem accounting information: done This filesystem will be automatically checked every 38 mounts or 180 days, whichever comes first. Use tune2fs -c or -i to override. [root@p5020 /root]# mount /dev/sda1 /mnt Kernel configuration for USB Human Input Devices support * Device Drivers---> [*] HID Devices ---> -*- Generic HID support <*> USB Human Interface Device (full HID) support Input device support ---> -*- Generic input layer (needed for keyboard, mouse,...) <*> Mouse interface [*] Provide legacy /dev/psaux device (1024) Horizontal screen resolution (768) Vertical screen resolution [*] Keyboards ---> 100 NXP Semiconductors

101 Linux Kernel Drivers Universal Serial Bus Interfaces <*> AT keyboard [*] Mice ---> <*> PS/2 mouse [*] ALPS PS/2 mouse protocol extension [*] Logitech PS/2++ mouse protocol extension [*] Synaptics PS/2 mouse protocol extension [*] IBM Trackpoint PS/2 mouse protocol extension plug in USB keyboard ~ # usb 1-1: new full speed USB device using fsl-ehci and address 3 usb 1-1: configuration #1 chosen from 1 choice hub 1-1:1.0: USB hub found hub 1-1:1.0: 3 ports detected usb 1-1.1: new full speed USB device using fsl-ehci and address 4 usb 1-1.1: configuration #1 chosen from 1 choice input: Dell Dell USB Keyboard Hub as /class/input/input1 generic-usb 0003:413C: : input: USB HID v1.10 Keyboard [Dell Dell USB Ke yboard Hub] on usb-fsl-ehci.0-1.1/input0 input: Dell Dell USB Keyboard Hub as /class/input/input2 generic-usb 0003:413C: : input: USB HID v1.10 Device [Dell Dell USB Keyb plug in USB mouse ~ # usb 1-1: new low speed USB device using fsl-ehci and address 2 usb 1-1: configuration #1 chosen from 1 choice input: HID 413c:3010 as /class/input/input0 generic-usb 0003:413C: : input: USB HID v1.00 Mouse [HID 413c:3010] on u Power Management Following Pwr. Mgmt. features are supported: 1) Sleep 2) Deep Sleep NXP Semiconductors 101

102 Linux Kernel Drivers Universal Serial Bus Interfaces Pwr. Mgmt. Kernel Configuration Option(s) Kernel Configure Tree View Options Description Enable Power Management feature Kernel options---> [*] Suspend to RAM and standby [*] Hibernation (aka 'suspend to disk') () Default resume partition (NEW) Enable the CPU frequency driver Platform support --> CPU Frequency scaling --> [*] CPU Frequency scaling <*> CPU frequency translation statistics Default CPUFreq governor (userspace) --> -*- 'userspace' governor for userspace frequency scaling CPU Frequency drivers --> [*] Support for Freescale MPC85xx CPU freq Verification in Linux Sleep Capability A system can be put into Suspend state, and can also be Resumed (woken-up) by USB. For this the following needs to be done: 1. Enable USB remote wake-up capability before putting the system into Suspend state ~ # echo enabled >/sys/bus/usb/devices/usb1/power/wakeup 2. Insert/Remove a USB flash drive into USB port after the system is put into SUSPEND state. This will bring the system out of the SUSPEND state # echo standby > /sys/power/state PM: Syncing filesystems... done. Freezing user space processes... (elapsed 0.01 seconds) done. Freezing remaining freezable tasks... (elapsed 0.01 seconds) done. Suspending console(s) (use no_console_suspend to debug) sd 0:0:0:0: [sda] Synchronizing SCSI cache sd 0:0:0:0: [sda] Stopping disk PM: suspend of devices complete after msecs PM: late suspend of devices complete after msecs PM: noirq suspend of devices complete after msecs Disabling non-boot CPUs... USB Flash drive inserted ---> Enabling non-boot CPUs... CPU1 is up PM: noirq resume of devices complete after msecs PM: early resume of devices complete after msecs fsl-lbc ffe05000.localbus: Chip select error: LTESR 0x NXP Semiconductors

103 Linux Kernel Drivers Universal Serial Bus Interfaces 0xfff00000 /pcie@ffe0a000: 0x0 /pcie@ffe0a000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. /pcie@ffe0a000: DMA window size is 0x0 /pcie@ffe0b000: 0x0 /pcie@ffe0b000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. /pcie@ffe0b000: DMA window size is 0x0 pci 0000:00:00.0: enabling device (0106 -> 0107) pci 0001:02:00.0: enabling device (0106 -> 0107) pci 0002:04:00.0: enabling device (0106 -> 0107) ata2: No Device OR PHYRDY change,hstatus = 0xa ata2: SATA link down (SStatus 0 SControl 300) ata1: Signature Update 504 msecs ata1: SATA link up 3.0 Gbps (SStatus 123 SControl 300) ata1.00: configured for UDMA/133 sd 0:0:0:0: [sda] Starting disk PM: resume of devices complete after msecs Restarting tasks... done. root@p1022ds:~# usb 1-1: new high-speed USB device number 2 using fsl-ehci scsi2 : usb-storage 1-1:1.0 scsi 2:0:0:0: Direct-Access SRT USB 1100 PQ: 0 ANSI: 4 sd 2:0:0:0: Attached scsi generic sg1 type 0 sd 2:0:0:0: [sdb] byte logical blocks: (7.97 GB/7.42 GiB) sd 2:0:0:0: [sdb] Write Protect is off sd 2:0:0:0: [sdb] Mode Sense: sd 2:0:0:0: [sdb] No Caching mode page present sd 2:0:0:0: [sdb] Assuming drive cache: write through sd 2:0:0:0: [sdb] No Caching mode page present sd 2:0:0:0: [sdb] Assuming drive cache: write through sdb: sdb1 sd 2:0:0:0: [sdb] No Caching mode page present sd 2:0:0:0: [sdb] Assuming drive cache: write through sd 2:0:0:0: [sdb] Attached SCSI removable disk FAT-fs (sdb): error, fat_get_cluster: invalid cluster chain (i_pos 0) FAT-fs (sdb): Filesystem has been set read-only Deep Sleep Capability USB working across Deep sleep using Timer Interrupt System is put into deep sleep using the following command : ~# echo 30 > /sys/devices/system/mpic/timer_wakeup;echo mem > /sys/power/state PM: Syncing filesystems... done. mmc0: card e624 removed Freezing user space processes... (elapsed seconds) done. Freezing remaining freezable tasks... (elapsed seconds) done. Suspending console(s) (use no_console_suspend to debug) sd 0:0:0:0: [sda] Synchronizing SCSI cache sd 0:0:0:0: [sda] Stopping disk PM: suspend of devices complete after msecs PM: late suspend of devices complete after msecs PM: noirq suspend of devices complete after msecs Disabling non-boot CPUs... /pcie@ffe240000: 0xff /pcie@ffe240000: Setup 64-bit PCI DMA window /pcie@ffe240000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. NXP Semiconductors 103

104 Linux Kernel Drivers Universal Serial Bus Interfaces DMA window size is 0xe xff /pcie@ffe250000: Setup 64-bit PCI DMA window /pcie@ffe250000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. /pcie@ffe250000: DMA window size is 0xe /pcie@ffe260000: 0x0 /pcie@ffe260000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. /pcie@ffe260000: DMA window size is 0x0 /pcie@ffe270000: 0xff /pcie@ffe270000: Setup 64-bit PCI DMA window /pcie@ffe270000: WARNING: Outbound window cfg leaves gaps in memory map. Adjusting the memory map could reduce unnecessary bounce buffering. /pcie@ffe270000: DMA window size is 0xe After 30 seconds, system comes out of deep sleep and usb storage device is successfully detected Enabling non-boot CPUs... CPU1 is up CPU2 is up CPU3 is up PM: noirq resume of devices complete after msecs PM: early resume of devices complete after msecs caam ffe crypto: Instantiated RNG4 SH0 caam ffe crypto: Instantiated RNG4 SH1 ata2: No Device OR PHYRDY change,hstatus = 0x ata2: SATA link down (SStatus 10 SControl 300) ata1: Signature Update 504 msecs ata1: SATA link up 3.0 Gbps (SStatus 123 SControl 300) ata1.00: configured for UDMA/133 sd 0:0:0:0: [sda] Starting disk PM: resume of devices complete after msecs Restarting tasks... done. usb 1-1: USB disconnect, device number 3 root@t1040rdb:~# EXT2-fs (sdb1): previous I/O error to superblock detected EXT2-fs (sdb1): previous I/O error to superblock detected EXT2-fs (sdb1): previous I/O error to superblock detected EXT2-fs (sdb1): previous I/O error to superblock detected mmc0: new high speed SDHC card at address e624 mmcblk0: mmc0:e624 SU08G 7.40 GiB mmcblk0: p1 usb 1-1: new high-speed USB device number 4 using fsl-ehci usb-storage 1-1:1.0: USB Mass Storage device detected scsi4 : usb-storage 1-1:1.0 scsi 4:0:0:0: Direct-Access JetFlash Transcend 4GB 8.07 PQ: 0 ANSI: 4 sd 4:0:0:0: Attached scsi generic sg1 type 0 sd 4:0:0:0: [sdb] byte logical blocks: (4.01 GB/3.73 GiB) sd 4:0:0:0: [sdb] Write Protect is off sd 4:0:0:0: [sdb] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA sdb: sdb1 sd 4:0:0:0: [sdb] Attached SCSI removable disk Deep Sleep using USB wake-up interrupt This feature is not yet supported. 104 NXP Semiconductors

105 Linux Kernel Drivers Universal Serial Bus Interfaces Known Bugs, Limitations, or Technical Issues 1. Across system Deep Sleep, if a device is already mounted, it may get umounted automatically. Hence, to use it again, the user needs to re-mount the device 2. USB remote wake-up during system Deep-Sleep is not yet supported 3. On some platforms where USB2 controller is muxed with some other IP, USB2 is disabled in default platform configurations inside both U-boot and Linux. For more details, please refer Platform BSP/Board User Manuals 4. Dual-Utmi Phy HW register restoration requirement for System Deep-Sleep feature: Some SoCs have a new utmi phy version called "dual-utmi" phy (for example: T1040, T1042, T1020, T1022, T2080, T2081: rev1.0 and rev1.1 ). This dualphy hw registers need to be saved and restored across system Deep-Sleep. Hence, a code is added in u-boot usb driver that identifies all socs having this dual-utmi phy, and adds "dual_utmi" in phy_type property. This is used to determine if all phy registers are to be saved (during system-suspend) and restored (during system-resume). In absence of restoration of dual-phy hw registers, system restore during deep-sleep is going to fail - system hangs and goes into non-recoverable state USB Gadget Network Driver User Manual USB 2.0 Gadget Network Driver User Manual Description The NXP processor has a High speed Dual-Role(DR) USB controller, which supports device mode Module Loading USB device controller driver can be built in kernel or compiled as a module. Gadget drivers are recommended to be built as modules, because parameters will be passed as module parameter Table 4. Kernel Configure Tree View Options Kernel Configure Tree View Options Description Need to enable CONFIG_USB_FSL_MPH_DR_OF Device Drivers ---> USB support ---> <*> Support for Host-side USB <*> EHCI HCD (USB 2.0) support -*- Root Hub Transaction Translators [ ] Use Xilinx usb host EHCI controller core [*] Support for Freescale PPC on-chip EHCI USB controller Table continues on the next page... NXP Semiconductors 105

106 Linux Kernel Drivers Universal Serial Bus Interfaces Table 4. Kernel Configure Tree View Options (continued) Kernel Configure Tree View Options Description Enable NXP USB Device Controller support Device Drivers ---> USB support ---> USB Gadget Support ---> < M > Support for USB Gadgets USB Peripheral Controller (Freescale Highspeed USB DR Peripheral Controller) ---> Freescale Highspeed USB DR Peripheral Controller Enable USB Gadget support Device Drivers ---> USB support ---> USB Gadget Support ---> < M > Support for USB Gadgets USB Gadget Drivers <M> Ethernet Gadget (with CDC Ethernet support) [*]RNDIS support (NEW) [ ]Ethernet Emulation Model (EEM) support (NEW) Table 5. Compile-time Configuration Options Options Values Default Description CONFIG_USB_SUPPORT y/n/m Ym Enable USB Support CONFIG_USB_FSL_MPH_ DR_OF y/n/m Y Enable NXP EHCI USB controller CONFIG_USB_GADGET y/n/m m Enable USB Gadget modules CONFIG_USB_GADGET_F SL_USB2 y/n/m m Enable NXP USB peripheral controller CONFIG_USB_ETH y/n/m m Enable Ethernet Gadget CONFIG_USB_ETH_RNDI S y/n y Enable Ethernet Gadget 106 NXP Semiconductors

107 Linux Kernel Drivers Universal Serial Bus Interfaces Source Files The driver source is maintained in the Linux kernel source tree. Table 6. Source Files Source File drivers/usb/gadget/fsl_usb2_udc.c drivers/usb/host/fsl-mph-dr-of.c drivers/usb/gadget/ether.c Drivers/usb/gadget/rndis.[ch] Description NXP USB peripheral controller driver Hook between OF tree and platform device Ethernet gadget driver Microsoft s RNDIS support Device Tree Entry usb@22000 { #address-cells = <1>; #size-cells = <0>; compatible = "fsl-usb2-<controller-type>-v<controller version>", "fsl-usb2-<controller-type>"; reg = <0x x1000>; /* specifies register base addr, soc dependent */ interrupt-parent = <&mpic>; interrupts = <28 0x2>; /* specifies usb interrupt line, soc dependent */ phy_type = "ulpi"; /* phy can be ulpi(external)/utmi(internal) */ dr_mode = "peripheral" /* this entry specifies usb mode */ }; NOTE Controller-type: dr(dual-role), mph(multi-port-host) controller-version: 1.6, 2.2, or earlier default mode is always host. It can be either changed to peripheral inside the dts entry like above. In this case re-compilation of dts is required. DR mode can also be changed to peripheral via u-boot command line. This won't require DTS recompilation, and can work with default DTS For USB1 controller. => setenv hwconfig 'usb1:dr_mode=peripheral,phy_type=<ulpi/utmi> Test Procedure For board specific changes (required for USB Gadget mode), please refer to the board BSP User Manual. 1. Bring all USB Gadget modules (driver/usb/gadget/*.ko including fs/configfs/configfs.ko) onto the target board. 2. Load device controller driver and test ethernet gadget Load FSL gadget driver module udc-core.ko & fsl_usb2_udc.ko bash# insmod udc-core.ko bash# insmod fsl_usb2_udc.ko Load Ethernet modules bash# insmod configfs.ko NXP Semiconductors 107

108 Linux Kernel Drivers Universal Serial Bus Interfaces bash# insmod libcomposite.ko bash# insmod u_ether.ko bash# insmod u_rndis.ko bash# insmod usb_f_rndis.ko bash# insmod usb_f_ecm.ko bash# insmod usb_f_ecm_subset.ko bash# insmod g_ether.ko using random self ethernet address using random host ethernet address usb0: HOST MAC 82:14:b4:63:d1:85 usb0: MAC 4a:b1:59:3b:b3:bd using random self ethernet address using random host ethernet address g_ether gadget: Ethernet Gadget, version: Memorial Day 2008 g_ether gadget: g_ether ready bash# ifconfig usb0 usb0 Link encap:ethernet HWaddr 5e:0c:de:2f:f9:0f BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 3. Assign an IP to usb0 bash# ifconfig usb netmask up IPv6: ADDRCONF(NETDEV_UP): usb0: link is not ready bash# ifconfig usb0 usb0 usb0 Link encap:ethernet HWaddr 5e:0c:de:2f:f9:0f inet addr: Bcast: Mask: UP BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 4. Connect a USB cable between target board USB port and the USB port on Windows host machine. As soon as USB cable is plugged into a Windows XP host, the following message displays: title=setting_up_usbnet#install_the_rndis_driver 5. Download linux.inf from either of the following, and install the Windows XP RNDIS driver as mentioned in the previous step: For Windows 7, driver will automatically install. 108 NXP Semiconductors

109 Linux Kernel Drivers Universal Serial Bus Interfaces 6. As soon as driver installed on host, the following message displays on the target: bash# g_ether gadget: high-speed config #2: RNDIS IPv6: ADDRCONF(NETDEV_CHANGE): usb0: link becomes ready 7. Once the RNDIS driver is installed, configured, and loaded, configure the IP address for the new network device. For example, assign as IP to the RNDIS device and run ipconfig to verify the network configuration. 8. Now run ping both ways to check the connectivity between and D:\Profiles>ping Pinging with 32 bytes of data: Reply from : bytes=32 time<1ms TTL=64 Reply from : bytes=32 time<1ms TTL=64 Reply from : bytes=32 time<1ms TTL=64 Ping statistics for : Packets: Sent = 3, Received = 3, Lost = 0 (0% loss), Approximate round trip times in milli-seconds: Minimum = 0ms, Maximum = 0ms, Average = 0ms bash# ping PING ( ): 56 data bytes 64 bytes from : seq=0 ttl=128 time=4.352 ms 64 bytes from : seq=1 ttl=128 time=1.015 ms 64 bytes from : seq=2 ttl=128 time=0.974 ms 64 bytes from : seq=3 ttl=128 time=0.935 ms 64 bytes from : seq=4 ttl=128 time=1.021 ms ping statistics packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max = 0.935/1.659/4.352 ms Known Bugs, Limitations, or Technical Issues If a board/platform is having multiple USB controller, they cannot be simultaneously used in "gadget/peripheral" mode. Please do not set dr_mode as peripheral for both the controllers at the same time. Supporting Documentation Linux USB gadget framework - Please refer to for setting up the RNDIS on Windows XP. Linux USB 3.0 Host/Peripheral Linux Driver User Manual NXP Semiconductors 109

110 Linux Kernel Drivers Universal Serial Bus Interfaces 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 Super-speed (5 GT/s), High-speed (480 Mbps), full-speed (12 Mbps), and low-speed (1.5 Mbps) operations Supports operation as a standalone single port USB Supports eight programmable, bidirectional USB endpoints OTG (On-The-Go) 2.0 compliant, which includes both device and host capability. Modes of Operation Host Mode: SS/HS/FS/LS Device Mode: SS/HS/FS OTG: HS/FS/LS 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 Options Description Enables USB host controller support Device Drivers---> USB support ---> [*] Support for Host-side USB Device Drivers---> Enables XHCI Host Controller Driver and transaction translator USB support ---> <*> xhci HCD (USB 3.0) support Table continues on the next page NXP Semiconductors

111 Linux Kernel Drivers Universal Serial Bus Interfaces Table continued from the previous page... Kernel Configure Tree View Options Device Drivers---> USB support ---> <*> USB Mass Storage support Description Enable support for USB mass storage devices. This is the driver needed for USB flash devices, and memory sticks [ ] 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 Enables support for USB Audio devices. This driver is needed for USB microphone. 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) Note: Required only for USB Gadget/ Peripheral Support Enable driver for peripheral/device controller Enable Ethernet Gadget Client driver Enable Mass Storage Client driver Device Drivers---> Enable XHCI DRD Core Support <*> DesignWare USB3 DRD Core Support DWC3 Mode Selection (Dual Role mode) ---> Compile-time Configuration Options Option Values Default Value Description CONFIG_USB y/m/n y Enables USB host controller CONFIG_USB_XHCI_HCD y/m/n y Enables XHCI HCD CONFIG_USB_DWC3 y/m/n y Enables DWC3 Controller Table continues on the next page... NXP Semiconductors 111

112 Linux Kernel Drivers Universal Serial Bus Interfaces Table continued from the previous page... Option Values Default Value Description CONFIG_USB_GADGET y/m/n n Enables USB peripheral device CONFIG_USB_ETH y/m/n n Enable Ethernet style communication CONFIG_USB_MASS_STORAGE m/n n Enable USB Mass Storage disk drive CONFIG_SOUND y/m/n y Enables Sound Card Support CONFIG_SND y/m/n y Enables ALSA (Advanced Linux Sound Architecture) CONFIG_SND_MIXER_OSS y/m/n y Enables OSS Mixer API CONFIG_SND_PCM_OSS y/m/n y Enables OSS PCM (digital audio) API CONFIG_SND_PCM_OSS_PLUGINS y/n y Enables OSS PCM (digital audio) API - Include plugin system CONFIG_SND_SUPPORT_OLD_API y/n y Enables old ALSA API CONFIG_SND_USB y/n n Enables USB sound devices CONFIG_SND_USB_AUDIO y/m/n n Enables USB Audio/MIDI driver 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 Table continued from the previous page... Source File Description drivers/usb/host/xhci-* drivers/usb/gadget/mass_storage.c drivers/usb/gadget/ether.c xhci platform driver USB Mass Storage Ethernet gadget driver Device Tree Binding for Host usb@ { compatible = "snps,dwc3"; reg = <0x0 0x x0 0x10000>; interrupts = <GIC_SPI 93 IRQ_TYPE_LEVEL_HIGH>; dr_mode = "host; }; Device Tree Binding for Peripheral Note: with multiple USB controller, just one can be peripheral mode at a time. usb@ { compatible = "snps,dwc3"; 112 NXP Semiconductors

113 Linux Kernel Drivers Universal Serial Bus Interfaces }; reg = <0x0 0x x0 0x10000>; interrupts = <GIC_SPI 93 IRQ_TYPE_LEVEL_HIGH>; dr_mode = "peripheral; maximum-speed = "super-speed"; Host Testing 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 0x 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 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] 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] 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. NXP Semiconductors 113

114 Linux Kernel Drivers Universal Serial Bus Interfaces Make filesystem and mount connected USB flash drive using below commands /$ fdisk -l Disk /dev/sda: 16.0 GB, bytes 255 heads, 63 sectors/track, 1946 cylinders Units = cylinders of * 512 = bytes Device Boot Start End Blocks Id System /dev/sda Linux root@freescale /$ root@freescale /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm % /dev/shm rwfs % /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 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 (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! Calling ioctl() to re-read partition table root@freescale /$ root@freescale /$ root@freescale /$ fdisk -l Disk /dev/sda: 16.0 GB, bytes 255 heads, 63 sectors/track, 1946 cylinders Units = cylinders of * 512 = bytes Device Boot Start End Blocks Id System /dev/sda Linux root@freescale /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm % /dev/shm rwfs % /mnt/rwfs root@freescale /$ mkdir my_mnt 114 NXP Semiconductors

115 Linux Kernel Drivers Universal Serial Bus Interfaces /$ /$ /$ mkfs.ext2 /dev/sda1 Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) inodes, blocks blocks (5%) reserved for the super user First data block=0 Maximum filesystem blocks= block groups blocks per group, fragments per group 8144 inodes per group Superblock backups stored on blocks: 32768, 98304, , , , , , , /$ /$ /$ /$ /$ /$ mount /dev/sda1 my_mnt/ /$ /$ /$ /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm % /dev/shm rwfs % /mnt/rwfs /dev/sda % /my_mnt root@freescale /$ Test by wring/reading data on mount drive root@freescale /$ dd if=/dev/urandom of=/tmp/123 bs=1m count= records in records out bytes (100.0MB) copied, seconds, 1.8MB/s root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ cp /tmp/123 /my_mnt/. root@freescale /$ sync root@freescale /$ ls /my_mnt/ 123 lost+found root@freescale /$ Peripheral testing with Win7 as Host NOTE In gadget mode standard USB cables with micro plug should be used. Below Message will appear during bootup if dr_mode set as peripheral in device-tree usbcore: registered new interface driver usbfs usbcore: registered new interface driver hub usbcore: registered new device driver usb NXP Semiconductors 115

116 Linux Kernel Drivers Universal Serial Bus Interfaces usbcore: registered new interface driver usb-storage Make sure "dr_mode" contains "peripheral" string /$# cat peripheral /$ Move all below modeules to platform fs/configfs/configfs.ko driver/usb/gadget/libcomposite.ko driver/usb/gadget/g_mass_storage.ko driver/usb/gadget/u_rndis.ko driver/usb/gadget/u_ether.ko driver/usb/gadget/usb_f_ecm.ko driver/usb/gadget/usb_f_ecm_subset.ko driver/usb/gadget/usb_f_rndis.ko driver/usb/gadget/g_ether.ko Mass Storage Gadget To use ramdisk as a backing store use the following root@freescale /$ mkdir /mnt/ramdrive root@freescale /$ mount -t tmpfs tmpfs /mnt/ramdrive -o size=600m root@freescale /$ dd if=/dev/zero of=/mnt/ramdrive/vfat-file bs=1m count=500 root@freescale /$ mke2fs -F /mnt/ramdrive/vfat-file root@freescale /$ insmod configfs.ko root@freescale /$ insmod libcomposite.ko root@freescale /$ insmod usb_f_mass_storage.ko root@freescale /$ insmod g_mass_storage.ko file=/mnt/ramdrive/vfat-file stall=n We will get below messages [ ] g_mass_storage gadget: Mass Storage Function, version: 2009/09/11 [ ] g_mass_storage gadget: Number of LUNs=1 [ ] lun0: LUN: file: /home/backing_file_20mb [ ] g_mass_storage gadget: Mass Storage Gadget, version: 2009/09/11 [ ] g_mass_storage gadget: userspace failed to provide iserialnumber [ ] 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 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: [root@freescale ~]$ aplay l**** List of PLAYBACK Hardware Devices **** card 0: FSLVF610TWRBOAR [FSL-VF610-TWR-BOARD], device 0: HiFi sgtl [ ] Subdevices: 1/1 Subdevice #0: subdevice #0 116 NXP Semiconductors

117 Linux Kernel Drivers Universal Serial Bus Interfaces 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: ~]$ aplay -D hw:1,0 LYNC_fsringing.wav Playing WAVE 'LYNC_fsringing.wav' : Signed 16 bit Little Endian, Rate 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 foobar.wav -d 5 Recording WAVE 'foobar.wav' : Signed 16 bit Little Endian, Rate 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: [root@freescale ~]$ amixer c1 controls numid=3,iface=mixer,name='pcm Playback Switch' numid=4,iface=mixer,name='pcm Playback Volume' numid=5,iface=mixer,name='headset Capture Switch' numid=6,iface=mixer,name='headset Capture Volume' numid=2,iface=pcm,name='capture Channel Map' numid=1,iface=pcm,name='playback Channel Map' [root@freescale ~]$ amixer c1 Simple mixer control 'PCM',0 Capabilities: pvolume pvolume-joined pswitch pswitch-joined penum Playback channels: Mono Limits: Playback 0-11 Mono: Playback 4 [36%] [-20.00dB] [on] Simple mixer control 'Headset',0 Capabilities: cvolume cvolume-joined cswitch cswitch-joined penum Capture channels: Mono Limits: Capture 0-7 Mono: Capture 5 [71%] [0.00dB] [on] For Example, in above output there are two controls named PCM and Headset for Speaker and microphone respectively. Sample Audio controls Usage: a. mute/unmute [root@freescale ~]$ amixer -c1 set PCM mute Simple mixer control 'PCM',0 Capabilities: pvolume pvolume-joined pswitch pswitch-joined Playback channels: Mono Limits: Playback 0-11 Mono: Playback 2 [18%] [-28.00dB] [off] [root@freescale ~]$ amixer -c1 set PCM unmute Simple mixer control 'PCM',0 Capabilities: pvolume pvolume-joined pswitch pswitch-joined Playback channels: Mono Limits: Playback 0-11 Mono: Playback 2 [18%] [-28.00dB] [on] NXP Semiconductors 117

118 Linux Kernel Drivers Universal Serial Bus Interfaces b. volume up/down Below commands are trying to set volume to 11 and 2 performing volume up and down respectively. root@freescale ~]$ amixer -c1 set PCM 11 Simple mixer control 'PCM',0 Capabilities: pvolume pvolume-joined pswitch pswitch-joined Playback channels: Mono Limits: Playback 0-11 Mono: Playback 11 [100%] [8.00dB] [on] [root@freescale ~]$ amixer -c1 set PCM 2 Simple mixer control 'PCM',0 Capabilities: pvolume pvolume-joined pswitch pswitch-joined Playback channels: Mono Limits: Playback 0-11 Mono: Playback 2 [18%] [-28.00dB] [on] Ethernet Gadget To use Ethernet gadget use the following root@freescale /$ insmod configfs.ko root@freescale /$ insmod libcomposite.ko root@freescale /$ insmod u_ether.ko root@freescale /$ insmod u_rndis.ko root@freescale /$ insmod usb_f_ecm.ko root@freescale /$ insmod usb_f_ecm_subset.ko root@freescale /$ insmod usb_f_rndis.ko root@freescale /$ insmod g_ether.ko We will get below messages [ ] using random self ethernet address [ ] using random host ethernet address [ ] usb0: HOST MAC 82:96:69:7e:a5:7d [ ] usb0: MAC 72:00:a5:80:2b:e8 [ ] using random self ethernet address [ ] using random host ethernet address [ ] g_ether gadget: Ethernet Gadget, version: Memorial Day 2008 [ ] g_ether gadget: g_ether ready Make sure USB0 ethernet interface is available after this root@freescale /$ ifconfig -a can0 Link encap:unspec HWaddr 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 can1 Link encap:unspec HWaddr 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: NXP Semiconductors

119 Linux Kernel Drivers Universal Serial Bus Interfaces eth0 eth1 eth2 lo sit0 usb0 Link encap:ethernet HWaddr 00:E0:0C:BC:E5:60 BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Link encap:ethernet HWaddr 00:E0:0C:BC:E5:61 BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Link encap:ethernet HWaddr 00:E0:0C:BC:E5:62 inet addr: Bcast: Mask: inet6 addr: fe80::2e0:cff:febc:e562/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:2311 errors:0 dropped:3 overruns:0 frame:0 TX packets:66 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes: (283.9 KiB) TX bytes:8976 (8.7 KiB) Link encap:local Loopback inet addr: Mask: inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:2 errors:0 dropped:0 overruns:0 frame:0 TX packets:2 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:100 (100.0 B) TX bytes:100 (100.0 B) Link encap:ipv6-in-ipv4 NOARP MTU:1480 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:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Link encap:ethernet HWaddr 72:00:A5:80:2B:E8 BROADCAST MULTICAST MTU:1500 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:1000 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 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 /$ ifconfig usb /$ /$ /$ ping usb PING ( ): 56 data bytes 64 bytes from : seq=0 ttl=128 time=5.294 ms 64 bytes from : seq=1 ttl=128 time=6.101 ms NXP Semiconductors 119

120 Linux Kernel Drivers Watchdog Timers 64 bytes from : seq=2 ttl=128 time=4.170 ms 64 bytes from : seq=3 ttl=128 time=4.233 ms Known Bugs, Limitations, or Technical Issues Some issue with Pen drives from Kingston/Transcend. This have noticed some patches floating in open-source for these issues, and also found that open-source USB community trying to fix. Linux allow only one peripheral at one time. Please make sure When DWC3 set as Peripheral the other should not be set in same mode. Erratum:A (Frame length of USB3 controller for USB2.0 and USB3.0 operation is incorrect) impacts some socs like LS1020A/LS1021A because of which some USB2.0 and USB3.0 devices may not work properly, and hence, a sw workaround is needed. This sw workaround involves programing following registers of XHCI controller as: GFLADJ[5:0] = 20H and GFLADJ[7] = 1. This is already done via u-boot and linux codebase Watchdog Timers Watchdog Device Driver User Manual Description Watchdog driver description here. Module Loading Watchdog device driver support kernel built-in mode. U-Boot Configuration Runtime options Env Variable Env Description Sub option Option Description bootargs Kernel command line argument passed to kernel setenv othbootargs wdt_period=35 Sets the watchdog timer period timeout Kernel Configure Options Kernel Configure Tree View Options Kernel Configure Tree View Options Description PowerPC Book-E Watchdog Timer Device Drivers ---> [*] Watchdog Timer Support ---> [*] Disable watchdog shutdown on close [*] PowerPC Book-E Watchdog Timer 120 NXP Semiconductors

121 Linux Kernel Drivers Watchdog Timers Compile-time Configuration Options Option Values Default Value Description CONFIG_BOOKE_WDT y/n y PowerPC Book-E Watchdog Timer Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/char/watchdog/booke_wdt.c Description PowerPC Book-E Watchdog Timer User Space Application The following applications will be used during functional or performance testing. Please refer to the SDK UM document for the detailed build procedure. Command Name Description Package Name watch watchdog is a daemon for watchdog feeding watchdog Verification in Linux set nfs rootfs build a rootfs image which includes watchdog daemon. et booting parameter on the u-boot prompt, set following parameter set nfsargs "setenv bootargs wdt_period=35 root=/dev/nfs rw nfsroot=$serverip:$rootpath ip= $ipaddr:$serverip:$gatewayip:$netmask:$hostname:$netdev:off console=$consoledev,$baudrate $othbootargs" set nfsboot "run nfsargs;tftp $loadaddr $bootfile;tftp $fdtaddr $fdtfile;bootm $loadaddr - $fdtaddr" run nfsboot Note: wdt_period is watchdog timeout period, set it with proper value depending on your board bus frequency. NXP Semiconductors 121

122 Linux Kernel Drivers Watchdog Timers Also wdt_period is inversely proportional to watchdog expiry time ie. Higher the wdt_period, lower the watchdog expiry time. So if we increase wdt_period to high, watchdog will expiry early. check watchdog feeding operation after system boots up, check the screen output, if you see... PowerPC Book-E Watchdog Timer Enabled (wdt_period=35)... it means watchdog module loads successfully login in system, run command "watchdog /dev/watchdog" watchdog /dev/watchdog ps -ae grep watchdog 3285? 00:00:00 watchdog 122 NXP Semiconductors

123 Linux Kernel Drivers Watchdog Timers wait for some minutes, if system is still alive, watchdog feeding is OK check watchdog reboot operation run command "killall" killall -9 watchdog ps -ae grep watchdog PowerPC Book-E Watchdog Exception wait for some seconds, if system reboots, watchdog reboot operation is OK Known Bugs, Limitations, or Technical Issues On the T4240RDB board, if you will use watchdog, please disable the following menu configuration in kernel Location: --> Device Drivers --> Hardware Monitoring support (HWMON [=n]) Or they are conflicting with each other. NXP Semiconductors 123

124 Additional Linux Use Cases Power Management Chapter 7 Additional Linux Use Cases 7.1 Power Management Power Management User Manual Linux SDK for QorIQ Processors Description QorIQ Processors have features to minimize power consumption at several different levels. All processors support a sleep mode (LPM20). Some processors, such as T1040, LS1021, LS1046, also support a deep sleep mode (LPM35). The following power management features are supported on various QorIQ processors: Dynamic power management Shutting down unused IP blocks Cores support low power modes (such as PW15) Processors enter low power state (LPM20, LPM35) LPM20 mode: most part of processor clocks are shut down LPM35 mode: power is removed to cores, cache and IP blocks of the processor such as DIU, elbc, PEX, etsec, USB, SATA, esdhc etc. CPU hotplug: If cores are down at runtime, they will enter low power state. The wake-up event sources caused quitting from low power mode are listed as below: Wake on LAN (WoL) using magic packet Wake by MPIC timer or FlexTimer Wake by Internal and external interrupts For more information on a specific processor, refer to processor Reference Manual. Kernel Configure Tree View Options For ARM platforms Kernel Configure Tree View Options Description Enable sleep feature Power management options --> [*] Suspend to RAM and standby Device Drivers ---> SOC (System On Chip) specific Drivers ---> Enable the FTM alarm (FlexTimer module) driver Table continues on the next page NXP Semiconductors

125 Additional Linux Use Cases Power Management Table continued from the previous page... Kernel Configure Tree View Options Description [*] Layerscape Soc Drivers [*] FTM alarm driver Enable the CPU Idle driver CPU Power Management ---> CPU Idle ---> [*] CPU idle PM support [*] Ladder governor (for periodic timer tick) -*- Menu governor (for tickless system) ARM CPU Idle Drivers ---> [*] Generic ARM/ARM64 CPU idle Driver Table continues on the next page... Compile-time Configuration Options Linux Framework Hardware Feature Platform Kernel Config Suspend LPM20 LS1012, LS1021, LS1046 CONFIG_SUSPEND wake by Flextimer LS1012, LS1021, LS1046 CONFIG_FTM_ALARM CPU idle PW15 LS1012, LS1021, LS1046 CONFIG_ARM_CPUIDLE Device Tree Binding Property Type Description fsl,#rcpm-wakeup-cells unsigned int the number of cells in "rcpm-wakeup" except the pointer to "rcpm" rcpm-wakeup unsigned int require if the IP block can work as a wakeup source For processors integrated RCPM rcpm: rcpm@1ee2000 { compatible = "fsl,ls1046a-rcpm", "fsl,qoriq-rcpm-2.1"; reg = <0x0 0x1ee2000 0x0 0x1000>; fsl,#rcpm-wakeup-cells = <1>; }; ftm0: ftm0@29d0000 { compatible = "fsl,ftm-alarm"; reg = <0x0 0x29d0000 0x0 0x10000>; interrupts = <0 86 0x4>; big-endian; rcpm-wakeup = <&rcpm 0x0 0x >; NXP Semiconductors 125

126 Additional Linux Use Cases Power Management }; status = "okay"; Refer to the Linux document: Documentation/devicetree/bindings/soc/fsl/rcpm.txt Source Files The source files are maintained in the Linux kernel source tree. Source File drivers/soc/fsl/layerscape/rcpm.c drivers/soc/fsl/layerscape/ftm_alarm.c drivers/cpuidle/cpuidle-arm.c Description the RCPM driver needed by the sleep feature the FTM timer driver worked as a wakeup source the cpuidle driver for ARM core Verification in Linux Cpuidle Driver The cpuidle driver can switch CPU state according to the idle policy (governor). For more information, please see "Documentation/cpuidle/sysfs.txt" in kernel source code. /* Check the cpuidle driver which is currently used. */ # cat /sys/devices/system/cpu/cpuidle/current_driver /* Check the following directory to see the detailed statistic information of each state on each CPU. */ /sys/devices/system/cpu/cpu0/cpuidle/state0/ /sys/devices/system/cpu/cpu0/cpuidle/state1/ Supporting Documentation QorIQ processor reference manuals CPU Frequency Switching User Manual Linux SDK for QorIQ Processors Abbreviations and Acronyms DFS: Dynamic Frequency Scaling Description QorIQ Processors support DFS (Dynamic Frequency Switching) feature, also known as CPU Frequency Switch, which can change the frequency of cores dynamically. For more information on a specific processor, refer to processor Reference Manual. Kernel Configure Tree View Options CPU Power Management --> Description Enable the CPU frequency driver 126 NXP Semiconductors

127 Additional Linux Use Cases Power Management Kernel Configure Tree View Options Description CPU Frequency scaling --> [*] CPU Frequency scaling <*> CPU frequency translation statistics Default CPUFreq governor (userspace) --> -*- 'userspace' governor for userspace frequency scaling ARM CPU frequency scaling drivers --> <*> CPU frequency scaling driver for Freescale QorIQ SoCs Compile-time Configuration Options Linux Framework Hardware Feature Platform Kernel Config cpufreq DFS ALL CONFIG_CPU_FREQ, CONFIG_CPU_FREQ_DEFAULT_GOV_USERS PACE cpufreq DFS Layerscape CONFIG_QORIQ_CPUFREQ User Space Application Simply using command "cat" and "echo" can verify this feature. Device Tree Binding Property Type Status Description #clock-cells unsigned int Required The number of cells in a clock-specifier clocks handle Required Clock source handle compatible String Required Compatible strings reg unsigned int Required register address range Table continues on the next page... clockgen: clocking@1ee1000 { compatible = "fsl,ls1012a-clockgen"; reg = <0x0 0x1ee1000 0x0 0x1000>; #clock-cells = <2>; clocks = <&sysclk>; }; Source Files The driver source is maintained in the Linux kernel source tree. Source File Description NXP Semiconductors 127

128 Additional Linux Use Cases Power Management Table continued from the previous page... Source File drivers/cpufreq/qoriq_cpufreq.c Description CPU frequency scaling driver for qoriq chips Verification in Linux CPU frequency mode In order to test the CPU frequency scaling feature, we need to enable the CPU frequency feature on the menuconfig and choose the USERSPACE governor. You can learn more about CPU frequency scaling feature by referring to the kernel documents. They all are put under Documentation/cpu-freq/ directory. For example: all the information about governors is put in Documentation/cpu-freq/governors.txt. Test step: 1. list all the frequencies a core can support (take cpu 0 for example) : # cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies check the CPU's current frequency # cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq change the CPU's frequency we expect: # echo > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed You can check the CPU's current frequency again to confirm if the frequency transition is successful. Please note that if the frequency you want to change to doesn't support by current CPU, kernel will round up or down to one CPU supports System Monitor Power Monitor User Manual Description There are two methods currently we can use to measure the power consumption which are called online and offline power monitoring respectively. The difference between them is that offline power monitoring support measuring power consumption during sleep or deep sleep. The Power Monitor can be supported on P4080DS/P5020DS/P5040DS/T4240QDS board. This User guide uses the T4240QDS board as an example. Online Power Monitoring The Lm-sensors tool ( download from will be used to read the power/ temperature from on-boards sensors. The drivers vary from sensor to sensor. Basically they would be INA220, ZL6100 and ADT7461 etc. The device driver support either a built-in kernel or module loading. 128 NXP Semiconductors

129 Additional Linux Use Cases Power Management Kernel Configure Tree View Options Option Device Drivers ---> <*> Hardware Monitoring support ---> <*> Texas Instruments INA219 and compatibles Description Enables INA220 Device Drivers ---> [*] Enable compatibility bits for old user-space <*> I2C device interface [*] Autoselect pertinent helper modules I2C Hardware Bus support ---> <*> MPC107/824x/85xx/512x/52xx/83xx/86xx Enables I2C block device driver support Device Drivers ---> <*> I2C bus multiplexing support Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches Enables I2C bus multiplexing PCA9547 Compile-time Configuration Options Option Values Default Value Description CONFIG_I2C_MPC y/n y Enable I2C bus protocol SENSORS_INA2XX y/n y Enables INA220 CONFIG_I2C_MUX_PCA954x y/n y Enables I2C multiplexing PCA9547 Device Tree Binding Property Type Status Description compatible String Required "Philips,pca9547" for pca9547 reg integer Required reg = <0x77> compatible String Required "ti,ina220" for ina220 reg integer Required reg = <the i2c address of ina220> Default node: i2c@ { pca9547@77 { compatible = "philips,pca9547"; reg = <0x77>; #address-cells = <1>; #size-cells = <0>; channel@2 { #address-cells = <1>; #size-cells = <0>; reg = <0x2>; NXP Semiconductors 129

130 Additional Linux Use Cases Power Management { compatible = "ti,ina220"; reg = <0x40>; shunt-resistor = <1000>; }; ina220@41 { compatible = "ti,ina220"; reg = <0x41>; shunt-resistor = <1000>; }; ina220@44 { compatible = "ti,ina220"; reg = <0x44>; shunt-resistor = <1000>; }; ina220@45 { compatible = "ti,ina220"; reg = <0x45>; shunt-resistor = <1000>; }; ina220@46 { compatible = "ti,ina220"; reg = <0x46>; shunt-resistor = <1000>; }; }; }; ina220@47 { compatible = "ti,ina220"; reg = <0x47>; shunt-resistor = <1000>; }; Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/i2c/muxes/i2c-mux-pca954x.c drivers/hwmon/ina2xx.c Description PCA9547 driver ina220 driver Test Procedure Do the following to validate under the kernel 1. The bootup information is displayed:... i2c /dev entries driver mpc-i2c ffe i2c: timeout us mpc-i2c ffe i2c: timeout us mpc-i2c ffe i2c: timeout us mpc-i2c ffe i2c: timeout us 130 NXP Semiconductors

131 Additional Linux Use Cases Power Management i2c i2c-0: Added multiplexed i2c bus 6 i2c i2c-0: Added multiplexed i2c bus 7 i2c i2c-0: Added multiplexed i2c bus 8 i2c i2c-0: Added multiplexed i2c bus 9 i2c i2c-0: Added multiplexed i2c bus 10 i2c i2c-0: Added multiplexed i2c bus 11 i2c i2c-0: Added multiplexed i2c bus 12 i2c i2c-0: Added multiplexed i2c bus 13 pca954x : registered 8 multiplexed busses for I2C mux pca9547 ina2xx : power monitor ina220 (Rshunt = 1000 uohm) ina2xx : power monitor ina220 (Rshunt = 1000 uohm) ina2xx : power monitor ina220 (Rshunt = 1000 uohm) ina2xx : power monitor ina220 (Rshunt = 1000 uohm) ina2xx : power monitor ina220 (Rshunt = 1000 uohm) ina2xx : power monitor ina220 (Rshunt = 1000 uohm) # sensors ina220-i2c-8-40 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V power1: W curr1: A ina220-i2c-8-41 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V power1: mw curr1: A ina220-i2c-8-45 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V power1: mw curr1: A ina220-i2c-8-46 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V power1: mw curr1: A ina220-i2c-8-47 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V power1: mw curr1: A ina220-i2c-8-44 Adapter: i2c-0-mux (chan_id 2) in0: V in1: V NXP Semiconductors 131

132 Additional Linux Use Cases Power Management power1: curr1: 1.86 W A NOTE Please make sure to include the "sensors" command in your rootfs Offline Power Monitoring Inside the FPGA of some NXP QorIQ (PowerPC) reference boards is a microprocessor called the General Purpose Processor (GSMA). Running on the GSMA is the Data Collection Manager (DCM), which is used to periodically read and tally voltage, current, and temperature measurements from the on-board sensors. You can use this feature to measure power consumption while running tests, without having the host CPU perform those measurements. This method support measuring power consumption when kernel is in sleep or deep sleep status. It gets the average power value of period from the time DCM starts to the time it ends. Module Loading The device driver support either kernel built-in or module. Kernel Configure Tree View Options Kernel Configure Tree View Options Device Drivers ---> [*] Misc devices ---> <*> Freescale Data Collection Manager (DCM) driver Description Enables DCM driver Compile-time Configuration Options Option Values Default Value Description CONFIG_FSL_DCM y/n y Enable DCM module Device Tree Binding Property Type Status Description compatible String Required "fsl,t4240qds-fpga", "fsl,fpga-qixis" reg Integer Required reg = <3 0 0x300> Default node: ifc: localbus@ffe { board-control@3,0 { compatible = "fsl,t4240qds-fpga", "fsl,fpga-qixis"; reg = <3 0 0x300>; }; Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/misc/fsl_dcm.c Description DCM driver 132 NXP Semiconductors

133 Additional Linux Use Cases Power Management Test Procedure Do the following to validate under the Kernel: 1. The bootup information is displayed:... Freescale Data Collection Module is installed Start measuring measure power # echo 1 > /sys/devices/platform/fsl-dcm.0/control 3. Stop measuring power #echo 0 > /sys/devices/platform/fsl-dcm.0/control 4. Display the average power consumption #cat /sys/devices/platform/fsl-dcm.0/result Name Average ==================== ================ CPU voltage: 1068 (mv) CPU current: (ma) DDR voltage: 1348 (mv) DDR current: 740 (ma) CPU temperature: 38 (C) Thermal Monitor User Manual Description The Temperature Monitoring function is provided by the chip ADT7461. This driver exports the values of Temperature to SYSFS. The user space lm-sensors tools can get and display these values. Kernel Configure Tree View Options Kernel Configure Tree View Options Device Drivers ---> [*] Hardware Monitoring support ---> [*] National Semiconductor LM90 and compatibles Description Enable thermal monitor chip driver like ADT7461. Device Drivers ---> <*> I2C bus multiplexing support ---> Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches Enable I2C PCA954x multiplexer support NXP Semiconductors 133

134 Additional Linux Use Cases Power Management Compile-time Configuration Options Option Values Default Value Description CONFIG_HWMON y/m/n n Enable Hardware Monitor CONFIG_SENSORS_LM90 y/m/n n Enable ATD7461 driver CONFIG_I2C_MUX y/m/n n Enable I2C bus multiplexing support CONFIG_I2C_MUX_PCA954x y/m/n n Enable PCA954x driver Device Tree Binding adt7461@4c { compatible = "adi,adt7461"; reg = <0x4c>; }; pca9547@77 { compatible = "philips,pca9547"; reg = <0x77>; }; Source Files The driver source is maintained in the Linux kernel source tree. Source File drivers/hwmon/hwmon.c drivers/hwmon/lm90.c drivers/i2c/i2c-mux.c drivers/i2c/muxes/pca954x.c Description Linux hwmon subsystem support ADT7461 chip driver I2C bus multiplexing support PCA954x chip driver Verification in Linux There are two ways to get temperature results. 1. You can manually read the thermal interfaces in sysfs: ~$ ls /sys/class/hwmon/hwmon1/devices alarms temp1_crit temp1_min_alarm temp2_max_alarm driver temp1_crit_alarm temp2_crit temp2_min hwmon temp1_crit_hyst temp2_crit_alarm temp2_min_alarm modalias temp1_input temp2_crit_hyst temp2_offset name temp1_max temp2_fault uevent power temp1_max_alarm temp2_input update_interval subsystem temp1_min temp2_max ~$ cat /sys/class/hwmon/hwmon1/devices/temp1_input You can use lm_sensors tools as follows. ~ # sensors adt7461-i2c-1-4c 134 NXP Semiconductors

135 Additional Linux Use Cases Power Management Adapter: MPC adapter temp1: C (low = +0.0 C, high = C) (crit = C, hyst = C) temp2: C (low = +0.0 C, high = C) (crit = C, hyst = C) lm_sensors is integrated into Yocto file system by default. If there is no "sensors" command in your rootfs just add lmsensors-sensors package and build your own rootfs using Yocto: IMAGE_INSTALL += "lmsensors-sensors" Web-based System Monitor User Guide Monitors the health of a system using a web browser in real time. Description Web-based System Monitor is a tool for monitoring the health of your system using a web browser in real time. The following procedures will guide you to setup the system monitor. Kernel requirements The raw data of this monitor system is collected from hardware monitor chips. So before you setup this monitor system you should enable the hwmon subsystem and drivers of monitor chips in the kernel. Kernel configure details are listed below. Kernel Configure Tree View Options Device Drivers ---> [*] Hardware Monitoring support ---> [*] National Semiconductor LM90 and compatibles [*] Texas Instruments INA219 and compatibles Description Enable monitor chip drivers like ADT7461(ADT7481)/INA220, etc. Device Drivers ---> <*> I2C bus multiplexing support ---> Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches Enable I2C PCA954x multiplexer support Some monitor chips may not be included in the device tree. In this case you could add the device manually. Take adt7461 on T4240QDS as an example: the monitor is attached to I2C multiplexer PCA954x channel 3 in address 0x43. T4240QDS has 4 I2C controllers so the channel index of multiplexer start from 4 (represent the channel 0). ADT7461 is connected to channel 3 which indexed as 7. Use the flowing command to add the device to kernel: ~$ echo adt7461 0x4c > /sys/bus/i2c/devices/i2c-7/new_device Rootfs requirements You could use the fsl-image-full rootfs in which all packages needed are included. Or you can build your own rootfs using Yotco. Please follow the steps below. 1. Add following package group to your rootfs recipes like fsl-image-core.bb: IMAGE_INSTALL += "packagegroup-fsl-monitor" NXP Semiconductors 135

136 Additional Linux Use Cases Power Management 2. If you are using ramdisk boot please add following settings to local.conf to get enough space for monitor systems: IMAGE_ROOTFS_EXTRA_SPACE = "100000" NOTE This will add KB (100MB) more space to rootfs for monitor database. Each sensor needs about 10MB more space for logging raw data. Setting up system monitor The monitor system will be setup automatically. What you need to do is to make sure that the network on board is working. Then you can monitor the system via any web browser by visiting: This results page will refresh itself for every 10 seconds. If you need to re-setup the system you could enter /usr/rrd directory and run: $ make clean $ make NOTE The System Monitor only works when system time is right. So you should guarantee that. How to configure the system monitor The monitor results you see is based on the configuration file: "monitor.conf". It's automatically generated by scanning the hwmon subsystem. You could manually modify it too. Here is how: 1. Each line of this configuration file represents one monitor curve. It contains four fields formatted as follows: SENSDEV:MONITOR_TERM:DURATION:DESCRIPTION SENSDEV: The sensor data can be monitored from /sys/class/hwmon/ interfaces. Each sensor has a corresponding folder distinguished by hwmon# like hwmon0 or hwmon1. SENSDEV is the folder name. MONITOR_TERM: This is the item you want to read like temp1 or temp2 etc. DURATION: This is how long you want to see the results. You can set minute/hour/day here. DESCRIPTION: This DESCRIPTION will show up on the result picture helping you to understand the contents of the curve. 2. You could add/remove/resort the configuration file. After modifying it, you could enter the /usr/rrd directory and run: $ make config 3. Then the monitor results will be updated to what you configured. Run demo We also provide scripts to cycle the system through different PM low power states to form a out-of-box demo for PM features. Please enter /usr/pm_demo directory and simply run: $./pm_demo.sh The output of the script will state the current PM features. It helps you to understand the system monitor results better. NOTE The demo could be terminated by CTRL-C and will apply the default PM features back. 136 NXP Semiconductors

137 Additional Linux Use Cases Real Time Application Note 7.2 Real Time Application Note Application Note on Real Time Introduction Baseband use-cases like 3G/4G have strict timelines to accomplish some particular jobs. Real Time (RT) feature available in the operating system aims at creating an environment to meet these time critical processing requirements. There are various approaches available for providing RT feature. NXP uses Linux PREEMPT_RT patch (also known as RT patch) to meet these requirements. PREEMPT_RT patch can be pulled from kernel.org git repository For more information regarding PREEMPT_RT refer to kernel.org wiki page PREEMPT_RT Patch in SDK PREEMPT_RT patch is applied in the kernel available with this SDK. By default, RT feature is disabled in all the defconfigs of this SDK, except the one mentioned in later section. Please note that, once one enable RT feature, throughput-performance of the system might decrease (and this decrease is expected as per design of RT). Support Status Hardware: Software: Currently supported only for P4080DS, B4860qds, TWR-LS1021A, LS1012A, LS2080 Linux (with PREEMPT_RT patch), (SMP-Linux: non KVM) Compilation Option Default Kernel Defconfig Kernel Configure Option Tree view For enabling RT in defconfig using "make menuconfig" for kernel Kernel Configure Tree View Options Kernel options ---> Preemption Model (Fully Preemptible Kernel (RT)) ---> (X) Fully Preemptible Kernel (RT) Description These options enable RT in Linux. Identifier Below are the configure identifiers which are used in kernel source code and default configuration files. Option Values Default Value to enable RT Description CONFIG_SLAB y/n y Enable SLAB Support Table continues on the next page... NXP Semiconductors 137

138 Additional Linux Use Cases Real Time Application Note Table continued from the previous page... Option Values Default Value to enable RT Description CONFIG_HIGHMEM y/n n Disable highmem support CONFIG_PREEMPT_RT_FULL y/n y Enable Full RT support Device Tree Binding No RT specific changes required Verification in Linux To verify that PREEMPT_RT Patch is applied and RT is enabled in Linux configuration after Linux has booted, check Linux version on Linux prompt, one should see pattern PREEMPT RT in the version string. Eg: root@bsc913x:~# uname -a Linux bsc913x rt6+ #52 PREEMPT RT Wed May 22 12:26:51 IST 2013 ppc GNU/Linux Test Tool RT-tests suit contains various test applications like cyclictest, hackbench, etc to measure latencies and induce various test loads. It come as package in yocto (can be build in rootfs) or can be downloaded from kernel.org git repository. NOTE PREEMPT_RT feature provides RTT (Real Time throttling) feature. For details on RTT, refer to Documentation/scheduler/sched-rt-group.txt in Linux source code. RTT might get triggered in case of heavy traffic leading to high latency. It can be disabled by: [root@bsc913x]#echo -1 > /proc/sys/kernel/sched_rt_runtime_us Supporting Documentation Known Limitations On non-dpaa SoCs like LS1021, LS1021 with PREEMPT_RT enabled kernel, while running IPv4 forwarding benchmarking scenarios (including the IPSec forwarding benchmark) or pi-stress test-case, which are inherently CPU and traffic intensive, sometimes RCU stalls dumps were observed in dmesg. There is no negative impact on occurrence of this RCU stall dumps, the system continues to run as before. (For IPv4, IPSEC forwarding test-cases, refer to Benchmark Reproducibility Guides in SDK documentation). Note: TCP/UPD Termination testing does not cause this issue even though CPU utilization is 100%. Workaround: The above kind of use-case for a real-time device is unlikely. If the above kind of scenario is expected to occur in a device, the device should have some provisions to reduce the CPU load by throttling the low priority jobs.or limit the traffic. Or use TCP/UDP terminating type traffic 138 NXP Semiconductors

139 Linux User Space OpenSSL Offload User's Guide Chapter 8 Linux User Space 8.1 OpenSSL Offload User's Guide Overview The Secure Socket Layer (SSL) protocol is the most widely deployed application protocol to protect data during transmission by encrypting the data using popular cipher algorithms such as AES, DES and 3DES. Apart from encryption it also provides message authentication services using popular hash/digest algorithms such as SHA1 and MD5. SSL is widely used in application web servers (HTTP) and other applications such as SMTP POP3, IMAP, Proxy servers etc., where protection of data in transit is essential for data integrity There are various version of SSL protocol such as TLSv1, SSLv3 that are commonly used. Other newer versions are available, such as TLSv2, TLSv3 and DTLS (Datagram TLS). Of all the SSL protocol versions, TLSv1 and SSLv3 are in common use. This document introduces NXP SSL acceleration solution on QorIQ platforms using OpenSSL: 1. OpenSSL software architecture 2. Building OpenSSL with hardware offload support 3. Examples of OpenSSL Offloading OpenSSL Software architecture The SSL protocol is implemented as a library in OpenSSL - the most popular library distribution in Linux and BSD systems. The OpenSSL library has several sub-components such as: 1. SSL protocol library 2. Crypto library (Symmetric and Asymmetric cipher support, digest support etc.) 3. Certificate Management The following figure presents the general interconnect architecture for OpenSSL. Each relevant layer is represented with a clear separation between Linux User Space and Linux Kernel Space. NXP Semiconductors 139

140 Linux User Space OpenSSL Offload User's Guide Figure 2. OpenSSL interface with Linux kernel OpenSSL s ENGINE Interface OpenSSL Crypto library provides Symmetric and Asymmetric (PKI) cipher support that is used in a wide variety of applications such as OpenSSH, OpenVPN, PGP, IKE, XML-SEC etc. The OpenSSL Crypto library provides software support for: 1. Cipher algorithms 2. Digest algorithms 3. Random number generation 4. Public Key Infrastructure Apart from the software support, the OpenSSL can offload these functions to hardware accelerators via the ENGINE interface. The ENGINE interface provides callback hooks that integrate hardware accelerators with the crypto library. The callback hooks provide the glue logic to interface with the hardware accelerators. Generic offloading of cipher and digests algorithms through Linux kernel is possible with cryptodev engine NXP solution for OpenSSL hardware offloading The following layers can be observed in NXP's solution for OpenSSL hardware offloading: OpenSSL (user space) - implements the SSL protocol cryptodev-engine (user space) - implements the OpenSSL ENGINE interface; talks to cryptodev-linux (/dev/crypto) via ioctls, offloading cryptographic operations in kernel cryptodev-linux (kernel space) - Linux module that translates ioctl requests from cryptodev-engine into calls to Linux Crypto API 140 NXP Semiconductors

141 Linux User Space OpenSSL Offload User's Guide Linux Crypto API (kernel space) - Linux kernel crypto abstraction layer CAAM driver (kernel space) - Linux device driver for the CAAM (Cryptographic Acceleration and Assurance Module) crypto engine The following are offloaded in hardware in current SDK: protocols: TLS v1.0 cipher modes: one-shot (a single ioctl for both encryption and authentication): AES128-SHA, AES256-SHA two-shot (two ioctls - one for encryption, the other for authentication): all combinations of AES with SHA1, all combinations of DES and 3DES with SHA Building OpenSSL with hardware offloading support 1. Build the fsl-image-core rootfs for ls1012ardb (similar for other platforms); this will automatically deploy OpenSSL 1.0.2h with cryptodev-engine support: $ bitbake fsl-image-core 2. Boot the board and load the cryptodev kernel module: root@ls1012ardb:~# modprobe cryptodev cryptodev: driver 1.8 loaded. 3. Check that OpenSSL detected cryptodev: root@ls1012ardb:~# openssl engine (cryptodev) BSD cryptodev engine (dynamic) Dynamic engine loading support Nginx offloading with OpenSSL In this section, a client-server example will be presented. There are two options of testing and validating the OpenSSL TLS 1.0 Offloading: Web Server running on the NXP QorIQ Board - client (e.g. HTTPS browser) on third party equipment Web Server running on a third party equipment, client running on the NXP QorIQ board Test Scenario 1 is commonly used when a NXP Board is used as an HTTPS server responding to request from various SSL clients (e.g. web browsers). TLS record offload show performance improvement when the HTTPS is used to transfer large amount of data between server and client. The examples below use nginx web server and "openssl s_client" utility as client. Building a custom OpenSSL and a web server Manually building openssl and nginx is no longer required with NXP SDK full image. For other images (like core or minimal) you just customize the image recipe files to add nginx. Nginx is required only for test scenario 1 and the following line should be added in the bitbake image file (e.g. fsl-image-minimal.bb): IMAGE_INSTALL += "nginx" Unlike "openssl s_client", nginx will not use cryptodev by default. To enable cipher offloading through cryptodev, the engine must be enabled in nginx configuration file. Edit this file for the nginx server in board's filesystem: NXP Semiconductors 141

142 Linux User Space OpenSSL Offload User's Guide /etc/nginx/nginx.conf: ssl_engine cryptodev; worker_processes 4; worker_cpu_affinity ; #for 4 Core CPU; For 2 Core CPU worker_cpu_affinity 01 10;... # HTTPS server # server { listen 443; server_name localhost; ssl on; ssl_certificate server.crt; ssl_certificate_key server.key; ssl_session_timeout 5m; ssl_protocols TLSv1; ssl_ciphers AES128-SHA:AES256-SHA; ssl_prefer_server_ciphers on;... } location / { root /var/www/localhost/html; index index.html index.htm; } Worker processes and affinity should be set according to the number of CPU cores available on the platform. Insert cryptodev module and basic checks Cryptodev must be installed and loaded before testing record layer acceleration. This step is required before openssl or nginx are started. $ modprobe cryptodev cryptodev: driver 1.8 loaded. $ openssl version OpenSSL 1.0.2h (...) $ openssl engine (cryptodev) BSD cryptodev engine (dynamic) Dynamic engine loading support If cryptodev driver is not loaded, openssl will report only dynamic engine support and all operations will be done in userspace without HW acceleration. If crypto testing module (tcrypt) was built into the kernel, it can be used to check if TLS support is available. This step is optional however. Kernel algorithms (including TLS) are visible only after their first use. If tcrypt is missing, grep may not show anything: $ modprobe tcrypt $ grep tls /proc/crypto name : tls10(hmac(sha1),cbc(aes)) driver : tls10-hmac-sha1-cbc-aes-caam Offloading operations can be monitored with the interrupt counters for CAAM JR interfaces: root@ls1012ardb:~# cat /proc/interrupts grep -i jr 28: 2 GIC 103 Level jr 142 NXP Semiconductors

143 Linux User Space OpenSSL Offload User's Guide 29: GIC 104 Level jr 30: GIC 105 Level jr 31: 0 GIC 106 Level jr Testing TLS To verify TLS record offload, the minimum setup requires a testing board and a web server with support for TLS1.0, either nginx, apache, lighttpd. We will use the second test scenario and prepare a 100MB file on server side, and transfer it with an https client over the network. Figure 3. Test setup Openssl s_client command will be used on NXP board to make the connection with the server: $ openssl s_client The command can be scripted and run without further intervention: $ echo GET /index.html openssl s_client connect <server_ip>:443 cipher AES128-SHA tls1 quiet The option "-quiet" can be removed to see more details about the TLS session. OpenSSL will use automatically the HW acceleration if cryptodev module is loaded in the kernel. No further configuration is necessary. If cryptodev module is removed, openssl operations will fall back to software in user-space so this can be used effectively to check the hardware support Valid TLS Ciphersuites based on TLS protocol version In order to avoid compatibility issues cipher suite vs protocol version, the following list (extracted from OpenSSL) represent the compatibility list. Table 7. OpenSSL CipherSuite Compatibility CipherSuite SSL_RSA_WITH_NULL_MD5 SSL_RSA_WITH_NULL_SHA TLS Protocol Version SSL3.0 SSL3.0 Table continues on the next page... NXP Semiconductors 143

144 Linux User Space OpenSSL Offload User's Guide Table 7. OpenSSL CipherSuite Compatibility (continued) CipherSuite SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_RC4_128_SHA SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSL_RSA_WITH_IDEA_CBC_SHA SSL_RSA_EXPORT_WITH_DES40_CBC_SHA SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA SSL_DH_DSS_WITH_DES_CBC_SHA SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA SSL_DH_RSA_WITH_DES_CBC_SHA SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA SSL_DHE_DSS_WITH_DES_CBC_SHA SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA SSL_DHE_RSA_WITH_DES_CBC_SHA SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 SSL_DH_anon_WITH_RC4_128_MD5 SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA SSL_DH_anon_WITH_DES_CBC_SHA SSL_DH_anon_WITH_3DES_EDE_CBC_SHA SSL_FORTEZZA_KEA_WITH_NULL_SHA SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA SSL_FORTEZZA_KEA_WITH_RC4_128_SHA TLS_RSA_WITH_NULL_MD5 TLS_RSA_WITH_NULL_SHA TLS_RSA_EXPORT_WITH_RC4_40_MD5 TLS Protocol Version SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 SSL3.0 TLS1.0 TLS1.0 TLS1.0 Table continues on the next page NXP Semiconductors

145 Linux User Space OpenSSL Offload User's Guide Table 7. OpenSSL CipherSuite Compatibility (continued) CipherSuite TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_RC4_128_SHA TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 TLS_RSA_WITH_IDEA_CBC_SHA TLS_RSA_EXPORT_WITH_DES40_CBC_SHA TLS_RSA_WITH_DES_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA TLS_DH_DSS_WITH_DES_CBC_SHA TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA TLS_DH_RSA_WITH_DES_CBC_SHA TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA TLS_DHE_DSS_WITH_DES_CBC_SHA TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA TLS_DHE_RSA_WITH_DES_CBC_SHA TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 TLS_DH_anon_WITH_RC4_128_MD5 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA TLS_DH_anon_WITH_DES_CBC_SHA TLS_DH_anon_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_DH_DSS_WITH_AES_128_CBC_SHA TLS_DH_DSS_WITH_AES_256_CBC_SHA TLS_DH_RSA_WITH_AES_128_CBC_SHA TLS_DH_RSA_WITH_AES_256_CBC_SHA TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS Protocol Version TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 Table continues on the next page... NXP Semiconductors 145

146 Linux User Space OpenSSL Offload User's Guide Table 7. OpenSSL CipherSuite Compatibility (continued) CipherSuite TLS_DHE_DSS_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DH_anon_WITH_AES_128_CBC_SHA TLS_DH_anon_WITH_AES_256_CBC_SHA TLS_RSA_WITH_CAMELLIA_128_CBC_SHA TLS_RSA_WITH_CAMELLIA_256_CBC_SHA TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA TLS_RSA_WITH_SEED_CBC_SHA TLS_DH_DSS_WITH_SEED_CBC_SHA TLS_DH_RSA_WITH_SEED_CBC_SHA TLS_DHE_DSS_WITH_SEED_CBC_SHA TLS_DHE_RSA_WITH_SEED_CBC_SHA TLS_DH_anon_WITH_SEED_CBC_SHA TLS_ECDH_RSA_WITH_NULL_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_ECDSA_WITH_NULL_SHA TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS Protocol Version TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 Table continues on the next page NXP Semiconductors

147 Linux User Space OpenSSL Offload User's Guide Table 7. OpenSSL CipherSuite Compatibility (continued) CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_NULL_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_NULL_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDH_anon_WITH_NULL_SHA TLS_ECDH_anon_WITH_RC4_128_SHA TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA TLS_ECDH_anon_WITH_AES_128_CBC_SHA TLS_ECDH_anon_WITH_AES_256_CBC_SHA TLS_RSA_WITH_NULL_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_DH_RSA_WITH_AES_128_CBC_SHA256 TLS_DH_RSA_WITH_AES_256_CBC_SHA256 TLS_DH_RSA_WITH_AES_128_GCM_SHA256 TLS_DH_RSA_WITH_AES_256_GCM_SHA384 TLS_DH_DSS_WITH_AES_128_CBC_SHA256 TLS_DH_DSS_WITH_AES_256_CBC_SHA256 TLS_DH_DSS_WITH_AES_128_GCM_SHA256 TLS_DH_DSS_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS Protocol Version TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.0 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 Table continues on the next page... NXP Semiconductors 147

148 Linux User Space OpenSSL Offload User's Guide Table 7. OpenSSL CipherSuite Compatibility (continued) CipherSuite TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_DH_anon_WITH_AES_128_CBC_SHA256 TLS_DH_anon_WITH_AES_256_CBC_SHA256 TLS_DH_anon_WITH_AES_128_GCM_SHA256 TLS_DH_anon_WITH_AES_256_GCM_SHA384 TLS Protocol Version TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS1.2 TLS NXP Semiconductors

149 Boot Loaders Primary Protected Application (PPA) User's Guide Chapter 9 Boot Loaders 9.1 Primary Protected Application (PPA) User's Guide Introduction Rationale and Scope This document is the Specification and Users Guide for a loadable secure services firmware component running in TrustZone. This component, called the Primary Protected Application (PPA), has the following characteristics: Is loaded into the secure side of an ARM core early in the boot process Remains resident after boot Provides secure services for boot software and runtime software Contains a Secure Monitor, which controls access to/from the secure world Implements services behind a std abstract interface (published by ARM) Has the secure world exception vectors and handlers Is the focal point for implementing the Platform Security Policy Each of these will be discussed in detail in the sections that follow. Although secure boot and other boot components such as bootloaders and bootrom will be mentioned here, this specification is not intended to exhaustively cover secure boot, bootloaders (such as UEFI and U-boot), or bootrom code. The phrase secure world, used heavily in this doc, refers to ARM TrustZone, and vice-versa. The phrase secure monitor refers to the ARM v8 definition of a software entity that runs at EL3 and controls access to/from the secure world. Do not confuse secure monitor in this context with security monitor, which is a hardware component of the QorIq Trust Architecture. There are a number of compelling reasons for having a resident secure services layer: 1. The secure services layer is first-and-foremost a focal point for implementation of a Platform Security Policy. 2. ARM cores come out of reset executing in the secure world. 3. The non-secure world needs an agent to perform tasks in the secure world 4. The PSCI interface, which is ARM s abstract power mgmt interface, runs in the secure world. 5. A resident secure firmware can streamline bootloaders, making it easier to support multiple bootloaders. 6. The PPA is the foundation upon which a deeper TrustZone software stack can be built References [1] LS1043A SoC Architecture Specification v0.3.0 [2] SMC Calling Convention, ARM Ltd, 2013 [3] ARM Architecture Reference Manual, Armv8 Edition, beta [4] LS1043 PRL, Revision 0.7 [5] QorIQ Chassis Architecture Specification, Generation 2.1, Revision 0.8 [6] LS1 Trust Architecture, Chapter 10 NXP Semiconductors 149

150 Boot Loaders Primary Protected Application (PPA) User's Guide [7] Layerscape Chassis Architecture Specification, Generation 3, v0.9 [8] ARM Trusted Firmware Design [10] LS2 Boot Interfaces Programmers Guide, v1.5 [11] Power State Coordination Interface, ARM Ltd, Definitions AP Application Processor, same as GPP ATF ARM Trusted Firmware Bootloader FW that loads the OS kernel (uboot, uefi) ESBC External Secure Boot Code, image validation code in the bootloader GPP General Purpose Processor ISBC Internal Secure Boot Code, image validation code in the bootrom OCRAM On-Chip RAM PPA Primary Protected Application, the secure monitor and associated functions that comprise the base EL3 sw foundation Protected Higher-privilege sw, such as a hypervisor PSCI Power State Coordination Interface, an ARM std interface Secure SW or components that are isolated by the TrustZone architecture Secure Monitor the SW running at EL3 that controls the gateway from the non-secure world to the secure world Security Monitor a HW feature of the QorIQ Trust Architecture SCP SMC an ARM instruction which generates an exception, and an ARM std interface based on that excepton call SP Service Processor, an auxiliary core that performs initial boot functions on the SoC TPM Trusted Platform Module, a specification of the Trusted Computing Group Trusted Architecture (TA) a security architecture found in the QorIq family of SoCs, including the ARM-based QorIq products TrustZone (TZ) an isolation context provided as part of the ARM architecture; an infrastructure for building secure subsystems Boot Flow Architecture LS1043A/LS1012A Boot Flow Component Load Sequence 1. GPP Bootrom loads/validates* 1st stage bootloader 2. 1st stage bootloader loads/validates* 2nd stage bootloader 3. 1st stage bootloader loads/validates* PPA 4. 2nd stage bootloader loads/validates* kernel 150 NXP Semiconductors

151 Boot Loaders Primary Protected Application (PPA) User's Guide Secure World Non Secure World GPP Bootrom 1 1 st Stage Bootloader* 2 2 nd Stage Bootloader* 3 4 SMC Lib EL3 init Kernel secure monitor EL3 boot component TBD PSCI PPA EL2/EL1 boot component EL3 boot/runtime EL2/EL1 runtime Legend * images validated if secure boot enabled Figure 4. Component Load Sequence Boot execution Order 1. Execution begins in the PBI State Machine when the SoC comes out of reset 2. After PBI, execution starts with bootcore in GPP bootrom 3. Bootcore branches to 1st stage bootloader running in EL3 4. Bootcore in 1st stage bootloader branches to EL3 init code in PPA 5. When bootcore completes EL3 init, it branches to 2nd stage bootloader in EL2 6. Bootcore in 2nd stage bootloader branches to Linux kernel in EL1 7. Kernel calls PSCI (cpu_on) to release secondary cores (LS1043A only) NXP Semiconductors 151

152 Boot Loaders Primary Protected Application (PPA) User's Guide SoC reset 1 Secure World Non Secure World PBI State Machine 2 GPP Bootrom 3 1 st Stage Bootloader* 2 nd Stage Bootloader* EL3 boot component SMC Lib secure monitor EL3 init 7 Kernel EL2/EL1 boot component TBD PPA PSCI EL3 boot/runtime EL2/EL1 runtime Legend Figure 5. Boot Execution Order Secondary core execution path 1. Execution starts in the GPP bootrom when secondary core released from reset 2. If core is marked to be disabled, core enters power-down sequence in bootrom 3. Cores not disabled branch to EL3 init code in PPA 4. Upon completion of EL3 init, cores branch to start address at EL2 in kernel NOTE LS1012A does not have secondary cores 152 NXP Semiconductors

153 Boot Loaders Primary Protected Application (PPA) User's Guide core reset 1 Secure World Non Secure World GPP Bootrom 1 st Stage Bootloader* 2 nd Stage Bootloader* 2 3 power down SMC Lib secure monitor EL3 init 4 Kernel TBD PSCI EL3 boot component PPA EL2/EL1 boot component EL3 boot/runtime EL2/EL1 runtime Legend Figure 6. Secondary Core Execution Path Loading and Initializing the PPA The PPA must be loaded to a 64Kb boundary Copy the binary image to the load address the component installing the PPA MUST be executing at EL3 PPA should be loaded to an address in secure memory - recommend a 2MB secure region in DDR (but PPA can be tested in non-secure DDR) After copying the image file to DDR, clean the data cache by VA (all virtual address ranges affected by PPA load), and invalidate the instruction cache The PPA initialization runs at EL3 but the PPA transfers control back to the address loaded in BOOTLOCPTR at EL2 you must write the start address of the EL2 portion of your bootloader into BOOTLOCPTR before initializing the PPA After writing the EL2 start address in BOOTLOCPTR, initialize the PPA by branching to its start address How to Call SMC/PSCI functions SMC functions obey the ARM ABI SMC functions treat registers x0-x12 as volatile, all others are preserved To call an SMC/PSCI function, load the registers according to the table below, then execute an SMC 0x0 instruction If the function specifies a return value, it will be found in register x0 NXP Semiconductors 153

154 Boot Loaders Primary Protected Application (PPA) User's Guide Return values, including error returns, are returned in x0 The SMC 0x0 instruction generates an exception after the exception is processed in the secure monitor (when the SMC function has completed), control will return to the instruction following the SMC 0x0 Please refer to [2] for more details of the SMC calling convention Note: currently, only SMC fast calls are implemented (including PSCI). This means that while the calling core is in the secure world, interrupts to the core are masked. SMC input parameters: Register Meaning X0 Function ID (see Section 5, 6) X1 X2 X3 First optional parameter Second optional parameter Third optional parameter SMC return values: Register X0 Meaning Return value, Error return code PSCI Function List Please see [11] for details of the PSCI function interface. Keep in mind that the PSCI interface is a subset of the SMC Calling Convention [2] PSCI_VERSION Get the Version number of this PSCI implementation. Function ID: 0x8400_0000 Input parameters: Register X0 Meaning Function ID No other inputs Return values: Register X0 bits[31:16] X0 bits [15:0] Meaning Major Version Number Minor Version Number Currently, the PSCI v0.2 specification is implemented. Thus, the Major Version Number returned is 0x0, and the Minor Version Number returned is 0x NXP Semiconductors

155 Boot Loaders Primary Protected Application (PPA) User's Guide CPU_ON Release a secondary core from reset, or from the CPU_OFF state. Function ID: 0xC400_0000 Input Parameters: Register X0 Meaning Function ID X1 Target CPU, in MPIDR format (see [11]) X2 X3 Start address (Physical) Context ID Return Values: Register Return Code (see 5.8) X0 SUCCESS INVALID_PARAMETERS ALREADY_ON ON_PENDING INTERNAL_FAILURE NOTE When cores are delivered to the Start Address, they will be executing at EL CPU_OFF Power down the calling core. Function ID: 0x8400_0002 Input Parameters: Register X0 Meaning Function ID Return Values: Register Return Code (see 5.8) Function does not return if successful X0 DENIED Note that this function is called on the core that is to be powered down. There is no mechanism to power down one core from another core. By definition, a power-down state is a state without retention, so the caller must save whatever state is needed when the core resumes execution. The only way to restart a core after a call to CPU_OFF is with a call to CPU_ON. NXP Semiconductors 155

156 Boot Loaders Primary Protected Application (PPA) User's Guide If successful, this function does not return CPU_SUSPEND Put the calling core/cluster/system into a low-power state. Function ID: 0xC400_0001 Input Parameters (see [11]): Register X0 X1 X2 X3 Meaning Function ID Power_State Start_Address (Physical) Context_Id Return Values: Register Return Code (see 5.8) X0 SUCCESS INVALID_PARAMETERS Note that this function is called on the core/cluster/system that is to be suspended. There is no mechanism to suspend one core from another core. There are two available power states, Standby and Power-Down (see [11]). For cluster low-power states, all cores of the cluster except this final core must already be in the requested power state. The function checks to see if this is the last core standing of the cluster if it is the last core, the core is suspended along with the cluster. If this function is called when there is more than one active core in the cluster, the function will return with the INVALID_PARAMETERS value in x0. Likewise for system power-down, the function checks to see if this is the last active gpp core in the SoC. If it is the last active core, then the core is suspended along with the SoC. If it is not the last active core, then the function returns with the error value INVALID_PARAMETERS in x0. The input parameters to this function describe a complex interface. Please see [11] for details of how to use this function call. If successful, this function does not return AFFINITY_INFO Get information about a specific affinity level. Function ID: 0xC400_0004 Input Parameters (see [11]): Register X0 X1 X2 Meaning Function ID Target_Affinity Lowest_Affinity Return Values: 156 NXP Semiconductors

157 Boot Loaders Primary Protected Application (PPA) User's Guide Register Return Codes (see 5.8, 5.8.1) X0 ON_PENDING OFF ON INVALID_PARAMETERS NOT_PRESENT DISABLED SYSTEM_OFF Power down the entire system. Function ID: 0x8400_0008 Input Parameters: Register X0 Meaning Function ID Return Values: The function does not return SYSTEM_RESET Perform a hard reset on the entire system. Function ID: 0x8400_0009 Input Parameters: Register X0 Meaning Function ID Return Values: The function does not return PSCI Return Code Values Mnemonic Value SUCCESS 0 NOT_SUPPORTED -1 INVALID_PARAMETERS -2 DENIED -3 Table continues on the next page... NXP Semiconductors 157

158 Boot Loaders Primary Protected Application (PPA) User's Guide Table continued from the previous page... ALREADY_ON -4 ON_PENDING -5 INTERNAL_FAILURE -6 NOT_PRESENT -7 DISABLED -8 PSCI Return Codes Specific to Affinity_Info Mnemonic Value ON 0 OFF 1 ON_PENDING PSCI Functions Implemented, by SoC LS1012A CPU_ON CPU_OFF AFFINITY_INFO CPU_SUSPEND PSCI_VERSION SYSTEM_RESET SYSTEM_OFF N/A N/A WIP X SMC Function List Please see [2] for details of the SMC function interface Function Count - SMC64 Return the number of functions implemented by the smc64 interface, including this function and PSCI functions using this interface. Uses smc64 interface. Function ID: 0xC200_FF00 Input Parameters: Register X0 Meaning Function ID Return Values: 158 NXP Semiconductors

159 Boot Loaders Primary Protected Application (PPA) User's Guide Register X0 Value Smc64 function count Function Count - SMC32 Return the number of functions implemented by the smc32 interface, including this function and PSCI functions using this interface. Uses smc32 interface. Function ID: 0x8200_FF00 Input Parameters: Register X0 Meaning Function ID Return Values: Register X0 Value Smc32 function count Get UUID Return the 128-bit UUID uniquely identifying this SMC implementation. Uses the smc32 interface. Function ID: 0x8200_FF01 Input Parameters: Register X0 Meaning Function ID Return Values: Register X0 X1 X2 X3 Value Bytes [3:0] of UUID Bytes [7:4] of UUID Bytes [11:8] of UUID Bytes [15:12] of UUID Get Revision Return the major and minor revision numbers of the SIP portion of this SMC implementation. Uses smc32 interface. Function ID: 0x8200_FF03 NXP Semiconductors 159

160 Boot Loaders Primary Protected Application (PPA) User's Guide Input Parameters: Register X0 Meaning Function ID Return Values: Register X0 X1 Value Major revision number of sip-smc Minor revision number of sip-smc Building the PPA In the SDK, the PPA image will be built as part of the Yocto recipe System Considerations When Calling SMC & PSCI Functions There is always the possibility that malware will attempt to execute an SMC. The affects of this may be mitigated with three methods: 1. Insure that calling an smc/psci function can never corrupt the machine 2. Insure that calling an smc/psci function can never lower the security stance of the machine 3. Provide only one place in the system, a kernel driver, from which all smc calls are made Items (1) & (2) mean that even if malware successfully makes an smc call, the effects of that call will not open the system up to an attack. Take careful note of item (2) this means that any EL3 configuration that lowers the security of the system must be set in the PPA initialization phase, and not as a dynamic smc function. Item (3) allows the PPA to determine if an unauthorized access has been attempted. Since the smc call generates an exception, the register ELR_EL3 is loaded, by hw, with the return address of the caller. If there is only one place in the system where smc calls are made from, then the PPA can be configured to register the return address. Malware, attempting to make an smc call, will have a different return address. The secure monitor in the PPA can detect this different return address, and reject the request. In addition, the secure monitor can return to the authorized return address with a security violation error. To enable this capability in later revisions of the PPA, the kernel developer should implement a kernel driver where all smc calls are made from. 160 NXP Semiconductors

161 Boot Loaders Secure Boot: PBL Based Platforms Non-secure World Secure World EL1 secure access driver SMC illegal access attempt trapped by PPA malware SMC PPA exception return address EL3 security error returned to registered access point Figure 7. System Considerations When Calling SMC and PSCI Functions 9.2 Secure Boot: PBL Based Platforms Introduction This document is intended for end-users to demonstrate the image validation process. The image validation can be split into stages, where each stage performs a specific function and validates the subsequent stage before passing control to that stage. In the example, the ESBC is Freescale provided reference code referred to as ESBC uboot. Chain of Trust ESBC uboot performs minimal SoC configuration before validating the Next Executable using the same CSF header format as the ISBC used to validate ESBC Uboot. The CSF Header and signature are added to the Next Executable using the Freescale Code Signing Tool. Figure 8. Chain of Trust Chain of Trust with confidentiality The validated ESBC uboot image is allowed to use the One Time Programmable Master Key to decrypt system secrets. Cryptographic blob mechanism is used to establish Chain of trust with confidentiality. NXP Semiconductors 161

162 Boot Loaders Secure Boot: PBL Based Platforms Figure 9. Chain of Trust with confidentiality This document provides more details on the secure boot flow, ISBC, ESBC and Freescale Code signing tool Secure boot Process Secure boot process uses a digital signature validation routine already present in INTERNAL BOOT ROM. This routine performs validation using HW bound RSA public key to decrypt the signed hash and compare it to a freshly calculated hash over the same system image. If the comparison passes, the image can be considered as authentic. The complete process can be broken down into following phases: Pre Boot Phase 1. PBL 2. SFP ISBC ESBC The Complete Secure boot Process is shown in the Figure below. 162 NXP Semiconductors

163 Boot Loaders Secure Boot: PBL Based Platforms Figure 10. Secure Boot Process Pre-Boot Phase When the processor is powered on, reset control logic blocks all device activity (including scan and debug activity) until fuse values can be accurately sensed. The most important fuse value at this stage of operation is the Intent to Secure (ITS) bit. When an OEM sets ITS, they intend for the system to operate in a secure and trusted manner. The two main components involved during this process are : The security fuse processor (SFP) has two roles. The first is to physically burn fuses during device provisioning. The second is to use these provisioned values to enforce security policy in the pre-boot phase, and to securely pass provisioned keys and other secret values to other hardware blocks when the system is in a trusted/secure state. PreBoot Loader (PBL) is the micro-sequencer that can simplify system boot by configuring the DDR memory controllers to more optimal settings and copying code and data from low speed memory into DDR. This allows subsequent phases of boot to operate at higher speed. The setting of ITS determines where the PBL is allowed to read and write. The use of the PBL is mandatory when performing secure boot. At a minimum, the PBL must read a command file from a location determined by the Reset Configuration Word (RCW) and perform a store of a value to the ESBC Pointer Register within the SoC. If the PBL doesn t perform this operation (or sets the ESBC pointer to the wrong value), the ISBC will fail to validate the ESBC. Once the PBL has completed any operations defined by its command file, the PBL is disabled until the next Power on Reset and the Boot Phase begins. Some example PBI commands used in the demo are given below. The commands are embedded in the RCW's mentioned in the SDK Images required for the demo NXP Semiconductors 163

164 Boot Loaders Secure Boot: PBL Based Platforms NOR SECURE BOOT P3/P4/P5 #LAW for ESBC 09000cd (Flush command) 09000cd4 c (Flush command) 09000cd8 81f0001d (FLUSH command) # Scratch Register 090e0200 c0b00000 T1/T2/T4/B4 #LAW for ESBC 09000c c14 c c18 81f0001b # LAW for CPC/SRAM 09000d d04 bff d # Scratch Registers 090e0200 c0b e0208 c0c00000 # CPC SRAM bff00009 # CPC Configuration 09010f NAND SECURE BOOT P3/P5 # SCRATCH REGISTER 090e0200 bff (Flush Command) # CPC1 SRAM bff0000b 09010f (Flush Command) # LAW for CPC/SRAM 09000d d04 bff d (Flush Command) # Alternate Configuration Space Configuration bf (Flush Command) # CPC2 Cache NXP Semiconductors

165 Boot Loaders Secure Boot: PBL Based Platforms d c (Flush Command) /* hdr_uboot.out and u-boot.bin must also be loaded on NAND * ALT_CONFIG_WRITE command must be used for the same. * Starting offset for ALT_CONFIG_WRITE command would be * hdr_uboot.out - 0xf00000 * u-boot.bin - 0xf40000 */ The ISBC is capable of reading from NOR flash connected to the Local Bus, on-chip memory configured as SRAM, or main memory. Unless the ESBC is stored in NOR flash, the developer is required to create a PBL Image that copies the image to be validated from NVRAM to main memory or internal SRAM prior to writing the SCRATCHRW1 Register and executing the ISBC code. To assist with the creation of PBL Images (for both normal and Trust systems), Freescale offers a PBL Image Tool. Note that it is possible for an attacker to modify the board to direct the PBL to the wrong non-volatile memory interface, or change the PBL Image and CSF Header pointer, however this will result in a secure boot failure and the system remaining in an idle loop indefinitely ISBC Phase Flow in the ISBC Code With the PBL disabled and all external masters blocked by the PAMUs, CPU 0 is released from boot hold-off and begins executing instructions from a hardwired location within the Internal BootROM. The instructions inside the Internal BootROM are Freescale developed code known as the Internal Secure Boot Code (ISBC). The ISBC leads CPU 0 to perform the following actions: 1. Who am I check? - CPU 0 reads its Processor ID Register, and if it finds any value besides physical CPU 0, the CPU enters a loop. This insures that only CPU 0 executes the ISBC. 2. Sec_Mon check - CPU 0 confirms that the Sec_Mon is in the Check state. If not, it writes a fail bit in a Sec_Mon control register, leading to a state transition. 3. ESBC pointer read - CPU 0 reads the ESBC Pointer Register, and then reads the word at the indicated address, which is the first word of the Command Sequence File Header which precedes the ESBC itself. If the contents of the word don t match a hard coded preamble value, the ISBC takes this to mean it has not found a valid CSF and cannot proceed. This leads to a fail, as described in #2 above. 4. CSF parsing and public key check - If CPU 0 finds a valid CSF header, it parses the CSF header to locate the public key to be used to validate the code. There can be a single public key or a table of 4 public keys present in the header. The Secure Fuse Processor doesn t actually store a public key, it stores a SHA-256 hash of the public key/table of 4 keys. This is done to allow support for up to 4096b keys without an excessively large fuse block. If the hash of the public key fails to match the stored hash, secure boot fails. 5. Signature validation - With the validated public key, CPU 0 decrypts the digital signature stored with the CSF header. The ISBC then uses the ESBC lengths and pointer fields in the CSF header to calculate a hash over the code. The ISBC checks that the CSF header is included in the address range to be hashed. Option flags in the CSF header tell the ISBC whether the Freescale Unique ID and the OEM Unique ID (in the Secure Fuse Processor) are included in the hash calculation. Including these IDs allows the image to be bound to a single platform. If the decrypted hash and generated hash don t match, secure boot fails. 6. ESBC First Instruction Pointer check - One final check is performed by the ISBC. This check confirms that the First Instruction Pointer in the CSF header falls within the range of the addresses included in the previous hash. If the pointer NXP Semiconductors 165

166 Boot Loaders Secure Boot: PBL Based Platforms is valid, the ISBC writes a PASS bit in a Sec_Mon command register, the state machine transitions to Trusted, and the OTPMK is made available to the SEC. 7. In case of failure, for Trust v2.0 devices, secondary flag is checked in the CSF header. If set, ISBC reads the CSF header pointer form SCRATCHRW3 location and repeats from step 4. There are many reasons the ISBC could fail to validate the ESBC. Technicians with debug access can check the SCRATCHRW2 Register to obtain an error code. For a list of error codes refer ISBC Validation Error Codes Super Root keys (SRKs) and signing keys These are RSA public and private key pairs. Private keys are used to sign the images and public keys are used to validate the image during ISBC and ESBC phase. Public keys are embedded in the header and the hash of srk table is fused in SRKH register of SFP. These are Hardware Bound Keys, once the hash is fused the public private key pair can't be modified. Keys of sizes 1k, 2k and 4k are supported in FSL Secure Boot Process. It is the OEM s responsibility to tightly control access to the RSA private signature key. If this key is ever exposed, attackers will be able to generate alternate images that will pass secure boot. If this key is ever lost, the OEM will be unable to update the image Key Revocation Trust Architecture 2.0 introduces support for revoking the RSA public keys used by the ISBC to verify the ESBC. The RSA public keys used for this purpose are called super root keys. OEM can use either a single key or a list of upto 4 super root keys in the Trust Arch v2.0 devices. In the Freescale Code Signing Tool (CST), the OEM defines whether the device uses a single super root key, or offers a list of super root keys. If using a single super root key, a new flag bit in the CSF header will indicate Key, otherwise the flag will indicate Key List. Assuming key list, the OEM can populate a list of up to 4 super root keys for trust arch v2.0 onwards platforms. And calculates a SHA-256 hash over the list. This hash is written to the SRKH registers in the SFP. As part of code signing, the OEM defines which key in the key list is to be used for validating the image. This key number is included as a new field in the CSF header. During secure boot, the ISBC determines whether a key list is in use. If the key list is valid, the ISBC checks the key number indicated in the CSF header against the revocation fuses in the SFP s OEM Security Policy Register (SFP_OSPR). If the key is revoked, the image validation fails. NOTE In order to prevent unauthorized revocation of keys, SFP provides a bit (Write Disable). If the bit is set, the Key revocation bits cannot be written to. In regular operation, the ESBC (early Trusted S/W) needs to set the SFP Write Disable bit. When circumstances call for revoking a key, the OEM will use an ESBC image with Write Disable bit not set. So, the SFP will be in a state in which key revocation fuses can be set. Logically after revoking the required key(s), the OEM would then load a new signed ESBC image with code to set the "Write Disable" bit, with new CSF header indicating which of the remaining non-revoked key to use. So, only the possessor of a legitimate RSA private key can enable key revocation. One possible motivation for an OEM to revoke a super root key is the loss of the associated RSA private key to an attacker. If the attacker has gained access to a legitimate RSA private key, and the attacker can turn on power to the fuse programming circuitry, then the attacker could maliciously revoke keys. To prevent this from being used to permanently disable the system, one super root key does not have an associated revocation fuse. 166 NXP Semiconductors

167 Boot Loaders Secure Boot: PBL Based Platforms Alternate Image Support Trust 2.0 onwards will support a primary and alternate image, where failure to find a valid image at the Primary location will cause the ISBC to check a configured alternate location. To execute, the alternate image must be validated using a non-revoked public key as defined by its CSF Header. A valid alternate image has same rights and privileges as a valid primary image. This feature helps to reduce risk of corrupting single valid image during firmware update or as a result of Flash block wearout. To enable this feature, create PBI with pointers for both Primary and Alternate Images (HW PBL uses SCRATCHRW1 & SCRATCHRW3) ESBC with CSF Header ESBC is the generic name for the code that the ISBC validates. A few ESBC scenarios are described in later sections. The figure below provides an example of an ESBC with CSF (Command Sequence File) Header. The CSF Header includes lengths and offset which allow the ISBC to locate the operands used in ESBC image validation, as well as describe the size and location of the ESBC image itself. Note: CSF Header and ESBC Header may be used synonymously in this and other Freescale Trust Architecture documentation ESBC Phase Figure 11. ESBC with CSF Header Unlike the ISBC, which is in an internal ROM and therefore unchangeable, the ESBC is Freescale-supplied reference code, and can be changed by OEMs. The remainder of this section is the description of a reasonable secure boot chain of trust based on Freescale's reference software for secure boot. Depending on the requirement, ESBC can be a monolithic image - including uboot, device trees, boot firmware, drivers along with the OS and applications or can be mini-uboot. Freescale provided ESBC consists of standard u-boot which has been signed using a private key. U-boot reserves a small space for storing environment variables. This space is typically one sector above or below the u-boot and is stored on persistent storage devices like NOR flash if macro CONFIG_ENV_IS_IN_FLASH is used. In case of secure boot, macro NXP Semiconductors 167

168 Boot Loaders Secure Boot: PBL Based Platforms CONFIG_ENV_IS_NOWHERE is used and so, environment is compiled in uboot image and is called default environment. This default environment can't be stored on flash devices. User won't be able to edit this environment also as he can't reach to uboot prompt in case of secure boot. There is default boot command for secure boot in this default environment which executes on autoboot. ESBC validates a file called boot script and on successful validation execute the commands in the boot script. There are many reasons ESBC could fail to validate Client images or boot script. The error status message along with the code is printed on the u-boot console. For a list of error codes refer ESBC Validation Error Codes. Users are free to use Freescale ESBC as it is provided or to use it as reference to modify their own secure boot system. NOTE On Soc's with ARMv8 core (eg:- LS1043, LS1012), during ISBC phase in Internal Boot ROM, SMMU (which by default is in by-pass mode) is configured to allow only secure transactions from CAAM. The security policy w.r.t. SMMU in ESBC phase must be decided by the user/customer. So, currently in ESBC (U-Boot), SMMU is configured back to by-pass mode allowing all transactions (secure as well as non-secure) Boot script Bootscript is a U-Boot script image which contains u-boot commands. ESBC would validate this boot script before executing commands in it. NOTE 1. Boot script can have any commands which u-boot supports. No checking on the allowed commands in boot script. Since it is validated image, assumption is that commands in boot script would be correct. 2. If some basic scripting error done in boot script like unknown command, missing arguments, the required usage of that command and core is put in infinite loop. 3. After execution of commands in boot script, if control reaches back in u-boot, error message would be printed on u-boot console and core would be put in spin loop by command esbc_halt. 4. Scatter gather images not supported with validate command. 5. If ITS fuse is blown, any error in verification of the image would result in system reset. The error would be printed on console before system goes for a reset Where to place the boot script? Freescale's ESBC u-boot expects the boot script to be loaded in flash as specified in address map for different platforms under the topic 'Appendix <platform> Secure Boot Demo'. ESBC u-boot code assumes that the public/private key pair used to sign the boot script is same as that was used while signing the u-boot image. If user used different key pair to sign the image, hash of the N and E component of the key pair should be defined in macro: CONFIG_BOOTSCRIPT_KEY_HASH. Note - The hash defined should be hex value, 256 bits long. Both the above macros can be defined or changed in the configuration file secure_boot.h at the following location in u-boot code: u-boot/arch/powerpc//include/asm/fsl_secure_boot.h Two new commands called esbc_validate and esbc_halt have been added in Freescale ESBC u-boot Chain of Trust Boot script contains information about the next level of images, e.g. Linux, HV, etc. ESBC validates these images as per their public keys and then executes bootm command to pass-on the control to next image. 168 NXP Semiconductors

169 Boot Loaders Secure Boot: PBL Based Platforms Users are free to use Freescale ESBC as it is provided or to use it as reference to modify their own secure boot system. Figure below shows the Chain of trust established for Validation with this ESBC u-boot Sample Boot Script A sample boot script would look like: Figure 12. Secure boot flow (Chain of Trust)... esbc_validate <Img1 header addr> <pub_key hash> esbc_validate <Img2 header addr> <pub_key hash> esbc_validate <Img3 header addr> <pub_key hash>... bootm <img1 addr> <img2 addr> <img3 addr> esbc_validate command esbc_validate img_hdr [pub_key_hash] Input arguments: img_hdr - Location of CSF Header of the image to be validated NXP Semiconductors 169

170 Boot Loaders Secure Boot: PBL Based Platforms pub_key_hash - hash of the public key used to verify the image. This is optional parameter. If not provided, code makes the assumption that the key pair used to sign the image is same as that used with ISBC. So the hash of the key in the header is checked against the hash available in SRK fuse for verification. Description: The command would do the following: Perform CSF header validation on the address passed in the image header. During parsing of the header, image address in stored in an environment variable which is later used in source command in default secure boot command. Signature checks on the image esbc_halt command esbc_halt (no arguments) Description: The command would do the following: This command puts core in spin loop. After successful validation of images, bootm command in bootscript should execute and control should never reach back to uboot. If somehow, control reaches back to uboot (eg. bootm not present in bootscript), core should just spin Chain of Trust with Confidentiality To establish chain of trust with confidentiality, cryptgraphic blob mechanism can be used. In this chain of trust, validated image is allowed to use the One Time Programmable Master Key to decrypt system secrets. Two bootscripts are to be used. First encap bootscripts is used which creates a blob of the LINUX images and saves them. After this the system is booted after replacing the encap bootscript with decap bootscript which decapsulates the blobs and boot the LINUX with the images. Figures below show the Chain of trust with confidentiality (Encapsulation and Decapsulation). 170 NXP Semiconductors

171 Boot Loaders Secure Boot: PBL Based Platforms Figure 13. Chain of Trust with Confidentiality (Encapsulation) NXP Semiconductors 171

172 Boot Loaders Secure Boot: PBL Based Platforms Figure 14. Chain of Trust with Confidentiality (Decapsulation) Sample Encap Boot Script A sample encap boot script would look like:... blob enc <Img1 addr> <Img1 dest addr> <Img1 size> <key_modifier address> erase <encap Img1 addr> +<encap Imag1 size> cp.b <Img1 dest addr> <encap Img1 addr> <encap Imag1 size> blob enc <Img2 addr> <Img2 dest addr> <Img2 size> <key_modifier address> erase <encap Img2 addr> +<encap Imag2 size> cp.b <Img2 dest addr> <encap Img2 addr> <encap Imag2 size> blob enc <Img3 addr> <Img3 dest addr> <Img3 size> <key_modifier address> erase <encap Img3 addr> +<encap Imag3 size> cp.b <Img3 dest addr> <encap Img3 addr> <encap Img3 size> blob enc command blob enc <src location> <dst location> <length> <key_modifier address> Input arguments: src location - Address of the image to be encapsulated 172 NXP Semiconductors

173 Boot Loaders Secure Boot: PBL Based Platforms dst location - Address where the blob will be created length - Size of the image to be encapsulated key_modifier address - Address where a random number 16 bytes long(key modifier) is placed Description: The command would do the following: Create a cryptographic blob of the image placed at src location and place the blob at dst location Sample Decap Boot Script A sample decap boot script would look like:... blob dec <Img1 blob addr> <Img1 dest addr> <expected Img1 size> <key_modifier address> blob dec <Img2 blob addr> <Img2 dest addr> <expected Img2 size> <key_modifier address> blob dec <Img3 blob addr> <Img3 dest addr> <expected Img3 size> <key_modifier address>... bootm <Img1 dest addr> <Img2 dest addr> <Img3 dest addr> blob dec command blob dec <src location> <dst location> <length> <key_modifier address> Input arguments: src location - Address of the image blob to be decapsulated dst location - Address where the decapsulated image will be placed length - Expected Size of the image after decapsulation. key_modifier address - Address where key modifier (Same as that used for Encapsulation) is placed Description: The command would do the following: Decapsulate the blob placed at src location and place the decapsulated data of expected size at dst location Next Executable (Linux Phase) The bootloader (ESBC) finishes the platform initialization and passed control to the Linux image. The boot-chain can be further extended to be able to sign application which would be running on Linux prompt. Further RTIC can be integrated to verify memory regions using Security Engine (SEC) during run time CST Tool KEY GENERATION gen_keys This utility generates a RSA public and private key pair using OPENSSL APIs. The key pair consists of 3 parts: N, E and D. N Modulus E Encryption exponent D Decryption exponent Public Key - It is a combination of E and N components. Private Key - It is a combination of D and N components. NXP Semiconductors 173

174 Boot Loaders Secure Boot: PBL Based Platforms It is the OEM s responsibility to tightly control access to the RSA private signature key. If this key is ever exposed, attackers will be able to generate alternate images that will pass secure boot. If this key is ever lost, the OEM will be unable to update the image. Features The application allows the user to generate 3 sizes keys. The sizes allowed are bits, 2048 bits and 4096 bits. It generates RSA key pairs in PEM format. Keys are generated and stored in the files. User can provide filenames through command line option. Usage./gen_keys [OPTION] SIZE SIZE refers to size of public key in bits. (Modulus size). Sizes supported , 2048, The generated keys would be in PEM format. Options: -h,--help Usage of the command -k,--pubkey File where Public key would be stored in PEM format(default = srk.pub) -p,--privkey File where Private key would be stored in PEM format(default = srk.priv) Usage Example $./gen_keys 1024 # # # # # CST (Code Signing Tool) Version # # # # # =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) =============================================================== Generated SRK pair stored in : PUBLIC KEY srk.pub PRIVATE KEY srk.pri $./gen_keys k my.pub -p my.pri # # # # # CST (Code Signing Tool) Version # # # # # =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) =============================================================== 174 NXP Semiconductors

175 Boot Loaders Secure Boot: PBL Based Platforms Generated SRK pair stored in : PUBLIC KEY my.pub PRIVATE KEY my.pri gen_drv_drbg This utility in the Code Signing Tool inserts hamming code in a user defined 64b hexadecimal string, or generate a 64b hexadecimal random number and inserts the hamming code in it which can be used as Debug Response Value. NOTE For random number generation, Hash_DRBG library is used. The Hash_DRBG is an implementation of the NIST approved DRBG(Deterministic Random Bit Generator), specified in SP800-90A. The entropy source is the Linux /dev/random. Features: Generates random numbers, which can be used if user defined string is not provided, to generate Debug Response value. Calculates and embeds the hamming code in the hexadecimal string. Usage:./gen_drv_drbg <Hamming_algo> [string] Hamming_algo : Platforms A1 : T10xx, T20xx, T4xxx, P4080rev1, B4xxx A2 : LSx B : P10xx, P20xx, P30xx, P4080rev2, P4080rev3, P50xx, BSC913x, C29x string : 8 byte string In case string is not specified, the utility generates an 8 byte random number and embeds hamming code in it. Usage Example: $./gen_drv_drbg A2 # # # # # CST (Code Signing Tool) Version # # # # # Input string not provided Generating a random string * Hash_DRBG library invoked * Seed being taken from /dev/random Random Key Genearted is: f4bfc65e16284dbb DRV[63:0] after Hamming Code is: f4bfc65f16294daf NAME BITS VALUE NXP Semiconductors 175

176 Boot Loaders Secure Boot: PBL Based Platforms DRV f4bfc65f DRV daf $./gen_drv_drbg A2 1652afe595631dec # # # # # CST (Code Signing Tool) Version # # # # # DRV[63:0] after Hamming Code is: 1652afe495631cea NAME BITS VALUE DRV afe4 DRV cea gen_otpmk_drbg This utility in the Code Signing Tool inserts hamming code in a user defined 256b hexadecimal string, or generate a 256b hexadecimal random number and inserts the hamming code in it which can be used as OTPMK value. NOTE For random number generation, Hash_DRBG library is used. The Hash_DRBG is an implementation of the NIST approved DRBG(Deterministic Random Bit Generator), specified in SP800-90A. The entropy source is the Linux /dev/random. Features: Generates random numbers, which can be used if user defined string is not provided, to generate OTPMK value. Calculates and embeds the hamming code in the hexadecimal string. Usage:./gen_otpmk_drbg <bit_order> [string] <bit_order> : (1 or 2) OTPMK Bit Ordering Scheme in SFP 1 : BSC913x, P1010, P3, P4, P5, C29x 2 : T1, T2, T4, B4, LSx <string> : 32 byte string In case string is not specified, the utility generates a 32 bytes random number and embeds hamming code in it. Usage Example: $./gen_otpmk_drbg 2 # # # # # CST (Code Signing Tool) Version # # # # # Input string not provided Generating a random string * Hash_DRBG library invoked 176 NXP Semiconductors

177 Boot Loaders Secure Boot: PBL Based Platforms * Seed being taken from /dev/random OTPMK[255:0] is: 3feac02ce3583ad9077ab70f3a398cd71955f8bffa cb25bb6bffb3113 NAME BITS VALUE OTPMKR feac02c OTPMKR e3583ad9 OTPMKR ab70f OTPMKR a398cd7 OTPMKR f8bf OTPMKR fa OTPMKR cb25bb6 OTPMKR bffb3113 $./gen_otpmk_drbg a6f6e a8958c983774b848438fe # # # # # CST (Code Signing Tool) Version # # # # # OTPMK[255:0] is: ce3c a6b a5e3d a8958c983774b848438fe NAME BITS VALUE OTPMKR ce3c5638 OTPMKR OTPMKR a6b66617 OTPMKR a5e3d OTPMKR OTPMKR a8958 OTPMKR c983774b OTPMKR fe CSF Header Generation uni_sign tool can be used for the following functions : CSF header generation along with signature for both ISBC and ESBC phase CSF header generation without signature if private key is not provided Usage: If INPUT file does not have ESBC = 1, uni_sign invokes create_hdr_isbc else it will invoke create_hdr_esbc To view usage of tool: $./uni_sign --help # # # # # CST (Code Signing Tool) Version # # # # # NXP Semiconductors 177

178 Boot Loaders Secure Boot: PBL Based Platforms Correct Usage of Tool is:./create_hdr_isbc [options] <input_file> --verbose Display header Info after Creation --hash Print the SRK(Public key) hash. --img_hash Header is generated without Signature. Image Hash is stored in a separate file. --help Show the Help for Tool Usage. <input_file> Contains all information required by tool ************************************************************* * uni_sign is a wrapper script over the TOOL * Correct Usage (Description as specified above): * *./uni_sign [options] <input_file> * ************************************************************* Default Usage When uni_sign is executed without any option i.e. only providing the input file as the argument, it parses the required fields from the input file and creates the CSF header as described in 5.2 along with the Public Key/ SRK Hash, Digital Signature and SG Table to create a combined binary. Usage :: $./uni_sign <input_file> Example $./uni_sign input_uboot_secure =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) =============================================================== Key Hash : a a70bcbaa9d3aa1acb70f6369e1e81c d9a364e2a HEADER file hdr_uboot.out created Sample Input File and Output Sample input file to generate CSF Header is as follows # Specify the platform. [Mandatory] # Choose Platform /1040/2041/3041/4080/5020/5040/9131/9132/9164/4240/C290 PLATFORM=4240 # ESBC Flag. Specify ESBC=0 to sign u-boot and ESBC=1 to sign ESBC images.(default is 0) ESBC= # Entry Point/Image start address field in the header.[mandatory] # (default=address of first file specified in images) ENTRY_POINT=cffffffc NXP Semiconductors

179 Boot Loaders Secure Boot: PBL Based Platforms # Specify the file name of the keys seperated by comma. # The number of files and key select should lie between 1 and 4 for 1040 and C290. # For rest of the platforms only one key is required and key select should not be provided. # USAGE (for 4080/5020/5040/3041/2041/1010/913x): PRI_KEY = <key1.pri> # USAGE (for 1040/C290/9164/4240): PRI_KEY = <key1.pri>, <key2.pri>, <key3.pri>, <key4.pri> # PRI_KEY (Default private key :srk.pri) - [Optional] PRI_KEY=srk.pri # PUB_KEY (Default public key :srk.pub) - [Optional] PUB_KEY=srk.pub # Please provide KEY_SELECT(between 1 to 4) (Required for 1040/C290/9164/4240 only) - [Optional] KEY_SELECT= # Specify SG table address, only for (2041/3041/4080/5020/5040) with ESBC=0 - [Optional] SG_TABLE_ADDR= # Specify the target where image will be loaded. (Default is NOR_16B) - [Optional] # Only required for Non-PBL Devices (1010/1040/9131/9132i/C290) # Select from - NOR_8B/NOR_16B/NAND_8B_512/NAND_8B_2K/NAND_8B_4K/NAND_16B_512/NAND_16B_2K/ NAND_16B_4K/SD/MMC/SPI IMAGE_TARGET= # Specify IMAGE, Max 8 images are possible. DST_ADDR is required only for Non-PBL Platform. [Mandatory] # USAGE : IMAGE_NO = {IMAGE_NAME, SRC_ADDR, DST_ADDR} IMAGE_1={u-boot.bin,cff40000,ffffffff} IMAGE_2={,,} IMAGE_3={,,} IMAGE_4={,,} IMAGE_5={,,} IMAGE_6={,,} IMAGE_7={,,} IMAGE_8={,,} # Specify OEM AND FSL ID to be populated in header. [Optional] # e.g FSL_UID= FSL_UID= OEM_UID= # Specify the file names of csf header and sg table. (Default :hdr.out) [Optional] OUTPUT_HDR_FILENAME=hdr_uboot.out # Specify the file names of hash file and sign file. HASH_FILENAME=img_hash.out INPUT_SIGN_FILENAME=sign.out # Specify the signature size.it is mandatory when neither public key nor private key is specified. # Signature size would be [0x80 for 1k key, 0x100 for 2k key, and 0x200 for 4k key]. SIGN_SIZE= # Specify the output file name of sg table. (Default :sg_table.out). [Optional] # Please note that OUTPUT SG BIN is only required for 2041/3041/4080/5020/5040 when ESBC flag is not set. OUTPUT_SG_BIN= # Following fields are Required for 4240/9164/1040/C290 only # Specify House keeping Area # Required for 4240/9164/1040/C290 only when ESBC flag is not set. [Mandatory] NXP Semiconductors 179

180 Boot Loaders Secure Boot: PBL Based Platforms HK_AREA_POINTER=bff00000 HK_AREA_SIZE= # Following field Required for 4240/9164/1040/C290 only # Specify Secondary Image Flag. (0 or 1) - [Optional] # (Default is 0) SEC_IMAGE= Table 8. Description of fields. Field PLATFORM ESBC ENTRY_POINT PRI_KEY PUB_KEY KEY_SELECT IMAGE_1 - IMAGE_8 OEM_UID OEM_UID_1 FSL_UID FSL_UID_1 HK_AREA_POINTER HKAREA_SIZE OUTPUT_HDR_FILENAME Field Description To identify the platform/soc for which CF Header needs to be created. Don t set this flag when code signing is being performed on the image directly verified by the ISBC. For later images in the chain of trust, set this flag. Entry Point address / Image start address field in the header. Private key filename to be used for signing the image. (File has to be in PEM format) (default = srk.pri generated by gen_keys command) FILE1 [,FILE2, FILE3, FILE4]. Multiple key support for Trust Arch v2.x devices only. Public key filename in PEM format. (default = srk.pub generated by gen_keys) FILE1 [,FILE2, FILE3, FILE4]. Multiple key support for Trust Arch v2.x devices only. Specify the key to be used in signature generation when more than one key has been given as input. (Default=1, first key will be selected) Create Entries for SG Table in the format { IMAGE_NAME, SRC_ADDR, DST_ADDR } OEM UID to be populated in the header. OEM UID 1 to be populated in the header. Required Only for ls1 FSL UID to be populated in header. FSL UID 1 to be populated in header.required Only for ls1 House Keeping Area Starting Pointer Required by Sec (Required for Trust Arch v2.x devices only when esbc option is not provided) House Keeping Area Size (Required for Trust Arch v2.x devices only when esbc option is not provided) Name of the combined header binary to be created by tool Table continues on the next page NXP Semiconductors

181 Boot Loaders Secure Boot: PBL Based Platforms Table 8. Description of fields. (continued) Field SG_TABLE_ADDR OUTPUT_SG_BIN IMAGE_TARGET SEC_IMG MP_FLAG VERBOSE Field Description Specify SG_TABLE Address where Scatter Gather table is present for 2041/3041/4080/5020/5040 when ESBC=0. Specify the output file name of sg table. Specify the target where image will be loaded. Ex:NOR_8B/NOR_16B/NAND_8B_512/NAND_8B_2K/ NAND_8B_4K/ NAND_16B_512/NAND_16B_2K/ NAND_16B_4K/SD/MMC/SPI Flag for Secondary Image. Required for Trust Arch v2.x devices only Specify Manufacturing Protection Flag. Available for LS1 only. Specify Verbose option. Contents of header generated will be printed Verbose Mode (--verbose) Verbose mode can be used to display extra information while creating the header. If selected, along with header creation, the tool will also display information about Output header and SG_TABLE entries.. Usage :: $./uni_sign --verbose <input_file> Example $./uni_sign --verbose input_uboot_secure =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young =============================================================== Key Hash : a a70bcbaa9d3aa1acb70f6369e1e81c d9a364e2a Image Hash :6c0048c92079b5e a16d2463b808b5fd6ae23e7c42dcd30f49efafa8e ********** HEADER ************** barker:0x srk_table_offset 200 srk_table_flag(8) : 1 srk_sel(8) : 1 num_srk_entries(16) : 3 psign 1410, length 128 uid_flag 0 sfp_wp(8) : 0 sec_image_flag(8) : 0 uid_flag(16) : 0 psgtable 1400 num_entries 1 img start cffffffc FSL UID 0 OEM UID 0 NXP Semiconductors 181

182 Boot Loaders Secure Boot: PBL Based Platforms sg_flag 1 hkptr bff00000 hksize ********** SG TABLE ************ no of entries 1 entry 0 len ptr cff40000 SIGFNATURE file sign.out created HEADER file hdr_uboot.out created Public Key/ SRK Hash Generation Only (--hash) The Hash of the Public Key or SRK Table as selected by user in the input file while signing the images needs to be fused in the SFP block. So if user wants to get the value of SRK Hash, this option can be used. Usage :: $./uni_sign --hash <input_file> Example $./uni_sign --hash input_uboot_secure =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) =============================================================== Key Hash : 478c14568d8f76e822a2d483489a5ed9752c7c453b1fe5351f085a57fae2a30f ISBC Key Extension (IE) Introduction The ISBC Key Extension feature allows the user to extend the ISBC and the number of keys available for signature validation. The ISBC uses a key directly bound to the silicon via the SRKH, the ISBC extension code (added to downstream images in a chain of trust) use IE_Keys, which are validated by the ISBC How it works If IE feature is enabled in input file, the CST signs the image along with a number of public keys. Logically, it will be used when signing Boot 1 (bootloader), so that the bootloader and downstream images in the chain of trust can use keys which aren't directly bound to the silicon via the SRKH. Decoupling the chain of trust from the hardware super root keys minimizes the need to perform hardware key revocation. 182 NXP Semiconductors

183 Boot Loaders Secure Boot: PBL Based Platforms Figure 15. Execution and Verification of Images using Key_Ext feature. NOTE Next stage images are signed with corresponding pair of Extension private keys list, not HW private keys. Key Extension feature is applicable only for NOR secure Boot. It is not applicable for RAMBOOT (where data has to be copied onto RAM, eg:- NAND, SD, SPI) IE Key Structure Table 9. IE Key Structure which is embedded in header and placed in memory. Offset Data Bits [0:31] 0x00-0x03 0x04-0x07 0x08-0x0b 0x0c-0x40b 0x40c-0x40f 0x410-0x80f This 32 bit word can be used to represent which keys from the table below have been revoked and are no longer available for use. Each bit represents 1 Key, Bit 0 represents Key 1 in the table.bit 31 is the 32nd key in the table Total number of keys (Max N = 32 as 32 bit key revocation field is provided) Key 1 length. Key 1 value. Key 2 length. Key 2 value. Table continues on the next page... NXP Semiconductors 183

184 Boot Loaders Secure Boot: PBL Based Platforms Table 9. IE Key Structure which is embedded in header and placed in memory. (continued) Offset Data Bits [0:31] Key N value Sample Input File and Output This file is same as file described above in <link to 4.1.2> except fields required for IE Key extension highlighted in red # Specify the platform. [Mandatory] # Choose Platform /2080/2041/3041/4080/5020/5040/4860/4240/LS1 PLATFORM=1040 # ESBC Flag. Specify ESBC=0 to sign u-boot and ESBC=1 to sign ESBC images.(default is 0) ESBC=0 # ESBC Header address. It contains address where ESBC header is loaded in memory. ESBC_HDRADDR=c0b # Entry Point/Image start address field in the header.[mandatory] # (default=address of first file specified in images) ENTRY_POINT=cffffffc # Specify the file name of the keys seperated by comma. # The number of files and key select should lie between 1 and 4 for 1040/2080 and C290. # For rest of the platforms only one key is required and key select should not be provided. # USAGE (for 4080/5020/5040/3041/2041/1010/913x): PRI_KEY = <key1.pri> # USAGE (for 1040/2080/C290/4860/4240): PRI_KEY = <key1.pri>,<key2.pri>,<key3.pri>,<key4.pri> # PRI_KEY (Default private key :srk.pri) - [Optional] PRI_KEY=srk.pri # PUB_KEY (Default public key :srk.pub) - [Optional] PUB_KEY=srk.pub # Please provide KEY_SELECT(between 1 to 4) (Required for 1040/2080/C290/4860/4240 only) - [Optional] KEY_SELECT= # Specify the file name of the extension keys seperated by comma. # USAGE : IE_KEY = <key1.pub>,<key2.pub>,<key3.pub>,<key4.pub>,<key5.pub> IE_KEY=<iekey1k_1.pub>,<iekey1k_2.pub>,<iekey1k_3.pub>,<iekey2k_1.pub>,<iekey2k_2.pub>,<iekey2k_3. pub>,<iekey4k_1.pub>,<iekey4k_2.pub> # Please provide Revoke keys. - [Optional] # Provide key numbers from available ie keys to be revoked. Max n-1 keys can be revoked. n is total number of IE keys. # LSb represents key0 and MSb represents key 31. So total 32 keys are supported. IE_REVOC=1, # Specify SG table address, only for (2041/3041/4080/5020/5040) with ESBC=0 - [Optional] SG_TABLE_ADDR= # Specify the target where image will be loaded. (Default is NOR_16B) - [Optional] # Only required for Non-PBL Devices (1010/9131/9132/C290) # Select from - NOR_8B/NOR_16B/NAND_8B_512/NAND_8B_2K/NAND_8B_4K/NAND_16B_512/NAND_16B_2K/ NAND_16B_4K/SD/MMC/SPI 184 NXP Semiconductors

185 Boot Loaders Secure Boot: PBL Based Platforms IMAGE_TARGET= # Specify IMAGE, Max 8 images are possible. DST_ADDR is required only for Non-PBL Platform. [Mandatory] # In case using IE_KEY, Max 7 images are possible. [Mandatory] # USAGE : IMAGE_NO = {IMAGE_NAME, SRC_ADDR, DST_ADDR} IMAGE_1={u-boot.bin,cff40000,ffffffff} IMAGE_2={,,} IMAGE_3={,,} IMAGE_4={,,} IMAGE_5={,,} IMAGE_6={,,} IMAGE_7={,,} # Specify OEM AND FSL ID to be populated in header. [Optional] # e.g FSL_UID= FSL_UID= OEM_UID= # Specify the file names of csf header and sg table. (Default :hdr.out) [Optional] OUTPUT_HDR_FILENAME=hdr_uboot.out # Specify the file names of hash file and sign file. HASH_FILENAME=img_hash.out INPUT_SIGN_FILENAME=sign.out # Specify the signature size.it is mandatory when neither public key nor private key is specified. # Signature size would be [0x80 for 1k key, 0x100 for 2k key, and 0x200 for 4k key]. SIGN_SIZE= # Specify the output file name of sg table. (Default :sg_table.out). [Optional] # Please note that OUTPUT SG BIN is only required for 2041/3041/4080/5020/5040 when ESBC flag is not set. OUTPUT_SG_BIN= # Following fields are Required for 4240/4860/1040/2080/C290 only # Specify House keeping Area # Required for 4240/4860/1040/2080/C290 only when ESBC flag is not set. [Mandatory] HK_AREA_POINTER=bff00000 HK_AREA_SIZE= # Following field Required for 4240/4860/1040/2080/C290 only # Specify Secondary Image Flag. (0 or 1) - [Optional] # (Default is 0) SEC_IMAGE= Table 10. Description of new fields introduced. Field ESBC_HDRADDR Field Description ESBC Header address. It contains location of ESBC header in the memory Table continues on the next page... NXP Semiconductors 185

186 Boot Loaders Secure Boot: PBL Based Platforms Table 10. Description of new fields introduced. (continued) Field IE_KEY IE_REVOC Field Description Extension Public key filenames to be used by further level images. (File has to be in PEM format) FILE1 [,FILE2, FILE3, FILE4]. Revoked keys numbers from available ie keys. If a key is compromised then this feature helps to avoid that key usage. Max n-1 keys can be revoked. n is total number of IE keys and less than equal to 32.Ex.[1,3,5] OUTPUT Highlighted fields shows IE structure is embedded in the CSF header Generate Header for Next Level Images (bootscript, rootfs, dtb, linux). IE key table generated in previous is embedded along with the CSF header for u-boot. Boot ROM code verifies these keys along with the bootloader. For the rest of the images in the chain of trust, user can use the keys in the IE key table. The IE 186 NXP Semiconductors

187 Boot Loaders Secure Boot: PBL Based Platforms Key Table is in the memory already, the sample input file needs to have the IE Key number to be used.(ie_key_sel). The corresponding private key of the file needs to be provided for signature to be generated (PRI_KEY). This sample file is same as file described above in <link to 4.1.2> except fields required for IE Key extension highlighted in red. CSF Header for bootscript # Specify the platform. [Mandatory] # Choose Platform /2080/2041/3041/4080/5020/5040/4860/4240/LS1 PLATFORM=1040 # ESBC Flag. Specify ESBC=0 to sign u-boot and ESBC=1 to sign ESBC images.(default is 0) ESBC= # Entry Point/Image start address field in the header.[mandatory] # (default=address of first file specified in images) ENTRY_POINT=e8a # Specify the file name of the keys seperated by comma. # The number of files and key select should lie between 1 and 4 for 1040/2080 and C290. # For rest of the platforms only one key is required and key select should not be provided. # USAGE (for 4080/5020/5040/3041/2041/1010/913x): PRI_KEY = <key1.pri> # USAGE (for 1040/2080/C290/4860/4240): PRI_KEY = <key1.pri>, <key2.pri>, <key3.pri>, <key4.pri> # PRI_KEY (Default private key :srk.pri) - [Optional] PRI_KEY=iekey4k_2.pri # PUB_KEY (Default public key :srk.pub) - [Optional] PUB_KEY= # Please provide KEY_SELECT(between 1 to 4) (Required for 1040/2080/C290/9164/4240 only) - [Optional] KEY_SELECT= # Specify SG table address, only for (2041/3041/4080/5020/5040) with ESBC=0 - [Optional] SG_TABLE_ADDR= # Specify IE_KEY to be used for signature verification. [Mandatory] IE_KEY_SEL= # Specify the target where image will be loaded. (Default is NOR_16B) - [Optional] # Only required for Non-PBL Devices (1010/9131/9132/C290) # Select from - NOR_8B/NOR_16B/NAND_8B_512/NAND_8B_2K/NAND_8B_4K/NAND_16B_512/NAND_16B_2K/ NAND_16B_4K/SD/MMC/SPI IMAGE_TARGET= # Specify IMAGE, Max 8 images are possible. DST_ADDR is required only for Non-PBL Platform. [Mandatory] # In case using IE_KEY, Max 1 image is possible. [Mandatory] # USAGE : IMAGE_NO = {IMAGE_NAME, SRC_ADDR, DST_ADDR} IMAGE_1={bootscript,e8a00000,ffffffff} IMAGE_2={,,} IMAGE_3={,,} IMAGE_4={,,} IMAGE_5={,,} IMAGE_6={,,} IMAGE_7={,,} IMAGE_8={,,} NXP Semiconductors 187

188 Boot Loaders Secure Boot: PBL Based Platforms # Specify OEM AND FSL ID to be populated in header. [Optional] # e.g FSL_UID= FSL_UID= OEM_UID= # Specify the file names of csf header. (Default :hdr.out) [Optional] OUTPUT_HDR_FILENAME=hdr_bs.out # Specify the file names of hash file and sign file. HASH_FILENAME=img_hash.out INPUT_SIGN_FILENAME=sign.out # Specify the signature size.it is mandatory when neither public key nor private key is specified. # Signature size would be [0x80 for 1k key, 0x100 for 2k key, and 0x200 for 4k key]. SIGN_SIZE=0x # Specify the output file name of sg table. (Default :sg_table.out). [Optional] # Please note that OUTPUT SG BIN is only required for 2041/3041/4080/5020/5040 when ESBC flag is not set. OUTPUT_SG_BIN= # Following fields are Required for 4240/9164/1040/2080/C290 only # Specify House keeping Area # Required for /1040/2080/C290 only when ESBC flag is not set. [Mandatory] HK_AREA_POINTER= HK_AREA_SIZE= # Following field Required for 4240/9164/1040/2080/C290 only # Specify Secondary Image Flag. (0 or 1) - [Optional] # (Default is 0) SEC_IMAGE= Table 11. Description of new fields introduced. Field IE_KEY_SEL Field Description IE_KEY number for public key in IE Key table to be used for signature verification of ESBC image. OUTPUT Given below is a snapshot of header generated in which highlighted fields indicates IE flag is ON and IE KEY SELECT i.e. key to be used to verify image is embedded in header. Highlighted fields shows IE key select in CSF header. 188 NXP Semiconductors

189 Boot Loaders Secure Boot: PBL Based Platforms Image Hash Generation (--img_hash) Introduction The -img_hash generation feature provides OEMs with the ability to perform code signing in a secure environment which does not run the FSL Code Signing Tool. When used in conjunction with the IE Key List feature, the user generates the IE key list and the list of hardware public keys (those bound to the silicon with the SRKH), and passes them to the CST for inclusion in the ESBC image hash calculation. The CST generates the appropriate CSF header, S/G table, and key lists, then calculates and exports the SHA256 hash. The OEM then RSA encrypts the hash with one of the private keys associated with the public key provided to verify the signature. The signature, which must be in PKCS#1v1.5 format, is then appended to the ESBC. See section 4.7 for more information on appending Features Generates hash file in binary format which contains SHA256 hash of CSF header along with keys(srk table, IE keys), SG table and its entries. Generates output header binary file based on the fields specified in input file. Output header binary file doesn t contain signature. Provides flexibility to manually append signature at the end of output header file. User s can use their own custom tool to generate the signature. The signature offset chosen in the header is such that the signature can be appended at the end of the header file. This option does not require private key to be provided. But the corresponding Public key from the public/private key pair must be provided to calculate correct SHA256 hash. NXP Semiconductors 189

190 Boot Loaders Secure Boot: PBL Based Platforms Usage Example:./uni_sign --img_hash input_uboot_nor_secure =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young =============================================================== Key Hash : f1f18e7eaeb28cee50a30f5ba5d270b3e71b2c7c ca8e7e4c110547eb2 HASH file hash.out created HEADER file esbc_hdr.out created Help (--help) It prints help menu describing various options available Code Signing Tool Walkthrough Step-1) Yocto installs the cst package at the following location: tmp/sysroots/x86_64-linux/usr/bin/cst OR In the Yocto environment, the user can use below commands to rebuild cst: 1. bitbake cst-native c cleanall 2. bitbake cst-native Step-2) cd tmp/sysroots/x86_64-linux/usr/bin/cst gen_keys and uni_sign binaries are available in cst. Note : LD_LIBRARY_PATH should be set to the library path in yocto workspace. <project_folder_path>/tmp/sysroots/x86_64- linux/usr/lib Step-3) Generate private key public key pair -./gen_keys 1024 NOTE Here, 1024 refers to the size of public key Modulus in bits. Other allowed sizes are bits, 4096 bits. See help - bash-2.05a$./gen_keys -h Step-4) Put all the images (limited by number 8) you want to sign using OPENSSL RSA APIs in current directory. 190 NXP Semiconductors

191 Boot Loaders Secure Boot: PBL Based Platforms Step-5) Execute the binary uni_cfsign to generate signature over CSF header and ESBC images. CSF Header Generation Example taken for B4860: $./uni_sign input_files/uni_sign/b4860/input_uboot_nor_secure =============================================================== This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young =============================================================== Key Hash : a9bb28a23c641e13b58c19a7fc48dfd8660a29895ebbc8bd0beba432e04c0785 HEADER file hdr_uboot.out created The header would look like this: h9' f * cc fe 4d fc 20 c1 6d ba c2 4d c4 5b 45..M..m.wBQ.M.[E e2 88 a9 55 d0 49 7b 86 fe 5a b7 db A...U.I{..Z..h ef b7 2d 2a 1f 5b 74 4d 9c 7a c7 54 a9 b0 ff...-*.[tm.z.t cf a6 1c ed 3d f3 de 8d cc 91 ae 5f 60 b4 88 ab...=..._` a5 70 0b b 1b e7 2f fd a6.p. s0u8[.q"./ a 78 5d 1e ee 81 b8 a6 c4 81 e5 bc be e..jx] dc c a 36 ab 7c 0c e0 ab b1 01 bb.d...z de a0 e a d3 ba 1f 52 7a 5f...Ve.)sgW...Rz_ * f * b3 6e 9e d5 3a 47 c6 44 4e 09 ff 29 0d a5 a1 c3.n..:g.dn..) f3 b5 50 c6 42 f0 5b f6 7d 57 0d 0a f9 2..P.B.[Y).}W d6 d a e9 dd c1 eb d3 03 d6 "..hw.* f fa 4b 8c 1c 3e 7c db e6 3e 72 fd 8d.y'`.K..>..>r d9 ee 0f 30 5a 3a cf 7e d4 3a dc 98 bc c9 P%...0Z:.~.: b3 8f e 55 1a f c 8d 5b U...2q..[ c f0 80 d2 1c 38 d5 a c 7d 01 2f...8..w.8I }./ a1 c f5 af 67 7f d2 eb b9 e4 84 6c e C..g...l.w * @... NXP Semiconductors 191

192 Boot Loaders Secure Boot: PBL Based Platforms Product execution This section presents the steps needed to be followed in order to properly run the software product according to its intended use and functionalities Getting started The example below demonstrates the secure-boot flow with all the images loaded in NOR Flash. Steps in the demo would be: 1. ISBC code would validate the ESBC code. 2. On successful validation, ESBC code would run, which would then validate the boot script. 3. On successful validation of boot script, commands in boot script would be executed. 4. The boot script contains commands to validate next level images, i.e rootfs, linux uimage and device tree. 5. Once all the images are validated, bootm command in boot script would be executed which would pass control to linux. NOTE For PowerPC SoC's, ISBC expects the code to be validated i.e. ESBC code to be within 0-3.5G address map. In the demo we map the flash to address 0xc for the ISBC code to validate ESBC in NOR Flash using PBI commands. Once the control reaches the ESBC code the earlier mapping of flash is removed and flash is mapped to address 0xe For useful commands of U-Boot and CCS, refer to commands for different platforms under the topic 'Appendix <platform> Secure Boot Demo' Environment for Secure Boot There are 2 ways in which secure boot can be initiated: Set SB_EN bit in RCW to 1. Programming the ITS fuse. In a manufacturing environment, it is recommended that all fuses be programmed at once, including the ITS and OEM Section Write Protect bits. In a prototyping environment, it may be preferable to leave ITS and Write Protect unprogrammed (relying on RCW to initiate secure boot) until the developer has confidence in the secure boot process. Two different RCW's are provided for the demo purpose: 1. The RCW which has SB_EN bit set as 0 (sben0) and can be used when ITS = 1 i.e user wants to initiate secure boot flow using fuse. 2. The RCW which has the SB_EN bit set as 1 (sben1)and can be used when user wants to initiate secure boot using RCW SDK Images required for the demo Given below are the images required for the demo which are built with Yocto as part of the SDK: 1. RCW with PBI commands 2. ESBC (U-Boot) 3. uimage (Linux Image) * 4. rootfs Image * 5. Device tree * Please refer to User Manual QorIQ DPAA SDK for detailed description on how to run Yocto Build. Once the build process finishes, all the binaries would be present at the following location: build_<platform>_release/tmp/deploy/images 192 NXP Semiconductors

193 Boot Loaders Secure Boot: PBL Based Platforms The images will be created with the following names: u-boot-secure-boot.bin uimage-<platform>.bin fsl-image-core-<platform>.ext2.gz.u-boot uimage-<platform>.dtb U-Boot binary image for Secure Boot kernel image that can be loaded with U-Boot ramdisk filesystem image that can be loaded with U-Boot device tree binary(dtb) for kernel bootup RCW files will be present in the path build_<platform>_release/tmp/deploy/images/rcw NOTE * Some platforms with ARMv8 core have support for LINUX boot using a single kernel FIT image instead of 3 separate images (uimage, rootfs and DTB) Chain of Trust This section presents the steps needed to be followed in order to execute Chain of Trust. Steps in the demo would be: 1. ISBC code would validate the ESBC code. 2. On successful validation, ESBC code would run, which would then validate the boot script. 3. On successful validation of boot script, commands in boot script would be executed. 4. The boot script contains commands to validate next level images, i.e rootfs, linux uimage and device tree. 5. Once all the images are validated, bootm command in boot script would be executed which would pass control to linux Other images required for the demo Apart from SDK images described above, the following images are also required: 1. CSF Header of the ESBC u-boot image 2. CSF Header of the uimage * 3. CSF Header of the rootfs image * 4. CSF Header of the device tree * 5. Boot Script 6. CSF Header of the boot script The following section describes how to create the CSF headers and boot script. NOTE * Some platforms with ARMv8 core have support for LINUX boot using a single kernel FIT image instead of 3 separate images (uimage, rootfs and DTB). For these platforms a single CSF Header is required Boot Script and Signing the images User can sign all the images with same public/private key pair or can use different key pairs to sign the images. Section below describes both the processes. CST tool used for signing the images is provided as a package with yocto and is built for host. It can be run from your host machine. Install path for CST binaries in yocto: tmp/sysroots/x86_64-linux/usr/bin/cst/ NXP Semiconductors 193

194 Boot Loaders Secure Boot: PBL Based Platforms CST uses openssl libraries, version In the Yocto environment, the user needs to use below commands to rebuild cst: 1. bitbake cst-native c cleanall 2. bitbake cst-native 3. Modify the CST source code if needed. 4. bitbake cst-native c cleanall 5. bitbake cst-native c patch Note: after step5, CST binary will be put to build_<platform_release/tmp/sysroots/x86_64-linux/usr/bin/cst/ directory. Table 12. Platforms supported in SDK for Secure Boot Soc <platform> supported in SDK <platform> supported in CST B4860 b4860qds b4860 P2041 p2041rdb p3_p4_p5 P3041 p3041ds p3_p4_p5 P4080 p4080ds p3_p4_p5 P5020 p5020ds p3_p4_p5 P5040 p5040ds p3_p4_p5 T1024 t1024rdb t1_t2_t4 T104x t1040rdb, t1042rdb t1_t2_t4 T2080 t2080qds, t2080rdb t1_t2_t4 T4240 t4240qds t1_t2_t4 LS1021 ls1021aqds ls1 LS1021 ls1021atwr ls1 LS1043 ls1043ardb ls1043 LS1043 ls1043aqds ls1043 LS1012 ls1012ardb ls1012 NOTE Some platforms with ARMv8 core have support for LINUX boot using a single kernel FIT image instead of 3 separate images (uimage, rootfs and DTB). For such platforms, in CST as well instead of 3 different input files for signing uimage, rootfs and dtb, there is a single input file named input_kernel_secure which can be used to sign the single kernel FIT image. This applies to all subsequent sections below Signing the images using same key pair CSF header needs to be generated for all the images. More details on the commands provided by CST can be found in Section. 194 NXP Semiconductors

195 Boot Loaders Secure Boot: PBL Based Platforms 1. Generate the key pair to be used for signing the image./gen_keys 1024 Key pair - public key file - srk.pub and private key in srk.priv would be generated. 2. Obtain hash string of the key pair generated to be programmed in SFP./uni_sign --hash input_files/uni_sign/<platform>/input_uboot_secure This would provide you the 256 bit hash in form of string of the key pair generated in the previous step. The hash has to be programmed in the SRK hash Fuse. 3. Create CSF header for u-boot Image../uni_sign input_files/uni_sign/<platform>/input_uboot_secure The input fields are specified in input_uboot_secure file. Please ensure that the filename mentioned in the input_uboot_secure is same as copied in the cst directory. 4. Create CSF header for Linux uimage./uni_sign input_files/uni_sign/<platform>/input_uimage_secure uimage.bin would be validated form u-boot. The flash address used here is according to the address map of u-boot. Please ensure that filename mentioned in the input_uimage_secure is same as copied in the cst directory. 5. Create CSF header for rootfs./uni_sign input_files/uni_sign/<platform>/input_rootfs_secure Please make sure that filename mentioned in the input_rootfs_secure is same as copied in the cst directory 6. Create CSF Header for hardware device tree./uni_sign input_files/uni_sign/<platform>/input_dtb_secure Please make sure that filename mentioned in the input_dtb_secure is same as copied in the cst directory 7. Create Boot script Bootscript is a U-Boot script image. Steps to create bootscript are given below : a. Create a text file bootscript.txt with following commands. esbc_validate <uimage CSF Header address> esbc_validate <dtb CSF Header address> esbc_validate <rootfs CSF Header address> bootm <uimage Address> <rootfs address> <dtb address> b. Then you will have to use the mkimage tool to convert this text file into a U-Boot image (using the image type script) powerpc arch:: /tmp/sysroots/x86_64-linux/usr/bin/mkimage -A ppc -T script -a 0 -e 0x40 -d bootscript.txt bootscript arm arch:: /tmp/sysroots/x86_64-linux/usr/bin/mkimage -A arm -T script -a 0 -e 0x40 -d bootscript.txt bootscript 8. Generate CSF hdr for the boot script./uni_sign input_files/uni_sign/<platform>/input_bootscript_secure The fields can be changed in the input files for the images based on the requirement. NXP Semiconductors 195

196 Boot Loaders Secure Boot: PBL Based Platforms Signing the images using different key pair If boot script is also signed with a different key, remember to define the macro "CONFIG_BOOTSCRIPT_KEY_HASH" with the hash of the key used to sign the boot script in file arch/powerpc/asm/include/fsl_secure_boot.h. ESBC u-boot would have to be recompiled if any change in this file is made. 1. Generate the key pair to be used for signing the image./gen_keys p u-boot.priv -k u-boot.pub Key pair - public key file - u-boot.pub and private key in u-boot.priv would be generated. 2. Obtain hash string of the key pair generated to be programmed in SFP./uni_sign --hash input_files/uni_sign/<platform>/input_uboot_secure This would provide you the 256 bit hash in form of string of the key pair generated in the previous step. The hash has to be programmed in the SRK hash Fuse. 3. Create CSF header for u-boot Image. Open input_files/uni_sign/<platform>/input_uboot_secure and change PRI_KEY and PUB_KEY to u- noot.priv and u-boot.pub respectively and run the following command../uni_sign input_files/uni_sign/<platform>/input_uboot_secure 4. Create CSF header for Linux uimage using different key pair. Repeat step 1 to generate another key pair../gen_keys p lnx.priv -k lnx.pub Open input_files/uni_sign/<platform>/input_uimage_secure and change PRI_KEY and PUB_KEY to lnx.priv and lnx.pub respectively and run the following command../uni_sign input_files/uni_sign/<platform>/ input_uimage_secure Remember the "Key Hash" printed as it would be required in esbc_validate command in boot script. Say the hash of the key is <lnx_key_hash> 5. Create CSF header for rootfs./gen_keys p rootfs.priv -k rootfs.pub Open input_files/uni_sign/<platform>/input_rootfs_secure and change PRI_KEY and PUB_KEY to rootfs.priv and rootfs.pub respectively and run the following command../uni_sign input_files/uni_sign/<platform>/input_rootfs_secure Remember the "Key Hash" printed as it would be required in esbc_validate command in boot script. Say the hash of the key is <rootfs_key_hash> 6. Create CSF Header for hardware device tree./gen_keys p dtb.priv -k dtb.pub Open input_files/uni_sign/<platform>/input_dtb_secure and change PRI_KEY and PUB_KEY to dtb.priv and dtb.pub respectively and run the following command../uni_sign input_files/uni_sign/<platform>/ input_dtb_secure Remember the "Key Hash" printed as it would be required in esbc_validate command in boot script. Say the hash of the key is <dtb_key_hash> 7. Write Boot script Bootscript is a U-Boot script image. Steps to create bootscript are given below : 196 NXP Semiconductors

197 Boot Loaders Secure Boot: PBL Based Platforms a. Create a text file bootscript.txt with following commands. esbc_validate <uimage CSF Header address> <lnx_key_hash> esbc_validate <dtb CSF Header address> <dtb_key_hash> esbc_validate <rootfs CSF Header address> <rootfs_key_hahs> bootm <uimage Address> <rootfs address> <dtb address> NOTE Hashes would be the 256 bit string hash. These are the hashes of the key used to sign the respective images. b. Generate header over bootscript.txt which will be consumed by uboot command source powerpc arch :: tmp/sysroots/x86_64-linux/usr/bin/mkimage -A ppc -T script -a 0 -e 0x40 -d bootscript.txt bootscript arm arch :: tmp/sysroots/x86_64-linux/usr/bin/mkimage -A arm -T script -a 0 -e 0x40 -d bootscript.txt bootscript 8. Generate CSF hdr for the boot script./gen_keys p bs.priv -k bs.pub Open input_files/uni_sign/<platform>/input_dtb_secure and change PRI_KEY and PUB_KEY to bs.priv and bs.pub respectively and run the following command../uni_sign input_files/uni_sign/<platform>/input_dtb_secure Running secure boot (Chain of Trust) 1. Setup the board for secure boot flow. You can choose any if the flows mentioned below. a. Flow A Program the ITS fuse. Use RCW with SB_EN=0 Or b. Flow B For protyping phase, don't blow the ITS fuse, but use rcw with SB_EN = 1. Note: For P3/P4/P5, if ITS fuse is blown, then ITF fuse must also be blown. (The value of ITS and ITF fuse must be identical.) 2. Blow other required fuses on the board. (OTPMK and SRK hash [1] ) For more details regarding fuse blowing, CCS and Boot Hold Off, refer to Platform reference manual and Trust Architecture User Guide. NOTE SRK hash in the fuse should be same as the hash of the key pair being used to sign the ESBC u- boot. Step 2 of Signing the images using same key pair on page 194 For testing purpose, the SRK Hash can be written in the mirror registers. gen_otpmk_drbg utility in cst can be used to generate otpmk key. 3. Flash all the generated images at locations as described in the address map ( specified for different platforms under the topic 'Appendix <platform> Secure Boot Demo' ). [1] Blowing of OTPMKis essential to run secure boot for both Production (Flow A) and Prototyping/Development (Flow B). For SRK Hash,in Development Mode (Flow B), there is a workaround to avoid blowing fuses. For this use RCW with BOOT_HO = 1. This will put the core in Boot Hold off stage. Then a CCS can be connected via JTAG. Write the SRK Hash value in SFP mirror registers and then release the core out of Boot Hold off by writing to Core Release Register in DCFG. NXP Semiconductors 197

198 Boot Loaders Secure Boot: PBL Based Platforms a. Flow A - All the images would have to be flashed at the current bank addresses. Once ITS fuse is blown, the control would automatically shift to ISBC on power on. b. If you are using Flow B, you can use alternate bank for demo purpose. This would mean flashing the images on alternate bank addresses from Bank0 and then switching to Bank4. 4. Give a power on cycle to the board. a. For Flow A and Flow B (Secure boot Images flashed on default Bank) On power on, ISBC code would get control, validate the ESBC image. ESBC image would further validate the signed linux, rootfs and dtb images Linux would come up b. Flow B (Secure boot Images flashed on alternate Bank) On power on cycle, u-boot prompt on bank 0 would come up. On switching to alternate bank, the secure boot flow as mentioned above would execute Chain of Trust with Confidentiality This section presents the steps needed to be followed in order to execute Chain of Trust with confidentiality. The demo would be divided into two parts: 1. Creating /encrypting images in form of blobs. 2. Decrypting the images, and booting from decrypted images. Steps in the demo would be: Step 1: Creating blobs 1. ISBC code would validate the ESBC code. 2. On successful validation, ESBC code would run, which would then validate the boot script. 3. On successful validation of boot script, commands in boot script would be executed. 4. The boot script contains commands to encapsullate next level images, i.e rootfs, linux uimage and device tree. blob encapsulation command:: blob enc src dst len km - Encapsulate and create blob of data $len - Number of bytes to be encapsulated. $src - The address where image to be encapsulated is present. $dst - The address where encapsulated image will be stored. $km - It is the address where the key modifier is stored. The modifier is required and used as key for cryptographic operation. Key modifier should be 16 bytes long. Step 2: Decrypting blob and booting 1. ISBC code would validate the ESBC code. 2. On successful validation, ESBC code would run, which would then validate the boot script. 3. On successful validation of boot script, commands in boot script would be executed. 4. The boot script contains commands to decapsulate/decrypt next level images, i.e rootfs, linux uimage and device tree. 5. After decryption, bootm command would be executed in boot script to pass control to Linux. blob decapsulation command:: blob dec src dst len km - Decapsulate the image and recover the data 198 NXP Semiconductors

199 Boot Loaders Secure Boot: PBL Based Platforms $len - Number of bytes to be decapsulated. $src - The address where encapsulated image is present. $dst - The address where decapsulated image will be stored. $km - It is the address where the key modifier is stored. The modifier is required and used as key for cryptographic operation. Key modifier should be 16 bytes long. It should be same as passed while encapsulating the image Other images required for the demo Apart from SDK images described above, the following images are also required: 1. Encap Boot script 2. Decap Boot script 3. CSF header for ESBC u-boot Image 4. CSF Header of the encap boot script 5. CSF Header of the decap boot script The following section describes how to create the CSF headers and boot script Encap Bootscript 1. Create a bootscript_en.txt file with following commands: blob enc <uimage address> 0x <uimage size> <key_modifier address> erase <encapsulated uimage address> +<encapsulated uimage size> cp.b 0x <encapsulated uimage address> <encapsulated uimage size> blob enc <rootfs address> 0x <rootfs size> <key_modifier address> erase <encapsulated rootfs address> +<encapsulated rootfs size> cp.b 0x <encapsulated rootfs address> <encapsulated rootfs size> blob enc <dtb address> 0x <dtb size> <key_modifier address> erase <encapsulated dtb address> +<encapsulated dtb size> cp.b 0x <encapsulated dtb address> <encapsulated dtb size> For the addresses to load images refer Section for different platforms under the topic 'Appendix <platform> Secure Boot Demo' 2. Use the mkimage tool to convert this text file into a U-Boot image (using the image type script) /tmp/sysroots/x86_64-linux/usr/bin/mkimage -A ppc -T script -a 0 -e 0x40 -d bootscript_en.txt bootscript_encap Decap Bootscript 1. Create a bootscript_de.txt file with following commands: blob dec <encapsulated uimage address> 0x <uimage size + 0x30> <key_modifier address> blob dec <encapsulated rootfs address> 0x <rootfs size + 0x30> <key_modifier address> blob dec <encapsulated dtb address> 0x <dtb size + 0x30> <key_modifier address> NXP Semiconductors 199

200 Boot Loaders Secure Boot: PBL Based Platforms bootm 0x x x For the addresses to load images refer section for different platforms under the topic 'Appendix <platform> Secure Boot Demo' The script decapsulates/decrypts the blob created by earlier boot script and boots using them. NOTE 0x30(48 bytes) should be added in the size of encapsulated images while decapsulating them. Always 48B are added at the end of the encapsulated image which needs to be added while providing the size of image to be decapsulated in blob dec command. 2. Use the mkimage tool to convert this text file into a U-Boot image (using the image type script) /tmp/sysroots/x86_64-linux/usr/bin/mkimage -A ppc -T script -a 0 -e 0x40 -d bootscript_de.txt bootscript_decap Creating CSF Headers CSF Header for ESBC Use the command given below to generate the hdr for u-boot binary../uni_sign input_files/uni_sign/<platform>/<input file for uboot> Please change the binary name as per your uboot binary in IMAGE_1. CSF Header for bootscript_encap and bootscript_decap Use the command given below to generate the headers for bootscripts./uni_sign input_files/uni_sign/<platform>/<input file for bootscript> Please change the binary name as per your bootscript in IMAGE_ Running secure boot (Chain of Trust with Confidentiality) 1. Setup the board for secure boot flow. You can choose any if the flows mentioned below. a. Flow A Program the ITS fuse. Use RCW with SB_EN=0 Or b. Flow B For protyping phase, don't blow the ITS fuse, but use rcw with SB_EN = 1. Note: For P3/P4/P5, if ITS fuse is blown, then ITF fuse must also be blown. (The value of ITS and ITF fuse must be identical.) 2. Blow other required fuses on the board. (OTPMK and SRK hash [2] ) For more details regarding fuse blowing, CCS and Boot Hold Off, refer to Platform reference manual and Trust Architecture User Guide. [2] Blowing of OTPMKis essential to run secure boot for both Production (Flow A) and Prototyping/Development (Flow B). For SRK Hash,in Development Mode (Flow B), there is a workaround to avoid blowing fuses. For this use RCW with BOOT_HO = 1. This will put the core in Boot Hold off stage. Then a CCS can be connected via JTAG. Write the SRK Hash value in SFP mirror registers and then release the core out of Boot Hold off by writing to Core Release Register in DCFG. 200 NXP Semiconductors

201 Boot Loaders Secure Boot: PBL Based Platforms NOTE SRK hash in the fuse should be same as the hash of the key pair being used to sign the ESBC u- boot. For testing purpose, the SRK Hash can be written in the mirror registers. gen_otpmk_drbg utility in cst can be used to generate otpmk key. 3. Flash all the generated images at locations as described in the address map specified for different platforms under the topic 'Appendix <platform> Secure Boot Demo' Uboot binary CSF Header of uboot Linux uimage Rootfs Device tree bootscript_encap CSF Header for bootscript_encap a. Flow A - All the images would have to be flashed at the current bank addresses. Once ITS fuse is blown, the control would automatically shift to ISBC on power on. b. If you are using Flow B, you can use alternate bank for demo purpose. This would mean flashing the images on alternate bank addresses from Bank0 and then switching to Bank4. 4. Give a power on cycle to the board. a. For Flow A and Flow B (Secure boot Images flashed on default Bank) On power on, ISBC code would get control, validate the ESBC image. ESBC image would further validate the bootscript. Bootscript would encapsulate the Linux, rootfs and device tree and store the blobs at the desired locations. b. Flow B (Secure boot Images flashed on alternate Bank) On power on cycle, u-boot prompt on bank 0 would come up. On switching to alternate bank, the secure boot flow as mentioned above would execute. 5. Give a power on cycle to the board. 6. Replace the encap bootscript and its CSF header with decap bootscript and the CSF header of the decap bootscript respectively. 7. Give a power on cycle to the board. a. For Flow A and Flow B (Secure boot Images flashed on default Bank) On power on, ISBC code would get control, validate the ESBC image. ESBC image would further validate the bootscript. Bootscript would decapsulate the Linux, rootfs and device tree bloband store them on DDR Bootm commnd in bootscript would execute on successful decapsulation Linux prompt would come up.. b. Flow B (Secure boot Images flashed on alternate Bank) On power on cycle, u-boot prompt on bank 0 would come up. On switching to alternate bank, the secure boot flow as mentioned above would execute. NXP Semiconductors 201

202 Boot Loaders Secure Boot: PBL Based Platforms NAND Secure Boot (Chain of Trust) This section presents the steps and images needed for running Secure Boot Chain of Trust from NAND on P3/P5. The procedure for running Secure boot from NAND is same as Secure Boot from NAND. The only difference is that in case of NOR, image is not required to be copied from NOR while in case of NAND, images have to be copied from NAND to SRAM/ DDR before validation. Images Required for Demo 1. PBL.bin The PBL.bin is generated using QCVS Tool. It creates the RCW along with PBI commands. ESBC (U-boot) and CSF Header for U-Boot are added using ACS_WRITE PBI commands. (For details/screenshots refer Using QCVS Tool (Secure Boot From NAND) on page 245) 2. uimage (Linux Image) 3. rootfs 4. dtb (Device Tree) 5. CSF Header of the uimage 6. CSF Header of the rootfs image 7. CSF Header of the device tree 8. Boot Script 9. CSF Header of the Boot Script Boot Script The sample bootscript.txt would have the following commands: # Read uimage & Header nand read <uimage DDR> <uimage NAND> <uimage size> nand read <uimage Header DDR> <uimage Header NAND> <uimage Header size> # Read rootfs & Header nand read <rootfs DDR> <rootfs NAND> <rootfs size> nand read <rootfs Header DDR> <rootfs Header NAND> <rootfs Header size> # Read dtb & Header nand read <dtb DDR> <dtb NAND> <dtb size> nand read <dtb Header DDR> <dtb Header NAND> <dtb Header size> # Validate and Boot esbc_validate <uimage Header DDR> esbc_validate <DTB Header DDR> esbc_validate <rootfs Header DDR> bootm <uimage DDR> <rootfs DDR> <dtb DDR> Image Signing The image signing process will remain same as in case of NOR #unique_225 <platform> will be p3_p4_p5/nand NOTE ISBC Key Extension Feature is not applicable for Secure Boot from NAND Running Secure Boot Chain of Trust (from NAND) 1. Setup the board for secure boot flow. You can choose any if the flows mentioned below. 202 NXP Semiconductors

203 Boot Loaders Secure Boot: PBL Based Platforms a. Flow A Program the ITS fuse. Use RCW with SB_EN=0 Or b. Flow B For protyping phase, don't blow the ITS fuse, but use rcw with SB_EN = 1. Note: For P3/P5, if ITS fuse is blown, then ITF fuse must also be blown. (The value of ITS and ITF fuse must be identical.) 2. Blow other required fuses on the board. (OTPMK and SRK hash [3] ) For more details regarding fuse blowing, CCS and Boot Hold Off, refer to Platform reference manual and Trust Architecture User Guide. NOTE SRK hash in the fuse should be same as the hash of the key pair being used to sign the ESBC u- boot. Step 2 of Signing the images using same key pair on page 194 For testing purpose, the SRK Hash can be written in the mirror registers. gen_otpmk_drbg utility in cst can be used to generate otpmk key. 3. Flash all the generated images on NAND Flash at locations as described in the address map (specified for different platforms under the topic 'Appendix <platform> Secure Boot Demo' ). 4. Switch to NAND Boot. a. FLOW A Change the Switch Settings to change the RCW_SRC to NAND and power on the board. b. FLOW B Power on the board to bring up Non-Secure U-Boot on NOR and from U-Boot promt issue the following command. mw.b 0xffdf0020 0x48;mw.b 0xffdf0021 0x78;mw.b 0xffdf002c 0x90;mw.b 0xffdf002d 0xf0;mw.b 0xffdf0010 0; mw.b 0xffdf The PBL would configure CPC as SRAM, update the SCRATCH register and copy the Header and U-boot (ESBC) on CPC configured as SRAM. ISBC code would get control, validate the ESBC image. ESBC image would further copy the Boot Script Header and Boot Script from NAND to DDR, validate the boot script and execute it. The Boot Script has commands to copy the linux images and their respective headers from NAND to DDR, validate the signed linux, rootfs and dtb images. Linux would be booted. [3] Blowing of OTPMKis essential to run secure boot for both Production (Flow A) and Prototyping/Development (Flow B). For SRK Hash,in Development Mode (Flow B), there is a workaround to avoid blowing fuses. For this use RCW with BOOT_HO = 1. This will put the core in Boot Hold off stage. Then a CCS can be connected via JTAG. Write the SRK Hash value in SFP mirror registers and then release the core out of Boot Hold off by writing to Core Release Register in DCFG. NXP Semiconductors 203

204 Boot Loaders Secure Boot: PBL Based Platforms NAND Secure Boot (Chain of Trust with Confidentiality) This section presents the steps and images needed for running Secure Boot Chain of Trust with Confidentiality from NAND on P3/P5 The procedure for running Secure boot from NAND is same as Secure Boot from NAND. The only difference is that in case of NOR, image is not required to be copied from NOR while in case of NAND, images have to be copied from NAND to SRAM/ DDR before validation. Images Required for Demo 1. PBL.bin The PBL.bin is generated using QCVS Tool. It creates the RCW along with PBI commands. ESBC (U-boot) and CSF Header for U-Boot are added using ACS_WRITE PBI commands. (For details/screenshots refer Using QCVS Tool (Secure Boot From NAND) on page 245) 2. uimage (Linux Image) 3. rootfs 4. dtb (Device Tree) 5. Encap Boot Script 6. CSF Header of the Encap Boot Script 7. Decap Boot Script 8. CSH Header for Decap Boot Script Encap Boot Script # uimage nand read <uimage DDR> <uimage NAND> <uimage size> esbc_blob_encap <uimage DDR> 0x <uimage size> 0x aabbccddeeff nand erase <encapsulated uimage NAND> <encapsulated uimage size> nand write 0x <encapsulated uimage NAND> <encapsulated uimage size> # rootfs nand read <rootfs DDR> <rootfs NAND> <rootfs size> esbc_blob_encap <rootfs DDR> 0x <rootfs size> 0x aabbccddeeff nand erase <encapsulated rootfs NAND> <encapsulated rootfs size> nand write 0x <encapsulated rootfs NAND> <encapsulated rootfs size> # dtb nand read <dtb DDR> <dtb NAND> <dtb size> esbc_blob_encap <dtb DDR> 0x <dtb size> 0x aabbccddeeff nand erase <encapsulated dtb NAND> <encapsulated dtb size> nand write 0x <encapsulated dtb NAND> <encapsulated dtb size> Decap Boot Script nand read <encapsulated uimage DDR> <encapsulated uimage NAND> <encapsulated uimage size> esbc_blob_decap <encapsulated uimage DDR> 0x <uimage size> 0x aabbccddeeff nand read <encapsulated rootfs DDR> <encapsulated rootfs NAND> <encapsulated rootfs size> esbc_blob_decap <encapsulated rootfs DDR> 0x <rootfs size> 0x aabbccddeeff nand read <encapsulated dtb DDR> <encapsulated dtb NAND> <encapsulated dtb size> esbc_blob_decap <encapsulated dtb DDR> 0x <dtb size> 0x aabbccddeeff 204 NXP Semiconductors

205 Boot Loaders Secure Boot: PBL Based Platforms bootm 0x x x Image Signing The image signing process will remain same as in case of NOR #unique_225 <platform> will be p3_p4_p5/nand Running Secure Boot Chain of Trust with Confidentiality (from NAND) 1. Setup the board for secure boot flow. You can choose any if the flows mentioned below. a. Flow A Program the ITS fuse. Use RCW with SB_EN=0 Or b. Flow B For protyping phase, don't blow the ITS fuse, but use rcw with SB_EN = 1. Note: For P3/P5, if ITS fuse is blown, then ITF fuse must also be blown. (The value of ITS and ITF fuse must be identical.) 2. Blow other required fuses on the board. (OTPMK and SRK hash [4] ) For more details regarding fuse blowing, CCS and Boot Hold Off, refer to Platform reference manual and Trust Architecture User Guide. NOTE SRK hash in the fuse should be same as the hash of the key pair being used to sign the ESBC u- boot. Step 2 of Signing the images using same key pair on page 194 For testing purpose, the SRK Hash can be written in the mirror registers. gen_otpmk_drbg utility in cst can be used to generate otpmk key. 3. Flash all the generated images on NAND Flash at locations as described in the address map (specified for different platforms under the topic 'Appendix <platform> Secure Boot Demo' ) a. PBL.bin b. LINUX Images (uimage, dtb, rootfs) c. CSF Header for bootscript_encap) d. bootscript_encap 4. Switch to NAND Boot. a. FLOW A Change the Switch Settings to change the RCW_SRC to NAND and power on the board. b. FLOW B [4] Blowing of OTPMKis essential to run secure boot for both Production (Flow A) and Prototyping/Development (Flow B). For SRK Hash,in Development Mode (Flow B), there is a workaround to avoid blowing fuses. For this use RCW with BOOT_HO = 1. This will put the core in Boot Hold off stage. Then a CCS can be connected via JTAG. Write the SRK Hash value in SFP mirror registers and then release the core out of Boot Hold off by writing to Core Release Register in DCFG. NXP Semiconductors 205

206 Boot Loaders Secure Boot: PBL Based Platforms Power on the board to bring up Non-Secure U-Boot on NOR and from U-Boot promt issue the following command. mw.b 0xffdf0020 0x48;mw.b 0xffdf0021 0x78;mw.b 0xffdf002c 0x90;mw.b 0xffdf002d 0xf0;mw.b 0xffdf0010 0; mw.b 0xffdf The PBL would configure CPC as SRAM, update the SCRATCH register and copy the Header and U-boot (ESBC) on CPC configured as SRAM. ISBC code would get control, validate the ESBC image. ESBC image would further copy the Boot Script Header and Boot Script from NAND to DDR, validate the boot script and execute it. Bootscript would encapsulate the Linux, rootfs and device tree and store the blobs at the desired locations. 5. Revert the switch settings to earlier RCW_SRC and power on the board. Replace the encap bootscript and its CSF header with decap bootscript and the CSF header of the decap bootscript respectively. 6. Switch to NAND Boot. a. FLOW A Change the Switch Settings to change the RCW_SRC to NAND and power on the board. b. FLOW B Power on the board to bring up Non-Secure U-Boot on NOR and from U-Boot promt issue the following command. mw.b 0xffdf0020 0x48;mw.b 0xffdf0021 0x78;mw.b 0xffdf002c 0x90;mw.b 0xffdf002d 0xf0;mw.b 0xffdf0010 0; mw.b 0xffdf The PBL would configure CPC as SRAM, update the SCRATCH register and copy the Header and U-boot (ESBC) on CPC configured as SRAM. ISBC code would get control, validate the ESBC image. ESBC image would further copy the Boot Script Header and Boot Script from NAND to DDR, validate the boot script and execute it. Bootscript would copy the Linux, rootfs and device tree blobs on DDR and then decapsulate them on DDR. Bootm commnd in bootscript would execute on successful decapsulation. Linux prompt would come up. 206 NXP Semiconductors

207 Boot Loaders Secure Boot: PBL Based Platforms Troubleshooting Table 13. Troubleshooting Symptoms Reasons and/or Recommended actions 1. No print on UART console. Check the status register of sec mon block (location 0xfe314014). Refer to the details of the register from the Reference Manual. Bits OTPMK_ZERO, OTMPK_SYNDROME and PE should be 0 otherwise there is some error in the OTPMK fuse blown by you. 2. Instead of linux prompt, you get a u-boot command prompt instead of linux prompt. If OTMPK fuse is correct (see Step 1), check the SCRATCHRW2 register for errors. Refer to Section for error codes. If Error code = 0 then check the Security Monitor state in HPSR register of Sec Mon. Sec Mon in Check State (0x9) If ITS fuse = 1, then it means ISBC code has reset the board. This may be due to the following reasons: Hash of the public key used to sign the ESBC u-boot doesn't match with the value in SRK Hash Fuse Or Signature verification of the image failed Sec Mon in Trusted State (0xd) or Non Secure State (0xb) Check the entry point field in the ESBC header. It should be 0xcffffffc for the demo described in Section 4. If entry point is correct, ensure that u-boot image has been compiled with the required secure boot configuration. You have not booted in secure boot mode. You never get a u-boot prompt in secure boot flow. Check Step 1 in Running secure boot (Chain of Trust) on page 197. You would reach this stage if ITS = 0 and you are using rcw where sben0 is present in its name. 3 u-boot hangs or board resets Some validation failure occurred in ESBC u-boot. Error code and description would be printed on u-boot console. Refer to for more details on errors CSF Header Data Structure The CSF Header provides the ISBC with most of the information needed to validate the image. NXP Semiconductors 207

208 Boot Loaders Secure Boot: PBL Based Platforms P3/P4/P5 Platforms Figure 16. CSF Header for P3/P4/P5 (ISBC and ESBC Phase) Offset Data Bits [0:31] Table 14. CSF Header Format (P3/P4/P5 Platforms) 0x00-0x03 0x04-0x07 0x08-0x0b Barker code. This location should contain the value: 0x The ISBC code searches for this Barker code. If the value in this location does not match the Barker code, the ISBC stops execution and reports error. Public key offset. This location contains an offset in bytes of the public key from the start of CSF header. Using this offset and the public key length, the public key is read. Public key length in bytes. (Value populated here should be twice of Modulus size). Supported sizes are 256, 512 or 1024 bytes (2 * 1024, 2 * 2048, 2 * 4096 bits). Table continues on the next page NXP Semiconductors

209 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 14. CSF Header Format (P3/P4/P5 Platforms) (continued) 0x0c-0x0f 0x10-0x13 0x14-0x17 0x18-0x1b 0x1c-0x1f 0x20-0x23 0x24-0x27 0x28-0x2b RSA Signature offset. This location contains an offset(in bytes) of the RSA signature from the start of CSF header. Using this offset and the Signature length, the RSA signature is read. The RSA signature is calculated over CSF Header, Scatter Gather table and ESBC images. RSA Signature length in bytes. For ISBC Phase: Based on the Scatter Gather flag in CSF header, this location can either be treated as Pointer to Scatter Gather table or the address of ESBC image. For ESBC Phase: This location is treated as address of image(linux/bootscript/rootfs/dtb) to be validated. For ISBC Phase: Based on the Scatter gather flag in CSF Header, this location can either be treated as number of entries in SG table or ESBC image size in bytes. For ESBC Phase: Size of image to be validated For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved. For ISBC Phase: Scatter Gather flag. 0x0000-0x14-0x17 is a pointer to the ESBC image 0x0001-0x14-0x17 is a pointer to a scatter/gather table. For ESBC Phase: Reserved Unique ID Usage. UIDs present in the CSF Header are compared to the corresponding UIDs in the SFP, and are included in the ESBC validation. 0x No UIDs are present in CSF header 0x FSL_UID and OEM_UID are present in CSF header 0x Only OEM_UID present in CSF header 0x Only FSL_UID present in CSF header Freescale unique ID. A unique 32 bit value, which is specific to Freescale. This value is compared with the FSL ID in Secure Fuse Processor 's FSL-ID registers Table continues on the next page... NXP Semiconductors 209

210 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 14. CSF Header Format (P3/P4/P5 Platforms) (continued) 0x2c-0x2f 0x30-0x47 0x48-0x4b 0x4c-0x4f OEM unique ID. A unique 32 bit value, which is specific to OEM. This value is compared with the OEM ID in Secure Fuse Processor 's OEM-ID registers For ISBC Phase: Not Applicable For ESBC Phase: Reserved For ISBC Phase: Not Applicable For ESBC Phase: ISBC key Extension flag. If this flag is set, key to be used for validation needs to be picked up from IE Key table. For ISBC Phase: Not Applicable For ESBC Phase: IE Key Select. Key Number to be used from the IE Key Table if IE flag is set. Offset Data Bits [0:31] Table 15. Scatter Gather Table Format (P3/P4/P5 Platforms) 0x00-0x03 0x04-0x07 0x08-0x0b 0x0c-0x0f 0xww-0xxx 0xyy-0xzz Length in bytes of the first segment of the ESBC image. Pointer to first segment of ESBC image. Length in bytes of the second segment of the ESBC image. Pointer to second segment of ESBC image. Length in bytes of the nth segment of the ESBC image. Pointer to nth segment of ESBC image Table 16. Signature (P3/P4/P5 Platforms) Offset Data Bits [0:31] 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). 210 NXP Semiconductors

211 Boot Loaders Secure Boot: PBL Based Platforms Table 17. Public key (P3/P4/P5 Platforms) Offset Data Bits [0:31] 0x00-size Public Key Value. The hash of this public key is compared with the hash stored in Secure Fuse Processor SRKH registers. B4/T1/T2/T4 Platforms Figure 17. CSF Header for B4/T1/T2/T4 (ISBC and ESBC Phase) Offset Data Bits [0:31] Table 18. CSF Header Format (B4/T1/T2/T4 Platforms) 0x00-0x03 Barker code. This location should contain the value: 0x The ISBC code searches for this Barker code. If the value in this location does not match the Barker code, the ISBC stops execution and reports error. Table continues on the next page... NXP Semiconductors 211

212 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 18. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) 0x04-0x07 If the srk_table_flag is not set : Public key offset: This location contains an address which is the offset of the public key from the start of CSF header. Using this offset and the public key length, the public key is read. If srk_table_flag is set: Srk table offset: This location contains an address which is the offset of the srk table from the start of CSF header. Using this offset and the number of entries is SRK Table, the SRK table is read. 0x08 Srk table flag. This flag indicates whether hash burnt in srk fuse is of a single key or of srk table. 0x09-0x0b If the srk_table_flag is not set : Public key length: This location contains the length of the public key in bytes. If srk_table_flag is set: 0x09 Key Number from srk table which is to be used for verification. 0x0a-0x0b Number of entries in srk table. Minimum number of entries in table = 1, Maximum = 4. 0x0c-0x0f 0x10-0x13 0x14-0x17 0x18-0x1b RSA Signature offset. This location contains an offset(in bytes) of the RSA signature from the start of CSF header. Using this offset and the Signature length, the RSA signature is read. The RSA signature is calculated over CSF Header, Scatter Gather table and ESBC images. RSA Signature length in bytes. For ISBC Phase: SG Table offset This location contains an address which is the offset of the SG table from the start of CSF header. Using this offset and the number of entries is SG Table, the SG table is read. For ESBC Phase: Address of the image to be validated. For ISBC Phase: Number of entries in SG Table (Earlier,Based on the Scatter gather flag in CSF Header, this location can either be treated as number of entries in SG table or ESBC image size in bytes.). For ESBC Phase: Size of Image to be validated Table continues on the next page NXP Semiconductors

213 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 18. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) 0x1c-0x1f 0x20-0x23 0x24 0x25 0x26-0x27 0x28-0x2b 0x2c-0x2f 0x30-0x33 For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved Reserved.(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) For ISBC Phase: Reserved For ESBC Phase: Reserved For ISBC Phase: Secondary Image flag Indicates if user has a secondary image available in case of failures in validating primary iamge.valid in case of primary Images s Header. For ESBC Phase:Reserved Unique ID Usage This location contains a flag which specifies one of these possibilities 0x00 - No UID s present 0x01 - FSL UID and OEM UID are present 0x02 - Only FSL UID is present 0x04 - Only OEM UID is present Freescale unique ID. A unique 32 bit value, which is specific to Freescale. This value is compared with the FSL ID in Secure Fuse Processor 's FSL-ID registers OEM unique ID. A unique 32 bit value, which is specific to OEM. This value is compared with the OEM ID in Secure Fuse Processor 's OEM-ID registers For ISBC Phase: Housekeeping area address This is address of start of a memory which can be accessed by devices on SOC bus. (DDR, L3 cache configured as SRAM ). The area should have been pre-configured by user through PBL commands or configuration header For ESBC Phase: Reserved Table continues on the next page... NXP Semiconductors 213

214 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 18. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) 0x34-0x37 0x38-0x3f 0x40-0x47 0x48-0x4b 0x4c-0x4f For ISBC Phase: Size of the housekeeping area Size of the pre-configured memory which can be used by Boot Rom Code. For ESBC Phase: Reserved Reserved For ISBC Phase: Not Applicable For ESBC Phase: Reserved For ISBC Phase: Not Applicable For ESBC Phase: ISBC key Extension flag If this flag is set, key to be used for validation needs to be picked up from IE Key table. For ISBC Phase: Not Applicable For ESBC Phase: IE Key Select Key Number to be used from the IE Key Table if IE flag is set. Offset Data Bits [0:31] Table 19. Scatter Gather Table Format (B4/T1/T2/T4 Platforms) 0x00-0x03 Length. This location specifies the length in bytes of the ESBC image 1. 0x04-0x07 Target where the ESBC Image 1 can be found. This field is ignored in case of PBL based SOC s. 0x08-0x0b Source Address of ESBC Image 1 0x0c-0x0f Destination Address of ESBC Image 1 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. 0x10-0x13 Length. This location specifies the length in bytes of the ESBC image 2. 0x14-0x17 Target where the ESBC Image 2 can be found. This field is ignored in case of PBL based SOC s. 0x18-0x1b Source Address of ESBC Image 2 0x1c-0x1f Destination Address of ESBC Image 2 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. 214 NXP Semiconductors

215 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 20. Signature (B4/T1/T2/T4 Platforms) 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Offset Data Bits [0:31] Table 21. Public key (B4/T1/T2/T4 Platforms) 0x00-size Public Key Value. The hash of this public key is compared with the hash stored in Secure Fuse Processor SRKH registers. Offset Data Bits [0:31] Table 22. SRK Table (B4/T1/T2/T4 Platforms) 0x00-0x03 0x04-0x403 0x404-0x407 0x408-0x807 0x808-0x80b 0x80c-0xb0b 0xb0c-0xb0f 0xb10-0xe10 Key 1 length Key 1 value. (Remaining bytes will be padded with zero) Key 2 length Key 2 value. (Remaining bytes will be padded with zero) Key 3 length Key 3 value. (Remaining bytes will be padded with zero) Key 4 length Key 4 value. (Remaining bytes will be padded with zero) NXP Semiconductors 215

216 Boot Loaders Secure Boot: PBL Based Platforms LS1 Platform Figure 18. CSF Header for LS1 (ISBC and ESBC Phase) Offset Data Bits [0:31] Table 23. CSF Header Format (LS1 Platform) 0x00-0x03 Barker code. This location should contain the value: 0x The ISBC code searches for this Barker code. If the value in this location does not match the Barker code, the ISBC stops execution and reports error. 0x07-0x04 If the srk_table_flag is not set : Public key offset: This location contains an address which is the offset of the public key from the start of CSF header. Using this offset and the public key length, the public key is read. If srk_table_flag is set: Srk table offset: This location contains an address which is the offset of the srk table from the start of CSF header. Using this offset and the number of entries is SRK Table, the SRK table is read. Table continues on the next page NXP Semiconductors

217 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 23. CSF Header Format (LS1 Platform) (continued) 0x08 Srk table flag. This flag indicates whether hash burnt in srk fuse is of a single key or of srk table. 0x0b-0x09 If the srk_table_flag is not set : 0x0b-0x9 -- Public key length: This location contains the length of the public key in bytes. If srk_table_flag is set: 0x09 Key Number from srk table which is to be used for verification. 0x0b-0x0a Number of entries in srk table. Minimum number of entries in table = 1, Maximum = 4. 0x0f-0x0c 0x13-0x10 0x17-0x14 0x1b-0x18 0x1f-0x1c 0x21-0x20 0x23-0x22 RSA Signature offset. This location contains an offset(in bytes) of the RSA signature from the start of CSF header. Using this offset and the Signature length, the RSA signature is read. The RSA signature is calculated over CSF Header, Scatter Gather table and ESBC images. RSA Signature length in bytes. For ISBC Phase: SG Table offset This location contains an address which is the offset of the SG table from the start of CSF header. Using this offset and the number of entries is SG Table, the SG table is read. For ESBC Phase: Address of the image to be validated. For ISBC Phase: Number of entries in SG Table (Earlier,Based on the Scatter gather flag in CSF Header, this location can either be treated as number of entries in SG table or ESBC image size in bytes.). For ESBC Phase Size of image to be validated For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved Manufacturing Protection Flag Indicates if manufacturing protection has to be enabled or not in ISBC. Reserved.(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) Table continues on the next page... NXP Semiconductors 217

218 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 23. CSF Header Format (LS1 Platform) (continued) 0x24 0x25 0x27-0x26 For ISBC Phase: Reserved For ESBC Phase: Reserved For ISBC Phase Secondary Image flag Indicates if user has a secondary image available in case of failures in validating primary iamge.valid in case of primary Images s Header. For ESBC Phase:Reserved Unique ID Usage This location contains a flag which specifies one of these possibilities 0x00 - No UID s present 0x01 - FSL UID and OEM UID are present 0x02 - Only FSL UID is present 0x04 - Only OEM UID is present 0x2b-0x28 Freescale unique ID 0 0x2f-0x2c OEM unique ID 0 Upper 32 bits of a unique 64 bit value, which is specific to Freescale. This value is compared with the FSL ID 1 in Secure Fuse Processor 's FSL-ID registers Upper 32 bits of a unique 64 bit value, which is specific to OEM. This value is compared with the OEM ID 0 in Secure Fuse Processor 's OEM-ID registers 0x37-0x30 Reserved 0x3b-0x38 Freescale unique ID 1 0x3f-0x3c OEM unique ID 1 Lower 32 bits of a unique 64 bit value, which is specific to Freescale. This value is compared with the FSL ID 1 in Secure Fuse Processor 's FSL-ID registers Lower 32 bits of a unique 32 bit value, which is specific to OEM. This value is compared with the OEM ID 1 in Secure Fuse Processor 's OEM-ID registers 0x40-0x47 0x48-0x4b For ISBC Phase: Not Applicable For ESBC Phase: Reserved For ISBC Phase: Not Applicable For ESBC Phase: ISBC key Extension flag If this flag is set, key to be used for validation needs to be picked up from IE Key table. Table continues on the next page NXP Semiconductors

219 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 23. CSF Header Format (LS1 Platform) (continued) 0x4c-0x4f For ISBC Phase: Not Applicable For ESBC Phase: IE Key Select Key Number to be used from the IE Key Table if IE flag is set. Offset Data Bits [0:31] Table 24. Scatter Gather Table Format (LS1 Platform) 0x00-0x03 Length. This location specifies the length in bytes of the ESBC image 1. 0x04-0x07 Target where the ESBC Image 1 can be found. This field is ignored in case of PBL based SOC s. 0x08-0x0b Source Address of ESBC Image 1 0x0c-0x0f Destination Address of ESBC Image 1 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. 0x10-0x13 Length. This location specifies the length in bytes of the ESBC image 2. 0x14-0x17 Target where the ESBC Image 2 can be found. This field is ignored in case of PBL based SOC s. 0x18-0x1b Source Address of ESBC Image 2 0x1c-0x1f Destination Address of ESBC Image 2 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. Offset Data Bits [0:31] Table 25. Signature (LS1 Platform) 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Table 26. Public key (LS1 Platform) Offset Data Bits [0:31] 0x00-size Public Key Value. The hash of this public key is compared with the hash stored in Secure Fuse Processor SRKH registers. NXP Semiconductors 219

220 Boot Loaders Secure Boot: PBL Based Platforms Table 27. SRK Table (LS1 Platform) Offset Data Bits [0:31] 0x00-0x03 0x04-0x403 0x404-0x407 0x408-0x807 0x808-0x80b 0x80c-0xb0b 0xb0c-0xb0f 0xb10-0xe10 Key 1 length Key 1 value. (Remaining bytes will be padded with zero) Key 2 length Key 2 value. (Remaining bytes will be padded with zero) Key 3 length Key 3 value. (Remaining bytes will be padded with zero) Key 4 length Key 4 value. (Remaining bytes will be padded with zero) 220 NXP Semiconductors

221 Boot Loaders Secure Boot: PBL Based Platforms LS1043/LS1012 Platforms Figure 19. CSF Header for LS1043/LS1012 (ISBC and ESBC Phase) Offset Data Bits [0:31] Table 28. CSF Header Format (LS1043/LS1012 Platforms) 0x00-0x03 Barker code. This location should contain the value: 0x The ISBC code searches for this Barker code. If the value in this location does not match the Barker code, the ISBC stops execution and reports error. 0x07-0x04 If the srk_table_flag is not set : Public key offset: This location contains an address which is the offset of the public key from the start of CSF header. Using this offset and the public key length, the public key is read. If srk_table_flag is set: Srk table offset: This location contains an address which is the offset of the srk table from the start of CSF header. Using this offset and the number of entries is SRK Table, the SRK table is read. Table continues on the next page... NXP Semiconductors 221

222 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 28. CSF Header Format (LS1043/LS1012 Platforms) (continued) 0x08 Srk table flag. This flag indicates whether hash burnt in srk fuse is of a single key or of srk table. 0x0b-0x09 If the srk_table_flag is not set : 0x0b-0x9 -- Public key length: This location contains the length of the public key in bytes. If srk_table_flag is set: 0x09 Key Number from srk table which is to be used for verification. 0x0b-0x0a Number of entries in srk table. Minimum number of entries in table = 1, Maximum = 4. 0x0f-0x0c 0x13-0x10 0x17-0x14 0x1b-0x18 0x1f-0x1c 0x21-0x20 0x23-0x22 RSA Signature offset. This location contains an offset(in bytes) of the RSA signature from the start of CSF header. Using this offset and the Signature length, the RSA signature is read. The RSA signature is calculated over CSF Header, Scatter Gather table and ESBC images. RSA Signature length in bytes. For ISBC Phase: SG Table offset This location contains an address which is the offset of the SG table from the start of CSF header. Using this offset and the number of entries is SG Table, the SG table is read. For ESBC Phase: Reserved For ISBC Phase: Number of entries in SG Table (Earlier,Based on the Scatter gather flag in CSF Header, this location can either be treated as number of entries in SG table or ESBC image size in bytes.). For ESBC Phase Size of image to be validated For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved Manufacturing Protection Flag Indicates if manufacturing protection has to be enabled or not in ISBC. Reserved.(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) Table continues on the next page NXP Semiconductors

223 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 28. CSF Header Format (LS1043/LS1012 Platforms) (continued) 0x24 0x25 0x27-0x26 For ISBC Phase: Reserved For ESBC Phase: Reserved For ISBC Phase Secondary Image flag Indicates if user has a secondary image available in case of failures in validating primary iamge.valid in case of primary Images s Header. For ESBC Phase:Reserved Unique ID Usage This location contains a flag which specifies one of these possibilities 0x00 - No UID s present 0x01 - FSL UID and OEM UID are present 0x02 - Only FSL UID is present 0x04 - Only OEM UID is present 0x2b-0x28 Freescale unique ID 0 0x2f-0x2c OEM unique ID 0 Upper 32 bits of a unique 64 bit value, which is specific to Freescale. This value is compared with the FSL ID 1 in Secure Fuse Processor 's FSL-ID registers Upper 32 bits of a unique 64 bit value, which is specific to OEM. This value is compared with the OEM ID 0 in Secure Fuse Processor 's OEM-ID registers 0x37-0x30 Reserved 0x3b-0x38 Freescale unique ID 1 0x3f-0x3c OEM unique ID 1 Lower 32 bits of a unique 64 bit value, which is specific to Freescale. This value is compared with the FSL ID 1 in Secure Fuse Processor 's FSL-ID registers Lower 32 bits of a unique 32 bit value, which is specific to OEM. This value is compared with the OEM ID 1 in Secure Fuse Processor 's OEM-ID registers 0x40-0x47 0x48-0x4b For ISBC Phase: Not Applicable For ESBC Phase: 64 bit pointer to ESBC image For ISBC Phase: Not Applicable For ESBC Phase: ISBC key Extension flag If this flag is set, key to be used for validation needs to be picked up from IE Key table. Table continues on the next page... NXP Semiconductors 223

224 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 28. CSF Header Format (LS1043/LS1012 Platforms) (continued) 0x4c-0x4f For ISBC Phase: Not Applicable For ESBC Phase: IE Key Select Key Number to be used from the IE Key Table if IE flag is set. Offset Data Bits [0:31] Table 29. Scatter Gather Table Format (LS1043/LS1012 Platforms) 0x00-0x03 Length. This location specifies the length in bytes of the ESBC image 1. 0x04-0x07 Target where the ESBC Image 1 can be found. This field is ignored in case of PBL based SOC s. 0x08-0x0b Source Address of ESBC Image 1 0x0c-0x0f Destination Address of ESBC Image 1 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. 0x10-0x13 Length. This location specifies the length in bytes of the ESBC image 2. 0x14-0x17 Target where the ESBC Image 2 can be found. This field is ignored in case of PBL based SOC s. 0x18-0x1b Source Address of ESBC Image 2 0x1c-0x1f Destination Address of ESBC Image 2 If the target address is 0xffffffff, the image is not copied to the target. This field is ignored in case of PBL based SOC s. Offset Data Bits [0:31] Table 30. Signature (LS1043/LS1012 Platforms) 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Offset Data Bits [0:31] Table 31. Public key (LS1043/LS1012 Platforms) 0x00-size Public Key Value. The hash of this public key is compared with the hash stored in Secure Fuse Processor SRKH registers. 224 NXP Semiconductors

225 Boot Loaders Secure Boot: PBL Based Platforms Offset Data Bits [0:31] Table 32. SRK Table (LS1043/LS1012 Platforms) 0x00-0x03 0x04-0x403 0x404-0x407 0x408-0x807 0x808-0x80b 0x80c-0xb0b 0xb0c-0xb0f 0xb10-0xe10 Key 1 length Key 1 value. (Remaining bytes will be padded with zero) Key 2 length Key 2 value. (Remaining bytes will be padded with zero) Key 3 length Key 3 value. (Remaining bytes will be padded with zero) Key 4 length Key 4 value. (Remaining bytes will be padded with zero) ISBC Validation Error Codes P3/P4/P5 platforms Table 33. ISBC Validation Failures (P3/P4/P5 platforms) Value Code Definition 0x1 CPUID_NO_MATCH ISBC is not running on CPU0 0x2 ESBC_HDR_LOC ESBC header location is not in 3.5G space 0x4 ESBC_HEADER_BARKER Barker code in the header is incorrect. 0x8 ESBC_HEADER_KEY_LEN Length of public key in header is not one of the supported values. 0x10 ESBC_HEADER_SIGN_LEN Length of RSA signature in header is not one of the supported values. 0x20 0x40 0x80 ESBC_HEADER_KEY_LEN_NOT_T WICE_SIG_LEN ESBC_HEADER_SG_TABLE_ADDR_ NULL ESBC_HEADER_SG_TABLE_ADDR_ NOT_IN_3_5G Public key is not twice the length of the RSA signature SG table/esbc image address (0x14-0x17 in CSF Header) is null SG table/esbc image address (0x14-0x17 in CSF Header) is beyond 3.5G 0x100 ESBC_HEADER_KEY_MOD_1 Most significant bit of modulus in header is zero. Table continues on the next page... NXP Semiconductors 225

226 Boot Loaders Secure Boot: PBL Based Platforms Table 33. ISBC Validation Failures (P3/P4/P5 platforms) (continued) Value Code Definition 0x200 ESBC_HEADER_KEY_MOD_2 Modulus in header is even number 0x400 ESBC_HEADER_SIG_KEY_MOD Signature value is greater than modulus in header 0x800 ESBC_HEADER_SG_ENTRIES_NUL SG Table contains zero entries 0x1000 ESBC_HEADER_SG_ENTRIES_NOT _IN_3_5G Address in SG entry in not in 3.5G 0x2000 ESBC_HEADER_SG_ESBC_EP ESBC entry point in header not within ESBC address range 0x4000 HASH_COMPARE_KEY Super Root Key Hash Comparison failure. Mismatch in the hash of the public key as present in the header with the value in the SRK HASH fuse. 0x8000 HASH_COMPARE_EM RSA signature check failure. Signature provided by you in the header doesn't match with the signature of the ESBC image generated by ISBC. The ESBC image loaded by you may be different than the image used while generating the signature(using CST) 0x10000 SSM_CHECKSTS SEC_MON State Machine not in CHECK state at start of ISBC. Some Security violation could have occurred. Details can be found in P4080 Reference Manual. 0x20000 SSM_TRUSTSTS SEC_MON State Machine not in TRUSTED state at end of ISBC. 0x40000 FSL_UID FSL_UID in ESBC Header did not match the FSL_UID in SFP 0x80000 OEM_UID OEM_UID in ESBC Header did not match the OEM_UID in SFP 0x BAD_ADDRESS A Data / Instruction TLB Exception occurred during ISBC execution 0x MISC E500mc exception other than TLB 0x ESBC_HEADER_SG_ENTIRES_BAD SG Table too large (too many entries) NOTE For error codes 0x2-0x2000 i,e errors in the ESBC Header, check the value of that particular field by dumping the header. B4/T1/T2/T4/LS1/LS1043/LS1012 platforms Errors in the system can be of following types: 1. Core Exceptions 2. System State Failures 226 NXP Semiconductors

227 Boot Loaders Secure Boot: PBL Based Platforms 3. Header Checking Failures a. General Failures b. Key/Signature/UID related errors 4. Verification Failures 5. SEC/PAMU errors Table 34. Core Exceptions (LS1 platform) Value Code Definition 0x1 ERROR_UNDEFINED_INSTRUCTION Occurs if neither the processor nor any attached coprocessor recognizes the currently executing instruction. 0x2 ERROR_SWI Software Interrupt is a user-defined interrupt instruction. It allows a program running in User mode, for example, to request privileged operations that run in Supervisor mode. 0x3 ERROR_PREFETCH_ABORT Occurs when the processor attempts to execute an instruction that has been prefetched from an illegal address. 0x4 ERROR_DATA_ABORT Occurs when a data transfer instruction attempts to load or store data at an illegal address. 0x5 ERROR_IRQ Occurs when the processor external interrupt request pin is asserted (LOW) and IRQ interrupts are enabled. 0x6 ERROR_FIQ Occurs when the processor external fast interrupt request pin is asserted (LOW) and FIQ interrupts are enabled. Table 35. Core Exceptions (LS1043/LS1012 platforms) Error Code Value Current EL with SP0 ERROR_EXCEPTION_SYNC_SP0 ERROR_EXCEPTION_IRQ_SP0 ERROR_EXCEPTION_FIQ_SP0 ERROR_EXCEPTION_SERROR_SP0 0x01 0x02 0x03 0x04 Current EL with SPx ERROR_EXCEPTION_SYNC_SPX ERROR_EXCEPTION_IRQ_SPX ERROR_EXCEPTION_FIQ_SPX ERROR_EXCEPTION_SERROR_SPX 0x05 0x06 0x07 0x08 Lower EL using AArch64 ERROR_EXCEPTION_SYNC_L64 ERROR_EXCEPTION_IRQ_L64 0x11 0x12 Table continues on the next page... NXP Semiconductors 227

228 Boot Loaders Secure Boot: PBL Based Platforms Table 35. Core Exceptions (LS1043/LS1012 platforms) (continued) ERROR_EXCEPTION_FIQ_L64 ERROR_EXCEPTION_SERROR_L64 0x13 0x14 Lower EL using AArch32 ERROR_EXCEPTION_SYNC_L32 ERROR_EXCEPTION_IRQ_L32 ERROR_EXCEPTION_FIQ_L32 ERROR_EXCEPTION_SERROR_L32 0x15 0x16 0x17 0x18 Table 36. Core Exceptions (B4/T1/T2/T4 platforms) Value Code Definition 0x1 ERROR_MACHINECHECK Machine check Exception 0x2 ERROR_DSI DSI Exception 0x3 ERROR_ISI ISI Exception 0x4 ERROR_CRITICAL Critical Exception 0x5 ERROR_ALIGN Alignment Exception 0x6 ERROR_PROG Program Exception 0x13 ERROR_DATA_TLB Data TLB Miss 0x14 ERROR_INST_TLB Instruction TLb Miss 0x20 ERROR_MISC Any other exception Table 37. System State Failures (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) Value Code Definition 0x100 ERROR_CORE_NON_ZERO ISBC is not running on CPU0 0x101 ERROR_STATE_NOT_CHECK SEC_MON State Machine not in CHECK state at start of ISBC. Some Security violation could have occurred. 0x102 ERROR2_STATE_NOT_CHECK SEC_MON State Machine not in CHECK state, when trying to transition it to Trusted/Non Secure/Soft Fail state 0x103 ERROR_SSM_TRUSTSTS SEC_MON State Machine not in TRUSTED state at end of ISBC. 228 NXP Semiconductors

229 Boot Loaders Secure Boot: PBL Based Platforms Table 38. General Header Checking Failures (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) Value Code Definition 0x301 ERROR_ESBC_HDR_LOC ESBC header location is not in 3.5G space 0x302 ERROR_ESBC_HEADER_BARKER Barker code in the header is incorrect. 0x303 ERROR_ESBC_HEADER_SG_ENTRIES _NOT_IN_3_5G SG table/esbc image address (header address + image offset in sg table) is beyond 3.5G 0x304 ERROR_ESBC_HEADER_SG_ESBC_EP ESBC entry point in header not within ESBC address range 0x305 0x306 0x307 0x308 ERROR_SGL_ENTIRES_NOT_SUPPOR TED ERROR_ESBC_HEADER_HKAREA_LE N_ZERO ERROR_ESBC_HEADER_HKAREA_NO T_IN_3_5G ERROR_ESBC_HEADER_HKAREA_LE N_INSUFFICIENT Number of entries in SG table exceeds maximum limit i.e 8 Houskeeping area not provided in header House keeping area not in 3.5G boundary Housekeeping area length provided is not sufficient. 0x309 ERROR_SG_TABLE_NOT_IN_3_5 SG Table is not in 3.5G boundary 0x310 ERROR_ESBC_HEADER_HKAREA_NO T_4K_ALIGNED House keeping area is not aligned to 4K boundary 0x311 ERROR_SGL_ENTRIES_SIZE_ZERO SG table has entry with size zero. Table 39. Key/Signature/UID related errors (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) Value Code Definition 0x320 ERROR_ESBC_HEADER_KEY_LEN Length of public key in header is not one of the supported values. 0x321 ERROR_ESBC_HEADER_KEY_LEN_ NOT_TWICE_SIG_LEN Public key is not twice the length of the RSA signature 0x322 ERROR_ESBC_HEADER_KEY_MOD_1 Most significant bit of modulus in header is zero. 0x323 ERROR_ESBC_HEADER_KEY_MOD_2 Modulus in header is even number 0x324 ERROR_ESBC_HEADER_SIG_KEY_MO D Signature value is greater than modulus in header 0x325 ERROR_FSL_UID FSL_UID in ESBC Header did not match the FSL_UID in SFP if fsl uid flag Is 1 0x326 ERROR_OEM_UID OEM_UID in ESBC Header did not match the OEM_UID in SFP if oem uid flag is 1. 0x327 ERROR_INVALID_SRK_NUM_ENTRY Number of entries field in CSF Header is > 4(This is when srk_flag in header is 1) 0x328 ERROR_INVALID_KEY_NUM Key number to be used from srk table is not present in table. ( This is when srk_flag in header is 1) Table continues on the next page... NXP Semiconductors 229

230 Boot Loaders Secure Boot: PBL Based Platforms Table 39. Key/Signature/UID related errors (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) (continued) Value Code Definition 0x329 ERROR_KEY_REVOKED Key selected from srk table has been revoked(this is when srk_flag in header is 1) 0x32a ERROR_INVALID_SRK_ENTRY_KEYLE N Key length specified in one of the entries in srk table is not one of the supported values (This is when srk_flag in header is 1) 0x32b ERROR_SRK_TBL_NOT_IN_3_5 SRK Table is not in 3.5G boundary (This is when srk_flag in header is 1) 0x32c ERROR_KEY_NOT_IN_3_5G Key is not in 3.5G boundary Table 40. Verification Failures (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) Value Code Definition 0x340 ERROR_HASH_COMPARE_KEY Super Root Key Hash Comparison failure. Mismatch in the hash of the public key/srk table as present in the header with the value in the SRK HASH fuse. 0x341 ERROR_HASH_COMPARE_EM RSA signature check failure. Signature provided by you in the header doesn t match with the signature of the ESBC image generated by ISBC. The ESBC image loaded by you may be different than the image used while generating the signature(using CST) Table 41. SEC/PAMU Failures (B4/T1/T2/T4/LS1/LS1043/LS1012 platforms) Value Code Definition 0x700 ERROR_SEC_ENQ Error when enqueuing to SEC 0x701 ERROR_SEC_DEQ Sec Block returned some error when dequeuing from it. 0x702 ERROR_SEC_DEQ_TO Timeout when trying to deq from SEC 0x800 ERROR_PAMU Error while programming PAACT/SPAACT tables in PAMU (For PowerPC platforms only) ESBC Validation Error Codes For trust arch version 1.x and 2.x. Table 42. ESBC Validation Failures Value Code Definition 0x4 ERROR_ESBC_CLIENT_HEADER_BARK ER Wrong barker code in header Table continues on the next page NXP Semiconductors

231 Boot Loaders Secure Boot: PBL Based Platforms Table 42. ESBC Validation Failures (continued) Value Code Definition 0x8 0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 ERROR_ESBC_CLIENT_HEADER_KEY_ LEN ERROR_ESBC_CLIENT_HEADER_SIG_L EN ERROR_ESBC_CLIENT_HEADER_KEY_ REVOKED ERROR_ESBC_CLIENT_HEADER_INVAL ID_SRK_NUM_ENTRY ERROR_ESBC_CLIENT_HEADER_INVAL ID_KEY_NUM ERROR_ESBC_CLIENT_HEADER_INV_S RK_ENTRY_KEYLEN ERROR_ESBC_CLIENT_HEADER_IE_KE Y_REVOKED ERROR_ESBC_CLIENT_HEADER_INVAL ID_IE_NUM_ENTRY ERROR_ESBC_CLIENT_HEADER_INVAL ID_IE_KEY_NUM ERROR_ESBC_CLIENT_HEADER_INV_I E_ENTRY_KEYLEN Wrong public key length in header Wrong signature length in header Selected key is revoked. Wrong key entry. Wrong key is selected. Wrong srk public key len in header. Selected IE key is revoked. Wrong key entry in IE Table. Wrong IE key is selected. Wrong IE public key len in header. 0x19 ERROR_IE_TABLE_NOT_FOUND Information about IE Table missing. 0x20 ERROR_ESBC_CLIENT_HEADER_KEY_ LEN_NOT_TWICE_SIG_LEN Public key length not twice of signature length 0x21 ERROR_KEY_TABLE_NOT_FOUND No Key/ Key Table Found in header. 0x40 0x80 0x100 0x400 ERROR_ESBC_CLIENT_HEADER_KEY_ MOD_1 ERROR_ESBC_CLIENT_HEADER_KEY_ MOD_2 ERROR_ESBC_CLIENT_HEADER_SIG_K EY_MOD ERROR_ESBC_CLIENT_HASH_COMPAR E_KEY Public key Modulus most significant bit not set Public key Modulus in header not odd Signature not less than modulus Public key hash comparison failed Table continues on the next page... NXP Semiconductors 231

232 Boot Loaders Secure Boot: PBL Based Platforms Table 42. ESBC Validation Failures (continued) Value Code Definition 0x800 ERROR_ESBC_CLIENT_HASH_COMPAR E_EM RSA verification failed 0x2000 ERROR_ESBC_CLIENT_BAD_ADDRESS Bad address error. 0x4000 ERROR_ESBC_CLIENT_MISC Miscallaneous error. 0x20000 ERROR_ESBC_CLIENT_HEADER_IMG_ SIZE Invalid Image size. 0x40000 ERROR_ESBC_WRONG_CMD Unknown cmd/wrong arguments. Core in infinite loop. 0x80000 ERROR_ESBC_MISSING_BOOTM Bootm command missing from bootscript Address map used for the demo The addresses below are effective addresses as mapped by u-boot. P3/P4/P5/T1/T2/T4 platforms Table 43. Memory map for P3/P4/P5/T1_T2_T4 platforms Address(N OR vbank 0) Address (NOR Alternate Bank) [5] Definition (Chain of Trust) Definition (Chain of Trust with Confidentiality) Size Reserved (KB) E EC RCW RCW 128 E EC uimage uimage 8064 E EC DTB DTB 1024 E EC E8A00000 ECA00000 Bootscript Bootscript 1024 E8B00000 ECB00000 ESBC U-Boot HEADER ESBC U-Boot HEADER 1024 E8C00000 ECC E8E00000 ECE00000 Bootscript Header Bootscript Header 1024 E8F00000 ECF E ED uimage Heaer 1024 Table continues on the next page... [5] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank NXP Semiconductors

233 Boot Loaders Secure Boot: PBL Based Platforms Table 43. Memory map for P3/P4/P5/T1_T2_T4 platforms (continued) Address(N OR vbank 0) Address (NOR Alternate Bank) [5] Definition (Chain of Trust) Definition (Chain of Trust with Confidentiality) Size Reserved (KB) E ED DTB Header 1024 E ED Rootfs Header 1024 E ED Rootfs Rootfs EC E uimage (ENCAPSULATED) EC E DTB (ENCAPSULATED) ED E Rootfs (ENCAPSULATED) EFF20000 EBF20000 u-boot env u-boot env (current bank) EFF40000 EBF40000 u-boot u-boot 768 Chain Of Trust Boot Script Used as per Address Map esbc_validate 0xE esbc_validate 0xE esbc_validate 0xE bootm 0xE xE xE B4 platforms Table 44. Memory map for B4 platforms Address(NO R vbank 0) Address (NOR Alternate Bank) [6] Definition (Chain of Trust) Definition (Chain of Trust with Confidentiality) Size Reserved (KB) EC EE RCW RCW 128 Table continues on the next page... [5] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. [6] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. [6] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. NXP Semiconductors 233

234 Boot Loaders Secure Boot: PBL Based Platforms Table 44. Memory map for B4 platforms (continued) Address(NO R vbank 0) Address (NOR Alternate Bank) [6] Definition (Chain of Trust) Definition (Chain of Trust with Confidentiality) Size Reserved (KB) EC EE uimage uimage 7040 EC EE Bootscript Bootscript 1024 EC EE DTB DTB 1024 EC EE ECA00000 EEA ECB00000 EEB00000 ESBC U-Boot HEADER ESBC U-Boot HEADER 1024 ECC00000 EEC00000 Bootscript Header Bootscript Header 1024 ECD00000 EED00000 uimage Heaer 1024 ECE00000 EEE00000 Rootfs Header 1024 ECF00000 EEF00000 DTB Header 1024 ED EF DTB (Encapsulated) ED EF uimage (Encapsulated ) EE EC rootfs/ rootfs (ENCAPSULATED) EFF20000 EDF20000 u-boot env u-boot env 128 EFF40000 EDF40000 u-boot u-boot 768 NOTE To use 512KB u-boot, change u-boot address from xxx40000 to xxx Chain Of Trust Boot Script Used as per Address Map esbc_validate 0xECD00000 esbc_validate 0xECE00000 esbc_validate 0xECF00000 bootm 0xEC xEE xEC LS NXP Semiconductors

235 Boot Loaders Secure Boot: PBL Based Platforms Table 45. Memory map for LS1 platforms Address NOR(vBank 0) Address (NOR Alternate Bank) [7] Definition (Chain of Trust) Size Reserved(KB) RCW DTB Bootscript ESBC U-Boot HEADER A A0000 Bootscript Header ESBC U-Boot uimage A A00000 Rootfs F F00000 uimage Header F F20000 DTB Header F F40000 rootfs Header 128 Chain Of Trust Boot Script Used as per Address Map esbc_validate 0x63F20000 esbc_validate 0x63F00000 esbc_validate 0x63F40000 bootm 0x x60A x LS1043 Table 46. Memory map for LS1043 platforms Address NOR(vBank 0) Address (NOR Alternate Bank) [8] Definition (Chain of Trust) Size Reserved (KB) RCW Bootscript ESBC U-Boot HEADER 128 Table continues on the next page... [7] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. [8] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. NXP Semiconductors 235

236 Boot Loaders Secure Boot: PBL Based Platforms Table 46. Memory map for LS1043 platforms (continued) Address NOR(vBank 0) Address (NOR Alternate Bank) [8] Definition (Chain of Trust) Size Reserved (KB) 600A A0000 Bootscript Header C C0000 PPA Header ESBC U-Boot PPA FIT Image A00000* 64A00000* Kernel FIT Image F F40000 kernel Header 128 NOTE * For LS1043 Bootscript, kernel image must be copied to DDR address 0x before issuing esbc_validate command. Chain of Trust Boot Script Used as per Address Map # Copy the Kernel Image from Flash to DDR cp.b 0x60A x x # Validate the Kernel Image (The header has Image address as 0x ) esbc_validate 0x63F40000 # Boot the validated Kernel FIT Image. setenv bootargs "console=ttys0, root=/dev/ram0 earlycon=uart8250,0x21c0500"; setenv fdt_high "0xffffffffffffffff"; setenv initrd_high "0xffffffffffffffff"; bootm $img_addr LS1012 NOTE * For QSPI flash banking support on LS1012, please refer to [QorIQ LS1012A SDK vx.x-->software Deployment Guides-->Boards--><board-name>-->Flash Bank Usage]. [8] Address to be used for loading the images in case of working in Development mode with Non-Secure Boot images on Bank 0. [9] QSPI by default works in 64bit Big Endian as XIP memory. So the data has to be 64 bit byte swapped before loading on QSPI. 236 NXP Semiconductors

237 Boot Loaders Secure Boot: PBL Based Platforms Table 47. Memory map for LS1012 platform Address QSPI [9] Definition (Chain of Trust) Size Reserved (KB) RCW Bootscript ESBC U-Boot HEADER C0000 Bootscript Header ESBC U-Boot PPA Header PPA FIT Image A00000 [10] Kernel FIT Image/ Kernel FIT Image (ENCAPSULATED) kernel Header 128 NOTE * For LS1012 Bootscript, kernel image must be copied to DDR address 0x before issuing esbc_validate command. Chain of Trust Boot Script Used as per Address Map # Copy the Kernel Image from Flash to DDR cp.b 0x40A x x # Validate the Kernel Image (The header has Image address as 0x ) esbc_validate 0x # Boot the validated Kernel FIT Image. setenv bootargs "console=ttys0, root=/dev/ram0 earlycon=uart8250,0x21c0500"; setenv fdt_high "0xffffffffffffffff"; setenv initrd_high "0xffffffffffffffff"; bootm $img_addr Chain of Trust Boot Script with kernel image and its header placed on SD card # Copy the Kernel Image from Flash to DDR mmc read 0x x0 0x4 mmc read 0x x8 0x14000 # Validate the Kernel Image (The header has Image address as 0x ) esbc_validate 0x # Boot the validated Kernel FIT Image. [10] The Kernel Image and its CSF Header may be placed on any other memory as well. The same must be copied to DDR before validation and Booting. NXP Semiconductors 237

238 Boot Loaders Secure Boot: PBL Based Platforms setenv bootargs "console=ttys0, root=/dev/ram0 earlycon=uart8250,0x21c0500"; setenv fdt_high "0xffffffffffffffff"; setenv initrd_high "0xffffffffffffffff"; bootm $img_addr Chain of Trust with Confidentiality Encap Boot Script # Encap kernel.itb image blob enc 0x40A x x27c0000 0x # Write kernel.itb (Encapsulated) image on QSPI flash sf probe 0:0 sf erase 0xA x sf write 0x xA x # Reset to boot again using Decap Boot Script reset Decap Boot Script # Read kernel.itb (Encapsulated) image from QSPI flash sf probe 0:0 sf read 0x xA x # Decap kernel.itb (Encapsulated) Image blob dec 0x x x27c0000 0x # Validate the Kernel Image (The header has Image address as 0x ) esbc_validate 0x # Boot the validated Kernel FIT Image. setenv bootargs "console=ttys0, root=/dev/ram0 earlycon=uart8250,0x21c0500"; setenv fdt_high "0xffffffffffffffff"; setenv initrd_high "0xffffffffffffffff"; bootm $img_addr P3/P5 NAND SECURE BOOT Table 48. Memory Map for P3/P5 NAND SECURE BOOT Description (Chain of Trust) Description (Chain of Trust with Confidentiality) Address on NAND Address on DDR (Image copied to from NAND) Size PBL.bin (RCW, PBI, U-Boot, U-boot Header) PBL.bin (RCW, PBI, U-Boot, U-boot Header) 0x xD0000 Boot Script Header Boot Script Header 0x x x2000 Boot Script Boot Script 0x x x2000 uimage Header 0x x x2000 dtb Header 0x x x2000 Table continues on the next page NXP Semiconductors

239 Boot Loaders Secure Boot: PBL Based Platforms Table 48. Memory Map for P3/P5 NAND SECURE BOOT (continued) Description (Chain of Trust) Description (Chain of Trust with Confidentiality) Address on NAND Address on DDR (Image copied to from NAND) Size rootfs Header 0x x x2000 uimage uimage 0x x x dtb dtb 0x06b x00c x9000 rootfs rootfs 0x x x uimage (Encapsulated) 0x x x dtb (Encapsulated) 0x06b x x9000 rootfs (Encapsulated) 0x x x Chain Of Trust Boot Script Used as per Address Map #UImage and Header nand read 0x x x nand read 0x x x2000 #Rootfs and HEader nand read 0x x x nand read 0x x x2000 #DTB and Header nand read 0x00c x06b x9000 nand read 0x x x2000 esbc_validate 0x esbc_validate 0x esbc_validate 0x bootm 0x x x00c Useful U-Boot and CCS Commands This section contains some useful commands for loading images via U-Boot (As per memory map defined in this document) and CCS commands to load the SRK Hash in shadow registers and get the core out of boot hold off in Development mode. NOTE The CCS commands to connect and configure config chain might change with Board/Silicon Revision. Kindly refer the board manual/ccs Guide in case of issues with CCS commands.the commands provided below are for reference only. These will assist users in writing to SFP mirror registers and getting the core out of Boot Hold Off. NXP Semiconductors 239

240 Boot Loaders Secure Boot: PBL Based Platforms NOTE For permanently blowing the values (OTPMK, SRK HASH etc.) in SFP, refer to the details in Trust Arch. User Guide. A brief summary of the steps is described below: 1. Ensure that PROG_SFP/POVDD signal is correctly asserted. This is usually controlled via a switch or a jumper. (Refer Board schematic/manual for the same) 2. Write the required fuse values to the SFP mirror registers. 3. To permamnetly blow the fuses, write to 'PROGFB' in SFP Instruction Register (SFP_INGR). Make sure that the values written in SFP mirror registers are correct before blowing the fuses as once blown, the fuse values cannot be changed. To check if OTPMK is blown or not on the Silicon, check the bit 'OTPMK_ZERO' in the SECMON_HPSR register. If the bit is set, it means OTPMK is zero i.e. OTPMK needs to be blown. The OTPMK value can be generated using 'gen_otpmk_drbg' tool provided in CST. After writing the values in SFP mirror registers, check the hamming error register. Ensure that the value is 0x0 i.e. no error is reported. Hamming error is reported in SecMon_HP Status Register (HPSR) for P3/P4/P5. For other SoC's, it is reported in SFP Secret Value Hamming Error Status Register (SFP_SVHESR). T1/T2/T4 protect off all; setenv dir <tftp_path> tftp $dir/rcw.bin; erase EC $filesize; cp.b EC $filesize; tftp $dir/hdr_uboot.out;erase ECB $filesize; cp.b ECB00000 $filesize; tftp $dir/u-boot.bin;erase EBF $filesize; cp.b EBF40000 $filesize ; tftp $dir/hdr_bs.out;erase 0xECE $filesize;cp.b xECE00000 $filesize; tftp $dir/hdr_linux.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/hdr_rootfs.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/hdr_dtb.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/rootfs;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/bootscript;erase 0xECA $filesize;cp.b xECA00000 $filesize; tftp $dir/uimage.bin;erase 0xEC $filesize;cp.b xEC $filesize; tftp $dir/uimage.dtb;erase 0xEC $filesize;cp.b xEC $filesize; # Connect to CCS and configure Config Chain ccs::config_chain {t4240 j2i2cs} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem 0 0xfe ccs::display_mem 0 0xfe0e #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e823c 4 0 <SRKH1> ccs::write_mem 0 0xfe0e <SRKH2> ccs::write_mem 0 0xfe0e <SRKH3> ccs::write_mem 0 0xfe0e <SRKH4> ccs::write_mem 0 0xfe0e824c 4 0 <SRKH5> ccs::write_mem 0 0xfe0e <SRKH6> ccs::write_mem 0 0xfe0e <SRKH7> ccs::write_mem 0 0xfe0e <SRKH8> 240 NXP Semiconductors

241 Boot Loaders Secure Boot: PBL Based Platforms #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e x B4 protect off all; setenv dir <tftp_path> tftp $dir/rcw.bin; erase EE $filesize; cp.b EE $filesize; tftp $dir/hdr_uboot.out;erase EEB $filesize; cp.b EEB00000 $filesize; tftp $dir/u-boot.bin;erase EDF $filesize; cp.b EDF40000 $filesize ; tftp $dir/hdr_bs.out;erase 0xEEC $filesize;cp.b xEEC00000 $filesize; tftp $dir/hdr_linux.out;erase 0xEED $filesize;cp.b xEED00000 $filesize; tftp $dir/hdr_rootfs.out;erase 0xEEE $filesize;cp.b xEEE00000 $filesize; tftp $dir/hdr_dtb.out;erase 0xEEF $filesize;cp.b xEEF00000 $filesize; tftp $dir/rootfs;erase 0xEC $filesize;cp.b xEC $filesize; tftp $dir/bootscript;erase 0xEE $filesize;cp.b xEE $filesize; tftp $dir/uimage.bin;erase 0xEE $filesize;cp.b xEE $filesize; tftp $dir/uimage.dtb;erase 0xEE $filesize;cp.b xEE $filesize; # Connect to CCS and configure Config Chain ccs::config_chain {b4860 j2i2cs} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem 0 0xfe ccs::display_mem 0 0xfe0e #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e823c 4 0 <SRKH1> ccs::write_mem 0 0xfe0e <SRKH2> ccs::write_mem 0 0xfe0e <SRKH3> ccs::write_mem 0 0xfe0e <SRKH4> ccs::write_mem 0 0xfe0e824c 4 0 <SRKH5> ccs::write_mem 0 0xfe0e <SRKH6> ccs::write_mem 0 0xfe0e <SRKH7> ccs::write_mem 0 0xfe0e <SRKH8> #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e x P3/P4/P5 protect off all; setenv dir <tftp_path> tftp $dir/rcw.bin; erase EC $filesize; cp.b EC $filesize; tftp $dir/hdr_uboot.out;erase ECB $filesize; cp.b ECB00000 $filesize; tftp $dir/u-boot.bin;erase EBF $filesize; cp.b EBF40000 $filesize ; tftp $dir/hdr_bs.out;erase 0xECE $filesize;cp.b xECE00000 $filesize; tftp $dir/hdr_linux.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/hdr_rootfs.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/hdr_dtb.out;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/rootfs;erase 0xED $filesize;cp.b xED $filesize; tftp $dir/bootscript;erase 0xECA $filesize;cp.b xECA00000 $filesize; NXP Semiconductors 241

242 Boot Loaders Secure Boot: PBL Based Platforms tftp $dir/uimage.bin;erase 0xEC $filesize;cp.b xEC $filesize; tftp $dir/uimage.dtb;erase 0xEC $filesize;cp.b xEC $filesize; # Connect to CCS and configure Config Chain ccs::config_chain p3040 display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem 0 0xfe ccs::display_mem 0 0xfe0e #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e807c 4 0 <SRKH1> ccs::write_mem 0 0xfe0e <SRKH2> ccs::write_mem 0 0xfe0e <SRKH3> ccs::write_mem 0 0xfe0e <SRKH4> ccs::write_mem 0 0xfe0e808c 4 0 <SRKH5> ccs::write_mem 0 0xfe0e <SRKH6> ccs::write_mem 0 0xfe0e <SRKH7> ccs::write_mem 0 0xfe0e <SRKH8> #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e x LS1020 protect off all; setenv path <tftp_path> tftp $path/rcw.bin;erase $filesize;cp.b $filesize; tftp $path/hdr_uboot.out;erase $filesize;cp.b $filesize; tftp $path/u-boot.bin;erase $filesize;cp.b $filesize; tftp $path/hdr_bs.out;erase 640A0000 +$filesize;cp.b A0000 $filesize; tftp $path/bootscript;erase $filesize;cp.b $filesize; tftp $path/hdr_dtb.out;erase 67F $filesize;cp.b F20000 $filesize; tftp $path/uimage.dtb;erase $filesize;cp.b $filesize; tftp $path/hdr_linux.out;erase 67F $filesize;cp.b F00000 $filesize; tftp $path/uimage.bin;erase $filesize;cp.b $filesize; tftp $path/hdr_rootfs.out;erase 67F $filesize;cp.b F40000 $filesize; tftp $path/rootfs;erase 64a $filesize;cp.b a00000 $filesize; # Connect to CCS and configure Config Chain ccs::config_server ccs::config_chain {ls1020a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem <dap chain pos> 0x1e ccs::display_mem <dap chain pos> 0x1ee #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem <dap chain pos> 0x1e <SRKH1> ccs::write_mem <dap chain pos> 0x1e <SRKH2> ccs::write_mem <dap chain pos> 0x1e8025c 4 0 <SRKH3> ccs::write_mem <dap chain pos> 0x1e <SRKH4> ccs::write_mem <dap chain pos> 0x1e <SRKH5> 242 NXP Semiconductors

243 Boot Loaders Secure Boot: PBL Based Platforms ccs::write_mem <dap chain pos> 0x1e <SRKH6> ccs::write_mem <dap chain pos> 0x1e8026c 4 0 <SRKH7> ccs::write_mem <dap chain pos> 0x1e <SRKH8> #Get the Core Out of Boot Hold-Off ccs::write_mem <dap chain pos> 0x1ee00e x LS1043 protect off all; setenv path <tftp_path> tftp $path/rcw.bin;erase $filesize;cp.b $filesize; tftp $path/hdr_uboot.out;erase $filesize;cp.b $filesize; tftp $path/u-boot.bin;erase $filesize;cp.b $filesize; tftp $path/hdr_bs.out;erase 640A0000 +$filesize;cp.b A0000 $filesize; tftp $path/bootscript;erase $filesize;cp.b $filesize; tftp $path/hdr_kernel.out;erase 67F $filesize;cp.b F40000 $filesize; tftp $path/kernel.itb;erase 64a $filesize;cp.b a00000 $filesize; tftp $path/hdr_ppa.out;erase 640C0000 +$filesize;cp.b C0000 $filesize; tftp $path/ppa.itb;erase $filesize;cp.b $filesize; # Connect to CCS and configure Config Chain ccs::config_server ccs::config_chain {ls1043a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem <dap chain pos> 0x1e ccs::display_mem <dap chain pos> 0x1ee #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem <dap chain pos> 0x1e <SRKH1> ccs::write_mem <dap chain pos> 0x1e <SRKH2> ccs::write_mem <dap chain pos> 0x1e8025c 4 0 <SRKH3> ccs::write_mem <dap chain pos> 0x1e <SRKH4> ccs::write_mem <dap chain pos> 0x1e <SRKH5> ccs::write_mem <dap chain pos> 0x1e <SRKH6> ccs::write_mem <dap chain pos> 0x1e8026c 4 0 <SRKH7> ccs::write_mem <dap chain pos> 0x1e <SRKH8> #Get the Core Out of Boot Hold-Off ccs::write_mem <dap chain pos> 0x1ee00e x LS1012 # Steps to sign images and swap images and corresponding headers before writing to QSPI memory. # Copy secure boot release binaries as: # RCW binary: PBL_0x35_0x08_800_250_1000_sben.bin # u-boot.bin-qspi-secure-boot -> u-boot.bin # ppa-unswap.itb -> ppa.itb # kernel-ls1012ardb.itb -> kernel.itb./uni_sign input_files/uni_sign/ls1012/input_uboot_qspi_secure /bin/tclsh./byte_swap.tcl u-boot.bin u-boot_swap.bin 8 /bin/tclsh./byte_swap.tcl hdr_uboot.out hdr_swap_uboot.out 8 NXP Semiconductors 243

244 Boot Loaders Secure Boot: PBL Based Platforms./uni_sign input_files/uni_sign/ls1012/input_ppa_secure /bin/tclsh./byte_swap.tcl ppa.itb ppa_swap.itb 8 /bin/tclsh./byte_swap.tcl hdr_ppa.out hdr_swap_ppa.out 8./uni_sign input_files/uni_sign/ls1012/input_bootscript_secure /bin/tclsh./byte_swap.tcl bootscript bootscript_swap 8 /bin/tclsh./byte_swap.tcl hdr_bs.out hdr_swap_bs.out 8./uni_sign input_files/uni_sign/ls1012/input_kernel_secure /bin/tclsh./byte_swap.tcl kernel.itb kernel_swap.itb 8 /bin/tclsh./byte_swap.tcl hdr_kernel.out hdr_swap_kernel.out 8 # U-boot Commands: protect off all; setenv path <tftp_path> # To select QSPI flash bank2 i2c mw 0x24 0x7 0xfc; i2c mw 0x24 0x3 0xf5; # Write all the images on QSPI flash bank2 sf probe 0:0 tftp 0x $path/pbl_0x35_0x08_800_250_1000_sben.bin; sf erase 0x ; sf write 0x x tftp 0x $path/hdr_swap_uboot.out; sf erase 0x ; sf write 0x x tftp 0x $path/u-boot_swap.bin; sf erase 0x ; sf write 0x x tftp 0x $path/hdr_swap_bs.out; sf erase 0xC ; sf write 0x xC tftp 0x $path/bootscript_swap; sf erase 0x ; sf write 0x x tftp 0x $path/hdr_swap_kernel.out; sf erase 0x ; sf write 0x x tftp 0x $path/kernel_swap.itb; sf erase 0xA x ; sf write 0x xA x tftp 0x $path/hdr_swap_ppa.out; sf erase 0x ; sf write 0x x tftp 0x $path/ppa_swap.itb; sf erase 0x ; sf write 0x x # Reset board to run secure boot. reset # CCS Commands: # Connect to CCS and configure Config Chain ccs::config_server ccs::config_chain {ls1043a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem <dap chain pos> 0x1e ccs::display_mem <dap chain pos> 0x1ee #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem <dap chain pos> 0x1e <SRKH1> ccs::write_mem <dap chain pos> 0x1e <SRKH2> ccs::write_mem <dap chain pos> 0x1e8025c 4 0 <SRKH3> ccs::write_mem <dap chain pos> 0x1e <SRKH4> ccs::write_mem <dap chain pos> 0x1e <SRKH5> 244 NXP Semiconductors

245 Boot Loaders Secure Boot: PBL Based Platforms ccs::write_mem <dap chain pos> 0x1e <SRKH6> ccs::write_mem <dap chain pos> 0x1e8026c 4 0 <SRKH7> ccs::write_mem <dap chain pos> 0x1e <SRKH8> #Get the Core Out of Boot Hold-Off ccs::write_mem <dap chain pos> 0x1ee00e x Trust Architecture and SFP Information SoC Trust Arch. Version SFP Version POVDD DRVR OTPMK SNVS/SFP Register to Algo (CST) Register to Algo (CST) Register to check check check Hamming Hamming Hamming Error Error Error P4080 rev V A None/ Simulation P4080 rev V B None/ Simulation P4080 rev V B None/ Simulation P V B None/ Simulation P V B None/ Simulation P V B None/ Simulation P V B None/ Simulation 1 SNVS SecMon_HP Status 1 SNVS (HPSR) 1 SNVS 1 SNVS 1 SNVS 1 SNVS 1 SNVS T4240 rev V A SFP 2 SFP SFP Secret T4240 rev V A SFP 2 SFP Value Hamming B4860 rev V A SFP 2 SFP Error Status B4860 rev V A SFP 2 SFP Register (SFP_SVHE T V A SFP 2 SFP SR) T V A SFP 2 SFP T V A SFP 2 SFP LS1020A V A SFP 2 SFP LS1043A V A SFP 2 SFP LS1012A V A SFP 2 SFP Using QCVS Tool (Secure Boot From NAND) Use Freescale s QCVS tool for adding the hdr_uboot.out and u-boot.bin in terms of ALT_CONFIG_WRITE PBI commands at required addresses. The below screenshots describe the usage of QCVS Tool. NXP Semiconductors 245

246 Boot Loaders Secure Boot: PBL Based Platforms 1. Import rcw.bin from SDK in QCVS Tool. 2. Add ACS Data 0xF NXP Semiconductors

247 Boot Loaders Secure Boot: PBL Based Platforms 3. Add ACS Data NXP Semiconductors 247

248 Boot Loaders Secure Boot: PBL Based Platforms 248 NXP Semiconductors

249 Boot Loaders Secure Boot: PBL Based Platforms 4. Make Sure that the output format is Binary. NXP Semiconductors 249

250 Boot Loaders Secure Boot: PBL Based Platforms 5. Generate Processor Expert Code to get PBL.bin. 250 NXP Semiconductors

251 Boot Loaders Secure Boot: PBL Based Platforms. NXP Semiconductors 251

252 Virtualization KVM/QEMU Chapter 10 Virtualization 10.1 KVM/QEMU KVM/QEMU Release Notes Copyright (C) Freescale Semiconductor, Inc. Freescale KVM/QEMU Release Notes 06/23/2016 Overview This document describes new features, current limitations, and known issues in KVM and QEMU for NXP QorIQ LS1012A release. New Features Linux and QEMU versions: o KVM is based on the LS1012A release Linux kernel o QEMU is based on QEMU Only basic functionality is supported: basic guest boot without I/O. Limitations The following items describe known limitations with this release of KVM/QEMU: o VFIO-PCI is not supported o 64K page size in the host kernel is not supported. Privacy Terms of Use Terms of Sale Feedback NXP Semiconductors. All rights reserved KVM for ARM Architecture Users Guide and Reference Introduction to KVM and QEMU Overview This document is a guide and tutorial to building and using KVM (Kernel-based Virtual Machine) on NXP QorIQ SoCs. Virtualization provides an environment that enables running multiple operating systems on a single computer system. Virtualization uses hardware and software technologies together to enable this by providing an abstraction layer between system hardware and the OS. The isolated environment in which OSes run is known as a virtual machine (or VM). The abstraction layer that manages all this is referred to as a hypervisor or virtual machine manager. The hypervisor layer 252 NXP Semiconductors

253 Virtualization KVM/QEMU operates at a privilege level higher than that of the operating systems, thus enabling it to enforce system security, ensure that virtual machines cannot interfere with each other, and transparently provide other services such as I/O sharing to the VM. Figure 20. KVM is a Linux kernel driver that together with QEMU, an open source machine emulator, provides an open source virtualization platfiorm based on Linux. KVM and QEMU together act as a virtual machine manager that can boot and run operating systems in virtual machines. See Figure below. In this document the term host kernel refers to the underlying instance of Linux with the KVM driver that acts as the hypervisor. The term guest refers to the operating system, such as Linux, that runs in a virtual machine. A virtual machine will be referred to as a "VM". Figure 21. NXP QorIQ SoCs based on ARM v7 and ARM v8 CPUs are supported Organization of this Document This document is organized as follows: Introduction to KVM and QEMU on page 252 provides an introduction to KVM/QEMU, including overview information and references. NXP Semiconductors 253

254 Virtualization KVM/QEMU Building QEMU and KVM on page 257 provides information on how to build QEMU and the Linux kernel with KVM. Using QEMU and KVM on page 262 describes how to use KVM/QEMU, including how to invoke QEMU to start virtual machines and how to set up virtual I/O and passthrough I/O devices. Virtual machine reference on page 266 provides a reference for virtual machines-- details about initial VM state, virtual CPUs, and virtual I/O devices. This information is relevant when porting an OS or device driver to a KVM-based virtual machine. Debugging virtual machines on page 269 describes facilities available for debugging software running in a virtual machine. KVM/QEMU How-to's on page 271 provides a set of examples for common tasks Virtual Machine Overview A guest OS running in a KVM/QEMU virtual machine "sees" a hardware environment similar to running on a physical board. The guest sees CPUs, memory, and a number of I/O devices. Some aspects of this environment are virtualized (emulated in software by KVM/QEMU) but this virtualization is mostly transparent to the guest, and changes to the guest are typically not required to run in a virtual machine. The number of virtual machines that can be run simultaneously is only limited by the amount of available resources (like any other application on Linux). KVM/QEMU implements a generic virt machine which is described completely by the device tree. The virtual machine contains the following resources: one or more ARMv7/ARMv8 virtual CPUs memory virtual console based on an emulated PL011 virtio over PCI (used for virtual devices such as block and network devices) ARM Virtual Generic Interrupt Controller ARM virtual timer and counter Introduction to KVM and QEMU QEMU (pronounced KYOO-em-yoo) is a software-based machine emulator that emulates a variety of CPUs and hardware systems. KVM is a Linux kernel device driver that provides virtual CPU services to QEMU. The two software components work together as a virtual machine manager. 254 NXP Semiconductors

255 Virtualization KVM/QEMU Figure 22. QEMU is a Linux user-space application that runs on the host Linux instance and is used to start and manage a virtual machine. QEMU provides the following: A command line interface that provides extensive customization and configuration of a virtual machine when it is started-- e.g. type of VM, which images to load, and how virtual devices are configured Loading of all images needed by the guest-- e.g kernel images, root filesystem, guest device tree Setting the initial state of the VM and booting the guest Virtual I/O services, such as virtual network interfaces and virtual disks Debug services-which provide the capability to debug a guest OS using GDB (similar to a virtual JTAG) KVM is a device driver in the Linux kernel whose key role in the VM architecture is to provide virtual CPU services. These services involve two aspects: 1. First, KVM provides an API set that QEMU uses to set and get the state of virtual CPUs and run them. For example, QEMU sets the initial values of the CPU's registers before starting the VM. 2. Second, after KVM starts a guest OS, certain operations (such as privileged instructions) performed by the OS cause an exception (or exit) into the host Linux kernel that must be handled and processed by KVM. This handling of traps is referred to as "emulation". These traps are transparent to the guest. The KVM API is documented in the Linux kernel-- Documentation/virtual/kvm/api.txt. KVM/QEMU supports virtual I/O which allows sharing of physical I/O devices by multiple VMs. Virtual network and block I/O are supported. See For More Information on page 257 for references that provide additional information on virtio. NXP Semiconductors 255

256 Virtualization KVM/QEMU Device Tree Overview A device tree is a data structure that describes hardware resources such as CPUs, memory, and I/O devices. An device tree aware OS is passed a device tree which it reads to determine what hardware resources are available. The host Linux kernel is booted first, typically by u-boot (an open source bootloader). U-boot passes the kernel a hardware device tree that lists and describes all system hardware resources available to the host kernel (CPUs/cores, memory, interrupt controller and I/O). Similarly, when a guest OS is booted in a KVM/QEMU virtual machine, QEMU passes it a guest device tree that describes all the hardware resources in the VM. See Figure below. Figure 23. The guest device tree is generated by QEMU and is used to define the resources a virtual machine will see. The guest device tree defines CPUs, memory, and I/O devices. QEMU places the guest device tree in the virtual machine's memory prior to starting the virtual machine References [1] QEMU Emulator User Documentation: [2] The Linux usage model for device tree data: [3] Specification for virtio devices: NXP Semiconductors

257 Virtualization KVM/QEMU For More Information KVM KVM website: ARM VM specification: Supporting KVM on ARM architecture: QEMU QEMU website: Device Trees devicetree.org website: DTC, the device tree compiler is available at: DTC also includes a library called libfdt which can be used by software to parse device trees. Virtio-- a framework for doing virtual I/O using KVM/QEMU Virtual Networking with QEMU Building QEMU and KVM Overview Linux with KVM enabled and QEMU can be built as part of the standard build process used to build the NXP SDK using Yocto. They can also be built in a standalone manner outside of Yocto. The build instructions in the sections that follow assume a working understanding of how to use Yocto to build the NXP SDK. Please refer to the Yocto documentation in the SDK Building Linux with KVM Overview KVM is a component in the Linux kernel. KVM is not enabled in the default kernel configuration in the NXP SDK and KVM features must be enabled using the kernel's menuconfig configuration utility prior to building the kernel. In the sections that follow configuration options are described for both the host and guest Linux kernel. The host and guest kernels can be built separately, but it is possible to build a single Linux kernel image that can be used for both the host and the guest. The kernel configuration options described below would be the same if building the kernel standalone (outside of Yocto). The following sections provide high level build information: Running menuconfig with Yocto - describes how to configure the kernel under Yocto Quick Start - Recommended Configuration Options - in a single step shows all the recommended configuration options to enable to build a kernel with virtual I/O enabled with the same kernel image serving as both host and guest. NXP Semiconductors 257

258 Virtualization KVM/QEMU The following sections provide more detailed information on each KVM-related configuration option for host and guest: Host Kernel: Enabling KVM - describes the configuration options to enable KVM in the host kernel. Host Kernel: Enabling Virtual Networking - describes how to enable bridging and tun/tap in the host kernel which enables virtual networking. Guest Kernel: Enabling Network and Block Virtual I/O - describes how to enable virtual I/O in the guest kernel. Guest kernel: Enabling console - describes how to enable the console for the guest kernel Running menuconfig with Yocto The prerequisite and starting point for building the Linux kernel with KVM enabled is performing a standard kernel build with Yocto. $ bitbake virtual/kernel To change the kernel configuration options use the Linux standard menuconfig utility. To invoke menuconfig under Yocto do the following from the Yocto build environment: $ bitbake -c menuconfig virtual/kernel Note: Depending on what build steps may have been done previously, it may be necessary to invoke the command 'bitbake -c clean virtual/kernel' prior to running the menuconfig command. The result will be an xterm that appears that displays the menuconfig screen: Figure Quick Start - Recommended Configuration Options The steps below show all the recommended configuration options to enable to build a kernel with virtual I/O enabled with the same kernel image serving as both host and guest. The sections that follow explain these options in further detail. 258 NXP Semiconductors

259 Virtualization KVM/QEMU Note: The configuration options are enabled by default in the kernel configuration. However, they are are listed here for reference. 1. From the main menuconfig window enable virtualization: [*] Virtualization 2. In the virtualization menu enable the following options: [*] Kernel-based Virtual Machine (KVM) support 3. Enable network bridging Networking support ---> Networking options ---> <*> 802.1d Ethernet Bridging 4. Enable virtio PCI Device Drivers ---> Virtio drivers ---> <*> PCI driver for virtio devices 5. Enable virtio for block devices Device Drivers ---> [*] Block devices ---> <*> Virtio block driver 6. Enable virtio for network devices [*] Network core driver support <*> Universal TUN/TAP device driver support <*> Virtio network driver 7. Enable vhost for virtio network devices [*] Virtualization <*> Host kernel accelerator for virtio net 8. Enable Huge TLB file support File Systems ---> Pseudo filesystems ---> [*] Huge TLB file system support 9. Enable guest serial support Device Drivers ---> Character devices ---> Serial drivers ---> <*> ARM AMBA PL011 serial port support [*] Support for console on AMBA serial port NXP Semiconductors 259

260 Virtualization KVM/QEMU Host Kernel: Enabling KVM This section describes the core, basic options needed to enable KVM in the host kernel. KVM is enabled in the host kernel under the virtualization menu of the main kernel menuconfig window. [*] Virtualization Core KVM support is enabled as follows: [*] Kernel-based Virtual Machine (KVM) support Host Kernel: Enabling Virtual Networking Virtual network interfaces on page 265 describes how virtual networking can be used to give each VMs a virtual network interface which share physical network interfaces in Linux. One common approach to configuring virtual networking is for QEMU to use a tun/tap interface bridged to a physical network interface. To do this Ethernet bridging and the kernel's tun/tap features must be enabled in the host kernel: Networking support ---> Networking options ---> <*> 802.1d Ethernet Bridging Device Drivers ---> [*] Network core driver support <*> Universal TUN/TAP device driver support In order to enable vhost-net, the following config option should ne enabled: [*] Virtualization <*> Host kernel accelerator for virtio net Guest Kernel: Enabling Network and Block Virtual I/O Virtio is a framework for doing paravirtualized I/O using QEMU/KVM. In order to support communication between guest and hypervisor virtio uses a PCI transport protocol. Below the kernel configuration options are shown to enable virtio-pci: Device Drivers ---> Virtio drivers ---> <*> PCI driver for virtio devices Below the kernel configuration options are shown to enable virtio drivers in the Linux kernel to support networking I/O and block (disk) I/O. Device Drivers ---> [*] Network device support ---> <*> Virtio network driver Device Drivers ---> [*] Block devices ---> <*> Virtio block driver 260 NXP Semiconductors

261 Virtualization KVM/QEMU Guest kernel: Enabling console QEMU emulates an AMBA/PL011 console. Below the kernel configuration options are shown to enable console: Device Drivers ---> Character devices ---> Serial drivers ---> <*> ARM AMBA PL011 serial port support [*] Support for console on AMBA serial port Building QEMU QEMU is a standard package in the QorIQ SDK and will be built for the following Yocto build configurations: fsl-image-virt fsl-image-full To add QEMU to another Yocto build configuration, edit the conf/local.conf file and add the IMAGE_INSTALL_append variable: IMAGE_INSTALL_append = " qemu" After a Yocto build is complete, the target root filesystem will contain the following QEMU components that are required for using KVM/QEMU: /usr/bin/qemu-system-arm /usr/bin/qemu-system-aarch64 # QEMU executable for ARMv7 platforms # QEMU executable for ARMv8 platforms QEMU can be built as an individual component in the Yocto environment as well, it's package name is "qemu". To clean and rebuild QEMU from the Yocto build environment: $ bitbake -c clean qemu $ bitbake qemu Creating a host Linux root filesystem Overview Creating a Linux root filesystem is out of the scope of this document. Please reference the NXP QorIQ SDK for more information on how to create root filesystems with Yocto. This section describes the software components needed on a root filesystem to use KVM/QEMU. The host root filesystem is the filesystem booted by the host kernel. The host rootfs is distinct from a guest root filesystem which may be needed by certain guest such as Linux. A host root filesystem capable of running Linux as a guest needs the following components: Guest Linux kernel image (Image or zimage). Note:Only zimage is supported for ARMv7 platforms. QEMU executable Guest root filesystem Dynamic libraries needed by QEMU (libfdt, libz, glib2.0). These libraries are standard components in a Yocto-created rootfs. Example host root filesystem layout with the required components to boot a Linux guest (excluding shared libraries): /root/zimage /root/rootfs.ext2.gz # guest Linux kernel # guest rootfs NXP Semiconductors 261

262 Virtualization KVM/QEMU /usr/bin/qemu-system-arm /usr/bin/qemu-system-aarch64 # QEMU for ARMv7 platforms # QEMU for ARMv8 platforms Adding Images to a Root Filesystem with Yocto If using Yocto, as described in Building QEMU on page 261, the root filesystem produced by the build process will contain QEMU and the example guest device trees provided by the SDK. A feature is also available with Yocto and the SDK to add arbitrary additional images to the root filesystem. This is done using the merge-files component in Yocto. Any files and directories copied to the "merge" directory (see path below) will be copied to the root filesystem created by Yocto: meta-freescale/recipes-extended/merge-files/merge-files/merge After populating the merge directory with the desired files, clean and rebuild the rootfs. See example below for the fsl-imagecore image type: $ bitbake -c install -f merge-files $ bitbake merge-files $ bitbake fsl-image-core See the how-to article Quick-start Steps to Build and Deploy KVM Using Yocto on page 271 for a more detailed example Using QEMU and KVM Overview of Using QEMU QEMU is used to start virtual machines and is built and included in the rootfs created by Yocto. The QEMU application is named qemu-system-arm (for 32 bit platforms) or qemu-system-aarch64 (for 64 bit platforms). In addition to the QEMU executable itself, the following is a list of the minimum components that must be available on the target system to launch a virtual machine using QEMU: The host Linux kernel on the target must be built with virtualization support for KVM enabled as described in Building Linux with KVM on page 257. A guest OS kernel image (e.g. zimage or Image for Linux) A guest root filesystem (If needed by the guest OS. For example, a Linux guest requires a rootfs.) Recommended: A working network interface (to interface to the guest's console and the QEMU monitor) See the article Quick-start Steps to Run KVM Using Hugetlbfs on page 273 for an example of how to boot a virtual machine with a rootfs created by Yocto. The QEMU Emulator User Documentation [1] (see References on page 256) contains complete documentation for all QEMU command line arguments. The Table below summarizes some of the flags and arguments for basic operation. Table 49. Argument -enable-kvm Descriptions Specifies that the Linux KVM should be used for the virtual machine's CPUs Table continues on the next page NXP Semiconductors

263 Virtualization KVM/QEMU Table 49. (continued) Argument -nographic Descriptions Disables graphical output-console will be on emulated serial port. -M machine Specifies the type of virtual machine. One value is supported: virt -smp cpu_count Specifies the number of CPUs for the virtual machine. The number of virtual CPUs allowed is the same as the value of the CONFIG_NR_CPUS config option in the host Linux kernel. To see this value issue the following command from Linux on the target board: zcat /proc/config.gz grep NR_CPUS -kernel file Specifies the guest OS image. The supported image types are in Image format (the generic Linux kernel binary image file) and zimage (a compressed version of the Linux kernel image) -initrd file -append cmdline -serial dev Specifies a root filesystem image Use cmdline as the guest OS kernel command line (passed in the bootargs property of the /chosen node in the guest device tree) Redirects the virtual serial port to the host device dev. QEMU supports many possible host devices. Please refer to the QEMU User Documentation [1] (see References on page 256) for complete details. Note: if using a tcp device with the server option QEMU will wait for a connection to the device before continuing unless the nowait option is used. -m megs Specifies the size of the VM's RAM in megabytes. This option is ignored if using direct mapped memory.. -mem-path path -monitor dev Specifies the path to a file from which to allocate memory for the virtual machine. This option should be used to allocate memory from hugetlbfs. Redirects the QEMU monitor to the host device dev. QEMU supports many possible host devices. Please refer to the QEMU User Documentation [1] (see References on page 256) for complete details. Note: if using a tcp device with the server option QEMU will wait for a connection to the device before continuing unless the nowait option is used. -S Do not start CPU at startup (you must type 'c' in the monitor). This can be useful if debugging. -gdb dev Wait for gdb connection on device dev Table continues on the next page... NXP Semiconductors 263

264 Virtualization KVM/QEMU Table 49. (continued) Argument -drive [args] -netdev [args] -device virtio-net-device [args] -cpu model Descriptions Used to create a virtual disk in a virtual machine.. The -netdev and -device virtio-net-device arguments specify the network backend and front end for createing virtual network devices in virtual machines. Select CPU model. Only one model is supported: host Below is an example command line a user would run from the host Linux to start virt virtual machine booting a Linux guest: ARMv7: qemu-system-arm -enable-kvm -m 512 -nographic -cpu host -machine type=virt -kernel /boot/zimage - serial tcp::4446,server,telnet -initrd /boot/guest.rootfs.ext2.gz -append 'root=/dev/ram0 rw console=ttyama0 rootwait earlyprintk' -monitor stdio ARMv8: qemu-system-aarch64 -enable-kvm -m 512 -nographic -cpu host -machine type=virt -kernel /boot/image -serial tcp::4446,server,telnet -initrd /boot/guest.rootfs.ext2.gz -append 'root=/dev/ram0 rw console=ttyama0 rootwait earlyprintk' -monitor stdio Virtual Machine Memory QEMU allocates and loads images into a VM's memory prior to starting the VM. The amount of memory needed for a virtual machine will be dependent on the workload to be run in the VM. There are two ways to allocate memory: 1. Allocation via hugetlbfs Hugetlbfs is a Linux mechanism that allows applications to allocate memory backed large physically contiguous regions of memory. QEMU can take advantage of hugetlbfs for allocation of memory for virtual machines, which can provide a significant performance improvement over malloc allocated memory. Hugetlbfs allocated memory provides the flexibility of memory that can be allocated and freed with performance comparable to direct mapped memory. The 32 bit ARMv7 implementation in Linux supports 2MB sized huge pages. The 64 bit ARMv8 implementation in Linux supports 2MB and 1GB sized huge pages (for 4K granularity page size). The -mem-path argument to QEMU specifies the path to the hugetlbfs mount point where the huge pages should be allocated from. The -m argument to QEMU specifies the amount of memory to allocate to the virtual machine. There are no constraints on the size passed to this argument other than that the amount of memory must fit within the constraints of the system and be enough for the workload in the VM. See the how-to article Quick-start Steps to Run KVM Using Hugetlbfs on page 273 for an example of how to use hugetlbfs. 2. Allocation via malloc The default for QEMU is to allocate guest memory by the standard malloc facility available to user space applications in Linux. The amount of memory is specified with the -m command line argument. Malloc'ed memory has the flexibility of being allocated and freed by QEMU as needed. However, malloc'ed memory is backed by 4KB physical pages that are not contiguous and emulation is required by KVM to present a contiguous guest physical memory region to the VM. This approach is discouraged since the emulation can result in a substantial performance penalty for certain workloads. 264 NXP Semiconductors

265 Virtualization KVM/QEMU The guest device tree generated by QEMU will contain a memory node that specifies the total amount of memory. NOTE A virtual machine's memory is part of the address space of the QEMU process. This means that the amount of memory allocated to a VM is limited by the standard limits that exist for Linux processes. A 32-bit host kernel has a 2GiB virtual address space used for stack, text, and other data, and this limits the amount of memory that can be allocated to a VM Virtual network interfaces QEMU provides a number of options for creating virtual network interfaces in virtual machines. Virtual network interfaces are specified using the QEMU command line and guest software sees them as memory mapped devices. There are two aspects of virtual network interfaces with QEMU: 1. The network front-end, which is the network card as seen by the guest. This is specified with the -device QEMU argument. The argument to specify a virtio network front end would look like: -device virtio-net-pci 2. The network "backend", which connects the network card to some network. Network backend options include user mode networking, a host TAP interface, sockets, or virtual distributed Ethernet. The network backend is specified using the - netdev command line argument of QEMU. Note: It is possible to connect two virtual machines using virtual network interfaces. Normally QEMU userspace process emulates I/O accesses from the guest. However, there is an in-kernel implementation: vhost-net which puts the data plane emulation code into the kernel. For example, to use a virtio NIC card with a TAP interface back-end the QEMU command line argument would look like: -netdev tap,id=tap0,script=/root/qemu-ifup -device virtio-net-pci,netdev=tap0 The script /root/qemu-ifup is a script that QEMU invokes and passes the TAP interface name as an argument. For example, the script could add the TAP interface to an Ethernet bridge. See the QEMU Users Manual [1] (see References on page 256) for detailed information about command line options and the types of network interfaces and backends. For best performance, the virtio front-end is recommended. For additional information about QEMU networking see the references in For More Information on page 257. For a detailed example, see the how-to article How to Use Virtual Network Interfaces Using Virtio on page VMs and the Linux Scheduler Each virtual machine appears to the host Linux as a process with each virtual CPU in the VM implemented as a thread. A VM appears as an instance of QEMU when looking at Linux processes as can be seen in the example below: $ ps -ef o o root Oct01 ttys0 00:00:00 -sh root :24? 00:00:00 [kworker/u4:2] root :27 ttys0 00:00:17 qemu-system-arm -enable-kvm -m root :28? 00:00:00 sshd: root@pts/0 root :28 pts/0 00:00:00 -sh o o CPUs appear as threads. To see thread IDs use the info cpus command in the QEMU monitor. Example of a VM with 8 virtual CPUs: (qemu) info cpus * CPU #0: thread_id=1984 NXP Semiconductors 265

266 Virtualization KVM/QEMU CPU #1: (halted) thread_id=1985 CPU #2: (halted) thread_id=1986 CPU #3: (halted) thread_id=1987 CPU #4: (halted) thread_id=1988 CPU #5: (halted) thread_id=1989 CPU #6: (halted) thread_id=1990 CPU #7: (halted) thread_id=1991 To see the QEMU threads using the ps command: ps -el grep qemu ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar ttys1 00:00:00 qemu-system-aar Being a Linux thread means that standard Linux mechanisms can be used to control aspects of how the threads are scheduled relative to other threads/processes. These mechanisms include: process priority CPU affinity isolcpus cgroups Virtual machine reference VM Overview In general the architecture of KVM/QEMU is such that few changes should be needed to guest software to run in a VM-- i.e. a full virtualization approach is used, which means that virtual CPUs and virtual I/O devices behave like the physical hardware they are emulating. However, there are some differences between virtual machines and native hardware that should be considered when targeting an OS to a KVM virtual machine. These differences can be divided into 2 general categories that will be discussed in further detail in this section: 1. Initial state and boot 2. CPUs Memory Map of Virtual I/O Devices The virt virtual machine contains a small subset of the devices found on an SoC. The available devices will be represented in the device tree passed to the guest at boot. See the table below for a summary of the virtual I/O devices in the virt VM: 266 NXP Semiconductors

267 Virtualization KVM/QEMU Table 50. Virtual I/O Devices for virt machine virt VM Address, size 0,128MB Descriptions space for a flash device (this allows running bootrom code) 0x , 0x20000 Virtual CPU peripherals (including GIC distributor and CPU peripheral space) 0x , 0x10000 Virtual GIC distributor 0x , 0x10000 Virtual GIC CPU interface 0x , 0x10000 Virtul GICv2m controller 0x , 0x10000 Virtual UART 0x , 0x10000 Virtual RTC 0x0a x0a0001ff Virtual MMIO... Virtual MMIO 0x0c000000, 0x Virtual platform bus 0x , 0x virtual PCIE 0x , 30G guest RAM Virtual machine state at initialization Initial State and Boot When booting the Host, kernel is entered into the HYP mode for ARMv7 respectively EL2 privillege level for ARMv8. After the boot the kernel uses a stub to install KVM and switches back to SVC, respectively EL1. The virtual machine has no virtualization extensions available, so the guest kernel will be entered in SVC mode (ARMv7) respectively EL1 (ARMv8). In case of a real hardware the boot program will provide some services before giving control to the OS. The necessary steps needed to be done by the bootloader are described in the kernel documentation: Documentation/arm/Booting/ (ARMv7), Documentation/arm64/booting.txt (ARMv8). In case of virtualization, KVM/QEMU makes the necessary actions to put hardware into the initial state (as seen by the guest) and also will take the role of the bootloader and makes the necessary settings. QEMU also installs a very simple bootloader which just set some registers and after that it jumps to the kernel. It is recommended that a guest OS be minimally device tree aware. The libfdt library (available with the DTC tool) provides a full range of APIs to parse and manipulate device trees and will make the process of adding device tree awareness to an OS straightforward Initial State of Virtual CPUs In a VM with multiple virtual CPUs, CPU #0 is the boot CPU and all other vcpus in the partition are considered secondary. The boot method for the secondary CPUs is PSCI. The virtual CPU entry conditions comply with the entry conditions specified by linux/documentation/arm/booting (ARMv7) or Documentation/ arm64/booting.txt (ARMv8) The virtual CPU state is summarized below: ARMv7: R0 = 0 NXP Semiconductors 267

268 Virtualization KVM/QEMU R1 = machine type number R2 = physical address of device tree block (DTB) in system RAM MMU off data cache off CPSR: 0x000001d3 (SVC mode, asynchronous abort, IRQ and FIQ masked) ARMv8: x0 = physical address of device tree blob (dtb) in system RAM. x1 = 0 x2 = 0 x3 = 0 MMU off Virtual CPUs Virtual CPU Specification Software running in a virtual machine sees a virtual CPU that emulates an ARMv7/ARMv8 core without virtualization extensions. The virtual CPU type will match that of the host hardware platform Time in the Virtual CPU ARM architecture has an optional extension, the generic timers, which provides: a counter (physical counter) that measures passing of time in real time a timer (physical timer) for each CPU. The timer is programmed to raise an interrupt to the CPU after a certain amount of time has passed. The generic timers include virtualization support by introducing: a new counter, the virtual counter a new timer, the virtual timer. This allows the virtual machine to have direct access to reading (virtual) counters and programming (virtual) timers without trapping. KVM uses the physical timers in the host, the virtual machine access to the physical timers being disabled. The virtual machine accesses the virtual timer and can, in this way, directly access the timer hardware without trapping to the hypervisor. However, the virtual timers do not raise virtual interrupts, but hardware interrupts which trap to the hypervisor. KVM injects a corresponding virtual interrupt into the VM when it detects that the virtual timer expired VGIC The ARM Generic Interrupt Controller (GIC) provides hardware support for virtualization. The guest is able to mask, acknowledge and EOI interrupts without trapping to the hypervisor. However, there is a central part of the GIC called distributor which is responsible for interrupt prioritization and distribution to each CPU which does not provide virtualization extensions and for this part KVM provides an in-kernel emulation. Also, all the physical interrupts cannot be directly received by the guest. Instead, the KVM will program a virtual interrupt which will be raised in the guest. But, with the virtualization support in the GIC controller, when the guest is ACK-ing and EOI-ing the virtual interrupt, there is no need to trap into KVM. 268 NXP Semiconductors

269 Virtualization KVM/QEMU Debugging virtual machines QEMU Monitor When starting QEMU, a monitor shell is available that can be used to control and see the state of VM. By default this monitor is started in the Linux shell where QEMU is invoked. See example below of the output when starting QEMU. The user can interact with the monitor at the (qemu) prompt. QEMU monitor - type 'help' for more information (qemu) QEMU waiting for connection on: disconnected:telnet::4446,server The monitor can also be exposed over a network port by using the -monitor dev command line option. See Overview of Using QEMU on page 262 and the QEMU user's manual [1] (see References on page 256). Refer to the QEMU user's manual [1] for a complete listing of the monitor commands available. Below is a list of some useful commands supported in the NXP SDK implementation of QEMU: help - lists all the available commands with usage information info cpus - displays the state and thread ID of all virtual CPUs info registers - displays the contents of the default vcpu's registers cpu cpu_number - sets the default vcpu number system_reset - resets the VM x/fmt addr -- virtual memory dump starting at 'addr' xp/fmt addr -- physical memory dump starting at 'addr' QEMU GDB Stub QEMU supports debugging of a VM using gdb. QEMU contains a gdb stub that can be attached to from a host system and allows standard source level debugging capabilities to examine the state of the VM and do run control. NXP Semiconductors 269

270 Virtualization KVM/QEMU Figure 25. To use the gdb stub, start QEMU with the -gdb dev option where dev specifies the type of connection to be used. See the QEMU user's manual [1] (see References on page 256) for details. One useful option when debugging is the -S argument to QEMU which causes QEMU to wait to start the first instruction of the guest until told to start using the monitor (continue command). In the example below the tcp device type is used. A gdb stub will be active on port 4445 of the host Linux kernel when starting QEMU: $ qemu-system-arm -enable-kvm -m 512 -mem-path /var/lib/hugetlbfs/pagesize-2mb -nographic -cpu host -machine type=virt -kernel /boot/zimage -serial tcp::4446,server,telnet -initrd /boot/fslimage-core-ls1021atwr.ext2.gz -append 'root=/dev/ram0 rw console=ttyama0 rootwait earlyprintk' - monitor stdio -gdb tcp::4445 QEMU monitor - type 'help' for more information (qemu) QEMU waiting for connection on: telnet: :4446,server After the guest has been started normally, gdb can be used to connect to the VM (in this example the host kernel has an ip address of ): (gdb) target remote :4445 Remote debugging using :4445 0x80024f44 in?? () Debugging with gdb can then proceed normally: (gdb) p/x $r15 $2 = 0x80024f44 (gdb) 270 NXP Semiconductors