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 two TAR files:
bringup_tests_R35.5.0_aarch64.tbz2 and
bringup_framework_R35.5.0_aarch64.tbz2

The bringup_tests_R35.5.0_aarch64.tbz2 archive contains test applications and
scripts that run on the target to validate different hardware components of the
developer kit. The bringup_framework_R35.5.0_aarch64.tbz2 archive contains the
testing framework, including one top-level script used to execute all test
modules based on user-provided input parameters.


------- 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_R35.5.0_aarch64.tbz2 and
bringup_tests_R35.5.0_aarch64.tbz2.

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

cd "${HOME}"
tar xpf bringup_framework_R35.5.0_aarch64.tbz2
tar -xpf bringup_tests_R35.5.0_aarch64.tbz2 -C /

The extracted ${HOME}/bringup folder, which comes from extracting the
bringup_framework_R35.5.0_aarch64.tbz2, has the following file hierarchy as
described in the notes following the structure diagram:

00. bringup/
01. |-bringup.sh
02. |-<modulename>/
03.   |-bringup_<modulename>.sh
04.   |-bringup_<modulename>_<socname1>.sh
05.   |-bringup_<modulename>_<socname2>.sh
06.   |- etc.

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 bringup_<modulename>.sh which
    runs generic tests for the module. The bringup_<modulename>.sh can then call
    bringup_<modulename>_<soc>.sh, which run tests specific to that SoC.
02) A module directory.
03) A Script that controls flow of tests in the module subdirectory.
    This script may contain functions that tests functionality for all boards,
    independent of model or SoC. This script also calls any other scripts in the
    same directory that match the board or SoC of the host environment.
04) An SoC-specific test script example.
05) A second SoC-specific test script example.
06) Other SoC-specific test scripts.

4. Add the tests, which were extracted from the
bringup_tests_R35.5.0_aarch64.tbz2 in step #3, to your PATH variable with the
following command:
export PATH="${PATH}":/opt/nvidia/bringup_framework/bringup_tests

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

cd $HOME/bringup/
./bringup_sh --print-dependencies

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.

6. Some modules (Ex. rtc, wdt) reboots the system. There are restrictions to
test these modules:
Always run them individually.
Always run before qspi module is tested.

You are now ready to run the bringup framework.

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

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

cd "${HOME}"/bringup/
./bringup.sh

This script checks the kernel version running on the platform. Based on the
kernel version, test scripts include module_common_<KERNEL_VERSION>.conf which
is present in the bringup_tests folder. If the .conf file is missing, that will
abort the test. module_common_<KERNEL_VERSION>.conf contains the module-based
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 this script calls scripts for all available test modules in
sub-directories in automated mode, which excludes tests that require user input,
or those specific to a SoC (unless specified). To run test modules specific to
your SoC, please specify the SoC for that platform using the --SoC flag. To run
in interactive mode, which runs all automated tests and tests requiring user
input, use the --interactive flag.

If for example there was a test module named "cpu", there would be a script
named bringup_cpu.sh inside ${HOME}/bringup/cpu. This script would
be in charge of executing the actual test scripts, such as
"/opt/nvidia/bringup_framework/bringup_tests/cputest_one.sh". Since the
"/opt/nvidia/bringup_framework/bringup_tests" folder has been exported to PATH,
the cputest_one.sh script can be executed directly by name.

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

-i|--interactive: Runs in interactive mode, can prompt the user for input.
-m|--module : Specifies the name of the module to test.
-s|--soc : Specifies the name of a particular SoC.
-h|--help : Show this help information.
<TODO: have an option to skip modules>

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

./bringup.sh -m "cpu"

To test the CPU and GPU for a specific SoC (T210) (jetson-tx1) in
interactive mode, use the following command:

./bringup.sh -i -m "cpu gpu" -s t210

------- How to run rtc/wdt Module ------

To test rtc/wdt module, follow below command sequence:
cd "${HOME}"/bringup/
export PATH="${PATH}":/opt/nvidia/bringup_framework/bringup_tests
./bringup.sh -m rtc or ./bringup.sh -m wdt

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

The bringup script determines module names from the sub-directory names.
It then uses the module name to determine the correct test script file
in that directory to execute.

For example, a new test module named "cpu" would be created as the directory
"bringup/cpu". Inside the cpu directory, the module's bringup test
script must be named after the module being used, for example in this case,
"bringup_cpu.sh", which is required to match the directory name. If there are
SoC-specific tests for the new test module, you must create a new script named
"bringup_cpu_<socname>.sh".


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

Two arrays are defined at the beginning of a test script such as bringup_cpu.sh,
TESTS and INTERACTIVE_TESTS.
These are names of the actual test scripts in the
"/opt/nvidia/bringup_framework/bringup_tests" folder.
The former are automated tests and the latter are interactive tests. To add new
tests, you need to write the test case script, and add its name to one of the
two arrays. The test script should be placed in the "bringup_tests" folder.

Refer to existing test modules for example of how to add new test module and
new test scripts.

Examples for adding tests:

*** To test functionality for automatic decoding, add the script to
    "/opt/nvidia/bringup_framework/bringup_tests/decoding/", and add its name to
    the TESTS array defined in bringup/decode/bringup_decode.sh.

*** To test functionality for audio on Tegra K1 mode,
    add the test script to "/opt/nvidia/bringup_framework/bringup_tests/audio/",
    and add its name to the TESTS array defined in
    bringup/audio/bringup_audio_t124.sh

*** To test functionality for camera on Tegra K1 that requires user
    input, add the script to
    "/opt/nvidia/bringup_framework/bringup_tests/camera/", and add its name to
    the INTERACTIVE_TESTS array defined in
    bringup/camera/bringup_camera_t124.sh.


-------- How to Add/Update a Kernel Based .Conf file -------

1) If a new test is added, add all hardcodings of test script in
module_common_<KERNEL_VERSION>.conf under the < module > specific to that test.
*** Note that the files use variable names based on module_soc_.. to
differentiate them from other SOC modules, as the .conf file is common for all
modules and is sourced by all test scripts present in bringup_tests.

Example: For module cpu, a new test <cpu_new_test.sh> is added. All hardcodings
must be present in the < cpu > module in the .conf file. Reference module_common
_<KERNEL_VERSION>.conf in cpu_new_test.sh script like this:
KERNEL_VERSION=$(uname -r | cut -d '.' -f-2)
source "${SCRIPT_DIRECTORY}"/module_common_"${KERNEL_VERSION}".conf

2) If a new module is added, add the module test scripts hardcodings at the end
of module_common_<KERNEL_VERSION>.conf with the same structure as other modules
being added.

Example: If module display is to be added, add it like below at the end of .conf
file:
############ < DISPLAY > ########################
.... all hardcodings should be added here ...

3) If a new Kernel version is available, add a new conf file in the
bringup_tests folder in the same format with the name
module_common_<NEW_KERNEL_VERSION>.conf

4) If a new SOC/PLATFORM is to be added, add hardcodings for all of the modules
being tested for the new SOC/PLATFORM and update get_board_soc/get_platform()
in the .conf file.

------------------- Test Result ----------------------
Test results get saved in stat.txt in bringup directory.
Test logs get saved in log.txt in bringup directory.

There is a separate file where rtc/wdt test logs with results get saved.
rtc_log.txt and wdt_log.txt in bringup directory.
