NXP Semiconductors Document Number: QORIQLS1012ASDK04 Rev. 0, Aug 2016 QorIQ LS1012A SDK v0.4 Contents
Contents
Chapter 1 SDK Overview...... 8 1.1 What's New...... 8 1.2 Components...... 8 1.3 Known Issues...... 9
Chapter 2 Getting Started...... 11 2.1 Yocto SDK File System Images...... 11 2.1.1 fsl-image-minimal...... 11 2.1.2 fsl-image-mfgtool...... 11 2.1.3 fsl-image-full...... 12 2.1.4 fsl-image-core...... 12 2.1.5 fsl-image-virt...... 13 2.2 Essential Build Instructions...... 13 2.2.1 Install the SDK...... 13 2.2.2 Host Environment...... 14 2.2.3 Setup Poky...... 15 2.2.4 Builds...... 15 2.3 Additional Instructions for Developers...... 16 2.3.1 Customizing U-Boot...... 16 2.3.2 Customizing Linux Kernel...... 17 2.3.3 Patching Packages...... 18 2.3.4 Extract Source Code...... 19 2.3.5 Customize Root Filesystem...... 19 2.3.6 Native Packages...... 20 2.3.7 Standalone Toolchain...... 20 2.3.8 Shared State(sstate) Cache ...... 21 2.3.9 Yocto FAQ...... 21 2.3.10 BitBake User Manual...... 23
Chapter 3 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB)...... 24 3.1 Introduction...... 24 3.2 Basic Host Set-up...... 24 3.3 Target Board Set-up...... 25 3.4 Optimzing Boot Flow (Fast Boot)...... 27 3.5 Boards...... 28 3.5.1 LS1012ARDB...... 29 3.5.1.1 Overview...... 29 3.5.1.2 Switch Settings...... 29 3.5.1.3 U-Boot Environment Variables...... 29 3.5.1.3.1 U-Boot Environment Variable "hwconfig"...... 29 3.5.1.3.2 Configuring U-Boot Network Parameters...... 30 3.5.1.4 RCW (Reset Configuration Word) and Ethernet Interfaces...... 30 3.5.1.5 System Memory Map...... 30 3.5.1.6 Flash Bank Usage...... 31 3.5.1.7 Programming a New U-Boot and RCW...... 32 3.5.1.8 Deployment...... 33
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 2 NXP Semiconductors Contents
3.5.1.8.1 Ramdisk Deployment from TFTP...... 33 3.5.1.8.2 Ramdisk Deployment from Flash...... 34 3.5.1.8.3 NFS Deployment...... 34 3.5.1.8.4 SD Deployment...... 35 3.5.1.9 Check 'Link Up' for Serial Ethernet Interfaces...... 36 3.5.1.10 Basic Networking Ping Test...... 37 3.5.2 FRDM-LS1012A...... 42 3.5.2.1 Switch Settings...... 42 3.5.2.2 U-Boot Environment Variables...... 42 3.5.2.2.1 U-Boot Environment Variable "hwconfig"...... 42 3.5.2.2.2 Configuring U-Boot Network Parameters...... 43 3.5.2.3 RCW (Reset Configuration Word) and Ethernet Interfaces...... 43 3.5.2.4 System Memory Map...... 43 3.5.2.5 Flash Bank Usage...... 44 3.5.2.6 Programming a New U-Boot and RCW...... 45 3.5.2.7 Deployment...... 45 3.5.2.7.1 Ramdisk Deployment from TFTP...... 46 3.5.2.7.2 Ramdisk Deployment from Flash...... 46 3.5.2.7.3 NFS Deployment...... 47 3.5.2.8 Check 'Link Up' for Serial Ethernet Interfaces...... 48 3.5.2.9 Basic Networking Ping Test...... 48
Chapter 4 System Recovery...... 53 4.1 Environment Setup...... 53 4.1.1 Environment Setup (Common)...... 53 4.2 Image Recovery...... 53 4.2.1 Recover system with already working U-Boot...... 53 4.2.2 Recover system using CodeWarrior Flash Programmer...... 54
Chapter 5 About Yocto Project...... 57 5.1 Yocto Project Quick Start...... 57 5.2 Application Development Toolkit User's Guide...... 57 5.3 Board Support Packages - Developer's Guide...... 57 5.4 Yocto Project Development Manual...... 57 5.5 Yocto Project Linux Kernel Development Manual...... 57 5.6 Yocto Project Profiling and Tracing Manual...... 58 5.7 Yocto Project Reference Manual...... 58
Chapter 6 Linux Kernel Drivers...... 59 6.1 Audio...... 59 6.1.1 SAI User Manual LS1012A...... 59 6.2 DMA Controller ...... 61 6.2.1 Enhanced Direct Memory Access Driver (ARM)...... 61 6.2.1.1 eDMA User Manual...... 61 6.3 Enhanced Secured Digital Host Controller (eSDHC)...... 64 6.3.1 eSDHC Driver User Manual...... 64 6.4 PCI Express Interface Controller...... 69 6.4.1 PCIe Linux Driver...... 69 6.4.2 EDAC Driver User Manual...... 72 6.4.3 PCIe Advanced Error Reporting User Manual...... 75 6.4.4 PCIe Remove and Rescan User Manual...... 77 6.4.5 PCIe Endpoint User Manual...... 78
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 3 Contents
6.5 Packet Forward Engine (PFE) Network Driver...... 83 6.5.1 Introduction...... 83 6.5.1.1 Overview...... 83 6.5.1.2 Purpose...... 83 6.5.1.3 Features...... 83 6.5.2 High level decomposition and data flow...... 83 6.5.3 NAPI support...... 85 6.5.4 Interrupt coalescing...... 85 6.5.5 Checksum offloading...... 85 6.5.6 Scatter gather support...... 85 6.5.7 Ethtool support...... 85 6.6 Real Time Clock (off-chip)...... 86 6.6.1 RTC Driver User Manual (Linux BSP)...... 86 6.7 SATA Controller...... 88 6.7.1 External SATA Controller User Manual...... 88 6.7.2 NXP Native SATA User Manual...... 94 6.8 Serial Peripheral Interface...... 97 6.8.1 QuadSPI Driver for TWR-LS1021A User Manual...... 97 6.8.1.1 QuadSPI Driver User Manual...... 97 6.9 Universal Serial Bus Interfaces...... 99 6.9.1 USB 2.0 Host Driver...... 99 6.9.1.1 USB 2.0 Host Driver User Manual...... 99 6.9.2 USB Gadget Memory Driver User Manual...... 111 6.9.2.1 USB Gadget for Memory Devices...... 111 6.9.3 USB Gadget Network Driver User Manual...... 117 6.9.3.1 USB Gadget for Network Devices...... 117 6.9.4 USB 3.0 Host/Peripheral Linux Driver User Manual...... 121 6.9.4.1 USB 3.0 Host/Peripheral Linux Driver User Manual...... 121 6.10 Watchdog Timers...... 131 6.10.1 Watchdog Device Driver User Manual LS1012A...... 131
Chapter 7 Additional Linux Use Cases...... 136 7.1 Power Management...... 136 7.1.1 Power Management User Manual...... 136 7.1.2 CPU Frequency Switching User Manual...... 138 7.1.3 System Monitor...... 142 7.1.3.1 Power Monitor User Manual...... 142 7.1.3.2 Thermal Monitor User Manual...... 147 7.1.3.3 Web-based System Monitor User Guide...... 148 7.2 Real Time Application Note...... 150 7.2.1 Real Time Application Note...... 150
Chapter 8 Linux User Space...... 153 8.1 OpenSSL Offload User's Guide...... 153 8.1.1 Overview...... 153 8.1.1.1 OpenSSL Software architecture...... 153 8.1.1.1.1 OpenSSL’s ENGINE Interface...... 154 8.1.1.1.2 NXP solution for OpenSSL hardware offloading ...... 154 8.1.2 Building OpenSSL with hardware offloading support...... 155 8.1.3 Nginx offloading with OpenSSL...... 155 8.1.4 Valid TLS Ciphersuites based on TLS protocol version...... 157
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 4 NXP Semiconductors Contents
Chapter 9 Boot Loaders...... 163 9.1 Primary Protected Application (PPA) User's Guide...... 163 9.1.1 Introduction...... 163 9.1.1.1 Rationale and Scope...... 163 9.1.1.2 References...... 163 9.1.1.3 Definitions...... 164 9.1.2 Boot Flow Architecture...... 164 9.1.2.1 LS1043A/LS1012A Boot Flow...... 164 9.1.3 Loading and Initializing the PPA...... 167 9.1.4 How to Call SMC/PSCI functions...... 167 9.1.5 PSCI Function List...... 168 9.1.5.1 PSCI_VERSION...... 168 9.1.5.2 CPU_ON...... 169 9.1.5.3 CPU_OFF...... 169 9.1.5.4 CPU_SUSPEND...... 170 9.1.5.5 AFFINITY_INFO...... 170 9.1.5.6 SYSTEM_OFF...... 171 9.1.5.7 SYSTEM_RESET...... 171 9.1.5.8 PSCI Return Code Values...... 171 9.1.5.9 PSCI Functions Implemented, by SoC...... 172 9.1.6 SMC Function List...... 172 9.1.6.1 Function Count - SMC64...... 172 9.1.6.2 Function Count - SMC32...... 173 9.1.6.3 Get UUID...... 173 9.1.6.4 Get Revision...... 173 9.1.7 Building the PPA...... 174 9.1.8 System Considerations When Calling SMC & PSCI Functions...... 174 9.2 Secure Boot: PBL Based Platforms...... 175 9.2.1 Introduction...... 175 9.2.2 Secure Boot Process...... 176 9.2.3 Pre-Boot Phase...... 177 9.2.4 ISBC Phase...... 179 9.2.4.1 Flow...... 179 9.2.4.2 SRKs...... 180 9.2.4.3 Key Revocation...... 180 9.2.4.4 Alternate Image support...... 181 9.2.4.5 ESBC with CSF Header...... 181 9.2.5 ESBC Phase...... 181 9.2.5.1 Boot script...... 182 9.2.5.1.1 Where to place the boot script?...... 182 9.2.5.1.2 Chain of Trust...... 182 9.2.5.1.3 Chain of Trust with Confidentiality...... 184 9.2.6 Next Executable Phase...... 187 9.2.7 CST Tool...... 187 9.2.7.1 KEY GENERATION...... 187 9.2.7.1.1 gen_keys...... 187 9.2.7.1.2 gen_drv_drbg...... 189 9.2.7.1.3 gen_otpmk_drbg...... 190 9.2.7.2 CSF HEADER GENERATION...... 191 9.2.7.2.1 Default Usage...... 192 9.2.7.2.2 Verbose Mode...... 195 9.2.7.2.3 Public Key/ SRK Hash Generation Only...... 196 9.2.7.2.4 Key Extension...... 196
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 5 Contents
9.2.7.2.5 Image Hash Generation...... 203 9.2.7.2.6 Help...... 204 9.2.7.3 Code Signing Tool Walkthrough...... 204 9.2.8 Product execution...... 206 9.2.8.1 Getting started...... 206 9.2.8.1.1 Environment for Secure Boot...... 206 9.2.8.1.2 SDK Images required for the demo...... 206 9.2.8.2 Chain of Trust...... 207 9.2.8.2.1 Other Images Required for demo...... 207 9.2.8.2.2 Bootscript and Signing the images...... 207 9.2.8.2.3 Running secure boot (Chain of Trust)...... 211 9.2.8.3 Chain of Trust with Confidentiality...... 212 9.2.8.3.1 Other Images Required for demo...... 213 9.2.8.3.2 Encap Bootscript...... 213 9.2.8.3.3 Decap Bootscript...... 213 9.2.8.3.4 Creating CSF Headers...... 214 9.2.8.3.5 Running secure boot (Chain of Trust with Confidentiality)...... 214 9.2.8.4 NAND Secure Boot (Chain of Trust)...... 216 9.2.8.4.1 Running NAND Secure boot (Chain of Trust)...... 216 9.2.8.5 NAND Secure Boot (Chain of Trust with Confidentiality)...... 218 9.2.8.5.1 Running NAND Secure boot (Chain of Trust with Confidentiality)...... 219 9.2.9 Troubleshooting...... 221 9.2.10 CSF Header Data Structure Definition...... 221 9.2.11 ISBC Validation error codes...... 239 9.2.12 ESBC Validation error codes...... 244 9.2.13 Address Map used for demo...... 246 9.2.14 Useful U-Boot and CCS Commands...... 253 9.2.15 Trust Architecture and SFP Information...... 259 9.2.16 QCVS Tool Usage...... 259
Chapter 10 Virtualization...... 266 10.1 KVM/QEMU...... 266 10.1.1 KVM/QEMU Release Notes...... 266 10.1.2 KVM for ARM Architecture Users Guide and Reference...... 266 10.1.2.1 Introduction to KVM and QEMU...... 266 10.1.2.1.1 Overview...... 266 10.1.2.1.2 Organization of this Document...... 267 10.1.2.1.3 Virtual Machine Overview...... 268 10.1.2.1.4 Introduction to KVM and QEMU...... 268 10.1.2.1.5 Device Tree Overview...... 270 10.1.2.1.6 References...... 270 10.1.2.1.7 For More Information...... 271 10.1.2.2 Building QEMU and KVM...... 271 10.1.2.2.1 Overview...... 271 10.1.2.2.2 Building Linux with KVM...... 271 10.1.2.2.3 Building QEMU...... 274 10.1.2.2.4 Creating a host Linux root filesystem...... 275 10.1.2.3 Using QEMU and KVM...... 276 10.1.2.3.1 Overview of Using QEMU...... 276 10.1.2.3.2 Virtual Machine Memory...... 278 10.1.2.3.3 Virtual network interfaces...... 278 10.1.2.3.4 VMs and the Linux Scheduler...... 279 10.1.2.4 Virtual machine reference...... 280 10.1.2.4.1 VM Overview...... 280
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 6 NXP Semiconductors Contents
10.1.2.4.2 Memory Map of Virtual I/O Devices...... 280 10.1.2.4.3 Virtual machine state at initialization...... 281 10.1.2.4.4 Virtual CPUs...... 281 10.1.2.4.5 VGIC...... 282 10.1.2.5 Debugging virtual machines...... 282 10.1.2.5.1 QEMU Monitor...... 282 10.1.2.5.2 QEMU GDB Stub...... 283 10.1.2.6 KVM/QEMU How-to's...... 284 10.1.2.6.1 Quick-start Steps to Build and Deploy KVM Using Yocto...... 284 10.1.2.6.2 Quick-start Steps to Run KVM Using Hugetlbfs...... 286 10.1.2.6.3 How to Use Virtual Network Interfaces Using Virtio...... 288 10.1.2.6.4 How to use vhost-net with virtio...... 289 10.1.2.6.5 Debugging: How to Examine Initial Virtual Machine State with QEMU...... 290 10.1.2.6.6 Debugging: How to Profile Virtualization Overhead with KVM...... 291
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 7 SDK Overview What's New Chapter 1 SDK Overview
1.1 What's New NXP Digital Networking is pleased to announce the release of Linux SDK for LS1012A, v0.4 supporting LS1012A rev1.0 processor on RDB and FRDM boards. This is the follow on release to SDK v0.3 release. The additional functionalities supported in this release are Real Time and ARM v8 32 Bit Support. 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-r2015.06, glibc-linaro-2.20-r2014.11, binutils-linaro-2.25-r2015.01, gdb-7.10.1
U-Boot Boot Loader • U-Boot 2016.01 • ARMv8 core • 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 4.1.8 • 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 • Crypto driver supporting SEC 5 (CAAM)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 8 NXP Semiconductors SDK Overview Known Issues
• 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-5875 On running Open LS1012A SDK pistress test tool, v0.4 some rcu related call trace might be observed
QLINUX-5876 The kernel Call Open LS1012A SDK Trace when testing v0.4 ce_sec_tcrypto_a es.
QUBOOT-1737 If code warrior is Open LS1012A SDK Use Code-Warrior used to program u- v0.3 to program the 64 boot or RCW, the MB SDK image flash gets into (LS1012) thereby invalid state. programming the entire flash. After power recycle, the board will start functioning.
QUBOOT-1691 USB 3.0 USB Open LS1012A SDK Harddisk v0.3 enumeration issue is faced with certain disks
QSDK-2982 Inconsistent Open LS1012A SDK behavior while v0.3 reading QSPI using U-boot cmds "sf read" and "md" commands
QLINUX-5849 Jumbo frame Open LS1012A SDK floodping will v0.3 cause the Call Trace.
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 9 SDK Overview Known Issues
Table continued from the previous page...
QLINUX-5831 Power off Resolved LS1012A SDK LS1012A SDK command in Linux v0.3 v0.4 causes kernel crash
QLINUX-5768 LS1012:rmmod of Open LS1012A SDK PFE modules v0.2 crashes the kernel
QLINUX-5767 LS1012A: RDB/ Resolved LS1012A SDK LS1012A SDK FRDM:Not able to v0.2 v0.3 transfer more than 32 MB of file via tftp in Linux.
QLINUX-5764 caam driver / pkc / Resolved LS1012A SDK LS1012A SDK v0.2 v0.3 rsa operation fail
QLINUX-5756 The kernel bootup Resolved LS1012A SDK LS1012A SDK failed when the v0.2 v0.3 pagesize was 64K but 4K pagesize passed
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 10 NXP Semiconductors 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.
2.1 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. 2.1.1 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. It does not contain NXP special SDK packages such as USDPAA, etc. 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.
2.1.2 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. It does not contain NXP special SDK packages such as USDPAA, etc. 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 11 Getting Started SDK File System Images
NXP preloads “fsl-image-full” (see below) onto disks on development boards that have them. For these boards, “fsl-image- mfgtool” can be used to restore the larger disk image if it becomes corrupted. 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)
2.1.3 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. It contains all of the special NXP SDK packages such as USDPAA, etc. 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-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/Poky-derived embedded distribution. However, the Yocto 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.
2.1.4 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 such as USDPAA, etc. Purpose:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 12 NXP Semiconductors Getting Started Essential Build Instructions
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”. 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.
2.1.5 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_
$ sudo mount -o loop LS1012A-SDK-
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 13 Getting Started Essential Build Instructions
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.
2.2.2 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-2.7.3 or greater(excluding python3 which is not supported), git-1.7.8 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 2.6.6. 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 https://www.python.org/ftp/python/2.7.6/Python-2.7.6.tar.xz [NOTE: Python 2.7.3 and python 2.7.5 can be used as well.] $ tar -xf Python-2.7.6.tar.xz $ cd Python-2.7.6 $ ./configure --prefix=/opt/python-2.7.6 $ 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-7.1.1503,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/meta- yocto/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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 14 NXP Semiconductors Getting Started Essential Build Instructions
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
2.2.3 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
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
2.2.4 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
Where
• 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 15 Getting Started Additional Instructions for Developers
• 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: A Yocto build produces images that will be located in the following directory:
The following list shows the typical directory/image files (exact contents depend on the setting of the
• fsl-image-
• fsl-image-
• fsl-image-
• kernel-
• Image-
• u-boot-
• Image-
• 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. 2.3.1 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
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 16 NXP Semiconductors Getting Started Additional Instructions for Developers
NOTE Other helpful bitbake cleaning commands:
bitbake -c clean
• Removes work directory in build_
bitbake -c cleansstate
• Removes work directory in build_
• Removes cache files in
2. $ bitbake -c patch u-boot
3. $ cd and modify the source code
NOTE Use bitbake -e u-boot | grep ^S= to get value of .
To Rebuild U-Boot Image:
1. $ cd build_
2. $ bitbake -c compile -f u-boot
3. $ bitbake u-boot
NOTE U-Boot image can be found in build_
2.3.2 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 and change the source code
NOTE Use bitbake -e .
2. Change the kernel defconfig
a. $ update KERNEL_DEFCONFIG variable in meta-freescale/conf/machine/
a. $ update KERNEL_DEVICETREE variable in meta-freescale/conf/machine/
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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 17 Getting Started Additional Instructions for Developers
NOTE This runs the normal kernel menuconfig within the Yocto environment. If the kernel configure UI cannot open, edit /
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"
5. Rebuild Kernel image
a. $ cd build_
c. $ bitbake virtual/kernel
NOTE Kernel images can be found in build_
2.3.3 Patching Packages How to Patch and Rebuild a Package
1. $ cd
2. $ bitbake -c cleansstate
3. $ cd
NOTE Use bitbake
4. $ mkdir -p
5. Copy patch into
6. Modify
SRC_URI += "file://
7. Rebuild this package:
$ bitbake
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 18 NXP Semiconductors Getting Started Additional Instructions for Developers 2.3.4 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
2. $ bitbake -c patch
3. $ cd
NOTE Use bitbake -e .
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/ls1012afrdm- fsl-linux/u-boot-qoriq/2016.01+git-r0/
2.3.5 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 19 Getting Started Additional Instructions for Developers
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_
If
$ bitbake
2.3.6 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
NOTE The binaries can be found in build_
2.3.7 Standalone toolchain
Build and install the standalone toolchain with Yocto: 1. $ . ./fsl-setup-env -m
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-
To invoke the compiler, use the $CC variable (eg. $CC
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/
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 20 NXP Semiconductors Getting Started Additional Instructions for Developers 2.3.8 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 (sstate- cache), as pointed to by SSTATE_DIR. 1. Use the following setting in local.conf:
SSTATE_DIR="
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.
2.3.9 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:
1. $ cd
• $ bitbake -c patch
• $ cd and do change
NOTE Use bitbake -e .
3. Modify configure (dts can also be modified):
• Modify the UBOOT_CONFIG variable in meta-freescale/conf/machine/
• $ cd
• $ bitbake -c compile -f
• $ bitbake
NOTE u-boot.bin, Image and dtb files can be found in build_
Or set
Q: How to build u-boot/kernel with debugger (CodeWarrior support)? A: For u-boot:
1. $ cd
2. $ bitbake -c cleansstate u-boot
3. Modify the u-boot-qoriq_
• $ cd meta-freescale/recipes-bsp/u-boot
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 21 Getting Started Additional Instructions for Developers
• $ add 'EXTRA_OEMAKE += "CONFIG_CW=1"' in u-boot-qoriq_
• $ bitbake u-boot For kernel:
1. $ cd
• $ 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
NOTE Use bitbake -e
Q: How to display packages which are included in current rootfs image? A: There are three methods :
• $hob
• $bitbake -e
• $bitbake -g
1. $ cd
• $ 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 22 NXP Semiconductors Getting Started Additional Instructions for Developers
1. $bitbake fsl-toolchain
NOTE fsl-qoriq-glibc-x86_64-
NOTE fsl-qoriq-glibc-x86_64-
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
2.3.10 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 (www.openembedded.org), 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 http://docs.openembedded.org/ bitbake
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 23 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) and Development System (DS). The guide starts with generic host and target board pre-requisites. This is followed by board- specifc configuration: • Switch Settings • U-Boot environment Variables • Frame Manager Microcode (if applicable) • 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 flash bank, the "Programming a New U-Boot, RCW, FMan Microcode" section describes how the user can individually or simultaneously update U-Boot, RCW, and FMan microcode by flashing them to the board's alternate bank 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:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 24 NXP Semiconductors 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
3. Use Yocto to generate a tar.gz type file system, and uncompress it in
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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 25 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 2016.01LS1012A-SDK+g7944a94 (Aug 27 2016 - 04:43:01 +0800)
SoC: LS1012AE (0x87040010) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): 00000000: 08000008 00000000 00000000 00000000 00000010: 33050000 c000000c 40000000 00001800 00000020: 00000000 00000000 00000000 000c4571 00000030: 00000000 00c28120 00000096 00000000 I2C: ready DRAM: 510 MiB Using SERDES1 Protocol: 13061 (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: 0000000004000000, ddr_baseaddr: 0000000083800000, ddr_phys_baseaddr: 03800000 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: 0000000083e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: 0000000083e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: 0000000083e40400, 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 53.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 26 NXP Semiconductors 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 96000000 ... Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0x9600013c Data Size: 12502016 Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x80080000 Entry Point: 0x80080000 ## Loading ramdisk from FIT Image at 96000000 ... Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0x96bef354 Data Size: 24512880 Bytes = 23.4 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at 96000000 ... Using 'config@1' configuration Trying 'fdt@1' fdt subimage
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 27 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
Description: Flattened Device Tree blob Type: Flat Device Tree Compression: uncompressed Data Start: 0x96bec5f0 Data Size: 11490 Bytes = 11.2 KiB Architecture: AArch64 Loading fdt from 0x96bec5f0 to 0x90000000 Booting using the fdt blob at 0x90000000 Loading Kernel Image ... OK Using Device Tree in place at 0000000090000000, end 0000000090005ce1
Starting kernel ...
[ 0.000000] Booting Linux on physical CPU 0x0 [ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Linux version 4.1.8-rt8+g19202f1 (jenkins@neptune) (gcc version 4.9.4 20150629 (prerelease) (Linaro GCC 4.9-2015.06) ) #1 SMP Mon Aug 22 04:38:44 CST 2016 [ 0.000000] CPU: AArch64 Processor [410fd034] revision 4 [ 0.000000] Detected VIPT I-cache on CPU0 [ 0.000000] alternatives: enabling workaround for ARM erratum 845719 [ 0.000000] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ 0.000000] bootconsole [uart0] enabled [ 0.048225] No BMan portals available! [ 0.054167] No QMan portals available! [ 0.197414] Freescale FM module, FMD API version 21.1.0 [ 0.202816] Freescale FM Ports module [ 0.211351] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ 0.669450] fsl-mc bus not found, restool driver registration failed [ 0.939507] usb usb1-port1: over-current condition [ 0.944339] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ 3.077683] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff0000003fb000) 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 Boards
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 28 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards 3.5.1 LS1012ARDB 3.5.1.1 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.
3.5.1.2 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
1 2 3 4 5 6 7 8
SW1 1 0 1 0 0 1 1 0
SW2 0 0 0 0 0 0 0 0
Below are additional switch settings for alternate boot option i.e QSPI Flash2.
Table 2. Switch configuration
1 2 3 4 5 6 7 8
SW1 1 0 1 0 0 1 1 0
SW2 0 0 0 0 0 0 1 0
3.5.1.3 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. 3.5.1.3.1 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 29 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
3.5.1.3.2 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
NOTE (i)
(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
3.5.1.4 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 3.0
3.5.1.5 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:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 30 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) 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
3.5.1.6 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 2016.01-g5ab5bba (Jun 14 2016 - 12:56:17 +0530)
SoC: LS1012AE (0x87040010) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): 00000000: 08000008 00000000 00000000 00000000 00000010: 35080000 c000000c 40000000 00001800 00000020: 00000000 00000000 00000000 00014571 00000030: 00000000 18c2a120 00000096 00000000 I2C: ready DRAM: 1022 MiB MMU warning: gd->secure_ram is not maintained, disabled. SEC: RNG instantiated Using SERDES1 Protocol: 13576 (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, regs @ 0x3400000 In: serial Out: serial Err: serial Model: LS1012A RDB Board Board: LS1012ARDB Version: RevB, boot from QSPI: bank1 SATA link 0 timeout. AHCI 0001.0301 32 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: 0000000004000000, ddr_baseaddr: 0000000083800000, ddr_phys_baseaddr:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 31 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
03800000 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: 0000000083e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: 0000000083e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: 0000000083e40400, 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_0000
3.5.1.7 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 32 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) 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 0x80000000
The commands above will only program a new U-Boot. Programming a new RCW will be discussed in the next sections. 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 0x000000. 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 0x80000000
NOTE RCW and U-Boot binary must be byte swapped using command (tclsh ./byte_swap.tcl u-boot- dtb.bin u-boot-dtb_swap.bin 8)
3.5.1.8 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. 3.5.1.8.1 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,115200 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 33 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
Execute the following commands to TFTP the images to the board, then boot into Linux.
=>tftp 0xa0000000
Now the board will boot into Linux using the images generated by Yocto.
3.5.1.8.2 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 0x96000000 0xa00000 0x2800000; bootm 0x96000000
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
=>tftp 0x96000000
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 0x96000000 0xa00000 0x2800000; bootm 0x96000000
3.5.1.8.3 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:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 34 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
b. Restart the NFS service:
/etc/init.d/nfs restart
NOTE nfs_root_path: the NFS root directory path on NFS server.
3. Setting U-Boot Environment 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 30 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=
NOTE
Now U-Boot is ready for NFS deployment. 4. Booting up the System TFTP the kernel image to the board, then boot it up.
=>tftp 96000000 kernel.itb; =>bootm 96000000:kernel@1 - 96000000:fdt@1
Now the board will boot up with NFS filesystem.
3.5.1.8.4 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 Note: The first 2056 sectors of SD card must be remained for u-boot imageFIT Kernel Image and Root File System Deployment from 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/
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 35 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
4. Copy the Root File System to the SD card partition. #cp fsl-image-core-ls1043ardb_
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
3.5.1.9 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.
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
Example:
=> mdio read pfe_eth0 1 Reading from bus PFE_MDIO PHY at address 2: 1 - 0x79ad => mdio read pfe_eth1 1
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 36 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
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 0x7989.
3.5.1.10 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 2016.01-gc423721 (Jun 27 2016 - 13:06:22 +0530)
SoC: LS1012AE (0x87040010) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): 00000000: 08000008 00000000 00000000 00000000 00000010: 35080000 c000000c 40000000 00001800 00000020: 00000000 00000000 00000000 00014571 00000030: 00000000 18c2a120 00000096 00000000 I2C: ready DRAM: 1022 MiB MMU warning: gd->secure_ram is not maintained, disabled. SEC: RNG instantiated Using SERDES1 Protocol: 13576 (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, regs @ 0x3400000 In: serial Out: serial Err: serial Model: LS1012A RDB Board Board: LS1012ARDB Version: RevB, boot from QSPI: bank1 SATA link 0 timeout. AHCI 0001.0301 32 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: 0000000004000000, ddr_baseaddr: 0000000083800000, ddr_phys_baseaddr: 03800000 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: 0000000083e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: 0000000083e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: 0000000083e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled pfe_hw_init: done
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 37 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
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 192.168.1.1;setenv ipaddr 192.168.1.136 => ping $serverip Speed detected 3e8 Using pfe_eth0 device host 192.168.1.1 is alive => edit ethact edit: pfe_eth1 => ping $serverip Speed detected 3e8 Using pfe_eth1 device host 192.168.1.1 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 0xa0000000 kernel-ls1012a-rdb.itb Speed detected 3e8 Using pfe_eth1 device TFTP from server 192.168.1.1; our IP address is 192.168.1.136 Filename 'kernel-ls1012a-rdb.itb'. Load address: 0xa0000000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# #################################################################
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 38 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ############ 5.6 MiB/s done Bytes transferred = 38342491 (2490f5b hex) => pfe stop Stopping PFE... => bootm 0xa0000000 ## Loading kernel from FIT Image at a0000000 ... Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0xa00000dc Data Size: 12482048 Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x80080000 Entry Point: 0x80080000 ## Loading ramdisk from FIT Image at a0000000 ... Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: LS2 Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0xa0be9ba4 Data Size: 25849963 Bytes = 24.7 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at a0000000 ... Using 'config@1' configuration 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 0x90000000 Booting using the fdt blob at 0x90000000 Loading Kernel Image ... OK Using Device Tree in place at 0000000090000000, end 000000009000538c Starting kernel ...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 39 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
[ 0.000000] Booting Linux on physical CPU 0x0 [ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Linux version 4.1.8-rt8+g2511ec0 (jenkins@neptune) (gcc version 4.9.4 20150629 (prerelease) (Linaro GCC 4.9-2015.06) ) #1 SMP Sat Aug 27 04:44:19 CST 2016 [ 0.000000] CPU: AArch64 Processor [410fd034] revision 4 [ 0.000000] Detected VIPT I-cache on CPU0 [ 0.000000] alternatives: enabling workaround for ARM erratum 845719 [ 0.000000] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ 0.000000] bootconsole [uart0] enabled [ 0.046613] No BMan portals available! [ 0.052448] No QMan portals available! [ 0.186759] Freescale FM module, FMD API version 21.1.0 [ 0.192162] Freescale FM Ports module [ 0.200605] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ 0.658570] fsl-mc bus not found, restool driver registration failed [ 0.927488] usb usb1-port1: over-current condition [ 0.932320] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ 3.038179] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff0000003fb000) 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 [ 39.882345] pfe: module is from the staging directory, the quality is unknown, you have been warned. [ 39.895444] cbus_baseaddr: ffff000000880000, ddr_baseaddr: ffff800003400000, ddr_phys_baseaddr: 83400000, ddr_size: c00000 [ 39.907048] pfe_hw_init [ 39.909498] CLASS version: 20 [ 39.912466] TMU version: 1011231 [ 39.916024] BMU1 version: 21 [ 39.918907] BMU2 version: 21 [ 39.921787] EGPI1 version: 50 [ 39.924754] EGPI2 version: 50 [ 39.928157] HGPI version: 50 [ 39.931041] GPT version: 0 [ 39.933747] HIF version: 10 [ 39.936851] HIF NOPCY version: 10 [ 39.940171] bmu_init(1) done [ 39.943053] bmu_init(2) done [ 39.948670] class_init() done
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 40 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
[ 39.961678] tmu_init() done [ 39.964475] gpi_init(1) done [ 39.967585] gpi_init(2) done [ 39.970469] gpi_init(hif) done [ 39.973523] bmu_enable(1) done [ 39.976899] bmu_enable(2) done [ 39.979957] pfe_hif_lib_init [ 39.983049] pfe_hif_init [ 39.985582] pfe_hif_alloc_descr [ 39.989399] pfe_hif_init_buffers [ 39.992789] pfe_firmware_init [ 39.996492] pfe_load_elf [ 39.999043] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff00000050b000) rcvd [ 40.032785] PFE binary version: pfe_ls1012a_00_1-dirty [ 40.037965] pfe_firmware_init: class firmware loaded 0xa60 0xc3010000 [ 40.044415] pfe_load_elf [ 40.048328] pfe_firmware_init: tmu firmware loaded 0x200 [ 40.053668] pfe_ctrl_init [ 40.056631] pfe_ctrl_init finished [ 40.060039] pfe_eth_init [ 40.062614] pfe_eth_mdio_init [ 40.066072] pfe_ctrl_timer [ 40.076155] libphy: Comcerto MDIO Bus: probed [ 40.082466] pfe_phy_init interface 3 [ 40.175983] eth0: pfe_eth_init_one: created interface, baseaddr: ffff000000a80000 [ 40.192945] pfe_phy_init interface 7 [ 40.276066] eth1: pfe_eth_init_one: created interface, baseaddr: ffff000000aa0000 [ 40.283643] 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 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:127.0.0.1 Mask:255.0.0.0 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 00-00-00-00-3A-30-30-30-00-00-00-00-00-00-00-00is 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)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 41 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
root@ls1012ardb:~# ifconfig eth1 192.168.1.34 up [ 62.478999] eth1: pfe_eth_open [ 62.482403] hif_process_client_req: register client_id 1 [ 62.487772] pfe_hif_client_register [ 62.491755] eth1: pfe_gemac_init root@ls1012ardb:~# [ 67.275999] eth1: Link is Up - 1Gbps/Full - flow control rx/tx
root@ls1012ardb:~# root@ls1012ardb:~# root@ls1012ardb:~# root@ls1012ardb:~# ping 192.168.1.1 PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. 64 bytes from 192.168.1.1: icmp_seq=1 ttl=128 time=1.81 ms 64 bytes from 192.168.1.1: icmp_seq=2 ttl=128 time=0.883 ms ^C --- 192.168.1.1 ping statistics --- 2 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, eth1.
3.5.2 FRDM-LS1012A 3.5.2.1 Switch Settings
No On-Board Switch setting available
3.5.2.2 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. 3.5.2.2.1 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 42 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
3.5.2.2.2 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
NOTE (i)
(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
3.5.2.3 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 0x3505 • SGMII, SGMII • USB 3.0
3.5.2.4 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:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 43 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) 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
3.5.2.5 Flash Bank Usage The FRDM-LS1012A only has one QSPI flash connected over QSPI contoller.
U-Boot 2016.01-g1c18d6a (Jun 17 2016 - 15:15:39 +0530)
SoC: LS1012AE (0x87040010) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): 00000000: 08000008 00000000 00000000 00000000 00000010: 33050000 c000000c 40000000 00001800 00000020: 00000000 00000000 00000000 000c4571 00000030: 00000000 00c28120 00000096 00000000 I2C: ready DRAM: 510 MiB MMU warning: gd->secure_ram is not maintained, disabled. Using SERDES1 Protocol: 13061 (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: 0000000004000000, ddr_baseaddr: 0000000083800000, ddr_phys_baseaddr: 03800000 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: 0000000083e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: 0000000083e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: 0000000083e40400, base_pa: 03e40400 HIF init complete bmu1 enabled bmu2 enabled
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 44 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
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_0000
3.5.2.6 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 0x80000000
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 0x80000000
Note: RCW and U-Boot binaries must be byte swapped using command (tclsh ./byte_swap.tcl u-boot-dtb.bin u-boot- dtb_swap.bin 8). The ./byte_swap.tcl script is included as a part od the RCW source code.
3.5.2.7 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 45 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
3.5.2.7.1 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,115200 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 0x96000000
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.
3.5.2.7.2 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 0x96000000 0xa00000 0x2800000; bootm 0x96000000
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
=>tftp 0x96000000
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 46 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
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 0x96000000 0xa00000 0x2800000; bootm 0x96000000
3.5.2.7.3 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:
b. Restart the NFS service:
/etc/init.d/nfs restart
NOTE nfs_root_path: the NFS root directory path on NFS server.
3. Setting U-Boot Environment 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 30 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=
NOTE
Now U-Boot is ready for NFS deployment. 4. Booting up the System TFTP the kernel image to the board, then boot it up.
=>tftp 96000000 kernel.itb; =>bootm 96000000:kernel@1 - 96000000:fdt@1
Now the board will boot up with NFS filesystem.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 47 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
3.5.2.8 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
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.
3.5.2.9 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 2016.01-g1c18d6a (Jun 17 2016 - 15:15:39 +0530) SoC: LS1012AE (0x87040010) Clock Configuration: CPU0(A53):800 MHz Bus: 250 MHz DDR: 1000 MT/s Reset Configuration Word (RCW): 00000000: 08000008 00000000 00000000 00000000 00000010: 33050000 c000000c 40000000 00001800 00000020: 00000000 00000000 00000000 000c4571 00000030: 00000000 00c28120 00000096 00000000
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 48 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
I2C: ready DRAM: 510 MiB MMU warning: gd->secure_ram is not maintained, disabled. Using SERDES1 Protocol: 13061 (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: 0000000004000000, ddr_baseaddr:0000000083800000, ddr_phys_baseaddr: 03800000 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: 0000000083e40400, base_pa: 03e40400, desc_count: 64 hif_rx_desc_init: Rx desc base: 0000000083e40000, base_pa: 03e40000, desc_count: 64 HIF tx desc: base_va: 0000000083e40400, 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 192.168.5.124;setenv ipaddr 192.168.5.136 => edit ethact edit: pfe_eth1 => ping $serverip Speed detected 3e8 Using pfe_eth1 device host 192.168.5.124 is alive => edit ethact edit: pfe_eth0 => ping $serverip Speed detected 3e8 Using pfe_eth0 device host 192.168.5.124 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 49 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
On U-Boot prompt:
=> tftp 0x96000000 kernel-ls1012a-frdm.itb Speed detected 3e8 Using pfe_eth0 device TFTP from server 192.168.5.124; our IP address is 192.168.5.125 Filename 'kernel-ls1012a-frdm.itb'. Load address: 0x96000000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# 2.5 MiB/s done Bytes transferred = 40631911 (26bfe67 hex) => pfe stop Stopping PFE... => bootm 0x96000000 ## Loading kernel from FIT Image at 96000000 ... Using 'config@1' configuration Trying 'kernel@1' kernel subimage Description: ARM64 Linux kernel Type: Kernel Image Compression: uncompressed Data Start: 0x9600013c Data Size: 12502016 Bytes = 11.9 MiB Architecture: AArch64 OS: Linux Load Address: 0x80080000 Entry Point: 0x80080000 ## Loading ramdisk from FIT Image at 96000000 ... Using 'config@1' configuration Trying 'ramdisk@1' ramdisk subimage Description: Ramdisk Type: RAMDisk Image Compression: uncompressed Data Start: 0x96bef354 Data Size: 24491924 Bytes = 23.4 MiB Architecture: AArch64 OS: Linux Load Address: unavailable Entry Point: unavailable ## Loading fdt from FIT Image at 96000000 ... 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: 11490 Bytes = 11.2 KiB Architecture: AArch64
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 50 NXP Semiconductors Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
Loading fdt from 0x96bec5f0 to 0x90000000 Booting using the fdt blob at 0x90000000 Loading Kernel Image ... OK Using Device Tree in place at 0000000090000000, end 0000000090005ce1
Starting kernel ...
[ 0.000000] Booting Linux on physical CPU 0x0 [ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Linux version 4.1.8-rt8+g2511ec0 (jenkins@neptune) (gcc version 4.9.4 20150629 (prerelease) (Linaro GCC 4.9-2015.06) ) #1 SMP Sat Aug 27 04:44:19 CST 2016 [ 0.000000] CPU: AArch64 Processor [410fd034] revision 4 [ 0.000000] Detected VIPT I-cache on CPU0 [ 0.000000] alternatives: enabling workaround for ARM erratum 845719 [ 0.000000] earlycon: Early serial console at MMIO 0x21c0500 (options '') [ 0.000000] bootconsole [uart0] enabled [ 0.046613] No BMan portals available! [ 0.052448] No QMan portals available! [ 0.186759] Freescale FM module, FMD API version 21.1.0 [ 0.192162] Freescale FM Ports module [ 0.200605] vfio_fsl_mc_driver_init: Driver registration fails as no fsl_mc_bus found [ 0.658570] fsl-mc bus not found, restool driver registration failed [ 0.927488] usb usb1-port1: over-current condition [ 0.932320] usb usb2-port1: over-current condition INIT: version 2.88 booting Starting udev [ 3.038179] pe_load_ddr_section: load address(3fb0000) and elf file address(ffff0000003fb000) 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: root@ls1012afrdm:~# root@ls1012afrdm:~# [ 48.955650] eth0: Link is Up - 1Gbps/Full - flow control rx/tx root@ls1012afrdm:~# ping 192.168.5.124 PING 192.168.5.124 (192.168.5.124) 56(84) bytes of data. 64 bytes from 192.168.5.124: icmp_seq=1 ttl=128 time=1.92 ms 64 bytes from 192.168.5.124: icmp_seq=2 ttl=128 time=1.51 ms 64 bytes from 192.168.5.124: icmp_seq=3 ttl=128 time=1.44 ms ^C --- 192.168.5.124 ping statistics --- 3 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 51 Deploy U-Boot, Linux Kernel, and Root Filesystem to a Reference Design Board (RDB) Boards
inet addr:192.168.5.125 Bcast:192.168.5.255 Mask:255.255.255.0 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:127.0.0.1 Mask:255.0.0.0 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 00-00-00-00-3A-30-30-30-00-00-00-00-00-00-00-00 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 52 NXP Semiconductors System Recovery Environment Setup Chapter 4 System Recovery
4.1 Environment Setup
4.1.1 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
4.2 Image Recovery
4.2.1 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 53 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.
4.2.2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 54 NXP Semiconductors 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 ucode/microcode (if applicable). e. Identify the starting address for the dtb image. f. Identify the starting address for the RamDisk image. g. Identify the starting address for the Linux Kernel image. For example:
Table 3. T4240QDS NOR flash
Binaries Starting Address
U-Boot 0xEFF40000
RCW 0xE8000000 ucode 0xEFF00000 dtb 0xE8800000
RamDisk (rootfs) 0xE9300000
Linux Kernel (uImage) 0xE8020000
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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 55 System Recovery Image Recovery
11. Reset or power-cycle the board and verify that u-boot appears in the board’s serial terminal.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 56 NXP Semiconductors 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 57 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 58 NXP Semiconductors Linux Kernel Drivers Audio Chapter 6 Linux Kernel Drivers
6.1 Audio
6.1.1 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 366-367, EC1_BASE = 00
Kernel Configure Options Tree View
Kernel Configure Tree View Options Description
Enable ALSA SOC driver, I2C driver and EDMA driver. 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
<*> 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 --->
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 59 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_ y/m/n y Support conversion of PLUGINS channels, formats and rates
CONFIG_SND_SUPPORT_ y/m/n y Enable support old ALSA OLD_API API
CONFIG_SND_SOC_FSL_ y/m/n y Enable SAI module support SAI
CONFIG_SND_SOC_GENE y/m/n y Enable generic dma engine RIC_DMAENGINE_PCM for PCM
CONFIG_SND_SIMPLE_CA y/m/n y Enable generic simple RD sound card support
CONFIG_SND_SOC_SGTL y/m/n y Enable codec sgtl5000 5000 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 Description
sound/soc/fsl ALSA SOC driver source
Verification in Linux 1. The following messages will be shown in the kernel boot process.
sgtl5000 5-000a: sgtl5000 revision 0x11
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 60 NXP Semiconductors Linux Kernel Drivers DMA Controller
sgtl5000 5-000a: Using internal LDO instead of VDDD ...... asoc-simple-card sound: sgtl5000 <-> 2b60000.sai mapping ok ...... ALSA device list: #0: 2b60000.sai-sgtl5000
2. 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 116 0 mknod pcmC0D0c c 116 24 mknod pcmC0D0p c 116 16
3. 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 44100 -t wav -c 2 44k-16bit-stereo.wav
arecord -d 10 -f S16_LE -r 44100 -t wav -c 2 44k-16bit-stereo-10s.wav aplay -f S16_LE -r 44100 -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
6.2.1 Enhanced Direct Memory Access Driver (ARM) 6.2.1.1 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 61 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 0x2c00000 0x0 0x10000>, <0x0 0x2c10000 0x0 0x10000>, <0x0 0x2c20000 0x0 0x10000>; interrupts =
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@2180000 { #address-cells = <1>; #size-cells = <0>; compatible = "fsl,vf610-i2c"; reg = <0x0 0x2180000 0x0 0x10000>; interrupts =
Source Files The following source files are related the this feature in Linux kernel.
Table 4. Source Files
Source File Description
drivers/dma/fsl-edma.c The eDMA driver file
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 62 NXP Semiconductors 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] 0 1 2 3 4 5 6 7 8 9 a b c d e f 00: ------10: ------20: ------30: ------40: ------50: ------60: ------69 ------70: ------root@ls1021aqds:~# i2cdump 0 0x69 i 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789abcdef 00: 05 07 ff ff 5d 55 10 55 11 05 1e 00 e8 03 b5 ff ??..]U?U???.???. 10: ff e8 03 95 00 00 00 00 aa fe 9a 00 00 00 00 78 .???....???....x 20: 05 12 04 ff 00 7f 40 14 1d 60 3c 83 05 00 40 00 ???..?@??`
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 63 Linux Kernel Drivers Enhanced Secured Digital Host Controller (eSDHC)
6.3 Enhanced Secured Digital Host Controller (eSDHC)
6.3.1 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 Description
Enables SD/MMC block device Device Drivers ---> driver support <*> MMC/SD/SDIO card support ---> <*> MMC block device driver (8) Number of minors per block device [*] Use bounce buffer for simple hosts
Enables NXP eSDHC driver support *** MMC/SD/SDIO Host Controller Drivers ***
<*> Secure Digital Host Controller Interface support <*> SDHCI platform and OF driver helper [*] SDHCI OF support for the NXP eSDHC controller
Compile-time Configuration Options
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...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 64 NXP Semiconductors 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@114000 { compatible = "fsl,esdhc"; reg = <0x114000 0x1000>; interrupts = <48 2 0 0>; clock-frequency = <0>; };
For special platform (T1040 as example): /include/ "qoriq-esdhc-0.dtsi" sdhc@114000 { compatible = "fsl,t1040-esdhc", "fsl,esdhc"; fsl,iommu-parent = <&pamu0>; fsl,liodn-reg = <&guts 0x530>; /* eSDHCLIODNR */ sdhci,auto-cmd12; rcpm-wakeup = <&rcpm 0x00000080>; };
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 Description drivers/mmc/host/sdhci.c Linux SDHCI driver support drivers/mmc/host/sdhci-pltfm.c Linux SDHCI platform devices support driver drivers/mmc/host/sdhci-of-esdhc.c Linux eSDHC driver
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 65 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 Description Package Name Name
iozone IOzone is a filesystem benchmark tool. The benchmark generates and measures a iozone 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.
Verification in U-boot The u-boot log:
=> mmcinfo Device: FSL_ESDHC Manufacturer ID: 3 OEM: 5344 Name: SD02G Tran Speed: 25000000 Rd Block Len: 512 SD version 2.0 High Capacity: No Capacity: 2032664576 Bus Width: 4-bit => mmc read 0 10000 0 1 MMC read: dev # 0, block # 0, count 1 ... 1 blocks read: OK => mmc part 0 Partition Map for MMC device 0 -- Partition Type: DOS Partition Start Sector Num Sectors Type
1 16 3970032 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 66 NXP Semiconductors Linux Kernel Drivers Enhanced Secured Digital Host Controller (eSDHC)
mmcblk0: p1
Check the disk
~ # fdisk -l /dev/mmcblk0
disk /dev/mmcblk0: 2032 MB, 2032664576 bytes
63 heads, 62 sectors/track, 1016 cylinders
Units = cylinders of 3906 * 512 = 1999872 bytes
Device Boot Start End Blocks Id System
/dev/mmcblk0p1 1 1016 1984217 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 67 Linux Kernel Drivers Enhanced Secured Digital Host Controller (eSDHC)
Iozone: Performance Test of File I/O
Version $Revision: 3.263 $
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:04 2011
Excel chart generation enabled
Auto Mode
Using minimum file size of 524288 kilobytes.
Using maximum file size of 1048576 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 = 0.000005 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
524288 64 7040 7253 371022 372079
1048576 64 6537 6566 9857 10203
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 68 NXP Semiconductors 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
6.4.1 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 Description
Enable PCI host bridge and Bus support ---> message support [*] PCI support [*] Message Signaled Interrupts (MSI and MSI-X)
Enable NXP Layerscape Bus support ---> PCIe controller PCI host controller drivers ---> [*] Freescale Layerscape PCIe controller
Intel PRO/1000 PCI-Express Device Drivers ---> support [*]Network device support ---> [*]Ethernet device support ---> [*] Intel devices ---> <*> Intel (R) PRO/1000 PCI-Express Gigabit Ethernet support
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 69 Linux Kernel Drivers PCI Express Interface Controller
Table continued from the previous page...
Kernel Configure Tree View Options Description
Enable support for Silicon Device Drivers ---> 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 Description
arch/powerpc/sysdev/fsl_pci.c The MPC85XX platform PCIE host bridge support source
drivers/pci/host/pci-layerscape.c The Layerscape platform PCIE host bridge support source
drivers/net/ethernet/intel/e1000e/ Intel Pro/1000 driver source code
drivers/ata/sata_sil.c 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, 85899345920 bytes 255 heads, 63 sectors/track, 10443 cylinders Units = cylinders of 16065 * 512 = 8225280 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,
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 70 NXP Semiconductors 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 10443. 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 (1-10443, default 1): Using default value 1 Last cylinder or +size or +sizeM or +sizeK (1-10443, 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] 167772160 512-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) 100576 inodes, 200804 blocks 10040 blocks (5.00%) reserved for the super user First data block=0 7 block groups 32768 blocks per group, 32768 fragments per group 14368 inodes per group Superblock backups stored on blocks: 32768, 98304, 163840
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]#
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 71 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 192.168.20.100 ip address should not be conficted with other Ethernet port. In Linux window, run ping 192.168.20.101
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 +++ b/arch/powerpc/sysdev/fsl_pci.c @@ -511,7 +511,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 -ENOMEM; @@ -846,7 +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;
6.4.2 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/P5020 64bit.
Module Loading Linux EDAC Driver supports kernel built-in or module.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 72 NXP Semiconductors Linux Kernel Drivers PCI Express Interface Controller
Kernel Configure Options
Kernel Configure Tree View Options
Kernel Configure Tree View Options Description
Enables EDAC support Device Drivers ---> for 85xx platform <*> EDAC (Error Detection And Correction) reporting --- > <*> Main Memory EDAC (Error Detection And Correction) reporting <*> Freescale MPC83xx / MPC85xx
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 = <16 2 1 23>; };
/* controller at 0x200000 */ pci0 { compatible = "fsl,p4080-pcie"; device_type = "pci"; #size-cells = <2>; #address-cells = <3>; bus-range = <0x0 0xff>; clock-frequency = <33333333>; interrupts = <16 2 1 15>; };
Source Files The driver source is maintained in the Linux kernel source tree.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 73 Linux Kernel Drivers PCI Express Interface Controller
Source File Description
drivers/edac/edac_core.c Enables EDAC core support
drivers/edac/mpc85xx_edac.c Enables EDAC NXP 85xx support
Kernel boot message:
...... EDAC MC: Ver: 2.1.0 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 'ffe200000.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 'ffe201000.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 'ffe202000.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: 0x00020000 PCIE ERR_CAP_STAT register: 0x80000001 PCIE ERR_CAP_R0 register: 0x00000800 PCIE ERR_CAP_R1 register: 0x00000000 PCIE ERR_CAP_R2 register: 0x00000000 PCIE ERR_CAP_R3 register: 0x00000000 ...... p4080 login: root Password: [root@p4080 root]#
Test Procedure:
[root@p4080 root]# [root@p4080 root]# cat /proc/interrupts |grep EDAC 16: 1 0 0 0 0 0 0 0 OpenPIC Level [EDAC] MC err, [EDAC] MC err, [EDAC] PCI err, [EDAC] PCI err, [EDAC] PCI err [root@p4080 root]# [root@p4080 root]#
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 74 NXP Semiconductors 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.
6.4.3 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 Description
enable PCI-Express AER and AER-INJECTOR in Bus options ---> kernel [*] PCI Express support [*] Root Port Advanced Error Reporting support <*> PCIe AER error injector support
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 Description drivers/pci/pcie/aer/*.c 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 0 1 2 3
NOTE: error type can be ["COR_STATUS", "UNCOR_STATUS"]
Corrected error can be: ["BAD_TLP", "RCVR", "BAD_DLLP", "REP_ROLL", "REP_TIMER"]
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 75 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 1000000 uImage;tftp 2000000 board.dtb; tftp 3000000 rootfs.ext2.gz.uboot; bootm 1000000 3000000 2000000
4, 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,115200 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:0410 01: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=00000040/00002000 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 192.168.1.1 -c 2 -s 64 PING 192.168.1.1 (192.168.1.1): 64 data bytes 72 bytes from 192.168.1.1: icmp_seq=0 ttl=64 time=0.272 ms 72 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=0.210 ms --- 192.168.1.1 ping statistics --- 2 packets transmitted, 2 packets received, 0% packet loss
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 76 NXP Semiconductors 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.
6.4.4 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 ---> This option enables kernel support for Intel PCI-e e1000e [*] Network device support---> network card [*] Ethernet (1000 Mbit) ---> [*] Intel(R) PRO/1000 PCI-Express Gigabit Ethernet support
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 eth0 10.193.20.100 # ping -I eth0 10.193.20.31
2. Remove the PCI-e network card from system.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 77 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\:00.0
4. 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 eth0 10.193.20.100 # ping -I eth0 10.193.20.31
6. 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.
6.4.5 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 78 NXP Semiconductors 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 12.04 64bit.
1. Change directory to Yocto, then extract the SKMM Host source code as following:
#> source ./poky/fsl-setup-poky -m
2. The source code will be in tmp/work/
#> 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
• 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 79 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
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 1000000 uImage-
4. 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 80 NXP Semiconductors 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
root@p4080:skmm_$(host) /dev/mtd4
For T4240qds as EP 1.
#> setenv ipaddr
2. Program RCW with “RR_XXSSPRPH_1_28_6_12/rcw_1_28_6_12_pexep_1666MHz.bin”
#> tftp 1000000 uImage-
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
3. Execute following command at u-boot prompt to boot the board
#> tftp 1000000 uImage-
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 81 Linux Kernel Drivers PCI Express Interface Controller
#> tftp c00000 uImage-
4. 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)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 82 NXP Semiconductors Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver
For example, to P4080ds, Cpu Frequency is 1.5GHz(1.5 x 109). 5000 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 6.5.1 Introduction 6.5.1.1 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.
6.5.1.2 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.
6.5.1.3 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.
6.5.2 High level decomposition and data flow A system level block view, from a network device perspective, may be depicted as follows:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 83 Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver
User ethtool iproute2 application package package
Network protocol handler/ioctl interface
Linux network stack
Eth0 Eth1
HIF/Ethernet client driver
Kernel HIF driver layer
H
PFE HW MAC 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 84 NXP Semiconductors Linux Kernel Drivers Packet Forward Engine (PFE) Network Driver 6.5.3 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.
6.5.4 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.
6.5.5 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.
6.5.6 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).
6.5.7 Ethtool support Non-exhaustive list of the most notable ethtool commands implemented by PFE Linux driver:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 85 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 • Set UDP/TCP checksum offloading enabled or disabled. • tx on|off
• ethtool -S • • Show interface statistics, Linux specific counters and various MAC H/ W counters.
6.6 Real Time Clock (off-chip)
6.6.1 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 Description
Enable RTC driver 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)
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...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 86 NXP Semiconductors 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 Description
drivers/rtc/ 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-ds3232 1-0068: rtc core: registered ds3232 as rtc0 MC object device driver dpaa2_rtc registered rtc-ds3232 0-0068: setting system clock to 2000-01-01 00:00:51 UTC (946684851) ...
NOTE: Please refer to the related DTS file to enable the RTC driver before building. For example, LS2080AQDS board, should enable the below option: <*> Dallas/Maxim DS3232
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 87 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:41 2000 0.000000 seconds ~ # date 011115502011 Tue Jan 11 15:50:00 UTC 2011 ~ # hwclock -w ~ # hwclock Tue Jan 11 15:50:36 2011 0.000000 seconds ~ # date 011115502010 Mon Jan 11 15:50:00 UTC 2010 ~ # hwclock -s ~ # date Tue Jan 11 15:50:49 UTC 2011 ~ #
NOTE: Before using the rtc driver, make sure the /dev/rtc node in your file system is correct. Otherwise, you need to make correct node for /dev/rtc
6.7 SATA Controller
6.7.1 External SATA Controller User Manual
Description The SATA controller is integrated in ULi1575 south bridge on the board.
Source Files The driver source is maintained in the U-boot source tree.
Source File Description
drivers/block/ahci.c U-Boot sata driver support
common/cmd_scsi.c U-Boot scsi command support
The driver source is maintained in the Linux source tree.
Source File Description
drivers/ata/sata_fsl.c NXP SATA driver
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 88 NXP Semiconductors Linux Kernel Drivers SATA Controller
Kernel Configure Tree View Options
Kernel Configure Tree View Options Description
Enable NXP 3.0Gbps SATA SoC driver Device Drivers --->
<*> Serial ATA (prod) and Parallel ATA (experimental) drivers --->
[*] SATA Port Multiplier support
<*> AHCI SATA support
<*> Freescale 3.0Gbps SATA support
Enable SCSI disk support
Device Drivers --->
SCSI device support --->
<*> SCSI disk support
Enable filesystem and partition table support File systems --->
<*> Second extended fs support
<*> Ext3 journalling file system support
Partition Types --->
[*] Advanced partition selection
[*] PC BIOS (MSDOS partition tables) support
Native Language Support --->
(iso8859-1) Default NLS Option
<*> Codepage 437 (United States, Canada)
<*> NLS ISO 8859-1 (Latin 1; Western European Languages)
Compile-time Configuration Options
Option Values Default Value Description
CONFIG_ATA y/n y Enables libata support
CONFIG_SATA_FSL y/m/n y Enables NXP 3.0Gbps SATA driver
CONFIG_BLK_DEV_SD y/m/n y Enables SCSI disk support
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 89 Linux Kernel Drivers SATA Controller
Table continued from the previous page...
Option Values Default Value Description
CONFIG_EXT2_FS y/m/n y Enables ext2 filesystem support
CONFIG_EXT3_FS y/m/n y Enables ext3 filesystem support
CONFIG_PARTITION_ADVANCED y/n y Enables partition table of other OS
CONFIG_MSDOS_PARTITION y/n y Enables MSDOS partition table support
CONFIG_NLS_DEFAULT y/n y Default NLS used when mounting file system
CONFIG_NLS_CODEPAGE_437 y/n y Add support to codepage 437
Verification in U-Boot Make sure sata had been inserted on board before power on. U-Boot log . Take P2020DS board as an example.
SCSI: AHCI 0001.0000 32 slots 4 ports 3 Gbps 0xf impl IDE mode
flags: ncq ilck pm led clo pmp pio slum part
scanning bus for devices...
Device 0: (1:0) Vendor: ATA Prod.: Hitachi HDT72101 Rev: ST1O
Type: Hard Disk
Capacity: 131071.9 MB = 127.9 GB (268435455 x 512)
Scanthe contents of the SATA disk in u-boot
=> scsi scan
scanning bus for devices...
Device 0: (1:0) Vendor: ATA Prod.: Hitachi HDT72101 Rev: ST1O
Type: Hard Disk
Capacity: 131071.9 MB = 127.9 GB (268435455 x 512)
=>
Verificationin Linux Scanthe contents of the SATA disk.
=> ext2ls scsi 0:3 /
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 90 NXP Semiconductors Linux Kernel Drivers SATA Controller
619548672 rootfs.p2020
....
=>
Set bootargs.
=>setenv scsiboot 'scsiboot=setenv bootargs root=/dev/sda3 rw console=ttyS0,115200;ext2load scsi 0:3 1000000 /boot/uImage.p2020;ext2load scsi 0:3 c00000 /boot/p2020ds.dtb;bootm 1000000 - c00000'
=>setenv bootcmd 'run scsiboot'
=>saveenv
=>reset
Here is the booting log.
....
SCSI: AHCI 0001.0000 32 slots 4 ports 3 Gbps 0xf impl IDE mode
flags: ncq ilck pm led clo pmp pio slum part
scanning bus for devices...
Device 0: (2:0) Vendor: ATA Prod.: ST3160815AS Rev: 3.AA
Type: Hard Disk
Capacity: 131071.9 MB = 127.9 GB (268435455 x 512)
Net: eTSEC1, eTSEC2, eTSEC3
Hit any key to stop autoboot: 0
2681833 bytes read
12288 bytes read
....
EXT3-fs warning: checktime reached, running e2fsck is recommended
EXT3 FS on sda3, internal journal
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 91 Linux Kernel Drivers SATA Controller
EXT3-fs: recovery complete.
EXT3-fs: mounted filesystem with ordered data mode.
VFS: Mounted root (ext3 filesystem).
Freeing unused kernel memory: 212k init
Mounting /proc and /sys
Starting the hotplug events dispatcher udevd
Synthesizing initial hotplug events
Setting the hostname to p2020ds
Running depmod
WARNING: Couldn't open directory /lib/modules/2.6.28.6-00524-g3c7d759-dirty: No such file or directory
FATAL: Could not open /lib/modules/2.6.28.6-00524-g3c7d759-dirty/modules.dep.temp for writing: No such file or directory
Mounting filesystems
Starting syslogd and klogd
Running sysctl
Setting up networking on loopback device:
Setting up networking on eth0:
ADDRCONF(NETDEV_UP): eth0: link is not ready
Adding static route for default gateway to 192.168.1.1:
Setting nameserver to 192.168.1.1 in /etc/resolv.conf:
Setting up networking oADDRCONF(NETDEV_UP): eth1: link is not ready
n eth1:
Adding static route for default gateway to 192.168.1.1:
Setting nameserver to 192.168.1.1 in /etc/resolv.conf:
Starting inetd:
Starting the port mapper:
Setting time from ntp server:
/bin/ntpclient: option requires an argument -- h
Usage: /bin/ntpclient [-c count] [-d] [-g goodness] -h hostname [-i interval]
[-l] [-p port] [-r] [-s]
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 92 NXP Semiconductors Linux Kernel Drivers SATA Controller
Starting the watchdog daemon:
rebuilding rpm database
PHY: mdio@24520:00 - Link is Up - 1000/Full
ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
Welcome to Freescale Semiconductor Embedded Linux Environment
!!!!! WARNING !!!!!!!
The default password for the root account is: root
please change this password using the 'passwd' command
and then edit this message (/etc/issue) to remove this message
p2020ds login:
Mount sata after bootup.
~ #
~ # fdisk -l
Disk /dev/sda: 160.0 GB, 160041885696 bytes
255 heads, 63 sectors/track, 19457 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Device Boot Start End Blocks Id System
/dev/sda1 1 13 104391 83 Linux
/dev/sda2 14 379 2939895 83 Linux
/dev/sda3 380 866 3911827+ 83 Linux
~ # mount /dev/sda3 /mnt/src
~ # ls /mnt/src
bin include mnt sbin
boot lib opt sys
dev linuxrc proc tmp
etc lost+found root usr
home man rootfs.ext2.gz.uboot var
~ #
~ # umount /dev/sda3
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 93 Linux Kernel Drivers SATA Controller
~ # ls /mnt/src
~ #
~ #
6.7.2 NXP Native SATA Driver User Manual
Description The driver supports NXP native SATA controller. There are two types of SATA controller. One is PowerPC-based and the other is ARM-based. There is slight difference between them. This manual will take P5020DS board as example for description.
Module Loading SATA driver supports either kernel built-in or module.
Kernel Configure Tree View Options 1) For PowerPC-based Socs, like P5020, P5040 etc.
Kernel Configure Tree View Options Description
Enables SATA controller support on PowerPC-based SoCs Device Drivers---> <*> Serial ATA and Parallel ATA drivers ---> --- Serial ATA and Parallel ATA drivers <*> Freescale 3.0Gbps SATA support
2) For ARM-based Socs, like LS1021, LS2085 etc.
Kernel Configure Tree View Options Description
Enables SATA controller support on ARM-based SoCs Device Drivers---> <*> Serial ATA and Parallel ATA drivers ---> --- Serial ATA and Parallel ATA drivers <*> AHCI SATA support <*> Freescale QorIQ AHCI SATA support
Compile-time Configuration Options 1) For PowerPC-based Socs, like P5020, P5040 etc.
Option Values Default Value Description
CONFIG_SATA_FSL=y y/m/n y Enables SATA controller
2) For ARM-based Socs, like LS1021, LS2085 etc.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 94 NXP Semiconductors Linux Kernel Drivers SATA Controller
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. 1) For PowerPC-based Socs, like P5020, P5040 etc.
Source File Description
drivers/ata/sata-fsl.c SATA controller driver
2) For ARM-based Socs, like LS1021, LS2085 etc.
Source File Description
drivers/ata/ahci_qoriq.c Platform AHCI SATA support
P5020DS Test Procedure
Please follow the following steps to use USB in Simics (1) Boot up the kernel ... fsl-sata ffe18000.sata: Sata FSL Platform/CSB Driver init scsi0 : sata_fsl ata1: SATA max UDMA/133 irq 74 fsl-sata ffe19000.sata: Sata FSL Platform/CSB Driver init scsi1 : sata_fsl ata2: SATA max UDMA/133 irq 41 ... (2) The disk will be found by kernel. ... ata1: Signature Update detected @ 504 msecs ata2: No Device OR PHYRDY change,Hstatus = 0xa0000000 ata2: SATA link down (SStatus 0 SControl 300) ata1: SATA link up 1.5 Gbps (SStatus 113 SControl 300) ata1.00: ATA-8: WDC WD1600AAJS-22WAA0, 58.01D58, max UDMA/133 ata1.00: 312581808 sectors, multi 0: LBA48 NCQ (depth 16/32) ata1.00: configured for UDMA/133 scsi 0:0:0:0: Direct-Access ATA WDC WD1600AAJS-2 58.0 PQ: 0 ANSI: 5 sd 0:0:0:0: [sda] 312581808 512-byte logical blocks: (160 GB/149 GiB) sd 0:0:0:0: Attached scsi generic sg0 type 0 sd 0:0:0:0: [sda] Write Protect is off sd 0:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA sda: sda1 sda2 sda3 sda4 < sda5 sda6 > sd 0:0:0:0: [sda] Attached SCSI disk
(3)play with the disk according to the following log. [root@p5020 root]# fdisk -l /dev/sda Disk /dev/sda: 160.0 GB, 160041885696 bytes 255 heads, 63 sectors/track, 19457 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 95 Linux Kernel Drivers SATA Controller
Device Boot Start End Blocks Id System /dev/sda1 1 237 1903671 83 Linux /dev/sda2 238 480 1951897+ 82 Linux swap /dev/sda3 481 9852 75280590 83 Linux /dev/sda4 9853 19457 77152162+ f Win95 Ext'd (LBA) /dev/sda5 9853 14655 38580066 83 Linux /dev/sda6 14656 19457 38572033+ 83 Linux [root@p5020 root]# [root@p5020 root]# mke2fs /dev/sda1 mke2fs 1.41.4 (27-Jan-2009) Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) 65280 inodes, 261048 blocks 13052 blocks (5.00%) reserved for the super user First data block=0 Maximum filesystem blocks=268435456 8 block groups 32768 blocks per group, 32768 fragments per group 8160 inodes per group Superblock backups stored on blocks: 32768, 98304, 163840, 229376
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@p5020 root]# [root@p5020 root]# mkdir sata [root@p5020 root]# mount /dev/sda1 sata [root@p5020 root]# ls sata/ lost+found [root@p5020 root]# cp /bin/busybox sata/ [root@p5020 root]# umount sata/ [root@p5020 root]# mount /dev/sda1 sata/ [root@p5020 root]# ls sata/ busybox lost+found [root@p5020 root]# umount sata/ [root@p5020 root]# mount /dev/sda3 /mnt [root@p5020 root]# df Filesystem 1K-blocks Used Available Use% Mounted on rootfs 852019676 794801552 13937948 99% / /dev/root 852019676 794801552 13937948 99% / tmpfs 1036480 52 1036428 1% /dev shm 1036480 0 1036480 0% /dev/shm /dev/sda3 74098076 4033092 66300956 6% /mnt
Known Bugs, Limitations, or Technical Issues 1) For PowerPC-based Socs, like P5020, P5040 etc.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 96 NXP Semiconductors Linux Kernel Drivers Serial Peripheral Interface
• The best value of RX_WATER_MARK for good performance is 0x16, but it is set to 0x10 in driver since some disks cannot work with higher value. The value can be changed at run time like below:
echo 22 > /sys/devices/ffe000000.soc/ffe220000.sata/rx_watermark
22 is 0x16, ffe220000 is the register base of first SATA controller (ffe221000 is the second SATA controller), after changing it, use below instruction to check:
cat /sys/devices/ffe000000.soc/ffe220000.sata/rx_watermark
• The SATA controller has only 32-bit DMA access ability, it cannot access memory space above 4G if there is more than 4G memory in system, then kernel will enable SWIOTLB (which is also know as bounce buffer) to do an extra copy, this will cause performance degradation. So if there is more than 4G memory and need a good performance for SATA, set 'mem=4G' in U-boot bootargs, this will limit the system to use only 4G memory. • P5040DS board has issue to support Gen1(1.5Gbps) hard drive, use Gen2(3Gbps) hard drive on P5040DS. 2) For ARM-based Socs, like LS1021, LS2085 etc. • CDROM is not supported due to the silicon limitation
6.8 Serial Peripheral Interface
6.8.1 QuadSPI Driver for TWR-LS1021A User Manual 6.8.1.1 QuadSPI Driver User Manual
U-Boot Configuration Make sure your boot mode support QSPI. Use QSPI boot mode to boot an board, please check the board user manual and boot from QSPI. (or some other boot mode decide by your board.)
Kernel Configure Tree View Options
Device Drivers ---> Memory Technology Device (MTD) support RAM/ROM/Flash chip drviers ---> < > Detect flash chips by Common Flash Interface (CFI) probe < > Detect non-CFI AMD/JEDEC-compatible flash chips < > Support for RAM chips in bus mapping < > Support for ROM chips in bus mapping < > Support for absent chips in bus mapping Self-contained MTD device drivers ---> <*> Support most SPI Flash chips (AT26DF, M25P, W25X, ...) < > NAND Device Support ---- [*] the framework for SPI-NOR support <*> Freescale Quad SPI controller
Device Drivers --->
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 97 Linux Kernel Drivers Serial Peripheral Interface
[ ] Memory Controller drivers ----
Compile-time Configuration Options
Config Values Defualt Value Description
Enable QSPI module CONFIG_SPI_FSL_QUADSPI y/n y
Enables the framework for SPI-NOR CONFIG_MTD_SPI_NOR_BASE y/n y
Verification in U-Boot
=> sf probe 0:0 SF: Detected N25Q128A13 with page size 256 Bytes, erase size 4 KiB, total 16 MiB => sf erase 0 100000 SF: 1048576 bytes @ 0x0 Erased: OK => sf write 82000000 0 1000 SF: 4096 bytes @ 0x0 Written: OK => sf read 81100000 0 1000 SF: 4096 bytes @ 0x0 Read: OK => cm.b 81100000 82000000 1000 Total of 4096 byte(s) were the same
Verification in Linux:
The booting log
...... fsl-quadspi 1550000.quadspi: n25q128a13 (16384 Kbytes) fsl-quadspi 1550000.quadspi: QuadSPI SPI NOR flash driver ......
Erase the QSPI flash
~ # mtd_debug erase /dev/mtd0 0x1100000 1048576 Erased 1048576 bytes from address 0x00000000 in flash
Write the QSPI flash
~ # dd if=/bin/tempfile.debianutils of=tp bs=4096 count=1 ~ # mtd_debug write /dev/mtd0 0 4096 tp Copied 4096 bytes from tp to address 0x00000000 in flash
Read the QSPI flash
~ # mtd_debug read /dev/mtd0 0 4096 dump_file
Copied 4096 bytes from address 0x00000000 in flash to dump_file
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 98 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Check Read and Write
Use compare tools(yacto has tools named diff). ~ # diff tp dump_file ~ # If diff command has no print log, the QSPI verification is passed.
6.9 Universal Serial Bus Interfaces
6.9.1 USB 2.0 Host Driver 6.9.1.1 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
U-Boot Compile Time Configuration Options
U-Boot Configure Options Description
Enables USB host Dual Role controller support. Defined inside #define CONFIG_HAS_FSL_DR_USB platform config file: include/configs/
#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
Enable internal UTMI Phy support. Required only for SoCs having internal UTMI PHY. Defined inside file: arch/powerpc/include/asm/ CONFIG_SYS_FSL_USB_INTERNAL_UTMI_PHY config_mpc85xx.h
Tell maximum no. of USB controllers in this SoC. Defined inside file: arch/powerpc/include/asm/config_mpc85xx.h CONFIG_USB_MAX_CONTROLLER_COUNT
U-Boot Source Files The driver source is maintained in the U-boot source in following files
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 99 Linux Kernel Drivers Universal Serial Bus Interfaces
Source File Description
drivers/usb/host/ehci-fsl.c EHCI FSL USB host controller driver
common/cmd_usb.c Common usb command file
drivers/usb/host/ehci-hcd.c EHCI USB host controller driver
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
Enables EHCI Host Controller Driver and Device Drivers---> transaction translator. USB support --->
<*> EHCI HCD (USB 2.0) support
-*- Root Hub Transaction Translators
[ ] Improved Transaction Translator scheduling (EXPERIMENTAL)
[*] 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
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 100 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Table continued from the previous page...
Option Values Default Value Description
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 Description
drivers/usb/host/ehci-fsl.c EHCI USB host controller driver
arch/powerpc/sysdev/fsl_soc.c Hook between OF tree and platform device
drivers/usb/host/ohci_hcd.c OHCI USB host controller driver
Device Tree Binding
usb@22000 {
#address-cells = <1>;
#size-cells = <0>;
compatible = "fsl-usb2-
"fsl-usb2-
reg = <0x22000 0x1000>;
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 101 Linux Kernel Drivers Universal Serial Bus Interfaces
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 10011 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
USB device 0: Vendor: SanDisk Rev: 8.02 Prod: Cruzer Colors+
Type: Removable Hard Disk
Capacity: 7663.9 MB = 7.4 GB (15695871 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 2.0 - 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 102 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
2: Mass Storage, USB Revision 2.0 - 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 512 - Endpoint 2 Out Bulk MaxPacket 512
=> md 2000000 02000000: 02992004 02060002 08462cc0 84990329 ...... F,....) 02000010: 00c48e24 82181008 06501810 01a80004 ...$.....P...... 02000020: 083d3881 00808270 40a00000 b012a502 .=8....p@...... 02000030: d4000088 28840b45 80028200 40244400 ....(..E....@$D. 02000040: 022b1004 04842482 20610b81 0494d020 .+....$. a..... 02000050: 8012b628 08200100 010c6300 0411b880 ...(. ....c..... 02000060: 42400200 8004a4c8 29802818 904000c0 B@...... ).(..@.. 02000070: 08210200 2040a8c0 448aae00 a0000000 .!.. @..D...... 02000080: 2800c800 04b62080 60199885 02a62324 (...... `.....#$ 02000090: 04870a08 a0008000 18020003 0281a232 ...... 2 020000a0: 50414020 4000850b 02044c00 10013018 PA@ @.....L...0. 020000b0: 00208810 000c2280 081805a8 88800010 . ...."...... 020000c0: 000c020a 0012b024 01282c02 00808181 ...... $.(,..... 020000d0: 00010824 0160b602 81621008 00828082 ...$.`...b...... 020000e0: 38d0f028 42010e03 1d242290 02000120 8..(B....$".... 020000f0: 6c217230 00920800 20200d40 41c08011 l!r0.... .@A... => mw 2000000 ffffaaaa 100 => md 2000000 02000000: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000010: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000020: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000030: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000040: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000050: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000060: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000070: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000080: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 02000090: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000a0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000b0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000c0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000d0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000e0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 020000f0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... => usb write 2000000 0 100
USB write: device 0 block # 0, count 256 ... 256 blocks write: OK => md 1000000 01000000: fbf3eae6 2feeffbf dbf7775d ff5bebf7 ..../.....w].[.. 01000010: abefefaf 7dbb3e3b bfffb5bb bfb86a7f ....}.>;...... j. 01000020: eff7b68f deaadfff eebf7bff bd7fed1f ...... {..... 01000030: ffef7deb e7bfbbef dfeff7df 7f3ffcba ..}...... ?.. 01000040: ab3bfbfe dfdee69b ffe18fd5 ff3e777f .;...... >w. 01000050: da7effef bfabff7f f58ef768 9ffffeff .~...... h.... 01000060: cfebf8b0 f1b7dfef e9eefbfe f37bbadb ...... {.. 01000070: b7f34ea2 da7efbff dfdff7ff f7effde3 ..N..~......
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 103 Linux Kernel Drivers Universal Serial Bus Interfaces
01000080: fffbebff fe56ff5d 6ffd7ffd ff87efdf .....V.]o...... 01000090: b6bfafac ddebfbfb ffacebfd f87bff9f ...... {.. 010000a0: ffebffff ff7e7ff9 aefefd7f 5f7f5ebf .....~...... _.^. 010000b0: 6fe87e7b fabfdbcf d3faefad 6fbb5e7a o.~{...... o.^z 010000c0: f6af86de ffdb7bbf ff5ff6ba bfa4bfdf ...... {.._...... 010000d0: ffbfa87f ffe67fcd efeffb9a 9b7e6a6f ...... ~jo 010000e0: fffcf76f efbfeebb ffaceab1 5cfbfffe ...o...... \... 010000f0: edebffde e29fefff deaeafdb f97bdff5 ...... {.. => usb read 1000000 0 100
USB read: device 0 block # 0, count 256 ... 256 blocks read: OK => md 1000000 01000000: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000010: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000020: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000030: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000040: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000050: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000060: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000070: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000080: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 01000090: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000a0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000b0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000c0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000d0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000e0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... 010000f0: ffffaaaa ffffaaaa ffffaaaa ffffaaaa ...... =>
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 - 437
* 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)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 104 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
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 8859-1 (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] 3907583 512-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] 3907583 512-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
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, 2000682496 bytes
64 heads, 63 sectors/track, 969 cylinders
Units = cylinders of 4032 * 512 = 2064384 bytes
Device Boot Start End Blocks Id System
/dev/sda1 1 969 1953439+ b Win95 FAT32
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 105 Linux Kernel Drivers Universal Serial Bus Interfaces
~ # 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) 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 1.41.4 Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) 65536 inodes, 262094 blocks 13104 blocks (5.00%) reserved for the super user First data block=0 Maximum filesystem blocks=268435456 8 block groups 32768 blocks per group, 32768 fragments per group 8192 inodes per group Superblock backups stored on blocks: 32768, 98304, 163840, 229376
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 106 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
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 --->
<*> 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 107 Linux Kernel Drivers Universal Serial Bus Interfaces
usb 1-1.1: configuration #1 chosen from 1 choice
input: Dell Dell USB Keyboard Hub as /class/input/input1
generic-usb 0003:413C:2002.0002: 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:2002.0003: 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:3010.0001: input: USB HID v1.00 Mouse [HID 413c:3010] on u
Power Management Following Pwr. Mgmt. features are supported: 1) Sleep 2) Deep Sleep
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 108 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
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 519.108 msecs PM: late suspend of devices complete after 0.489 msecs PM: noirq suspend of devices complete after 0.555 msecs Disabling non-boot CPUs ...
USB Flash drive inserted --->
Enabling non-boot CPUs ... CPU1 is up PM: noirq resume of devices complete after 0.513 msecs PM: early resume of devices complete after 0.349 msecs fsl-lbc ffe05000.localbus: Chip select error: LTESR 0x00080000 /pcie@ffe09000: PCICSRBAR @ 0xfff00000 /pcie@ffe0a000: PCICSRBAR @ 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: PCICSRBAR @ 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 = 0xa0000000 ata2: SATA link down (SStatus 0 SControl 300) ata1: Signature Update detected @ 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 5419.653 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] 15568896 512-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: 43 00 00 00 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 109 Linux Kernel Drivers Universal Serial Bus Interfaces
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 0.001 seconds) done. Freezing remaining freezable tasks ... (elapsed 0.001 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 316.061 msecs PM: late suspend of devices complete after 0.217 msecs PM: noirq suspend of devices complete after 31.099 msecs Disabling non-boot CPUs ... /pcie@ffe240000: PCICSRBAR @ 0xff000000 /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. /pcie@ffe240000: DMA window size is 0xe0000000 /pcie@ffe250000: PCICSRBAR @ 0xff000000 /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 0xe0000000 /pcie@ffe260000: PCICSRBAR @ 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: PCICSRBAR @ 0xff000000 /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 0xe0000000
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 63.844 msecs PM: early resume of devices complete after 0.166 msecs caam ffe300000.crypto: Instantiated RNG4 SH0 caam ffe300000.crypto: Instantiated RNG4 SH1 ata2: No Device OR PHYRDY change,Hstatus = 0x80000000 ata2: SATA link down (SStatus 10 SControl 300) ata1: Signature Update detected @ 504 msecs ata1: SATA link up 3.0 Gbps (SStatus 123 SControl 300)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 110 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
ata1.00: configured for UDMA/133 sd 0:0:0:0: [sda] Starting disk PM: resume of devices complete after 4461.429 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] 7843200 512-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.
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 dual- phy 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.
6.9.2 USB Gadget Memory Driver User Manual 6.9.2.1 USB 2.0 Gadget Memory Driver User Manual
Description The NXP processor has a High speed Dual-Role(DR) USB controller, which supports device mode.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 111 Linux Kernel Drivers Universal Serial Bus Interfaces
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
Kernel Configure Tree View Options
Kernel Configure Tree View Options Description
Need to enable Device Drivers ---> CONFIG_USB_FSL_MPH_DR_OF
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
Enable NXP USB Device Controller Device Drivers ---> support
USB support --->
USB Gadget Support --->
< M > Support for USB Gadgets
USB Peripheral Controller (Freescale Highspeed USB DR Peripheral Controller) --->
< M > 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 > Mass Storage Gadget
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 112 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Compile-time Configuration Options
Option Values Default Value Description
CONFIG_USB_SUPPORT y/n/m y Enables 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_FSL_USB2 y/n/m m Enable NXP USB peripheral controller
CONFIG_USB_MASS_STORAGE y/n/m m Enable File Storage Gadget
Source Files The driver source is maintained in the Linux kernel source tree.
Source File Description
drivers/usb/gadget/fsl_usb2_udc.[ch] NXP USB peripheral controller driver
drivers/usb/host/fsl-mph-dr-of.c Hook between OF tree and platform device
drivers/usb/gadget/mass_storage.c Memory gadget driver
Device Tree Entry
usb@22000 {
#address-cells = <1>;
#size-cells = <0>;
compatible = "fsl-usb2-
"fsl-usb2-
reg = <0x22000 0x1000>; /* 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 113 Linux Kernel Drivers Universal Serial Bus Interfaces
For USB1 controller, to configure for gadget mode: => setenv hwconfig 'usb1:dr_mode=peripheral,phy_type=
Test Procedure For board specific changes (required for USB Gadget mode), please refer board BSP user manual Preparation 1. Bring all USB Gadget modules (driver/usb/gadget/*.ko including fs/configfs/configfs.ko) onto the target board using tftp. 2. Create a (e.g. 16MB) file backed storage as under on the target:
bash# dd bs=1M count=16 if=/dev/zero of=/root/bkup
16+0 records in
16+0 records out
3. Load device controller driver and test mass-storage gadget a. Load FSL USB Gadget driver module
bash# insmod udc-core.ko bash# insmod fsl_usb2_udc.ko
b. Load Mass storage module
bash# insmod configfs.ko bash# insmod libcomposite.ko bash# insmod usb_f_mass_storage.ko bash# insmod g_mass_storage.ko file=/root/bkup Number of LUNs=8 Mass Storage Function, version: 2009/09/11 LUN: removable file: (no medium) Number of LUNs=1 LUN: file: /root/bkup Number of LUNs=1 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
4. Connect a USB cable between USB port of target board and the USB port on Windows machine(host). The following message pops up on the target. At the same time XP recognizes the USB storage device and Windows configures and installs its driver.
bash# g_mass_storage gadget: high-speed config #1: Linux File-Backed Storage
5. To see the driver letter for the newly found USB storage, create a partition in /root/bkup on the target:
bash# fdisk /root/bkup
Device contains neither a valid DOS partition table, nor Sun, SGI or OSF disklabel Building a new DOS disklabel with disk identifier 0x8a12fec0. Changes will remain in memory only, until you decide to write them.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 114 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
After that, of course, the previous content won't be recoverable.
You must set cylinders. You can do this from the extra functions menu. Warning: invalid flag 0x0000 of partition table 4 will be corrected by w(rite)
Command (m for help): x
Expert command (m for help): s Number of sectors (1-63, default 63): 8 Warning: setting sector offset for DOS compatiblity
Expert command (m for help): h Number of heads (1-256, default 255): 16
Expert command (m for help): c Number of cylinders (1-1048576): 1024
Expert command (m for help): r
Command (m for help): p
Disk /root/bkup: 0 MB, 0 bytes 16 heads, 8 sectors/track, 1024 cylinders Units = cylinders of 128 * 512 = 65536 bytes Disk identifier: 0x8a12fec0
Device Boot Start End Blocks Id System
Command (m for help): n
Command action
e extended p primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-1024, default 1): Using default value 1 Last cylinder or +size or +sizeM or +sizeK (1-1024, default 1024): Using default value 1024
Command (m for help): p
Disk /root/bkup: 0 MB, 0 bytes 16 heads, 8 sectors/track, 1024 cylinders Units = cylinders of 128 * 512 = 65536 bytes Disk identifier: 0x8a12fec0
Device Boot Start End Blocks Id System
/root/bkup1 1 1024 65532 83 Linux
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 115 Linux Kernel Drivers Universal Serial Bus Interfaces
Command (m for help): w
The partition table has been altered! Calling ioctl() to re-read partition table. WARNING: Re-reading the partition table failed with error 25: Inappropriate ioctl for device. The kernel still uses the old table. The new table will be used at the next reboot. Syncing disks.
bash# fdisk -lu /root/bkup
You must set cylinders. You can do this from the extra functions menu.
Disk /root/bkup: 0 MB, 0 bytes 16 heads, 8 sectors/track, 0 cylinders, total 0 sectors Units = sectors of 1 * 512 = 512 bytes Disk identifier: 0x8a12fec0
Device Boot Start End Blocks Id System
/root/bkup1 8 131071 65532 83 Linux
6. Run losetup to setup the loopback device with offset (8*512 = 1024) and create an ext2 file system
bash# losetup -o 4096 /dev/loop0 /root/bkup bash# mke2fs /dev/loop0 mke2fs 1.41.4 (27-Jan-2009) Filesystem label= OS type: Linux Block size=1024 (log=0) Fragment size=1024 (log=0) 4096 inodes, 16380 blocks 819 blocks (5.00%) reserved for the super user First data block=1 Maximum filesystem blocks=16777216 2 block groups 8192 blocks per group, 8192 fragments per group 2048 inodes per group Superblock backups stored on blocks: 8193
Writing inode tables: done Writing superblocks and filesystem accounting information: done This filesystem will be automatically checked every 24 mounts or 180 days, whichever comes first. Use tune2fs -c or -i to override.
7. Now a drive letter should appear for the USB storage device on Windows XP and should be able to read/write
Supporting Documentation Linux USB gadget framework - http://www.linux-usb.org/gadget/ Further details about Linux USB file backed storage - http://www.linux-usb.org/gadget/file_storage.html
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 116 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Known Limitations/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.
6.9.3 USB Gadget Network Driver User Manual 6.9.3.1 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 5. 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
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
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 117 Linux Kernel Drivers Universal Serial Bus Interfaces
Table 5. Kernel Configure Tree View Options (continued)
Kernel Configure Tree View Options Description
Enable USB Gadget support
Device Drivers --->
USB support --->
USB Gadget Support --->
< M > Support for USB Gadgets
USB Gadget Drivers
Table 6. Compile-time Configuration Options
Options Values Default Description
CONFIG_USB_SUPPORT y/n/m Ym Enable USB Support
CONFIG_USB_FSL_MPH_ y/n/m Y Enable NXP EHCI USB DR_OF controller
CONFIG_USB_GADGET y/n/m m Enable USB Gadget modules
CONFIG_USB_GADGET_F y/n/m m Enable NXP USB peripheral SL_USB2 controller
CONFIG_USB_ETH y/n/m m Enable Ethernet Gadget
CONFIG_USB_ETH_RNDI y/n y Enable Ethernet Gadget S
Source Files The driver source is maintained in the Linux kernel source tree.
Table 7. Source Files
Source File Description
drivers/usb/gadget/fsl_usb2_udc.c NXP USB peripheral controller driver
drivers/usb/host/fsl-mph-dr-of.c Hook between OF tree and platform device
drivers/usb/gadget/ether.c Ethernet gadget driver
Drivers/usb/gadget/rndis.[ch] Microsoft’s RNDIS support
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 118 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Device Tree Entry
usb@22000 {
#address-cells = <1>; #size-cells = <0>; compatible = "fsl-usb2-
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=
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 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 119 Linux Kernel Drivers Universal Serial Bus Interfaces
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 usb0 10.232.1.11 netmask 255.255.255.0 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:10.232.1.11 Bcast:10.232.1.255 Mask:255.255.255.0 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:
http://embedded.seattle.intel-research.net/wiki/index.php? 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:
http://www.davehylands.com/linux/gumstix/usbnet/linux.inf http://embedded.seattle.intel-research.net/wiki/files/linux.inf
For Windows 7, driver will automatically install. 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 10.232.1.10 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 RNDIS@Windows and usb0@linux
D:\Profiles>ping 10.232.1.11
Pinging 10.232.1.11 with 32 bytes of data:
Reply from 10.232.1.11: bytes=32 time<1ms TTL=64 Reply from 10.232.1.11: bytes=32 time<1ms TTL=64 Reply from 10.232.1.11: bytes=32 time<1ms TTL=64
Ping statistics for 10.232.1.11: Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 120 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Approximate round trip times in milli-seconds: Minimum = 0ms, Maximum = 0ms, Average = 0ms
bash# ping 10.232.1.10
PING 10.232.1.10 (10.232.1.10): 56 data bytes
64 bytes from 10.232.1.10: seq=0 ttl=128 time=4.352 ms 64 bytes from 10.232.1.10: seq=1 ttl=128 time=1.015 ms 64 bytes from 10.232.1.10: seq=2 ttl=128 time=0.974 ms 64 bytes from 10.232.1.10: seq=3 ttl=128 time=0.935 ms 64 bytes from 10.232.1.10: seq=4 ttl=128 time=1.021 ms
--- 10.232.1.10 ping statistics ---
5 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 - http://www.linux-usb.org/gadget/ Please refer to http://embedded.seattle.intel-research.net/wiki/index.php?title=Setting_up_USBnet for setting up the RNDIS on Windows XP. Linux USBnet @ http://www.linux-usb.org/usbnet/
6.9.4 USB 3.0 Host/Peripheral Linux Driver User Manual 6.9.4.1 USB 3.0 Host/Peripheral Linux Driver User Manual
Description The driver supports xHCI SuperSpeed (SS) Dual-Role-Device (DRD) controller
Main features of xHCI controller • Supports operation as a standalone USB xHCI host controller • USB dual-role operation and can be configured as host or device • 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 121 Linux Kernel Drivers Universal Serial Bus Interfaces
• 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
Enables XHCI Host Controller Driver and transaction translator Device Drivers--->
USB support ---> <*> xHCI HCD (USB 3.0) support
Enable support for USB mass storage Device Drivers---> devices. This is the driver needed for USB flash devices, and memory sticks USB support ---> <*> USB Mass Storage support
[ ] USB Mass Storage verbose debug
Enables support for USB Audio devices. <*> Sound card support ---> <*> Advanced Linux Sound Architecture ---> This driver is needed for USB <*> OSS Mixer API microphone. <*> OSS PCM (digital audio) API [*] OSS PCM (digital audio) API - Include plugin system [*] Support old ALSA API [*] USB sound devices ---> <*> USB Audio/MIDI driver
Note: Required only for USB Gadget/ Device Drivers---> Peripheral Support
USB support ---> • Enable driver for peripheral/device <*> USB Gadget Support ---> controller
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 122 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Table continued from the previous page...
Kernel Configure Tree View Options Description
Enable XHCI DRD Core Support Device Drivers--->
<*> DesignWare USB3 DRD Core Support
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
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 123 Linux Kernel Drivers Universal Serial Bus Interfaces
Table continued from the previous page...
Source File Description
drivers/usb/host/xhci-* xhci platform driver
drivers/usb/gadget/mass_storage.c USB Mass Storage
drivers/usb/gadget/ether.c Ethernet gadget driver
Device Tree Binding for Host
usb@3100000 { compatible = "snps,dwc3"; reg = <0x0 0x3100000 0x0 0x10000>; interrupts =
Device Tree Binding for Peripheral
usb@3100000 { compatible = "snps,dwc3"; reg = <0x0 0x3100000 0x0 0x10000>; interrupts =
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 0x03100000 hub 1-0:1.0: USB hub found hub 1-0:1.0: 1 port detected xhci-hcd xhci-hcd.0.auto: xHCI Host Controller xhci-hcd xhci-hcd.0.auto: new USB bus registered, assigned bus number 2 hub 2-0:1.0: USB hub found hub 2-0:1.0: 1 port detected usbcore: registered new interface driver usb-storage
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 124 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
sd 0:0:0:0: [sda] 1957887 512-byte logical blocks: (1.00 GB/955 MiB) sd 0:0:0:0: Attached scsi generic sg0 type 0 sd 0:0:0:0: [sda] Write Protect is off sd 0:0:0:0: [sda] No Caching mode page found sd 0:0:0:0: [sda] Assuming drive cache: write through sd 0:0:0:0: [sda] No Caching mode page found sd 0:0:0:0: [sda] Assuming drive cache: write through sda: sda1 sd 0:0:0:0: [sda] No Caching mode page found sd 0:0:0:0: [sda] Assuming drive cache: write through sd 0:0:0:0: [sda] Attached SCSI removable disk
For Super-Speed Device attach # usb 2-1: new SuperSpeed USB device number 2 using xhci-hcd usb 2-1: Parent hub missing LPM exit latency info. Power management will be impacted. usb-storage 2-1:1.0: USB Mass Storage device detected scsi0 : usb-storage 2-1:1.0 scsi 0:0:0:0: Direct-Access SanDisk Extreme 0001 PQ: 0 ANSI: 6 sd 0:0:0:0: [sda] 31277232 512-byte logical blocks: (16.0 GB/14.9 GiB) sd 0:0:0:0: Attached scsi generic sg0 type 0 sd 0:0:0:0: [sda] Write Protect is off sd 0:0:0:0: [sda] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA sda: sd 0:0:0:0: [sda] Attached SCSI removable disk FAT-fs (sda): Volume was not properly unmounted. Some data may be corrupt. Please run fsck.
Make filesystem and mount connected USB flash drive using below commands
root@freescale /$ fdisk -l
Disk /dev/sda: 16.0 GB, 16013942784 bytes 255 heads, 63 sectors/track, 1946 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes
Device Boot Start End Blocks Id System /dev/sda1 1 1946 15631213+ 83 Linux root@freescale /$ root@freescale /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm 516684 0 516684 0% /dev/shm rwfs 512 0 512 0% /mnt/rwfs root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ fdisk /dev/sda
The number of cylinders for this disk is set to 1946. There is nothing wrong with that, but this is larger than 1024, and could in certain setups cause problems with: 1) software that runs at boot time (e.g., old versions of LILO) 2) booting and partitioning software from other OSs (e.g., DOS FDISK, OS/2 FDISK)
Command (m for help): d Selected partition 1
Command (m for help): n Command action e extended
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 125 Linux Kernel Drivers Universal Serial Bus Interfaces
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, 16013942784 bytes 255 heads, 63 sectors/track, 1946 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes
Device Boot Start End Blocks Id System /dev/sda1 1 1946 15631213+ 83 Linux root@freescale /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm 516684 0 516684 0% /dev/shm rwfs 512 0 512 0% /mnt/rwfs root@freescale /$ mkdir my_mnt root@freescale /$ root@freescale /$ root@freescale /$ mkfs.ext2 /dev/sda1 Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) 977280 inodes, 3907803 blocks 195390 blocks (5%) reserved for the super user First data block=0 Maximum filesystem blocks=4194304 120 block groups 32768 blocks per group, 32768 fragments per group 8144 inodes per group Superblock backups stored on blocks: 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208 root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ mount /dev/sda1 my_mnt/ root@freescale /$ root@freescale /$ root@freescale /$ root@freescale /$ df Filesystem 1K-blocks Used Available Use% Mounted on shm 516684 0 516684 0% /dev/shm rwfs 512 0 512 0% /mnt/rwfs /dev/sda1 15385852 20 14604272 0% /my_mnt root@freescale /$
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 126 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
Test by wring/reading data on mount drive
root@freescale /$ dd if=/dev/urandom of=/tmp/123 bs=1M count=100 100+0 records in 100+0 records out 104857600 bytes (100.0MB) copied, 54.535026 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
usbcore: registered new interface driver usb-storage
Make sure "dr_mode" contains "peripheral" string
# cat /proc/device-tree/soc/usb\@3100000/dwc3/dr_mode peripheralroot@ls1021aqds:~#
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@ls1021aqds:/home# mkdir /mnt/ramdrive root@ls1021a~# mount -t tmpfs tmpfs /mnt/ramdrive -o size=600M roo~# dd if=/dev/zero of=/mnt/ramdrive/vfat-file bs=1M count=500 root@ls1021aqds:/home# mke2fs -F /mnt/ramdrive/vfat-file root@ls1021aqds:/home# insmod configfs.ko root@ls1021aqds:/home# insmod libcomposite.ko ro~# insmod g_mass_storage.ko file=/mnt/ramdrive/vfat-file stall=n
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 127 Linux Kernel Drivers Universal Serial Bus Interfaces
We will get below messages
[ 39.987594] g_mass_storage gadget: Mass Storage Function, version: 2009/09/11 [ 39.994822] g_mass_storage gadget: Number of LUNs=1 [ 39.989240] lun0: LUN: file: /home/backing_file_20mb [ 39.994367] g_mass_storage gadget: Mass Storage Gadget, version: 2009/09/11 [ 39.990902] g_mass_storage gadget: userspace failed to provide iSerialNumber [ 39.987547] g_mass_storage gadget: g_mass_storage ready
Attached ***USB3.0 only*** gadget cable to host and you will get below message. Now Storage is ready to use.
g_mass_storage gadget: super-speed config #1: Linux File-Backed Storage
Speaker and Microphone
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 sgtl5000-0 [ ] Subdevices: 1/1 Subdevice #0: subdevice #0 card 1: USB [Jabra SPEAK 410 USB], device 0: USB Audio [USB Audio] Subdevices: 1/1 Subdevice #0: subdevice #0
2. Sample wav file can be played using the below command:
[root@freescale ~]$ aplay -D hw:1,0 LYNC_fsringing.wav Playing WAVE 'LYNC_fsringing.wav' : Signed 16 bit Little Endian, Rate 48000 Hz, Stereo
3. Sample wav file can be recorded using the below command:
[root@freescale ~]$ arecord -f S16_LE -t wav -Dhw:1,0 -r 16000 foobar.wav -d 5 Recording WAVE 'foobar.wav' : Signed 16 bit Little Endian, Rate 16000 Hz, Mono
NOTE: If recorded audio is not played, try to use "-D plughw:1,0" in above command. 4. Audio controls can be checked using the below command, control details and name of the controls can be checked from output of “amixer –c1” as below:
[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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 128 NXP Semiconductors Linux Kernel Drivers Universal Serial Bus Interfaces
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]
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@ls1021aqds:/home# insmod configfs.ko root@ls1021aqds:/home# insmod libcomposite.ko root@ls1021aqds:/home# insmod u_ether.ko root@ls1021aqds:/home# insmod u_rndis.ko root@ls1021aqds:/home# insmod usb_f_ecm.ko root@ls1021aqds:/home# insmod usb_f_ecm_subset.ko root@ls1021aqds:/home# insmod usb_f_rndis.ko root@ls1021aqds:/home# insmod g_ether.ko
We will get below messages
[ 28.692611] using random self ethernet address [ 28.697156] using random host ethernet address [ 28.694271] usb0: HOST MAC 82:96:69:7e:a5:7d [ 28.698928] usb0: MAC 72:00:a5:80:2b:e8 [ 28.692586] using random self ethernet address [ 28.697080] using random host ethernet address
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 129 Linux Kernel Drivers Universal Serial Bus Interfaces
[ 28.691368] g_ether gadget: Ethernet Gadget, version: Memorial Day 2008 [ 28.698028] g_ether gadget: g_ether ready
Make sure USB0 ethernet interface is available after this
root@ls1021aqds:/home# ifconfig -a can0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 NOARP MTU:16 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:10 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Interrupt:158
can1 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 NOARP MTU:16 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:10 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) Interrupt:159
eth0 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)
eth1 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)
eth2 Link encap:Ethernet HWaddr 00:E0:0C:BC:E5:62 inet addr:10.232.132.212 Bcast:10.232.135.255 Mask:255.255.252.0 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:290810 (283.9 KiB) TX bytes:8976 (8.7 KiB)
lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 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)
sit0 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 130 NXP Semiconductors Linux Kernel Drivers Watchdog Timers
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
usb0 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
root@ls1021aqds:/home# ifconfig usb0 10.232.1.11 root@ls1021aqds:/home# root@ls1021aqds:/home# root@ls1021aqds:/home# ping usb 10.232.1.10 PING 10.232.1.10 (10.232.1.10): 56 data bytes 64 bytes from 10.232.1.10: seq=0 ttl=128 time=5.294 ms 64 bytes from 10.232.1.10: seq=1 ttl=128 time=6.101 ms 64 bytes from 10.232.1.10: seq=2 ttl=128 time=4.170 ms 64 bytes from 10.232.1.10: seq=3 ttl=128 time=4.233 ms
Known Bugs, Limitations, or Technical Issues • 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-009116 (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.
6.10 Watchdog Timers
6.10.1 Watchdog Device Driver User Manual LS1012A
Description Watchdog driver description here.
Module Loading Watchdog device driver support kernel built-in mode.
U-Boot Configuration Runtime options
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 131 Linux Kernel Drivers Watchdog Timers
Env Variable Env Description Sub option Option Description
bootargs Kernel command line argument setenv othbootargs Sets the watchdog timer period passed to kernel wdt_period=35 timeout
Kernel Configure Options
Kernel Configure Tree View Options
Kernel Configure Tree View Options Description
IMX2 Watchdog Timer Device Drivers --->
[*] Watchdog Timer Support --->
[*] Disable watchdog shutdown on close
[*] IMX2+ Watchdog
Compile-time Configuration Options
Option Values Default Value Description
CONFIG_IMX2_WDT y/n y IMX2 Watchdog Timer
Source Files The driver source is maintained in the Linux kernel source tree.
Source File Description
drivers/watchdog/imx2_wdt.c IMX2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 132 NXP Semiconductors Linux Kernel Drivers Watchdog Timers
· 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.
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 133 Linux Kernel Drivers Watchdog Timers
login in system, run command "watchdog /dev/watchdog"
root@p1020rdb:~# watchdog /dev/watchdog
root@p1020rdb:~# ps -ae | grep watchdog
3285 ? 00:00:00 watchdog
root@p1020rdb:~#
wait for some minutes, if system is still alive, watchdog feeding is OK
· check watchdog reboot operation
run command "killall"
root@p1020rdb:~# killall -9 watchdog
root@p1020rdb:~#
root@p1020rdb:~# ps -ae | grep watchdog
root@p1020rdb:~#
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 134 NXP Semiconductors Linux Kernel Drivers Watchdog Timers
root@p1020rdb:~# PowerPC Book-E Watchdog Exception
wait for some seconds, if system reboots, watchdog reboot operation is OK
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 135 Additional Linux Use Cases Power Management Chapter 7 Additional Linux Use Cases
7.1 Power Management 7.1.1 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, 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
Enable the FTM alarm (FlexTimer module) driver Device Drivers ---> SOC (System On Chip) specific Drivers --->
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 136 NXP Semiconductors 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 CONFIG_SUSPEND
wake by Flextimer LS1012, LS1021 CONFIG_FTM_ALARM
CPU idle PW15 LS1012, LS1021 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,ls1012a-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 0x20000000>; status = "okay"; };
Refer to the Linux document: Documentation/devicetree/bindings/soc/fsl/rcpm.txt
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 137 Additional Linux Use Cases Power Management
Source Files The source files are maintained in the Linux kernel source tree.
Source File Description
drivers/soc/fsl/layerscape/ls-rcpm.c the RCPM driver needed by the sleep feature
drivers/soc/fsl/layerscape/ftm_alarm.c the FTM timer driver worked as a wakeup source
drivers/cpuidle/cpuidle-arm.c 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.
/* Because LS1012A only supports one low power mode, PW15/WFI. Linux uses a arch-specific fuction to enter idle instead of using the cpuidle driver. So "cat /sys/devices/system/cpu/cpuidle/current_driver" will return "none". */ # cat /sys/devices/system/cpu/cpuidle/current_driver
• Sleep and Wake up by FTM timer
/* Start a FTM timer. It will trigger an interrupt to wake up the system in 5 seconds. */ echo 5 > /sys/devices/platform/soc/29d0000.ftm0/ftm_alarm && echo mem > /sys/power/state
Supporting Documentation • QorIQ processor reference manuals
7.1.2 CPU Frequency Switching User Manual
Linux SDK for QorIQ Processors
Abbreviations and Acronyms DFS: Dynamic Frequency Scaling P2, T4, B4, ... : stand for P2xxx, T4xxx, B4xxx processors
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.
U-boot Configuration None
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 138 NXP Semiconductors Additional Linux Use Cases Power Management
Kernel Configure Tree View Options For Powerpc platform
Kernel Configure Tree View Options Description
Enable the CPU frequency driver for DFS Platform support --> CPU Frequency scaling --> [*] CPU Frequency scaling <*> CPU frequency translation statistics Default CPUFreq governor (userspace) --> -*- 'userspace' governor for userspace frequency scaling PowerPC CPU frequency scaling drivers ---> <*> CPU frequency scaling driver for Freescale QorIQ SoCs
CPU Frequency drivers --> [*] Support for Freescale MPC85xx CPU freq
For Layerscape platform
Kernel Configure Tree View Options Description
Enable the CPU frequency driver CPU Power Management --> 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 P2 CONFIG_MPC85xx_CPUFREQ
cpufreq DFS P3, P4, P5, T4, B4 CONFIG_QORIQ_CPUFREQ
User Space Application Simply using command "cat" and "echo" can verify this feature.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 139 Additional Linux Use Cases Power Management
Device Tree Binding
Property Type Status Description
#clock-cells unsigned int Required The number of cells in a clock-specifier
clock-output-names String Required Clock output name
clocks handle Required Clock source handle
compatible String Required Compatible strings
reg unsigned int Required register address range
Table continues on the next page...
For processors used old clock binding, like ls1021a:
clockgen: clocking@1ee1000 { #address-cells = <1>; #size-cells = <1>; ranges = <0x0 0x0 0x1ee1000 0x10000>;
sysclk: sysclk { compatible = "fixed-clock"; #clock-cells = <0>; clock-output-names = "sysclk"; };
cga_pll1: pll@800 { compatible = "fsl,qoriq-core-pll-2.0"; #clock-cells = <1>; reg = <0x800 0x10>; clocks = <&sysclk>; clock-output-names = "cga-pll1", "cga-pll1-div2", "cga-pll1-div4"; };
platform_clk: pll@c00 { compatible = "fsl,qoriq-core-pll-2.0"; #clock-cells = <1>; reg = <0xc00 0x10>; clocks = <&sysclk>; clock-output-names = "platform-clk", "platform-clk-div2"; };
cluster1_clk: clk0c0@0 { compatible = "fsl,qoriq-core-mux-2.0"; #clock-cells = <0>; reg = <0x0 0x10>; clock-names = "pll1cga", "pll1cga-div2", "pll1cga-div4"; clocks = <&cga_pll1 0>, <&cga_pll1 1>, <&cga_pll1 2>; clock-output-names = "cluster1-clk"; }; };
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 140 NXP Semiconductors Additional Linux Use Cases Power Management
For processors used new clock framework, like ls2085a and ls1043a:
clockgen: clocking@1ee1000 { compatible = "fsl,ls1043a-clockgen"; reg = <0x0 0x1ee1000 0x0 0x1000>; #clock-cells = <2>; clocks = <&sysclk>; };
Source Files The driver source is maintained in the Linux kernel source tree.
Table continued from the previous page...
Source File Description
drivers/cpufreq/qoriq_cpufreq.c 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 1199999 599999 299999 799999 399999 199999 1066666 533333 266666
2. check the CPU's current frequency # cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq 1199999
3. change the CPU's frequency we expect: # echo 799999 > /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.
Known Bugs, Limitations, or Technical Issues • On T4 series, when the CCB frequency is 666.667MHz, CPU frequency scaling can't work correctly. When CCB frequency is 600MHz, CPU frequency scaling works fine.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 141 Additional Linux Use Cases Power Management
Supporting Documentation • QorIQ processor reference manuals
7.1.3 System Monitor 7.1.3.1 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 http://dl.lm-sensors.org/lm-sensors/releases) 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. Kernel Configure Tree View Options
Option Description
Enables INA220 Device Drivers ---> <*> Hardware Monitoring support ---> <*> Texas Instruments INA219 and compatibles
Enables I2C block device driver support 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 bus multiplexing PCA9547 Device Drivers ---> <*> I2C bus multiplexing support Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 142 NXP Semiconductors Additional Linux Use Cases Power Management
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 =
Default node: i2c@118000 { pca9547@77 { compatible = "philips,pca9547"; reg = <0x77>; #address-cells = <1>; #size-cells = <0>;
channel@2 { #address-cells = <1>; #size-cells = <0>; reg = <0x2>;
ina220@40 { 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>;
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 143 Additional Linux Use Cases Power Management
}; }; };
Source Files The driver source is maintained in the Linux kernel source tree.
Source File Description
drivers/i2c/muxes/i2c-mux-pca954x.c PCA9547 driver
drivers/hwmon/ina2xx.c ina220 driver
Test Procedure Do the following to validate under the kernel 1. The bootup information is displayed:
...... i2c /dev entries driver mpc-i2c ffe118000.i2c: timeout 1000000 us mpc-i2c ffe118100.i2c: timeout 1000000 us mpc-i2c ffe119000.i2c: timeout 1000000 us mpc-i2c ffe119100.i2c: timeout 1000000 us 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 0-0077: registered 8 multiplexed busses for I2C mux pca9547 ina2xx 8-0040: power monitor ina220 (Rshunt = 1000 uOhm) ina2xx 8-0041: power monitor ina220 (Rshunt = 1000 uOhm) ina2xx 8-0045: power monitor ina220 (Rshunt = 1000 uOhm) ina2xx 8-0046: power monitor ina220 (Rshunt = 1000 uOhm) ina2xx 8-0047: power monitor ina220 (Rshunt = 1000 uOhm) ina2xx 8-0044: power monitor ina220 (Rshunt = 1000 uOhm) ......
2. # sensors ina220-i2c-8-40 Adapter: i2c-0-mux (chan_id 2) in0: +0.08 V in1: +1.06 V power1: 35.00 W curr1: +32.77 A
ina220-i2c-8-41 Adapter: i2c-0-mux (chan_id 2) in0: +0.01 V in1: +0.01 V power1: 60.00 mW curr1: +6.62 A
ina220-i2c-8-45
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 144 NXP Semiconductors Additional Linux Use Cases Power Management
Adapter: i2c-0-mux (chan_id 2) in0: +0.01 V in1: +0.00 V power1: 60.00 mW curr1: +8.20 A
ina220-i2c-8-46 Adapter: i2c-0-mux (chan_id 2) in0: +0.01 V in1: +0.01 V power1: 60.00 mW curr1: +6.60 A
ina220-i2c-8-47 Adapter: i2c-0-mux (chan_id 2) in0: +0.01 V in1: +0.02 V power1: 140.00 mW curr1: +7.40 A
ina220-i2c-8-44 Adapter: i2c-0-mux (chan_id 2) in0: +0.00 V in1: +1.51 V power1: 1.86 W curr1: +1.23 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 Description
Enables DCM driver Device Drivers ---> [*] Misc devices ---> <*> Freescale Data Collection Manager (DCM) driver
Compile-time Configuration Options
Option Values Default Value Description
CONFIG_FSL_DCM y/n y Enable DCM module
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 145 Additional Linux Use Cases Power Management
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@ffe124000 { 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 Description
drivers/misc/fsl_dcm.c DCM driver
Test Procedure Do the following to validate under the Kernel: 1. The bootup information is displayed:
...... Freescale Data Collection Module is installed......
2. 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: 25910 (mA) DDR voltage: 1348 (mV) DDR current: 740 (mA) CPU temperature: 38 (C)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 146 NXP Semiconductors Additional Linux Use Cases Power Management
7.1.3.2 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 Description
Enable thermal monitor chip driver like ADT7461. Device Drivers ---> [*] Hardware Monitoring support ---> [*] National Semiconductor LM90 and compatibles
Enable I2C PCA954x multiplexer support Device Drivers ---> <*> I2C bus multiplexing support ---> Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches
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 Description drivers/hwmon/hwmon.c Linux hwmon subsystem support
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 147 Additional Linux Use Cases Power Management
Table continued from the previous page...
Source File Description drivers/hwmon/lm90.c ADT7461 chip driver drivers/i2c/i2c-mux.c I2C bus multiplexing support drivers/i2c/muxes/pca954x.c 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 29000
2. You can use lm_sensors tools as follows. ~ # sensors
adt7461-i2c-1-4c Adapter: MPC adapter temp1: +34.0 C (low = +0.0 C, high = +85.0 C) (crit = +85.0 C, hyst = +75.0 C) temp2: +48.5 C (low = +0.0 C, high = +85.0 C) (crit = +85.0 C, hyst = +75.0 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"
7.1.3.3 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 148 NXP Semiconductors Additional Linux Use Cases Power Management
Kernel Configure Tree View Options Description
Enable monitor chip drivers like Device Drivers ---> ADT7461(ADT7481)/INA220, etc. [*] Hardware Monitoring support ---> [*] National Semiconductor LM90 and compatibles [*] Texas Instruments INA219 and compatibles
Enable I2C PCA954x multiplexer support Device Drivers ---> <*> I2C bus multiplexing support ---> Multiplexer I2C Chip support ---> <*> Philips PCA954x I2C Mux/switches
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"
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 100000KB (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: http://your.ip.address/senspix/sensors.cgi. 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 149 Additional Linux Use Cases Real Time Application Note
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.
7.2 Real Time Application Note 7.2.1 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 150 NXP Semiconductors Additional Linux Use Cases Real Time Application Note
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: Currently supported only for P4080DS, B4860qds, TWR-LS1021A, LS1012A, LS2080
Software: 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 Description
These options enable RT in Linux. Kernel options ---> Preemption Model (Fully Preemptible Kernel (RT)) ---> (X) Fully Preemptible Kernel (RT)
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
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 3.8.13-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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 151 Additional Linux Use Cases Real Time Application Note
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 https://rt.wiki.kernel.org
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 152 NXP Semiconductors Linux User Space OpenSSL Offload User's Guide Chapter 8 Linux User Space
8.1 OpenSSL Offload User's Guide 8.1.1 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 8.1.1.1 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 153 Linux User Space OpenSSL Offload User's Guide
Figure 2. OpenSSL interface with Linux kernel 8.1.1.1.1 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.
8.1.1.1.2 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 154 NXP Semiconductors 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 SHA1
8.1.2 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
8.1.3 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:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 155 Linux User Space OpenSSL Offload User's Guide
/etc/nginx/nginx.conf:
ssl_engine cryptodev; worker_processes 4; worker_cpu_affinity 0001 0010 0100 1000; #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 user- space 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 1710000.jr
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 156 NXP Semiconductors Linux User Space OpenSSL Offload User's Guide
29: 17835482 GIC 104 Level 1720000.jr 30: 17280913 GIC 105 Level 1730000.jr 31: 0 GIC 106 Level 1740000.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
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.
8.1.4 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 8. OpenSSL CipherSuite Compatibility
CipherSuite TLS Protocol Version
SSL_RSA_WITH_NULL_MD5 SSL3.0
SSL_RSA_WITH_NULL_SHA SSL3.0
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 157 Linux User Space OpenSSL Offload User's Guide
Table 8. OpenSSL CipherSuite Compatibility (continued)
CipherSuite TLS Protocol Version
SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL3.0
SSL_RSA_WITH_RC4_128_MD5 SSL3.0
SSL_RSA_WITH_RC4_128_SHA SSL3.0
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSL3.0
SSL_RSA_WITH_IDEA_CBC_SHA SSL3.0
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_RSA_WITH_DES_CBC_SHA SSL3.0
SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_DH_DSS_WITH_DES_CBC_SHA SSL3.0
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_DH_RSA_WITH_DES_CBC_SHA SSL3.0
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_DHE_DSS_WITH_DES_CBC_SHA SSL3.0
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_DHE_RSA_WITH_DES_CBC_SHA SSL3.0
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 SSL3.0
SSL_DH_anon_WITH_RC4_128_MD5 SSL3.0
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA SSL3.0
SSL_DH_anon_WITH_DES_CBC_SHA SSL3.0
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA SSL3.0
SSL_FORTEZZA_KEA_WITH_NULL_SHA SSL3.0
SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA SSL3.0
SSL_FORTEZZA_KEA_WITH_RC4_128_SHA SSL3.0
TLS_RSA_WITH_NULL_MD5 TLS1.0
TLS_RSA_WITH_NULL_SHA TLS1.0
TLS_RSA_EXPORT_WITH_RC4_40_MD5 TLS1.0
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 158 NXP Semiconductors Linux User Space OpenSSL Offload User's Guide
Table 8. OpenSSL CipherSuite Compatibility (continued)
CipherSuite TLS Protocol Version
TLS_RSA_WITH_RC4_128_MD5 TLS1.0
TLS_RSA_WITH_RC4_128_SHA TLS1.0
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 TLS1.0
TLS_RSA_WITH_IDEA_CBC_SHA TLS1.0
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_RSA_WITH_DES_CBC_SHA TLS1.0
TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_DES_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_DES_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_DES_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_DES_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 TLS1.0
TLS_DH_anon_WITH_RC4_128_MD5 TLS1.0
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA TLS1.0
TLS_DH_anon_WITH_DES_CBC_SHA TLS1.0
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_RSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_RSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_AES_128_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_AES_256_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_AES_128_CBC_SHA TLS1.0
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 159 Linux User Space OpenSSL Offload User's Guide
Table 8. OpenSSL CipherSuite Compatibility (continued)
CipherSuite TLS Protocol Version
TLS_DHE_DSS_WITH_AES_256_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_DH_anon_WITH_AES_128_CBC_SHA TLS1.0
TLS_DH_anon_WITH_AES_256_CBC_SHA TLS1.0
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_RSA_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA TLS1.0
TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA TLS1.0
TLS_RSA_WITH_SEED_CBC_SHA TLS1.0
TLS_DH_DSS_WITH_SEED_CBC_SHA TLS1.0
TLS_DH_RSA_WITH_SEED_CBC_SHA TLS1.0
TLS_DHE_DSS_WITH_SEED_CBC_SHA TLS1.0
TLS_DHE_RSA_WITH_SEED_CBC_SHA TLS1.0
TLS_DH_anon_WITH_SEED_CBC_SHA TLS1.0
TLS_ECDH_RSA_WITH_NULL_SHA TLS1.0
TLS_ECDH_RSA_WITH_RC4_128_SHA TLS1.0
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_ECDH_ECDSA_WITH_NULL_SHA TLS1.0
TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS1.0
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS1.0
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 160 NXP Semiconductors Linux User Space OpenSSL Offload User's Guide
Table 8. OpenSSL CipherSuite Compatibility (continued)
CipherSuite TLS Protocol Version
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_ECDHE_RSA_WITH_NULL_SHA TLS1.0
TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS1.0
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_ECDHE_ECDSA_WITH_NULL_SHA TLS1.0
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS1.0
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS1.0
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS1.0
TLS_ECDH_anon_WITH_NULL_SHA TLS1.0
TLS_ECDH_anon_WITH_RC4_128_SHA TLS1.0
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA TLS1.0
TLS_ECDH_anon_WITH_AES_128_CBC_SHA TLS1.0
TLS_ECDH_anon_WITH_AES_256_CBC_SHA TLS1.0
TLS_RSA_WITH_NULL_SHA256 TLS1.2
TLS_RSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_RSA_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_RSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_RSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_DH_RSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_DH_RSA_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_DH_RSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_DH_RSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_DH_DSS_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_DH_DSS_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_DH_DSS_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_DH_DSS_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS1.2
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 161 Linux User Space OpenSSL Offload User's Guide
Table 8. OpenSSL CipherSuite Compatibility (continued)
CipherSuite TLS Protocol Version
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS1.2
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 TLS1.2
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS1.2
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS1.2
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS1.2
TLS_DH_anon_WITH_AES_128_CBC_SHA256 TLS1.2
TLS_DH_anon_WITH_AES_256_CBC_SHA256 TLS1.2
TLS_DH_anon_WITH_AES_128_GCM_SHA256 TLS1.2
TLS_DH_anon_WITH_AES_256_GCM_SHA384 TLS1.2
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 162 NXP Semiconductors Boot Loaders Primary Protected Application (PPA) User's Guide Chapter 9 Boot Loaders
9.1 Primary Protected Application (PPA) User's Guide 9.1.1 Introduction 9.1.1.1 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.
9.1.1.2 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 163 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, 2012-2013
9.1.1.3 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
9.1.2 Boot Flow Architecture 9.1.2.1 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 164 NXP Semiconductors Boot Loaders Primary Protected Application (PPA) User's Guide
Secure World Non Secure World
1 2 GPP 1st Stage 2nd Stage Bootrom Bootloader* Bootloader*
3 4
SMC EL3 Kernel Lib init secure monitor
PSCI EL3 boot component TBD 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)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 165 Boot Loaders Primary Protected Application (PPA) User's Guide
SoC reset 1 Secure World Non Secure World
2 3 PBI State GPP 1st Stage 2nd Stage Machine Bootrom Bootloader* Bootloader*
4 6 5
SMC EL3 Kernel Lib init secure 7 EL3 boot component monitor
TBD PSCI EL2/EL1 boot component PPA
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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 166 NXP Semiconductors Boot Loaders Primary Protected Application (PPA) User's Guide
core reset 1 Secure World Non Secure World
GPP 1st Stage 2nd Stage Bootrom Bootloader* Bootloader*
2 3
power down SMC EL3 4 Lib init Kernel secure monitor
TBD PSCI
EL3 boot component PPA
EL2/EL1 boot component
EL3 boot/runtime
EL2/EL1 runtime
Legend
Figure 6. Secondary Core Execution Path
9.1.3 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 all levels of the data cache, 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
9.1.4 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 167 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 First optional parameter
X2 Second optional parameter
X3 Third optional parameter
SMC return values:
Register Meaning
X0 Return value, Error return code
9.1.5 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]. 9.1.5.1 PSCI_VERSION Get the Version number of this PSCI implementation. Function ID: 0x8400_0000 Input parameters:
Register Meaning
X0 Function ID
No other inputs
Return values:
Register Meaning
X0 bits[31:16] Major Version Number
X0 bits [15:0] 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 0x2.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 168 NXP Semiconductors Boot Loaders Primary Protected Application (PPA) User's Guide
9.1.5.2 CPU_ON Release a secondary core from reset, or from the CPU_OFF state. Function ID: 0xC400_0000 Input Parameters:
Register Meaning
X0 Function ID
X1 Target CPU, in MPIDR format (see [11])
X2 Start address (Physical)
X3 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 EL2.
9.1.5.3 CPU_OFF Power down the calling core. Function ID: 0x8400_0002 Input Parameters:
Register Meaning
X0 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 169 Boot Loaders Primary Protected Application (PPA) User's Guide
If successful, this function does not return.
9.1.5.4 CPU_SUSPEND Put the calling core/cluster/system into a low-power state. Function ID: 0xC400_0001 Input Parameters (see [11]):
Register Meaning
X0 Function ID
X1 Power_State
X2 Start_Address (Physical)
X3 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.
9.1.5.5 AFFINITY_INFO Get information about a specific affinity level. Function ID: 0xC400_0004 Input Parameters (see [11]):
Register Meaning
X0 Function ID
X1 Target_Affinity
X2 Lowest_Affinity
Return Values:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 170 NXP Semiconductors 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
9.1.5.6 SYSTEM_OFF Power down the entire system. Function ID: 0x8400_0008 Input Parameters:
Register Meaning
X0 Function ID
Return Values: The function does not return.
9.1.5.7 SYSTEM_RESET Perform a hard reset on the entire system. Function ID: 0x8400_0009 Input Parameters:
Register Meaning
X0 Function ID
Return Values: The function does not return.
9.1.5.8 PSCI Return Code Values
Mnemonic Value
SUCCESS 0
NOT_SUPPORTED -1
INVALID_PARAMETERS -2
DENIED -3
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 171 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 2
9.1.5.9 PSCI Functions Implemented, by SoC
LS1012A
CPU_ON N/A
CPU_OFF N/A
AFFINITY_INFO
CPU_SUSPEND WIP
PSCI_VERSION
SYSTEM_RESET
SYSTEM_OFF
9.1.6 SMC Function List Please see [2] for details of the SMC function interface. 9.1.6.1 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 Meaning
X0 Function ID
Return Values:
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 172 NXP Semiconductors Boot Loaders Primary Protected Application (PPA) User's Guide
Register Value
X0 Smc64 function count
9.1.6.2 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 Meaning
X0 Function ID
Return Values:
Register Value
X0 Smc32 function count
9.1.6.3 Get UUID Return the 128-bit UUID uniquely identifying this SMC implementation. Uses the smc32 interface. Function ID: 0x8200_FF01 Input Parameters:
Register Meaning
X0 Function ID
Return Values:
Register Value
X0 Bytes [3:0] of UUID
X1 Bytes [7:4] of UUID
X2 Bytes [11:8] of UUID
X3 Bytes [15:12] of UUID
9.1.6.4 Get Revision Return the major and minor revision numbers of the SIP portion of this SMC implementation. Uses smc32 interface. Function ID: 0x8200_FF03
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 173 Boot Loaders Primary Protected Application (PPA) User's Guide
Input Parameters:
Register Meaning
X0 Function ID
Return Values:
Register Value
X0 Major revision number of sip-smc
X1 Minor revision number of sip-smc
9.1.7 Building the PPA In the SDK, the PPA image will be built as part of the Yocto recipe.
9.1.8 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 174 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
Non-secure World Secure World
secure access driver SMC illegal access attempt EL1 trapped by PPA
malware SMC exception PPA EL3 return address
security error returned to registered access point
Figure 7. System Considerations When Calling SMC and PSCI Functions
9.2 Secure Boot: PBL Based Platforms
9.2.1 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 ESBC uboot performs minimal SoC configuration before validating the Next Executable using the same Trust 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 The validated ESBC uboot image is allowed to use the One Time Programmable Master confidentiality Key to decrypt system secrets. Cryptographic blob mechanism is used to establish Chain of trust with confidentiality.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 175 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.
9.2.2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 176 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
Figure 10. Secure Boot Process
9.2.3 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 177 Boot Loaders Secure Boot: PBL Based Platforms
NOR SECURE BOOT • P3/P4/P5
#LAW for ESBC 09000cd0 00000000 09138000 00000000 (Flush command) 09000cd4 c0000000 09138000 00000000 (Flush command) 09000cd8 81f0001d 09138000 00000000(FLUSH command) # Scratch Register 090e0200 c0b00000
• T1/T2/T4/B4
#LAW for ESBC 09000c10 00000000 09000c14 c0000000 09000c18 81f0001b # LAW for CPC/SRAM 09000d00 00000000 09000d04 bff00000 09000d08 81000013 # Scratch Registers 090e0200 c0b00000 090e0208 c0c00000 # CPC SRAM 09010100 00000000 09010104 bff00009 # CPC Configuration 09010f00 08000000 09010000 80000000
NAND SECURE BOOT • P3/P5
# SCRATCH REGISTER 090e0200 bff00000 09138000 00000000 (Flush Command) # CPC1 SRAM 09010000 00200400 09010100 00000000 09010104 bff0000b 09010f00 08000000 09010000 80000000 09138000 00000000 (Flush Command) # LAW for CPC/SRAM 09000d00 00000000 09000d04 bff00000 09000d08 81000013 09138000 00000000 (Flush Command) # Alternate Configuration Space Configuration 09000010 00000000 09000014 bf000000 09000018 81000000 09138000 00000000 (Flush Command) # CPC2 Cache 09110000 80000403
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 178 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
09110020 2d170008 09110024 00100008 09110028 00100008 0911002c 00100008 09138000 00000000 (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.
9.2.4 ISBC Phase 9.2.4.1 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 179 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.
9.2.4.2 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.
9.2.4.3 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 180 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
9.2.4.4 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 wear- out. To enable this feature, create PBI with pointers for both Primary and Alternate Images (HW PBL uses SCRATCHRW1 & SCRATCHRW3).
9.2.4.5 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.
Figure 11. ESBC with CSF Header
9.2.5 ESBC Phase 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 181 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). 9.2.5.1 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. 9.2.5.1.1 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 used for the 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.
9.2.5.1.2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 182 NXP Semiconductors 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.
Figure 12. Secure boot flow (Chain of Trust) 9.2.5.1.2.1 Sample Boot Script A sample boot script would look like:
... esbc_validate
9.2.5.1.2.1.1 esbc_validate command esbc_validate img_hdr [pub_key_hash] Input arguments: img_hdr - Location of CSF Header of the image to be validated
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 183 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
9.2.5.1.2.1.2 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.
9.2.5.1.3 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).
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 184 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
Figure 13. Chain of Trust with Confidentiality (Encapsulation)
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 185 Boot Loaders Secure Boot: PBL Based Platforms
Figure 14. Chain of Trust with Confidentiality (Decapsulation) 9.2.5.1.3.1 Sample Encap Boot Script A sample encap boot script would look like:
... blob enc
blob enc
blob enc
...
9.2.5.1.3.1.1 blob enc command blob enc
src location - Address of the image to be encapsulated
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 186 NXP Semiconductors 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.
9.2.5.1.3.2 Sample Decap Boot Script A sample decap boot script would look like:
... blob dec
9.2.5.1.3.2.1 blob dec command blob dec
9.2.6 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.
9.2.7 CST Tool 9.2.7.1 KEY GENERATION 9.2.7.1.1 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 187 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 - 1024 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 -- 1024, 2048, 4096. 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 2.0 ------# #------# #------#
======This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Generated SRK pair stored in : PUBLIC KEY srk.pub PRIVATE KEY srk.pri
$ ./gen_keys 4096 -k my.pub -p my.pri
#------# #------# #------CST (Code Signing Tool) Version 2.0 ------# #------# #------#
======This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 188 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
Generated SRK pair stored in : PUBLIC KEY my.pub PRIVATE KEY my.pri
9.2.7.1.2 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
$ ./gen_drv_drbg A2
#------# #------# #------CST (Code Signing Tool) Version 2.0 ------# #------# #------#
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 ______|______|______
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 189 Boot Loaders Secure Boot: PBL Based Platforms
DRV 0 | 63 - 32 | f4bfc65f DRV 1 | 31 - 0 | 16294daf
$ ./gen_drv_drbg A2 1652afe595631dec
#------# #------# #------CST (Code Signing Tool) Version 2.0 ------# #------# #------#
DRV[63:0] after Hamming Code is: 1652afe495631cea NAME | BITS | VALUE ______|______|______DRV 0 | 63 - 32 | 1652afe4 DRV 1 | 31 - 0 | 95631cea
9.2.7.1.3 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
$ ./gen_otpmk_drbg 2
#------# #------# #------CST (Code Signing Tool) Version 2.0 ------# #------# #------#
Input string not provided Generating a random string ------* Hash_DRBG library invoked
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 190 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
* Seed being taken from /dev/random ------OTPMK[255:0] is: 3feac02ce3583ad9077ab70f3a398cd71955f8bffa3191428cb25bb6bffb3113
NAME | BITS | VALUE ______|______|______OTPMKR 0 | 255-224 | 3feac02c OTPMKR 1 | 223-192 | e3583ad9 OTPMKR 2 | 191-160 | 077ab70f OTPMKR 3 | 159-128 | 3a398cd7 OTPMKR 4 | 127- 96 | 1955f8bf OTPMKR 5 | 95- 64 | fa319142 OTPMKR 6 | 63- 32 | 8cb25bb6 OTPMKR 7 | 31- 0 | bffb3113
$ ./gen_otpmk_drbg 2 1234567856485626a6f6e6174858583847720673534a8958c983774b848438fe
#------# #------# #------CST (Code Signing Tool) Version 2.0 ------# #------# #------#
OTPMK[255:0] is: ce3c563856584664a6b66617485a5e3d46720673534a8958c983774b848438fe
NAME | BITS | VALUE ______|______|______OTPMKR 0 | 255-224 | ce3c5638 OTPMKR 1 | 223-192 | 56584664 OTPMKR 2 | 191-160 | a6b66617 OTPMKR 3 | 159-128 | 485a5e3d OTPMKR 4 | 127- 96 | 46720673 OTPMKR 5 | 95- 64 | 534a8958 OTPMKR 6 | 63- 32 | c983774b OTPMKR 7 | 31- 0 | 848438fe
9.2.7.2 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 2.0 ------# #------# #------#
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 191 Boot Loaders Secure Boot: PBL Based Platforms
Correct Usage of Tool is:
./create_hdr_isbc [options]
************************************************************* * uni_sign is a wrapper script over the TOOL * Correct Usage (Description as specified above): * * ./uni_sign [options]
$ ./uni_sign input_uboot_secure
======This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Key Hash : 9288723a0253229000a70bcbaa9d3aa1acb70f6369e1e81c9225319d9a364e2a
HEADER file hdr_uboot.out created
9.2.7.2.1.1 Sample Input File and Output Sample input file to generate CSF Header is as follows –
------# Specify the platform. [Mandatory] # Choose Platform - 1010/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=0 ------# Entry Point/Image start address field in the header.[Mandatory] # (default=ADDRESS of first file specified in images) ENTRY_POINT=cffffffc ------
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 192 NXP Semiconductors 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 =
# 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=11111111 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]
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 193 Boot Loaders Secure Boot: PBL Based Platforms
HK_AREA_POINTER=bff00000 HK_AREA_SIZE=00010000 ------# Following field Required for 4240/9164/1040/C290 only # Specify Secondary Image Flag. (0 or 1) - [Optional] # (Default is 0) SEC_IMAGE= ------
Table 9. Description of fields.
Field Field Description
PLATFORM To identify the platform/SoC for which CF Header needs to be created.
ESBC 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 Entry Point address / Image start address field in the header.
PRI_KEY 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.
PUB_KEY 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.
KEY_SELECT 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)
IMAGE_1 - IMAGE_8 Create Entries for SG Table in the format { IMAGE_NAME, SRC_ADDR, DST_ADDR }
OEM_UID OEM UID to be populated in the header.
OEM_UID_1 OEM UID 1 to be populated in the header. Required Only for ls1
FSL_UID FSL UID to be populated in header.
FSL_UID_1 FSL UID 1 to be populated in header.Required Only for ls1
HK_AREA_POINTER House Keeping Area Starting Pointer Required by Sec (Required for Trust Arch v2.x devices only when esbc option is not provided)
HKAREA_SIZE House Keeping Area Size (Required for Trust Arch v2.x devices only when esbc option is not provided)
OUTPUT_HDR_FILENAME Name of the combined header binary to be created by tool
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 194 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
Table 9. Description of fields. (continued)
Field Field Description
SG_TABLE_ADDR Specify SG_TABLE Address where Scatter Gather table is present for 2041/3041/4080/5020/5040 when ESBC=0.
OUTPUT_SG_BIN Specify the output file name of sg table.
IMAGE_TARGET 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
SEC_IMG Flag for Secondary Image. Required for Trust Arch v2.x devices only
MP_FLAG Specify Manufacturing Protection Flag. Available for LS1 only.
VERBOSE Specify Verbose option. Contents of header generated will be printed.
9.2.7.2.2 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
$ ./uni_sign --verbose input_uboot_secure
======This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Key Hash : 9288723a0253229000a70bcbaa9d3aa1acb70f6369e1e81c9225319d9a364e2a
Image Hash :6c0048c92079b5e44152634a16d2463b808b5fd6ae23e7c42dcd30f49efafa8e ********** HEADER ************** barker:0x68392781 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 195 Boot Loaders Secure Boot: PBL Based Platforms
sg_flag 1 hkptr bff00000 hksize 10000 ********** SG TABLE ************ no of entries 1 entry 0 len 786432 ptr cff40000 SIGFNATURE file sign.out created HEADER file hdr_uboot.out created
9.2.7.2.3 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
$./uni_sign --hash input_uboot_secure
======This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Key Hash : 478c14568d8f76e822a2d483489a5ed9752c7c453b1fe5351f085a57fae2a30f
9.2.7.2.4 ISBC Key Extension (IE) 9.2.7.2.4.1 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.
9.2.7.2.4.2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 196 NXP Semiconductors 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)
9.2.7.2.4.3 IE Key Structure
Table 10. IE Key Structure which is embedded in header and placed in memory.
Offset Data Bits [0:31]
0x00-0x03 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
0x04-0x07 Total number of keys (Max N = 32 as 32 bit key revocation field is provided)
0x08-0x0b Key 1 length.
0x0c-0x40b Key 1 value.
0x40c-0x40f Key 2 length.
0x410-0x80f Key 2 value.
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 197 Boot Loaders Secure Boot: PBL Based Platforms
Table 10. IE Key Structure which is embedded in header and placed in memory. (continued)
Offset Data Bits [0:31]
- -
- Key N value
9.2.7.2.4.4 Sample Input File and Output This file is same as file described above in except fields required for IE Key extension highlighted in red.
------# Specify the platform. [Mandatory] # Choose Platform - 1040/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=c0b00000 ------# 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 =
# 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 =
# 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,7 ------# 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 198 NXP Semiconductors 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=11111111 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=00010000 ------# Following field Required for 4240/4860/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 Field Description
ESBC_HDRADDR ESBC Header address. It contains location of ESBC header in the memory
Table continues on the next page...
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 199 Boot Loaders Secure Boot: PBL Based Platforms
Table 11. Description of new fields introduced. (continued)
Field Field Description
IE_KEY Extension Public key filenames to be used by further level images. (File has to be in PEM format) FILE1 [,FILE2, FILE3, FILE4].
IE_REVOC 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.
9.2.7.2.4.5 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
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 200 NXP Semiconductors 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 except fields required for IE Key extension highlighted in red. CSF Header for bootscript
------# Specify the platform. [Mandatory] # Choose Platform - 1040/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=1 ------# Entry Point/Image start address field in the header.[Mandatory] # (default=ADDRESS of first file specified in images) ENTRY_POINT=e8a00000 ------# 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 =
# 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=8 ------# 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={,,} ------
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 201 Boot Loaders Secure Boot: PBL Based Platforms
# Specify OEM AND FSL ID to be populated in header. [Optional] # e.g FSL_UID=11111111 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=0x200 ------# 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 42409164/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 12. Description of new fields introduced.
Field Field Description
IE_KEY_SEL 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 202 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
9.2.7.2.5 Image Hash Generation (--img_hash) 9.2.7.2.5.1 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.
9.2.7.2.5.2 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 203 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 (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Key Hash : f1f18e7eaeb28cee50a30f5ba5d270b3e71b2c7c8382507ca8e7e4c110547eb2
HASH file hash.out created HEADER file esbc_hdr.out created
9.2.7.2.6 Help (--help) It prints help menu describing various options available.
9.2.7.3 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.
./gen_keys 1024
NOTE • Here, 1024 refers to the size of public key Modulus in bits.
• Other allowed sizes are - 2048 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.
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 204 NXP Semiconductors 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 (http://www.openssl.org/) This product includes cryptographic software written by Eric Young ([email protected]) ======
Key Hash : a9bb28a23c641e13b58c19a7fc48dfd8660a29895ebbc8bd0beba432e04c0785
HEADER file hdr_uboot.out created
The header would look like this:
00000000 68 39 27 81 00 00 02 00 00 00 01 00 00 00 14 00 |h9'...... | 00000010 00 00 00 80 00 00 16 00 00 00 00 01 11 07 f0 00 |...... | 00000020 00 00 00 01 00 00 00 01 11 11 11 11 99 99 99 99 |...... | 00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |...... | * 00000200 cc fe 4d fc 20 c1 6d ba 77 42 51 c2 4d c4 5b 45 |..M. .m.wBQ.M.[E| 00000210 41 e2 88 a9 55 d0 49 7b 86 fe 5a 85 89 68 b7 db |A...U.I{..Z..h..| 00000220 89 ef b7 2d 2a 1f 5b 74 4d 9c 7a c7 54 a9 b0 ff |...-*.[tM.z.T...| 00000230 cf a6 1c ed 3d f3 de 8d cc 91 ae 5f 60 b4 88 ab |....=...... _`...| 00000240 a5 70 0b 20 73 30 75 38 5b 1b 51 22 e7 2f fd a6 |.p. s0u8[.Q"./..| 00000250 65 00 07 4a 78 5d 1e ee 81 b8 a6 c4 81 e5 bc be |e..Jx]...... | 00000260 dc 64 09 c0 07 91 7a 36 ab 7c 0c e0 ab b1 01 bb |.d....z6.|...... | 00000270 de a0 e2 56 65 0a 29 73 67 57 d3 ba 1f 52 7a 5f |...Ve.)sgW...Rz_| 00000280 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |...... | * 000002f0 00 00 00 00 00 00 00 00 00 00 00 00 00 01 00 01 |...... | 00000300 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |...... | * 00001400 b3 6e 9e d5 3a 47 c6 44 4e 09 ff 29 0d a5 a1 c3 |.n..:G.DN..)....| 00001410 32 f3 b5 50 c6 42 f0 5b 59 29 f6 7d 57 0d 0a f9 |2..P.B.[Y).}W...| 00001420 22 d6 d8 68 57 85 2a e9 dd 15 18 c1 eb d3 03 d6 |"..hW.*...... | 00001430 8f 79 27 60 fa 4b 8c 1c 3e 7c db e6 3e 72 fd 8d |.y'`.K..>|..>r..| 00001440 50 25 d9 ee 0f 30 5a 3a cf 7e d4 3a dc 98 bc c9 |P%...0Z:.~.:....| 00001450 34 b3 8f 13 35 2e 55 1a f5 92 98 32 71 9c 8d 5b |4...5.U....2q..[| 00001460 8c f0 80 d2 1c 38 d5 a1 77 07 38 49 7c 7d 01 2f |.....8..w.8I|}./| 00001470 a1 c4 08 43 f5 af 67 7f d2 eb b9 e4 84 6c e1 77 |...C..g...... l.w| 00001480 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |...... | * 00001600 00 08 00 00 00 00 00 08 00 00 40 00 11 00 00 00 |...... @.....|
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 205 Boot Loaders Secure Boot: PBL Based Platforms 9.2.8 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. 9.2.8.1 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 0xc0000000 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 0xe0000000.
For useful commands of U-Boot and CCS, refer Useful U-Boot and CCS Commands 9.2.8.1.1 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.
9.2.8.1.2 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_
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 206 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms
The images will be created with the following names: u-boot-secure-boot.bin U-Boot binary image for Secure Boot uImage-
RCW files will be present in the path build_
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)
9.2.8.2 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. 9.2.8.2.1 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.
9.2.8.2.2 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/
QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 207 Boot Loaders Secure Boot: PBL Based Platforms
CST uses openssl libraries, version 0.9.8. 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_ Table 13. Platforms supported in SDK for Secure Boot Soc 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. 9.2.8.2.2.1 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 . QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 208 NXP Semiconductors 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/ ./uni_sign input_files/uni_sign/ ./uni_sign input_files/uni_sign/ 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/ 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 esbc_validate esbc_validate bootm 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/ QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 209 Boot Loaders Secure Boot: PBL Based Platforms 9.2.8.2.2.2 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 1024 -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/ Open input_files/uni_sign/ 4. Create CSF header for Linux uImage using different key pair. Repeat step 1 to generate another key pair. ./gen_keys 1024 -p lnx.priv -k lnx.pub Open input_files/uni_sign/ ./gen_keys 1024 -p rootfs.priv -k rootfs.pub Open input_files/uni_sign/ ./uni_sign input_files/uni_sign/ ./gen_keys 1024 -p dtb.priv -k dtb.pub Open input_files/uni_sign/ QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 210 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms a. Create a text file bootscript.txt with following commands. esbc_validate 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 1024 -p bs.priv -k bs.pub Open input_files/uni_sign/ ./uni_sign input_files/uni_sign/ 9.2.8.2.3 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 208 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 (Address map used for the 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 211 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. 9.2.8.3 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 212 NXP Semiconductors 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. 9.2.8.3.1 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. 9.2.8.3.2 Encap Bootscript 1. Create a bootscript_en.txt file with following commands: blob enc erase blob enc erase blob enc erase For the addresses to load images refer Section Address map used for the 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 9.2.8.3.3 Decap Bootscript 1. Create a bootscript_de.txt file with following commands: blob dec blob dec blob dec bootm 0x10000000 0x20000000 0x1000000 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 213 Boot Loaders Secure Boot: PBL Based Platforms For the addresses to load images refer Section Address map used for the 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 9.2.8.3.4 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/ 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/ Please change the binary name as per your bootscript in “IMAGE_1”. 9.2.8.3.5 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 214 NXP Semiconductors 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 (Address map used for the 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 215 Boot Loaders Secure Boot: PBL Based Platforms 9.2.8.4 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 259) 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 # Read rootfs & Header nand read # Read dtb & Header nand read # Validate and Boot esbc_validate Image Signing The image signing process will remain same as in case of NOR Boot Script and Signing the images NOTE ISBC Key Extension Feature is not applicable for Secure Boot from NAND. 9.2.8.4.1 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 216 NXP Semiconductors 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 208 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 (Address map used for the 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 0xffdf0010 1 • 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 217 Boot Loaders Secure Boot: PBL Based Platforms 9.2.8.5 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 259) 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 # rootfs nand read # dtb nand read Decap Boot Script nand read nand read nand read QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 218 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms bootm 0x10000000 0x20000000 0x1000000 Image Signing The image signing process will remain same as in case of NOR Boot Script and Signing the images 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 208 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 (Address map used for the 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 219 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 0xffdf0010 1 • 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 0xffdf0010 1 • 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 220 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms 9.2.9 Troubleshooting Table 14. 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. • 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. 2. Instead of linux prompt, you get a u-boot You have not booted in secure boot mode. You never get a u-boot prompt command prompt instead of linux prompt. in secure boot flow. Check Step 1 in Running secure boot (Chain of Trust) on page 211. 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. 9.2.10 CSF Header Data Structure The CSF Header provides the ISBC with most of the information needed to validate the image. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 221 Boot Loaders Secure Boot: PBL Based Platforms P3/P4/P5 Platforms Figure 16. CSF Header for P3/P4/P5 (ISBC and ESBC Phase) Table 15. CSF Header Format (P3/P4/P5 Platforms) Offset Data Bits [0:31] 0x00-0x03 Barker code. This location should contain the value: 0x68392781. 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. 0x04-0x07 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. 0x08-0x0b 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 222 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 15. CSF Header Format (P3/P4/P5 Platforms) (continued) Offset Data Bits [0:31] 0x0c-0x0f 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. 0x10-0x13 RSA Signature length in bytes. 0x14-0x17 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. 0x18-0x1b 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 0x1c-0x1f For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved. 0x20-0x23 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 0x24-0x27 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. 0x0000 - No UIDs are present in CSF header 0x0001 - FSL_UID and OEM_UID are present in CSF header 0x0002 - Only OEM_UID present in CSF header 0x0004 - Only FSL_UID present in CSF header 0x28-0x2b 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 223 Boot Loaders Secure Boot: PBL Based Platforms Table 15. CSF Header Format (P3/P4/P5 Platforms) (continued) Offset Data Bits [0:31] 0x2c-0x2f 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 0x30-0x47 For ISBC Phase: Not Applicable For ESBC Phase: Reserved 0x48-0x4b 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. 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. Table 16. Scatter Gather Table Format (P3/P4/P5 Platforms) Offset Data Bits [0:31] 0x00-0x03 Length in bytes of the first segment of the ESBC image. 0x04-0x07 Pointer to first segment of ESBC image. 0x08-0x0b Length in bytes of the second segment of the ESBC image. 0x0c-0x0f Pointer to second segment of ESBC image. 0xww-0xxx Length in bytes of the nth segment of the ESBC image. 0xyy-0xzz Pointer to nth segment of ESBC image Table 17. 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). QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 224 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 18. 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) Table 19. CSF Header Format (B4/T1/T2/T4 Platforms) Offset Data Bits [0:31] 0x00-0x03 Barker code. This location should contain the value: 0x68392781. 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 225 Boot Loaders Secure Boot: PBL Based Platforms Table 19. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) Offset Data Bits [0:31] 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 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. 0x10-0x13 RSA Signature length in bytes. 0x14-0x17 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. 0x18-0x1b 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 226 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 19. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) Offset Data Bits [0:31] 0x1c-0x1f For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved 0x20-0x23 Reserved .(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) 0x24 For ISBC Phase: Reserved For ESBC Phase: Reserved 0x25 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 0x26-0x27 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 0x28-0x2b 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 0x2c-0x2f 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 0x30-0x33 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 227 Boot Loaders Secure Boot: PBL Based Platforms Table 19. CSF Header Format (B4/T1/T2/T4 Platforms) (continued) Offset Data Bits [0:31] 0x34-0x37 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 0x38-0x3f Reserved 0x40-0x47 For ISBC Phase: Not Applicable For ESBC Phase: Reserved 0x48-0x4b 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. 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. Table 20. Scatter Gather Table Format (B4/T1/T2/T4 Platforms) Offset Data Bits [0:31] 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 228 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 21. Signature (B4/T1/T2/T4 Platforms) Offset Data Bits [0:31] 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Table 22. Public key (B4/T1/T2/T4 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. Table 23. SRK Table (B4/T1/T2/T4 Platforms) Offset Data Bits [0:31] 0x00-0x03 Key 1 length 0x04-0x403 Key 1 value. (Remaining bytes will be padded with zero) 0x404-0x407 Key 2 length 0x408-0x807 Key 2 value. (Remaining bytes will be padded with zero) 0x808-0x80b Key 3 length 0x80c-0xb0b Key 3 value. (Remaining bytes will be padded with zero) 0xb0c-0xb0f Key 4 length 0xb10-0xe10 Key 4 value. (Remaining bytes will be padded with zero) QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 229 Boot Loaders Secure Boot: PBL Based Platforms LS1 Platform Figure 18. CSF Header for LS1 (ISBC and ESBC Phase) Table 24. CSF Header Format (LS1 Platform) Offset Data Bits [0:31] 0x00-0x03 Barker code. This location should contain the value: 0x68392781. 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 230 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 24. CSF Header Format (LS1 Platform) (continued) Offset Data Bits [0:31] 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 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. 0x13-0x10 RSA Signature length in bytes. 0x17-0x14 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. 0x1b-0x18 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 0x1f-0x1c For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved 0x21-0x20 Manufacturing Protection Flag Indicates if manufacturing protection has to be enabled or not in ISBC. 0x23-0x22 Reserved .(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 231 Boot Loaders Secure Boot: PBL Based Platforms Table 24. CSF Header Format (LS1 Platform) (continued) Offset Data Bits [0:31] 0x24 For ISBC Phase: Reserved For ESBC Phase: Reserved 0x25 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 0x27-0x26 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 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 0x2f-0x2c OEM unique ID 0 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 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 0x3f-0x3c OEM unique ID 1 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 For ISBC Phase: Not Applicable For ESBC Phase: Reserved 0x48-0x4b 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 232 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 24. CSF Header Format (LS1 Platform) (continued) Offset Data Bits [0:31] 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. Table 25. Scatter Gather Table Format (LS1 Platform) Offset Data Bits [0:31] 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. Table 26. Signature (LS1 Platform) Offset Data Bits [0:31] 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Table 27. 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 233 Boot Loaders Secure Boot: PBL Based Platforms Table 28. SRK Table (LS1 Platform) Offset Data Bits [0:31] 0x00-0x03 Key 1 length 0x04-0x403 Key 1 value. (Remaining bytes will be padded with zero) 0x404-0x407 Key 2 length 0x408-0x807 Key 2 value. (Remaining bytes will be padded with zero) 0x808-0x80b Key 3 length 0x80c-0xb0b Key 3 value. (Remaining bytes will be padded with zero) 0xb0c-0xb0f Key 4 length 0xb10-0xe10 Key 4 value. (Remaining bytes will be padded with zero) QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 234 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms LS1043/LS1012 Platforms Figure 19. CSF Header for LS1043/LS1012 (ISBC and ESBC Phase) Table 29. CSF Header Format (LS1043/LS1012 Platforms) Offset Data Bits [0:31] 0x00-0x03 Barker code. This location should contain the value: 0x68392781. 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 235 Boot Loaders Secure Boot: PBL Based Platforms Table 29. CSF Header Format (LS1043/LS1012 Platforms) (continued) Offset Data Bits [0:31] 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 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. 0x13-0x10 RSA Signature length in bytes. 0x17-0x14 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 0x1b-0x18 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 0x1f-0x1c For ISBC Phase: ESBC entry point. ISBC transfers control to this location upon successful validation of ESBC image(s). For ESBC Phase: Reserved 0x21-0x20 Manufacturing Protection Flag Indicates if manufacturing protection has to be enabled or not in ISBC. 0x23-0x22 Reserved .(Earlier this field was SG Flag. SG flag is always assumed to be 1 in unified implementation.) Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 236 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 29. CSF Header Format (LS1043/LS1012 Platforms) (continued) Offset Data Bits [0:31] 0x24 For ISBC Phase: Reserved For ESBC Phase: Reserved 0x25 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 0x27-0x26 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 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 0x2f-0x2c OEM unique ID 0 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 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 0x3f-0x3c OEM unique ID 1 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 For ISBC Phase: Not Applicable For ESBC Phase: 64 bit pointer to ESBC image 0x48-0x4b 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 237 Boot Loaders Secure Boot: PBL Based Platforms Table 29. CSF Header Format (LS1043/LS1012 Platforms) (continued) Offset Data Bits [0:31] 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. Table 30. Scatter Gather Table Format (LS1043/LS1012 Platforms) Offset Data Bits [0:31] 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. Table 31. Signature (LS1043/LS1012 Platforms) Offset Data Bits [0:31] 0x00-size The RSA signature calculated over CSF Header, Scatter Gather table and ESBC image(s). Table 32. Public key (LS1043/LS1012 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 238 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 33. SRK Table (LS1043/LS1012 Platforms) Offset Data Bits [0:31] 0x00-0x03 Key 1 length 0x04-0x403 Key 1 value. (Remaining bytes will be padded with zero) 0x404-0x407 Key 2 length 0x408-0x807 Key 2 value. (Remaining bytes will be padded with zero) 0x808-0x80b Key 3 length 0x80c-0xb0b Key 3 value. (Remaining bytes will be padded with zero) 0xb0c-0xb0f Key 4 length 0xb10-0xe10 Key 4 value. (Remaining bytes will be padded with zero) 9.2.11 ISBC Validation Error Codes P3/P4/P5 platforms Table 34. 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 ESBC_HEADER_KEY_LEN_NOT_T Public key is not twice the length of the RSA signature WICE_SIG_LEN 0x40 ESBC_HEADER_SG_TABLE_ADDR_ SG table/ESBC image address (0x14-0x17 in CSF Header) is null NULL 0x80 ESBC_HEADER_SG_TABLE_ADDR_ SG table/ESBC image address (0x14-0x17 in CSF Header) is beyond 3.5G NOT_IN_3_5G 0x100 ESBC_HEADER_KEY_MOD_1 Most significant bit of modulus in header is zero. Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 239 Boot Loaders Secure Boot: PBL Based Platforms Table 34. 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 Address in SG entry in not in 3.5G _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 0x100000 BAD_ADDRESS A Data / Instruction TLB Exception occurred during ISBC execution 0x200000 MISC E500mc exception other than TLB 0x400000 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 240 NXP Semiconductors 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 35. Core Exceptions (LS1 platform) Value Code Definition 0x1 ERROR_UNDEFINED_INSTRUCTION Occurs if neither the processor nor any attached co- processor 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 36. Core Exceptions (LS1043/LS1012 platforms) Error Code Value Current EL with SP0 ERROR_EXCEPTION_SYNC_SP0 0x01 ERROR_EXCEPTION_IRQ_SP0 0x02 ERROR_EXCEPTION_FIQ_SP0 0x03 ERROR_EXCEPTION_SERROR_SP0 0x04 Current EL with SPx ERROR_EXCEPTION_SYNC_SPX 0x05 ERROR_EXCEPTION_IRQ_SPX 0x06 ERROR_EXCEPTION_FIQ_SPX 0x07 ERROR_EXCEPTION_SERROR_SPX 0x08 Lower EL using AArch64 ERROR_EXCEPTION_SYNC_L64 0x11 ERROR_EXCEPTION_IRQ_L64 0x12 Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 241 Boot Loaders Secure Boot: PBL Based Platforms Table 36. Core Exceptions (LS1043/LS1012 platforms) (continued) ERROR_EXCEPTION_FIQ_L64 0x13 ERROR_EXCEPTION_SERROR_L64 0x14 Lower EL using AArch32 ERROR_EXCEPTION_SYNC_L32 0x15 ERROR_EXCEPTION_IRQ_L32 0x16 ERROR_EXCEPTION_FIQ_L32 0x17 ERROR_EXCEPTION_SERROR_L32 0x18 Table 37. 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 38. 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 242 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 39. 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 SG table/ESBC image address (header address + image _NOT_IN_3_5G 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 ERROR_SGL_ENTIRES_NOT_SUPPOR Number of entries in SG table exceeds maximum limit i.e 8 TED 0x306 ERROR_ESBC_HEADER_HKAREA_LE Houskeeping area not provided in header N_ZERO 0x307 ERROR_ESBC_HEADER_HKAREA_NO House keeping area not in 3.5G boundary T_IN_3_5G 0x308 ERROR_ESBC_HEADER_HKAREA_LE Housekeeping area length provided is not sufficient. N_INSUFFICIENT 0x309 ERROR_SG_TABLE_NOT_IN_3_5 SG Table is not in 3.5G boundary 0x310 ERROR_ESBC_HEADER_HKAREA_NO House keeping area is not aligned to 4K boundary T_4K_ALIGNED 0x311 ERROR_SGL_ENTRIES_SIZE_ZERO SG table has entry with size zero. Table 40. 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_ Public key is not twice the length of the RSA signature NOT_TWICE_SIG_LEN 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 Signature value is greater than modulus in header D 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... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 243 Boot Loaders Secure Boot: PBL Based Platforms Table 40. 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 Key length specified in one of the entries in srk table is not N 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 41. 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 42. 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) 9.2.12 ESBC Validation Error Codes For trust arch version 1.x and 2.x. Table 43. ESBC Validation Failures Value Code Definition 0x4 ERROR_ESBC_CLIENT_HEADER_BARK Wrong barker code in header ER Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 244 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 43. ESBC Validation Failures (continued) Value Code Definition 0x8 ERROR_ESBC_CLIENT_HEADER_KEY_ Wrong public key length in header LEN 0x10 ERROR_ESBC_CLIENT_HEADER_SIG_L Wrong signature length in header EN 0x11 ERROR_ESBC_CLIENT_HEADER_KEY_ Selected key is revoked. REVOKED 0x12 ERROR_ESBC_CLIENT_HEADER_INVAL Wrong key entry. ID_SRK_NUM_ENTRY 0x13 ERROR_ESBC_CLIENT_HEADER_INVAL Wrong key is selected. ID_KEY_NUM 0x14 ERROR_ESBC_CLIENT_HEADER_INV_S Wrong srk public key len in header. RK_ENTRY_KEYLEN 0x15 ERROR_ESBC_CLIENT_HEADER_IE_KE Selected IE key is revoked. Y_REVOKED 0x16 ERROR_ESBC_CLIENT_HEADER_INVAL Wrong key entry in IE Table. ID_IE_NUM_ENTRY 0x17 ERROR_ESBC_CLIENT_HEADER_INVAL Wrong IE key is selected. ID_IE_KEY_NUM 0x18 ERROR_ESBC_CLIENT_HEADER_INV_I Wrong IE public key len in header. E_ENTRY_KEYLEN 0x19 ERROR_IE_TABLE_NOT_FOUND Information about IE Table missing. 0x20 ERROR_ESBC_CLIENT_HEADER_KEY_ Public key length not twice of signature length LEN_NOT_TWICE_SIG_LEN 0x21 ERROR_KEY_TABLE_NOT_FOUND No Key/ Key Table Found in header. 0x40 ERROR_ESBC_CLIENT_HEADER_KEY_ Public key Modulus most significant bit not set MOD_1 0x80 ERROR_ESBC_CLIENT_HEADER_KEY_ Public key Modulus in header not odd MOD_2 0x100 ERROR_ESBC_CLIENT_HEADER_SIG_K Signature not less than modulus EY_MOD 0x400 ERROR_ESBC_CLIENT_HASH_COMPAR Public key hash comparison failed E_KEY Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 245 Boot Loaders Secure Boot: PBL Based Platforms Table 43. ESBC Validation Failures (continued) Value Code Definition 0x800 ERROR_ESBC_CLIENT_HASH_COMPAR RSA verification failed E_EM 0x2000 ERROR_ESBC_CLIENT_BAD_ADDRESS Bad address error. 0x4000 ERROR_ESBC_CLIENT_MISC Miscallaneous error. 0x20000 ERROR_ESBC_CLIENT_HEADER_IMG_ Invalid Image size. SIZE 0x40000 ERROR_ESBC_WRONG_CMD Unknown cmd/Wrong arguments. Core in infinite loop. 0x80000 ERROR_ESBC_MISSING_BOOTM Bootm command missing from bootscript. 9.2.13 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 44. Memory map for P3/P4/P5/T1_T2_T4 platforms Address(N Address (NOR Definition Definition Size OR vBank Alternate Reserved (Chain of Trust) (Chain of Trust with 0) Bank)[5] (KB) Confidentiality) E8000000 EC000000 RCW RCW 128 E8020000 EC020000 uImage uImage 8064 E8800000 EC800000 DTB DTB 1024 E8900000 EC900000 1024 E8A00000 ECA00000 Bootscript Bootscript 1024 E8B00000 ECB00000 ESBC U-Boot HEADER ESBC U-Boot HEADER 1024 E8C00000 ECC00000 2048 E8E00000 ECE00000 Bootscript Header Bootscript Header 1024 E8F00000 ECF00000 1024 E9000000 ED000000 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 0. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 246 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 44. Memory map for P3/P4/P5/T1_T2_T4 platforms (continued) Address(N Address (NOR Definition Definition Size OR vBank Alternate Reserved (Chain of Trust) (Chain of Trust with 0) Bank)[5] (KB) Confidentiality) E9100000 ED100000 DTB Header 1024 E9200000 ED200000 Rootfs Header 1024 E9300000 ED300000 Rootfs Rootfs 29696 EC020000 E8020000 uImage 8064 (ENCAPSULATED) EC800000 E8800000 DTB 1024 (ENCAPSULATED) ED300000 E9300000 Rootfs 29696 (ENCAPSULATED) EFF20000 EBF20000 u-boot env u-boot env 128 (current bank) EFF40000 EBF40000 u-boot u-boot 768 Chain Of Trust Boot Script Used as per Address Map esbc_validate 0xE9000000 esbc_validate 0xE9100000 esbc_validate 0xE9200000 bootm 0xE8020000 0xE9300000 0xE8800000 B4 platforms Table 45. Memory map for B4 platforms Address(NO Address Definition Definition Size R vBank 0) (NOR Reserved (Chain of Trust) (Chain of Trust with Alternate (KB) Confidentiality) Bank)[6] EC000000 EE000000 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 247 Boot Loaders Secure Boot: PBL Based Platforms Table 45. Memory map for B4 platforms (continued) Address(NO Address Definition Definition Size R vBank 0) (NOR Reserved (Chain of Trust) (Chain of Trust with Alternate (KB) Confidentiality) Bank)[6] EC020000 EE020000 uImage uImage 7040 EC700000 EE700000 Bootscript Bootscript 1024 EC800000 EE800000 DTB DTB 1024 EC900000 EE900000 1024 ECA00000 EEA00000 1024 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 ED300000 EF300000 DTB 1024 (Encapsulated) ED500000 EF500000 uImage 10496 (Encapsulated ) EE020000 EC020000 rootfs/ 31232 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 xxx80000. Chain Of Trust Boot Script Used as per Address Map esbc_validate 0xECD00000 esbc_validate 0xECE00000 esbc_validate 0xECF00000 bootm 0xEC020000 0xEE020000 0xEC800000 LS1020 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 248 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 46. Memory map for LS1 platforms Address NOR(vBank Address (NOR Definition Size 0) Alternate Bank)[7] Reserved(KB) (Chain of Trust) 60000000 64000000 RCW 128 60020000 64020000 DTB 256 60060000 64060000 Bootscript 128 60080000 64080000 ESBC U-Boot HEADER 128 600A0000 640A0000 Bootscript Header 128 60100000 64100000 ESBC U-Boot 1024 60200000 64200000 uImage 8192 60A00000 64A00000 Rootfs 54272 63F00000 67F00000 uImage Header 128 63F20000 67F20000 DTB Header 128 63F40000 67F40000 rootfs Header 128 Chain Of Trust Boot Script Used as per Address Map esbc_validate 0x63F20000 esbc_validate 0x63F00000 esbc_validate 0x63F40000 bootm 0x60200000 0x60A00000 0x60020000 LS1043 Table 47. Memory map for LS1043 platforms Address Address (NOR Definition Size NOR(vBank 0) Alternate Bank)[8] Reserved (Chain of Trust) (KB) 60000000 64000000 RCW 128 60060000 64060000 Bootscript 128 60080000 64080000 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 249 Boot Loaders Secure Boot: PBL Based Platforms Table 47. Memory map for LS1043 platforms (continued) Address Address (NOR Definition Size NOR(vBank 0) Alternate Bank)[8] Reserved (Chain of Trust) (KB) 600A0000 640A0000 Bootscript Header 128 600C0000 640C0000 PPA Header 128 60100000 64100000 ESBC U-Boot 1024 60500000 64500000 PPA FIT Image 2048 60A00000* 64A00000* Kernel FIT Image 54272 63F40000 64F40000 kernel Header 128 NOTE * For LS1043 Bootscript, kernel image must be copied to DDR address 0x81000000 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 0x60A00000 0x81000000 0x3500000 # Validate the Kernel Image (The header has Image address as 0x81000000) esbc_validate 0x63F40000 # Boot the validated Kernel FIT Image. setenv bootargs "console=ttyS0,115200 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--> [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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 250 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 48. Memory map for LS1012 platform Address QSPI[9] Definition Size Reserved (KB) (Chain of Trust) 40000000 RCW 128 40060000 Bootscript 128 40080000 ESBC U-Boot HEADER 128 400C0000 Bootscript Header 128 40100000 ESBC U-Boot 1024 40480000 PPA Header 128 40500000 PPA FIT Image 2048 40A00000[10] Kernel FIT Image/ Kernel FIT Image 40960 (ENCAPSULATED) 43200000 kernel Header 128 NOTE * For LS1012 Bootscript, kernel image must be copied to DDR address 0x81000000 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 0x40A00000 0x81000000 0x2800000 # Validate the Kernel Image (The header has Image address as 0x81000000) esbc_validate 0x43200000 # Boot the validated Kernel FIT Image. setenv bootargs "console=ttyS0,115200 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 0x80000000 0x0 0x4 mmc read 0x81000000 0x8 0x14000 # Validate the Kernel Image (The header has Image address as 0x81000000) esbc_validate 0x80000000 # 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 251 Boot Loaders Secure Boot: PBL Based Platforms setenv bootargs "console=ttyS0,115200 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 0x40A00000 0x80000000 0x27c0000 0x40000000 # Write kernel.itb (Encapsulated) image on QSPI flash sf probe 0:0 sf erase 0xA00000 +0x2800000 sf write 0x80000000 0xA00000 0x2800000 # 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 0x80000000 0xA00000 0x2800000 # Decap kernel.itb (Encapsulated) Image blob dec 0x80000000 0x81000000 0x27c0000 0x40000000 # Validate the Kernel Image (The header has Image address as 0x81000000) esbc_validate 0x43200000 # Boot the validated Kernel FIT Image. setenv bootargs "console=ttyS0,115200 root=/dev/ram0 earlycon=uart8250,0x21c0500"; setenv fdt_high "0xffffffffffffffff"; setenv initrd_high "0xffffffffffffffff"; bootm $img_addr P3/P5 NAND SECURE BOOT Table 49. Memory Map for P3/P5 NAND SECURE BOOT Description Description Address on Address on DDR Size NAND (Chain of Trust) (Chain of Trust with (Image copied to Confidentiality) from NAND) PBL.bin (RCW, PBI, U-Boot, PBL.bin (RCW, PBI, U-Boot, 0x00000000 -- 0xD0000 U-boot Header) U-boot Header) Boot Script Header Boot Script Header 0x00800000 0x00010000 0x2000 Boot Script Boot Script 0x00802000 0x00012000 0x2000 uImage Header 0x00804000 0x00014000 0x2000 dtb Header 0x00806000 0x00016000 0x2000 Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 252 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms Table 49. Memory Map for P3/P5 NAND SECURE BOOT (continued) Description Description Address on Address on DDR Size NAND (Chain of Trust) (Chain of Trust with (Image copied to Confidentiality) from NAND) rootfs Header 0x00808000 0x00018000 0x2000 uImage uImage 0x06500000 0x01000000 0x410000 dtb dtb 0x06b00000 0x00c00000 0x9000 rootfs rootfs 0x02000000 0x02000000 0x2000000 uImage (Encapsulated) 0x06500000 0x10000000 0x410000 dtb (Encapsulated) 0x06b00000 0x10000000 0x9000 rootfs (Encapsulated) 0x02000000 0x10000000 0x2000000 Chain Of Trust Boot Script Used as per Address Map #UImage and Header nand read 0x01000000 0x06500000 0x410000 nand read 0x00014000 0x00804000 0x2000 #Rootfs and HEader nand read 0x02000000 0x02000000 0x2000000 nand read 0x00016000 0x00806000 0x2000 #DTB and Header nand read 0x00c00000 0x06b00000 0x9000 nand read 0x00018000 0x00808000 0x2000 esbc_validate 0x00014000 esbc_validate 0x00016000 esbc_validate 0x00018000 bootm 0x01000000 0x02000000 0x00c00000 9.2.14 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 253 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 1000000 $dir/hdr_bs.out;erase 0xECE00000 +$filesize;cp.b 1000000 0xECE00000 $filesize; tftp 1000000 $dir/hdr_linux.out;erase 0xED000000 +$filesize;cp.b 1000000 0xED000000 $filesize; tftp 1000000 $dir/hdr_rootfs.out;erase 0xED200000 +$filesize;cp.b 1000000 0xED200000 $filesize; tftp 1000000 $dir/hdr_dtb.out;erase 0xED100000 +$filesize;cp.b 1000000 0xED100000 $filesize; tftp 1000000 $dir/rootfs;erase 0xED300000 +$filesize;cp.b 1000000 0xED300000 $filesize; tftp 1000000 $dir/bootscript;erase 0xECA00000 +$filesize;cp.b 1000000 0xECA00000 $filesize; tftp 1000000 $dir/uImage.bin;erase 0xEC020000 +$filesize;cp.b 1000000 0xEC020000 $filesize; tftp 1000000 $dir/uImage.dtb;erase 0xEC800000 +$filesize;cp.b 1000000 0xEC800000 $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 0xfe314014 4 0 1 ccs::display_mem 0 0xfe0e0200 4 0 4 #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e823c 4 0 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 254 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e4 4 0 0x00000001 B4 protect off all; setenv dir tftp 1000000 $dir/hdr_bs.out;erase 0xEEC00000 +$filesize;cp.b 1000000 0xEEC00000 $filesize; tftp 1000000 $dir/hdr_linux.out;erase 0xEED00000 +$filesize;cp.b 1000000 0xEED00000 $filesize; tftp 1000000 $dir/hdr_rootfs.out;erase 0xEEE00000 +$filesize;cp.b 1000000 0xEEE00000 $filesize; tftp 1000000 $dir/hdr_dtb.out;erase 0xEEF00000 +$filesize;cp.b 1000000 0xEEF00000 $filesize; tftp 1000000 $dir/rootfs;erase 0xEC020000 +$filesize;cp.b 1000000 0xEC020000 $filesize; tftp 1000000 $dir/bootscript;erase 0xEE700000 +$filesize;cp.b 1000000 0xEE700000 $filesize; tftp 1000000 $dir/uImage.bin;erase 0xEE020000 +$filesize;cp.b 1000000 0xEE020000 $filesize; tftp 1000000 $dir/uImage.dtb;erase 0xEE800000 +$filesize;cp.b 1000000 0xEE800000 $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 0xfe314014 4 0 1 ccs::display_mem 0 0xfe0e0200 4 0 4 #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e823c 4 0 #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e4 4 0 0x00000001 P3/P4/P5 protect off all; setenv dir tftp 1000000 $dir/hdr_bs.out;erase 0xECE00000 +$filesize;cp.b 1000000 0xECE00000 $filesize; tftp 1000000 $dir/hdr_linux.out;erase 0xED000000 +$filesize;cp.b 1000000 0xED000000 $filesize; tftp 1000000 $dir/hdr_rootfs.out;erase 0xED200000 +$filesize;cp.b 1000000 0xED200000 $filesize; tftp 1000000 $dir/hdr_dtb.out;erase 0xED100000 +$filesize;cp.b 1000000 0xED100000 $filesize; tftp 1000000 $dir/rootfs;erase 0xED300000 +$filesize;cp.b 1000000 0xED300000 $filesize; tftp 1000000 $dir/bootscript;erase 0xECA00000 +$filesize;cp.b 1000000 0xECA00000 $filesize; QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 255 Boot Loaders Secure Boot: PBL Based Platforms tftp 1000000 $dir/uImage.bin;erase 0xEC020000 +$filesize;cp.b 1000000 0xEC020000 $filesize; tftp 1000000 $dir/uImage.dtb;erase 0xEC800000 +$filesize;cp.b 1000000 0xEC800000 $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 0xfe314014 4 0 1 ccs::display_mem 0 0xfe0e0200 4 0 4 #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem 0 0xfe0e807c 4 0 #Get the Core Out of Boot Hold-Off ccs::write_mem 0 0xfe0e00e4 4 0 0x00000001 LS1020 protect off all; setenv path tftp 80000000 $path/hdr_bs.out;erase 640A0000 +$filesize;cp.b 80000000 640A0000 $filesize; tftp 80000000 $path/bootscript;erase 64060000 +$filesize;cp.b 80000000 64060000 $filesize; tftp 80000000 $path/hdr_dtb.out;erase 67F20000 +$filesize;cp.b 80000000 67F20000 $filesize; tftp 80000000 $path/uImage.dtb;erase 64020000 +$filesize;cp.b 80000000 64020000 $filesize; tftp 80000000 $path/hdr_linux.out;erase 67F00000 +$filesize;cp.b 80000000 67F00000 $filesize; tftp 80000000 $path/uImage.bin;erase 64200000 +$filesize;cp.b 80000000 64200000 $filesize; tftp 80000000 $path/hdr_rootfs.out;erase 67F40000 +$filesize;cp.b 80000000 67F40000 $filesize; tftp 80000000 $path/rootfs;erase 64a00000 +$filesize;cp.b 80000000 64a00000 $filesize; # Connect to CCS and configure Config Chain ccs::config_server 0 10000 ccs::config_chain {ls1020a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 256 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms ccs::write_mem #Get the Core Out of Boot Hold-Off ccs::write_mem LS1043 protect off all; setenv path tftp 80000000 $path/hdr_bs.out;erase 640A0000 +$filesize;cp.b 80000000 640A0000 $filesize; tftp 80000000 $path/bootscript;erase 64060000 +$filesize;cp.b 80000000 64060000 $filesize; tftp 80000000 $path/hdr_kernel.out;erase 67F40000 +$filesize;cp.b 80000000 67F40000 $filesize; tftp 80000000 $path/kernel.itb;erase 64a00000 +$filesize;cp.b 80000000 64a00000 $filesize; tftp 80000000 $path/hdr_ppa.out;erase 640C0000 +$filesize;cp.b 80000000 640C0000 $filesize; tftp 80000000 $path/ppa.itb;erase 64500000 +$filesize;cp.b 80000000 64500000 $filesize; # Connect to CCS and configure Config Chain ccs::config_server 0 10000 ccs::config_chain {ls1043a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem #Get the Core Out of Boot Hold-Off ccs::write_mem 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 257 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 # 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 0x80000000 $path/PBL_0x35_0x08_800_250_1000_sben.bin; sf erase 0x0 20000; sf write 0x80000000 0x0 20000 tftp 0x80000000 $path/hdr_swap_uboot.out; sf erase 0x80000 20000; sf write 0x80000000 0x80000 20000 tftp 0x80000000 $path/u-boot_swap.bin; sf erase 0x100000 100000; sf write 0x80000000 0x100000 100000 tftp 0x80000000 $path/hdr_swap_bs.out; sf erase 0xC0000 20000; sf write 0x80000000 0xC0000 20000 tftp 0x80000000 $path/bootscript_swap; sf erase 0x60000 20000; sf write 0x80000000 0x60000 20000 tftp 0x80000000 $path/hdr_swap_kernel.out; sf erase 0x3200000 20000; sf write 0x80000000 0x3200000 20000 tftp 0x80000000 $path/kernel_swap.itb; sf erase 0xA00000 0x2800000; sf write 0x80000000 0xA00000 0x2800000 tftp 0x80000000 $path/hdr_swap_ppa.out; sf erase 0x480000 20000; sf write 0x80000000 0x480000 20000 tftp 0x80000000 $path/ppa_swap.itb; sf erase 0x500000 40000; sf write 0x80000000 0x500000 40000 # Reset board to run secure boot. reset # CCS Commands: # Connect to CCS and configure Config Chain ccs::config_server 0 10000 ccs::config_chain {ls1043a dap sap2} display ccs::get_config_chain #Check Initial SNVS State and Value in SCRATCH Registers ccs::display_mem #Wrie the SRK Hash Value in Mirror Registers ccs::write_mem QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 258 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms ccs::write_mem #Get the Core Out of Boot Hold-Off ccs::write_mem 9.2.15 Trust Architecture and SFP Information SoC Trust Arch. SFP POVDD DRVR OTPMK SNVS/SFP Version Version Register to Algo (CST) Register to Algo (CST) Register to check check check Hamming Hamming Hamming Error Error Error P4080 rev1 1 1 1.5 V A None/ 1 SNVS SecMon_HP Simulation Status (HPSR) P4080 rev2 1 1.1 1.5 V B None/ 1 SNVS Simulation P4080 rev3 1 2.2 1.5 V B None/ 1 SNVS Simulation P3041 1.1 2 1.5 V B None/ 1 SNVS Simulation P5020 1.1 2 1.5 V B None/ 1 SNVS Simulation P5040 1.1 2.2 1.5 V B None/ 1 SNVS Simulation P5021 1.1 2.2 1.5 V B None/ 1 SNVS Simulation T4240 rev1 2 3.1 1.89 V A SFP 2 SFP SFP Secret Value T4240 rev2 2 3.2 1.89 V A SFP 2 SFP Hamming B4860 rev1 2 3.1 1.89 V A SFP 2 SFP Error Status Register B4860 rev2 2 3.2 1.89 V A SFP 2 SFP (SFP_SVHE T2080 2 3.2 1.89 V A SFP 2 SFP SR) T1040 2 3.2 1.89 V A SFP 2 SFP T1023 2 3.2 1.89 V A SFP 2 SFP LS1020A 2.1 3.3 1.89 V A SFP 2 SFP LS1043A 2.1 3.3 1.89 V A SFP 2 SFP LS1012A 2.1 3.3 1.89 V A SFP 2 SFP 9.2.16 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 259 Boot Loaders Secure Boot: PBL Based Platforms 1. Import rcw.bin from SDK in QCVS Tool. 2. Add ACS Data hdr_uboot.out @ 0xF00000. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 260 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms 3. Add ACS Data u-boot.bin @0xF40000. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 261 Boot Loaders Secure Boot: PBL Based Platforms QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 262 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms 4. Make Sure that the output format is Binary. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 263 Boot Loaders Secure Boot: PBL Based Platforms 5. Generate Processor Expert Code to get PBL.bin. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 264 NXP Semiconductors Boot Loaders Secure Boot: PBL Based Platforms . QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 265 Virtualization KVM/QEMU Chapter 10 Virtualization 10.1 KVM/QEMU 10.1.1 KVM/QEMU Release Notes Copyright (C) 2013-2016 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 2.4.0 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 ©2006-2016 NXP Semiconductors. All rights reserved. 10.1.2 KVM for ARM Architecture Users Guide and Reference 10.1.2.1 Introduction to KVM and QEMU 10.1.2.1.1 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 266 NXP Semiconductors 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. 10.1.2.1.2 Organization of this Document This document is organized as follows: • Introduction to KVM and QEMU on page 266 provides an introduction to KVM/QEMU, including overview information and references. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 267 Virtualization KVM/QEMU • Building QEMU and KVM on page 271 provides information on how to build QEMU and the Linux kernel with KVM. • Using QEMU and KVM on page 276 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 280 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 282 describes facilities available for debugging software running in a virtual machine. • KVM/QEMU How-to's on page 284 provides a set of examples for common tasks. 10.1.2.1.3 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 10.1.2.1.4 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 268 NXP Semiconductors 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 271 for references that provide additional information on virtio. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 269 Virtualization KVM/QEMU 10.1.2.1.5 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. 10.1.2.1.6 References [1] QEMU Emulator User Documentation: http://qemu.weilnetz.de/qemu-doc.html [2] The Linux usage model for device tree data: https://www.kernel.org/doc/Documentation/devicetree/usage-model.txt [3] Specification for virtio devices: http://docs.oasis-open.org/virtio/virtio/v1.0/csprd01/virtio-v1.0-csprd01.pdf QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 270 NXP Semiconductors Virtualization KVM/QEMU 10.1.2.1.7 For More Information KVM • KVM website: http://www.linux-kvm.org • ARM VM specification: http://lwn.net/Articles/589122/ • Supporting KVM on ARM architecture: http://lwn.net/Articles/557132/ QEMU • QEMU website: http://www.qemu.org/ Device Trees • devicetree.org website: http://devicetree.org • DTC, the device tree compiler is available at: http://git.jdl.com . 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 • http://www.ibm.com/developerworks/linux/library/l-virtio/ • http://ozlabs.org/~rusty/virtio-spec/virtio-paper.pdf • http://www.linux-kvm.org/wiki/images/d/dd/KvmForum2007%24kvm_pv_drv.pdf • http://docs.oasis-open.org/virtio/virtio/v1.0/csprd01/virtio-v1.0-csprd01.pdf Virtual Networking with QEMU • http://wiki.qemu.org/Documentation/Networking • http://www.linux-kvm.org/page/Networking 10.1.2.2 Building QEMU and KVM 10.1.2.2.1 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. 10.1.2.2.2 Building Linux with KVM 10.1.2.2.2.1 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 271 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 10.1.2.2.2.2 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 24. 10.1.2.2.2.3 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 272 NXP Semiconductors 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 273 Virtualization KVM/QEMU 10.1.2.2.2.4 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 10.1.2.2.2.5 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 10.1.2.2.2.6 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 10.1.2.2.3 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" QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 274 NXP Semiconductors Virtualization KVM/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 # QEMU executable for ARMv7 platforms /usr/bin/qemu-system-aarch64 # 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 10.1.2.2.4 Creating a host Linux root filesystem 10.1.2.2.4.1 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 # guest Linux kernel /root/rootfs.ext2.gz # guest rootfs /usr/bin/qemu-system-arm # QEMU for ARMv7 platforms /usr/bin/qemu-system-aarch64 # QEMU for ARMv8 platforms 10.1.2.2.4.2 Adding Images to a Root Filesystem with Yocto If using Yocto, as described in Building QEMU on page 274, 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 275 Virtualization KVM/QEMU After populating the merge directory with the desired files, clean and rebuild the rootfs. See example below for the fsl-image- core 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 284 for a more detailed example. 10.1.2.3 Using QEMU and KVM 10.1.2.3.1 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 271. • 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 286 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 270) contains complete documentation for all QEMU command line arguments. The Table below summarizes some of the flags and arguments for basic operation. Table 50. Argument Descriptions -enable-kvm Specifies that the Linux KVM should be used for the virtual machine's CPUs -nographic 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) Table continues on the next page... QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 276 NXP Semiconductors Virtualization KVM/QEMU Table 50. (continued) Argument Descriptions -initrd file Specifies a root filesystem image -append cmdline Use cmdline as the guest OS kernel command line (passed in the bootargs property of the /chosen node in the guest device tree) -serial dev 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 270) 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 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. -monitor dev 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 270) 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 -drive [args] Used to create a virtual disk in a virtual machine. . -netdev [args] The -netdev and -device virtio-net-device arguments specify the network backend and front end for createing virtual network devices in virtual machines. -device virtio-net-device [args] -cpu model 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 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 277 Virtualization KVM/QEMU 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 10.1.2.3.2 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 286 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. 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. 10.1.2.3.3 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 278 NXP Semiconductors Virtualization KVM/QEMU 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 270) 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 271. For a detailed example, see the how-to article How to Use Virtual Network Interfaces Using Virtio on page 288 . 10.1.2.3.4 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 1333 1 0 Oct01 ttyS0 00:00:00 -sh root 1336 2 0 08:24 ? 00:00:00 [kworker/u4:2] root 1372 1333 18 08:27 ttyS0 00:00:17 qemu-system-arm -enable-kvm -m root 1361 1304 0 08:28 ? 00:00:00 sshd: root@pts/0 root 1363 1361 0 08: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 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: root@ls2080ardb:~# ps -eL | grep qemu 1981 1981 ttyS1 00:00:00 qemu-system-aar 1981 1982 ttyS1 00:00:00 qemu-system-aar 1981 1983 ttyS1 00:00:00 qemu-system-aar 1981 1984 ttyS1 00:00:00 qemu-system-aar 1981 1985 ttyS1 00:00:00 qemu-system-aar 1981 1986 ttyS1 00:00:00 qemu-system-aar 1981 1987 ttyS1 00:00:00 qemu-system-aar 1981 1988 ttyS1 00:00:00 qemu-system-aar 1981 1989 ttyS1 00:00:00 qemu-system-aar 1981 1990 ttyS1 00:00:00 qemu-system-aar 1981 1991 ttyS1 00:00:00 qemu-system-aar QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 279 Virtualization KVM/QEMU 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 10.1.2.4 Virtual machine reference 10.1.2.4.1 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 10.1.2.4.2 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: Table 51. Virtual I/O Devices for virt machine virt VM Descriptions Address, size 0,128MB space for a flash device (this allows running bootrom code) 0x08000000, 0x20000 Virtual CPU peripherals (including GIC distributor and CPU peripheral space) 0x08000000, 0x10000 Virtual GIC distributor 0x08010000, 0x10000 Virtual GIC CPU interface 0x08020000, 0x10000 Virtul GICv2m controller 0x09000000, 0x10000 Virtual UART 0x09010000, 0x10000 Virtual RTC 0x0a000000..0x0a0001ff Virtual MMIO ... Virtual MMIO 0x0c000000, 0x02000000 Virtual platform bus 0x10000000, 0x30000000 virtual PCIE 0x40000000, 30G guest RAM QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 280 NXP Semiconductors Virtualization KVM/QEMU 10.1.2.4.3 Virtual machine state at initialization 10.1.2.4.3.1 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. 10.1.2.4.3.2 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 • 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 10.1.2.4.4 Virtual CPUs 10.1.2.4.4.1 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. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 281 Virtualization KVM/QEMU 10.1.2.4.4.2 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. 10.1.2.4.5 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. 10.1.2.5 Debugging virtual machines 10.1.2.5.1 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 2.4.0 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 276 and the QEMU user's manual [1] (see References on page 270). 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' QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 282 NXP Semiconductors Virtualization KVM/QEMU 10.1.2.5.2 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. 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 270) 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/fsl- image-core-ls1021atwr.ext2.gz -append 'root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk' - monitor stdio -gdb tcp::4445 QEMU 2.4.0 monitor - type 'help' for more information (qemu) QEMU waiting for connection on: telnet:0.0.0.0: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 192.168.3.30): (gdb) target remote 192.168.3.30:4445 Remote debugging using 192.168.3.30:4445 0x80024f44 in ?? () QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 283 Virtualization KVM/QEMU Debugging with gdb can then proceed normally: (gdb) p/x $r15 $2 = 0x80024f44 (gdb) 10.1.2.6 KVM/QEMU How-to's 10.1.2.6.1 Quick-start Steps to Build and Deploy KVM Using Yocto The following steps show how to build host and guest root filesystems, Linux kernel, and QEMU in the Yocto environment. There are two possibilities to deploy KVM using Yocto: • Using the preconfigured fsl-image-virt Yocto image as the base for host root filesystem. This image type will generate a host root filesystem which contains: QEMU, guest root filesystem and guest kernel image. • Using other Yocto images as the base for host rootfilesystem . If the user wants to use other Yocto images to enable KVM there will be additional steps needed in order to add all the needed pieces into the host root filesystem: QEMU, guest root filesystem, guest kernel image. 10.1.2.6.1.1 Deploy KVM using fsl-image-virt Image The host roofs is based on the fsl-image-virt image type and the guest rootfs is based on fsl-image-core. The steps outlined below assume that the Yocto build environment is configured so that the bitbake command can be run. 1. Build the base host root filesystem using the fsl-image-virt image type. $ bitbake fsl-image-virt 2. Build a kernel with KVM enabled. In this case the same kernel image will be used for both host and guest. Configure the Linux kernel to enable KVM-related features (if not enabled by default in the kernel config) $ bitbake -c menuconfig virtual/kernel Follow the steps described in section Quick Start - Recommended Configuration Options on page 272 to enable KVM in the Linux kernel. Then rebuild the kernel based on the new configuration options: $ bitbake virtual/kernel 3. Re-build the fsl-image-virt image (if nothing was done at step 2, this step may be skipped) bitbake fsl-image-virt 4. Create the kernel.itb file (if necessary) U-boot may use both uImage or FIT image format to load the kernel image. For ARMv7 platforms an uImage is used and for these platforms this step is not needed. For ARMv8, a FIT image is used and the FIT image must be generated. The following steps need to be taken: • Update the fsl-image-kernelitb to include the rootfs generated by the fsl-image-virt (by default the recipee would use the rootfs generated by fsl-image-core). In order to change the rootfs type in the generated itb file there are two possible solutions: QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 284 NXP Semiconductors Virtualization KVM/QEMU • Redefine the ROOTFS_IMAGE variable in meta-freescale/recipes-fsl/images/fsl-image-kernelitb.bb directly: -ROOTFS_IMAGE ?= "fsl-image-core" +ROOTFS_IMAGE ?= "fsl-image-virt" • Add the following line to build_ ROOTFS_IMAGE = "fsl-image-virt” • Generate the kernel itb: bitbake fsl-image-kernelitb The resulting host rootfs will contain: • Linux kernel image. Currently for ARMv7 paltforms the zImage file will be included and for ARMv8 platforms the Image file. The kernel image will be located in /boot • Guest root filesystem: based on fsl-image-core. The guest root file system will be located in /boot • QEMU For steps to run QEMU see the article Quick-start Steps to Run KVM Using Hugetlbfs on page 286. 10.1.2.6.1.2 Deploy KVM using fsl-image-core Image The host roofs is based on the fsl-image-core image type and the guest rootfs is based on fsl-image-minimal. The steps outlined below assume that the Yocto build environment is configured so that the bitbake command can be run. 1. Build the base host root filesystem using the fsl-image-core image type. $ bitbake fsl-image-core 2. Build a host kernel with KVM-enabled (if not enabled by default in the kernel config) Configure the Linux kernel to enable KVM-related features. $ bitbake -c menuconfig virtual/kernel Follow the steps described in section Quick Start - Recommended Configuration Options on page 272 to enable KVM in the Linux kernel. Then rebuild the kernel based on the new configuration options: $ bitbake virtual/kernel 3. Add QEMU to the packages built by fsl-image-core. Edit the conf/local.conf file and append the following line which adds the QEMU package: IMAGE_INSTALL_append = " qemu" 4. Build a guest root filesystem and add it to the host rootfs. A. Build the guest roofs using the fsl-image-minimal image type. This creates a small rootfs sufficient for booting a Linux guest: $ bitbake fsl-image-minimal QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 285 Virtualization KVM/QEMU This command results in the minimal rootfs being created in tmp/deploy/images. In this example the minimal rootfs built is named: fsl-image-minimal.rootfs.ext2.gz B. Use the merge-files feature of Yocto (see Adding Images to a Root Filesystem with Yocto on page 275) to copy the guest rootfs to the host rootfs. $ mkdir -p meta-freescale/recipes-extended/merge-files/merge-files/merge/home/root $ cp tmp/deploy/images/machine/fsl-image-minimal.rootfs.ext2.gz meta-freescale/recipes-extended/ merge-files/merge-files/merge/home/root/guest.rootfs.ext2.gz $ bitbake -c install -f merge-files $ bitbake merge-files 5. Re-build the fsl-image-core image. bitbake fsl-image-core 6. Create the kernel.itb file (if necessary) U-boot may use both uImage or FIT image format to load the kernel image. For ARMv7 platforms an uImage is used and for those platforms this step is not needed. For ARMv8, a FIT image is used and the FIT image must be generated. bitbake fsl-image-kernelitb The resulting host rootfs will contain: • Linux kernel image • Guest root filesystem • QEMU, including the example guest device trees For steps to run QEMU see the article Quick-start Steps to Run KVM Using Hugetlbfs on page 286. 10.1.2.6.2 Quick-start Steps to Run KVM Using Hugetlbfs The pre-requisite to this example is completing the steps in the article Quick-start Steps to Build and Deploy KVM Using Yocto on page 284. This example assumes that the host Linux kernel is booted, has a working network interface, and the following images are present in the host root filesystem: • Guest kernel image (/boot/zImage or /boot/Image) • Guest root filesystem (/boot/guest.rootfs.ext2.gz) • QEMU (/usr/bin/qemu-system-arm or /usr/bin/qemu-system-aarch64) There are a number of mechanisms for allocating huge pages and making them accessible via a mount point. Refer to the SDK documentation for details. This example assume allocating pages using the hugeadm command. Create a 512MB pool of 2MB huge pages, which can be used by QEMU for allocating VM memory: $ hugeadm --pool-pages-min 2M:256 hugeadm --pool-list Size Minimum Current Maximum Default 2097152 256 256 256 * QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 286 NXP Semiconductors Virtualization KVM/QEMU Create a mount point to access the huge pages: $ hugeadm --create-mounts $ ls -1 /var/lib/hugetlbfs/ pagesize-2MB Start QEMU specifying the 2MB huge page pool as the file from which to allocate memory. In this example 512MB of memory is allocated to the VM: 32 bit ARMv7: 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/ guest.rootfs.ext2.gz -append 'root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk' -monitor stdio QEMU waiting for connection on: telnet::0.0.0.04446,server 64bit ARMv8: qemu-system-aarch64 -enable-kvm -m 512 -mem-path /var/lib/hugetlbfs/pagesize-2MB -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 QEMU waiting for connection on: telnet::0.0.0.04446,server Explanation of the command line options: • -enable-kvm : specifies that KVM should be used • -m 512 : the amount of memory for the VM • -mem-path /var/lib/hugetlbfs/pagesize-2MB : allocates from hugetlbfs based memory • -nographic : don't instantiate a graphics card, this is the only option supported for the SDK • -cpu host : the type of the CPU. In this case it is the same as the host CPU • -machine type=virt : the type of virtual machine • -kernel /boot/zImage : name of guest Linux kernel • -initrd ./boot/guest.rootfs.ext2.gz : name of guest roofs • -append "root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk" : guest Linux bootargs • -serial tcp::4446,server,telne : provide an emulated serial port (telnet server) on port 4444 on the host Linux system. Default behavior will be for QEMU to wait until the user connects to this port before booting the VM. • -monitor stdio : start QEMU monitor At this point QEMU is waiting for a telnet connection to the virtual machine's console (port 4446 of the target board) prior to starting the virtual machine. Connect to QEMU via telnet to start the virtual machine booting. In this example the target board has IP address 192.168.3.30. $ telnet 192.168.3.30 4446 [ 0.000000] Booting Linux on physical CPU 0x0 [ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Linux version 4.1.8-rt8+gf42311c (gcc version 4.9.3 20150311 (prerelease) (Linaro GCC 4.9-2015.03) ) #1 SMP Tue Apr 26 15:40:46 EEST 2016 [ 0.000000] CPU: AArch64 Processor [411fd071] revision 1 [ 0.000000] Detected PIPT I-cache on CPU0 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 287 Virtualization KVM/QEMU [ 0.000000] alternatives: enabling workaround for ARM erratum 832075 [ 0.000000] alternatives: enabling workaround for ARM erratum 834220 [ 0.000000] efi: Getting EFI parameters from FDT: ...... Starting system log daemon...0 Starting kernel log daemon...0 Starting internet superserver: xinetd. QorIQ SDK (FSL Reference Distro) 2.0 ls2080ardb /dev/ttyAMA0 ls2080ardb login: 10.1.2.6.3 How to Use Virtual Network Interfaces Using Virtio As discussed in Virtual network interfaces on page 278, there are two aspects of virtual network interfaces-- 1) the "front end" (the device as seen by the guest OS) and 2) the "backend" (the means by the virtual device is connected to the network). This example uses a "virtio" model NIC card and a tap network backend. The virtual network interface is bridged via a TAP interface to the physical network. The guest OS is Linux. When starting QEMU we will add the following arguments to create the virtual network interface: -netdev tap,id=tap0,script=/home/root/qemu-ifup,downscript=no,ifname="tap0" -device virtio-net- pci,netdev=tap0 Perform the following steps: 1. Enable virtio networking in the host and guest Linux kernels (see Host Kernel: Enabling Virtual Networking and Guest Kernel: Enabling Network and Block Virtual I/O on page 274). 2. On the host Linux create a bridge to the physical network interface to be used by the virtual network interface in the virtual machine using the brctl command. In this example the physical interface being used is eth2: brctl addbr br0 ifconfig br0 192.168.3.30 netmask 255.255.248.0 ifconfig eth2 0.0.0.0 brctl addif br0 eth2 3. Create a qemu-ifup script on the host Linux system. For the TAP backend type, when QEMU creates the virtual network interface it invokes a user-created script that allows customization of how the TAP interface is to be handled. The name of the TAP interface created by QEMU is passed as an argument. In this example we will bridge the the TAP inteface to the bridge created in step #2. See the example qemu-ifup script below: #!/bin/sh # TAP interface will be passed in $1 bridge=br0 guest_device=$1 ifconfig $guest_device 0.0.0.0 up brctl addif $bridge $guest_device 4. When starting QEMU specify that the network device type is "virtio" and specify the path to the script created in step #3: qemu-system-aarch64 -smp 8 -enable-kvm -m 4096 -nographic -cpu host -machine type=virt -kernel / boot/Image -serial tcp::4446,server,telnet -initrd /boot/fsl-image-core-ls2080ardb.ext2.gz - append 'root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk' -monitor stdio -netdev tap,id=tap0,script=qemu-ifup,downscript=no,ifname="tap0" -device virtio-net-pci,netdev=tap0 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 288 NXP Semiconductors Virtualization KVM/QEMU 5. In the guest OS the virtual network interface will appear and can be brought up and assigned an IP address in the normal way. In the example below (the commands are run from the guest command shell) the virtio interface is eth0. $ ip addr 1: lo: root@ls2080ardb:~# ethtool -i eth0 driver: virtio_net version: 1.0.0 firmware-version: expansion-rom-version: bus-info: 0000:00:01.0 supports-statistics: no supports-test: no supports-eeprom-access: no supports-register-dump: no supports-priv-flags: no $ ifconfig eth0 192.168.3.31 netmask 255.255.248.0 10.1.2.6.4 How to use vhost-net with virtio vhost-net is a character device that can be used to reduce the number of system calls involved in virtio networking. vhost- net moves network packets between the guest and the host system using the Linux kernel, bypassing QEMU. In order to use vhost-net perform the following steps: 1. Enable virtio networking and vhost-net in the host and guest Linux kernels (see Host Kernel: Enabling Virtual Networking and Guest Kernel: Enabling Network and Block Virtual I/O on page 274). 2. On the host Linux create a bridge to the physical network interface to be used by the virtual network interface in the virtual machine using the brctl command. In this example the physical interface being used is eth2: brctl addbr br0 ifconfig br0 192.168.3.30 netmask 255.255.248.0 ifconfig eth2 0.0.0.0 brctl addif br0 eth2 3. Create a qemu-ifup script on the host Linux system. For the TAP backend type, when QEMU creates the virtual network interface it invokes a user-created script that allows customization of how the TAP interface is to be handled. The name of the TAP interface created by QEMU is passed as an argument. In this example we will bridge the the TAP inteface to the bridge created in step #2. See the example qemu-ifup script below: #!/bin/sh # TAP interface will be passed in $1 bridge=br0 guest_device=$1 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 289 Virtualization KVM/QEMU ifconfig $guest_device 0.0.0.0 up brctl addif $bridge $guest_device 4. When starting QEMU specify that the network device type is "virtio" and that vhost-net (vhost=on parameter) is used: qemu-system-aarch64 -smp 8 -enable-kvm -m 8192 -mem-path /var/lib/hugetlbfs/pagesize-1GB - nographic -cpu host -machine type=virt -kernel /boot/Image -serial tcp::4446,server,telnet - initrd /boot/fsl-image-core-ls2080ardb.ext2.gz -append 'root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk ramdisk_size=307200' -monitor stdio -netdev tap,id=tap0,script=qemu- ifup,downscript=no,ifname="tap0",vhost=on -device virtio-net-pci,netdev=tap0 5. In the guest the virtual interface will come up as described in How to Use Virtual Network Interfaces Using Virtio on page 288. In the Host kernel the vhost thread can be seen consuming CPU: 2078 root 20 0 0 0 0 R 93.7 0.0 0:07.09 vhost-2066 2066 root 20 0 9192660 511632 7532 S 82.0 3.3 0:12.70 qemu-system- aar 2091 root 20 0 159636 1092 960 S 68.0 0.0 0:05.50 iperf 10.1.2.6.5 Debugging: How to Examine Initial Virtual Machine State with QEMU It can be helpful when debugging to examine the state of the virtual machine prior to executing the first instruction of the guest OS. To do this, start QEMU with the -S option. Example: qemu-system-aarch64 -enable-kvm -m 512 -nographic -cpu host -machine type=virt -kernel /boot/ Image -serial tcp::4446,server,telnet -initrd /boot/fsl-image-core-ls2080ardb.ext2.gz -append 'root=/dev/ram0 rw console=ttyAMA0 rootwait earlyprintk' -monitor stdio -S The console was started with the "-serial tcp::4446,server,telnet" option so QEMU waits for a connection prior to starting initialization. Use telnet to connect to port 4446 of the target. At this point QEMU initializes the VM, but does not execute the entry point to the guest OS. The monitor prompt can now be used to examine initial state: QEMU 2.4.0 monitor - type 'help' for more information (qemu) QEMU waiting for connection on: telnet:0.0.0.0:4446,server (qemu) To see where boot images are loaded and placed by QEMU use the info roms command: (qemu) info roms addr=0000000040000000 size=0x000028 mem=ram name="bootloader" addr=0000000040080000 size=0xb9a800 mem=ram name="/boot/Image" addr=0000000048000000 size=0x1517eef mem=ram name="/boot/fsl-image-core-ls2080ardb.ext2.gz" addr=0000000049600000 size=0x010000 mem=ram name="dtb" /rom@etc/acpi/tables size=0x200000 name="etc/acpi/tables" /rom@etc/table-loader size=0x000880 name="etc/table-loader" /rom@etc/acpi/rsdp size=0x000024 name="etc/acpi/rsdp" A trivial bootloader is loaded at the start of guest memory at 0x40000000 The kernel image (zImage) is loaded at 0x40080000. The ramdisk is loaded at 0x48000000. QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 290 NXP Semiconductors Virtualization KVM/QEMU To examine the initial state of registers use the info registers command: (qemu) info registers PC=0000000040000000 SP=0000000000000000 X00=0000000000000000 X01=0000000000000000 X02=0000000000000000 X03=0000000000000000 X04=0000000000000000 X05=0000000000000000 X06=0000000000000000 X07=0000000000000000 X08=0000000000000000 X09=0000000000000000 X10=0000000000000000 X11=0000000000000000 X12=0000000000000000 X13=0000000000000000 X14=0000000000000000 X15=0000000000000000 X16=0000000000000000 X17=0000000000000000 X18=0000000000000000 X19=0000000000000000 X20=0000000000000000 X21=0000000000000000 X22=0000000000000000 X23=0000000000000000 X24=0000000000000000 X25=0000000000000000 X26=0000000000000000 X27=0000000000000000 X28=0000000000000000 X29=0000000000000000 X30=0000000000000000 PSTATE=400003c5 (flags -Z--) q00=0000000000000000:0000000000000000 q01=0000000000000000:0000000000000000 q02=0000000000000000:0000000000000000 q03=0000000000000000:0000000000000000 q04=0000000000000000:0000000000000000 q05=0000000000000000:0000000000000000 q06=0000000000000000:0000000000000000 q07=0000000000000000:0000000000000000 q08=0000000000000000:0000000000000000 q09=0000000000000000:0000000000000000 q10=0000000000000000:0000000000000000 q11=0000000000000000:0000000000000000 q12=0000000000000000:0000000000000000 q13=0000000000000000:0000000000000000 q14=0000000000000000:0000000000000000 q15=0000000000000000:0000000000000000 q16=0000000000000000:0000000000000000 q17=0000000000000000:0000000000000000 q18=0000000000000000:0000000000000000 q19=0000000000000000:0000000000000000 q20=0000000000000000:0000000000000000 q21=0000000000000000:0000000000000000 q22=0000000000000000:0000000000000000 q23=0000000000000000:0000000000000000 q24=0000000000000000:0000000000000000 q25=0000000000000000:0000000000000000 q26=0000000000000000:0000000000000000 q27=0000000000000000:0000000000000000 q28=0000000000000000:0000000000000000 q29=0000000000000000:0000000000000000 q30=0000000000000000:0000000000000000 q31=0000000000000000:0000000000000000 FPCR: 00000000 FPSR: 00000000 The program counter is set to 0x40000000 which is the effective address of the entry point of the kernel. 10.1.2.6.6 Debugging: How to Profile Virtualization Overhead with KVM Running software in a virtual machine can cause additional overhead that affects performance. The virtualization overhead is directly related to the number of times the hypervisor (KVM) is invoked to handle exception conditions that may occur in the virtual machine. These exception handling events are referred to as 'exits', because guest context is exited. Examples of exits include things such the guest executing a privileged instruction, access a privileged CPU register, accessing a virtual I/O device, or a hardware interrupt such as a decrementer interrupt. The type and number of exits that occur is workload dependent. KVM implements a mechanism in which different events are logged. These events are actually tracepoint events, and perf nicely integrates with them. You have to compile the host kernel with the following options: Kernel hacking ---> [*] Tracers ---> [*] Trace process context switches and events Counting Events A count of a subset of KVM events that occur can be seen under debugfs. To see this first mount debugfs: mount -t debugfs none /sys/kernel/debug QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 NXP Semiconductors 291 Virtualization KVM/QEMU The statistics can be seen using perf tool: # perf stat -e "kvm:*" -p 1395 ^C Performance counter stats for process id '1395': 5678 kvm:kvm_entry 5678 kvm:kvm_exit 3121 kvm:kvm_guest_fault 2278 kvm:kvm_irq_line 0 kvm:kvm_mmio_emulate 0 kvm:kvm_emulate_cp15_imp 2438 kvm:kvm_wfi 0 kvm:kvm_unmap_hva 2 kvm:kvm_unmap_hva_range 0 kvm:kvm_set_spte_hva 0 kvm:kvm_hvc 3119 kvm:kvm_userspace_exit 0 kvm:kvm_set_irq 0 kvm:kvm_ack_irq 4068 kvm:kvm_mmio 0 kvm:kvm_fpu 0 kvm:kvm_age_page 59.316709040 seconds time elapsed Tracing events Detailed traced can be generated using ftrace: [enable ftrace in kernel: events and system calls] $echo 1 > /sys/kernel/debug/tracing/events/kvm/enable $cat /sys/kernel/debug/tracing/trace_pipe qemu-system-arm-1366 [000] .... 716.115891: kvm_guest_fault: ipa 0x9000000, hsr 0x93430046, hxfar 0xa084c030, pc 0x80266a9c qemu-system-arm-1366 [000] .... 716.115892: kvm_mmio: mmio write len 2 gpa 0x9000030 val 0xf01 qemu-system-arm-1366 [000] .... 716.115895: kvm_userspace_exit: reason KVM_EXIT_MMIO (6) qemu-system-arm-1366 [000] d... 716.115907: kvm_entry: PC: 0x80266aa0 qemu-system-arm-1366 [000] d... 716.116234: kvm_exit: PC: 0x800cf508 qemu-system-arm-1366 [000] d... 716.118274: kvm_entry: PC: 0x800cf508 qemu-system-arm-1366 [000] d... 716.118704: kvm_exit: PC: 0x0000981c qemu-system-arm-1366 [000] d... 716.120737: kvm_entry: PC: 0x0000981c qemu-system-arm-1366 [000] d... 716.121159: kvm_exit: PC: 0x800bb104 qemu-system-arm-1366 [000] d... 716.123197: kvm_entry: PC: 0x800bb104 qemu-system-arm-1366 [000] d... 716.123620: kvm_exit: PC: 0x8009cae0 qemu-system-arm-1366 [000] d... 716.125696: kvm_entry: PC: 0x8009cae0 qemu-system-arm-1366 [000] d... 716.126091: kvm_exit: PC: 0x800c90f4 qemu-system-arm-1366 [000] d... 716.128130: kvm_entry: PC: 0x800c90f4 qemu-system-arm-1366 [000] d... 716.128561: kvm_exit: PC: 0x801f37f4 qemu-system-arm-1366 [000] d... 716.130594: kvm_entry: PC: 0x801f37f4 qemu-system-arm-1366 [000] d... 716.130623: kvm_exit: PC: 0x8020576c qemu-system-arm-1366 [000] d... 716.130635: kvm_entry: PC: 0x8020576c qemu-system-arm-1366 [000] d... 716.131018: kvm_exit: PC: 0x43014750 qemu-system-arm-1366 [000] d... 716.133053: kvm_entry: PC: 0x43014750 qemu-system-arm-1366 [000] d... 716.133478: kvm_exit: PC: 0x80205778 qemu-system-arm-1366 [000] d... 716.135555: kvm_entry: PC: 0x80205778 QorIQ LS1012A SDK v0.4, Rev. 0, August 2016 292 NXP Semiconductors How To Reach Us Information in this document is provided solely to enable system and software implementers to use Freescale products. There are no express or implied copyright licenses granted Home Page: hereunder to design or fabricate any integrated circuits based on the information in this nxp.com document. Freescale reserves the right to make changes without further notice to any Web Support: products herein. nxp.com/support Freescale makes no warranty, representation, or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. “Typical” parameters that may be provided in Freescale data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including “typicals,” must be validated for each customer application by customer's technical experts. Freescale does not convey any license under its patent rights nor the rights of others. Freescale sells products pursuant to standard terms and conditions of sale, which can be found at the following address: nxp.com/SalesTermsandConditions. Freescale, the Freescale logo, and Kinetis are trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. All other product or service names are the property of their respective owners. ARM and Cortex are registered trademarks of ARM Limited. Ⓒ 2016 Freescale Semiconductor, Inc. QORIQLS1012ASDK04 Rev. 0 30 Aug 2016