Version Checker

NVIDIA? DRIVE OS Linux contains many software components with packages installed. The NVIDIA Orin Devkit hardware includes many modules having firmware flashed. We provide the version checker tool to ensure correctness/checks of software components and the flashed firmwares. This tool provides a holistic way to check a list of firmware or filesystem packages using a data-driven approach. The version checker is divided into the frontend root node and the backend leaf nodes. The root node version checker manages passing board info, logging, filters output messages to the shell (standard output & /dev/console), iteratively executes the leaf node version checkers, and manages lower-layers errors. The version checker tool is modeled based on a tree with root node version checker responsible for all leaf node version checkers. The root node version checker uses root node config, and each leaf node version checker uses the respective leaf node config, both of which use the YAML format.

The root node version checker does the following to execute different leaf node modules:

  • Root node version checker reads root node config, obtains board-id, and makes the list of leaf node instances to call.
  • For each leaf node firmware, root node version checker passes board-id, calls leaf version checker with, and passes leaf node config.
The steps used to check the version using the leaf node version checker are the following:
  • If Leaf node config uses type=debian then:
    • Leaf node version checker gets the expected manifest of package versions from the config.
    • Leaf node version checker uses dpkg-query (reference Tool for debian packages) to get the packages and their versions in the filesystem.
    • Leaf node version checker then tallies manifest packages to filesystem packages and where packages tally, compares versions of packages.
    • Leaf node version checker depending on MATCH/MISMATCH, prints the PASS/FAIL result.
  • If Leaf node config uses type=firmware, then:
    • Leaf node version checker gets the expected firmware version based on the config file.
    • Leaf node version checker uses the Tool attribute and executes the command to fetch firmware version from the board.
    • Leaf node version checker compares expected firmware version to obtained firmware version and prints the PASS/FAIL result.

Version Checker Prerequisites

Version checker requires the following setup commands to be executed one time on the target before running it. Ensure that you have completed the target-side setup and have logged in using your username and password in the minicom console.
  1. Version checker in the default configuration prints all output to standard output and prints just error messages to /dev/console.
  2. Run the version checker application as shown in the command line below.
Notes specific to different filesystems:
  • Filesystems driveos-oobe-rfs and driveos-oobe-desktop-rfs:
    1. Using the preinstalled ssh server, connect from host to target using the ssh shell.
    2. Run the version checker in the ssh shell.
    3. The version checker prints to standard output shall be seen in the current shell, and the prints to /dev/console should be seen in the minicom console.
  • Filesystem driveos-core-rfs:
    1. In this filesystem, the ssh server package is not preinstalled, so it is not possible to start an ssh shell from the host to the target is possible.
    2. Use the minicom console to run the version checker.
    3. The version checker will print messages from standard output and /dev/console to the minicom console.

Version Checker Command Line

Version checker is always executed using the root version checker and uses the following command-line as shown below.
usage: version_checker_root.py [-h] [-i YAML_PATH] [-l LOGFILE_PATH] [-v]
Checks all system firmwares.
  -h, --help            show this help message and exit
  -i YAML_PATH, --input-yaml YAML_PATH
                        Input YAML config file.
  -l LOGFILE_PATH, --log-file-path LOGFILE_PATH
                        Optional Argument: Log file path. Default path is /var/log/version_checker.log.
  -v, --verbose         Optional Argument: Verbose logging i.e., print info/debug messages to /dev/console.

Examples running version_checker_root.pyapplication:

  1. Run with default log file path (/var/log/version_checker.log) and input config /etc/nvidia/version_checker/manifest/version_data_root.yml
    1. Prints info messages to standard output, log file, and only errors to /dev/console.
      version_checker_root.py -i /etc/nvidia/version_checker/manifest/version_data_root.yml
  2. Run with custom log file path <log_file> and same input config from step 1.
    1. Prints info messages to standard output, log file, and only errors to /dev/console.
      version_checker_root.py -i /etc/nvidia/version_checker/manifest/version_data_root.yml -l <log_file>
  3. Run with default log file path (/var/log/version_checker.log) and same input config from step 1 in verbose mode.
    1. Prints info messages to standard output, to log file, and to /dev/console.
      version_checker_root.py -i /etc/nvidia/version_checker/manifest/version_data_root.yml -v

Config Files

The root node config contains the following fields per child node:
  • Path to child node version checker.
  • Config file of child node version checker.
  • The version of DRIVE OS LINUX SDK.
  • Path of DRIVE OS LINUX SDK manifest.
Leaf node config contains the following fields:
  • Name of the module like filesystem or firmware.
  • Type of the module: debian or firmware.
  • For type=firmware, we have:
    • The firmware version flashed on board.
    • Firmware version list corresponding to board.
    • List of compatible boards (i.e., boards containing the firmware and has its version retrievable) corresponding to the firmware.
  • For type=debian we have:
    • Tool to fetch package versions in the filesystem.
    • Path of filesystem manifest.

The below examples provide a root node config and a leaf node config.

Root node config:
sdk_version: "<release>-<GCID>"
sdk_manifest: "/etc/nvidia/version-ubuntu-rootfs.txt"
versions:
  - versions: ["/usr/sbin/version_checker_leaf.py", "/etc/nvidia/version_checker/manifest/rootfs_debians.yml"]
  - versions: ["/usr/sbin/version_checker_leaf.py", "/etc/nvidia/version_checker/manifest/ethernet_firmware_1.yml"]
Leaf node config:
  1. Example with type=debian:
    sdk_version: "<release>-<GCID>"
type: "debian"
filesystem_packages:
  name: "Filesystem debian packages"
  tool: "dpkg-query -W -f '${Package}=${Version}\\n'"
  manifest: "/etc/nvidia/rootfilesystem-manifest/driveos-rfs.MANIFEST.json"
  2. Example type=firmware:
    sdk_version: "<release>-<GCID>"
type: "firmware"
firmware:
  name: "8 Port 100Mb Ethernet Switch"
  tool: "/bin/bash -c '/lib/firmware/marvell_ethernet/common/ota/linux/nvidia/update-firmware.sh --printversion | grep \"Current firmware version flashed is\" | cut -d\" \" -f7'"
  firmware_versions: # <list of dicts>
    - compatible_boards: [ "e3550_t194b", "e3550_t194a" ]
      firmware_version: ["02.07.1001"]

Output Messages and Logging

The version checker has the following structure for outputting messages into standard output, minicom console, and the (persistent) log file. The minicom console output messages appear only if an error occurs. The standard output and the log file contain informational messages to help users understand or debug tool/config files. The verbose ensures that all of the minicom console, standard output, and log files contain all the informational messages.

Sample /dev/console output on an error:

*** Version mismatch on firmware "8 Port 100Mb Ethernet Switch", expected ['02.07.1000'] but found 02.07.1001. ***
*** Error version check for firmware "8 Port 100Mb Ethernet Switch". ***
*** Version mismatch on firmware "8 Port 100Mb Ethernet Switch - Secure Keys", expected ['02.07.1000'] but found 02.07.1001. ***
*** Error version check for firmware "8 Port 100Mb Ethernet Switch - Secure Keys". ***

Sample standard output as well as log file content /dev/console output on an error:

===============================
ROOT VERSION CHECKER
===============================
Invoking python3 /lib/firmware/version_checker_leaf.py -i /lib/firmware/ethernet/ethernet_firmware_1.yml -b e3550_t194a

Start checking version of "8 Port 100Mb Ethernet Switch".
Invoking /bin/bash -c '/lib/firmware/marvell_ethernet/common/ota/linux/nvidia/update-firmware.sh --printversion | grep "Current firmware version flashed is" | cut -d" " -f7'

*** Version mismatch on firmware "8 Port 100Mb Ethernet Switch", expected ['02.07.1000'] but found 02.07.1001. ***
*** Error version check for firmware "8 Port 100Mb Ethernet Switch". ***
Finished checking version of "8 Port 100Mb Ethernet Switch".

Invoking python3 /lib/firmware/version_checker_leaf.py -i /lib/firmware/ethernet/ethernet_firmware_2.yml -b e3550_t194a

Start checking version of "8 Port 100Mb Ethernet Switch - Secure Keys".
Invoking /bin/bash -c '/lib/firmware/marvell_ethernet/common/ota/linux/nvidia/update-firmware.sh --printversion | grep "Current firmware version flashed is" | cut -d" " -f7'

*** Version mismatch on firmware "8 Port 100Mb Ethernet Switch - Secure Keys", expected ['02.07.1000'] but found 02.07.1001. ***
*** Error version check for firmware "8 Port 100Mb Ethernet Switch - Secure Keys". ***
Finished checking version of "8 Port 100Mb Ethernet Switch - Secure Keys".

Version Checker API Documentation

The version checker supports the following semantics below for each root node and leaf node version checker.

Root version checker semantics:
Field Type Acceptable Values Required Syntax Instructions
sdk_version str SDK version in form of A.B.C.D (like 5.2.6.0, 6.0.0.0, etc.) Yes "sdk_version" : "<sdk_ver_num>" Please add SDK release version info and must match the value on file in sdk_manifest.
sdk_manifest str Path of the file containing SDK version. Yes "sdk_version": <file path having sdk version> Please add the path of the file containing the SDK version to the value of key sdk_version.
versions list(dict)

Contains the list dictionaries in the form,

{version: <version data>}

 Yes "versions" : <list of dict>; dict is version: <version data> Please add a list of version entries under the version key.
version list(str) 2 element list of strings ["leaf checker", "leaf config"] Yes "version" : ["leaf checker", "leaf config"] Please add <path_to_firmware_checker, path_to_firmware_data> in the list for each.

Leaf version checker semantics:

Field Type Acceptable Values Required Syntax Instructions
sdk_version str SDK version in form of A.B.C.D (like 5.2.6.0, 6.0.0.0, etc.) Yes "sdk_version" : "<sdk_ver_num>" Please add SDK release version info and must match the value on file in sdk_manifest.
type str Type of config, either "debian" or "firmware". Yes "type": <type> Please add <type> of config which is "debian or "firmware".
name str Name of the version entry. Yes "name" : "<version entry name>" Please add the full name of the version entry in this field. This can be any user-defined name.
tool str Command-line tool to query existing version from the system. Yes "tool" : "<cmdline to query version>" Please add the full cmdline, including the path to the low-level utility to fetch the version of the component with arguments.
firmware_versions list(dict) Contains the list of dict in the form, {"compatible_boards": <value>, "firmware_version": <value>} Yes "firmware_versions" : <list of dicts> Please add the firmware definition listing under this field.
comptabile_boards list(str) Contains a list of board-ids. Yes "compatible_boards": <"board1", board2", ..> Please add all supported board_ids containing this firmware.
firmware_version list(str) Contains a list of firmware versions. Yes "firmware_version": <"ver1", "ver2", ..> Please add all possible firmware versions corresponding to a compatible board.
filesystem_packages dict(dict) Contains a dict describing filesystem attributes Yes "filesystem_packages": <fs_dict> Please add dict of filesystem attributes to this field.
manifest str A string containing the path of the RFS debian manifest. Yes "manifest": <path> Please add the path of the RFS debian manifest to this field.

Version Checker Developer API Documentation

Version checker tools are implemented in python3 and contains python3 compatible documentation within code. To open the documentation, please use the steps below.

  1. cd <top>/drive-linux/filesystem/contents/bin
  2. pydoc3 -w ./
  3. Open the generated version_checker_leaf.html and version_checker_root.html on your browser.