Version Checker#

NVIDIA DriveOS™ Linux contains software components with packages installed. The NVIDIA DriveOS™ Devkit hardware includes modules with firmware flashed. The version checker tool provided ensures correctness and checks of software components and the flashed firmware. 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 the following:

  • Passing board information

  • Logging

  • Filtering output messages to the shell (standard output and /dev/console)

  • Iteratively executing the leaf node version checkers

  • Handling lower-layer erros

The version checker tool is modeled based on a tree with a root node version checker, which is 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 executes different leaf node modules as follows:

  • 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 to check the version using the leaf node version checker are as follows:

  • 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 (a 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 execute one time on the target before running. Ensure that you have completed the target-side setup and 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:

Run the following steps on any filesystem except prod_nsr_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.

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

    • 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

  1. Run with custom log file path < log_file> and same input config from step 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>

  1. Run with default log file path (/var/log/version_checker.log) and same input config from step 1 in verbose mode.

    • 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 DriveOS LINUX SDK.

  • Path of DriveOS 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"

  1. Example type=firmware :

sdk_version: "<release>-<GCID>"
type: "firmware"
firmware:
  name: "Eth Switch 88Q5152 on Ferrix"
  tool: "/bin/bash -c '/lib/firmware/marvell_ethernet/driveota/P3960_88Q5152.sh --GetCurrentVersion'"
  firmware_versions: # <list of dicts>
    - compatible_boards: ["940-63960-0010-000", "940-63960-0012-000", "940-63960-0010-001", "940-63960-0012-001","940-63960-0010-002", "940-63960-0012-002"] #P3960
      firmware_version: ["0004.07007.0009.01"]

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 "Eth Switch 88Q5152 on Ferrix", expected ['004.07007.0009.01'] but found 004.07007.0009.02. ***
*** Error version check for firmware "Eth Switch 88Q5152 on Ferrix". ***

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

===============================
ROOT VERSION CHECKER
===============================
Invoking python3 /usr/sbin/version_checker_leaf.py -i /lib/firmware/ethernet/ethernet_firmware_1.yml -b 940-63960-0010-000

Start checking version of "Eth Switch 88Q5152 on Ferrix".
Invoking /bin/bash -c '/lib/firmware/marvell_ethernet/driveota/P3960_88Q5152.sh --GetCurrentVersion'

*** Version mismatch on firmware "Eth Switch 88Q5152 on Ferrix", expected ['004.07007.0009.01'] but found 004.07007.0009.02. ***
*** Error version check for firmware "Eth Switch 88Q5152 on Ferrix". ***
Finished checking version of "Eth Switch 88Q5152 on Ferrix".

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 (for example 5.2.6.0, 6.0.0.0, and so on)

Yes

“sdk_version” : “”

Add SDK release version info, which must match the value on file in sdk_manifest.

sdk_manifest

str

Path of the file containing SDK version.

Yes

“sdk_version” :

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: }

Yes

“versions” : ; dict is version:

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”]

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” : “”

Add SDK release version info, which must match the value on file in sdk_manifest.

type

str

Type of config, either “debian” or “firmware”.

Yes

“type”:

Add of config which is “debian or”firmware”.

name

str

Name of the version entry.

Yes

“name” : “”

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” : “”

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”: , “firmware_version”: }

Yes

“firmware_versions” :

Add the firmware definition listing under this field.

comptabile_boards

list(str)

Contains a list of board-ids.

Yes

“compatible_boards” : <“board1”, board2”, ..>

Add all supported board_ids containing this firmware.

firmware_version

list(str)

Contains a list of firmware versions.

Yes

“firmware_version” : <“ver1”, “ver2”, ..>

Add all possible firmware versions corresponding to a compatible board.

filesystem_packages

dict(dict)

Contains a dict describing filesystem attributes

Yes

“filesystem_packages” :

Add dict of filesystem attributes to this field.

manifest

str

A string containing the path of the RFS debian manifest.

Yes

“manifest” :

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, refer to the following steps.

  1. cd ${NV_WORKSPACE}/drive-linux/filesystem/contents/bin

  2. pydoc3 -w ./

  3. Open the generated version_checker_leaf.html and version_checker_root.html on your browser.

On this page