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() and from_json() functions.

Why TOML?

The TOML data file format is highly recommended for specifying your registers.

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 ley 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:

1. Two registers with different modes.

   1. One of which contains a bit field and an enumeration field.

2. A register array with two registers and fields.

3. 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.

################################################################################
[register.config]

# 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*.
"""

[register.config.bit.enable]

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

[register.config.enumeration.direction]

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."


################################################################################
[register.status]

mode = "r"


################################################################################
[register_array.channels]

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


# ------------------------------------------------------------------------------
[register_array.channels.register.read_address]

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


# ------------------------------------------------------------------------------
[register_array.channels.register.config]

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

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

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


################################################################################
[constant.axi_data_width]

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


################################################################################
[constant.clock_rate_hz]

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 are using 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.

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

Other data file formats

The TOML format is highly recommended due to the benefits it offers, listed above. However, if using another data file format is necessary then that is also possible. See this article for details: Using other data file formats.