Tegra Bringup Test Framework
-------------------------------------------------


------- Introduction -------

The bringup test framework includes an entry point and pre-written test scripts
which are called automatically by the framework for verifying different hardware
components of the Jetson Developer Kit. This readme file explains how to set up
the test framework and run individual or multiple tests in automatic or
interactive mode. It also explains how new tests can be added to the test
framework.

The test framework consists of a single TAR file:
bringup_framework_.tbz2

------- Preparation -------

1. Flash the developer kit with the latest release of the NVIDIA® Tegra® Linux
Driver Package for your developer board, following the instructions given in
the Linux for Tegra (L4T) user documentation.

2. Boot the developer kit, log in using "sudo su", and download the following
files to the $HOME directory (the remainder of the steps in this document assume
this location): bringup_framework_.tbz2.

3. Extract the TAR files to the ${HOME} directory with the following commands:

cd "${HOME}"
tar -xpf bringup_framework_.tbz2

The extracted ${HOME}/nv_bringup folder has the following file hierarchy:

00. nv_bringup/
01. |-nv_bringup.sh
02. |-nv_bringup_config.sh
03. |-supported-kernel/
04.   |-kernel_<version>.conf
05. |-supported-platforms/
06.   |-<board>.conf
07.   |-cvm/
08.     |-<cmv>.conf
09.   |-cvb/
10.     |-<cvb>.conf
11. |-tests/<modulename>/
12.     |-nv_bringup_<modulename>.sh
13.     |-<test>.sh

00) The top-level directory that holds the bringup.sh script and module
    sub-directories.
01) The top-level bringup script that executes the bringup tests found in any
    module subdirectories. This script calls nv_bringup_<modulename>.sh which
    runs generic tests for the module.
02) A script that configures the test environment. This file is sourced by
    nv_bringup.sh. The script sources configuration files in the <board>.conf
    to set environment variables for the test framework.
03) Directory containing kernel-specific configuration files.
04) Kernel-specific configuration file. Kernel version is determined automatically
    at runtime.
05) Directory containing platform-specific configuration files.
06) Platform-specific configuration file. Platform is selected by providing -b
    flag to nv_bringup.sh. This file contains platform_configs and test_modules array.
    The first one specifies what configuration file to use for the platform while
    the latter specifies the test modules to run for the platform.
07) Directory containing CVM-specific configuration files.
08) CVM-specific configuration file.
09) Directory containing CVB-specific configuration files.
10) CVB-specific configuration file.
11) Directory containing test module descriptions and test scripts.
12) Description of the test module. Specifies what test and for what platforms to run
    in this module.
13) Test script for the test module. This script is executed by nv_bringup.sh.

4. Some test modules rely on external commands and applications, which need to
be installed as prerequisites. Run nv_bringup.sh to determine test dependencies
with the following command:

cd $HOME/nv_bringup/
./nv_bringup.sh --print-dependency

Use apt-get to download and install the missing dependencies in the rootfs, and
follow the instructions provided to download or build other prerequisites. If
neccessary, gather other hardware devices required to run the testing and follow
instructions provided.

You are now ready to run the bringup framework.

------- How to Run Tests -------

To run tests using the bringup test framework, run nv_bringup.sh with the following
commands:

cd "${HOME}"/nv_bringup/
sudo ./nv_bringup.sh -b <board_name>

This script checks the kernel version running on the platform. Based on the
kernel version, test scripts include kernel_<version>.conf which is present in
the supported_kernel folder. If the .conf file is missing, the the testing is
aborted. kernel_<version>.conf contains the kernel version specific hardcoded
sysfs_nodes/data/functions. Please follow the instructions in "How to Add/Update
Kernel Based Conf file" at the end in this README file.

By default bringup framework will execute all tests for all modules specified in
test_modules array in <board>.conf file. To run a specific test module, use the
-m|--module flag.

If for example there was a test module named "cpu", there would be a script
named nv_bringup_cpu.sh inside ${HOME}/nv_bringup/tests/cpu. This script defines platform
specific TESTS array. This array contains all tests script applicable to the
given module, for example "cputest_one.sh" that should be present in the
nv_bringup/cpu directory. Once the TESTS array is defined, nv_bringup.sh will execute
all tests in the array.

The following optional parameters can be specified to customize the test:

-m|--module : Specifies the name of the module to test.
-h|--help : Show this help information.

For example, to test an individual test module "cpu", provide the module name
to the --module flag as shown in the following command:

./nv_bringup.sh -m cpu -b jetson-agx-thor-devkit

To test multiple modules, provide a space separated list of module names to the
-m|--module flag.

./nv_bringup.sh -m "cpu gpu" -b jetson-agx-thor-devkit

------- How to Add New Test Modules -------

The bringup script identifies available test modules by scanning the
subdirectories within the "tests" directory. Each subdirectory name is treated
as a module name. For each module, the script expects to find a corresponding
bringup test script inside that module's directory. The naming convention
requires the script to be named "nv_bringup_<module_name>.sh" (for example,
"nv_bringup_cpu.sh" for the "cpu" module inside "nv_bringup/tests/cpu/").

Any SoC specific logic for the module should be implemented within this bringup
script. The bringup script will execute the nv_bringup_<module_name>.sh script
for each module specified in the -m|--module flag but only if the module is
present in the test_modules array in the <board>.conf file.

-------- How to Add New Tests --------

After adding appropriate test scripts to the test module, update the TESTS array
in the nv_bringup_<modulename>.sh script.

Example:

TESTS=(
    "cputest_one.sh"
    "cputest_two.sh"
)

All tests used by the bringup framework should accept one and only argument:
--print-dependency. This argument is used to print the dependency of the test.

Example:

cputest_one.sh --print-dependency

All test specific values should be expected to be provided as environment variables.
Such environment variables should be defined in the kernel_<version>.conf file,
cvm_<part_number>.conf file, cvb_<part_number>.conf file or other appropriate
configuration file.

Example:

USB_DEVICE="sda" in cvb_<part_number>.conf file.

-------- How to Add New Platforms --------

To add a new platform, follow the following steps:
1. Create new kernel specific configuration file in the nv_bringup/supported-kernel
2. Create new CVM configuration file in the nv_bringup/supported-platforms/cvm/
3. Create new CVB configuration file in the nv_bringup/supported-platforms/cvb/
4. Create new platform configuration file in the nv_bringup/supported-platforms/

1.  To add a new kernel version, create a new config file in the
    nv_bringup/supported-kernel directory. The file name should be the same as the
    kernel version. Add kernel specific sysfs_nodes/data/functions to the file.
    These variables are made available to the test environment during runtime.

    Example: nv_bringup/supported-kernel/kernel_6.16.conf

2.  To add a new CVM, create a new config file in the
    nv_bringup/supported-platforms/cvm/ directory. The file name should start with
    "cvm_". Add CVM specific sysfs_nodes/data/functions to the file. These
    variables are made available to the test environment during runtime.

    Example: nv_bringup/supported-platforms/cvm/cvm_3834-0008.conf

3.  To add a new CVB, create a new config file in the
    nv_bringup/supported-platforms/cvb/ directory. The file name should start with
    "cvb_". Add CVB specific sysfs_nodes/data/functions to the file. These
    variables are made available to the test environment during runtime.

    Example: nv_bringup/supported-platforms/cvb/cvb_4071-0000.conf

4.  Create new platform configuration file in the nv_bringup/supported-platforms/
    directory. The file name should be the same as the platform name.

    Example: nv_bringup/supported-platforms/<board_name>.conf

    The config file should contain the following variables:

    platform_configs:
        An array of platform configuration files to source when setting up the
        environment. It is expected that the user provides configuration file for
        each part of the platform such as SoM (CVM) and carrier board (CVB).
        Currently, files starting with "cvm_" or "cvb_" are supported.

        Note: do not prepend directory name to the configuration files passed in
        the platform_configs array.

    test_modules:
        The name of the test modules to run for the platform.

    Example:

    platform_configs=("cvm_3834-0008.conf" "cvb_4071-0000.conf")
    test_modules=("cpu" "gpu" "emmc")

After completing the above steps, the bringup framework can be used to test newly
added platform by running the following command:

    ./nv_bringup.sh -b "<board_name>"

------------------- Test Result ----------------------

Test results get saved in stat.txt in bringup directory.
Module logs get saved in <module>_tests.log in nv_bringup/logs directory.
