Setting Up Your File System

NVIDIA® Jetson™ Linux requires a root file system. You must create a Linux host system and copy it to your reference board.

Sample Root File System

NVIDIA Jetson Linux Driver Package (L4T) comes with a pre-built sample root file system created for the NVIDIA Jetson developer kits.
NVIDIA provides a tool to generate a root file system. To use the tool, go to Navigate to the tools/samplefs directory of the extracted NVIDIA driver package:
$ cd <your_L4T_root>/Linux_for_Tegra/tools/samplefs
Execute the script nv_build_samplefs.sh:
$ sudo ./nv_build_samplefs.sh --abi aarch64 --distro ubuntu --version bionic
To see an explanation of the parameters, enter the script name alone. (You need not use sudo.) Because the command is used exactly as shown, though, you need not understand the parameters to use it.
Note:
This script downloads the base image, extracts the root file system, downloads and installs all required packages, and compresses the root file system directory to a tarball. It may take several hours to run. depending on the Internet speed of your host machine.

Setting Up the Root File System

Before booting the target board, configure the root file system (rootfs) to:
Set up the rootfs
Copy it to the rootfs on the device

Step 1: Set Up the Root File System

This procedure uses the sample file system provided by NVIDIA as the base. If you wish to use your own file system, set the LDK_ROOTFS_DIR environment variable to point to the location of your rootfs and skip the steps for setting the root file system.
To set up the rootfs
1. Download the following file to your home directory:
Tegra-Linux-Sample-Root-Filesystem_<release_type>.tbz2
This file contains the NVIDIA-provided sample root file system.
2. Extract the compressed file as follows:
Navigate to the rootfs directory of the extracted NVIDIA driver package.
$ cd <your_L4T_root>/Linux_for_Tegra/rootfs
Where <your_L4T_root> is your L4T root directory, which is assumed to be your home directory (~).
Extract the sample file system to the rootfs directory.
$ sudo tar -jxpf ../../Tegra-Linux-Sample-Root-Filesystem_<release_type>.tbz2
3. Run the apply_binaries.sh script to copy the NVIDIA user space libraries into the target file system.
$ cd ..
$ sudo ./apply_binaries.sh
4. If you are using a different rootfs, or if you have already configured your rootfs, apply the NVIDIA user space libraries by setting the LDK_ROOTFS_DIR environment variable to point to your rootfs. Then run the script, as shown above, to copy the binaries into your target file system.
If the apply_binaries.sh script installs the binaries correctly, the last message output from the script is “Success!”.
You have now completed setting up the root file system. Proceed to flash the rootfs onto the target SoC device.

Step 2: Copy the rootfs to the Jetson Device

The procedure you must use to copy the rootfs depends on the type of storage you want to hold it
To use the flashing tool to set up a root file system on the device, see the topic Flashing and Booting the Target Device.
If you prefer to set up a root file system yourself rather than use the flashing tool, use the following procedure.
To copy the file system to an external storage device
1. Plug your rootfs device into the host system.
2. If your device is not formatted as Ext4, enter the following command to format it with an Ext4 file system:
$ sudo mkfs.ext4 /dev/sd<port><device_number>
Where:
<port> is the port to which your device is mounted.
<device_number> is the device number of the device attached to the port. You can use the dmesg command to determine the port.
3. If needed, mount your device with the following command:
$ sudo mount /dev/sdX1 <mntpoint>
Where <mntpoint> is the mount point on the host system for your rootfs device.
4. Copy the file system. If LDK_ROOTFS_DIR is set, execute these commands:
$ cd ${LDK_ROOTFS_DIR}
$ sudo cp –a * <mntpoint> && sync
5. If it is not set, copy the rootfs directory that is included in the release by executing the following commands:
$ cd <your_L4T_root>/Linux_for_Tegra/rootfs
$ sudo cp –a * <mntpoint> && sync
6. After copying the content to the external disk or device, unmount the disk and connect it to the target SoC device.

Root File System Redundancy

NVIDIA® Jetson™ Linux provides full support for root file system redundancy (“rootfs redundancy”) on NVIDIA Jetson Xavier™ NX series, Jetson AGX Xavier™ series, and Jetson TX2 series. It uses two root file systems, one designated rootfs A and stored in the usual file system partition, APP, and the other designated rootfs B and stored in a new partition, APP_b, located after APP on the disk.
Graphical user interface, text, application, chat or text message Description automatically generated
Rootfs redundancy supports independent creation and updates of the two file systems, switching, and failover.
Note:
Rootfs redundancy is an advanced feature, and is intended for customers who have the capability to create customized rootfs images.
The partition names APP and APP_b may not be changed.

Rootfs Selection

L4T provides an option to tie bootloader A/B and rootfs A/B. If rootfs A/B is enabled, bootloader A/B is tied to rootfs A/B by default.
For information about how to enable and disable the option, see To customize the SMD partition image.

Rootfs Selection with Unified Bootloader and Rootfs A/B Disabled

When the option “Unified bootloader A/B and rootfs A/B” is disabled, bootloader A/B and rootfs A/B slot selection are independent of each other. There are four possible combinations of Bootloader and Rootfs:
A picture containing text Description automatically generated
Each rootfs has several attributes:
Each rootfs occupies a slot in the redundant file system architecture: “slot A” or “slot B.”
A picture containing graphical user interface Description automatically generated
When rootfs redundancy is in use, the kernel and kernel-dtb partitions belong to the userspace, not the bootloader. Consequently, they belong to the rootfs slots and are selected by their rootfs slots, not their bootloader slots.
The active rootfs slot is the slot that the next boot operation will attempt to boot from. The active rootfs slot (the slot whose rootfs Linux uses) is not necessarily the bootloader active slot (the slot from whose Bootloader Linux was booted).
The current rootfs slot is the one that the system booted from and is currently using. The other rootfs slot is called the unused rootfs slot. The system may exchange the roles of the current and unused rootfs slots in the course of an update, or when the current rootfs fails repeatedly while booting or immediately after. The current rootfs slot does not relate to the bootloader current slot.
A rootfs slot’s Status attribute indicates whether the rootfs contains a valid system image that can be used to boot the device. When the system is running, the current rootfs slot’s status is necessarily bootable. The unused rootfs slot may have an older, identical, or newer version of the system, and may or may not be bootable. The Status attribute is managed by CBoot and the Update Engine (UE), which manages updating the rootfs partitions .
The Update Mode attribute indicates that the system has attempted to run OTA update on this rootfs. This attribute is also handled by the UE.
If the current rootfs fails to boot a specified number of times, CBoot resets its Status attribute and switches the roles of the current and unused rootfs slots. If both root file systems are unbootable, the device tries to boot from the recovery kernel image.
By default the CBoot tries to boot the rootfs three times. The number of tries is configurable; see To customize the SMD partition image.

Rootfs Selection with Unified Bootloader and Rootfs A/B Enabled

When the option “Unified bootloader A/B and rootfs A/B” is enabled, bootloader A/B and rootfs A/B are configured together. The bootloader slot and the rootfs slot are switched together, so that Bootloader A boots only with rootfs A, and Bootloader B boots only with rootfs B. There are two combinations of bootloader and rootfs:
A picture containing chat or text message Description automatically generated

How to Create Redundant Root File Systems

L4T provides a simple flash command to create and flash the target board with rootfs redundancy. You can do some customizations before the flashing.
Before you create the file systems, find the layout file for your Jetson device and examine them side by side with the corresponding layout file for a non-redundant system. Understanding the differences is important to your understanding of how file system redundancy works.
A layout file is an XML file which describes the partition layout for an L4T system. One or more particular layout files describe the partition layout for each Jetson platform. The following list names the layout files for redundant file systems on various platforms. In each case, the corresponding non-redundant layout file has the same name without the filename suffix _rootfs_ab
For Jetson Xavier NX development module with SD memory:
Linux_for_tegra/bootloader/t186ref/cfg/flash_l4t_t194_spi_sd_p3668_rootfs_ab.xml
For Jetson Xavier NX production modules with eMMC:
Linux_for_Tegra/bootloader/t186ref/cfg/flash_l4t_t194_spi_emmc_p3668_rootfs_ab.xml
For Jetson AGX Xavier series:
Linux_for_Tegra/bootloader/t186ref/cfg/flash_t194_sdmmc_rootfs_ab.xml
For Jetson TX2 series:
Linux_for_Tegra/bootloader/t186ref/cfg/flash_l4t_t186_rootfs_ab.xml
To flash the target board with redundant root file systems
Go to the directory Linux_for_Tegra and enter the command:
$ sudo ROOTFS_AB=1 ./flash.sh [options] <target_board> <rootdev>
Where:
ROOTFS_AB=1 enables rootfs redundancy.
<target_board> indicates the type of device:
For Jetson Xavier NX series: jetson-xavier-nx-devkit-emmc or jetson-xavier-nx-devkit
For Jetson AGX Xavier series: jetson-agx-xavier-devkit
For Jetson TX2 series: jetson-tx2-devkit
<rootdev> specifies the location of the root file systems.
For example:
$ sudo ROOTFS_AB=1 ./flash.sh jetson-tx2-devkit mmcblk0p1
To flash redundant root file systems on an external storage device, see Workflow #5 in Linux_for_Tegra/tools/kernel_flash/README.txt.
To customize the rootfs size
When rootfs redundancy is in use, the size of each rootfs partition (APP and APP_b) is half the size that the rootfs would be if rootfs redundancy were not in use. That size is specified by ROOTFSSIZE in the configuration file for the target board.
You can change the amount of space allocated to the root file systems by changing the value of ROOTFSSIZE before you flash the target.
The configuration file you must change to customize the rootfs size is:
For Jetson Xavier NX series: Linux_for_Tegra/p3668.conf.common
For Jetson AGX Xavier series: Linux_for_Tegra/p2972-0000.conf.common
For Jetson TX2 series: Linux_for_Tegra/P2771-0000.conf.common
For example, to change the rootfs size for a Jetson TX2, edit p2771-0000.conf.common:
if [ "${ROOTFS_AB}" == 1 ]; then
rootfs_ab=1
EMMC_CFG=flash_l4t_t186_rootfs_ab.xml;
ROOTFSSIZE=14GiB;
fi;
To customize the SMD partition image
The SMD partition holds information about the status of a slot. A device with redundant file systems has two partitions, SMD for slot A and SMD_b for slot B. You can customize the SMD partitions before you flash the target.
Note:
Some L4T documents refer to the SMD and SMD_b partitions together as “the SMD partition.” Keep this in mind as you read REAME files and other documents.
Rootfs redundancy requires the SMD partitions to function. The SMD partition image is stored in the file slot_metadata.bin.rootfsAB, which the script nv_smd_generator generates from l4t_smd_info.rootfs_AB.cfg.
The default l4t_smd_info.rootfs_AB.cfg file looks like this:
< VERSION 5 >
 
# Set the maximum rootfs slot retry count
# Please make sure this field is set before slot info config
# The valid setting is 1 to 3
< MAX_ROOTFS_AB_RETRY_COUNT 3 >
 
#
# Config 1: Disable A/B support (by removing comments ##)
#
 
# slot info order is important!
# <priority> <suffix> <retry_count> <boot_successful>
##15 _a 7 1
 
#
# Config 2: Enable rootfs A/B support (default)
#
< REDUNDANCY_ENABLE 1 >
< ROOTFS_AB 1 >
 
# To enable rootfs autosync, use < RF_AUTOSYNC_ENABLE 1 >
# This option must be defined after "< ROOTFS_AB 1 >"
##< RF_AUTOSYNC_ENABLE 1 >
 
# Select rootfs A as the active rootfs slot
< ROOTFS_ACTIVE_A 1 >
##< ROOTFS_ACTIVE_B 1 >
 
# Enable/disable unified bootloader AB and rootfs AB
# Set 1 to enable, set 0 to disable. Default is enabled
# This option must be defined after "< ROOTFS_AB 1 >"
# When < ROOTFS_BL_UNIFIED_AB 1 > is set,
# auto sync for both BL and RF are disabled.
< ROOTFS_BL_UNIFIED_AB 1 >
 
# To disable bootloader autosync, use < BL_AUTOSYNC_DISABLE 1 >, default is disabled.
# REDUNDANCY_ENABLE or REDUNDANCY_USER must be defined before
# BL_AUTOSYNC_DISABLE !
< BL_AUTOSYNC_DISABLE 1 >
 
# slot info order is important!
# <priority> <suffix> <retry_count> <boot_successful>
15 _a 7 1
14 _b 7 1
< MAX_ROOTFS_AB_RETRY_COUNT 3 > (highlighted above) sets the maximum rootfs slot try count. This is the number of times CBoot tries to boot the rootfs before switching the roles of the current and unused rootfs slots. The setting range is 1 to 3; the default is 3.
< ROOTFS_AB 1 > (also highlighted above) enables rootfs redundancy. To disable rootfs redundancy, change this line to < ROOTFS_AB 0 >.
< ROOTFS_ACTIVE_A 1 > (also highlighted) makes rootfs slot A the default active rootfs slot. To make rootfs slot B the default active rootfs slot, change this line to < ROOTFS_ACTIVE_B 1 >.
< ROOTFS_BL_UNIFIED_AB 1 > (also highlighted) enables or disables unified bootloader A/B and rootfs A/B. To disable unified bootloader A/B and rootfs A/B, set this line to < ROOTFS_BL_UNIFIED_AB 0 >. The default setting is 1. When ROOTFS_BL_UNIFIED_AB is set, auto sync for both Bootloader and root file system are disabled.
If rootfs A/B and unified bootloader A/B are both to be enabled, < ROOTFS_ACTIVE_A 1 > must precede < ROOTFS_BL_UNIFIED_AB 1 > in the .cfg file.
< BL_AUTOSYNC_DISABLE 1 > (also highlighted) disables bootloader auto sync. To enable bootloader auto sync, change this line to < BL_AUTOSYNC_DISABLE 0 >. Note that 1 disables bootloader auto sync, and 0 enables it. The default value is 1.
To customize the SMD partitions:
1. Modify l4t_smd_info.rootfs_AB.cfg.
2. Run nv_smd_generator on an X86 host system to generate the new SMD image, slot_metadata.bin.rootfsAB.
C:\...> nv_smd_generator <config_file> <output_file>
Where:
<config_file> is the SMD configuration file.
<output_file> is the name of the output SMD image file.
For example:
C:\...> nv_smd_generator l4t_smd_info.rootfs_AB.cfg slot_metadata.bin.rootfsAB
3. Copy slot_metadata.bin.rootfsAB to the host machine.
4. Flash the SMD partitions to the target device:
For more information about the SMD partitions, see Enabling Rootfs Redundancy in the topic Jetson Xavier NX / AGX Xavier / TX2 Update and Redundancy.

Managing Rootfs Slots with nvbootctrl

The nvbootctrl tool can help you test and develop a pair of redundant file systems. You can use it to display the status of both root file systems or to change the active rootfs slot between slots A and B.
This tool’s default usage, shown below, is for Bootloader. For more information, see Jetson Xavier NX / AGX Xavier / TX2 Update and Redundancy.
The shell command that runs the nvbootctrl tool is:
$ sudo nvbootctrl [ -t <target>] <command>
Where:
<target> is the type of target. It can be either bootloader or rootfs. The default, effective when the -t option is not used, is bootloader.
<command> is one of the commands to the tool shown in this table:
Command
Description
get-number-slots
Prints the number of slots.
get-current-slot
Prints the index of the currently running slot.
mark-boot-successful
Marks the current slot as Good.
set-active-boot-slot <slot>
Causes next boot to load and execute the specified slot.
set-slot-as-unbootable <slot>
Marks <slot> as invalid.
is-slot-bootable <slot>
Returns 0 if <slot> is bootable, or a non-zero value otherwise.
is-slot-marked-successful <slot>
Returns 0 only if <slot> is marked Good, or a non-zero value otherwise.
get-suffix <slot>
Prints the suffix of <slot>.
dump-slots-info
Prints information about slots.
is-autosync-enabled
Prints the status of autosync (enabled or disabled). For Bootloader only.
toggle-autosync
Toggles the enablement status of autosync. For Bootloader only.
is-unified-enabled
Returns:
0 if both unified A/B and unified A/B are enabled
69 if both unified A/B and rootfs A/B are disabled
70 if rootfs A/B is enabled and unified A/B is disabled
(The fourth combination, rootfs A/B disabled and unified A/B enabled, is not possible.)
<slot> is a zero-based slot number: 0 for slot A, or 1 for slot B.
 
Note:
When “Unified bootloader A/B and rootfs A/B” is enabled, the command sudo nvbootctrl ‑t rootfs <command> is not supported, and nvbootctrl prints the warning message “sudo nvbootctrl <command> indicates both bootloader and rootfs information.”
To dump root file systems slot A and slot B information
Enter the command:
$ sudo nvbootctrl -t rootfs dump-slots-info
To switch between root file systems slot A and slot B
Enter the command:
$ sudo nvbootctrl -t rootfs set-active-boot-slot <slot>
Where <slot> is the active slot after the device is next rebooted.
Failover Rootfs Slot Switching
If a Jetson device with rootfs redundancy fails to boot the specified number of consecutive times (see To customize the SMD partition image), it fails over to the unused rootfs slot. That is, it makes the unused rootfs slot the active rootfs slot and vice versa, then tries to boot again.
If both rootfs slots are unbootable, the device boots into the recovery kernel image.
The background service l4t-rootfs-validation-config.service checks whether the root file system boot was successful. This service calls a customer-provided script /usr/sbin/user_rootfs_validation.sh to validate the rootfs according to user-defined criteria. By default, this script is not defined.
Note:
If user_rootfs_validation.sh returns a non-zero exit code, the service tries to reboot the device. If returns 0 or is not defined, the service does nothing more, but starts the nv_update_verifier service to validate the A/B update on the bootloader and the rootfs.

Using UUID for Root File System Partitions APP and APP_b

Always use a partition UUID, rather than a device name, to identify the APP and APP_b partitions when rootfs redundancy is enabled. The form of a UUID reference to a partition is <xxxx>(UUID), where <xxxx> is the partition’s UUID.
After you flash the Jetson device with the two root file systems, the UUID used for the APP partition is stored in bootloader/l4t-rootfs-uuid.txt, and the UUID used for the APP_b partition is stored in bootloader/l4t-rootfs-uuid.txt_b. You may specify your own UUID by writing the UUID to these files before executing the flash command as shown in How to Create and Flash Root File Systems A and B.

Over-the-Air Update with Rootfs Redundancy Enabled

Jetson Linux supports image-based Over-the-Air (OTA) update with rootfs redundancy enabled. For more information about the update process, see Updating Jetson Linux with Image-Based Over-the-Air Update in the topic Over-the-Air Update.
When the option “Unified bootloader A/B and rootfs A/B” is enabled, the Jetpack Debian package over-the-air update is disabled.
Performing an OTA update with a Debian package is not recommended for systems that use rootfs redundance, although it is possible when the option “Unified bootloader A/B and rootfs A/B” is disabled. This is because Debian packages only update files in the current rootfs slot. The system does not switch the active rootfs slot after rebooting.