Flash Steps for NVIDIA Thor System on Chip (SoC)#

Note

flash.py is deprecated in DriveOS 7.x and is no longer supported. To flash the target, use bootburn.py.

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 Python 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; the bootburn utility supports limited command-line options.

Bootburn Command Usage#

Run the bootburn.py script from a shell on your host Linux system by executing the command:

./bootburn.py <options>

Bootburn Options#

Options

Description

-b

<p3960-10-sw01 | p3960-10-sw02 | p3960-10-sw03 | p3960-30-sw01 | p3898-b00>

(lowercase b)

Provides the board name and revision. Possible board names include:

  • p3960-10-sw01

  • p3960-10-sw02

  • p3960-10-sw03

  • p3960-30-sw01

  • p3898-b00

Not all boards are supported in NSR and SR. For more information, see the NVIDIA DriveOS API Reference.

--board_config .json

Can be used with bootburn.py, create_bsp_images.py, and flash_bsp_images.py. board_name must include the absolute path.

-d (lowercase 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.

--encrypt

This is treated as a flag to indicate encryption is needed, and is used in combination with –hsm to encrypt images with secure boot encryption key. This can be used with bootburn.py and create_bsp_images.py and note that there are three sets of SBK keys, one for each cluster: psc, hpse, and sb with the full path name for each. Additionally, edit drive-foundation/tools/flashtools/flash/tegrasign_v3_debug.yaml. Default json file path is generated from the board name.

Find “SBK”.

{"HSM":
{
    "SBK_KEY"     : "sbk_hsm.key",
    "SBK_HPSE_KEY": "sbk_hsm.key",
    "SBK_SB_KEY"  : "sbk_hsm.key",
}

Where <sbk_hsm.key> is the path to the 32 bytes hexadecimal value of the key.

-f (lowercase)

Failure analysis (FA) mode support.

-g (lowercase)

Generate binaries at mentioned path only and do not flash. Used with create_bsp_images.py only.

-h (lowercase h)

Provides guidance on the actions and options of bootburn.

-i (lowercase 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 (lowercase k)

Specifies the configuration file for flashing.

-m (lowercase)

Flashing Modular Diagnostic Software (MODS). This option enables mods-specific overrides.

-o (lowercase 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 MCU it fails.

-p (lowercase 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. This option is used for filling up slot0 and slot1 with the same key, while the rest of the 14 slots are not signed. This is for development/debug purposes where user only wants to fuse two slots with the same key and does not want to use –hsm option. For production it is best to use –hsm and specify the key for each slot used in tegrasign_v3_debug.yaml. See –hsm for details.

--hsm

Can be used with bootburn.py and create_bsp_images.py. Tells Bootburn what keys will be used in HSM mode. Key String is <index>[rsa|eddsa]. Example: 15eddsa, this will tell both bootburn.py and create_bsp_images.py to use the slot15 with eddsa key entry to sign the boot artifact. Below is copied from tegrasign_v3_debug.yaml. It is suggested that user defines the SIGN_KEY_* that are planned for the production boards, where * ranges from 0 to 15, with SIGN_KEY_* defined for the slot used. Below shows SIGN_KEY_0, SIGN_KEY_1, and SIGN_KEY_15, these are required should user chooses to use slot0, slot1, and slot15 for the board’s secure boot enablement. Note that if user runs create_bsp_images.py with the updated tegrasign_v3_debug.yaml with valid key paths, and run with –hsm <index>[rsa|eddsa] option, the hash for the pkh fuse is being computed during image creation time. This hash value can be obtained by piping the output and search for the key words big-endian.

"SIGN_KEY_LIST":
{
    "FILE_NAME":   "sign_key_list.xml",
    "SIGN_KEY_0":
    {
         "PKC_KEY"     : "pkc_hsm.key",
         "PKC_PUBKEY"  : "pkc_hsm.pubkey",
         "ED25519_KEY" : "ed25519_hsm.key",
         "ECC_KEY"     : "ecc_hsm.key",
         "ECC521_KEY"  : "ecc521_hsm.key",
         "XMSS_KEY"    : "xmss_v3.key"
    },
    "SIGN_KEY_1":
    {
         "PKC_KEY"     : "pkc_hsm.key",
         "PKC_PUBKEY"  : "pkc_hsm.pubkey",
         "ED25519_KEY" : "ed25519_hsm.key",
         "ECC_KEY"     : "ecc_hsm.key",
         "ECC521_KEY"  : "ecc521_hsm.key",
         "XMSS_KEY"    : "xmss_v3.key"
    },
    "SIGN_KEY_15":
    {
         "PKC_KEY"     : "pkc_hsm.key",
         "PKC_PUBKEY"  : "pkc_hsm.pubkey",
         "ED25519_KEY" : "ed25519_hsm.key",
         "ECC_KEY"     : "ecc_hsm.key",
         "ECC521_KEY"  : "ecc521_hsm.key",
         "XMSS_KEY"    : "xmss_v3.key"
    }
}

-t (lowercase 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.

-x

Specifies the communication port for MCU 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 P3960, P3663, and P3898 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.

With this -x option, the MCU-FW is updated, if enabled in the configuration, at the end of Core Firmware flashing.

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 MCU 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.

-B (uppercase B)

Specifies the boot device, which must be either qspi or emmc. qspi is the default.

-C (uppercase C)

Specifies use of debug binaries for the boot loader.

-D (uppercase 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 (uppercase E)

Enables DRAM ECC.

-I (uppercase 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 (uppercase 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 (uppercase M)

Specifies development version firmware.

-R (uppercase 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.

-T (uppercase T)

Enables tracing. Tracing logs are stored under the bootburn directory as log_trace*.txt. Refer to the Bootburn Scripts chapter in the NVIDIA DriveOS 7.2.5.0 Safety Developer Guide for more information.

-U

Pass in the UFS provision configuration file.

-V (uppercase 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.

–customer-data

Specifies customer data such as skuinfo and others to be updated during flashing.

--clean

Used to erase qspi. .. note:: Post manufacturing the recommendation is to reprovision the UFS to completely erase and to use --clean to erase qspi.