4. UATG CLI Commands¶

4.1. `uatg --help`¶

$ uatg --help
Usage: uatg [OPTIONS] COMMAND [ARGS]...

RISC-V µ-Architectural Test Generator (UATG)

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  clean         Removes ASM, SV and other generated files from the work...
  from-config   Reads config.ini and invokes uatg with read paramaters.
  generate      Generates tests, cover-groups for a list of modules...
  list-modules  Lists the micro-architecture modules of core supported
                among...
  setup         Creates template configuration files.
  validate      Parses the log generated upon test execution using regular...

This is the help section which describes all the subcommands present in the UATG framework. The description for all the subcommands are presented in the table.

Table 4.1 UATG Subcommands¶
Parameter	Description
clean	Subcommand to clean the files created duting test generation. Clean will clean up all files, including the tests.
from-config	Runs the UATG from the config.ini file which contains all the parameters required.
generate	Subcommand to generate tests based on the arguments passed along with this command.
list-modules	Subcommand to list all the DUT modules for which test classes are present.
setup	Subcommand to create template dut_config, aliasing as well as config file for the user to edit.
validate	Subcommand to run the check logs feature in UATG.

4.2. Common Options present in UATG Subcommands¶

The table that follows discusses about all the options present in the previously shown 6 subcommands of UATG.

The first column lists the option. The second column indicates which subcommands support said option. It is followed by the description in the third column.

Table 4.2 Common Options in UATG Subcommands¶
Option	UATG Subcommand	Required?	Description
-v, --verbose	generate, clean, validate, from-config, list-modules	Optional	The verbosity of the log generated by the tool.
-m, --modules	generate, validate	Required	The Modules of the DUT for which you wish to generate the tests. (will take multiple values)
-md, --module_dir	generate, clean, validate, list-modules	Required	Absolute/relative path to the directory where the user has saved the tests for all modules.
-wd, --work_dir	generate, clean, validate	Required	The workdir where all of the files, reports and logs are generated.
-ld, --linker_dir	generate,	Optional	The directory where the user has stored his `link.ld` file. If not specified, UATG will generate a linker at the work_dir.
-cfg, --configuration	generate, validate	Required	The absolute/relative path to the configuration_yaml file(s) of the DUT for which the user wants to generate tests. The yaml paths should be provided individually with a -cfg for every path and should be passed in the following order, 1. isa_config.yaml 2. core_config.yaml 3. custom_config.yaml 4. csr_grouping.yaml. 5. rv_debug.yaml (The names here represent the functionality of the and not the actual name required by UATG. The user can name his files as they wish.)
-af, --alias_file	generate	Required	The absolute/relative path to the `aliasing.yaml` file of the DUT for which the user wants to generate covergroups.
-t, --gen_test_list	generate	Optional	[Flag] Creates a `test_list.yaml` file in the `work_dir`.
-gc, --gen_cvg	generate	Optional	[Flag] When True, UATG will generate the covergroups for the tests.
–version	generate, clean, validate list-modules	Optional	Prints the version of UATG and exits.
–help	generate, clean, validate, setup, list-modules, from-config	Optional	Prints the help section and exits.
-dp, --dut_path	setup	Optional	The absolute/relative path to the directory where template `dut_onfig.yaml` is to be created.
-cp, --config_path	setup	Optional	The absolute/relative path to the directory where template `config.ini` is to be created.
-ap, --alias_path	setup	Optional	The absolute/relative path to the directory where template `aliasing.yaml` is to be created.
-c, --config_file	from-config	Required	Absolute/relative path to the `config.ini` file.

4.3. `uatg setup --help`¶

$ uatg setup --help
Usage: uatg setup [OPTIONS]

  Creates template configuration files.

  Setups template files for config.ini, dut_config.yaml and aliasing.yaml.
  Optionally you can provide the path's for each of them. If not specified
  files will be written to default paths.

  Optional: -dp, --dut_path;  -ap, --alias_path; -cp, --config_path

Options:
  -dp, --dut_path PATH     Directory to store the dut_config.yaml file
  -ap, --alias_path PATH   Directory to store the aliasing.yaml file
  -cp, --config_path PATH  Directory to store the config.ini file
  --help                   Show this message and exit.

The setup command will create template configuration files in the directory the user passes. These template files can be edited by the user to meet his needs.

4.4. `uatg generate --help`¶

$ uatg generate --help
Usage: uatg generate [OPTIONS]

Generates tests, cover-groups for a list of modules corresponding to the
DUT parameters specified in the configuration yamls, inside the work_dir.
Can also generate the test_list needed to execute them on RiverCore.

Requires: -cfg, --configuration, -md, --module_dir; -wd, --work_dir

Depends : (-gc, --gen_cvg -> -af, --alias_file)

Optional: -gc, --gen_cvg; -t, --gen_test_list; -ld, --linker_dir;

          -m, --modules; -v, --verbose

Options:
  -v, --verbose [info|error|debug]
                                  Set verbose level for debugging
  -m, --modules TEXT              Enter a list of modules as a string in a
                                  comma separated format.
                                  default-all
  -wd, --work_dir PATH            Path to the working directory where
                                  generated files will be stored.  [required]
  -ld, --linker_dir PATH          Path to the directory containing the linker
                                  file. Work Directory is Chosen for linker if
                                  this argument is empty
  -t, --gen_test_list             Set this flag if a test-list.yaml is to be
                                  generated by uatg. uatg does not generate
                                  the test_list by default.
  -gc, --gen_cvg                  Set this flag to generate the Covergroups
  -md, --module_dir PATH          Absolute Path to the directory containing
                                  the python files which generates the
                                  assembly tests. Required Parameter
                                  [required]
  -cfg, --configuration PATH      Path to the DUT configuration YAML Files.
                                  The YAML files should be specified (space
                                  separated) in the following  order 1.
                                  isa_config.yaml 2. core_config.yaml 3.
                                  custom_config.yaml 4. csr_grouping.yaml
                                  5. rv_debug The ordering should be
                                  strictly followed and any deviation will
                                  result in UATG erroring out. This
                                  Parameter is needed to generate/validate
                                  tests and also generate covergroups
                                  [required]
  -af, --alias_file PATH          Path to the aliasing file containing
                                  containing BSV alias names.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

The generate command is the main command of UATG. It will find the test classes and then generate the Assembly test files to be run on the DUT.

The user can also choose to generate the covergroups by passing the gen_cvg option. In addition to that, the user can selectively generate tests using the modules option.

4.5. `uatg from-config --help`¶

$ uatg from-config --help
Usage: uatg from-config [OPTIONS]

  Reads config.ini and invokes uatg with read paramaters.

  Optional: -c, --config

Options:
  -v, --verbose [info|error|debug]
                                  Set verbose level for debugging
  -c, --config_file PATH          Provide a config.ini file's path. This runs
                                  uatg based upon the parameters stored in the
                                  file. If not specified individual args/flags
                                  are to be passed through cli. In thecase of
                                  conflict between cli and config.ini values,
                                  config.ini values will be chosen  [required]
  --help                          Show this message and exit.

UATG also provides the option to be run from a single config file instead of using the subcommands every time. The from-config command is for that purpose.

Once the user sets up a config.ini file with all the required parameters, they can run UATG using the from-config command. Here the -c option should point to the configured config.ini.

Note

The user can refer the UATG Configuration files section to learn more about setting up the config.ini file.

4.6. `uatg validate --help`¶

$ uatg validate --help
Usage: uatg validate [OPTIONS]

  Parses the log generated upon test execution using regular expressions and
  provides a minimal coverage report.

  Required: -wd, --work_dir

            -cfg, --configuration

            -md, --module_dir

  Optional: -m, --modules (default - all)

            -v, --verbose

Options:
  -v, --verbose [info|error|debug]
                                  Set verbose level for debugging
  -m, --modules TEXT              Enter a list of modules as a string in a
                                  comma separated format.
                                  default-all
  -wd, --work_dir PATH            Path to the working directory where
                                  generated files will be stored.  [required]
  -md, --module_dir PATH          Absolute Path to the directory containing
                                  the python files which generate the assembly
                                  tests. Required Parameter  [required]
  -cfg, --configuration PATH      Path to the DUT configuration YAML Files.
                                  The YAML files should be specified (space
                                  separated) in the following  order 1.
                                  isa_config.yaml 2. core_config.yaml 3.
                                  custom_config.yaml 4. csr_grouping.yaml
                                  5. rv_debug.yaml The ordering should be
                                  strictly followed and any deviation will
                                  result in UATG erroring out. This
                                  parameter is needed to generate/validate
                                  tests and also generate covergroups
                                  [required]
  --version                       Show the version and exit.
  --help                          Show this message and exit.

The validate subcommand is an added optional feature of UATG. If the user precisely knows the pattern to search for in the log generated by running his test on the DUT, he can create a regular expression for the same and store it in the regex_formats.py file. He may then import those patterns within the test_class and use the check_logs() method of the class to perform a regular expression matching using UATG. This will increase (to some extent) the confidence of the tests, and also requires lesser time when compared to SV based methods.

The user should pass the required methods for UATG to perform log checking automatically.

4.7. `uatg list-modules --help`¶

$ uatg list-modules --help
Usage: uatg list-modules [OPTIONS]

  Lists the micro-architecture modules of core supported  among the modules
  actually present in the DUT

  Requires: -md, --module_dir

Options:
  -md, --module_dir PATH          Absolute Path to the directory containing
                                  the python files which generates the
                                  assembly tests. Required Parameter
                                  [required]
  -v, --verbose [info|error|debug]
                                  Set verbose level for debugging
  --version                       Show the version and exit.
  --help                          Show this message and exit.

The list-modules command is used when the user is not sure about the modules for which test_classes exist. As UATG will exit if a module for which no test classes were created, it is necessary that the user specifies the right modules.

4.8. `uatg clean --help`¶

$ uatg clean --help
Usage: uatg clean [OPTIONS]

  Removes ASM, SV and other generated files from the work directory, and
  removes .yapsy plugins from module directory.

  Requires: -wd, --work_dir

  Optional: -md, --module_dir; -v, --verbose

Options:
  -v, --verbose [info|error|debug]
                                  Set verbose level for debugging
  -wd, --work_dir PATH            Path to the working directory where
                                  generated files will be stored.  [required]
  -md, --module_dir PATH          Absolute Path to the directory containing
                                  the python files which generates the
                                  assembly tests. Required Parameter
                                  [required]
  --version                       Show the version and exit.
  --help                          Show this message and exit.

The clean command is used to remove the files generated by UATG. It cleans the entire work_directory, removes the __pycache__ files and also removes the .yapsyplugin files created during test generation/validation.

4. UATG CLI Commands¶

4.1. uatg --help¶

4.2. Common Options present in UATG Subcommands¶

4.3. uatg setup --help¶

4.4. uatg generate --help¶

4.5. uatg from-config --help¶

4.6. uatg validate --help¶

4.7. uatg list-modules --help¶

4.8. uatg clean --help¶