Python code generator

The Python code “generator” is an automated way of saving a RegisterList object to a Python pickle. It is not intended to be used during development, but bundling the Python class pickles when making an FPGA release can be very useful.

The pickle is created e.g. like this:

Python code that parses the example TOML file and generates Python register artifacts.
 1# Standard libraries
 2import sys
 3from pathlib import Path
 4
 5# First party libraries
 6from hdl_registers.generator.html.constant_table import HtmlConstantTableGenerator
 7from hdl_registers.generator.html.page import HtmlPageGenerator
 8from hdl_registers.generator.html.register_table import HtmlRegisterTableGenerator
 9from hdl_registers.parser.toml import from_toml
10
11THIS_DIR = Path(__file__).parent
12
13
14def main(output_folder: Path):
15    """
16    Create register HTML artifacts from the TOML example file.
17    """
18    register_list = from_toml(
19        name="example",
20        toml_file=THIS_DIR.parent.parent / "user_guide" / "toml" / "toml_format.toml",
21    )
22
23    HtmlPageGenerator(register_list=register_list, output_folder=output_folder).create()
24    HtmlRegisterTableGenerator(register_list=register_list, output_folder=output_folder).create()
25    HtmlConstantTableGenerator(register_list=register_list, output_folder=output_folder).create()
26
27
28if __name__ == "__main__":
29    main(output_folder=Path(sys.argv[1]))

This will save the binary pickle, which represents the object precisely, as well as a convenient Python file to re-create the pickle, shown below:

Example Python class
 1# This file is automatically generated by hdl-registers version 4.1.1-dev2.
 2# Code generator PythonClassGenerator version 1.0.0.
 3# Generated 2023-12-04 10:43 from file toml_format.toml at commit d6ece437d0e3b2bc.
 4# Register hash 0d636d16ec9bdadff4d5e144aaacd9416830c91d.
 5
 6# Standard libraries
 7import pickle
 8from pathlib import Path
 9from typing import TYPE_CHECKING
10
11if TYPE_CHECKING:
12    # Third party libraries
13    from hdl_registers.register_list import RegisterList
14
15THIS_DIR = Path(__file__).parent
16
17
18class Example:
19
20    """
21    Instantiate this class to get the RegisterList object for the 'example' module.
22    """
23
24    def __new__(cls):
25        """
26        Recreate the RegisterList object from binary pickle.
27        """
28        with (THIS_DIR / "example.pickle").open("rb") as file_handle:
29            return pickle.load(file_handle)
30
31
32def get_register_list() -> "RegisterList":
33    """
34    Return a RegisterList object with the registers/constants from the 'example' module.
35    Recreated from a Python pickle file.
36    """
37    return Example()

A Python-based system test environment can use the re-created RegisterList objects from the FPGA release to perform register reads/writes on the correct registers addresses and field indexes.