NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux SDK

Developer Guide
5.1.12.0 Release

 
Flashing with Bootburn
 
Platform Configurations
Boot Modes
Host Side Flashing Tools
Target Side Flashing Tools
Options and Use Cases for nvdd
Flashing Scripts and Prebuilt Binaries
Flashing Flow
Configuration File in Bootburn
Boot Mode Selection
Virtualization Behavior
Rebuilding Host Side Tools
Before flashing with bootburn, consult Setting the Environment Variables to ensure successful flashing.
Platform Configurations
The platform configuration (platcfg) file is a JSON-formatted file with the properties defined in this section.
{
"mb1-bct": {
"<cfg-type>": [
"<sub-cfg-filename-0>",
"<sub-cfg-filename-n>"
]
},
"bootburn-flags": {
"<flag>": <boolean|string>
}
}
Property
Value
Description
Example
c["mb1-bct"]
JSON object
This contains a set of MB1-BCT cfg types for which properties need to be appended.
See below.
c["mb1-bct"]["<cfg-type>"]
key: MB1-BCT type.
value: JSON list.
List of sub-cfg filenames that need to be appended to the given MB1-BCT type.
The type is selected by key, which can be one of the following strings:
"misc"
The following keys are NOT  supported, but are listed here for future enhancements:
"sdram"
"wb0sdram"
"scr"
"pinmux"
"pmic"
"pmc"
"misc"
"prod"
"gpioint"
The value for this property is a JSON object with properties to be appended.
For MB1-BCT misc cfg:
"misc": [...]
c["mb1-bct"]["<cfg-type>"][i]
string
The value specifies the filename of sub-cfg. The contents of this sub-cfg is appended to MB1-BCT cfg (for the given type).
 
There will not be any support for dirname associated with this value. In other words, the files must be in the same directory as platcfg.
Allowed:
"DE.cfg"
"myprops.cfg"
 
Not allowed:
"some/rel/path/file.cfg"
"/some/abs/path/file.cfg"
c["bootburn-flags"]
JSON object
Contains a set of bootburn flags for which override is provided.
See below.
c["bootburn-flags"]["<flag>"]
key: Recognized flag for bootburn can be overridden.
value:
Recognized value for the given flag.
The key must be a string and is one of the valid bootburn flags:
"-E"
The remaining flags are NOT  supported for overriding. This format will allow such extensions in the future.
 
The value must be either a boolean or string, depending on the key:
"-E"
true (boolean) - This flag must be overridden to true.
false (boolean) - This flag must be overridden to false.
For DRAM-ECC:
"-E": true
"-E": false
For example, the following platcfg enables dual execution mode and overrides DRAM-ECC flag to true.
{
"mb1-bct": {
"misc": [
"DE.cfg",
"myprops.cfg"
]
},
"bootburn-flags": {
"-E": true
}
}
Boot Modes
Use these methods when booting the target device:
• FA Mode is used for testing and detecting failures in boot medium. For example, if you suspect there are issues in the flash medium, such as NOR, 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.
Host Side Flashing Tools
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.
nvimagegen
Generates the various images needed during flashing. The images are based on the configuration (CFG) file passed as an input argument. It appends headers, generic headers or boot headers, on top of the binaries, and signs them if required. nvimagegen then invokes tegrasign_v2 to sign the binaries with Zero Key Cipher-based MAC (CMAC) for a non-secure device or a private key for a secure device. It signs with the private key, provided from the command line, for a secure device.
nvimagegen invokes the following compression tools that it expects to be present at the local directory:
• tegrasign_v2
• mkfs_ext*
• nvguestimagegen
nvimagegen generates the FileToFlash.txt file which lists all the binary names after signing and offset on which binaries must be flashed on media. The FileToFlash.txt file is used by bootburn during flashing. nvimagegen can generate the following additional images, based on the supplied CFG file:
• PT.bin—Partition table for the whole system. Quickboot interprets this table to gather information about partitions.
• GPT_pri*.bin, GPT_bak*.bin—Standard GUID partition table (GPT) for media.
• File system images—Supported versions are ext2, ext3, and ext4. Linux also supports Unsorted Block Images File System (UBIFS).
• Kernel boot image—The generated kernel boot image is generated using compression type definition in the configuration file (CFG). The boot header and the generic header are appended at the top of the compressed kernel image.
• DTB images—Different firmware have their own dtb files. nvimagegen appends the required headers on dtb files and signs it. It also amends the os_args command line present in the CFG file to the kernel dtb.
• rcm_blob.bin—A blob of all the required images needed for RCM boot.
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.
nvguestimagegen
Used in hypervisor flashing to generate images of each guest partition.
• While parsing the CFG file, if nvimagegen finds a sub_config file specified, it invokes the internal nvguestimagegen tool passing the path of the sub_config_file and the partitionId arguments.
• nvguestimagegen ensures that the partition_attribute field is NOT 0 for a given guest. This verification is required because subconfig-file can be specified in only one partition.
• If the subconfig_file path is NOT an absolute path, it is assumed to be relative to the main global_storage.cfg configuration file
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.
Target Side Flashing Tools
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 command line options are as follows.
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.
To erase a device/partition
./nvdd --device <devicename> --deverase eoffset=<offset>,esize=<size>
If <offset> is 0 and <size> is 0 then the complete 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
Pre-built binaries are included and used during flashing boot.
• Bootburn scripts are available at:
drive-t186ref-foundation/tools/host/flashtools/bootburn_t19x
• Prebuilt flashing binaries are available at:
drive-t186ref-foundation/tools/host/flashtools/flash/t19x
 
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.
If you modify the kernel image and port the PDK to another platform, you must update the images at:
<top>//drive-t186ref-foundation/tools/host/flashtools/flash/t18x
 
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
Normal flashing configuration occurs when:
• Depending on the target and the operating system to be flashed, a configuration file is selected by bootburn by default.
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.
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 the internal nvguestimagegen tool and passes the path of the sub_config_file and the partitionId arguments.
• Before invoking nvguestimagegen, nvimagegen ensures that:
• The partition_attribute field is NOT 0 and for given guest.
• There is only one partition where sub_config_file can be specified.
If the sub_config_file path is not an absolute path, it is assumed to be relative to the main global_storage.cfg configuration file.
Rebuilding Host Side Tools
For rebuilding host side flashing tools, such as nvimagegen, use the following instructions.
1. Set the environmental variables needed for build:
cd <top>
export TOP=$(pwd)
export UPDATE_CROSS_COMPILE=$TOP/toolchains/tegra-4.9-nv/usr/bin/aarch64-gnu-linux/aarch64-gnu-linux-
export TEGRA_TOP=$TOP/drive-t186ref-foundation/firmwares/src/bootloader
2. Navigate to the source location and build the tools:
cd $TOP/drive-t186ref-foundation/tools/host/flashtools/src/
make clean
make
3. Replace the existing binaries with output from build. For example, to replace nvimagegen:
cp $TOP/drive-t186ref-foundation/tools/host/flashtools/src/host/nvimagegen/_out/_hostside/nvimagegen $TOP/drive-t186ref-foundation/tools/host/flashtools/flash/nvimagegen