NVIDIA Tegra
NVIDIA DRIVE 5.0 Foundation SDK

Development Guide
5.0.10.3 Release

 
Bootburn: Advanced Concepts
 
Boot Modes
Flashing Tools: Host Side
Flashing Tools: Target Side
Options and Use Cases for nvdd
Flashing Scripts and Prebuilt Binaries
Flashing Flow
Configuration File in Bootburn
Boot Mode Selection
Virtualization Behavior
Note:
For convenience during flashing, the information in this chapter has been duplicated from the OS-agnostic chapter in Foundation 5.0 SDK Development Guide.
This section describes advanced flashing and booting concepts. You do not need to fully understand these concepts for common use cases.
Boot Modes
This topic describes the methods you can use when booting the target device:
• FA Mode is used for testing and detecting failures in boot medium. For example, if you suspect there issues in the flash medium (such as NOR), then you can use FA Mode to boot the kernel directly on RAM without touching the flash medium.
• Recovery (RCM) Mode is similar to FA Mode, but Bootburn reads the Boot Configuration Table (BCT) from flash for specific data.
• Normal Flashing Mode completely flashes the target as follows:
Writes all binaries to the flash medium. These binaries include BCT, partition table (PT), boot loader, kernel, and device tree blob (DTB).
In this step, Bootburn boots in recovery mode with RCM kernel and initial RAM filesystem (initramfs). It then flashes the binaries onto the flash medium.
With the next reset, the boot loader boots the kernel binary from the flash medium.
Flashing Tools: Host Side
The host-side tools, used in the flashing process, are as follows.
Host-side Tool
Description
tegrasign_v2
Signs images such as boot loaders, firmware, kernel, RAMdisk, with a private key provided during flashing for flashing to a secure device and with 0-CMAC for non-secure device.
tegrarcm_v2
Communicates with the target when it is in recovery mode. It then sends the required binaries such as BCT, MB1, MB1_BCT, and RCM-Blob to the target for booting. It also reads the needed information, such as flashed BCT, from the target.
tegrabct_v2
Generates BCT files such as bct_BR.bct and bct_Mb1.bct, and populates them with the necessary data that is subsequently flashed on the target.
For information about MB1 BCT files, see MB1 Platform Configuration.
For more information about the BCT files, see the Updating Partitions in Update Mechanism (PDK Only).
adb (Android Debug Bridge)
A standard host side tool used to transfer the data/binaries between the host and the target.
nvimagegen
Generates images that are used during flashing. The generated images are based on the input options, the CFG file, and binaries provided by the caller. The tool can also process subsidiary CFG files referenced by primary CFG file (using the tag ‘sub_config_file’).
The tool can append headers (generic or boot), modify content, sign sections (zero-key CMAC or private key), and compress sections of the input binaries. Examples of such images include:
• Kernel boot images: boot header and generic header appended on top of compressed kernel binary
• Filesystem images: ext2, ext3, ext4, UBIFS, etc.
• DTB images: required headers and signature appended, and os_args value inside DTB modified
• BCT images: update values inside DTB and signature
The tool can also generate images that are based on metadata of input binaries and metadata of output images. These include:
• PT: partition tables
• GPT: standard GUID partition table for media
• RCM blobs: a single binary containing all images for RCM boot
• FileToFlash: a text file that lists all output images along with target storage information, size, offset, etc.
nvimagegen invokes the following tools, which it expects to be in the current working directory:
• nvimagegen for processing subsidiary CFG files
• tegrasign_v2 for signing operations
• mkfs_ext* for filesystem operations
For more information about configuration files, see:
•  
nvskuinfo
Updates BCT information with metadata (SKUInfo) about the target board. SKUInfo includes:
• SKU ID
• SKU version
• Board ID
• Board revision
• Board serial number
• MAC ID
Preserves the metadata stored in the BCT during flashing. It reads metadata from the previous BCT and updates it in the new BCT that is subsequently flashed.
The metadata is record when the target board is initially flashed and is preserved during subsequent flashes.
For more information, see Flashing SKUInfo in Flashing Preprocessed Binaries (Tegra Parker).
 
compress_lzf
A light-weight Lempel-Ziv-Free compression tool for compressing the kernel image.
compress_zlib
Compresses the kernel using Zlib compression.
Jq-linux64
JSON processor used for parsing JSON files.
Flashing Tools: Target Side
The target-side tools, used in the flashing process, are as follows.
Target-side Tool
Description
nvdd
Copies the binary to the specified device at the specified location.
This tool supports char devices and block devices, including eMMC, SD card, and SATA. It also provides a read-back verification mechanism that you can use to verify that the file on the storage device is same as the file written to that device.
e2fsck
Checks a Linux ext2/ext3/ext4 filesystem.
losetup
Sets up and controls loop devices.
dumpe2fs
Dumps ext2/ext3/ext4 filesystem information.
diff
Compares files line by line. This tool is used in verification.
resize2fs
Resizes ext2/ext3/ext4 filesystem.
mkfs
Builds a Linux filesystem.
Options and Use Cases for nvdd
The nvdd tool has the following options at the command line.
Option
Description
--device
Specifies the device where nvdd performs operations.
--inputbin
Specifies the input file.
--startoffset
Specifies the offset of the start of the partition.
--partsize
Specifies the partition size.
--outputbin
Specifies the output file containing the data read back from the partition.
--deverase <partition>
Erases <partition>.
--parterase
Erases the rest of the partition on the device after the file is written.
--readback
Reads data just written back from the partition to a file for comparison with the original file for verification. Allows you to ensure that the file has been correctly written to the partition.
--skiperase
Writes a file to a partition without first erasing the partition.
--partunlock
Unlocks the partition before performing an erase or write operation.
--nowrite
Verifies that the content present in the partition matches with the file, without writing the file.
--md5sum
Verifies that the file has been correctly written to the partition. Similar to --readback, but computes the md5sum of the partition the file has been written to and compares that with the md5sum of the file provided by the user.
--printmd5sum
Verifies that the file has been correctly written to the partition. Similar to --readback, but computes the md5sum of the partition the file has been written to and compares that with the md5sum of the file provided by the user.
Also prints the md5sum of the partition.
The nvdd tool has the following typical use cases:
To erase a device/partition
./nvdd --device <devicename> --deverase eoffset=<offset>,esize=<size>
If <offset>==0 and <size>==0 then the entire device is erased.
To write a file to a partition
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset>
To write a file to a partition and erasing the rest of the partition
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset> --parterase
To write a file to a partition and perform verification that the file is correctly written
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset> --readback
To unlock a partition before writing/erasing it
Can be used with any of the use cases 1, 2, 3, 4, 6. Add --unlock to the nvdd command line.
To match the host file md5sum
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset> --readback --md5sum <md5sumstring>
To print the md5sum of the partition
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset> --printmd5sum
To match a file in a partition without writing to it
./nvdd --device <devicename> --inputbin <filename> --partsize <size> --startoffset <offset> --readback --nowrite
Flashing Scripts and Prebuilt Binaries
The Foundation SDK includes pre-built binaries used during flashing boot.
• Bootburn scripts are available at:
drive-t186ref-foundation/tools/host/flashtools/bootburn
• Prebuilt flashing binaries are available at:
drive-t186ref-foundation/tools/host/flashtools/flash/t18x
 
Bootburn Scripts and Files
Script
Description
bootburn.sh
The starting point of flashing process, responsible for interacting with the user.
bootburn_core.sh
Reads the flash command line and sets the flashing environment accordingly, for example, for simple flashing or parallel flashing.
bootburn_active.sh
The main flashing script that sources other scripts for flashing.
bootburn_lib.sh
Provides the function definitions.
bootburn_adb.sh
Includes scripts that define functions necessary to communicate over ADB.
Reads the FiletoFlash.txt during flashing, to flash the listed binaries.
bootburn_helper.sh
Sets the board specific paths and files needed by bootburn.sh.
quickboot_qspi_*.cfg
Depending on the OS and the target, one of the files is selected by bootburn. Consists of:
• Final flash layout passed to nvimagegen to create images to be flashed.
• FiletoFlash.txt that includes binary names and offset.
Prebuilt Flashing Binaries
Directories
Description
rcmfirmware
Prebuilt firmware used in flashing and includes:
• bpmp.bin: boot and power management processor firmware
• bpmp*.dtbs: device tree binaries.
• tos.img: secure monitor firmware.
rcmkernel
Prebuilt kernel image with dtb images.
rcmbl
Boot loader images used during flash-boot and includes:
• nvtboot_recovery.bin: second stage recovery boot loader MB2.
• qb_cpu.bin: Quickboot CPU boot loader with its dtb appended.
 
Note:
If you modify the kernel image and port the PDK to another platform, you must update the images at:
drive-t186ref-foundation/tools/host/flashtools/flash/t18x/rcmkernel
 
Warning:
After porting customized kernel code to another platform, failure to update the image, before flashing, may result in a bricked device.
Flashing Flow
nvimagegen generates the required binaries based on the input provided. The most important input is the selection of the configuration file (CFG file). Based on the configuration file, signed binaries are selected. The final flash structure is decided, and in the case of RCMblob, is generated based on the CFG file.
Configuration File in Bootburn
In a normal flashing operation, Bootburn selects a default configuration file that corresponds to the target’s operating system. The default configuration file is named:
quickboot_qspi_linux[_intramfs].cfg
Where the value within the angle brackets (“<…>”) designates the target operating system.
Boot Mode Selection
For RCM Boot, the flow includes:
• If the -R option is specified, RCM boot mode is selected.
• mnimagegen generates a blob of binaries including the boot loader and the kernel, depending on the CFG file.
• Bootburn downloads these binaries on the target RAM and boots it directly, without updating flash.
For Flash Boot, the flow includes:
• If -R option is NOT specified, bootburn updates the binaries on the target storage medium.
• To flash the target storage medium, bootburn uses a set of flashing pre-built binaries and the flashing configuration file in nvimagegen to generate the binary blob.
The blob is downloaded to the target and the flashing kernel is booted on initial RAM file system (initramfs).
• Bootburn then invokes nvimagegen a second time with the normal configuration file (CFG), and with the set of binaries identified in the configuration file to generate the binaries that must be flashed on the target.
A summary list for the final flash is generated in the FileToFlash.txt file.
• After booting and flashing the kernel on the target, bootburn establishes an ADB connection over USB with the target.
• Once the ADB connection is established, bootburn sends the generated binaries that are identified in the FileToFlash.txt using the ADB push protocol.
• Bootburn invokes a write to these binaries on the target by using an ADB shell, with the dd target-side command tool, and the appropriate offset arguments as identified in the FileToFlash.txt file.
The following diagrams illustrate the flashing flow for RCM Boot and Flash Boot and flashing the target with ADB:
Virtualization Behavior
For Virtualization, nvimagegen generates images of each guest partition.
• While parsing the configuration file, if nvimagegen finds a sub_config_file specified, it invokes another instance of nvguestimagegen and passes it the path of the sub_config_file, partitionId arguments, and guest flags.
• nvimagegen ensures that:
• For legacy (i.e. version 1) CFG files:
• The partition_attribute field is not 0 for the given guest.
• There is only one partition where sub_config_file can be specified.
• For three-level (i.e. version 2) CFG files, the partition_attribute field specifies the guest partition for the given guest.