NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux SDK

Developer Guide
5.1.12.0 Release


 
Mass Storage Partitions
 
Creating Partitions
Multipartition Architecture
Partition Overview
Xavier Native Partitions
Xavier Guest OS Partitions
Customizing the Configuration File
Customizing Partitions
Configuration File Entries
Setting Attributes
Aligning os_args Values and the Mass Storage Layout
Configuring GPT Devices
Flashing Partitions with a File System and Kernel Image
Managing Mass Storage Partitions in Virtualization
Partition Loader
Storage Layout
The platform supports formatting mass storage media into multiple partitions for storing data, such as device OS images and boot loader images. Data inside these partitions are not end-user visible through the typical OS filesystems.
The platform also supports the GUID partition table GPT scheme for defining the layout of the partition table on a physical hard disk.
Creating Partitions
Options for creating partitions differ between boot media and non-boot-media.
For boot media (for QSPI media), the partition layout is passed from the kernel command line or via the DT node. The partition layout is a kernel interpretation. The boot loader continues to use the partition table (PT).
For non-boot-media (eMMC/SD card), you can create partitions from user-space or by using bootburn. However, if you update the partition from user-space, the partition layout for the boot loader will go out of sync with the partitions. This is because user-space uses GPT for storing partition layout. In contrast, Boot loader uses the PT definitions.
For best practices, expose non-system partitions to user-space, excluding the system partitions like BCT, PT, boot loaders, and kernel partitions. To update system partitions using update tools, it is recommended that whole flash be exposed to user-space in the kernel.
For information about the flashing flow, see Flashing with Bootburn.
Multipartition Architecture
The multipartition layout is as follows.
multipart_ex_partition_layout.jpg
The partition properties are:
Base address, expressed as bytes
Length, expressed as bytes
Name, maximum 20 character-length string
Storage device ID
File system type
Flag indicating whether the partition is to be write-protected on boot.
Partition Overview
Two configuration (CFG) versions are supported. The existing CFG format is identified as “legacy” or “v1,” while the 3-level CFG format is identified as “v2.”
The usage for each type of partition is as follows:
Xavier Native Partitions
Xavier Guest OS Partitions
Xavier Native Partitions
The partition names for the primary and recovery partitions is as follows.
For CFG v1, each recovery partition’s name is the primary partition’s name suffixed with ‘r’.
For CFG v2, only the recovery partitions in the top-level CFG have their names suffixed with ‘r’.
The other recovery partitions in CFG v2 maintain the same name as their primary counterparts; the recovery partitions are differentiated based on the boot chain they belong to (i.e. A or B).
Partition name
Applies to
Description
APP
NVIDIA DRIVE™ Android
Contains the applications.
For best practices, allocate APP and CAC partitions large enough to accommodate future images.
CAC
NVIDIA DRIVE™ Android
Contains the cache partition. This partition must be large enough to hold system.img, boot.img, and all other binaries combined on the device.
For best practices, allocate APP and CAC partitions large enough so they can accommodate future images.
MDA
NVIDIA DRIVE™ Android
TBD
MSC
NVIDIA DRIVE™ Android
Contains one of the two commands, “boot-recovery”, which will make the system boot into recovery kernel.
UDA
NVIDIA DRIVE™ Android
Contains the User Data Area. This is the user space for the user to store data.
Bct
 
Contains the Boot Configuration Table.
mb1-bootloader
 
Contains the MB1 boot loader.
mb1-bct
 
Contains the BCT configuration file for MB1.
mb2-bootloader
 
Contains the MB2 boot loader for the BPMP.
mts-preboot
 
Contains preboot firmware for the CPU.
mts-bootpack
 
Contains the CPU firmware.
bpmp-fw
 
Contains the power-management firmware.
bpmp-fw-dtb
 
Contains the power-management firmware DTB.
ramdisk
 
Contains the primary copy of the ramdisk image.
secure-os
 
Contains the recovery copy of the ramdisk image.
Pt
 
Contains the Partition Table.
kernel
 
Contains the kernel image.
kernel-dtb
 
Contains the device tree binary image required by kernel.
eks
 
Contains the eks.dat object, which is an encrypted Widevine key.
spe-fw
 
Contain the firmware for SPE-R5.
sc7-fw
 
Contains the firmware for SC7 resume.
sce-fw
 
Contains the firmware for SCE-R5. This can be either Camera firmware or Safety firmware, based on use case.
adsp-fw
 
Contains the firmware for Audio processor.
gp1 or fs-gp1
 
Contains the primary GUID Partition Table.
The GPT partitioning scheme must be used. Extended boot record partitions (ER<n>) are not required with GPT partitioning. Do not use the filename partition attribute when creating a GP1 partition.
This partition type signifies the start of the GPT partitioning. All the partitions between GP1 to GPT partition are counted as partitions in GPT creation.
GP1 partition size must be greater than or equal to 17,408 bytes. Similarly, GPT partition size must be greater than or equal to 16,896 bytes.
For more information about using GPT, see Configuring GPT Devices.
gpt or fs-gpt
 
Contains the secondary GUID Partition Table. This partition must be at the end of the device.
The GPT partitioning scheme must be used. Extended boot record partitions (ER<n>) are not required with GPT partitioning. Do not use the filename partition attribute when creating a GPT partition.
GPT partition size must be greater than or equal to 16,896 bytes.
For information about using GPT, see Configuring GPT Devices.
A_<type>_chain
or
B_<type>_chain
 
Contains the partitions that belong to a particular boot chain (i.e. A or B). It points to a subsidiary CFG file that defines those partitions. <type> indicates the storage device type as emmc or qspi.
Xavier Guest OS Partitions
The supported guest partition names, and their legal values, is as follows.
Partition Name
Description
Applies to DRIVE OS Linux: guest-linux
Applies to DRIVE OS QNX: qnx-guest
In CFG v1, specifies the global partition for the first guest. In CFG v2, specifies the global partition for any given guest.
In either case it points to sub_storage_cfg, which defines the internal layout of that guest.
gos1-gp1
Specifies the primary GPT partition for the storage device used by Guest OS 1 (GOS1).
gos2-gp1
Specifies the primary GPT partition for the storage device used by Guest OS 2 (GOS2).
gos2-usr
Specifies the unused area on the storage device used by GOS2. The end-user can customize this area as desired.
gos2-gpt
Specifies the back-up GPT partition for the storage device used by GOS2.
pt
Specifies the NVIDIA-specific implementation of the Partition Table, which stores the information on the locations of the partitions in storage_cfg.
Customizing the Configuration File
Customize the mass storage partitions on the target by modifying the configuration file flashed to the target.
Configuration files (CFG files) consist of mass storage device declarations followed by partition declarations. The NVIDIA tools use the configuration file to create the images on the host and flash the target device on the specified memory locations.
The platform includes a default configuration file used by the flashing scripts. Use the default configuration file as a starting point for any customization, and backup the original file before attempting modifications.
For an example of the dual Linux OS partition configuration, see the Example Virtual Partition Configuration chapter in the NVIDIA DRIVE OS 5.1 Linux PDK Development Guide. For an example of a native OS (not virtual) partition configuration, see the Example Native OS Partition Configuration chapter in the NVIDIA DRIVE OS 5.1 Linux PDK Development Guide.
Note:
Two CFG versions are supported. The existing CFG format is identified as “legacy” or “v1,” while the 3-level CFG format is identified as “v2.”
The default configuration file for a platform is adequate for initial product development. However, consider creating a custom configuration file for these stages:
Finalizing production
Flashing updated images
There are several advantages to using a custom configuration file. It can specify:
Different kernel images for recovery and primary partitions
Temporary partition
RamDisk or other feature in recovery partition or vice-versa
If there is a need to repeatedly switch between NFS and MMC, it is recommended to create and use separate configuration files for each.
Customizing Partitions
When partitions are finally customized (for example, you have modified or added partition definitions in the configuration file, run the flashing script to flash the device and set the partitions as defined.
By default, the flashing scripts use the default configuration file. If you customized a configuration file, specify that file when calling the flash script.
For more information, consult Flashing the Board.
Configuration File Entries
Declarations consist of attribute/value pairs. The configuration file format is:
[meta]—(optional) Specifies CFG metadata.
<attr>=<val>—Specifies attribute/value pairs for the device.
[device n]—(required) Specifies a mass-storage device.
<attr>=<val>—Specifies attribute/value pairs for the device.
[partition]—Specifies a partition in the current device.
<attr>=<val>—Specifies attribute/value pairs for the partition.
# - comments
Mandatory configuration file entries are:
Device type.
Partition for the device partition table.
Partition for the OS image.
Partition for the kernel.
Partition for the boot loader.
BCT partition for the boot configuration table.
Size of partition, which can be the exact file size being programmed in bytes provided it be erase_block size aligned for the flash. However, to minimize changes to partition sizes in the CFGpartition, it is recommended to set the partition size in the CFG file greater than actual file size to be flashed in the partition.
 
Note:
The partition size always aligns to the erase block size. For Xavier, if partition size is not aligned, the flashing tool terminates with an error.
Setting Attributes
The possible values for the meta, device, and partition attributes are as follows.
Meta Attributes Table
The following table shows supported device attributes and their legal values.
Device
Values
Description
Version
1 (default) or 2
Specifies the CFG version.
• 1: legacy (v1)
• 2: 3-level (v2)
Device Attributes Table
The following table shows supported device attributes and their legal values.
Device
Values
Description
type
qspi/spi
sdmmc
ide
ufs_lun
ufs_boot
Specifies the type of mass storage device.
instance
<instance_num>
Specifies the controller instance.
Xavier has four sdmmc controller instances. Each instance drives one end point, as follows:
• instance=0 specifies SDMMC1.
• instance=1 specifies SDMMC2.
• instance=2 specifies SDMMC3.
• instance=3 specifies SDMMC4.
For type-ufs, the instance will correspond to the SCSI device instance. System partitions, if any, must be present on LUN 0, and LUN 0 must enumerate at /dev/sda.
size
<device_size>
Specifies the size of the mass storage device. Required if GPT partition is created during bootburn.
linux_name
<linux_name>
Specifies the name of the device in bootburn.
 
For QSPI devices: /dev/block/mtdblock<id>
Where <id> identifies the device.
• For MMC devices: /dev/block/mmcblk<id>
• For mSATA/USB/UFS devices:
/dev/block/sda
 
Note: With multiple mSATA/USB devices connected, enumeration varies as sda, sdb, etc. Instead of path, <linux_name> is specified with the controller address-space. For example:
/dev/block/34600000.sdhci
lun
0-7
Logical unit number for the device.
Partition Attributes Table
The following table shows supported partition attributes and their legal values.
Partition Attribute
Values
Description
name
<name>
Specifies up to a 20-character name for the partition. This name is used when opening a partition for read/write access.
Names longer than 20 characters are not supported.
id
<identifier>
Identifier.
type
boot_config_table
bootloader
partition_table
extended_boot_record
GP1
GPT
data
Specifies the type of partition.
boot_config_table is for the BCT.
partition_table is for the partition table.
extended_boot_record is for the EBR.
GP1 is for the primary GPT partition.
GPT is for the secondary GPT partition.
data is for the remaining partitions.
type (continued)
mb1_boot_config_table
mb2_bootloader
mts_preboot
mts_bootpack
bpmp_fw
bpmp_fw_dtb
bootloader_cpu
secure_os
kernel_dtb
kernel
ramdisk
WB0
spe-fw
ape-fw
sce-fw
 
allocation_policy
absolute
sequential
extended
Specifies the type of allocation policy.
 
sequential—The begin immediately after the preceding partition.
 
absolute—The partition begins at the location specified by the start_location attribute.
 
extended—The partition is extended until end of the device just before GPT partition. Only one extended partition is allowed per device.
filesystem_type
basic
ext2
ext3
ext4
qnx
Specifies the type of filesystem formatted on the partition when the partition is created. The value may be:
 
basic—No file system. The partition can be overloaded with a file system image by providing a filename for the partition (see the filename entry in this table), or by formatting the partition after it is created.
 
ext2, ext3, or ext4—An ext2, ext3, or ext4 filesystem.
 
Applies to: eMMC, SD card, and NOR media in Linux: UBIFS for QSPI media.
 
qnx—A qnx6 filesystem.
 
Applies to DRIVE OS QNX:
External file system support depends on the support available in the flashing tool.
For a qnx6 filesystem the following environment variables must be set:
$ export QNX_HOST=<QNX_TOOLCHAIN_BASE>/host/linux/x86_64/
$ export QNX_TARGET=<QNX_TOOLCHAIN_BASE>/target/qnx7/
Where <QNX_TOOLCHAIN_BASE> is the pathname of the toolchain base.
start_location
<start>
Specifies the starting location of the partition in the mass storage device. Valid for absolute partitions only.
size
<size>
Specifies the size of the partition in bytes. Decimal and hexadecimal values are valid. The boot loader requires that the partition size be aligned and the alignment size be:
• For QSPI: 128K (131072) bytes
• For eMMC/SD card: 8K (8192) bytes
partition_attribute
32-bit unsigned number
For CFG v1:
For virtualization, this property specifies to which guest this partition belongs. Partition_attribute must be equal to guest_id + 1 as defined in the PCT. Additionally, per device only one partition can be allocated to a given guest.
For CFG v2:
The bits of partition_attribute have the following definitions:
• Bit 31: Set if the partition’s storage device is the boot medium for the guest.
• Bit 30: Set if the partition holds a blob for boot-chain (and sub_cfg_file is present if the partition is present on the global boot device).
• Bit 29: Set if the partition holds a blob for guest partitions (and sub_cfg_file is present).
• Bit 28: Set if the partition holds a blob for user partitions (and sub_cfg_file is present).
• Bits 4:0: guest ID.
filename
<filename>
 
See Notes at the end of this table.
Specifies the name of the file to write into the partition. The file must be present in the directory in which nvimagegen is running or named with an absolute path.
The filename attribute cannot be used with the following attributes:
dirname
imagepath
rcm_filename
<filename*>
 
See Notes at the end of this table.
Specifies the recovery mode binary for use in microboot 1 (NVC) or microboot 2 (MB2). The file must be present in the directory in which nvimagegen is running or named with an absolute path.
The filename attribute cannot be used with the following attributes:
dirname
dirname
<Directory Path*>
 
See Notes at the end of this table.
Specifies the directory path for creating the filesystem image (based on the filesystem_type attribute) and burning the same to the media. This attribute applies to the ext2/3 external file system.
For detailed information, see the *_fs.cfg file.
The dirname and filename attributes cannot be used in the same partition.
imagepath
<file name*>
 
See Notes at the end of this table.
Specifies the kernel image path, which is usually an OS kernel partition. The Flashing tools create the kernel image, which will be flashed based on the other specified. For detailed information, see the *_fs.cfg file.
The imagepath and filename attributes cannot be used in the same partition.
os_args
<String>
Kernel command line to be passed to the kernel. Key-value pairs are separated by spaces. root= is required and, depending on the root=value, rootfstype= may also be required.
The supported key-value pairs are specified in:
kernel/Documentation/kernel-parameters.txt
Valid only with the kernel_dtb partition.
ramdisk_path
<filename*>
 
See Notes at the end of this table.
Specifies the name of the ramdisk image file. The specified file must be present in the directory in which nvimagegen is running or the name must be an absolute path.
Valid only with the imagepath attribute.
os_load_address
<address>
Specifies address where boot loader must load the kernel image.
When the image is zImage (specified in imagepath), set this property to 0xA00800. When the image is Image, set it to 0x8000.
ramdisk_load_address
<address>
Specifies the load address for Ram-disk.
decompression_algorithm
<lzf | zlib | none>
Specifies the algorithm that Quickboot uses for decompressing images.
lzf is the preferred algorithm.
Ensure that the partition has enough space to hold the image, especially when flashing an uncompressed image (decompression_algorithm=none).
• If this field is not specified, by default, lzf is used as the decompression algorithm.
• Quickboot decompresses images in parallel with loading the image.
Use only when the imagepath or ramdisk_path attribute points to an image.
Applies to: QSPI media only.
write_protect
0 or 1
Not currently supported.
Specifies whether to write-protect a given partition. Write-protection prevents partition erasures.
This attribute has no effect during flashing. All partitions are unprotected before flashing.
sub_config_file
<cfg_pathname*>
 
See Notes at the end of this table.
Specifies the path to the configuration file that contains the layout for the guest. The flashing system, including the main configuration file, assumes this is a single blob file.
load_address
Numeric_value
Specifies the load address for the binary in the given partition.
entry_point
Numeric_value
Specifies the entry_point for the binary in the given partition.
version
Numeric_value
Specifies the version for the given binary.
image_type
<linux | android | qnx | integrity | hypervisor | ramdisk | mods>
Specifies the type of image. Valid only for kernel and ramdisk partitions.
Currently, mods is for internal use.
stream_validation
<yes|no>
Specifies whether to validate the image in parallel with loading an decompressing the image.
If decompression_algorithm is selected, this attribute is ignored.
authentication_group
<number>
Specifies the partition to a group. All the partitions grouped will be authenticated together.
The minimum group number is 1 and the maximum group number is 15. Group number 0 means not in a group.
For more information, see Grouping of Boot Images.
Notes
*To avoid Bootburn errors, do not use special characters in directory names. Such special characters include the plus sign (+) and pound sign (#).
Configuration files that configure the Flashing tool for an eMMC, or QSPI media depend upon the targeted OS. You can find the configuration files in these locations:
<top>/drive‑t186ref‑foundation/tools/host/flashtools/bootburn_t19x/*.cfg
For best practices, retain the file as provided and add optional partitions based on project requirements.
Aligning os_args Values and the Mass Storage Layout
When flashing a device, the flashing script uses the configuration file to determine how to flash individual partitions. os_args attributes provide a kernel command line that specifies file system and partition attributes. Of particular interest are the settings for Memory Technology Device (MTD) devices, which use QSPI flash.
If you change your flash partition layout, you must also modify the attributes in os_args to be consistent with the mass storage layout. For example, if you move the data partition, you must also update the offsets or indices in the os_args value. Such modifications are required to ensure non-overlapping partitions.
By default, the OS kernel has no knowledge of the mass storage layout created when flashing (i.e., QSPI partition offset and size, and file system type). At runtime, the kernel cannot determine all layout settings. In particular, the os_args attribute may need to specify the Linux kernel settings described in the following table.
os_args Settings
Description
rootfstype=ubifs
Required if the root file system is UBIFS. Unlike the ext2/ext3/ext4 file systems, the kernel cannot at runtime detect UBIFS.
root=ubi<n>_<m>
Where:
<n> is the sequential number of the UBI device (usually 0)
<m> is the "id" attribute on the partition.
Required if the root device is a UBI volume.
The alternative form of this value is ubi<n>:<name>, where <name> is the partition name, such as EARLY_FS_VIDEO.
ubi.mtd=<x>
Where <x> is an MTD partition number.
Required to attach the UBI to the MTD partition at boot, for example, if the root device is a UBI volume.
mtdparts=tegra-nor:<size>@<offset>(<name>)
Where:
<size> is the partition size in kilobytes.
<offset> specifies the beginning of the partition.
<name> is the symbolic name for the partition. For example: whole_device or userspace.
Required to export NOR partitions as mtdN and mtdblockN devices. For example, use this key-value pair to export the partition at offset <offset> so UBI can attach itself to such devices. You can get the value for <size>and <offset> from the default CFG file for your platform.
tegra-nor is the flash device name and must not be changed.
For information on all supported kernel command parameters, see the following file.
kernel/Documentation/kernel-parameters.txt
Configuring GPT Devices
GUID Partition Table (GPT) is a standard for the layout of the partition table on a physical hard disk. For general information on GPT, see GUID Partition Table at:
http://en.wikipedia.org/wiki/GUID_Partition_Table
To configure GPT
1. In the kernel configuration file, enable the following partition types:
CONFIG_PARTITION_ADVANCED=y
CONFIG_EFI_PARTITION=y
2. In your flash.cfg configuration file, specify the GP1 partition.
Partitions between this partition and GPT are exposed, although only those selected to mount are mounted.
Among other attributes for GP1 partitions, the following attributes must be set as specified here:
filesystem_type=basic
type=GP1
3. Specify the GPT partition.
Among other attributes for GPT partitions, the following attributes must be set:
filesystem_type=basic
type=GPT
size=0xFFFFFFFFFFFFFFFF
 
Note:
The GPT partition must be the last partition.
4. Specify fill and extension attributes, depending on your platform. For Xavier, set the GPT partition allocation_policy attribute to sequential.
Flashing Partitions with a File System and Kernel Image
When the configuration file contains imagepath partition attributes, the flashing script flashes a file system and kernel image. Internally, flashing tools create the kernel image that is flashed based on the other partition attributes. The following partition attributes affect the file system:
filesystem_type
filename
dirname
imagepath
In addition to these attributes, the imagepath or ramdisk_path attribute uses the following attributes:
os_args
ramdisk_path
os_load_address
stream_decompression
decompression_algorithm
os_load_address/ramdisk_load_address or load_address
stream_validation
decompression_algorithm
See the Example Native OS Partition Configuration chapter in the NVIDIA DRIVE OS 5.1 Linux PDK Development Guide for an example that uses the imagepath and dirname partition attributes.
The flashing script invokes Flashing tools to perform actions for specific partitions.
For the dirname partition attribute:
Flashing tool creates the file system image based on filesystem_type partition attribute.
Bootburn then sends that image for writing to the media. This is the same as using the filename option in the configuration file.
The Flashing tools perform other actions.
For the imagepath and ramdisk_path partition attribute, the Flashing tool does the following:
Creates a compressed image based on the decompression_algorithm partition attributes.
Creates a final kernel image.
Managing Mass Storage Partitions in Virtualization
Virtualization enables managing independent partitions. It supports independent flashing, loading, and restarting of individual VM partitions.
You can enable this feature for individual partitions using the Partition Configuration Table (PCT) by setting a load_using_pl flag in your partition configuration.
If this flag is not enabled for a partition, then during the binding step all partition images are combined into a single bootable image with Hypervisor and other Foundation components. This image gets loaded into memory at once during system boot and reloading or rebooting such a partition at runtime is not possible.
Enabling the load_using_pl flag for a partition specifies that the system:
Stores partition images independently (boot loader, OS kernel, file system)
Enables independent flashing of partition images
Requires the Partition Loader to load and execute partition boot images
Enables partition restarting
Partition Loader
The Partition Loader is a special purpose boot loader image that is embedded into Hypervisor. During the boot process, Hypervisor:
1. Creates a VM container according to the PCT
2. Maps a Partition Loader image into guest OS memory space
3. Then passes control to it
Partition Loader is responsible for loading and starting guest OS boot images.
Note:
While being a part of the Hypervisor image, Partition Loader is executed in a context of a guest OS VM and can only access physical memory or storage devices that belong to the OS according to the PCT.
When a partition restarts after resetting partition state, Hypervisor passes control back to Partition Loader for subsequent reloading of Guest OS images.
Storage Layout
Independent partition flashing and loading requires special storage device layout configuration. Configuration information is part of PCT and is used by flashing tools to program partition images and Partition Loader to load the images during system boot or partition restart.
For CF v1, the storage layout is defined by the following 2 configuration files:
Global layout configuration file—defines partitions that are globally visible on all storage devices in the system, such as boot loader, Foundation image, and root file system images.
VM partition layout configuration file—defines storage partitions that are visible to individual VMs. It describes the locations of partition images (OS loader, OS kernel) and boot parameters, such as OS command line.
For CFG v2, the storage layout is defined by these configuration files:
Global layout configuration file: Defines partitions that are globally visible on all storage devices in the system and are common to both boot chains, such as BR BCT and MB1 boot loader.
Boot chain layout configuration file: Defines partitions that are globally visible on all storage devices in the system and belong to a particular boot chain (i.e. A or B), such as Foundation image, and root file system images.
VM partition storage layout configuration file: Defines storage partitions that are visible to individual VMs. This file describes the locations of partition images (OS loader, OS kernel) and boot parameters, such as OS command line.
The above storage layouts are defined using the NVIDIA Mass Storage configuration format.
For more information, see Partition Storage Layout Configuration Example.
To change the global layout
In the PCT directory, locate and edit the following file:
<global_storage.cfg>
Where <global_storage.cfg> is the name of the file referenced by the sub_config_file property in the virtual machine (VM) partition layout file. There are no requirements for naming VM partition layout files.
Examples
The PCT examples are available at:
<top>/drive-t186ref-foundation/virtualization/pct
The default configuration files for DRIVE OS Linux are as follows.
Global Storage Configuration File
Description
Dual Linux setup
/linux-linux/global_storage.cfg
First Linux partition storage configuration
/linux-linux/guest1_storage.cfg
Second Linux partition storage configuration
/linux-linux/guest2_storage.cfg