6. Code Documentation

6.1. riscv_config.checker

riscv_config.checker.add_debug_setters(schema_yaml)[source]

Function to set the default setters for various fields in the debug schema

riscv_config.checker.add_def_setters(schema_yaml)[source]

Function to set the default setters for various fields in the schema

riscv_config.checker.add_reset_setters(schema_yaml)[source]

Function to set the default setters for extension subfields in the misa

riscv_config.checker.check_custom_specs(custom_spec, work_dir, logging=False, no_anchors=False)[source]

Function to perform ensure that the isa and platform specifications confirm to their schemas. The Cerberus module is used to validate that the specifications confirm to their respective schemas.

Parameters
  • isa_spec (str) – The path to the DUT isa specification yaml file.

  • logging (bool) – A boolean to indicate whether log is to be printed.

Raises

ValidationError – It is raised when the specifications violate the schema rules. It also contains the specific errors in each of the fields.

Returns

A tuple with the first entry being the absolute path to normalized isa file and the second being the absolute path to the platform spec file.

riscv_config.checker.check_debug_specs(debug_spec, isa_spec, work_dir, logging=False, no_anchors=False)[source]

Function to perform ensure that the isa and debug specifications confirm to their schemas. The Cerberus module is used to validate that the specifications confirm to their respective schemas.

Parameters
  • debug_spec – The path to the DUT debug specification yaml file.

  • isa_spec (str) – The path to the DUT isa specification yaml file.

  • logging (bool) – A boolean to indicate whether log is to be printed.

Raises

ValidationError – It is raised when the specifications violate the schema rules. It also contains the specific errors in each of the fields.

Returns

A tuple with the first entry being the absolute path to normalized isa file and the second being the absolute path to the platform spec file.

riscv_config.checker.check_isa_specs(isa_spec, work_dir, logging=False, no_anchors=False)[source]

Function to perform ensure that the isa and platform specifications confirm to their schemas. The Cerberus module is used to validate that the specifications confirm to their respective schemas.

Parameters
  • isa_spec (str) – The path to the DUT isa specification yaml file.

  • logging (bool) – A boolean to indicate whether log is to be printed.

Raises

ValidationError – It is raised when the specifications violate the schema rules. It also contains the specific errors in each of the fields.

Returns

A tuple with the first entry being the absolute path to normalized isa file and the second being the absolute path to the platform spec file.

riscv_config.checker.check_mhpm(spec, logging=False)[source]

Check if the mhpmcounters and corresponding mhpmevents are implemented and of the same size as the source

riscv_config.checker.check_pmp(spec, logging=False)[source]

Check if the pmp csrs are implemented correctly as per spec. The following checks are performed:

  • the number of accessible pmpaddr csrs must be 0, 16 or 64

  • the number of implemented pmpcfg csrs must be 0, 16 or 64

  • the pmpaddr and pmpcfgs must be implemented implemented from the lowest numbered indices and be contiguous

  • the number of accessible pmpaddr csrs and the implemented pmpcfg csrs must be the same

  • for each accesible pmpaddr csr the corresponding pmpcfg csr must be implemented

  • reset values of the accessible pmpaddr csrs must be coherent with the pmp_granularity field.

riscv_config.checker.check_reset_fill_fields(spec, logging=False)[source]

The check_reset_fill_fields function fills the field node with the names of the sub-fields of the register and then checks whether the reset-value of the register is a legal value. To do so, it iterates over all the subfields and extracts the corresponding field value from the reset-value. Then it checks the legality of the value according to the given field description. If the fields is implemented i.e accessible in both 64 bit and 32 bit modes, the 64 bit mode is given preference.

riscv_config.checker.check_shadows(spec, logging=False)[source]

Check if the shadowed fields are implemented and of the same size as the source

riscv_config.checker.check_supervisor(spec, logging=False)[source]

this function includes several supervisor related checks:

  • check if pte_ad_hw_update is True, then satp.mode should be able to take one of the possible virtualization modes

riscv_config.checker.delegset()[source]

Function to set “implemented” value for mideleg regisrer.

riscv_config.checker.fsset()[source]

Function to set defaults based on presence of ‘F’ extension.

riscv_config.checker.groupc(test_list)[source]

Generator function to squash consecutive numbers for wpri bits.

riscv_config.checker.hregset()[source]

Function to set defaults based on presence of ‘H’ extension.

riscv_config.checker.hregseth()[source]

Function to set defaults based on presence of ‘H’ extension.

riscv_config.checker.hset()[source]

Function to set defaults based on presence of ‘U’ extension.

riscv_config.checker.nregset()[source]

Function to set defaults based on presence of ‘N’ extension.

riscv_config.checker.nuset()[source]

Function to check and set defaults for all fields which are dependent on the presence of ‘U’ extension and ‘N’ extension.

riscv_config.checker.reset()[source]

Function to set defaults to reset val of misa based on presence of ISA extensions.

riscv_config.checker.reset_vsstatus()[source]

Function to set defaults to reset val of mstatus based on the xlen and S, U extensions

riscv_config.checker.resetsu()[source]

Function to set defaults to reset val of mstatus based on the xlen and S, U extensions

riscv_config.checker.sregset()[source]

Function to set defaults based on presence of ‘S’ extension.

riscv_config.checker.sregseth()[source]

Function to set defaults based on presence of ‘S’ extension.

riscv_config.checker.sset()[source]

Function to set defaults based on presence of ‘S’ extension.

riscv_config.checker.trim(foo)[source]

Function to trim the dictionary. Any node with implemented field set to false is trimmed of all the other nodes.

Parameters

foo (dict) – The dictionary to be trimmed.

Returns

The trimmed dictionary.

riscv_config.checker.twset()[source]

Function to check and set value for tw field in misa.

riscv_config.checker.uregset()[source]

Function to set defaults based on presence of ‘U’ extension.

riscv_config.checker.uregseth()[source]

Function to set defaults based on presence of ‘U’ extension.

riscv_config.checker.uset()[source]

Function to set defaults based on presence of ‘U’ extension.

6.2. riscv_config.schemaValidator

class riscv_config.schemaValidator.schemaValidator(*args, **kwargs)[source]

Custom validator for schema having the custom rules necessary for implementation and checks.

__init__(*args, **kwargs)[source]

The arguments will be treated as with this signature:

__init__(self, schema=None, ignore_none_values=False,

allow_unknown=False, require_all=False, purge_unknown=False, purge_readonly=False, error_handler=errors.BasicErrorHandler)

_check_with_cannot_be_false_rv32(field, value)[source]

Functions ensures that the field cannot be False in rv32 mode

_check_with_cannot_be_false_rv64(field, value)[source]

Functions ensures that the field cannot be False in rv64 mode

_check_with_capture_isa_specifics(field, value)[source]

Function to extract and store ISA specific information(such as xlen,user spec version and extensions present) and check whether the dependencies in ISA extensions are satisfied.

_check_with_max_length(field, value)[source]

Function to check whether the given value is less than the maximum value that can be stored(2^xlen-1).

_check_with_max_length32(field, value)[source]

Function to check whether the given value is less than the maximum value that can be stored(2^xlen-1).

_check_with_mtval_update(field, value)[source]

Function to check if the mtval_update bitmap adhered to the required restrictions.

_check_with_s_debug_check(field, value)[source]

Function ensures that the ro_constant is hardwired to zero when S is present in the ISA string Used mainly for debug schema

_check_with_s_exists(field, value)[source]

Function to check that the value can be true only when ‘S’ mode exists in the ISA string

_check_with_u_debug_check(field, value)[source]

Function ensures that the ro_constant is hardwired to zero when U is present in the ISA string Used mainly for debug schema

_check_with_xcause_check(field, value)[source]

Function to verify the inputs for mcause.

_check_with_xtveccheck(field, value)[source]

Function to check whether the inputs in range type in mtvec are valid.

6.3. Utils

class riscv_config.utils.ColoredFormatter(*args, **kwargs)[source]

Class to create a log output which is colored based on level.

__init__(*args, **kwargs)[source]

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{‘ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

format(record)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class riscv_config.utils.SortingHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]
riscv_config.utils.setup_logging(log_level)[source]

Setup logging

Verbosity decided on user input

Parameters

log_level (str) – User defined log level

6.4. WARL

class riscv_config.warl.warl_class(node, csrname, f_msb, f_lsb, spec=None)[source]

This is a class for handling various operations and checks for the WARL type of registers and/or subfields as defined by the riscv-config spec<TODO: link here>. While riscv-config remains to be the major user of this package, this class can be used as an importable python package as well in several other scenarios to perform checks on a particular WARL string.

The basic WARL node should be dict adhering to the following syntax:

warl:
   dependency_fields: [list]
   legal: [list of warl-string]
   wr_illegal: [list of warl-string]
Parameters
  • node (dict) – This input is the dict adhering to the above syntax.

  • csrname (str) – this is string indicating the name of the csr or csr::subfield which is defined as a WARL type. This primarily used to generate a series of legible error and debug messages. If the input warl node is for a subfield, then use :: as the delimiter between the csr name and the subfield name.

  • f_msb (int) – the max msb location of the csr or subfield.

  • f_lsb (int) – the min lsb location of the csr or subfield.

  • spec (dict) – This is the entire isa-spec of a single hart. This dict is primarily used by this class to perform specific checks on reset-vals and on dependency_vals string validity.

__init__(node, csrname, f_msb, f_lsb, spec=None)[source]

Constructor Method

__weakref__

list of weak references to the object (if defined)

This function checks if a given value satifies the conditions present in a given legal string.

Parameters
  • legalstr (str) – This is a string following the warl-legal syntax.

  • value (int) – The value whose legality to be checked against the warl-legal string

Returns

A list of error strings encountered while performing the checks on a legal string

Return type

list(str)

The legal string is first broken down into smaller substrings, each of which assigns certain bits a specific value. Each substring should match the following regular-expression: \[(.*?)\]\s*(bitmask|in|not in)\s*\[(.*?)\]

For each substring, we then extract the indicies of the csr/subfield that are being assigned, the operation used (one of bitmask, in or not in) and values being assigned. Using the indices we extract the relevant sub-value of the input value argument which applies to these indices (we refer to this as subval).

In case of a bitmask operation all values of the input are considered legal - since the mask and fixedval will ensure only legal values are set.

In case of an in operation, the values list (extracted from the substring) is split into individual elements. Each element can either be a range or a single integer. In case of a range we check if the input subval falls within this range or not. In case of a single integer we perform a direct match. We parse the entire values list and stop as soon as atleast on match is detected.

In case of a not in operation, the procedure is the same as above, except we parse through the entire values list to ensure the subval doesn’t match any of those values, only then the subval is treated as a legal value.

getlegal(dependency_vals=[])[source]

This function is used to return a legal value for a given set of dependency_vals. If the dependency_vals is empty and self.dependencies is not empty, then the first legal string is picked and the assignment-string substring is dierctly evaluated to get a legal value.

Parameters

dependency_vals (dict) – This is dictionary of csr:value pairs which indicates the current value of csrs/subfields present in the dependency_fields of the warl node.

Returns

A single integer value which is considered legal for the csr under the provided dependency_vals arg

Return type

int

islegal(value, dependency_vals=None)[source]

This function is used to check if an input value is a legal value for csr for given set of dependency values. The legality is checked against all warl string listed under the legal node of the warl dictionary.

Parameters
  • value (int) – input integer whose legality needs to be checked for the csr/subfield warl node.

  • dependency_vals (dict) – This is dictionary of csr:value pairs which indicates the current value of csrs/subfields present in the dependency_fields of the warl node.

If the dependency_fields of the warl node is empty, then the single legal string in the legal list, is simply processed by the function check_subval_legal() and result of which is simply returned as is.

However, if the dependency_fields is not empty, then for each legal string we check if both dependency_vals substring is satisfied and the assignment substring is also satisfied, else an error is generated.

for the dependency_vals substring the values of the csrs in the dependency_fields if obtained either from the input dependency_vals argument or else the reset-vals of the csr in the isa spec (self.spec) are used. If neither is available, then an error is posted about the same.

The dependency_vals substring is again split further down to process each condition individually. The checks for the dependency_vals substring include:

  • checking is the csrs in the substring are indeed present in the dependency_fields list of the warl node

  • if writeval or currval is detected, then that part of the conditions is ignored.

The dependency_vals substring is treated as a boolean condition. Hence, when when each part of the substring is evaluated, we replace that part of the string with either True or False, and at the end perform an eval on the new replaced dependency_vals substring. If this condition evaluates to True, the corresponing assign string also evaluates to True, then the input value is considered legal.

Things this function does not do:

  • this does not check if the warl strings are valid. It is assumed that they are valid. If not, pass them through the function iserr to check for validity.

  • in case of dependency_fields being not empty, this function doesn’t check if the possible values of the dependency csrs/subfields are indeed legal for them. This causes a nesting problem, which is probably doesn’t warrant an immediate solution ??