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. It is accessed via the PythonPickleGenerator class.

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.python.pickle import PythonPickleGenerator
 7from hdl_registers.parser.toml import from_toml
 8
 9THIS_DIR = Path(__file__).parent
10
11
12def main(output_folder: Path):
13    """
14    Create register Python artifacts from the TOML example file.
15    """
16    register_list = from_toml(
17        name="example",
18        toml_file=THIS_DIR.parent.parent / "user_guide" / "toml" / "toml_format.toml",
19    )
20
21    PythonPickleGenerator(register_list=register_list, output_folder=output_folder).create()
22
23
24if __name__ == "__main__":
25    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 5.1.1-dev.
 2# Code generator PythonPickleGenerator version 1.0.0.
 3# Generated 2024-02-29 20:51 from file toml_format.toml at commit 4b70b6f413ca5a88.
 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.