Flashing Support

Use flash.sh to flash a Jetson device with Bootloader and the kernel, and optionally, flash the root file system to an internal or external storage device.

Use l4t_initrd_flash.sh to flash internal or external media connected to a Jetson device. This script uses the recovery initial ramdisk to do the flashing, and can flash internal and external media using the same procedure. Because this script uses the kernel for flashing, it is generally faster than flash.sh. See Flashing with Initrd for more details.

By default, the board configuration and the partition layout support external media with a storage capacity of 64GB or higher. To accommodate external media with a lower storage capacity, you need to modify the `ROOTFSSIZE` variable in the board configuration and the num_sectors field in the partition layout. For more information on how to modify the partition layout for external storage devices, see Flashing to an External Storage Device.

Before You Begin

The following directories must be present:

  • bootloader: Bootloader plus flashing tools, such as TegraFlash, CFG, and BCT

  • kernel: A kernel image /Image, DTB files, and kernel modules

  • rootfs: The root file system that you downloaded

    This directory starts empty. You populate it with the sample file system.

  • nv_tegra: User space binaries and sample applications

Additionally, before running these commands, you must connect your host computer to the Jetson device’s recovery port with a USB cable.

Basic Flashing Script Usage

Display the current usage information for flash.sh by running flash.sh –h, using the script included in the release. The basic usage is:

$ sudo ./flash.sh [options] <board> <rootdev>

Where:

  • options is one or more command line options. All of the options are optional. See Flashing Script Usage for information about the options.

  • <board> specifies the configuration to be applied to the device to be flashed. Values are listed in the Jetson Modules and Configurations table in Quick Start. flash.sh gets the configuration from a configuration file named <board>.conf. <board>.conf specifies the location of a partition layout file which specifies what storage devices are flashed on the Jetson target. For more detailed explanation of <board>.conf, see Explaining Board Configuration File and Generating a Flash Image to Flash Later .

  • <rootdev> specifies the type of device to be used as the root file system,. Use the value mmcblk0p1 to flash a local storage device (eMMC or SD card, depending on platform), as distinguished from an NFS server, for example.

Basic Flashing Procedures

This section describes some common procedures for flashing one or more target devices.

Installing the Flash Requirements

  1. Run the following command:

    $ sudo tools/l4t_flash_prerequisites.sh

Flashing the Target Device

  1. Put the target device into Force Recovery Mode.

    1. Power on the carrier board and hold down the RECOVERY button.

    2. Press the RESET button.

  2. Run the flash.sh script that is in the top-level directory of BSP for this release. The command line must specify the target board (for example, jetson-agx-orin-devkit) for the root file system:

    $ sudo ./flash.sh <board> <rootdev>

    Where:

    • <board> specifies the configuration of the target device, as described by the Jetson Modules and Configurations table in Quick Start.

    • <rootdev> specifies the device on which the root file system is located, as described in Basic Flashing Script Usage.

For examples, run the script like this:

$ sudo ./flash.sh <board> mmcblk0p1

Flashing by Using a Convenient Script

NVIDIA provides a convenient flashing script which automatically detects the Jetson device’s type of carrier board:

$ sudo ./nvsdkmanager_flash.sh [--storage <storage> ]

where --storage can be nvme0n1p1 for flashing to an external NVMe SSD or sda1 for flashing to an external USB storage drive or mmcblk11 for flashing to an external SD card.

On Jetson Orin series, flashing with the --storage option flashes also flashes the internal eMMC storage with a small boot partition that points to the external storage option as the root file system.

Without --storage option, It is expected that the Jetson devices has either internal emmc or an SD card attached if the Jetson does not have an internal emmc storage.

Flashing the Target Device to Mount a rootfs Specified by a UUID

  • For an internal storage device (e.g. eMMC or an SD card), enter the command:

    $ sudo ./flash.sh <board> internal

    This command generates a new UUID for the root file system partition and stores it in the bootloader/l4t-rootfs-uuid.txt file. You can specify your own UUID by writing the UUID to this file and execute the following command.:

    $ sudo ./flash.sh --reuse-uuid <board> internal

  • For an external stage device (e.g. an NVMe or USB device), enter the command:

    $ sudo ./flash.sh <board> external

    This command generates a new UUID for the root file system partition and stores it in the bootloader/l4t-rootfs-uuid.txt_ext file. You can specify your own UUID by writing the UUID to this file and execute the following command.:

    $ sudo ./flash.sh  --reuse-uuid <board> external

Flashing the Target Device to Mount a rootfs Specified by the Partition Device Name

Note

The commands below only flash a small boot partition to the Jetson’s internal eMMC storage to mount the USB/NVMe SSD that is externally attached to the Jetson. These commands do not actually flash the root file system contents onto the externally connected storage devices.

  • For a partition on a USB storage device connected to the Jetson device, enter this command:

    $ sudo ./flash.sh <board> sda<x>

  • For a partition on an NVMe storage device connected to the Jetson device, enter this command:

    $ sudo ./flash.sh <board> nvme0n1p<x>

    Where:

    • <board> specifies the configuration of the target device, as described in the table of device names in the topic Quick Start.

    • <x> is a number specifying the APP partition’s position on the storage device, e.g. sda1 for a USB device, or nvme0n1p1 for an NVMe storage device.

Explaining Board Configuration File and Generating a Flash Image to Flash Later

The board configuration file <board> is a bash script that defines several bash variables. These variables specify the Boot Configuration Table (BCT), Device Tree Blob (DTB), kernel, configuration files, firmwares, and partition layout to be used by flash.sh.

The board configuration file specifies a partition configuration file location in the EMMC_CFG variable which defines what storage devices are flashed by the flashing tool and the partition layout on those storage devices. The flashing tool only flashes the storage devices described in the partition configuration layout. - flash.sh allows one partition configuration file defined in the board configuration file. - l4t_initrd_flash.sh allows one partition configuration file defined in the board configuration file and one more partition configuration file passed through -c option when flashing with --external-device option, which defines the partition layout of the external device.

Refer to Partition Configuration for more information about the partition configuration file format.

Typically, NVIDIA-provided board configurations rely on values retrieved from EEPROM and the chip to define these bash variables. To generate a flash image for later flashing:

  1. Place the Jetson target into recovery mode.

  2. Use this command to retrieve the EEPROM and chip information from the board, and to subsequently generate a flash image:

    $ sudo ./flash.sh --no-flash <board> mmcblk0p1

In instances where the Jetson target in recovery mode is unavailable, it is still possible to generate flash image by using EEPROM and Chip values obtained manually through environment variables. For example:

$ sudo BOARDID=3701 BOARDSKU=0000 FAB=500 BOARDREV=500 CHIP_SKU=D0 RAMCODE=0 FUSELEVEL=fuselevel_production ./flash.sh --no-flash jetson-agx-orin-devkit mmcblk0p1

Such information is usually available on the Jetson target specification sheet. Alternatively, it can be retrieved manually if you have physical access to the Jetson target:

  1. Place the Jetson target into recovery mode.

  2. Run this command to generate bootloader/cvm.bin and bootloader/chip_info.bin_bak:

    $ sudo ./flash.sh --no-flash --no-systemimg <board> mmcblk0p1

  3. Retrieve the environment variables above using these commands:

    $ cd bootloader
$ BOARDID=$(./chkbdinfo -i cvm.bin)
$ BOARDSKU=$(./chkbdinfo -k cvm.bin)
$ FAB=$(./chkbdinfo -f cvm.bin)
$ BOARDREV=$(./chkbdinfo -r cvm.bin)
$ CHIP_SKU=$(./chkbdinfo -C chip_info.bin_bak)
$ RAMCODE_ID=$( ./chkbdinfo -R chip_info.bin_bak)
$ RAMCODE=$(echo "ibase=2; ${RAMCODE_ID//:/}" | bc)

After generating the flash image, you can proceed with flashing at a later time using these commands:

$ cd bootloader
$ sudo bash ./flashcmd.txt

Cloning a Jetson Device and Flashing

  1. Copy system.img from the file system partition you want to flash from. Enter the command:

    $ sudo ./flash.sh -r -k APP -G <clone> <board> mmcblk0p1

    Where:

    • <clone> determines the names of the copies.

    • <board> specifies the configuration of the target device.

    This step creates two copies of <clone> in the <top> directory, a sparsed image (smaller than the original) named <clone>, and an exact copy named <clone>.raw. The time it takes to back up a partition depends on the size of the partition.

    For example, if <clone> is original.img, flash.sh creates a sparsed image named original.img and an exact copy named original.img.raw.

  2. Copy <clone>.img to the <BSP>/bootloader/system.img directory, where <BSP> is the directory in which the Jetson Linux BSP is installed. Enter the command:

    $ sudo cp <clone>.img bootloader/system.img

  3. Flash the image to the target board.

    • If the target board has already been flashed, reflash the clone image to the APP partition. The time it takes to back up a partition depends on the size of the partition. To back up the partition, run the following command:

      $ sudo ./flash.sh -r -k APP <board> mmcblk0p1

    • If the target board has never been flashed, flash all of the board’s partitions. Enter the command:

      $ sudo ./flash.sh -r <board> mmcblk0p1

    Note

    If root file system of the source device for clone is resized during oem-config, the eMMC configuration file of destination device must be updated accordingly. For example, with jetson-agx-orin-devkit, root file system (APP) is the final partition before secondary_gpt. If the APP is resized to maximum allowed size, the allocation_attribute of APP partition in Linux_for_Tegra/bootloader/generic/cfg/flash_t234_qspi_sdmmc.xml must be updated from 0x8 to 0x808.

    Note

    To clone the rootfs partition of the external storage device, for example, the NVMe storage device, see Cloning rootfs with initrd.

Backing Up and Restoring a Jetson Device

NVIDIA provides tools for creating a backup image of a Jetson device and restoring the Jetson from a backup image.

Backing up a Jetson device differs from cloning one (see Cloning a Jetson Device and Flashing) because a backup image includes every partition in the device’s internal eMMC and QSPI memory, while a clone contains only the APP file system partition.

The tools for backing up and restoring a Jetson device are in this directory in the BSD:

/Linux_for_Tegra/tools/backup-restore/

Instructions for backing up and restoring a device are in the file README_backup_restore.txt in the same directory.

The time it takes to back up or restore a partition depends on the size of the partition.

Note

Workflow 3: To massflash the backup image is currently not working for Jetson Orin NX. In addition, a Jetson device needs to have an SD card or NVMe SSD attached to be able to use this tool.

RCM Booting to the NFS

  1. Put the device into reset/recovery mode.

    • Power on the carrier board and hold down the Recovery button.

    • Press the Reset button.

  2. Enter the command:

    $ sudo./flash.sh -N <ip_addr>:<root_path> --rcm-boot <board> eth0

    Where:

    • <ip_addr> is the IP address of the host system

    • <root_path> is the path to the NFS rootfs

    • <board> is the configuration of the target device as specified by the Jetson Modules and Configurations table in Quick Start.

Flashing Script Usage

This section complements Basic Flashing Script Usage by providing detailed information about flash.sh command line options and other aspects of flash.sh usage.

Command line option

Description

-c <cfgfile>

Pathname of a flash partition table configuration file.

-d <dtbfile>

Pathname of a device tree file.

-f <flashapp>

Name of the flash application to be used. Flash applications are stored in the bootloader directory. The default flash application is bootloader/tegraflash.py.

-h

Prints descriptions of the command line syntax and command line options.

-k <partition_id>

Partition name or number specified in flash.xml or flash.cfg.

-m <mts_preboot>

Name of the MTS preboot file to be used, such as mts_preboot.

-n <nfs_args>

Static NFS network assignments: <Client_IP>:­<Server_IP>:­<Gateway_IP>:­<Netmask>.

-o <odmdata>

ODM data.

-p <bp_size>

Total eMMC hardware boot partition size.

-r

Skips building system.img; reuse the existing one.

-t <tegraboot>

Pathname of a tegraboot binary, such as nvtboot.bin.

-u <PKC_key_file>

Pathname of a file containing the PKC key used for an ODM fused board.

-v <SBK_key_file>

Pathname of a file containing the Secure Boot Key (SBK) used for an ODM fused board.

-w <wb0boot>

Pathname of a warm boot binary, such as nvtbootwb0.bin.

-x <tegraid>

Processor chip ID. The default value is:

  • NVIDIA® Jetson Orin series: 0x23

-z <sn>

Serial number of the target board.

-B <boardid>

Board ID.

-C <args>

Kernel command line arguments. If this option is specified, it overrides the default values defined for flash.sh. If two or more arguments are specified, they must be enclosed in quotation marks and separated by spaces.

Kernel command line arguments are documented in the file kernel-4.9/Documentation/kernel-parameters.txt.

In the case of NFS booting, use this option to set NFS boot-related arguments if the -I option is omitted.

-F <flasher>

Pathname of a flash server, such as nvtboot_recovery_cpu.bin.

-G <file_name>

Reads the boot partition and saves the image to the specified file.

-I <initrd>

Pathname of the initrd file. The default value is null.

-K <kernel>

Pathname of a kernel image file such as zImage or Image.

-M <mts boot>

Pathname of an MTS boot file, such as mts_si.

-N <nfsroot>

NFS root address, such as <my_IP_address>:­/my/exported/nfs/rootfs.

-R <rootfs_dir>

Pathname of the sample rootfs directory.

-S <size>

Size of the rootfs in bytes. Valid only for an internal root device.

KB/MB/GB suffixes represent units of 1000, 10002, and 10003. The suffixes KiB/MiB/GiB represent of multipliers of 1024, 10242, and 10243.

For example, 2GiB represents 2×10243 bytes.

–bup

Generates Bootloader update payload (BUP).

–clean-up

Cleans up the BUP buffer when the script is flashing a multi-spec BUP.

–multi-spec

Enables support for building a multi-spec BUP.

–no-flash

Performs all steps except physically flashing the board. The script creates a system.img file.

–no-systemimg

Prevents creation or re-creation of system.img.

–sparseupdate

Only flash partitions that have changed. Currently supports only SPI flash memory.

–usb-instance <id>

USB instance to connect to; <id> a USB port path (for examples 3-14). To find the <id>, read section How to find usb-instance

–user_key <user_key_file>

Pathname of a file that contains a user key that can be used to encrypt and decrypt kernel, kernel-dtb, and initrd binary images. If user_key is specified, then the -v option must also be specified.

–sparseupdate

only flash partitions that have changed. Currently only SPI flash memory is supported.

Finding the usb-instance

The flash.sh script supports a usb-instance to flash a specific Jetson on a host that has multiple Jetson in recovery mode. This section provides information about how you can find out which usb-instance to use.

  1. Place all devices into recovery mode.

  1. Run the following command:

    $ grep <idProduct> /sys/bus/usb/devices/*/idProduct

    where idProduct is the ID for usb ID for recovery mode of the device. For example, 7023 is for Jetson AGX Orin.

    The result will be something like the following:

    /sys/bus/usb/devices/1-1.1/idProduct:7023

    1-1.1 is the usb-instance number you want to use to specify which device you want to flash

Flashing to a USB Drive

Jetson devices can be booted from a mass storage class USB device with bulk-only protocol, such as a flash drive. Hot plugging is not supported; the flash drive must be attached before the Jetson device is booted. You can manually set up a flash drive for booting as explained in To set up a flash drive manually for booting.

All Jetson devices can boot from internal storage using a boot partition and can mount an external USB drive as the root file system.

NVIDIA provides a way to simplify flashing to a USB drive that is connected to a Jetson device. For details, see To set up a USB drive as a boot device or root file system using flash with initrd.

Manually Setting Up a Flash Drive for Booting

  1. Confirm that the device can boot successfully from eMMC. If it cannot, correct the problem by flashing to eMMC first.

  2. Connect the flash drive to the host computer.

  3. Check the flash drive’s device name (e.g. /dev/sdb):

    $ sudo lsblk -p -d | grep sd

  4. Run the command:

    $ sudo <env-var> ./tools/kernel_flash/l4t_initrd_flash.sh [ -S <rootfssize> ] -c <config> --external-device sda1 --direct <sdx> <board> external

    Where

    • <sdx> is the device name that your host computer assigned to the flash drive.

    • <config> is the USB partition layout, and there is an example in Linux_for_Tegra/tools/kernel_flash/flash_l4t_t234_nvme.xml.

    • <board> is the type of Jetson device to be flashed. See the Jetson Modules and Configurations table in Quick Start.

    • You can also specify <rootfssize> as the size of the APP partition. This value is different from the total size of the external storage device, which is defined by the num_sectors field in <config>. If you change the num_sectors field in <config>, you have to specify a new <rootfssize> so that it is a few GiB smaller then the total size of the external storage device to fit the APP and other partitions.

    • If you run the command without a device in recovery mode plugged in, you will have to specify it.

    For example, if the host computer assigns the flash drive device name sdb, the command for Jetson AGX Orin is:

    $ sudo BOARDID=3701 BOARDSKU=0000 FAB=TS4 ./tools/kernel_flash/l4t_initrd_flash.sh -c tools/kernel_flash//flash_l4t_t234_nvme.xml --external-device sda1 --direct sdb jetson-agx-orin-devkit external

    By default, Linux_for_Tegra/tools/kernel_flash//flash_l4t_t234_nvme.xml only supports a 64GiB SD card and above. If you want to flash a 32GiB SD card, you will need to modify the num_sectors field in Linux_for_Tegra/tools/kernel_flash//flash_l4t_t234_nvme.xml so that num_sectors * 512 = 32GiB. The command to run is:

    $ sudo BOARDID=3701 BOARDSKU=0000 FAB=TS4 ./tools/kernel_flash/l4t_initrd_flash.sh -c tools/kernel_flash//flash_l4t_t234_nvme.xml -S 20GiB --external-device sda1 --direct sdb jetson-agx-orin-devkit external

    You have to specify <rootfssize> to 20GiB to be smaller then the SD card size.

Note

For more information, read Workflow 11 in the README_initrd_flash.txt file, which is in the Linux_for_Tegra/tools/kernel_flash directory.

  1. Plug the flash drive into the target device and power it on or reboot it.

  2. If your device still boots from its internal storage, you might need to modify the UEFI’s boot-order using efibootmgr or UEFI GUI.

Manually Setting Up a Flash Drive to Use as Root File System

  1. Prepare the flash drive similarly to

  1. Flash the Jetson device to mount the external flash drive:

    $ sudo ./flash.sh <board> sda1

Preparing Files to Boot from a Flash Drive with Secure Boot

When the Secureboot package is installed, the kernel file /boot/Image must be signed, and the signature file must be saved as /boot/Image.sig.

If you use flash.sh to flash a device with Secure Boot installed, the script automatically creates and stores the signature file. If you create a signature file manually, you must also save it manually. For more information, see the topic Secure Boot.

Setting Up a USB Drive as a Boot Device or Root File System using Flash with initrd

By flashing with initrd you can flash to an external USB device attached to a Jetson device. For more information, see Flashing to an External Storage Device.

Flashing to an NVMe Drive

Jetson devices can be booted from an NVMe drive. Hot-plugging is not supported; the NVMe drive must be attached before the Jetson device is booted.

You can manually set up an NVMe drive for booting by following the steps in To set up an NVMe drive manually for booting.

All Jetson devices can boot from internal storage using a boot partition and mount an external NVMe drive as the root file system.

NVIDIA provides a way to simplify flashing to an NVMe drive that is connected to a Jetson device. For details, see To set up an NVMe drive as a boot device or root file system using flash with initrd.

Manually Setting Up an NVMe Drive for Booting

  1. Confirm that the device can boot successfully from eMMC. If it cannot, correct the problem by flashing to eMMC first.

  2. Connect the flash drive to the host computer.

  3. Check the NVMe drive’s device name (e.g. /dev/nvme0n1):

    $ lsblk -d -p | grep nvme | cut -d\  -f 1

    Note that there must be two spaces after the -d\.

  4. Run the command:

    $ sudo <env-var> ./tools/kernel_flash/l4t_initrd_flash.sh [ -S <rootfssize> ] -c <config> --external-device nvme0n1p1 --direct <nvmeXn1> <board> external

    Where

    • <nvmeXn1> is the device name that your host computer assigns to the NVMe drive.

    • <config> is the NVMe SSD partition layout, and there is an example in Linux_for_Tegra/tools/kernel_flash//flash_l4t_t234_nvme.xml.

    • <board> is the type of Jetson device to be flashed. See the Jetson Modules and Configurations table in Quick Start.

    • You can also specify <rootfssize> as the size of the APP partition. This value is different from the total size of the external storage device, which is defined by the num_sectors field in <config>. If you change the num_sectors field in <config>, you have to specify a new <rootfssize> so that it is a few GiB smaller then the total size of the external storage device to fit the APP and other partitions.

    • If you run the command without a device in recovery mode plugged in, you will have to specify it.

    For example, if the host computer assigns the flash drive device name nvme1n1p1, the command for Jetson AGX Orin is:

    $ sudo BOARDID=3701 BOARDSKU=0000 FAB=TS4 ./tools/kernel_flash/l4t_initrd_flash.sh -c tools/kernel_flash//flash_l4t_t234_nvme.xml --external-device nvme0n1p1 --direct nvme1n1p1 jetson-agx-orin-devkit external

Note

For more information, read Workflow 11 in the README_initrd_flash.txt file, which is in the Linux_for_Tegra/tools/kernel_flash directory.

  1. Plug the flash drive into the target device and power it on or reboot it.

  2. If your device still boots from its internal storage, you might need to modify the UEFI’s boot-order using efibootmgr or the UEFI GUI.

Setting Up an NVMe Drive Manually to Use as Root File System

  1. Prepare the NVMe device similarly to

  1. Flash your Jetson to mount the external NVMe drive:

    $ sudo ./flash.sh <board> nvme0n1p1

Preparing Files to Boot from an NVMe Drive with Secure Boot

See To prepare files to boot from a flash drive with Secure Boot.

Setting Up an NVMe Drive as a Boot Device or Root File System using Flash with initrd

By flashing with initrd you can flash to an external NVMe SSD attached to a Jetson device. For more information, see Flashing to an External Storage Device.

Flashing to an SD Card

Applies to: only the Jetson Orin Nano Developer Kit.

This section describes the procedures to flash and use an SD card for the Jetson Orin Nano developer kit with the p3767-0005 module.

Prerequisites

  • Download Etcher for Linux. Etcher is the tool you use to copy an image to an SD card. It is available from the Balena Etcher home page.

    Download Etcher for Linux x64 (64-bit) (AppImage). Make the downloaded file executable.

Note

NVIDIA recommends using Etcher to copy an image to an SD card because it is an easy and foolproof method. If you prefer, you can perform this operation with the Linux dd command. If you use this method, you need not download Etcher.

Generating an Image to be Flashed to an SD Card

Applies to: only the Jetson Orin NX series

  1. If you have not already done so, expand the archive linux_for_tegra.tbz2.

  2. Go to the directory Linux_for_Tegra/tools.

  3. Enter the command:

    $ ./jetson-disk-image-creator.sh -o <blob_name> -b <board>

    Where:

    • <blob_name> is a filename; the script saves the raw image with this name.

    • <board> specifies the type of Jetson device that the SD card is to be flashed for. You can find the appropriate value of <board> in the Jetson Modules and Configurations table in Quick Start.

    This command generates a raw image with partitions as per the SPI-SD profile for a Jetson Orin NX development module.

    For example, to create a raw image file named sd-blob.img that will be used on a Jetson Orin NX development module:

    $ ./jetson-disk-image-creator.sh -o sd-blob.img -b jetson-orin-nano-devkit -r 100

The jetson-disk-image-creator.sh script supports use of a modified rootfs. Thus, you can create an SD card image with a specified rootfs directory:

$ ROOTFS_DIR=<MODIFIED_ROOTFS_PATH> ./jetson-disk-image-creator.sh -o <blob_name> -b <board> -r <revision>

Flashing the Image to an SD Card with Etcher

  1. Insert the SD card into an SD card slot or an external SD card reader on your host system.

  2. Launch Etcher and select the SD blob image file created by jetson-disk-image-creator.sh.

  3. Select the SD card to be flashed.

  4. Click Flash to write the SD blob image to the SD card.

Flashing the Image to an SD Card with dd

  • Enter the command:

    $ sudo dd if=<sd_blob_name> of=/dev/mmcblk<n> bs=1M oflag=direct

    Where:

    • <sd_blocb_name> is the name (with pathname, if necessary) of the blob image file created by jetson-disk-image-creator.sh.

    • <n> is the SD card block number detected by your Linux host, i.e. 0 or 1.

For example, to copy an image blob file named sd-blob.img from the working directory to SD card block number 1:

$ sudo dd if=sd-blob.img of=/dev/mmcblk1 bs=1M oflag=direct

Resizing the Root Partition to Fill the Available SD Card Space

The root partition is always created at the end of the boot device. This allows you to change its size without moving other partitions.

You change the size of the boot partition with the resize2fs tool, which is run by oem-config the first time a newly copied image blob file is booted from an SD card.

When a freshly initialized SD card is first booted it runs oem-config, one of whose functions is to set the APP partition’s size. It does the following things:

  1. Moves the backup GPT header to the end of the disk

  2. Deletes and re-creates the root partition

  3. Informs the kernel and OS of the change in the partition table and root partition size

  4. Resizes the file system on the root partition to fit the expected partition table and root partition size

Updating Jetson Orin Nano Devkit from JetPack 5 to JetPack 6

This update process provides out-of-the-box support to update the Jetson Orin Nano Devkit to JetPack 6 without a Linux Host. The recommended way is to flash the device directly.

Before you update, disconnect the NVMe storage from the Jetson Orin Nano Devkit and insert an SD card into the device.

To update the Jetson Orin Nano Devkit from the JetPack 5 to the JetPack 6 without using a Linux Host, follow the steps below:

  1. To update the current slot bootloader version in the QSPI to JetPack 5.1.3, you can use apt update with a JetPack 5.1.1 SD card or use a JetPack 5.1.3 SD card.

    • Using a JetPack 5.1.1 SD card:

      1. Prepare an SD card with JetPack 5.1.1 SD card image. You can download it from JetPack SDK 5.1.1. Refer to Flashing the Image to an SD Card with Etcher to prepare the SD card image.

      2. Boot the Jetson Orin Nano Devkit with the JetPack 5.1.1 SD card inserted.

      3. When prompted to Press ESCAPE for boot options from the landing page of the UEFI menu, navigate to Boot Manager to check the boot order. Make sure the UEFI SD Device is on the top of the list. If it is not, refer to Customizing the Default Boot Order in the UEFI Menu for more information about changing the boot order in the UEFI menu.

      4. Complete the oem-config if needed.

      5. After logging in, check the current slot bootloader version in the QSPI using the sudo nvbootctrl dump-slots-info command. The output Current version should be less than 35.5.0.

      6. Update to the latest JetPack 5 using Debian OTA. Refer to Updating to a New Minor Release for more information.

        To update to the latest JetPack 5.1.3:

        $ sudo vi /etc/apt/sources.list.d/nvidia-l4t-apt-source.list

### Change the r35.x to r35.5 in the following lines.
deb https://repo.download.nvidia.com/jetson/common r35.5 main
deb https://repo.download.nvidia.com/jetson/t234 r35.5 main

$ sudo apt update
$ sudo apt dist-upgrade

### Reboot the devkit.
$ sudo reboot

      1. After the Debian OTA update and boot to system, to check the current slot bootloader version is the latest, run the sudo nvbootctrl dump-slots-info command. The output should be Current version: 35.5.0.

    • Using a JetPack 5.1.3 SD card:

      1. Prepare an SD card with JetPack 5.1.3 SD card image. You can download it from JetPack SDK 5.1.3. Refer to Flashing the Image to an SD Card with Etcher for more information about preparing the SD card image.

      2. Boot the Jetson Orin Nano Devkit with the JetPack 5.1.3 SD card inserted.

      3. When you are prompted to Press ESCAPE for boot options**` * from the landing page of the UEFI menu, navigate to Boot Manager to check the boot order. Make sure the UEFI SD Device is on the top of the list. If it is not, refer to Customizing the Default Boot Order in the UEFI Menu for more information about changing the boot order in the UEFI menu.

      4. Complete the oem-config if needed.

      5. After logging in, check the current slot bootloader version in the QSPI using the sudo nvbootctrl dump-slots-info command.

        If the Current version output is less than 35.5.0, and earlier than JetPack 5.1.3, reboot the devkit to update the bootloader slot in the QSPI to JetPack 5.1.3. Ensure that the current slot bootloader version is updated to 35.5.0 after the update. Otherwise, you need to repeat the process from step b.

      Note

      • Before rebooting the devkit, to confirm the service status is 0/SUCCESS, run the sudo systemctl status nv-l4t-bootloader-config command.

      • When booting up from JetPack 5.1.3 SD with bootloader version less than 35.5.0, a background task will set UEFI capsule update request so that on next boot UEFI will trigger bootloader update automatically.

  2. Install the following Debian package to update the non-current bootloader slot in QSPI to JetPack 6, and reboot the devkit:

    $ sudo apt-get install nvidia-l4t-jetson-orin-nano-qspi-updater
$ sudo reboot

  3. After the update is completed, the devkit will boot to UEFI and halt.

Note

The halt is because of a mismatch between the bootloader in the QSPI and the file system in the SD card. The bootloader version is JetPack 6, and the file system is JetPack 5.1.3. JetPack 6 bootloader does not support the JetPack 5.1.3 file system.

  1. Power off the devkit.

  2. Prepare an SD card with the JetPack 6 GA SD card image. Refer to Flashing the Image to an SD Card with Etcher for more information.

  3. Insert the JetPack 6 GA SD card into the devkit and power it on, complete the oem-config and boot to userspace.

  4. Check the current slot bootloader version after the system boots by running the sudo nvbootctrl dump-slots-info command. The output should be Current version: 36.x.x.

  5. To sync up the other bootloader slot in the QSPI to JetPack 6, run the following command, and reboot the devkit:

    $ sudo dpkg-reconfigure nvidia-l4t-bootloader
$ sudo reboot

  6. After completing the update and booting into the system, check the current slot bootloader version by running the sudo nvbootctrl dump-slots-info command. The output should be Current version: 36.x.x, Capsule update status: 1, and the output of Current bootloader slot is different from the output in the step 7.

Flashing to an External Storage Device

The initrd flashing tool supports flashing to an external storage device. For an overview of this tool, see Flashing with initrd.

To flash an external device, you must create an external partition layout. For information about this, see External Storage Device Partition in the topic Boot Architecture.

The default partition layout for most configurations is Linux_for_Tegra/tools/kernel_flash//flash_l4t_t234_nvme.xml. This partition layout is used by SDK Manager and supports external media with a storage capacity of 64GB or higher.

The devices that Jetson Linux supports as external storage devices are the devices that which appear in the Linux file system as SCSI devices (device name /dev/sd*) and NVMe devices (/dev/nvme*n*) in the Linux “dev” file system. NVIDIA provides the necessary tools and instructions as part of the Linux BSP package. The devices might be found in the Linux_for_Tegra/tools/kernel_flash directory. For more detailed instructions, see workflows 3, 4, and 5 in the file README_initrd_flash.txt in that directory.

Flashing a Specific Partition

You can flash a specific partition instead of flashing the whole device by using the command line option -k.

  • Enter the command:

    $ sudo ./flash.sh -k <partition_name> [--image <image_name>] <board> <rootdev>

    Where:

    • <partition_name> is the name of the partition to be flashed. Possible values depend on the target device. For specific filenames, see the table of partition configuration files in the topic Partition Configuration.

    • <image_name> is the name of the image file. If omitted, flash.sh chooses the image file that was used to flash whole device.

    • <board> is the configuration of the target device as specified in the Jetson Modules and Configurations table in Quick Start.

    • <rootdev> specifies the device on which the root file system is located, as described in Basic Flashing Script Usage.

Examples

To flash A_MB1_BCT on Jetson AGX Orin series using a predefined list of configuration files:

$ sudo ./flash.sh -k A_MB1_BCT jetson-agx-orin-devkit mmcblk0p1

To flash only QSPI on Jetson Orin series:

$ sudo ./flash.sh --no-systemimg -c bootloader/generic/cfg/flash_t234_qspi.xml <board> <rootdev>

To flash only NVMe SSD:

$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --external-only --network usb0 --external-device nvme0n1 -c tools/kernel_flash//flash_l4t_t234_nvme.xml <board> <rootdev>

To flash UEFI bootloader (A_cpu-bootloader) on Jetson AGX Orin series:

$ sudo ./flash.sh -k A_cpu-bootloader jetson-agx-orin-devkit mmcblk0p1

To flash UEFI bootloader (A_cpu-bootloader) on Jetson Orin Nano series:

$ sudo ./flash.sh -k A_cpu-bootloader -c bootloader/generic/cfg/flash_t234_qspi.xml jetson-orin-nano-devkit nvme0n1p1

To flash APP partition in the NVMe:

$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --external-only --network usb0 -k APP --external-device nvme0n1 -c tools/kernel_flash//flash_l4t_t234_nvme.xml <board> <rootdev>

Flashing for NFS as Root

You can flash the device to use a network file system (NFS) as the root file system.

Flashing for a Network File System as a Root File System

  1. Put the device into Recovery Mode. Power the carrier board on; press and hold down the RECOVERY button, then press the RESET button.

  2. Enter the command:

    $ sudo ./flash.sh -N <ip_addr>:<root_path> <board> eth0

    Where:

    • <ip_addr> is the IP address of the host system.

    • <root_path> is the path to the NFS root file system.

    • <board> is the configuration of the target device as specified in the Jetson Modules and Configurations table in Quick Start.

    The command flashes Bootloader and a file system image with a /boot directory only to use the network file system at <ip_addr>:/<root_path> as the root file system at boot time.

    For the Jetson Orin NX series, if an SD card is not attached, use the following combination of commands:

    $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --no-flash -p " -c bootloader/generic/cfg/flash_t234_qspi.xml --no-systemimg" jetson-orin-nano-devkit internal

$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --no-flash -p '-N <ip_addr>:<root_path>' --external-device <storage-device> -c tools/kernel_flash/flash_l4t_external.xml --external-only --append jetson-orin-nano-devkit eth0

$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --network usb0 --flash-only

    Where, additionally:

    • <storage-device> is the external storage device that is attached to the Jetson Orin NX. For examples, --external-device nvme0n1p1 for a NVMe SSD attached to Jetson Orin NX.

Flashing with initrd

You can flash with initrd (initial RAM disk) to both internal media and external media connected to a Jetson device. The procedure uses initrd and USB device mode.

Tools and instructions for flashing with initrd can be found in the directory /Linux_for_Tegra/‌tools/‌kernel_flash/. For more detailed information, see README_initrd_flash.txt in the same directory.

README_initrd_flash.txt contains examples several workflows that flash with initrd:

  • Flashing internal storage devices

  • Flashing external storage devices such as NVMe SSD and USB drives

  • Enabling A/B rootfs on external storage devices

  • Enabling disk encryption on external storage devices

  • Flashing individual partitions

  • Flashing fused Jetson devices.

  • Flashing a Massflash blob to normal and fused Jetson devices

  • Generating separate images for external and internal storage devices, then flashing the combined images

Requirements

  1. Initrd flash requires a high-quality USB-C / micro-USB cable. (A low-quality cable might make the flashing process fail.)

  2. To install the correct dependencies, run the following script:

    $ sudo tools/l4t_flash_prerequisites.sh # For Debian-based Linux

  3. To flash, the tool uses NFS and SSH through IPv6 address space fc00:1:1::/48.

Note

  • Ensure that your operating system and your firewall allows using the IPv6 address space.

  • The tool has been validated with Ubuntu 18.04 and later.”

Flashing with initrd

The following procedure applies to devices with internal storage such as eMMC. For devices without internal storage, such as Jetson Orin Nano and Jetson Orin NX, refer to Flashing to an External Storage Device.

  1. Put the Jetson device in Recovery Mode.

  2. Enter these commands on the host:

    $ cd Linux_for_Tegra
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh <board-name> <rootdev>

    Where:

    • <board-name> is the value of the environment variable BOARD for the target device. See the Jetson Modules and Configurations table in Quick Start.

    • <rootdev> specifies the device on which the root file system is located, as described in Basic Flashing Script Usage.

Cloning rootfs with initrd

  1. Put the Jetson device in Recovery Mode.

  2. Enter these commands on the host:

    $ cd Linux_for_Tegra
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --initrd <board-name> <rootdev>

    Where:

    • <board-name> is the value of the environment variable BOARD for the target device. See the Jetson Modules and Configurations table in Quick Start.

    • <rootdev> specifies the device on which the root file system is located, as described in Basic Flashing Script Usage.

  3. Enter bash shell on the Jetson device.

  4. Plug a USB drive into Jetson device and clone rootfs partition as an exact copy system.img.raw into this USB drive by running the following commands:

    $ mount /dev/sda1 /mnt
$ dd if=<rootfs partition> of=/mnt/system.img.raw
$ sync
$ umount /mnt

The /dev/sda1 is the plugged USB drive. The <rootfs partition> might be /dev/mmcblk0p1 for eMMC device or /dev/nvme0n1p1 for NVMe device.

  1. Unplug the USB drive from Jetson device and plug it into host machine.

  2. Copy the system.img.raw file from the USB drive the to host machine.

  3. Convert it to the system.img sparse image by running the following command:

    $ cd Linux_for_Tegra
$ ./bootloader/mksparse --fillpattern=0 system.img.raw system.img

Bringing Up the Jetson Module for the initrd Flash Tool

  • Initrd flash is validated to work with the NVIDIA developer kit. For this tool to work on your custom carrier board with Jetson’s modules, ensure that a USB device mode has been enabled for your custom carrier board.

  • There are many cases where you want to customize the BSP. In some cases, it might cause the BSP fail to initrd flash the device. For these cases initrd flash support a separation of flashing environment and the content that is flashed:

  1. Copy the original Linux_for_Tegra folder and call it Linux_for_Tegra_original.

  2. Modify the BSP in the Linux_for_Tegra_modified folder.

  3. Run the initrd flash command with the –no-flash option on the Linux_for_Tegra folder with the modified BSP. For example:

    $ cd Linux_for_Tegra_modified
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --no-flash --external-device nvme0n1p1 -c ./tools/kernel_flash//flash_l4t_t234_nvme.xml --showlogs jetson-orin-nano-devkit nvme0n1p1

  4. If necessary, remove the existing Linux_for_Tegra_original/tools/kernel_flash/images folder and copy the images in Linux_for_Tegra/tools/kernel_flash/images to the Linux_for_Tegra_original/tools/kernel_flash directory.

  5. In the Linux_for_Tegra_original directory, run flash with the –use-backup-image option. For example:

    $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --use-backup-image --external-device nvme0n1p1 -c ./tools/kernel_flash//flash_l4t_t234_nvme.xml --showlogs jetson-orin-nano-devkit nvme0n1p1

Flashing to Multiple Jetson Devices

As part of the tool in Flashing with initrd, NVIDIA provides a tool and instructions to efficiently flash Jetson devices in a factory environment. To flash to multiple Jetson devices with this tool:

  1. Generate massflash package using the --no-flash and --massflash <x> and --network usb0 options, where <x> is the highest possible number of devices that will be concurrently flashed.

The online mode and offline mode are supported. In the following example, the offline mode is used to create a flashing environment that can concurrently flash five devices:

$ sudo BOARDID=<BOARDID> FAB=<FAB> BOARDSKU=<BOARDSKU> BOARDREV=<BOARDREV> CHIP_SKU="00:00:00:xx"  ./tools/kernel_flash/l4t_initrd_flash.sh --no-flash --network usb0 --massflash 5 jetson-orin-nano-devkit mmcblk0p1

For the value of BOARDID, FAB, BOARDSKU and BOARDREV, refer to Devices Supported By This Document, Flashing with initrd, and Explaining Board Configuration File and Generating a Flash Image to Flash Later.

  1. Connect the five Jetson devices to the flashing hosts.

  2. Ensure that the devices have the identical hardware revision.

  3. Place all of the connected Jetson devices into RCM mode.

  4. Run the following command:

    $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --flash-only --network usb0 --massflash 5 (Optionally add --showlogs to show all of the log)

Note

The actual number of connected devices can be less than the maximum number of devices the package can support.

When you use this tool, here are some tips to remember:

  • The tool provides the --keep option to keep the flash environment, and the --reuse options to reuse the flash environment that makes massflash run faster:

    • For the initial mass flash:

      $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --flash-only --network usb0 --massflash 5 --keep

    • For subsequent mass flash attempts:

      $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --flash-only --network usb0 --massflash 5 --reuse

  • Use ionice to make the flash process the highest I/O priority in the system:

    $ sudo ionice -c 1 -n 0 ./tools/kernel_flash/l4t_initrd_flash.sh --network usb0 --flash-only --massflash 5

  • If mass flashing with UEFI secure boot enabled, please refer to Workflow 8 in <Linux_for_Tegra>/tools/kernel_flash/README_initrd_flash.txt. For example, mass flashing with UEFI payload encryption:

    $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh –flash-only –network usb0 –massflash 5 –uefi-keys uefi_keys.conf –uefi-enc uefi_payload_encryption.key

Flashing to Jetson Without Reading EEPROM

Sometimes when you update the customer over-writable section of the EEPROM, a mistake can be made where the CRC-8 is no longer correct. In this case, you might have issues being able to flash and boot the system. To skip the EEPROM read during flashing, run the following command:

$sudo SKIP_EEPROM_CHECK=1 BOARDID=<BOARDID> BOARDSKU=<BOARDSKU> ./flash.sh <board> <rootdev>

For the BOARDID and BOARDSKU values, refer to Devices Supported By This Document and Flashing with initrd for more information.

After the board is flashed and boots up, to correct the EEPROM content, complete the following steps:

  1. Use the Linux i2c-tools to correct corrupted EEPROM content.

  2. Dump the complete EEPROM content with i2c-tools.

  3. Calculate the CRC8 value based on the result from step 2.

  4. Write the CRC8 value to byte 255 in EEPROM.

Refer to Jetson EEPROM Layout for more information about EEPROM content and calculating CRC8.

Note

This method only should be used for the CRC-8 checksum bit corruption in EEPROM. If your module has another faulty EERPOM or I2C, consider using RMA instead of the method above.

Enlarging an Internal Memory Partition for Root File System

Use the flash.sh option -S <size-in-bytes> to change the partition size.

Flashing for a Larger Partition

  • Execute the following command:

    $ sudo ./flash.sh -S <size> <board> <rootdev>

    Where:

    • <size> is the desired size for the partition, such as 8589934592 (or 8GiB) for 8 GB. The default size of APP is defined in the variable ROOTFSSIZE in the file <board>.conf.

    • <board> is the configuration of the target device as specified in the Jetson Modules and Configurations table in Quick Start.

    • <rootdev> specifies the device on which the root file system is located, as described in Basic Flashing Script Usage.

Determining the Success of a Driver Update

After updating drivers on a target board, verify that the update completed successfully. You can determine the success or failure of a driver update by using the following commands.

Determining the Success of a Driver Update

  • Execute this command on a booted target device:

    $ sha1sum –c /etc/nv_tegra_release

If the driver update succeeded, the command displays OK after the file name. A typical success message looks like this:

/usr/lib/xorg/modules/drivers/nvidia_drv.so: OK

The driver update fails if the file is missing. A typical error message looks like this:

sha1sum: /usr/lib/xorg/modules/drivers/nvidia_drv.so: No such file or directory
/usr/lib/xorg/modules/drivers/nvidia_drv.so: FAILED open or read

The driver update also fails if the new file is different from the existing file, producing an error such as:

/usr/lib/xorg/modules/drivers/nvidia_drv.so: FAILED

Reconfiguring a Jetson Device with oem-config

A target device that is flashed by SDK Manager runs the oem-config tool automatically the first time it boots after it is flashed. You can use this tool to change some parts of the device’s configuration.

oem-config is useful for custom-configuring production devices. In a typical use case, you flash a default configuration and clone it to many production devices. The purchaser of each device can use oem-config to set their own username and password, language, time zone, and so on.

On a headed target device (one equipped with a display), oem-config runs as a GUI application. On a headless target device (one without a display), it runs as a character interface application which communicates through the flashing port with a terminal program running on the host.

After the target device runs oem-config on first boot, it disables the tool so that it will not run on subsequent boots. If you install your own package and flash the target device manually (outside SDK Manager), you must re-enable oem-config manually if you want it to run on the first subsequent boot. Again, the target device disables oem-config after running it once.

Manually Enabling oem-config Again on a Flash Drive

  1. Select a source device of the same type as the target device(s), on which all necessary packages have been installed.

  2. Install these packages on the source device to enable oem-config for the next reboot: ubiquity, oem-config, and oem-config-gtk. Enter this command:

    $ sudo apt-get install --no-install-recommends ubiquity oem-config oem-config-gtk

  3. Remove the package nvidia-l4t-oem-config:

    $ sudo dpkg --purge nvidia-l4t-oem-config

  4. Clone the source device’s APP partition to backup.img and backup.img.raw. For details, see To clone a Jetson device and flash.

  5. Mount backup.img.raw (an ext4 image file) on the host at a mount point of your choice.

  6. Apply any required Jetson-specific binaries to the image file. The nv-oem-config setup files are included in apply_binaries.sh. To run this script, enter:

    $ cd Linux_for_Tegra
$ sudo ./apply_binaries.sh -r <root>

    Where <root> represents the backup.img.raw mount point.

  7. Set nv-oem-config.target as the default.target:

    $ cd $root/etc/systemd/system
$ sudo rm default.target
$ sudo ln -s /lib/systemd/system/nv-oem-config.target default.target

  8. Unmount the device mounted in step 5:

    $ umount $root

  9. Make a sparse version of the updated image file backup.img.raw and name it system.img:

    $ cd Linux_for_Tegra/bootloader/
$ sudo ./mksparse -v –fillpattern=0 /path/to/backup.img.raw system.img

  10. Flash system.img to the target device(s). For details, see To clone a Jetson device and flash.

Manually Enabling oem-config on a on an SD Card

  1. Select a source device of the same type as the target device(s) on which all necessary packages have been installed.

  2. Enter this command to install the following packages on the source device to enable oem-config for the next reboot: ubiquity, oem-config, and oem-config-gtk:

    $ sudo apt-get install --no-install-recommends ubiquity oem-config oem-config-gtk

  3. Remove the package nvidia-l4t-oem-config:

    $ sudo dpkg --purge nvidia-l4t-oem-config

  4. Power off the source device and remove the SD card from it, then insert it into in the host system.

  5. Mount partition #1 of the SD card (an ext4 file system) on the host, using a mount point of your choice.

  6. Apply any required Jetson-specific binaries to partition #1 of the SD card. The appropriate files are listed in nv-oem-config, and are applied by apply_binaries.sh. Enter these commands to run the script:

    $ cd Linux_for_Tegra
$ sudo ./apply_binaries.sh -r <root>

    Where <root> represents the partition #1 of the SD card mount point.

  7. Set nv-oem-config.target as the default.target:

    $ cd $root/etc/systemd/system
$ sudo rm default.target
$ sudo ln -s /lib/systemd/system/nv-oem-config.target default.target

  8. Run jetson-disk-image-creator.sh to create a new SD card image with a modified rootfs:

    $ cd Linux_for_Tegra/tools
$ sudo ROOTFS_DIR=<root> ./jetson-disk-image-creator.sh -o sd-blob.img -b jetson-nano-devkit -r 100

    Where <root> represents partition #1 of the SD card on its mount point.For details, see To generate an image to be flashed to an SD card.

  9. Enter this command to unmount the device mounted in step 5:

    $ umount $root

  10. Flash sd-blob.img to the new SD card. For details, see Flashing to an SD Card.

Communication Through the Debugging Port

The terminal program on the host computer customarily communicates with oem-config through the host computer’s tty device and the Jetson device’s flashing port (i.e. the USB port that is used for flashing). See Assumptions in the topic Quick Start.)

Some Jetson developer kits also have a UART port on a 40-pin header. You can edit the oem-config configuration file to make oem-config use this port instead. You must make this change before you flash images on the target device.

Configuring oem-config to Use a 40-pin Header UART Port

  1. Open the configuration file <top>/etc/nv-oem-config.conf on the host computer and find the line that defines the property:

    nv-oem-config-uart-port=ttyGS0

  2. Change the value of this property from ttyGS0 to ttyTHS0.

  3. Save and close the configuration file.

  4. Proceed to flash the target device as described elsewhere in this topic.

Headless Mode Flow in oem-config

Before the target system boots for the first time, you must start a terminal program on the host computer. You can use putty, screen, or any other program that communicates through the host computer’s tty device and supports the UTF-8 character set.

Note

NVIDIA does not recommend using minicom for this application because it has some issues dealing with UTF-8.

When the target device boots for the first time after flashing and finds no display device, it runs oem-config in headless mode. Use the following procedure to reconfigure the target device.

Reconfiguring the Target Device with oem-config

  1. oem-config displays a welcome screen. To advance to the next screen, press Tab, then Enter.

    ../_images/OemConfigWelcome.png

  2. oem-config displays the license that governs its use. Read the license, then accept it by pressing Tab, then Enter.

    ../_images/OemConfigLicense.png

  3. oem-config displays a screen that lists languages. Use the up and down-arrow keys to select the language you want to use for the installation process. Then press the left and right-arrow keys to select “OK,” and press Enter.

    ../_images/OemConfigLanguages.png

Note

To go back from any screen to the preceding one, select “Cancel” and press Enter. You can go back more than one screen by doing this more than once.

  1. oem-config displays a screen that lists locations in which the language you selected is used. Select your location; then select “OK” and press Enter.

    ../_images/OemConfigTimeLocations.png

  2. oem-config displays a screen that lists keyboard layouts. Select your keyboard’s layout, then select “OK” and press Enter.

    ../_images/OemConfigKeyboards.png

  3. oem-config displays a screen that lists time zones that exist in the location you select. Select your time zone, then select “OK” and press Enter.

    ../_images/OemConfigTimeZones.png

    If your time zone is not listed, select “Cancel” as many times as necessary to go back to the screen that lists locations, and choose a different location.

  4. oem-config asks whether you want to set the system clock to Universal coordinated Time (UTC, or Greenwich Mean Time). Linux expects the system clock to be set to UTC, so NVIDIA recommends that you select “Yes” and press Enter.

    ../_images/OemConfigSetUtc.png

  5. oem-config asks you to enter your name. Enter your full name (for example, John Smith), select OK, and press Enter.

    ../_images/OemConfigFullName.png

  6. oem-config asks you to enter a username for your user account. oem-config creates a user account with this name. Select “OK” and press Enter.

    ../_images/OemConfigUserName.png

    NVIDIA suggests using your first name, in lower case letters only. Use this account instead of the root account for anything other than administrative activities.

  7. oem-config asks you to enter a password for your user account. Enter a password, then select “OK” and press Enter.

    NVIDIA recommends that you choose a strong password, for example, one that is more than eight characters long and contains at least one each of upper and lower case letters, numerals, and other characters. If you enter a weak password, oem-config asks you to confirm that you want to use it.

    ../_images/OemConfigPassword.png

  8. oem-config asks you to enter your password again to confirm that you entered it correctly. If you enter the same password both times, it sets the password and goes on to the next step. If not, it prompts you to enter a password again.

    ../_images/OemConfigPasswordAgain.png

  9. oem-config prompts you to create and enable a 4 GB swap file. It first displays a message which summarizes the advantages and disadvantages of doing so:

    ../_images/OemConfigSwapFile.png

    Read the message and decide whether to create a swap file. Then press Enter to advance to the next screen:

    ../_images/OemConfigSwapFileCreate.png

    To create and enable a swap file, select “Yes” and press Enter. To skip this step, select “No” and press Enter.

Note

As the “Create Swap File” screen explains, NVIDIA recommends that you create and enable a swap file if you plan to use your Jetson device for artificial intelligence (AI) and deep learning applications.

Having a swap file might shorten the life of your SD card, due to increased writes to the medium.

If you do not create a swap file in oem-config, you can later create one manually as described in To create and enable a swap file manually.

  1. oem-config prompts you to specify the desired size of the APP partition in megabytes. To request the maximum possible size, leave the field empty or enter 0 (zero).

    ../_images/OemCongAppSize.png

To request the maximum possible size, leave the field empty or enter 0 (zero).

  1. oem-config displays a list of interfaces which it can use as the primary network interface during installation.

    If you are using Ethernet as the primary network interface, make sure that the Ethernet cable is connected. Then select the eth0: Ethernet option, select “OK,” and press Enter.

    ../_images/OemConfigNetworkInterface.png

Note

Due to a known wireless network configuration bug in oem-config, you must either enter the SSID manually instead of selecting it from the list, or wait until after initial setup is complete, then use the nmcli command to configure wireless networking. For more details, see the ubuntu.com documentation page Configure WiFi Connections.

  1. oem-config prompts you to enter your host computer’s host name. If you don’t know the host’s name, ask your network administrator. If you are setting up a dedicated network, you can select any name. Enter the host name, then select “OK,” and press Enter.

    ../_images/OemConfigHostName.png

  2. oem-config prompts you to install Chromium Browser right now. Internet connection is required for installation, and it will take several minutes to install.

    ../_images/OemConfigChromium.png

    Read the message and decide whether to install Chromium Browser. Then press Enter to advance to the next screen:

    ../_images/OemConfigChromiumInstall.png

    To install Chromium Browser, select “Yes” and press Enter. To skip this step, select “No” and press Enter.

  3. oem-config reconfigures the system with the selections you have made, then proceeds to the system’s log-in prompt.

Manually Creating and Enabling a Swap File

This procedure is an alternative to step 12 of To reconfigure the target device with oem-config. You can perform it at any time after you run oem-config.

  1. To create the swap file, enter the commands:

    $ sudo fallocate -l 4G /swapfile
$ sudo chmod 600 /swapfile
$ sudo mkswap /swapfile
$ sudo swapon /swapfile

  2. To automount the swap file on boot, open /etc/fstab in a text editor, add this line, and save:

    /swapfile swap swap defaults 0 0

Note

The fields in this line might be separated by any combination and number of tabs and spaces. NVIDIA recommends spacing the fields to align with the fields in the file’s other lines.

Skipping oem-config

If you don’t want to run oem-config to set up your system, you can make the first-time boot process skip it by running the host script l4t_create_default_user.sh before you flash. The boot process runs oem-config if no default user is defined; l4t_create_default_user.sh creates a default user, and thus prevents oem-config from running.

The script’s usage is:

$ l4t_create_default_user.sh [-u <user>] [-p <pswd>] [-n <host>] [-a] [-h]

This table describes the command line options:

Command line option

Description

-u <user>

–username <user>

Creates a default user with the specified username. If omitted, the script creates a default user named nvidia.

-p <pswd>

–password <pswd>

Creates the default user with the specified password. If omitted, the script generates a random password.

-n <host>

–hostname <host>

Creates the default user with the specified host name. If omitted, the script uses the host name tegra-ubuntu.

-a

–autologin

Configures Jetson Linux to log in to the default user automatically when booted. If omitted, the user must log in manually.

–accept-license

Accepts the EULA for NVIDIA software. If omitted, the script prompts you to accept the EULA.

-h

–help

Prints a description of the script’s usage.

Examples

  • Create a user named nvidia with the password NDZjMWM4 and the host name tegra-ubuntu:

    $ l4t_create_default_user.sh -u nvidia -p NDZjMWM4

  • Create a user named ubuntu with a randomly generated password and the host name tegra-ubuntu, and configures Jetson Linux to log in to it automatically at boot:

    $ l4t_create_default_user.sh -u ubuntu -a

  • Create a user named nvidia with a randomly generated password and the host name tegra:

    $ l4t_create_default_user.sh -n tegra

Modifying Jetson RAM Disk

Use the following procedure to modify the default configuration of a Jetson device’s RAM disk.

Modifying the RAM Disk

  1. Unpack your initrd:

    $ sudo su
$ cp <initrd_file> /tmp/l4t_initrd.img
$ mkdir /tmp/temp
$ cd /tmp/temp
$ gunzip -c /tmp/l4t_initrd.img | cpio -i

  2. Modify your initrd content in the tmp/temp/ directory according to your needs

  3. Package your initrd:

    $ sudo su
$ cd /tmp/temp
$ find . | cpio -H newc -o | gzip -9 -n > ../l4t_initrd.img

  4. Replace the initrd with your customized initrd:

    $ cp /tmp/l4t_initrd.img /boot/l4t_initrd.img

Enabling AGX Orin, Orin NX, and Orin Nano in USB3 Recovery Mode

To enable Orin series devices in USB3 recovery mode, complete the following steps:

  1. Download and set up the Factory Secure Key Provisioning tool.

  2. Place the device in recovery mode and connect to the host PC.

  3. On the host PC, navigate to the Linux_for_Tegra folder.

  4. Create a Fuse configuration file called usb3.xml with the following content:

    <genericfuse MagicId="0x45535546" version="1.0.0">
<fuse name="BootDevInfo" size="4" value="0x00000900"/>
<fuse name="SwReserved" size="4" value="0x00000080"/>
</genericfuse>

  5. Run the following command to use the fuse configuration file:

    # For Jetson Orin NX and Orin Nano series
$ sudo ./fskp_fuseburn.py --board-spec orinnano-board-spec.txt -f usb3.xml -b -K -c 0x23 -B <project_base_directory>/Linux_for_Tegra/jetson-orin-nano-devkit.conf
# For Jetson Orin AGX series
$ sudo ./fskp_fuseburn.py --board-spec orin-agx-board-spec.txt -f usb3.xml -b -K -c 0x23 -B <project_base_directory>/Linux_for_Tegra/jetson-agx-orin-devkit.conf

  6. Reset the device into recovery mode and run the $ lsusb -t command to confirm that the device is in USB3 mode.

Note

This step is irreversible.

Refer to Fuse Configuration File in Secure Boot and Using the Fuse Burning Toolkit for T234 from Jetson Download Center for more information about Fuse Configuration File and fskp_fuseburn.py.

Using initrd Flash with Orin NX and Nano

Initrd flash is the official method of flashing Jetson Orin NX series and Jetson Orin Nano series with NVMe as the external storage device. You can flash it for different cases by using the following commands:

  • Flashing for the default case:

    $ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --external-device nvme0n1p1 -p "-c ./bootloader/generic/cfg/flash_t234_qspi.xml" -c ./tools/kernel_flash/flash_l4t_t234_nvme.xml --showlogs --network usb0 jetson-orin-nano-devkit nvme0n1p1

  • Flashing with rootfs A/B enabled:

    # Generate images for QSPI
$ sudo ROOTFS_AB=1 ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs -p "-c bootloader/generic/cfg/flash_t234_qspi.xml" --no-flash --network usb0 jetson-orin-nano-devkit internal

# Generate images for external storage device
$ sudo ROOTFS_AB=1 ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --no-flash --external-device nvme0n1p1 -c ./tools/kernel_flash/flash_l4t_t234_nvme_rootfs_ab.xml --external-only --append --network usb0 jetson-orin-nano-devkit external

# Flash images into the both storage devices
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --network usb0 --flash-only

  • Flashing with disk encryption enabled:

    # Generate images for QSPI
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs -p "-c bootloader/generic/cfg/flash_t234_qspi.xml" --no-flash --network usb0 jetson-orin-nano-devkit internal

# Generate images for external storage device
$ sudo ROOTFS_ENC=1 ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --no-flash --external-device nvme0n1p1 -i ./ekb.key -c ./tools/kernel_flash/flash_l4t_t234_nvme_rootfs_enc.xml --external-only --append --network usb0 jetson-orin-nano-devkit external

# Flash images into the both storage devices
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --network usb0 --flash-only

Note

The “-i ./ekb.key” option specifies the disk encryption key. Refer to How to Create an Encrypted Rootfs on the Host in Disk Encryption.

  • Flashing with both rootfs A/B and disk encryption enabled:

    # Generate images for QSPI
$ sudo ROOTFS_AB=1 ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs -p "-c bootloader/generic/cfg/flash_t234_qspi.xml" --no-flash --network usb0 jetson-orin-nano-devkit internal

# Generate images for external storage device
$ sudo ROOTFS_AB=1 ROOTFS_ENC=1 ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --no-flash --external-device nvme0n1p1 -i ./ekb.key -c ./tools/kernel_flash/flash_l4t_t234_nvme_rootfs_ab_enc.xml --external-only --append --network usb0 jetson-orin-nano-devkit external

# Flash images into the both storage devices
$ sudo ./tools/kernel_flash/l4t_initrd_flash.sh --showlogs --network usb0 --flash-only

Using flash.sh with Orin NX and Nano

Note

The official method of flashing Orin NX and Nano is to use initrd flashing.

The memory layout used by flash.sh differs from the layout used by initrd flashing. To ensure successful OTA updates, production systems must use initrd flashing.

For development purposes, for features such as partition flashing, you might want to use flash.sh. The following flash configurations can be used with flash.sh:

  • jetson-orin-nano-devkit (supports SD card)

    Here is an example of flashing an SD card on the Jetson Orin Nano Developer Kit:

    $ sudo ./flash.sh jetson-orin-nano-devkit internal

  • jetson-orin-nano-devkit-nvme (supports NVME)

    To flash NVME, you need to know the PCIe controller that corresponds to the connector where the NVME is inserted. The PCIe C4 slot is the longer slot and holds a M2.2280 NVME card. The PCIe C7 slot holds M2.2230, which are the shorter form factor NVME cards.

    Here is an example of flashing a Jetson Orin Nano Developer Kit with an NVME that is connected to PCIe C4:

    $ sudo ./flash.sh jetson-orin-nano-devkit-nvme internal

    Here is an example of flashing a Jetson Orin Nano Developer Kit with an NVME that is connected to PCIe C7:

    $ sudo UPHYLANE="c7x2" ./flash.sh jetson-orin-nano-devkit-nvme internal

Configuring a PXE Boot Server for UEFI bootloader on Jetson

This section assumes that users understand how to set up their network and the configuration requirements.

The UEFI bootloader on Jetson can boot from a PXE Boot Server without using a special flashing configuration.

The PXE Boot Server comprises the following components:

  • DHCP server: provides the IP address information and the location of the initial application (NBP).

  • TFTP server: hosts the NBP and other initial files (kernel, grub.cfg, initrd, and so on).

  • NFS server: exposes the root file system for the boot.

The DHCP should be configured to point to the NBP program. Here is a sample configuration for the isc-dhcp` server. You need to modify the following configuration based on your network configuration and usage):

subnet 192.168.0.0 netmask 255.255.255.0 {
        range 192.168.0.11 192.168.0.20;
        option routers 192.168.0.1;

        # Required for PXE Boot
        class "pxeclients" {
                match if substring (option vendor-class-identifier, 0, 9) = "PXEClient";
                        filename "efi/grubnetaa64.efi.signed";
                        # TFTP Server IP address
                        next-server 192.168.0.1;
                        option root-path "/tftp/";
        }
}

host mytegra {
  hardware ethernet 48:B0:2D:B1:48:25;
  fixed-address 192.168.0.10;
}

The Kernel and initrd can be taken from the board support package directory as Image and initrd and are placed in the directory to which grub.cfg points.

For example, the grub config that pulls kernel/initrd from root of TFTP and boots from nfs location 192.168.42.1:/volume1/nfs_root:

set timeout_style=menu
set timeout=5

menuentry "Jetson" {
      linux /Image root=/dev/nfs rw netdevwait ip=:::::eth0:on nfsroot=192.168.42.1:/volume1/nfs_root fbcon=map:0 net.ifnames=0  console=ttyTCU0,115200 firmware_class.path=/etc/firmware fbcon=map:0 net.ifnames=0
      initrd /initrd
}

The TFPT server configuration using the tftpd-hpa on an Ubuntu machine:

# /etc/default/tftpd-hpa

TFTP_USERNAME="<vrlhostname>"
TFTP_DIRECTORY="/tftp"
TFTP_ADDRESS=":69"
TFTP_OPTIONS="--secure"

The kernel, the initrd, and the grub bootloader needs to be present at these locations:

/tftp/efi/grubnetaa64.efi.signed
/tftp/Image
/tftp/initrd

The NFS server /etc/exports configuration file on the NFS host with IP 192.168.42.1:

# /etc/exports
/volume1/nfs_root *(async,rw,no_root_squash,no_all_squash,no_subtree_check,insecure,anonuid=1000,anongid=1000)"

The root file system should be exported using an NFS server. After you finish configuring:

  1. Reboot Jetson.

  2. Press Esc during boot time to access UEFI boot menu.

  3. select the PXEv4 boot option of the network device from which you want to boot.