Linux Filesystems
NVIDIA DRIVE OS LINUX consists of multiple hierarchy filesystems. Each layer of the hierarchy of filesystems is assigned a purpose and the particular purpose at that layer defines the contents of the filesystem.
The Filesystem Hierarchy Pyramid image below shows a pyramid representing the hierarchy of filesystems. Each layer builds on top of the layers below it. The pyramid is not proportional; therefore, the width or area of each layer of the pyramid does not necessary represent the about of content at that specific layered filesystem.
At the very bottom of the hierarchy, the base layer is Canonical Ubuntu Base Filesystem. This is a filesystem from Canonical and is not changed but is required to be the initial based filesystem to be built on top of.
The next layer is named driveos-core-rfs and is purposed to contain automotive specific Debian packages as well as drivers, libraries, tools, firmwares, scripts, and any other necessary files for core functionality. This filesystem is normally given to and used for production systems.
The final layer is named driveos-oobe-rfs and is an Out Of Box Experience for developers. It contains automotive specific samples, documentations, and developer friendly tools. This filesystem is intended to be used by developers for developers.
The itemized listing of Debian packages in DRIVE OS LINUX filesystems is available in an end-user friendly descriptive version within the filesystem path (depending on driveos-oobe-rfs or driveos-core-rfs) below:
• /etc/nvidia/rootfilesystem-manifest/driveos-oobe-rfs.manifest
• /etc/nvidia/rootfilesystem-manifest/driveos-core-rfs.manifest
Additionally, the filesystems also contain a listing of all installed packages (useful for NVIDIA Build-Kit) at (depending on driveos-oobe-rfs or driveos-core-rfs)::
• /etc/nvidia/rootfilesystem-manifest/driveos-oobe-rfs.MANIFEST.json
• /etc/nvidia/rootfilesystem-manifest/driveos-core-rfs.MANIFEST.json
The filesystem source code packaged in drive-*-linux-*oss-src.run is built using the Debian package name and version from the above *.MANIFEST.json files, followed by executing the following command for each package to obtain its source and archiving them:
$ apt-get source <package>=<package_version>
Finally, the filesystem comprises of overlay files added on top of Debian packages from different modules like drivers, libraries, tools, firmware, scripts, and samples. The set of modules is included in driveos-core-rfs and driveos-oobe-rfs. The itemized listing is available in the CopyTarget chapter.
NVIDIA Linux Filesystems
There are two files that can be downloaded for each particular filesystem but only one download is necessary. The default file to download is listed in the column "Which File to Download" of the table "Table of Filesystems" but an alternative file can be downloaded as well, and this alternative file is listed in the column "Alternative File to Download".
The alternative file is not mandatory but is specified in the table because the installation steps differ. For more information, see Installing the Filesystem from Debian.
Filesystem | Which File to Download | Purpose | Alternative File to Download |
|---|---|---|---|
driveos-oobe-rfs | drive-t186ref-linux-<release>-<DRIVEOS_GCID>-driveos-oobe-rfs.run | Intended to be used by developers as a development or reference filesystem. Contains NVIDIA automotive sample applications and corresponding documentations. | nvidia-driveos-<release>-driveos-oobe-rfs.deb |
driveos-core-rfs | drive-t186ref-linux-<release>-<DRIVEOS_GCID>-driveos-core-rfs.run | Intended to be used by production systems. Contains NVIDIA automotive drivers, libraries, tools, firmwares, scripts, and other required files for core functionality. | nvidia-driveos-<release>-driveos-core-rfs.deb |
Where <DRIVEOS_GCID> is the GCID of NVIDIA DRIVE OS Linux.
Installation
To install a downloaded filesystem, refer to the relevant section corresponding to the type of file downloaded.
If you downloaded the file with an extension .run, see sub section Installing Filesystem from Runfile.
If you downloaded the file with an extension .deb, see sub section Installing Filesystem from Debian.
For each subsection, ensure you execute the installation commands in a BASH terminal.
For a comparison between .run and .deb, see Filesystem Installation Differences Between Runfile and Debian.
Installing the Filesystem from Runfile
Execute the runfile, and the installer will extract the filesystem into a directory at the relative location drive-t186ref-linux/targetfs/. You can then proceed to use or flash the filesystem to the target platform.
# Change directory to location of the downloaded DRIVE OS LINUX; your downloaded LINUX filesystem Runfile must be in this location as well; if not, ensure that it is.
# For our purpose, we will assume DRIVE OS LINUX was downloaded into ~/nvidia/driveos/.
nvidia@nvidia:~$ cd ~/nvidia/driveos/
nvidia@nvidia:~/nvidia/driveos$ bash drive-t186ref-linux-<release>-<DRIVEOS_GCID>-driveos-oobe-rfs.run
# Filesystem is installed into the relative directory drive-t186ref-linux/targetfs/.
nvidia@nvidia:~/nvidia/driveos$ ls -l drive-t186ref-linux/targetfs/
Where <DRIVEOS_GCID> is the GCID of NVIDIA DRIVE OS Linux.
Installing the Filesystem from Debian
Install the filesystem Debian using apt and answer the questions at each prompt. The Debian installs a filesystem image.
The Debian contains an installation script that requests additional information. In particular, you must indicate the location of DRIVE OS Linux.
# Change directory to location of the downloaded LINUX filesystem Debian. For our purpose, we will assume the Debian was downloaded into ~/Downloads/ and DRIVE OS LINUX was installed at ~/nvidia/driveos/.
nvidia@nvidia:~$ cd ~/Downloads/
# Proceed to install the Debian and answer the questions at each prompt.
nvidia@nvidia:~/Downloads$ sudo apt install ./nvidia-driveos-<release>-<DRIVEOS_FILESYSTEM>.deb
Please specify location of installed DRIVE OS LINUX.
~/nvidia/driveos/
Installing image
Updating targetfs.img symlink
Where <DRIVEOS_FILESYSTEM> is the filesystem selected, which can be driveos-core-rfs or driveos-oobe-rfs.
Note: | By default, PCT does not pick up the Linux target filesystem image installed from the Debian; To update PCT configuration to use the installed image, execute use_rootfs_img.sh as specified in Using the targetfs.img file for Linux guest rootfs. |
Reinstalling the Filesystem from Debian
Rerun the dpkg reconfigure command to reinstall the filesystem to another DRIVE OS Linux location.
sudo dpkg-reconfigure nvidia-driveos-<release>-<DRIVEOS_FILESYSTEM>
Where <DRIVEOS_FILESYSTEM> is the filesystem selected, which can be driveos-core-rfs or driveos-oobe-rfs.
Uninstalling the Filesystem Image Debian
Open a BASH terminal and execute:
sudo apt-get purge nvidia-driveos-<release>-<DRIVEOS_FILESYSTEM>
Where <DRIVEOS_FILESYSTEM> is the filesystem selected, which can be driveos-core-rfs or driveos-oobe-rfs.
Filesystem Differences Between Runfile and Debian
There are two methods to install the filesystem. One of the installation methods involves executing a runfile and the other installation method involves installing a Debian using apt. Of the two methods, installing the filesystem through its runfile is the default workflow and the Debian installation is an alternative, optional method.
There are more subtle differences. Installing the filesystem from a runfile extracts the filesystem into a directory that is located at drive-t186ref-lnux/targetfs/, relative to the DRIVE OS Linux installation directory. On the other hand, installing filesystem from Debian extracts the filesystem image in the DRIVE OS Linux installation directory at the relative location drive-t186ref-lnux/targetfs-images/ and a symlink is created at drive-t186ref-linux/targetfs.img.
The table compares the two installation methods.
Runfile | Debian | |
|---|---|---|
Is directory created; if so, where? | Yes, drive-t186ref-linux/targetfs/. | No. |
Is image extracted; if so, where? | No. | Yes, drive-t186ref-linux/targetfs-images/<DRIVEOS_FILESYSTEM>.img. |
Is symlink created; if so, where and what does it point to? | No. | Yes. Created at drive-t186ref-linux/targetfs.img and points to drive-t186ref-linux/targetfs-images/<DRIVEOS_FILESYSTEM>.img. |
Where <DRIVEOS_FILESYSTEM> is the filesystem selected, which can be driveos-core-rfs or driveos-oobe-rfs.
Filesystem Manifest
Each filesystem is accompanied by a Filesystem Manifest. The manifest is located with the filesystem at /opt/nvidia/driveos/<release>/filesystems/<DRIVEOS_FILESYSTEM>/<DRIVEOS_FILESYSTEM>.MANIFEST.json and can be used to identify the information defined in the NVIDIA DRIVE OS Build-Kit config for generating the filesystem. For more information, see NVIDIA Build-Kit documentation.
Prompts During Installation of Filesystem
During installation of filesystem, certain criteria may trigger one or more interactive prompts for you to confirm or specify additional information. When prompts are issued, you must answer in order to continue.
There are silent install variables that allow non-interactive installation. These silent install variables are specified in the respective tables of each installation method and an explanation to use them is provided. Silent install variables are set as environment variables and if exposed to the installers, are used.
Prompts During Installation of Filesystem from Runfile
Interactive Prompt | Default | Trigger | Instructions | Silent Install Variable Bypass Criteria |
|---|---|---|---|---|
<DIRECTORY_PATH> folder not empty, do you wish to delete contents [Y/n] Where <DIRECTORY_PATH> is the absolute directory path where the installer is attempting to install filesystem to. | y (yes) | This prompt will be presented to the user to confirm if the following condition is met unless the silent install variable criteria has been set with the appropriate value. Destination directory <DIRECTORY_PATH> already exists but may or may not be empty. | This prompt is presented to prevent automated destruction of potential existing data. | _NV_NON_INTERACTIVE=yes |
Prompts During Installation of Filesystem from Debian
Interactive Prompt | Acceptable Input | Default | Trigger | Instructions | Silent Install Variable Bypass Criteria |
|---|---|---|---|---|---|
Please input NV_WORKSPACE path. NV_WORKSPACE: Path where DRIVEOS SDK is installed | Valid Unix directory path, ensure input is terminated with a trailing slash. | - | This prompt will be presented to the user to confirm if the following condition is met unless the silent install variable criteria has been set with the appropriate value. ${NV_WORKSPACE} is not defined in the environment. | This prompt is required to be answered to indicate to Debian installation script the location to create filesystem image. | NV_WORKSPACE=<DIRECTORY_PATH> Where <DIRECTORY_PATH> is the valid DRIVE OS LINUX installed directory; ensure this directory path ends with a slash "/". |
"<FILEPATH>" already exists, do you wish to replace the img [y/N] ? Where <FILEPATH> is the absolute filepath where the installer is attempting to install filesystem image to. | "y" - yes "n" - no | n (no) | This prompt will be presented to the user to confirm if the following condition is met unless the silent install variable criteria has been set with the appropriate value. File <FILEPATH> already exists. | This prompt is presented to prevent automated destruction of potential existing data. | _NV_OVERWRITE_IMAGE=yes Note: It is irrelevant whether ${NV_WORKSPACE} has been set or not because ${NV_WORKSPACE} will be set by prior prompt (above) if not already. |
"<SYMLINK_PATH>" symlink already exists, and points to "<SYMLINK_POINTED_PATH>", Do you wish to continue to update the symlink to currently installing rootfs [y/N]? Where: <SYMLINK_PATH> is the absolute symlink path which the installer is attempting to update. <SYMLINK_POINTED_PATH> is the location the existing symlink is pointing to currently. | "y" - yes "n" - no | n (no) | This prompt will be presented to the user to confirm if the following conditions are met unless the silent install variable criteria has been set with the appropriate value. Symlink <SYMLINK_PATH> already exists. | This prompt is presented to prevent automated destruction of potential existing data. | _NV_OVERWRITE_SYMLINK=yes |
Filesystems Reference
Filesystem | Filesystem Built On Top Of | Runfile | Debian | Image Format and Name | Manifest Location |
|---|---|---|---|---|---|
driveos-oobe-rfs | driveos-core-rfs | driveos-oobe-rfs.run | driveos-oobe-rfs.deb | ext4 driveos-oobe-rfs.img | /opt/nvidia/driveos/<release>/filesystems/driveos-oobe-rfs/driveos-oobe-rfs.MANIFEST.json |
driveos-core-rfs | ubuntu-base-18.04.1-base-arm64.tar.gz | driveos-core-rfs.run | driveos-core-rfs.deb | ext4 driveos-core-rfs.img | /opt/nvidia/driveos/<release>/filesystems/driveos-core-rfs/driveos-core-rfs.MANIFEST.json |
Debian Packages
This section describes the purpose of the Debian packages and how they are installed.
Debian packages are used as an easy way to safely install files, links, etc. Installation does not require any parameters. The Debian packages know about dependencies, and installation does not begin if required packages are not present. It contains version management so that you do not mistakenly install an older version of a package over a newer one.
Installation of Debian packages typically is performed via apt-get install issued from the target-system. Alternatively, the installation can be done using the dpkg –install command.
Debian Packages
The naming scheme of the NVIDIA DRIVE OS Debian package is nvidia-driveos-package-name_<DRIVEOS_RELEASE>.deb.
Currently, there are thirteen (13) Debian packages:
• Eleven (11) Debian packages contain files, links, etc.
nvidia-driveos-aurix_<DRIVEOS_RELEASE>.deb to install Aurix firmwares
nvidia-driveos-configs_<DRIVEOS_RELEASE>.deb to install configuration files
nvidia-driveos-firmware_<DRIVEOS_RELEASE>.deb to install firmwares
nvidia-driveos-headers_<DRIVEOS_RELEASE>.deb to install headers
nvidia-driveos-kernel-modules_<DRIVEOS_RELEASE>.deb to install the kernel-modules
nvidia-driveos-libraries_<DRIVEOS_RELEASE>.deb to install libraries
nvidia-driveos-others_<DRIVEOS_RELEASE>.deb to install miscellaneous files
nvidia-driveos-samples_<DRIVEOS_RELEASE>.deb to install general sample files
nvidia-driveos-security_<DRIVEOS_RELEASE>.deb to install security related files
nvidia-driveos-setup-rootfs_<DRIVEOS_RELEASE>.deb to install setup related files
nvidia-driveos-tools_<DRIVEOS_RELEASE>.deb to install tools
• Two (2) Debian packages only contain dependencies:
nvidia-driveos-core_<DRIVEOS_RELEASE>.deb depends on 10 of the above Debian packages but not on nvidia-driveos-samples_<DRIVEOS_RELEASE>.deb
nvidia-driveos-oobe_<DRIVEOS_RELEASE>.deb depends on nvidia-driveos-core_<DRIVEOS_RELEASE>.deb and nvidia-driveos-samples_<DRIVEOS_RELEASE>.deb
Usage of the Debian Packages
Debian packages are restricted to run only on systems/platforms they are built for (via the architecture setting in the Debian control file).
The installation of a Debian package must be issued from the system to be updated.
The installation location is always relative to the system's root directory.
There are two ways to install the packages:
1. Install local Debian packages using the sudo dpkg –install command.
The Debian packages are hierarchical with respect to dependencies and dpkg does not automatically install dependent packages. First, install the eleven (11) Debian packages that contain files (in any order).
Install nvidia-driveos-core_<DRIVEOS_RELEASE>.deb and nvidia-driveos_<DRIVEOS_RELEASE>.deb last.
Uninstallation of the Debian packages works in reverse order.
2. Use a Debian mirror to install the packages via sudo apt-get install <Debian Package Filename>. In this approach, network access must be functional.
sudo apt-get install automatically installs all dependent packages from a Debian mirror. Use either:
sudo apt-get install nvidia-driveos-core_<DRIVEOS_RELEASE>.deb to install all packages without the nvidia-driveos-samples_<DRIVEOS_RELEASE>.deb.
-OR-
sudo apt-get install nvidia-driveos_<DRIVEOS_RELEASE>.deb to install all Debian packages.
Note: | The following Debians customize some upstream Ubuntu files: • nvidia-driveos-configs_<DRIVEOS_RELEASE>-1.deb • nvidia-driveos-headers_<DRIVEOS_RELEASE>-1.deb • nvidia-driveos-security_<DRIVEOS_RELEASE>-1.deb To install these Debian files: • Add option --force-overwrite in the dpkg command line if using dpkg -i to install the Debian packages. • Add option -o Dpkg::Options::="--force-overwrite" if using apt/apt-get to install the Debian packages. |
Creation of Debian Packages from copytarget-*.yaml files
The packages' creation is part of the build process. The Debian packages contain the DRIVE OS release. The content of each Debian package is defined by a corresponding copytarget-package-name.yaml file. The same copytarget-package-name.yaml files are used for the host-based pre-installation of the target file system.
The Debian packages also can be created manually from within an PDK package.
Debian Packages
The naming scheme of the NVIDIA DRIV OS Debian package is nvidia-driveos-package-name_<DRIVEOS_RELEASE>.deb, as mentioned in the previous section. package-name also identifies the corresponding copytarget-package-name.yaml.
Currently the two (2) Debian packages that only contain dependencies do not have corresponding copytarget-package-name.yaml files as they do not contain any files.
Tools to create Debian Packages
The following describes the tools used to create Debian packages:
• generate_debian.py: A tool to create Debian packages.
• copytarget.py: A tool to read the copytarget-package-name.yaml and copy the files listed there to a defined location. generate_debian.py uses copytarget.py to create the Debian packages.
Locations of the Debian Packages
Debian packages are provided with drive-t186ref-linux-<DRIVEOS_RELEASE>-buildID-nv-minimal-sdk.run.
After unpacking this run-file, a directory structure is created. You can find the Debian package in:
./drive-t186ref-linux/target-images/debians/.
The tools to create Debian packages are located in:
./drive-t186ref-linux/utils/scripts/debian_helper_utilities/.
Any copytarget-package-name.yaml can be used to create Debian packages from within the PDK located at ./drive-t186ref-linux/utils/scripts/copytarget/manifest/.
The mandatory copytarget.py script is delivered as part of the nvidia-driveos-<DRIVEOS_RELEASE>-copytarget.deb.
Testing Debian Packages
The following describes content-test for each Debian package (either on the host or on the target system).
1. Select a directory where the packages are verified (here referenced as $test_base_dir).
2. Create a "fake"-admin directory to avoid messing up test installations with regular installations:
mkdir -p $test_base_dir/fakeroot/var/lib/dpkg/updates
mkdir -p $test_base_dir/fakeroot/var/lib/dpkg/info
touch $test_base_dir/fakeroot/var/lib/dpkg/status
Note: | nvidia-driveos-core_<DRIVEOS_RELEASE>.deb and nvidia-driveos_<DRIVEOS_RELEASE>.deb do not contain file only dependencies and do not have corresponding copytarget-*.yaml files. |
3. For each Debian package:
• Create a "fake"-root directory named package-name_root.
mkdir p $test_base_dir/package-name_root
• Install the Debian package into this $test_base_dir/package-name_root directory.
On the host:
sudo dpkg --force-architecture --admindir=$test_base_dir/fakeoot /var/lib/dpkg --instdir=$test_base_dir/package-name_root/ --force-depends --install absolute_path_of_debian_package
On target system:
sudo dpkg --admindir=$test_base_dir/fakeroot /var/lib/dpkg --instdir=$test_base_dir/package-name_root/ --force-depends --install absolute_path_of_debian_package
Test Debian Package Dependencies
This section describes Debian package dependency tests.
• sudo apt-get install based installation:
This test can only be done on the target system, as sudo apt-get install does not support install directories (besides root).
From the target system, run sudo apt-get install nvidia-driveos_<DRIVEOS_RELEASE>.deb. Check that all Debian packages are installed with dpkg –list.
• sudo apt-get remove nvidia-driveos uninstalls all packages.
Verify that all Debian packages were uninstalled with dpkg –list.
• sudo dpkg –install based installation:
This test can run on the host system in “fake” root environment.
Verify that the installation fails if the dependent Debian packages are missing:
• Install nvidia-driveos_<DRIVEOS_RELEASE>.deb:
sudo dpkg --force-architecture --admindir=$test_base_dir/fakeroot/var/lib/dpkg --instdir=$test_base_dir/package-name_root/ --force-depends --install absolute_path_of_debian_package
The dpkg returns with an error, listing any modules that must be installed first (in this case, all other Debian packages).
• Install all remaining Debian packages:
Install nvidia-driveos_<DRIVEOS_RELEASE>.deb.
The installation passes.
Test on target system
Install the Debian packages on a target system and run a test suite to check if the system works.
This is the last step in testing to make sure the packages actually work on the system. All other tests only check that the Debian packages contain the right content at the right location.
Create the Debian Packages from the PDK
generate_debian.py creates a Debian package from the copytarget-package-name.yaml.
1. Get an nvidia-driveos-<DRIVEOS_RELEASE>-copytarget.deb and install it:
sudo dpkg --install nvidia-driveos-<DRIVEOS_RELEASE>-copytarget.deb
2. Create a directory where the Debian package are created. Use an environment variable to hold that directory.
$DEB_OUTDIR=/home/user/debians/pdk_generated_debians/ (as an example)
3. Run ./ generate_debian.py with these required parameters:
• --package pkg-name
pkg-name is one out of ("configs", "firmware", "headers", "kernel-modules", "libraries", "others", "samples", "security", "setup-rootfs", "tools")
• --copytarget_path /home/user/scripts/copytarget.py
Path to where nvidia-driveos-<DRIVEOS_RELEASE>-copytarget.deb installs copytarget.py.
• --python_path ${P4ROOT}"/sw/embedded/external-prebuilt/python/351/bin/python3"
Absolute path to the python3 binary.
• --debian_path $DEB_OUTDIR
Location where the Debian package is created.
• --yaml_path /drive-t186ref-linux/utils/scripts/copytarget/manifest/
The absolute path, not including the filename.
• --version "5.2.3.0-1"
The version mustbe the DRIVE OS release, and is used for all dependency and package names.
• --sourcetype “pdk_sdk_installed_path”
• --workspace $abs_workspace_dir
$abs_workspace_dir=PDK-package-dir/
Optional parameter:
--verbose[0|1]