5. UATG Configuration Files

UATG makes use of 3 configuration files.

  1. config.ini - UATG Configuration file.

  2. dut_config.yaml - DUT Configuration file for test filtering.

  3. aliasing.yaml - File with alias for verilog signal names. (used when generating covergroups)

When specified, UATG also generates a test_list.yaml file along with the tests.

In this document, we try to explain the need to have these files as well throw some light on the format of these documents, so that the user can write/edit the configuration file, as necessary.

In order to provide a headstart, the uatg setup command will generate template config.ini, dut_config.yaml and aliasing.yaml files.

5.1. config.ini Specification

The config.ini file is used to specify the arguments required by UATG to generate tests. The user may choose to use the subcommands to manually perform the same tasks and decide to not use a config.ini file.

5.1.1. Configuration Options

Note

Information about the dut_config.yaml, aliasing.yaml and test_list.yaml are provided in the following sections.

Warning

All paths are absolute.

Table 5.1 General Configuration Options

Parameter

Description

verbose

The verbosity of the log generated by the tool.

clean

[Boolean] Option to clean the files created duting test generation. Clean will clean up all files, including the tests.

modules

The Modules of the DUT for which you wish to generate the tests. (will take multiple values)

module_dir

Absolute path to the directory where the user has saved the tests for all modules.

work_dir

The workdir where all of the files, reports and logs are generated.

linker_dir

The directory where the user has stored his link.ld file. If not specified, UATG will generate a linker at the work_dir.

dut_config

The absolute path to the dut_config.yaml file of the DUT for which the user wants to generate tests.

alias_file

The absolute path to the aliasing.yaml file of the DUT for which the user wants to generate covergroups.

gen_test_list

[Boolean] Creates a test_list.yaml file in the work_dir.

gen_test

[Boolean] UATG generates tests only when this is True. Else, UATG does nothing.

val_test

[Boolean] When True, UATG will check the log generated from the DUT against known log patterns to obtain an intial report of test coverage.

gen_cvg

[Boolean] When True, UATG will generate the covergroups for the tests.

Note

The standard delimiter for options having multiple values is , (comma).

5.1.2. Sample config.ini

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 [uatg]

 # [info, error, debug] set verbosity level to view different levels of messages.
 verbose = debug
 # [True, False] the clean flag removes unnecessary files from the previous runs and cleans directories
 clean =

 # Enter the modules whose tests are to be generated/validated in comma separated format.
 # Run 'uatg --list-modules to find all the modules that are supported. '
 # Use 'all' to generate/validate all modules
 modules = all

 # Absolute path of the uarch_modules/modules Directory
 module_dir = /home/user/work/InCore/chromite_uarch_tests/modules/
 # Directory to dump assembly files and reports
 work_dir = /home/user/work/InCore/micro-arch-tests/work
 # location to store the link.ld linker file. By default it's same as work_dir
 linker_dir = /home/user/work/InCore/micro-arch-tests/work

 # Path of the yaml file containing DUT Configuration.
 # By default the configuration is "uatg/target/dut_config.yaml"
 dut_config = /home/user/work/InCore/micro-arch-tests/uatg/target/dut_config.yaml
 # Absolute Path of the yaml file containing the signal aliases of the DUT
 # presently it is stored in 'uarch_modules/aliasing.yaml'
 alias_file = /home/user/work/InCore/chromite_uarch_tests/aliasing.yaml

 # [True, False] If the gen_test_list flag is True, the test_list.yaml needed for running tests in river_core are generated automatically.
 # Until you want to validate individual tests in river_core set the flag to True
 gen_test_list = True
 # [True, False] If the gen_test flag is True, assembly files are generated/overwritten
 gen_test = True
 # [True, False] If the val_test flag is True, assembly files are executed and the modules are validated
 val_test =
 # [True, False] If the gen_cvg flag is True, System Verilog cover-groups are generated
 gen_cvg = True

5.2. dut_config.yaml Specification

The dut_config.yaml file is the configuration file used to configure the DUT. This file should contain information about the hardware units present in the DUT as well as provide information about the ISA and off-core components like cache supported/present in the unit.

Usually such a yaml file is used to generate a core of required configuration from an existing, highly parameterizable base design. In the case of Chromite , we have such configuration yaml file which we use to selectively generate tests based on the hardware units present in the DUT.

This dut_config.yaml will be used by the test classes as well as the test generator to identify tests that can suitably exercise functional coverpoints in the design as well as parameterize the test to exploit the hardware features to the fullest.

Warning

It is paramount that the user’s preferring their custom dut_config.yaml make sure that their file contains the ISA supported by the DUT as a parameter. UATG will throw an error and exit if the ISA argument is not present in the yaml.

5.2.1. Sample dut_config.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
ISA: RV64IMAFDCSU
iepoch_size: 2
depoch_size: 1
dtvec_base: 256
s_extension:
  mode: sv39
  itlb_size: 4
  dtlb_size: 4
  asid_width: 9
pmp:
  enable: true
  entries: 4
  granularity: 8
m_extension:
  mul_stages: 1
  div_stages: 32
branch_predictor:
  instantiate: True
  predictor: gshare
  on_reset: enable
  btb_depth: 64
  bht_depth: 512
  history_len: 8
  history_bits: 5
  ras_depth: 8
icache_configuration:
  instantiate: true
  on_reset: enable
  sets: 64
  word_size: 4
  block_size: 16
  ways: 4
  fb_size: 4
  replacement: RR
  ecc_enable: false
  one_hot_select: false
dcache_configuration:
  instantiate: true
  on_reset: enable
  sets: 64
  word_size: 8
  block_size: 8
  ways: 4
  fb_size: 8
  sb_size: 2
  replacement: RR
  ecc_enable: false
  one_hot_select: false
  rwports: 1
reset_pc: 4096
physical_addr_size: 32
bus_protocol: AXI4
fpu_trap: false
debugger_support: false
no_of_triggers: 0
csr_configuration:
  structure: daisy
  counters_in_grp4: 7
  counters_in_grp5: 7
  counters_in_grp6: 7
  counters_in_grp7: 8

The text shown above is in the yaml format. These key-value pairs are used to configure the chromite core.

If you notice, the yaml file contains everything from the ISA chosen, cache configuration to the number of CSRs. To explain, let us consider the branch_predictor key of the yaml file.

Table 5.2 Parameters in Branch Predictor

Parameter

Description

instantiate

indicates if the branch predictor (BPU) is present in the core

predictor

denotes the type of predictor implemented

on_reset

denotes if the BPU will be enabled after resetting the core

btb_depth

depth of the Branch target Buffer(BTB) in the gshare BPU

bht_depth

depth of the Branch History Table(BHT) in the gshare BPU

history_len

width of the Global History Register(GHR).

history_bits

bits of the Global History Register which is actually used for predicting based on history.

ras_depth

depth of the Return Address Stack used for storing return address of Call statements

Similar to this, you can find the configuration of other similar units present in the core from the dut_config.yaml file. The paramters obtained from the section like branch predictor will be particularly useful when tests are to be targeted.

The following snippet shows how the parameters of the branch predictor from the config file will be used to create a targeted test for exercising the BPU.

1
2
3
4
5
6
7
def execute(self, _dut_dict):
    _en_bpu = _bpu_dict['instantiate']
    self._btb_depth = _bpu_dict['btb_depth']
    if _en_bpu and self._btb_depth:
        return True
    else:
        return False

The snippet above is from the test class which tries to fill the entire Branch Target Buffer (BTB) of a branch predictor unit (G-Share Fully Associative) with jump, call, return and conditional branch instructions.

Note

The _dut_dict argument shown here contains only the values associated with the branch_predictor key from the yaml file shown earlier. The UATG-test_generator will send only the values present in the key which matches the module for which said test was written for.

Here, the execute() method reads the value of instantiate in the bpu section of the dut_config.yaml into the _en_bpu variable. It also stores the depth of the BTB in the variable _btb_depth. As this test is meant to exercise the BPU, there is no point to generate the test if the BPU is not instantiated. Likewise, it is necessary that the btb_depth is greater than one. Hence, we use these conditions to decide if the test which we have in the test_class would prove worthwhile when run on our DUT.

Therefore, it is necessary that the user creates a similiar yaml file as shown earlier and update it with their DUT’s configuration to make targeted test generation easier.

5.3. aliasing.yaml Specification

The aliasing file is neccesary when the user wants to generate Covergroups (CocoTb or SV) along with the tests. The aliasing file tries to make the test_class more readable.

The Verilog generated by the BSV compiler tends to be incomprehensible and long some times. In this case, having a alias file which can be used to alias such incomprehensible signal names with intelligible and logical names will make the process of defining the generate_covergroups() method easier as well as make the method readable for other people who do not know the actual BSV signal names.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
tb_top:
  path_to_bpu: mktbsoc.soc.ccore.riscv.stage0.bpu
  path_to_decoder: mktbsoc.soc.ccore.riscv.stage2.instance_decoder_func_32_2
  path_to_stage0: mktbsoc.soc.ccore.riscv.stage0
  path_to_fn_decompress: mktbsoc.soc.ccore.riscv.stage1.instance_fn_decompress_0

bpu:
  input:
  output:
  register:
    bpu_rg_ghr: rg_ghr_port1__read
    bpu_rg_initialize: rg_initialize
    bpu_rg_allocate: rg_allocate
  wire:
    bpu_mispredict_flag: ma_mispredict_g
    bpu_btb_tag: v_reg_btb_tag
    bpu_btb_entry: v_reg_btb_entry
    bpu_ras_top_index: ras_stack_top_index_port2__read
    bpu_btb_tag_valid: btb_valids

test_case:
  test: regression

The block above shows a sample aliasing file which has the signals in the branch_predictor(bpu) aliased. In addition to that, we also have the hierarchical paths to the modules to be used in the top module of the test bench defined here. Most of the times, the names generated by the BSV complier is very intelligible as shown in the above example. But, aliasing the signal names would make the process of writing/understanding code much easier.

As shown, the input, output, register and wire present in the module need to be separately organized in the yaml file. This makes selection of files even more easier as we do not have to indicate if the signal type in the aliased name for readability.

5.4. test_list.yaml Specification

When gen_test_list is true in the config.ini or when -t is passed with the uatg generate command, UATG, apart from generating just the test artifacts, must also generate a test list YAML. The test list has the following syntax:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<test-name>:
 asm_file: <path to assembly/C/test file generated>
 cc: <optional compile command to be used to compile the tests>
 ccargs: <optional compile arguments to be used>
 extra_compile: [<list of supplementary files to be compiled. Provided as absolute paths>]
 include: [<list of directories containing any required header file>]
 isa: <the isa string for which this test was generated for>
 linker_args: <arguments to be provided to the linker command>
 linker_file: <absolute path of the linker file to be used>
 result: <set to Unvailable during generation. Will change to Pass or Fail based on the simulation runs>
 generator: <name of the generator plugin used to generate this test>
 march: <the march argument to be supplied to the compiler>
 mabi: <the mabi argument to be supplied to the compiler>
 compile_macros: <list of strings indicating compile time macros that need to be enabled>

Note

While we capture the ISA, it may seem redundant to capture the march and mabi. However, the tests can be generated to check a subset features like - no compressed instructions in targets which do support compressed instructions. Hence the redundancy.

Note

cc and ccargs are optional here because typically the target/DUT will have its own compiler and toolchain setup and may ignore these fields. Also most of the test generators are independent of the choice of toolchain and may leave these fields blank.

Warning

All the files contain an absolute path.