5. UATG Configuration Files

UATG makes use of 4 configuration files for the currently existing tests. In addition to that, it takes in 2 more YAML files which will be used for future tests.

  1. config.ini - UATG Configuration file.

  2. isa_config.yaml - ISA Configuration file for ISA based test filtering.

  3. core_config.yaml - Core Configuration file specifying the micro architectural choices.

  4. custon_config.yaml - Custom configuration file.

  5. csr_grouping.yaml - Contains information about the CSRs required in the implementation.

  6. rv_debug.yaml - Contains information pertaining to the debug spec of

    RISC-V

  7. 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 *_config.yaml, csr_grouping.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. By default, the user is required to point to the target directory within chromite_uatg_tests

configuration_files

The absolute paths, comma-separated to the isa_config.yaml, core_config.yaml, custom_config.yaml, and csr_grouping.yaml files (in same order) of the DUT for which the user wants to generate tests. (no space between commas and paths allowed)

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
36
37
38
 # See LICENSE.incore for license details

 [uatg]

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

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

 # Absolute path to chromite_uatg_tests/modules Directory
 module_dir = /home/user/myquickstart/chromite_uatg_tests/modules/

 # Directory to dump assembly files and reports
 work_dir = /home/user/myquickstart/work/

 # location to store the link.ld linker file. By default it's the target directory within chromite_uatg_tests
 linker_dir = /home/user/myquickstart/chromite_uatg_tests/target

 # Path to the yaml files containing DUT Configuration.
 configuration_files = /home/user/myquickstart/isa_config.yaml,/home/user/myquickstart/core_config.yaml,/home/user/myquickstart/custom_config.yaml,/home/user/myquickstart/csr_grouping.yaml

 # Absolute Path of the yaml file containing the signal aliases of the DUT
 alias_file = /home/user/myquickstart/chromite_uatg_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.
 # Unless you want to run 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, Log from DUT are parsed and the modules are validated
 val_test = False
 # [True, False] If the gen_cvg flag is True, System Verilog cover-groups are generated
 gen_cvg = True

5.2. DUT Configuration YAML(s) Specification

The isa_config.yaml, core_config.yaml, custom_config.yaml, and csr_grouping.yaml files are the configuration files used to configure the DUT. These files 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 yaml files is used to generate a core of required configuration from an existing, highly parameterizable base design. In the case of Chromite , we have 4 configuration yaml files. We we use these files to selectively generate tests based on the hardware units present in the DUT.

This ***_config.yaml files will be used by the test classes as well as the test generator to identify tests that can suitably exercise all the hardware implemented in the design as well as parameterize the test to exploit the hardware features to the fullest.

Warning

It is paramount that the users who use their custom *_config.yaml and csr_grouping.yaml files make sure that their first YAML file contains the ISA supported by the DUT as a parameter. If not, UATG will throw an error and exit.

5.2.1. Sample isa_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
hart_ids: [0]
  hart0:
    custom_exceptions:
      - cause_val: 25
        cause_name: halt_ebreak
        priv_mode: M
      - cause_val: 26
        cause_name: halt_trigger
        priv_mode: M
      - cause_val: 28
        cause_name: halt_step
        priv_mode: M
      - cause_val: 29
        cause_name: halt_reset
        priv_mode: M
    custom_interrupts:
      - cause_val: 16
        cause_name: debug_interrupt
        on_reset_enable: 1
        priv_mode : M
    ISA: RV64IMACSUZicsr_Zifencei
    User_Spec_Version: "2.3"
    pmp_granularity: 1
    physical_addr_sz: 32
    supported_xlen:
      - 64

The YAML file has been truncated for brevity. The key-value pairs in the above YAML files are used to configure the ISA level parameters of the chromite core. You can find the complete YAML file in the repository.

If you notice, this yaml file contains information like the ISA chosen, custom interrupts, physical address size and several others.

5.2.2. Sample core_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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
isb_sizes:
    isb_s0s1: 2
    isb_s1s2: 2
    isb_s2s3: 1
    isb_s3s4: 8
    isb_s4s5: 8
num_harts: 1
merged_rf: False
s_extension:
  itlb_size: 4
  dtlb_size: 4
total_events : 31
iepoch_size: 2
m_extension:
  mul_stages_in : 1
  mul_stages_out: 1
  div_stages : 32
branch_predictor:
  instantiate: True
  predictor: gshare
  btb_depth: 32
  bht_depth: 512
  history_len: 8
  history_bits: 5
  ras_depth: 8
icache_configuration:
  instantiate: true
  sets: 64
  word_size: 4
  block_size: 16
  ways: 4
  replacement: RANDOM
  fb_size: 4
  ecc_enable: false
  one_hot_select: false
dcache_configuration:
  instantiate: true
  sets: 64
  word_size: 8
  block_size: 8
  ways: 4
  fb_size: 9
  sb_size: 2
  lb_size: 4
  ib_size: 2
  replacement: RR
  ecc_enable: false
  one_hot_select: false
  rwports: '1r1w'
reset_pc: 4096
bus_protocol: AXI4
bsc_compile_options:
  test_memory_size: 33554432
  assertions: true
  ovl_assertions: False
  sva_assertions: False
  ovl_path: ""
  trace_dump: True
  compile_target: 'sim'
  suppress_warnings: ["none"]
  verilog_dir: build/hw/verilog
  build_dir: build/hw/intermediate
  top_module: mkTbSoc
  top_file: TbSoc.bsv
  top_dir: test_soc
  open_ocd: False
  cocotb_sim: False
verilator_configuration:
  coverage: none
  trace: false
  threads: 1
  verbosity: true
  sim_speed: fast
  out_dir: bin
noinline_modules:
  stage0: True
  stage1: True
  stage2: True
  stage3: True
  stage4: True
  stage5: True
  mbox: True
  mbox_mul: True
  mbox_div: True
  registerfile: True
  bpu: True
  riscv: True
  csrbox: True
  scoreboard: True
  bypass: True
  base_alu: True
  decoder: True
  decompress: True

The key-value pairs in the above YAML files are used to configure the micro-architecture of the chromite core. You can find the updated YAML file here

If you notice, this yaml file contains information like the bus_protocol, isb size, cache parameters and several others.

To explain how we use these parameters in UATG, 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 core_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.

Note

UATG will internally combine the four YAML files into a nested dictionary. Then we only pass the required module section of the core_config.yaml file with the ISA string.

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.2.3. Sample custom_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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
hart_ids: [0]
hart0:
    dtim_base:
      reset-val: 0x0
      rv32:
          accessible: false
      rv64:
          accessible: false
          type:
              ro_constant: 0x0
          shadow:
          shadow_type:
          msb: 63
          lsb: 0
      description: dtim base
      address: 0x7C3
      priv_mode: M
    itim_base:
      reset-val: 0x0
      rv32:
          accessible: false
      rv64:
          accessible: false
          type:
              ro_constant: 0x0
          shadow:
          shadow_type:
          msb: 63
          lsb: 0
      description: dtim base
      address: 0x7C2
      priv_mode: M
    customcontrol:
      reset-val: 0x0000000000000017
      rv32:
        accessible: false
      rv64:
        accessible: true
        ienable:
          implemented: true
          type:
            ro_constant: 0x1
          description: bit for cache-enable of instruction cache, part of rg_customcontrol
          shadow:
          shadow_type:
          msb: 0
          lsb: 0
        denable:
          implemented: true
          type:
            ro_constant: 0x1
          description: bit for cache-enable of data cache, part of rg_customcontrol
          shadow:
          shadow_type:
          msb: 1
          lsb: 1
        bpuenable:
          implemented: true
          type:
            ro_constant: 0x1
          description: bit for enabling branch predictor unit, part of rg_customcontrol
          shadow:
          shadow_type:
          msb: 2
          lsb: 2
        arith_excep:
          implemented: true
          type:
            ro_constant: 0x0
          description: bit for enabling arithmetic exceptions, part of rg_customcontrol
          shadow:
          shadow_type:
          msb: 3
          lsb: 3
        debug_enable:
          implemented: true
          type:
            ro_constant: 0x1
          description: bit for enabling debugger on the current hart
          shadow_type:
          shadow:
          msb: 4
          lsb: 4
      description: the register holds enable bits for arithmetic exceptions, branch predictor unit, i-cache, d-cache units
      address: 0x800
      priv_mode: U

The YAML file shown above contains fields which will be used to configure the core.

5.2.4. Sample csr_grouping.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
  grp1:
    - MISA
    - MSCRATCH
    - SSCRATCH
    - MVENDORID
    - MSTATUS
    - SSTATUS
    - MIE
    - SIE
    - MIP
    - SIP
    - MTVEC
    - STVEC
    - MEPC
    - SEPC
    - MCAUSE
    - SCAUSE
    - MTVAL
    - STVAL
    - MCYCLE
    - MINSTRET
    - MHARTID
    - MARCHID
    - MIMPID
    - TIME
    - CYCLE
    - MCOUNTINHIBIT
    - INSTRET
    - SATP
    - MIDELEG
    - MEDELEG
    - PMPCFG0
    - PMPADDR0
    - PMPADDR1
    - PMPADDR2
    - PMPADDR3
    - CUSTOMCONTROL

This YAML file contains information about the CSR grouping. The CSRs in Chromite are daisy chained for better performance.

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.