Use the flash.sh helper script to flash the board with the bootloader and kernel, and optionally, flash the root file system to internal eMMC.
Before You Begin
The following directories must be present:
• bootloader: Bootloader plus flashing tools, such as NvFlash, CFG, BCT, etc.
• kernel: A kernel Image /vmlinux.uimg, DTB files, and kernel modules
• rootfs: The root file system that you download
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 have the USB cable connected to the recovery port.
Basic Flash Script Usage
Locate the most up-to-date usage information by running flash.sh –h (using the flash.sh script included in the release). The basic usage is as follows.
$ sudo ./flash.sh [switches] <board> <rootdev>
Where:
• switches is one or more command line switches. All switches are optional. Switches are described in Flash Script Usage.
• <board> specifies the configuration to be applied to the device to be flashed. Values are listed in the table of device names in the Quick Start Guide topic. flash.sh gets the configuration from a configuration file named <board>.conf.
• <rootdev> specifies the type of device that is to be flashed:
Type of device
<rootdev>
Jetson Nano development module QSPI RAM
mmcblk0p1
Jetson Nano development module SD card
mmcblk0p1
Jetson Nano development module eMMC RAM
mmcblk0p1
Jetson Xavier series
mmcblk0p1
Jetson TX2 series
mmcblk0p1
Jetson TX1
mmcblk0p1
Basic Flashing Procedures
This section describes some common procedures for flashing one or more target devices.
To flash using USB
Use the USB device mode default configuration script and associated README that describes how the USB flashing port operates in device mode.
1. Put the target device into reset/recovery mode.
1. Power on the carrier board and hold the RECOVERY button.
2. Press the RESET button.
2. Run the flash.sh script that is in the top-level directory of this release. The script must be supplied with the target board (e.g. jetson-xavier) for the root file system:
• <rootdev> depends on where the root file system is located:
For a root file system, execute the script like this:
$ sudo ./flash.sh <board> mmcblk0p1
To flash the target device to mount a rootfs specified by UUID
• Enter this command:
$ sudo ./flash.sh <board> internal
This command stores the UUID used for the root file-system partition in the file bootloader/l4t-rootfs-uuid.txt. You may specify your own UUID by writing the UUID to this file before executing the command above.
To clone a Jetson device and flash
1. Copy system.img from the filesystem partition you want to flash from. Enter this command:
• <board> specifies the configurationof 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.
For example, if <clone> is original.img, flash.sh creates a sparsed image named original.img and an exact copy named original.img.raw.
3. Copy <clone>.img to the <L4T>/bootloader/system.img directory. Enter this command:
$ sudo cp <clone>.img bootloader/system.img
4. Flash the image to the target board.
• If the target board has already been flashed, reflash the clone image to the APP partition. Enter this 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 this command:
$ sudo ./flash.sh -r <board> mmcblk0p1
To RAM boot to NFS (Jetson AGX Xavier series only)
1. Put the device into reset/recovery mode.
• Power on the carrier board and hold the RECOVERY button.
This section complements Basic Flash Script Usage by providing detailed information about flash.sh command line switches and other aspects of flash.sh usage.
Command line switch
Description
-b <bctfile>
Pathname of a boot control table configuration file.
-c <cfgfile>
Pathname of a flash partition table configuration file.
-d <dtbfile>
Pathname of a device tree file.
-e <emmc size>
Target device's eMMC memory size. Applies only to target devices that use eMMC.
-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 switches.
-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.
Skips building system.img; reuse the existing one.
-s <PKC_ key_ file>
Pathname of a file containing the PKC key used for signing and building bl_update_payload. (Obsolete)
-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:
• Jetson Nano and Jetson TX1: 0x21
• Jetson Xavier series: 0x19
• Jetson TX2 series: 0x18
-y <fusetype>
PKC if Secureboot is used, or NS otherwise.
-z <sn>
Serial number of the target board.
-B <boardid>
Board ID.
-C <args>
Kernel command line arguments. If this switch 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.
In the case of NFS booting, use this switch to set NFS booting related arguments if the -I option is omitted.
-F <flasher>
Pathname of a flash server such as cboot.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.
-L <bootloader>
Pathname of a Bootloader such as cboot.bin or u-boot-dtb.bin.
-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.
-P <ppt_end_plus1>
Deprecated. End of the PPT plus 1; primary GPT start address + size of PPT + 1.
-R <rootfs_dir>
Pathname of the sample rootfs directory.
-S <size>
Size of the rootfs in bytes. Valid only for an internal rootdev. KB/MB/GB suffixes represent units of 1000, 10002, and 10003. KiB/MiB/GiB suffixes represents of 1024, 10242, and 10243. For example, 2GiB represents 2×1024×1024×1024 bytes.
--bup
Generates Bootloader update payload (BUP).
--clean-up
Cleans up the BUP buffer when ‑‑multi-spec is enabled.
--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.
--usb-instance <id>
USB instance to connect to; <id> is an integer ID (e.g. 0, 1), a bus/dev (e.g. 003/091), or a USB port path (e.g. 3-14). The last is the recommended form.
Flashing to a Flash Drive
Applies to: Jetson Xavier NX and Jetson AGX Xavier series devices only
Jetson Xavier NX and Jetson AGX Xavier series devices can be booted from a USB device with mass storage class and bulk only protocol, such as a flash drive. Hot plugging is not supported; the flash drive must be attached before the device is booted.
The target device must be flashed at least once before the procedure is performed to ensure that the file system is available.
To set up a flash drive for booting
1. Connect the flash drive to the host computer.
2. Check the flash drive’s device name (e.g. /dev/sdb):
$ sudo lshw -quiet -short -c disk
3. Create a new GPT:
$ sudo parted /dev/<sdx> mklabel gpt
Where <sdx> is the device name your host computer assigned to the flash drive.
For example, if the host computer assigns the flash drive device name sdb, the command is:
Applies to: Jetson Xavier NX module and Jetson Nano development module only
This section describes procedures for flashing and utilizing an SD card for a Jetson Xavier NX module (P3668-0000) or a Jetson Nano development module (P3448-0000). These modules are used only as component of Jetson developer kits.
Prerequisites
• Download Etcher for Linux. Etcher is the tool you will use to copy an image to an SD card. It is available at:
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 also perform this operation with the Linux dd command. If you use this method, you need not download Etcher.
To generate an image to be flashed to an SD card
Applies to: Jetson Xavier NX and Jetson Nano only
1. If you have not already done so, expand the archive linux_for_tegra.tbz2.
• <blob_name> is a filename; the script saves the raw image with this name.
• <board> specifies the type of Jetson device the SD card is to be flashed for. The value of <board> may be jetson-nano or jetson-xavier-nx-devkit.
• <revision> is the revision number of the Jetson module to be used:
• 100 for Jetson Nano revision A01
• 200 for Jetson Nano revision A02
• 300 for Jetson Nano revision B00 or B01
• Nothing for Jetson Xavier NX (do not use this switch)
This command generates a raw image with partitions for a Jetson Xavier NX development module per the SPI‑SD profile, or for a Jetson Nano development module per the Min-SPI profile.
For example, to create a raw image file named sd-blob.img for use on a Jetson Nano development module revision A01:
To resize the root partition to fill 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 having to move 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 filesystem on the root partition to fit the expected partition table and root partition size
Flashing a Specific Partition
You can flash a specific partition instead of flashing the whole device by using the command line switch ‑k.
• <partition_name> is the name of the partition to be flashed. Possible values depend on the target device. For details, see the section Default Partition Overview in the Bootloader topic.
• <image_name> is the name of the image file. If omitted, flash.sh chooses the image file that was used to flash whole device.
Since U‑Boot is required for Jetson Nano and Jetson TX1, and is the default bootloader for Jetson TX2, the image flashed to the kernel partition is actually a U‑Boot image. U‑Boot loads the Linux kernel from /boot/Image in the root file system.
For this reason, you cannot update Linux kernel image using the ‑k kernel switch. You may update /boot/Image by either of these means:
• Modify /boot/extlinux/extlinux.conf to add a new boot entry.
Follow the instructions and example provided in /boot/extlinux/extlinux.conf. By this means you can always use cp or scp to replace /boot/Image with a custom-built kernel and launch it with U‑Boot.
• On T210 (Nano and TX1) devices only, connect the Jetson device’s recovery USB port to your host. Enter this command at the U‑Boot command prompt:
$ ums 0 mmc 1
This connects eMMC (or the Jetson Nano SD Card) to the host as a set of USB mass storage devices (each partition as a device). You then can copy your custom kernel to /boot/Image directly.
Flashing to Multiple Jetson Devices
NVIDIA provides a tool and instructions for flashing Jetson devices efficiently in a factory environment. This tool is part of the Linux BSP package and is available in the Linux_for_Tegra folder. Instructions for using the tool are included in README_Massflash.txt, located in the same folder.
Increasing Internal Memory Partition for Root File System
The suggested rootfs partition size for Jetson AGX Xavier is 15 gigabytes (GB). It is specified by default in the <target_board>.conf file used by the flash.sh script.
Use the -S <size-in-bytes> argument to flash.sh to change the partition size.
To flash for a larger partition
• Execute the following command:
$ sudo ./flash.sh -S <size> <bo;ard> <rootdev>
Where:
• <size> is the desired size for the partition, such as 8589934592 (or 8 GiB) for 8 GB, if you want to decrease the size of the partition.
• <rootdev> is the rootfs partition internal memory, for example mmcblk0p1.
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.
To determine the success of a driver update
• Execute the following command on a booted target device:
$ sha1sum –c /etc/nv_tegra_release
If the driver update succeeded, the output displays the word 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:
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.
The oem-config tool 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.
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.
To re-enable oem-config manually 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:
5. Mount backup.img.raw (an ext4 image file) on the host at a mount point of your choice.
6. Apply any Jetson-specific binaries to the image file. The nv-oem-config setup files are included in the apply_binaries script. 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:
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:
11. Power off the source device and remove the SD card from it, then insert it into in the host system.
12. Mount partition #1 of the SD card (an ext4 filesystem) on the host, using a mount point of your choice.
13. Apply any Jetson-specific binaries to partition #1 of SD card. The appropriate files are listed in nv-oem-config, and are applied by the apply_binaries script. Enter these commands to run the script:
$ cd Linux_for_Tegra
$ sudo ./apply_binaries.sh -r <root>
Where <root> represents the partition #1 of SD card mount point.
14. Set nv-oem-config.target as the default.target:
The serial application on the host computer customarily communicates with oem-config through the host computer’s tty device and the target device USB port that is used for flashing. (See Assumptions in the Quick Start Guide topic.)
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.
Jetson Nano supports use of the micro USB connector as a debugging port. This is the easiest way to control a headless Jetson Nano device, since a USB to TTL adapter is not required.
To configure oem-config to use a 40‑pin header UART port
1. Locate the appropriate configuration file on the host computer:
• For Jetson Nano and Jetson TX1: <top>/etc/nv-oem-config.conf.t210
• For Jetson Xavier series devices: <top>/etc/nv-oem-config.conf.t194
• For Jetson TX2 series devices: <top>/etc/nv-oem-config.conf.t186
2. Open the configuration file and file the line that defines the property:
nv-oem-config-uart-port=ttyGS0
3. Change the value of this property from ttyS0 to ttyTHS1.
4. Save and close the configuration file.
5. 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 serial application on the host computer. You may use putty, screen, or any other serial application 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.
To reconfigure the target device with oem-config
1. oem-config displays a welcome screen. To advance to the next screen, press Tab, then Enter.
2. oem-config displays the license that governs its use. Read the license, then accept it by pressing Tab, then Enter.
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.
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.
4. 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.
5. oem-config displays a screen that lists keyboard layouts. Select your keyboard’s layout, then select “OK” and press Enter.
6. 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.
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.
7. 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; therefore, NVIDIA recommends that you select “Yes” and press Enter. If you are using another operating system that expects the system clock to set to local time, however, select “No.”
8. oem-config asks you to specify your name. Enter your full name (e.g. John Smith), then select “OK” and press Enter.
9. oem-config asks you to specify a username for your user account. oem-config creates a user account for this name. then select “OK” and press Enter.
NVIDIA suggests using your first name, using lower case letters only. Use this account instead of the root account for non-administrative activities.
10. oem-config asks you to specify a password for your user account. Enter a password, then select “OK” and press Enter.
NVIDIA recommends that you specify a strong password, i.e. one that is more than eight characters long and contains at least one each of upper and lower case letters, numerals, and punctuation characters. If you enter a weak password, oem-config will ask you to confirm that you want to use it.
11. 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 specify a password again.
12. 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).
Note
Note: This is only the case of “Flashing to an SD card.” For the other case, which uses flash.sh, you can of course enlarge the APP partition statically with flash option ‑S.
13. 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 the Ethernet cable is connected. Then select the eth0: Ethernet option, select “OK,” and press Enter.
Note
Note: NVIDIA does not recommend choosing the wireless network interface at this time. Use Ubuntu NetworkManager utility to configure the wireless network after oem-config is run. For more details see the ubuntu.com documentation page Configure WiFi Connections.
14. oem-config prompts you to enter your host computer’s hostname. If you don’t know the host’s name, ask your network administrator. If you are setting up a dedicated network, you may choose any name. Enter the hostname, then select “OK,” and press Enter.
15. oem-config reconfigures the system with the selections you have made, then proceeds to the system’s log-in prompt.
