Software Packages and the Update Mechanism
NVIDIA provides additional NVIDIA® Jetson™ Linux software components and updates in APT
(Debian) repositories, accessible through the apt
utility.
Note
These packages are only verified with the root filesystem shipped in this L4T BSP release.
Installing Additional Packages
NVIDIA maintains the following APT repositories:
For NVIDIA® Jetson AGX Xavier™ series
For NVIDIA® Jetson Xavier™ NX series
For NVIDIA® Jetson AGX Orin™
For NVIDIA® Jetson Orin™ NX and NVIDIA® Jetson Orin™ Nano
The package nvidia-l4t-apt-source
is preinstalled in the Jetson Linux root
file system. It identifies the platform it is running on and adds the
appropriate repositories to the software source list.
The packages in the APT repositories are signed with GPG keys. The
corresponding public key is preinstalled in the Jetson Linux root file system.
Once the repositories are added to the source list, apt
can download and
install packages.
Note
The APT repositories described here are also used to upgrade existing packages and install packages that NVIDIA adds to the set initially installed with Jetson Linux. For more information, see Updating a Jetson Device.
Repackaging Debian Packages
You can use the script nvdebrepack.sh
to repackage the existing Jetson Linux
Debian packages. The script can be found in the directory Linux_for_Tegra/tools/Debian/
. See
Linux_for_Tegra/tools/Debian/nvdebrepack.txt
for usage and examples.
Building Kernel Debian Packages Yourself
You can customize the Jetson Linux kernel by getting the kernel source packages, making your changes, and building the Debian packages.
This section describes the package dependencies and scripts that NVIDIA uses to build the kernel packages. You may use it as a reference to create your own Debian packages.
Working with the Packages
The kernel packages are all open source. Three of the four kernel
packages are in public_sources.tbz2
. You can download the archive from
the NVIDIA Developer Center.
This archive contains another archive named kernel_src.tbz2
, which in
turn contains three directories of header files:
nvidia-l4t-kernel/
nvidia-l4t-kernel-dtbs/
nvidia-l4t-kernel-headers/
The debian.org Guide for Debian Maintainers gives guidelines for modifying the open source files and creating new Debian packages from them.
The fourth kernel package, nvidia-l4t-jetson-io
, is discussed in
nvidia-l4t-jetson-io, below.
Package Dependencies
Most Jetson Linux Debian packages pre-depend on nvidia-l4t-core
. This package
prevents package installation on an incompatible Jetson platform, e.g.,
installing a Jetson software package on a non-Jetson device. nvidia-l4t-core
does not perform the installation if it detects an incompatible
platform.
nvidia-l4t-core
also prevents a partial upgrade, in which one Jetson Linux package upgrades to a new major release, but other Jetson Linux packages that depend on it are not upgraded as well. Partial upgrades can cause compatibility issues between firmware, programs, and libraries that have been upgraded and ones that have not.
nvidia-l4t-kernel
nvidia-l4t-kernel
contains files for the Jetson Linux kernel itself.
Prerequisites and Dependencies
Here are the prerequisites for this package:
nvidia-l4t-core
(must match this package’s major release)
Here are the dependencies for this package:
nvidia-l4t-tools
nvidia-l4t-init
Package Scripts
This package has a post-installation script which you can get by
extracting the .deb
file. It performs these actions:
Executes
depmod -a
.Creates a dpkg trigger file named
/usr/lib/linux/triggers/<release>
. The trigger invokes actions defined in/etc/kernel/postinst.d
to updateinitramfs/grub configs/…
when the kernel is updated. This conforms to the standard Ubuntu kernel update procedure.
nvidia-l4t-kernel-dtbs
nvidia-l4t-kernel-dtbs
contains files for Jetson Linux’s device tree blobs (DTBs).
The package installs all of the .dtb
files in /boot/
. When you flash a
board, it installs the .dtb
file used by that board in /boot/dtb/
by
checking the board specification against the DTBs’ compatibility information.
Prerequisites and Dependencies
Here are the prerequisites for this package:
nvidia-l4t-core
(must match the major release for this package)
Here are the dependencies for this package:
device-tree-compiler
nvidia-l4t-kernel
Package Scripts
This package has a post-installation script, which you can get by
extracting the .deb
file.
The post-installation script performs these actions:
Decompiles the
.dtb
file used by the board in/boot/dtb/
and gets thebootargs
property in the/chosen
node.Decompiles the corresponding
.dtb
file in/boot/
and substitutes thebootargs
property from step 1 in the resulting.dts
file.Recompiles the
.dts
file to a.dtb
file and puts it in/boot/dtb/
.
nvidia-l4t-kernel-headers
nvidia-l4t-kernel-headers
contains Jetson Linux kernel header files.
Prerequisites and Dependencies
Here are the prerequisites for this package:
nvidia-l4t-core
(must match this package’s major release)
Here are the dependencies for this package:
nvidia-l4t-kernel
libc6
libssl1.1
Package Scripts
This package has no package scripts.
nvidia-l4t-jetson-io
nvidia-l4t-jetson-io
contains Python scripts concerned with Jetson I/O functions.
Prerequisites and Dependencies
Here are the prerequisites for this package:
nvidia-l4t-core
(must match this package’s major release)
Here are the dependencies for this package:
mount
python3
util-linux
nvidia-l4t-kernel
device-tree-compiler
You can also get the dependencies by extracting the Debian file.
Package Scripts
This package has no package scripts.
Over-the-Air Update
Over-the-Air (OTA) Update enables you to update NVIDIA Jetson devices and host computers for Jetson development.
Jetson Linux supports two forms of OTA, which are used for different purposes. Debian package management-based OTA can update Jetson devices running Jetson Linux or Jetson components on a host computer. Image-based OTA lets you create OTA payload packages, and can update the full image running on a Jetson device, partition by partition. The following sections describe both forms of OTA.
Updating from the NVIDIA APT Server
The first form of OTA update uses Debian packages obtained from an NVIDIA APT server. You can use this form of OTA update to update a Jetson device running Jetson Linux or to update NVIDIA JetPack™ components installed on a host computer running Ubuntu. The APT server maintains respective groups of Debian packages for each purpose.
This section describes the tools and packages that provide basic support for Jetson Linux.
Note
You cannot use OTA update to update a Jetson device on which JetPack is installed.
To update JetPack and Jetson Linux components to a new JetPack release on a system where both are installed, see the instructions in the JetPack documentation.
NVIDIA does not recommend installing OTA Debian packages on a Jetson Linux release earlier than release 32.3.1, or on a system that is based on Ubuntu without the customization of Jetson Linux.
Upgrading from release 32.x to release 35.x is not supported. Only release 34.x is supported right now. Please check the /etc/nv_tegra_release on your Jetson for the current software version.
Updating a Jetson Device
Use the appropriate procedure below to update your system:
To update to a new point release of the same minor release, for example, from release 35.1.0 to 35.1.1
To update to new minor release; for example, from release 35.0.0 to 35.1.0
Updating to a New Point Release
Enter the command:
$ sudo apt update
apt
reads a list of packages from the remote APT repository and identifies new and upgradable packages.Enter the command:
$ apt list --upgradable
apt
displays a list of new and upgradable packages.To install the basic packages for Jetson Linux, enter the command:
$ sudo apt upgrade
Reboot your Jetson device when the upgrade is finished.
Updating to a New Minor Release
Open the
apt
source configuration file in a text editor, for example:$ sudo vi /etc/apt/sources.list.d/nvidia-l4t-apt-source.list
Change the repository name and download URL in the
deb
commands.The original commands are:
deb https://repo.download.nvidia.com/jetson/common <release> main deb https://repo.download.nvidia.com/jetson/<platform> <release> main
Where:
<release> is the release number of the minor release to which you want to update. For example, to update to minor release 35.1, replace <release> with
r35.1
. OTA updates to the latest point release of the specified minor release.<platform>
identifies the platform’s processor:t234
for NVIDIA® Jetson Orin seriest194
for NVIDIA® Jetson Xavier series
For example, if the current release is release 35.1, and your platform is Jetson AGX Orin series, the commands are:
deb https://repo.download.nvidia.com/jetson/common r35.1 main deb https://repo.download.nvidia.com/jetson/t234 r35.1 main
Save and close the source configuration file.
Enter the commands:
$ sudo apt update $ sudo apt dist-upgrade
If
apt
prompts you to choose an option to fix local modified configuration file, reply Y for yes (to use the NVIDIA updated version of the file).If you’re upgrading from release 34, please install the following new packages manually:
$ sudo apt install nvidia-l4t-openwfd nvidia-l4t-vulkan-sc-dev nvidia-l4t-vulkan-sc-samples nvidia-l4t-vulkan-sc-sdk nvidia-l4t-vulkan-sc nvidia-l4t-jetsonpower-gui-tools
When the upgrade is finished, reboot the Jetson device.
Note
The
do-release-upgrade
command is disabled because Jetson Linux does not officially support Ubuntu release 22.04 at this time.
Updating a Host
NVIDIA provides a group of Debian packages that add or update Jetson Linux support components on the host computer.
Preparing the Host Computer to Install Jetson Linux Support Components
Enter this command to install the public key of the x86_64 repository of the public APT server:
$ sudo apt-key adv --fetch-key https://repo.download.nvidia.com/jetson/jetson-ota-public.asc
Add the following x86_64 repository to the host system’s source list.
For an Ubuntu 18.04 host:
deb http://repo.download.nvidia.com/jetson/x86_64/bionic <relno> main
For an Ubuntu 20.04 host:
deb http://repo.download.nvidia.com/jetson/x86_64/focal <relno> main
Where
<relno>
is the current release’s full release number as specified in the Release Notes.Enter the command:
$ sudo apt update
Use
apt
to download and install the required packages.For an Ubuntu 18.04 host:
$ sudo apt-get install cuda-cross-aarch64-11-4 cuda-toolkit-11-4 \ cuda-cupti-cross-aarch64-11-7 cuda-sanitizer-11-7 \ libnvvpi2 python3.8-vpi2 vpi2-demos vpi2-cross-aarch64-l4t \ vpi2-dev vpi2-samples nsight-systems-2022.3.3 nvsci \ nsight-compute-2022.2.1 nsight-compute-addon-l4t-2022.2.1 \ nsight-graphics-for-embeddedlinux-2022.3.0.0
For an Ubuntu 20.04 host:
$ sudo apt-get install cuda-cross-aarch64-11-4 cuda-toolkit-11-4 \ cuda-cupti-cross-aarch64-11-7 cuda-sanitizer-11-7 \ libnvvpi2 python3.8-vpi2 python3.9-vpi2 vpi2-demos \ vpi2-dev vpi2-samples vpi2-cross-aarch64-l4t \ nsight-compute-2022.2.1 nsight-compute-addon-l4t-2022.2.1 \ nsight-graphics-for-embeddedlinux-2022.3.0.0 \ nsight-systems-2022.3.3 nvsci
Debian Packages on the NVIDIA APT Server
This section lists the Debian packages maintained on the NVIDIA APT server for a Jetson device or a host.
Update Packages for Jetson Devices
Here is a list of the OTA update packages for BSP on Jetson devices as of Jetson Linux release 35.1.
Refer to List of JetPack OTA Packages in JetPack SDK for a list of other OTA packages and instructions to apply the packages.
Note
The component group for the following table is BSP.
Package
Purpose of the Package
jetson-gpio-common
Jetson GPIO library (common files).
The source files are in https://github.com/NVIDIA/jetson-gpio.
nvidia-l4t-3d-core
NVIDIA graphics libraries including GL and EGL.
nvidia-l4t-apt-source
The Jetson APT source list.
nvidia-l4t-bootloader
The Tegra bootloader update payload.
nvidia-l4t-camera
Tegra camera libraries and utilities.
nvidia-l4t-configs
Jetson Linux system configuration files.
nvidia-l4t-core
Jetson Linux core system libraries including RM, DLA, PVA, and so on.
nvidia-l4t-cuda
CUDA lower lever driver, cuDLA user space library, and CUDA forward compatibility layer.
nvidia-l4t-display-kernel
Display kernel modules including modeset and DRM drivers for Orin and later chips.
The source files are in https://nv-tegra.nvidia.com/r/tegra/kernel-src/nv-kernel-display-driver.git.
nvidia-l4t-firmware
Firmware for Tegra SoC and a few WiFi chips that are used by Jetson.
nvidia-l4t-gbm
Tegra GBM backend and EGL platform GBM implementation.
nvidia-l4t-graphics-demos
Graphics demonstration sources and binaries.
nvidia-l4t-gstreamer
Gstreamer applications and plugins for Jetson Linux.
nvidia-l4t-init
Jetson Linux system init files and systemd services.
nvidia-l4t-initrd
Jetson Linux init RAM disk package.
nvidia-l4t-jetson-io
Jetson-io tool to reconfigure the 40-pin expansion header on Jetson platforms.
Refer to Running Jetson-IO in Configuring the Jetson Expansion Headers for more information.
nvidia-l4t-jetson-multimedia-api
The Multimedia API is a collection of lower-level APIs that support flexible application development by providing better control over the underlying hardware blocks.
nvidia-l4t-jetsonpower-gui-tools
The GUI Tool that is used to configure power on Jetson.
nvidia-l4t-kernel
The Jetson Linux kernel image and modules.
The source files are in http://nv-tegra.nvidia.com/.
nvidia-l4t-kernel-dtbs
The Jetson Linux kernel dtb files.
The source files are in http://nv-tegra.nvidia.com/.
nvidia-l4t-kernel-headers
The Jetson Linux kernel headers for local development.
The source files are in http://nv-tegra.nvidia.com/.
nvidia-l4t-libvulkan
The Tegra Vulkan loader library.
nvidia-l4t-multimedia
The Jetson Linux multimedia libraries.
nvidia-l4t-multimedia-utils
The Jetson Linux multimedia utility libraries.
nvidia-l4t-nvfancontrol
The Fan control service and utility for Jetson.
nvidia-l4t-nvpmodel
The nvpmodel tool is used to manage power profiles and adjusts the maximum clock frequencies for the CPU, GPU, memory controller, and miscellaneous SoC clocks with the number of CPU clusters online.
nvidia-l4t-nvpmodel-gui-tools
The GUI version of the nvpmodel tool.
nvidia-l4t-nvsci
NvSci is a set of communication interface libraries out of which CUDA interops with
NvSciBuf
andNvSciSync
.nvidia-l4t-oem-config
The Jetson Linux OEM configuration utility.
nvidia-l4t-openwfd
The Tegra Open Source WiFi Display (OpenWFD) user space driver.
nvidia-l4t-optee
OP-TEE Trusted Applications, user space libraries/daemon, and demonstration applications.
nvidia-l4t-pva
The Programmable Vision Accelerator (PVA) user-mode driver and interface library.
nvidia-l4t-tools
Various system tools for Jetson.
nvidia-l4t-vulkan-sc
The Vulkan SC runtime package.
nvidia-l4t-vulkan-sc-dev
The Vulkan SC dev package.
nvidia-l4t-vulkan-sc-samples
The Vulkan SC samples package.
nvidia-l4t-vulkan-sc-sdk
The Vulkan SC SDK package.
nvidia-l4t-wayland
The Wayland package.
nvidia-l4t-weston
The Weston-related files including utilities, API and backend libraries, icons, and images.
nvidia-l4t-x11
The NVIDIA X11 configuration tool.
nvidia-l4t-xusb-firmware
The XUSB firmware to be loaded by bootloader to enable USB device at boot time.
python-jetson-gpio
The Jetson GPIO library package (Python 2).
The source files are in https://github.com/NVIDIA/jetson-gpio.
python3-jetson-gpio
The Jetson GPIO library package (Python 3).
The source files are in https://github.com/NVIDIA/jetson-gpio.
Update Packages for Hosts
The following table lists Jetson Linux support components that you can install with apt on a host, and the packages that contain them.
Component group |
Packages |
---|---|
CUDA |
|
CUDA cross-compile |
|
Computer Vision |
|
Developer Tools |
|
Customizing Debian Packages
You can customize Debian packages to help you implement your solution, for example, by adding support for your carrier board. For more information, see Repackaging Debian Packages and Building Kernel Debian Packages Yourself.
Downloading Debian Packages for Later Use
As an alternative to installing Debian packages on a Jetson device or host from the APT server, you can download packages and store them, and later install them manually.
To download packages, open the NVIDIA Jetson repository in a web browser. This page displays a list of Debian packages for each JetPack release and processor. Each package name is a hyperlink; to download a package, click its link.
Updating Jetson Linux with Image-Based Over-the-Air Update
Image-Based Over-the-Air Update is a failsafe way to update BSP on a Jetson device by writing pre-generated images to the partitions. For example, OTA from version 35.2.1 to version 35.6.0.
Image-based OTA also supports updates between versions with different partition layouts that require layout changes during the update. For example, image-based OTA currently supports updates from version 32.7.x to version 35.6.0.
Updates to Jetson Linux release 35.6.0 |
||
---|---|---|
Carrier board |
Modules |
From release |
Jetson AGX Xavier |
All Jetson AGX Xavier series modules |
32.5.2, 32.6.1, 32.7.1, 35.7.2, 32.7.3, 35.2.1, 35.3.1, 35.4.1, 35.5.0, or 35.6.0 |
Jetson AGX Xavier Industrial |
All Jetson AGX Xavier Industrial series modules |
32.7.1, 32.7.2, 32.7.3, 35.2.1, 35.3.1, 35.4.1, 35.5.0, or 35.6.0 |
Jetson Xavier NX series |
All Jetson Xavier NX series modules |
32.5.2, 32.6.1, 32.7.1, 32.7.1, 32.7.3, 35.2.1, 35.3.1, 35.4.1, 35.5.0, or 35.6.0 |
Jetson AGX Orin |
All Jetson AGX Orin series modules |
35.2.1, 35.3.1, 35.4.1, 35.5.0, or 35.6.0 |
Jetson Orin NX/Nano |
All Jetson Orin NX/Nano series modules |
35.4.1, 35.5.0 or 35.6.0 |
Terms and Abbreviations
This section uses the following terms and abbreviations:
Bootloader update payload (BUP): a file that contains firmware binaries of each type needed to update a Jetson device.
Minimal set of images (MSI): the minimal set of images needed to boot Jetson Linux.
Over-the-Air Update (OTA): the Jetson Linux feature that enables you to update Jetson devices.
Top of tree (ToT): the latest revision of a file in a source control system such as Git.
High-Level Flow
Here is the workflow for an image-based OTA update:
Prepare an OTA payload package on the host machine.
Trigger the OTA process on the target device.
Preparing the OTA Payload Package
The current Jetson Linux BSP provides the necessary tools to generate the OTA payload package in the OTA tool package. To download the OTA tool package, go to Jetson Linux page.
The OTA tool package can be used to create the OTA payload package for the following:
Updating a full system
Updating Bootloader only
Updating the rootfs only
The generated OTA payload package is in the ota_payload_package.tar.gz
archive, and the OTA payload
package includes images for the partitions that need to be updated.
Note
NVIDIA recommends applying a security mechanism, such as a signature or encryption, to this package
Upload ota_payload_package.tar.gz
and the OTA tools package
ota_tools_<rel>_aarch64.tbz2
to your OTA server.
Triggering the OTA Process
You are responsible for writing the OTA client service that triggers the OTA process, and the service must include the following steps:
Download the
ota_tools_<rel>_aarch64.tbz2
OTA tool package and theota_payload_package.tar.gz
OTA payload package from your own OTA server.<rel>
is the current release number, for example35.6.0
.Validate the downloaded OTA payload package and its contents according to your own security requirements.
Use the tool in the OTA tool package to trigger the OTA update. The tool decompresses the OTA payload package and prepares it for OTA update. The tool handles cases where a partition layout change is involved and not involved, and where rootfs A/B is enabled and disabled.
Preparing for an Image-Based OTA Update
To prepare for an image-based OTA update, the following steps need to be completed on the host machine and the target device.
Steps Performed on the Host Machine
Set the
BASE_BSP
environment variable to the complete pathname of theLinux_for_Tegra/
directory for base BSP. (The base BSP is the BSP release that needs to be updated, for example, r32.7.x or r35.x.x.). For example, setBASE_BSP
by running command:$ export BASE_BSP=/home/username/R32.7.3/Linux_for_Tegra
Get the package for the current release of Jetson Linux and unpack and apply its sample root file system.
Go to the directory that contains the current BSP package and enter the following commands:
$ tar xpf jetson_linux_<rel>_aarch64.tbz2 $ cd Linux_for_Tegra/rootfs/ $ sudo tar xpf ../../tegra_Linux_sample-root-filesystem_<rel>_aarch64.tbz2 $ cd .. $ sudo ./apply_binaries.sh
Set the environment variable
TARGET_BSP
to the complete pathname of theLinux_for_Tegra/
directory for current BSP release. For example, setTARGET_BSP
by running command:$ export TARGET_BSP=/home/username/R35.6.0/Linux_for_Tegra
Install the
ota_tools_<rel>_aarch64.tbz2
OTA tool package to${TARGET_BSP}
:$ cd ${TARGET_BSP}/../ $ sudo tar xpf ota_tools_<rel>_aarch64.tbz2
If
BASE_BSP
version is 35.x.x, continue to step 7. Otherwise, to generate recovery image and recovery dtb, run the following commands:$ cd ${TARGET_BSP} $ sudo ./tools/ota_tools/version_upgrade/build_base_recovery_image.sh \ [-u <PKC_key_file>] [--user-key <User_key_file>] <target_board> <bsp_version> \ ${BASE_BSP} ${BASE_BSP}/rootfs ${TARGET_BSP}
Where:
<PKC_key_file>
is an optional PKC key file, and it must be the same as the file that was used to flash images to the target board.<User_key_file>
is an optional user key file, and it must be the same as the file that was used to flash images to the target board.<target_board>
is the appropriate configuration name:For Jetson Xavier NX P3668-0001:
jetson-xavier-nx-devkit-emmc
For Jetson AGX Xavier P2888-0001 (16GB) or P2888-0004 (32GB) or P2888-0005 (64GB):
jetson-agx-xavier-devkit
For Jetson AGX Xavier Industrial P2888-0008 (64GB):
jetson-agx-xavier-industrial
<bsp_version>
is the base BSP version, in the form Rmm-n, where mm and n are the major and minor version numbers. For example,R32-7
specifies base BSP version 32.7.x.
To generate the OTA update payload package, enter the following commands:
$ cd ${TARGET_BSP} $ sudo -E ./tools/ota_tools/version_upgrade/l4t_generate_ota_package.sh \ [options] <target_board> <bsp_version>
Options:
-s
,-b
, and-r
can be used separately, as shown or be combined in one “word”, for example,-sb
or-sr
.-s
: Skip generating the rootfs image. Use this option if a rootfs image has been generated or specified with the-f
option.-b
: Generate an OTA payload package to only update Bootloader. This option is meaningful only for an update without layout change.-r
: Generate an OTA payload package to only update rootfs. This option is meaningful only for an update without layout change.
-u <PKC_key_file>
is an optional PKC key file, and it must be the same as the file that was used to flash images to the target board.-v <SBK_key_file>
is an optional SBK key file, and it must be the same as the file that was used to flash images to the target board.-o <rootfs_updater>
specifies the script that will be be used to update the rootfs partition. (Refer to Updating the Rootfs Partition with a Customized Updater and Image for more information.)-f <rootfs_image>
is the path of the rootfs image to be written to the rootfs partition.The default rootfs is built from
${TARGET_BSP}/rootfs
, and this option allows you overwrite the default rootfs image with a self-generated rootfs image. An example is an image that is cloned from a Jetson device that has been completely customized with aToT
release of Jetson Linux.--external-device <external_device>
specifies the external device to be upgraded, andnvme0n1
is the supported device.-S <rootfs_size>
specifies the size of rootfs partition on external device. It is only valid when--external-device
option is set.KiB
,MiB
,GiB
short hands are allowed. The size set through this option must be the same as the size of rootfs partition on the external device that will be upgraded.-E <esp_image>
specifies the image to update ESP. Only valid for updates without change in layout.-T <ext_num_sectors>
specifies the number of the sectors of the external storage device.--rootfs-uuid <rootfs_uuid>
specifies UUID for rootfs to be updated through OTA.--rootfs-b-uuid <rootfs_b_uuid>
specifies UUID for rootfs B on the device to be updated through OTA.--uda-uuid <uda_uuid>
specifies UUID for UDA on the device to be updated through OTA.--uefi-keys <keys_conf>
specifies the UEFI keys configuration file.--uefi-enc <UEFI_enc_key>
specifies the key file (0x19: 16-byte; 0x23: 32-byte) to encrypt UEFI payloads.
where:
<target_board>
is the appropriate configuration name:For Jetson Xavier NX P3668-0001:
jetson-xavier-nx-devkit-emmc
For Jetson AGX Xavier P2888-0001 (16GB) or P2888-0004 (32GB) or P2888-0005 (64GB):
jetson-agx-xavier-devkit
For Jetson AGX Xavier Industrial P2888-0008 (64GB):
jetson-agx-xavier-industrial
For Jetson AGX Orin P3701-0000(32GB) or P3701-0004 (32GB) or P3701-0005 (64GB):
jetson-agx-orin-devkit
For Jetson AGX Orin Industrial P3701-0008:
jetson-agx-orin-devkit-industrial
For Jetson Orin NX P3767-0000(16GB) or P3767-0001(8GB):
jetson-orin-nano-devkit
For Jetson Orin Nano P3767-0003(8GB) or P3767-0004(4GB) or P3767-0005(8GB):
jetson-orin-nano-devkit
<bsp_version>
is the base BSP version, in the form Rmm-n, where mm and n are the major and minor version numbers. For example,R32-7
specifies base BSP version 32.7.x.
The script generates the
ota_payload_package.tar.gz
file under the${TARGET_BSP}/bootloader/<target_board>/
directory.The
ota_payload_package.tar.gz
archive that the script generates from the default rootfs occupies about 2GB, and a self-generated rootfs might yield a larger or smaller archive. To apply the image-based OTA, and decompress the archive on the Jetson device, requires at least 6GB of free space.
Note
Step 7 in Steps Performed on the Host Machine
uses the Jetson Linux sample rootfs from Linux_for_Tegra/rootfs/
to build the OTA package.
If you customized the sample rootfs, for example, add required libraries and binaries into the rootfs and apply them before running this script.
To implement a complete OTA solution, place the OTA tool package and OTA payload package on your OTA server .
Steps Performed on the Jetson Device
Review
/boot/extlinux/extlinux.conf
.If the
INITRD
entry is not set, add this line under theLINUX /boot/Image
line:INITRD /boot/initrd
If the root device is not set, add it into the
APPEND
line, for example:root=/dev/mmcblk0p1 rw rootwait rootfstype=ext4
Download the
ota_tools_<rel>_aarch64.tbz2
OTA tool package and theota_payload_package.tar.gz
OTA payload package to the target board.Create a directory to hold files that were generated in the OTA update process.
Set the
WORKDIR
environment variable to the complete pathname for this directory.Unpack
ota_tools_<rel>_aarch64.tbz2
into the${WORKDIR}
directory.Create a
/ota/
directory.Place the
ota_payload_package.tar.gz
OTA payload package in the/ota/
directory.Unpack the OTA payload package and prepare to start OTA:
$ cd ${WORKDIR}/Linux_for_Tegra/tools/ota_tools/version_upgrade $ sudo ./nv_ota_start.sh /ota/ota_payload_package.tar.gz
Note
For OTA update from r35.x.x on Jetson AGX Xavier, ensure that the device has been rebooted at least once before starting OTA.
If no error occurred in step 8, reboot the target board.
After executing this step, the target board boots to the recovery kernel, which runs the OTA update process. If an unexpected power loss or reset occurs during the OTA update process, the target device can reboot into the recovery kernel and continue the update. The maximum number of times the target device reboots and continues the update is determined by the
OTA_MAX_RETRY_COUNT
script variable, which defaults to 0 (zero). If the update fails more than the specified number of times, the target device boots to the recovery kernel and enters the bash shell. You can change the value ofOTA_MAX_RETRY_COUNT
in${TARGET_BSP}/tools/ota_tools/version_upgrade/nv_recovery.sh
.On the target device, if the update process fails, the logs are stored in the
/ota_logs/
directory, and these logs record the details about the OTA update process. If this process successfully completes, by default, the logs are automatically deleted. To save logs for a successful OTA, see Reserving logs requirement in Miscellaneous Customization.
Note
To create a complete, secure OTA update solution, you must complete the following tasks:
Implement an OTA client that executes this procedure on the target device.
Apply security mechanisms according to your security policy requirements.
Utility to Trigger an OTA
The nv_ota_start.sh
utility is used to trigger the OTA, and image-based OTA supports
updates between versions with or without partition layout changes. The OTA supports updates
whether rootfs A/B is enabled or disabled. You do not need to be aware of the difference
because the nv_ota_start.sh
utility handles both cases.
nv_ota_start.sh
is included in ota_tools_<rel>_aarch64.tbz2
. It
determines whether layout changes are needed and executes another
script to perform the appropriate type of update.
To perform an update without layout changes, the script executes
nv_ota_update_without_layout_change.sh
.
To perform an update with layout changes, the script executes nv_ota_update_with_layout_change.sh
.
Refer to Updating with Partition Layout Changes for more
information about how to update a version with partition layout changes.
Updating with Partition Layout Changes
An update with partition layout changes is a challenging process for an image-based OTA update. If you perform the partition changes directly, an unexpected reboot during the update might fail and leave the Jetson device in an unbootable state.
BSP supports A/B update, which maintains two sets of partitions (chain A and chain B) to boot and run the operating system. It uses only one chain at a time, applies updates to the partitions on the inactive chain, and swaps the roles of the chains. For example, when chain A is active, BSP boots and runs the operating system from the partitions in chain A and applies updates to those in chain B. This ensures that an update failure cannot render the device unbootable.
For more information about the A/B update process, refer to Update and Redundancy.
To implement fail-safe update, if there is an unexpected reboot during update, the image-based OTA update process creates some intermediate partition layouts, which it uses to create alternative bootable paths. A bootable path is composed of many partitions located on the free space of the storage device. The images stored in these partitions are called MSI.
For example, an OTA update from release 32.7.x to release 35.6.0 on Jetson Xavier NX P3668-0001 the following intermediate partition layouts:
flash_l4t_t194_spi_emmc_p3668_R32i.xml
is based on the default partition layout in release 32.7.x. It is used byjetson-xavier-nx-devkit-emmc-R32i.conf
.flash_l4t_t194_spi_emmc_p3668_R32x_R35i.xml
is based on the default partition layout in release 32.7.x. It is used byjetson-xavier-nx-devkit-emmc-R32x-R35i.conf
.flash_l4t_t194_spi_emmc_p3668_R35A_R35i.xml
is based on the default partition layout in release 35.6.0. It is used byjetson-xavier-nx-devkit-emmc-R35A-R35i.conf
.
l4t_generate_ota_package.sh
uses these intermediate partition layouts
and their corresponding .conf
files to generate the OTA payload package.
By default, these layouts are created based on the default partition layout
from the released BSP. If you customize anything on the default partition
layout, you must apply the customization to the intermediate partition layouts.
During OTA, the update script verifies these layouts with layouts on the actual
board. If the layouts do not match, OTA update does not proceed.
Backing Up and Restoring Files on the APP Partition
The nv_ota_preserve_data.sh
script in the ota_tools_<rel>_aarch64.tbz2
backs up and restores files on the APP
partition during OTA update. It is
located in the Linux_for_Tegra/tools/ota_tools/version_upgrade/
directory.
Edit the ota_backup_files_list.txt
configuration file to add the
pathnames of files that will be preserved after the OTA update. The
distributed version of ota_backup_files_list.txt
contains the following:
# All the files or directories should be listed with absolute path
# Example:
# etc/passwd
# opt/nvidia
Pathnames are written in relative form, but the names are always interpreted relative to the file system root. You can think of the names as absolute pathnames from which the leading slash is omitted.
You can add comment lines starting with a pound sign (’#
’) in column 1.
Note
The nv_ota_preserve_data.sh
script packs the listed files into a .tar.gz
archive. You can select other ways to back up and restore these files based on your own requirements.
OTA Upgrades on an External Device
Jetson devices support booting from external storage devices, such as an NVMe.
To apply an image-based OTA on Jetson devices, the l4t_generate_ota_package.sh
script provides the --external-device
and -S
options to generate an OTA payload
package for external storage devices.
To flash a Jetson device with an external storage device, refer to Flashing with initrd in Flashing Support for more information.
OTA Upgrades with Disk Encryption Enabled
Jetson devices support disk encryption on internal or external devices, and the rootfs partition is encrypted.
To apply an image-based OTA on Jetson devices with disk encryption enabled, set “ROOTFS_ENC=1” when
running the l4t_generate_ota_package.sh
script to generate an OTA payload package. You can also specify the
key file for disk encryption by using the -i
option.
To enable disk encryption on Jetson devices, refer to How to Create an Encrypted Rootfs on the Host in Disk Encryption.
Note
This release is available for an OTA upgrade from earlier R35 releases to R35.6.0 with disk encryption enabled. For example, from R35.2.1 to R35.6.0.
OTA Upgrades with UEFI Secure Boot Enabled
The image-based OTA now supports UEFI secure boot. If the OTA payload is built with UEFI secure boot enabled, the following will occur after the update: UEFI secure boot will either remain enabled if it was already active, or it will be newly enabled if it was previously disabled.
To generate an OTA payload package with UEFI secure boot enabled, you must specify the --uefi-keys
and --rootfs-uuid
options. If UEFI payload encryption is enabled, you must specify the --uefi-enc
option. If rootfs A/B is enabled on the device, you must specify the --rootfs-b-uuid
option. If the UDA partition is encrypted with disk encryption, you must specify the --uda-uuid
option. The generated OTA payload package contains an additional uefi_secureboot_overlay_tar.gz
file which packs the UEFI signed and/or encrypted payloads.
Note
It is not supported to perform an OTA update from R32 release to the latest R35 release with UEFI secure boot enabled.
Complete and Secure the OTA
NVIDIA provides the basic functionality of updating the system through the OTA update process. You must modify the process and create a complete and secure OTA solution. Depending on your needs, your modified process might have to meet at least one of the following requirements:
Encrypting OTA update payloads
Hosting OTA update payloads on an OTA update server
Triggering an OTA update when an update is found on the OTA server (a function of the OTA update client on the target device)
Authenticating the OTA update server
Decrypting OTA update payloads
Determining when to apply OTA update payloads
Customization
If you customized the released BSP, for example by customizing the rootfs or changing the partition layout, you must modify some files in the distributed image-based OTA update process to apply the image-based OTA update solution. The following sections provide information about the customization types and the OTA update changes that the types require.
Rootfs Customization
Rootfs customization comprises:
Adding or removing files in the rootfs.
Modifying the files in rootfs.
These changes require the following:
Applying changes to the rootfs.
Partition Layout Customization
Partition layout customization comprises:
Adding or removing partitions.
Changing size of partitions.
Changing location of partitions.
These changes require the following:
Modifying the provided intermediate partition layouts to accommodate the base system. For example, for a Jetson Xavier NX P3668-0001 flashed with release 32.7.x, the partition layout files are
flash_l4t_t194_spi_emmc_p3668_R32i.xml
andflash_l4t_t194_spi_emmc_p3668_R32x_R35i.xml
.Modifying the provided intermediate partition layout based on
${TARGET_BSP}
the current release system. For the board above, the partition layout file isflash_l4t_t194_spi_emmc_p3668_R35A_R35i.xml
.Modifying the current release partition layout for
${TARGET_BSP}
. For Jetson Xavier NX P3668-0001, it isflash_l4t_t194_spi_emmc_p3668.xml
.Modifying
MSI_EMMC_OFFSET
in the*.conf
file if required. Make sure that the free space starting atMSI_EMMC_OFFSET
is large enough to store the MSI. For the example above, the corresponding configuration files arejetson-xavier-nx-devkit-emmc-R32i.conf
,jetson-xavier-nx-devkit-emmc-R32x-R35i.conf
andjetson-xavier-nx-devkit-emmc-R35A-R35i.conf
.
Update Process Customization
Update process customization comprises:
Changing the process of updating partitions.
Updating a newly created partition in addition to default partitions.
Updating only some of the default partitions.
These changes require the following:
Modifying the provided file
upgradetasklist.txt.XXX
, In theupgradetasklist.txt.XXX
file, “XXX
” is a string that specifies the device, the current version, and the version to which you want to update. For example, to update release 32.7.x to release 35.6.0 on a Jetson Xavier NX P3668-0001, you must modifyupgradetasklist.txt.jetson-xavier-nx-devkit-emmc.R32x_to_R35-ToT_emmc
to specify the partitions that will be updated.
Recovery Image Customization
Recovery image customization comprises:
Adding some files to the recovery initrd.
These changes require the following:
Editing the provided file
recovery_copy_binlist.txt
to specify the file systems and pathnames of any files you want to add to the recovery image. See the same file for an explanation and examples of how to make the changes.
Recovery Task Customization
In the recovery kernel, the nv_ota_run_tasks.sh
script will be executed as a task runner. It will execute OTA tasks in a sequential order. To add a task to be run when recovery kernel is running, you must complete the following tasks:
Place the script files that execute tasks into the
Linux_for_Tegra/tools/ota_tools/version_upgrade/
directory. Make sure the script files have execution permission.Modify the
OTA_TASKS
and theOTA_TASK_NEEDED_FILES
innv_ota_customer.conf
to add these script files.The script files whose names are listed in the
OTA_TASKS
are OTA tasks which will be executed in order by the task runner. Insert the script file name at a proper position.The script files whose names are listed in the
OTA_TASK_NEEDED_FILES
are the files needed by OTA tasks. Add the script file name into the list if any.
Re-generate the OTA update payload package.
Miscellaneous Customization
Ethernet connectivity requirement
If you want to ensure that no update is performed unless a stable Ethernet connection is available, enable OTA update’s Ethernet connectivity requirement by setting the property
REQUIRE_ETHERNET
innv_ota_customer.conf
. This setting makes Jetson device check Ethernet connectivity before starting OTA. If no connection is found, it attempts to establish one by rebooting.This requirement is disabled by default because a Jetson device does not use Ethernet as its primary means of connectivity.
Reserving logs requirement
Logs are automatically deleted after the OTA successfully completes. To save logs for debug purposes, you can set the
RESERVE_LOGS
property totrue
innv_ota_customer.conf
. After the OTA finishes, this setting saves all the logs in the/last_ota_update_log
directory.
Extlinux.conf Customization
For an OTA update without a layout change, and rootfs A/B is enabled, when you manually edit the /boot/extlinux/extlinux.conf
file in the rootfs before applying OTA, ensure that this change is also applied on the /boot/extlinux/extlinux.conf
in the updated rootfs after the OTA has finished. For example, to add a "video=tegrafb"
entry on the APPEND
line, you can add a few lines of code as follows into the restore_extlinux_conf()
function in the Linux_for_Tegra/tools/ota_tools/version_upgrade/nv_ota_update_without_layout_change.sh
:
restore_extlinux_conf()
{
......
sed -i "/^[ \t]*APPEND/s|\$| video=tegrafb|" "${extlinux_conf}"
if ! umount "${tmp_mnt}"; then
......
}
Multiple Board Specs Customization
The image-based OTA supports generating a multi-spec OTA payload for each supported Jetson device. If you are sure what the board specs are for your Jetson devices, you can customize the Linux_for_Tegra/tools/ota_tools/version_upgrade/ota_board_specs.conf
to comment out unused board spec entries before you generate the OTA payload package. This can shorten the time needed to generate the OTA payload package and decrease the size of the resulting package.
Here is a sample of a customized jetson_orin_nano_devkit_ota_emmc_r35_spec
field in the ota_board_specs.conf
file that can generate the OTA payload package exclusively for the Jetson Orin NX P3767-0001(8GB):
jetson_orin_nano_devkit_ota_emmc_r35_spec=(
# External device
# orin-nx 16GB
#'boardid=3767;fab=000;boardsku=0000;boardrev=;fuselevel_s=1;chiprev=;chipsku=00:00:00:D3;board=jetson-orin-nano-devkit;rootdev=nvme0n1p1;bup_type=bl;signed_img_dir=images-R35-ToT'
# orin-nx 8GB
'boardid=3767;fab=000;boardsku=0001;boardrev=;fuselevel_s=1;chiprev=;chipsku=00:00:00:D4;board=jetson-orin-nano-devkit;rootdev=nvme0n1p1;bup_type=bl;signed_img_dir=images-R35-ToT'
# orin-nano 8GB
#'boardid=3767;fab=000;boardsku=0003;boardrev=;fuselevel_s=1;chiprev=;chipsku=00:00:00:D5;board=jetson-orin-nano-devkit;rootdev=nvme0n1p1;bup_type=bl;signed_img_dir=images-R35-ToT'
# orin-nano devkit 8GB
#'boardid=3767;fab=000;boardsku=0005;boardrev=;fuselevel_s=1;chiprev=;chipsku=00:00:00:D5;board=jetson-orin-nano-devkit;rootdev=nvme0n1p1;bup_type=bl;signed_img_dir=images-R35-ToT'
# orin-nano 4GB
#'boardid=3767;fab=000;boardsku=0004;boardrev=;fuselevel_s=1;chiprev=;chipsku=00:00:00:D6;board=jetson-orin-nano-devkit;rootdev=nvme0n1p1;bup_type=bl;signed_img_dir=images-R35-ToT'
)
Updating the Rootfs Partition with a Customized Updater and Image
When you generate an OTA payload package (step 7 in
Steps Performed on the Host Machine),
you can specify the rootfs updater with the -o
option and specify the rootfs image with the -f
option.
The rootfs updater is a script that writes the rootfs image to the
rootfs partition. It is called with appropriate command line parameters
and options by several Jetson Linux utilities and services, such as OTA
update. NVIDIA provides a default rootfs updater named
nv_ota_rootfs_updater.sh
which is in the distribution archive
ota_tools_<rel>_aarch64.tbz2
.
The default rootfs updater’s usage is:
$ nv_ota_rootfs_updater.sh [-p <devnode>] [-d <workdir>] <image>
Where:
<devnode>
is the device node path of the rootfs partition, for example,/dev/mmcblk0p1
.<workdir>
is the path of the OTA work directory, for example,/ota_work
.<image>
is the path of the rootfs image, for example,/ota_work/system.img
.
If you create a customized rootfs image, you must specify a rootfs
updater that can process that image. The rootfs updater you specify must
expect the same arguments and options as nv_ota_rootfs_updater.sh
.
Depending on your needs, the updater might (or might not) use these arguments
and options.
User Release Version
An image-based OTA supports an update from the BSP version to the same BSP version. For example, for an OTA update from version 35.6.0 to version 35.6.0 with a updated rootfs and with a updated user version number.
The user release version is defined in Linux_for_Tegra/nv_tegra/user_version
and the valid value is between 0.0~999.999.
During generating rootfs image, the user release version defined as USER_VERSION
in Linux_for_Tegra/nv_tegra/user_version
is to be copied into the file /etc/user_release_version
in rootfs.
Updating the ESP Partition
To manually update the esp partition, complete the following steps:
Download the
ota_tools_<rel>_aarch64.tbz2
OTA tool package. <rel> is the current release number, for example, 35.6.0.Copy the OTA tool package to the Jetson device’s filesystem and extract the package. For example, you can copy the OTA tool package to the
/opt/
directory and extract it.Copy the new esp partition image to the Jetson device’s filesystem. For example, you can copy the
esp.img
to/opt/
directory.To update the esp partition, use the
nv_update_alt_part.sh
tool in the OTA tool package$ cd /opt/Linux_for_Tegra/tools/ota_tools/version_upgrade/ $ sudo ./nv_update_alt_part.sh esp /opt/esp.img
If no error occurred in step 4, reboot the Jetson device.
Examples
NVIDIA provides several examples of how to apply an image-based OTA update:
Generating the OTA payload package for different cases.
Using a golden image in the OTA update.
For more information about these examples, see the Linux_for_Tegra/tools/ota_tools/version_upgrade/Image_based_OTA_Examples.txt
file,
which is in the ota_tools_<rel>_aarch64.tbz2
OTA tool package.