NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux SDK

Developer Guide
5.1.12.0 Release


 
Bootburn Usage
 
Bootburn
Bootburn Command Usage
Bootburn Options
Kernel Parameter Combinations
Passing Additional Kernel Parameters
Updating the path for the targetfs
Using the targetfs.img file for Linux guest rootfs
Dialout Group
Use the Bootburn utility to flash platform boards with the boot loader, kernel, and file system. The Bootburn utility is provided as part of the Foundation package.
Bootburn
Bootburn is a shell script that:
Boots the device in the recovery-mode with RAMDisk
Signs or generates the images on the host
Transfers the images to target using ADB
Flashes the boards
Bootburn automatically resizes the rootfs image on the target to optimize the available storage on the partition dedicated to it, either on eMMC or NOR.
Bootburn supports a host NFS share as the mount point for the target rootfs. This feature provides a convenient way for developers to copy files between the target and host for rapid development. In this case, the uncompressed target rootfs directory on the host is leveraged directly by the target.
Bootburn relies on the Foundation services to provide the flashing and boot loader functionality. You configure it with the CFG file rather than with Bootburn command-line parameters; Bootburn supports limited command line options.
Bootburn Command Usage
Run the bootburn.sh script from a shell on your host Linux system by executing the command:
./bootburn.sh <options>
Bootburn Options
The supported options are as follows.
Options
Description
-a (lower case)
Flashes Android images.
--aquantia07b1
Enables flashing of the Aquantia network interface controller firmware. Uses the version packaged in the Foundation PDK. The automatic update is disabled by default. The firmware is taken from: <top>/drive-t186ref-foundation/firmwares/bin/common/aquantia.
--aquantia07b1_fw
Specifies the firmware to flash to the Aquantia network controller. This option only works if the --aquantia07b1 option is used and errors out if not.
-b <e3550a01-t186a | e3550a01-t186b | e3550a03-t186a | e3550a03-t186b>
(lower-case b)
Provides the board name and revision. Possible board names include:
e3550xxx-t194a : Xavier A
e3550xxx-t194b : Xavier B
e3550xxx-t194ia : IVI SKU Xavier A
p3479a01-t194 - Xavier-AD SKU
p3479a01-t194s - Xavier-S SKU
Where xxx is the board revision, which can be b01 or b03 based on the e3550 board revision. See Section 1.0 of the Release Notes for your release to confirm your board and revision information.
-d <partition_name> <dtb_file>
(lower-case d)
Specifies the DTB file to flash and the target partition. The default file is defined in BoardSetFilePathsAndDefaultValues.
bpmp-fw-dtb and kernel-dtb may be specified simultaneously.
Note: This option is not intended to specify kernel-dtb in Hypervisor.
-f (lower case)
Failure analysis (FA) mode support.
-h
(lower-case h)
Provides guidance on the actions and options of bootburn.
-i (lower case i)
File path to platform configuration file. If not provided for hypervisor configurations, then the tool expects the platform configuration file to be present in the hypervisor output directory
-k <configuration file>
(lower-case k)
Specifies the configuration file for flashing.
-m (lower case)
Flashing Modular Diagnostic Software (MODS). This option enables mods-specific overrides.
--marvell9485
Enabled flashing of the Marvell 88SE9345 PCIe SATA controller. Uses the version packaged in the Foundation PDK. The automatic update is disabled by default. The firmware is taken from: <top>/drive-t186ref-foundation/firmwares/bin/common/marvel_88SE9345.
--marvell9485_fw
Specifies the firmware to flash to the Marvell 88SE9345. This option only works if the --marvell9465 option is used and errors out if not.
--microsemi8534
Enables PCIe firmware update option. To use:
./bootburn.sh -b e3550b01-t194 --microsemi8534 ... [other options]
--microsemi8534_fw <path_to_FW>
Specifies the firmware to flash to the Microsemi PCIe controller. To choose the firmware:
./bootburn.sh -b e3550b01-t194 --microsemi8534 --microsemi8534_fw <path/to/FW> ... [other options]
If you choose this option, you must also choose --microsemi8534 to enable the firmware update. An error is thrown if you do not.
-o
(lower-case o)
Skips flashing of recovery partitions. Used by minicom.
WARNING: If you are using minicom with -o option, minicom does not initialize the port and therefore does NOT check or acquire the lock files for the communication port. If minicom is running in the background and you run bootburn with the -x option, bootburn acquires the lock BEFORE accessing the communication port. So, when bootburn attempts to communicate with AURIX it fails.
-p <key_file_path>
(lower-case p)
Signs the boot loader, secure OS (TOS), kernel and BCT binary, then flashes the device. <key_file_path> must be the full pathname of the key_file.
-q
(lower-case q)
Flashes QNX images.
-s
(lower-case s)
Skips flashing the file system.
Use the -s flag only when the target file system is already flashed.
-t <output_directory>
(lower-case t)
Specifies the output directory where images to be flashed onto the target are to be stored. The default directory is named _temp_dump, and is present in the flashing directory.
-u <bootchain>_<partition_name1>_<partition_name2> …
(lower-case u)
Updates the partition name(s) and does not write anything else. Partitions bct, mb1-bootloader (-r), and pt cannot be updated using this option.
A guest partition’s partition name includes a prefix that indicates the guest ID. For example, the kernel DTB partition of guest 1 is 1_kernel-dtb.
A guest partition’s partition name includes a prefix that indicates the guest ID. For example, the kernel DTB partition of guest 1 is 1_kernel-dtb.
To update a rebuilt kernel, use this option instead of the default bootburn command, which updates all the partitions of the boot medium (NOR):
1. Back up the original kernel binaries’ Image and zImage files.
2. Copy the updated Image and zImage files to the directory:
<top>/drive-t186ref-linux/kernel-rt_patches
3. Enter this command to update the partition:
For example: Xavier A (x1) on B01 revision of e3550:
./bootburn.sh -b e3550b01-t194a -u kernel
For example: Xavier B (x2) on B01 revision of e3550:
./bootburn.sh -b e3550b01-t194b -u kernel
4. To identify the partition name, consult the configuration file used for flashing.
-v <path to self-extracting firmware>
The automatic update uses a predefined firmware file and location. This option allows you to specify the dGPU VBIOS firmware update self-extracting file to be flash with -w. The firmware package that is specified with this option must have been generated with the nvflash packaging tool. The file must be created with no user input option selected. The -w option must be selected as well.
-w
Enables the dGPU VBIOS update process. Uses the version packaged in the Foundation PDK. The automatic update is disabled by default. The firmware is taken from: <PDK_TOP>/drive-t186ref-foundation/firmwares/bin/common
-x
Specifies the communication port for AURIX to put the SoC in recovery mode automatically.
With this -x option, bootburn performs target validation for the user provided board name on the command line, with the -b option, before flashing the board.
Bootburn generates a unique ID from the target Inforom data. The allowed target ID list for the user provided board is generated from BOM data file included in the package. Bootburn aborts flashing if the target unique ID is not found in the list of generated unique IDs for the provided board name. This feature is supported on e3550b01 and e3550b03 boards with Inforom system object version 3 or above.
Note: On boards with inforom, the bct sku info is updated with the information in the inforom.
If the -x option is used during the AURIX setup, at the end during the AURIX reset of the flashing procedure there may be output messages of the form: "Killed sudo cat $l_Aurix > $p_FlashFiles/$l_AurixLogFile". These messages are not errors and can be safely ignored.
WARNING: If minicom is used with the -o option, minicom does not initialize the port and therefore does NOT check or acquire the lock files for the communication port.
If minicom is running in the background and you run bootburn with the -x option, bootburn acquires the lock BEFORE accessing the communication port. So when bootburn attempts to communicate with AURIX it fails.
If you quit minicom forcefully it may not fully stop the process and it will be lingering in the background.
When bootburn attempts to connect in this state it will acquire the port but the output will still be directed to the minicom running in the background.
Avoid using the -o option when using minicom.
-z <board_info>-
(lower-case z)
Notes: On boards with inforom, only the bct sku info is updated; inforom sku info is not updated.
Provides the board information options, which include:
--skunum: Specifies the board SKU_Info, such as: 699-62382-0010-100. The label on your board provides the value to use. SKU_Info is mandatory for the -z option.
--setskuversion: Specifies AB. The label on your board provides the value to use. AB is mandatory for the -z option.
--setprodinfo: For example, 600-62379-0100-100 AB. This option is equivalent to --skunum and --setskuversion.
--setboardserial: Specifies the five-digit serial number.
--setmacid mac0 <0xaabbccddeeff>: Specifies a 6‑byte hexadecimal serial number. Make sure when using the --setmacid option to give every device a unique MAC ID.
The -z sub-options are enclosed in quotes, and must include --skunum and --setskuversion. The other sub-options are optional. If they are provided, they are stored on the target.
For example:
-z "--skunum 699-62382-0010-100 --setskuversion AB --setprodinfo 699-62382-0010-100 AB --setboardserial 00250 --setmacid mac0 0x00504b94df"
-B <boot_device>
(upper-case B)
Specifies the boot device, which must be either qspi or emmc. qspi is the default.
-C
(upper-case C)
Specifies use of debug binaries for the boot loader.
-D
(upper-case D)
Directs bootburn debug output to stdout along with the tool’s regular output. If -D is not specified, debug output goes to a temporary file.
-E
(upper-case E)
Enables DRAM ECC.
-H
(upper-case H)
Flashes the default Hypervisor image.
-I <bus_id> <device_id>
(upper-case I)
Flashes a specific device when multiple devices are in recovery.
To get the bus and device ID of each device in recovery, enter the lsusb command on the host. For example, if lsusb gives the following output:
Bus 003 Device 105: ID 0955:7018 NVidia Corp.
Bus 003 Device 104: ID 0955:7018 NVidia Corp.
Then flash the second device with the -I option as in this example:
-I 003 104
-L
(upper-case L)
Enables low power modes. This option requires that the spe-fw and WB0 firmware packages be included in the bootburn configuration because low-power modes require them.
-M
(upper-case M)
Specifies development version firmware.
-R
(upper-case R)
Specifies RCM boot support, where the device boots without being flashed. When the target is in recovery mode, this option causes the flashing script to download all binaries, other than BCT, from the host. The target then reads the BCT from storage and other binaries from RAM. It boots the kernel directly on RAM.
This option is much faster than when flashing also occurs. It is especially useful during debugging.
Use the -R flag to initiate RCMBOOT with any of the commands mentioned in this table.
-S
(upper case S)
Skips confirmation prompts from bootburn, as if “y” is selected for each prompt.
-T
(upper-case T)
Enables tracing. Tracing logs are stored under the bootburn directory as log_trace*.txt.
-U
Pass in the UFS provision configuration file.
-V
(upper case V)
Specifies read-back verification, where the binary images are read back (after writing) from the target’s storage and compared with the original binary images. The two sets of images are compared to detect discrepancies.
-X
(upper case X)
Enable Golden Register Address:Value Dump into GR memory carveout.
Kernel Parameter Combinations
Possible combinations of kernel parameters nfsdev, ip, and nfsroot are as follows. An error indicates that the initramfs shell is started.
nfsdev
ip
nfsroot
Result
(not set)
(not set)
(not set)
no network; root must be set in some other way
(not set)
(not set)
set
error; needs IP configuration
(not set)
set
(not set)
error; no root path to mount
(not set)
set
set
valid combination
set
(not set)
(not set)
valid combination; DHCP request is sent
set
(not set)
set
error; needs IP configuration
set
set
(not set)
error; no root path to mount
set
set
set
valid combination; no DHCP requests
Passing Additional Kernel Parameters
To pass additional kernel parameters, modify the os_args parameter of the kernel-dtb and kernel-dtb-r partitions in this file.
drive-t186ref-foundation/virtualization/pct/<platform>/linux/linux_storage_qspi.cfg
Where <platform> is:
e3550xxxb01-t194a for Xavier A (x1)
e3550xxx-t194b for Xavier B (x2)
e3550xxx-t194ia for IVI SKU Xavier A(x1)
p2888-t194 for Xavier CVM
xxx in the above platform name should be replaced with b01 or b03 based on the revision of e3550 board used.
To bind:
cd <top>/drive-t186ref-foundation
make -f Makefile.bind PCT=linux BOARD=<platform>
To flash all images for Linux:
cd <top>/drive-t186ref-foundation/tools/host/flashtools/bootburn_t19x
./bootburn.sh -b <platform> -B qspi
To flash kernel-dtb only:
cd <top>/drive-t186ref-foundation/tools/host/flashtools/bootburn_t19x
./bootburn.sh -b <platform> -u 1_kernel-dtb -B qspi
Updating the path for the targetfs
To update the path for the targetfs, modify the dirname parameter of the filesystem partition in:
drive-t186ref-foundation/tools/host/flashtools/bootburn_t19x/quickboot_qspi_linux_initramfs.cfg
This step applies to the configuration file used for qspi boot, that is, modify dirname in the file that does not have _initramfs in its filename.
Using the targetfs.img file for Linux guest rootfs
Note:
This feature is only supported under Linux AV PCT.
Invoke use_rootfs_img.sh to use the targetfs.img file as Linux AV guest rootfs instead of the rootfs directory contents under drive-t186ref-linux/targetfs:
cd <top>/drive-t186ref-foundation
./drive-t186ref-foundation/tools/host/use_rootfs_img.sh
Note:
use_rootfs_img.sh does not work when using custom targetfs folders as described in Updating the path for the targetfs.
Dialout Group
Add yourself to the dialout group since it is not possible to open the serial ports to the AURIX via sudo.
To add yourself to the dialout group:
sudo adduser <user name> dialout
You must log out and log back in for the command to take effect.