hdl_registers.parser package

Submodules

hdl_registers.parser.json module

hdl_registers.parser.json.from_json(name: str, json_file: Path, default_registers: list[Register] | None = None) → RegisterList

Parse a JSON file with register data.

Parameters:

name – The name of the register list.
json_file – The JSON file path.
default_registers – List of default registers.

Returns:

The resulting register list.

hdl_registers.parser.parser module

class hdl_registers.parser.parser.RegisterParser(name: str, source_definition_file: Path, default_registers: list[Register] | None = None)

Bases: object

Parse register data in the form of a dictionary into a RegisterList object. See Working with data files for further documentation.

A note on sanity check strategy: The parser performs only the basic sanity checks related to the data file format. For example, missing properties, unknown properties, etc. A lot of other sanity checks are performed in the Register, RegisterArray, RegisterField, etc, classes themselves.

For example, the default value of a bit field should be a string with the value “0” or “1”. This is checked in the constructor of the Bit class, not here in the parser. Similar for a lot of other things.

This is because these objects can be created from the Python API also, without involving the parser. Hence these sanity checks have to be present there. Having them also in the parser would enable better error messages, but would be redundant and would slow down the parser. Since the parser is run in real time, the performance is critical, and we can not afford to slow it down.

__init__(name: str, source_definition_file: Path, default_registers: list[Register] | None = None)

Parameters:

name – The name of the register list.
source_definition_file – The source file that defined this register list. Will be displayed in generated source code and documentation for traceability.
default_registers – List of default registers. Note that this list with Register objects will be deep copied, so you can use the same list many times without worrying about mutability.

default_register_array_items = {'array_length', 'description', 'type'}

default_register_items = {'description', 'mode', 'type'}

parse(register_data: dict[str, Any]) → RegisterList

Parse the register data.

Parameters:: register_data – Register data as a dictionary. Preferably read by the from_toml(), from_json() or from_yaml() functions.
Returns:: The resulting register list.

recognized_bit_items = {'default_value', 'description', 'type'}

recognized_bit_vector_items = {'default_value', 'description', 'type', 'width'}

recognized_constant_items = {'data_type', 'description', 'type', 'value'}

recognized_enumeration_items = {'default_value', 'description', 'element', 'type'}

recognized_integer_items = {'default_value', 'description', 'max_value', 'min_value', 'type'}

required_bit_items: list[str] = []

required_bit_vector_items = ['width']

required_constant_items = ['value']

required_enumeration_items = ['element']

required_integer_items = ['max_value']

required_register_array_items = ['array_length']

hdl_registers.parser.toml module

hdl_registers.parser.toml.from_toml(name: str, toml_file: Path, default_registers: list[Register] | None = None) → RegisterList

Parse a TOML file with register data.

Parameters:

name – The name of the register list.
toml_file – The TOML file path.
default_registers – List of default registers.

Returns:

The resulting register list.

hdl_registers.parser.yaml module

hdl_registers.parser.yaml.from_yaml(name: str, yaml_file: Path, default_registers: list[Register] | None = None) → RegisterList