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. This chapter describes:

Manually Generate a Root File System

NVIDIA provides a tool to generate a root file system. To use the tool, navigate to the tools/samplefs directory in the extracted NVIDIA driver package:

$ cd <your_L4T_root>/Linux_for_Tegra/tools/samplefs

Note

The tool 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. Depending on the Internet speed of your host machine, it might take several hours to run.

Desktop Flavor Root File System

The desktop root file system is the same as the NVIDIA prebuilt sample root file system, which includes the Ubuntu desktop and an OEM configuration.

Execute the nv_build_samplefs.sh script with the parameters to generate the desktop root file system:

$ sudo ./nv_build_samplefs.sh --abi aarch64 --distro ubuntu --flavor desktop --version focal

Minimal Flavor Root File System

The minimal root file system is the basic root file system that is used for NVIDIA Jetson develop kits. This file system does not provide the GUI mode, and all manipulations can be completed only by using the SSH or UART console. The file system does not also provide an OEM configuration, so we recommend that you create a default user before you flash the device. Refer to l4t_create_default_user.sh in Skipping oem-config for more information.

Execute the nv_build_samplefs.sh script with the parameters to generate the minimal root file system:

$ sudo ./nv_build_samplefs.sh --abi aarch64 --distro ubuntu --flavor minimal --version focal

Execute the Script on a Non-Ubuntu 20.04 Host

The script can only be executed on an Ubuntu 20.04 host. If your host is not running Ubuntu 20.04, NVIDIA allows you to use a Docker container to run the script:

$ sudo apt-get install docker.io
$ sudo docker run --privileged -it --rm -v <your_L4T_root>/Linux_for_Tegra:/l4t ubuntu:20.04

(inside of container) $ apt-get update
(inside of container) $ apt-get install -y qemu-user-static wget sudo
(inside of container) $ cd /l4t/tools/samplefs

Execute the script to generate the desktop/minimal root file system in the container.

Using the Script

For more information about the parameters, enter the script name without sudo. The command is used exactly as shown, but you need not understand the parameters to use it.

Root File System Redundancy

NVIDIA® Jetson™ Linux provides support for root file system redundancy (“rootfs redundancy”) on NVIDIA® Jetson AGX Orin™ series, NVIDIA® Jetson AGX Xavier™ series and NVIDIA® Jetson Xavier™ NX 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.

../../_images/RootfsRedundancy.svg

Rootfs redundancy supports independent creation and updates of the two file systems, switching, and fail-over.

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 cannot be changed.

Rootfs Selection

Jetson Linux provides an option to link rootfs A/B with Bootloader A/B. If rootfs A/B is enabled, rootfs A/B is linked to Bootloader A/B by default.

Note

User can choose the option in UEFI menu. The choices are:

  • Link with firmware(default)

  • A partition(APP)

  • B partition(APP_b)

Rootfs A/B is NOT linked with Bootloader A/B

When rootfs A/B is not linked with Bootloader A/B, Bootloader A/B and rootfs A/B slot selection are independent of each other. There are four possible combinations of Bootloader and rootfs:

../../_images/RootfsNotLinkWithFw.svg

Each rootfs has several attributes:

Each rootfs occupies a slot in the redundant file system architecture: “slot A” or “slot B”.

../../_images/RootfsAbSlots.svg

The kernel and kernel-dtb partitions belong to the userspace. When rootfs redundancy is in use, they belong to the rootfs slots and are selected by their rootfs slots.

The active rootfs slot is the slot from which the next boot operation will attempt to boot. The active rootfs slot (the rootfs slot that Linux uses), is not necessarily the Bootloader active slot (the Bootloader slot where 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 might exchange the roles of the current and unused rootfs slots during an update or when the current rootfs repeatedly fails 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 Status attribute of current rootfs slot is necessarily bootable. The unused rootfs slot might have an older, identical, or newer version of the system and might (or might not) be bootable. The Status attribute is managed by cpu-bootloader and the Update Engine (UE), which updates 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, cpu-bootloader marks 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 cpu-bootloader tries to boot the rootfs three times. The number of tries is configurable. Refer to To customize the rootfs redundancy configurations.

Note

Rootfs update is not supported in current release.

Rootfs A/B is linked with Bootloader A/B

When rootfs A/B is linked with Bootloader A/B, the Bootloader slot and rootfs slot are configured together. This way, by default, Bootloader A boots with rootfs A, and Bootloader B boots with rootfs B. There are two combinations of Bootloader and rootfs:

../../_images/RootfsLinkWithFw.svg

How to Create Redundant Root File Systems

To create and flash the target board with rootfs redundancy, Jetson-Linux provides a flash command. You can complete some customizations before the flashing.

Before you create the file systems, compare the layout file for your Jetson device with the corresponding layout file for a non-redundant system. Understanding the differences between the files helps you understand how file system redundancy works.

A layout file is an XML file that describes the partition layout for a Jetson-Linux system. The files describe the partition layout for each Jetson platform, and here is a list of the layout files for redundant file systems on various platforms:

  • For Jetson AGX Orin series:

    Linux_for_tegra/bootloader/t186ref/cfg/flash_t234_qspi_sdmmc_rootfs_ab.xml
    
  • For Jetson Xavier NX with SD memory:

    Linux_for_tegra/bootloader/t186ref/cfg/flash_l4t_t194_spi_sd_p3668_rootfs_ab.xml
    
  • For Jetson Xavier NX 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
    

Note

The corresponding non-redundant layout file has the same name without the filename suffix _rootfs_ab.

To flash the target board with redundant root file systems

Go to the directory Linux_for_Tegra and run the following 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 AGX Orin series: jetson-agx-orin-devkit

    • For Jetson Xavier NX: jetson-xavier-nx-devkit-emmc or jetson-xavier-nx-devkit

    • For Jetson AGX Xavier series: jetson-agx-xavier-devkit

  • <rootdev> specifies the location of the root file systems. For example:

    $ sudo ROOTFS_AB=1 ./flash.sh jetson-agx-orin-devkit mmcblk0p1
    

To flash redundant root file systems on an external storage device, refer to the Workflow #4 in Linux_for_Tegra/tools/kernel_flash/README_initrd_flash.txt.

To customize the rootfs size

When rootfs redundancy is being used, the size of each rootfs partition (APP and APP_b) is half of what the rootfs will be if rootfs redundancy is not being used. 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 AGX Orin series: Linux_for_Tegra/p3701.conf.common

  • For Jetson Xavier NX series: Linux_for_Tegra/p3668.conf.common

  • For Jetson AGX Xavier series: Linux_for_Tegra/p2972-0000.conf.common

For example, to change the rootfs size for a Jetson AGX Orin, edit p3701.conf.common:

if [ "${ROOTFS_AB}" == 1 ]; then
    rootfs_ab=1;
    val=$(echo ${ROOTFSSIZE} | sed 's/GiB//g');
    val=`expr ${val} / 2`;
    ROOTFSSIZE="${val}GiB";
    OVERLAY_DTB_ROOTFSABINFO_FILE="L4TRootfsABInfo.dtbo";
fi;

To customize the rootfs redundancy configurations

Note

Customization is not supported in current release.

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, refer to Update And Redundancy.

The following shell command runs the nvbootctrl tool:

$ 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> details refer to Update And Redundancy.

To dump root file systems slot A and slot B information

Run the following command:

$ sudo nvbootctrl -t rootfs dump-slots-info

To switch between root file systems slot A and slot B

Run the following command:

$ sudo nvbootctrl -t rootfs set-active-boot-slot <slot>

Where <slot> is the active slot after the device is next rebooted.

Fail-over Rootfs Slot Switching

If a Jetson device with rootfs redundancy fails to boot the specified number of consecutive times, it fails over to the unused rootfs slot. The default value is three times. The device makes the unused rootfs slot the active rootfs slot and vice versa and tries to boot again. If both rootfs slots are unbootable, the device boots into the recovery kernel image.

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 Redundant Root File Systems.

Over-the-Air Update with Rootfs Redundancy Enabled

Note

  • Image-based Over-the-Air (OTA) update is not supported with Rootfs Redundancy Enabled .

  • Performing an OTA update with a Debian package is not recommended for systems that use rootfs redundancy. This is because Debian packages only update files in the current rootfs slot. The system does not switch the active rootfs slot after rebooting.