8. Code Documentation¶

8.1. Test Generator¶

uatg.test_generator.asm_generation_process(args)[source]¶: for every plugin, a process shall be spawned. The new process shall create an Assembly test file.

uatg.test_generator.clean_dirs(work_dir, modules_dir)[source]¶: This function cleans the files generated by UATG. Presently it removes __pycache__, work_dir directory and also removes the ‘.yapsy plugins’ files in the module’s directories.

uatg.test_generator.generate_sv(work_dir, config_dict, modules, modules_dir, alias_dict, jobs)[source]¶: The generate_sv function dumps the covergroups written by the user into a ‘coverpoints.sv’ file present within the ‘sv_top’ directory within the work directory. This function dumps into an SV file only if the test_class contains the generate_covergroups method. This function, like generate_asm also allows to select the modules for which covergroups are to be generated. In addition, the method also takes in an alias_dict which can be used to alias the BSV signal names to something even more comprehensible.

uatg.test_generator.generate_tests(work_dir, linker_dir, modules, config_dict, test_list, modules_dir, index_path, paging_modes, jobs)[source]¶

The function generates ASM files for all the test classes specified within the module_dir. The user can also select the modules for which he would want the tests to be generated for. The YAPSY plugins for the tests are generated by the function automatically.

The tests are created within the work directory passed by the user. A test_list is also created in the yaml format by the function. The test generator also creates a linker file as well as the header files for running the ASM files on the DUT, when required. Finally, the test generator only generates the tests whose targets are implemented in the DUT.

uatg.test_generator.sv_generation_process(args)[source]¶: for every plugin, a process shall be spawned. The process shall generate System Verilog coverpoints

uatg.test_generator.validate_tests(modules, config_dict, work_dir, modules_dir)[source]¶: Parses the log returned from the DUT for finding if the tests were successful. The user should have created regular expressions for the patterns he’s expecting to be seen in the log generated by the DUT. In addition to just the checking, it can also be set up to provide a report for every test for which the user tries to validate.

8.2. Utils¶

uatg.utils.clean_modules(module_dir, modules)[source]¶: Function to read the modules specified by the user, check if they exist or raise an error. Returns a list of the modules for which tests will be generated.

uatg.utils.combine_config_yamls(configuration)[source]¶: This function reads all the YAML file paths specified by the user. Loads the data into a dictionary and then returns it to the invoking method.

uatg.utils.create_alias_file(alias_path)[source]¶: Creates a template aliasing.yaml file at the alias_path directory. Invoked by running uatg setup

uatg.utils.create_config_file(config_path, jobs, modules, module_dir, work_dir, linker_dir, alias_path, test_compile, cfg_files)[source]¶: Creates a template config.ini file at the config_path directory. Invoked by running uatg setup.

uatg.utils.create_dut_config_files(dut_config_path)[source]¶: Creates a template dut_config.yaml (based on Chromite’s default configuration at the dut_config_path. Invoked by running the uatg setup command

uatg.utils.create_linker(target_dir)[source]¶: Creates a template linker file in the target_directory specified by the user.

uatg.utils.create_model_test_h(target_dir)[source]¶: Creates a model_test.h file in the target directory specified by the user.

uatg.utils.create_plugins(plugins_path, index_yaml, module)[source]¶: This function is used to create Yapsy Plugin files. The YAPSY plugins are required to be in a certain pattern. This function will read the test classes and create files complying to the pattern. Yapsy will ignore all other python file which does not have a .yapsy-plugin file associated with it.

uatg.utils.find_instances(string, character)[source]¶: The function returns all the indices of the character present in the string. A list is returned

uatg.utils.generate_sv_components(sv_dir, alias_file)[source]¶: invokes the methods within the sv_components class and creates the sv files. tb_top.sv, interface.sv and Defines.sv are created. The coverpoints.sv file will be generated by the test_generator

uatg.utils.generate_test_list(asm_dir, uarch_dir, module_dir, isa, test_list, compile_macros_dict, self_checking_dict)[source]¶: updates the test_list.yaml file with the location of the tests generated by test_generator as well the directory to dump the logs. Check the test_list format documentation present. The test list generation is an optional feature which the user may choose to use.

uatg.utils.info(version)[source]¶: The function prints the Information about UATG.

uatg.utils.join_yaml_reports(work_dir='abs_path_here/', module='branch_predictor')[source]¶: Function that combines all the verification report yaml files into one. This function is used as a part of the Check_logs/validate option present in UATG.

uatg.utils.list_of_modules(module_dir)[source]¶: lists the tests modules available by reading the index.yaml file present in the modules directory.

uatg.utils.load_yaml(file)[source]¶: Common function to load YAML Files. The function checks if the file is of YAML format else exits. If the file is in YAML, it reads the file and returns the data from the file as a dictionary.

uatg.utils.paging_modes(yaml_string, isa)[source]¶: This function reads the YAML entry specifying the valid paging modses supported by the SATP CSR and returns the mode(s) for the framework to generate tests

uatg.utils.run_make(work_dir, jobs)[source]¶

function to invoke the empty compilation makefile

Parameters

work_dir – path to the work directory
jobs – number of parallel processes for the make utility to spawn

Returns

placeholder int

Return type

int

uatg.utils.rvtest_data(bit_width=0, num_vals=20, random=True, signed=False, align=4) → str [source]¶: Used to specify the data to be loaded into the test_data section of the DUT memory. The user will specify the data he wants in this section of the DUT memory.

uatg.utils.select_paging_modes(paging_modes)[source]¶: Function to read the paging modes specified by the user, and generate only those modes and not every possible paging mode. Returns a list of the user selected modes

uatg.utils.setup_pages(pte_dict, page_size=4096, paging_mode='sv39', valid_ll_pages=64, mode='machine', megapage=False, gigapage=False, terapage=False, petapage=False, user_superpage=False, user_supervisor_superpage=False, fault=False, mem_fault=False, misaligned_superpage=False)[source]¶

creates pagetables to run tests in User and Supervisor modes Currently works with the sv39 virtual memory addressing.

Parameters

page_size (int) – Size of the pages - 4kiB.
paging_mode (string) – Paging mode used in the tests - sv39, for now.
valid_ll_pages (int) – Valid last level pages to be created.
mode (string) – Mode of execution for which the test is being generated.

Returns

([out_code_string], out_data_string)

Return type

tuple(list, string)

uatg.utils.split_isa_string(isa_string)[source]¶: The function parses the ISA string, removes the ‘S,U,H and N’ characters from it. The updates ISA string is returned.

class uatg.utils.sv_components(config_file)[source]¶

This class contains the methods which will return the tb_top and interface system verilog tests. This text will be written into SV files.

__init__(config_file)[source]¶: Initialize self. See help(type(self)) for accurate signature.

__weakref__¶: list of weak references to the object (if defined)

generate_defines()[source]¶: creates the syntax for the defines file which will be used to select tests.

generate_interface()[source]¶: returns interface SV syntax.

generate_tb_top()[source]¶: returns tb_top Sv syntax

8.3. Instruction Constants¶

uatg.instruction_constants.bit_marcher(bit_width)[source]¶

Returns marching pattern of the given number of bits

Args:: bit_width (int): width of the 0s over which 1s are to be marched
Returns:: list: list of numbers in decimal value which represents bit_width marching pattern

uatg.instruction_constants.bit_walker(bit_width=8, n_ones=1, invert=False, signed=True)[source]¶

Returns a list of binary values each with a width of bit_width that walks with n_ones walking from lsb to msb. If invert is True, then list contains bits inverted in binary.

Parameters

bit_width – bit-width of register/value to fill.
n_ones – number of ones to walk.
invert – whether to walk one’s or zeros
signed – whether to generate signed values

Returns

list of strings

uatg.instruction_constants.illegal_generator(isa='RV32I') → list [source]¶

Parameters: isa – RV[32|64]{IMAFD}
Returns: list of illegal instructions for given ISA configuration

Provide the ISA string and obtain the list of illegal opcodes as integers. It uses the riscv-opcodes repository’s instruction encoding data and are stored above as rv32_encodings and rv64_encodings variables.

This function parses the instructions and initially finds all illegal opcodes. Then for the variable encoding fields in each instruction, it makes one/more/all of them to contain illegal values and appends such combination into a list and returns it.

Usage

from uatg.instruction_constant import illegal_generator

illegal_list = illegal_generator("RV32IMAF")

illegal list would contain decimal value of illegal instructions user should convert it into hex and dump into memory using .word

uatg.instruction_constants.pattern_walk(max_width: int, fill: str, pattern: str) → list [source]¶

Returns a list of test vectors (of width max_width) with the given pattern walked (digit-by-digit in hex) through the fill-string.

A pattern longer than max_width would result can be tricky to use.

Args:: max_width (int): width of each list element to be returned. fill (str): hex-digit to be used for filling spaces. pattern (str): pattern to be walked.
Returns:: list: list of test vectors (with the 0x) prefix.

uatg.instruction_constants.twos(val, bits)[source]¶

Finds the twos complement of the number

Parameters

val (str or int) – input to be complemented
bits (int) – size of the input

Result

two’s complement version of the input

8.4. Instruction Generator¶

class uatg.instruction_generator.instruction_generator(isa='RV64I')[source]¶

This class reads the isem.yaml file and based upon the ISA specification , it generates random/specific instructions with random/specific range of replacements. Presently supports RV[32|64]IMAFDCB extensions. It does not generate Branch/Jump/Load/Store instructions to avoid unpredictable control flow.

Usage

import uatg.instruction_generator

generator = instruction_generator('uatg/isem.yaml', 'RV64IMAFDC')
random_i_instructions = generator.generate_i_inst(
                                        instructions='random',
                                        modifiers={'xrs1': {'x0'},
                                                 'xrs2': {'x0'},
                                                 'xrd': {'x0'},
                                        },
                                        no_of_insts=10)

__init__(isa='RV64I')[source]¶

Constructor of the class.

Parameters: isa – string containing the ISA for which instructions should be generated.

__modifier_update(modifiers: Optional[dict]) → dict ¶

An private utility function to clean/update the modifiers from user-input

Parameters: modifiers – input modifiers from generate_x_inst function
Returns: sanitized modifiers containing default entries for unmentioned fields

__replace_fields(instruction: str, modifiers: dict) → str ¶

Private function to replace the variable fields in a given instruction

Parameters: instruction – str containing the asm-syntax of an instruction
Returns: str with the variable fields are replaced with random choice of registers/values

__weakref__¶: list of weak references to the object (if defined)

generate_a_inst(instructions: Union[str, list] = 'random', modifiers: Union[None, dict] = None, no_of_insts: int = 5) → List[str][source]¶

Function to generate A-instructions. Can generate both random selection of instructions or a specified list of instructions. The modifiers can be used to specify specific value/range of values for variable fields.

Parameters

instructions – ‘random’ or a list of instructions for which you wish to generate instructions
modifiers – None or dictionary containing custom replacement options.
no_of_insts – number of instructions to be generated

Returns