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
- 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
- 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
- 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.
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.
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.
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.
uregset
()[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
-
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 orstring.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.
-
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.
-
__weakref__
¶ list of weak references to the object (if defined)
-
check_subval_legal
(legalstr, value)[source]¶ This function checks if a given value satifies the conditions present in a given legal string.
- Parameters
- Returns
A list of error strings encountered while performing the checks on a legal string
- Return type
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
-
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
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 ??