Working with data files

The register parser reads a data file and constructs a RegisterList object. It is important that the data file is formatted correctly and has the necessary properties. The register parser will warn if there are any errors in the data, such as missing properties, unknown properties, wrong data type for properties, etc.

The register parser is implemented in the RegisterParser class. It can be called with the from_toml(), from_json() and from_yaml() functions.

Why TOML?

The TOML data file format is highly recommended for specifying your registers. All the examples on this website use TOML.

It is a configuration file format that is easy to both read and write. Compared to XML, YAML and JSON, which would be the most obvious alternatives, it has the following advantages that are relevant when handling FPGA registers:

Supports comments in file.
Supports hexadecimal and binary integer values, with optional underscore separator.
Clear and readable handling of multiline strings.
Duplicate key is an error.
Fewer control characters compared to XML and JSON.
Very fast Python parser available.

Furthermore, while readability can be considered subjective, the TOML format is considered quite obvious and easy to read.

TOML Format

Below is an example of a typical TOML file, which can be parsed with a call to from_toml(). It sets up:

Two registers with different modes.
1. One of which contains a bit field and an enumeration field.
A register array with two registers and fields.
An integer constant and a float constant.

See the menu sidebar for details about how to set up the different fields, constants, etc.

Also, see the “generator” articles for insight into the code that can be generated from this definition file. For example, the human-readable documentation from the data below can be seen in the HTML code generator article.

Register TOML format example.

################################################################################
[config]

# The "type" property is OPTIONAL for a register (but required for register arrays and constants).
# It is commonly left out for registers to keep line count down.
# Will default to "register" if not specified.
# The value specified MUST be "register".
type = "register"

# The "mode" property MUST be present for a register.
# The value specified MUST be a valid shorthand mode name. Either of:
# * "r" for Read.
# * "w" for Write.
# * "r_w" for Read, Write.
# * "wpulse" for Write-pulse.
# * "r_wpulse" for Read, Write-pulse.
# See https://hdl-registers.com/rst/basic_feature/basic_feature_register_modes.html for details.
mode = "r_w"

# The "description" property is OPTIONAL for a register.
# Will default to "" if not specified.
# The value specified MUST be a string.
description = """
This is the description of my register.

Rudimentary RST formatting can be used, such as **boldface** and *italics*.
"""

[config.enable]

type = "bit"
description = "Enable operation."
default_value = "1"

[config.direction]

type = "enumeration"
description = "Set the data direction."
default_value = "high_z"

element.data_in = "Receive data from outside the FPGA."
element.high_z = """
Set pins to high impedance.

Will not process any incoming data, nor send anything out.
"""
element.data_out = "Send data from FPGA."


################################################################################
[status]

mode = "r"


################################################################################
[channels]

type = "register_array"
array_length = 4
description = "Configuration for each channel."


# ------------------------------------------------------------------------------
[channels.read_address]

mode = "r_w"
description = "Read address for DMA data."


# ------------------------------------------------------------------------------
[channels.config]

mode = "w"
description = "Configuration of channel settings."

enable.type = "bit"
enable.description = "Enable this channel."

tuser.type = "bit_vector"
tuser.width = 8
tuser.description = "**TUSER** value for this channel."


################################################################################
[axi_data_width]

type = "constant"
value = 64
description = "Data width of the AXI port used by this module."


################################################################################
[clock_rate_hz]

type = "constant"
value = 156.25e6
description = "The clock rate used in the system, given in Hertz."

Using JSON data file

The TOML format is highly recommended due to the benefits it offers, listed above. Also all the examples on this website use TOML. However, the tool also supports using JSON data files if that is desired.

In this case you need to construct your JSON data on the exact format as the TOML format above and then parse it with a call to from_json().

Below is an example JSON snippet that sets up some register data:

Register JSON format example.

{
    "configuration": {
        "mode": "r_w",
        "description": "Configuration register.",
        "enable": {
            "type": "bit",
            "description": "Enable data passthrough.",
            "default_value": "1"
        }
    },
    "status": {
        "mode": "r",
        "description": "General status register."
    },
    "data_width": {
        "type": "constant",
        "value": 64,
        "description": "The width of the AXI port used by the module."
    },
    "clk_frequency_hz": {
        "type": "constant",
        "value": 156250000.0,
        "description": "The system clock frequency in Hertz."
    }
}

Using YAML data file

The TOML format is highly recommended due to the benefits it offers, listed above. Also all the examples on this website use TOML. However, the tool also supports using YAML data files if that is desired.

In this case you need to construct your YAML data on the exact format as the TOML format above and then parse it with a call to from_yaml().

Below is an example YAML snippet that sets up some register data:

Register YAML format example.

configuration:
  mode: r_w
  description: Configuration register.
  enable:
    type: bit
    default_value: '1'
    description: Enable data passthrough.

status:
  mode: r
  description: General status register.

clk_frequency_hz:
  type: constant
  value: 156250000.0
  description: The system clock frequency in Hertz.

data_width:
  type: constant
  value: 64
  description: The width of the AXI port used by the module.

Other data file formats

The TOML format is highly recommended due to the benefits it offers, listed above. We also officially support parsing JSON and YAML, see above. However, if you want to parse some other exotic data file format then that is also possible.

The parser functions, e.g. from_toml(), are just very thin wrappers around the RegisterParser class. The RegisterParser class takes register data as a Python dictionary and returns the high-level object RegisterList. So in order to implement your own parser, simply read or construct the data as Python dictionary in the exact format as described above and pass it to RegisterParser.

If you write a parser that you think others might have use for, please consider contributing to this project by creating an issue or a pull request.