Bit vector constants

Register constants can be of type bit_vector. This page will show you how the set up bit vector constants, as well as showcase all the code that can be generated from it.

The typical use case for a bit vector constant is when a number needs to be represented that is beyond the allowed 32-bit range of a VHDL integer.

Usage in TOML

The TOML file below shows how to set up a register list with two bit vector constants. Note that in the TOML, the type of the constant is determined by the type of the literal value.

TOML that sets up a register list with bit vector constants.
 1# This will allocate a register constant with the name "base_address" of data type
 2# unsigned bit vector.
 3[base_address]
 4
 5# The "type" property MUST be present and set to "constant".
 6type = "constant"
 7
 8# The "value" property MUST be present for a bit vector constant.
 9# The value specified MUST be a string, and MUST start with either "0x" or "0b".
10# Underscore (_) is allowed as a separator.
11value = "0xA_0000_0000"
12
13# The "data_type" MUST be provided to instruct the parser to interpret the "value" as an unsigned
14# bit vector rather than a string.
15data_type = "unsigned"
16
17# The "description" property is OPTIONAL for a constant.
18# Will default to "" if not specified.
19# The value specified MUST be a string.
20description = "Base address for this module on the register bus."
21
22
23[data_mask]
24
25type = "constant"
26value = "0b1100_1111"
27data_type = "unsigned"

Note that the second constant does not have a description specified, meaning it will default to an empty string.

Below you will see how you can parse this TOML file and generate artifacts from it.

Usage with Python API

The Python code below shows

  1. How to parse the TOML file listed above.

  2. How to create an identical register list when instead using the Python API.

  3. How to generate register artifacts.

Note that the result of the create_from_api call is identical to that of the parse_toml call. Meaning that using a TOML file or using the Python API is completely equivalent. You choose yourself which method you want to use in your code base.

Python code that sets up a register list with bit vector constants.
 1# Standard libraries
 2import sys
 3from pathlib import Path
 4
 5# First party libraries
 6from hdl_registers.constant.bit_vector_constant import UnsignedVector
 7from hdl_registers.generator.c.header import CHeaderGenerator
 8from hdl_registers.generator.cpp.interface import CppInterfaceGenerator
 9from hdl_registers.generator.html.page import HtmlPageGenerator
10from hdl_registers.generator.vhdl.register_package import VhdlRegisterPackageGenerator
11from hdl_registers.parser.toml import from_toml
12from hdl_registers.register_list import RegisterList
13
14THIS_DIR = Path(__file__).parent
15
16
17def parse_toml() -> RegisterList:
18    """
19    Create the register list by parsing a TOML data file.
20    """
21    return from_toml(name="caesar", toml_file=THIS_DIR.parent / "toml" / "constant_bit_vector.toml")
22
23
24def create_from_api() -> RegisterList:
25    """
26    Alternative method: Create the register list by using the Python API.
27    """
28    register_list = RegisterList(name="caesar")
29
30    register_list.add_constant(
31        name="base_address",
32        value=UnsignedVector("0xA_0000_0000"),
33        description="Base address for this module on the register bus.",
34    )
35
36    register_list.add_constant(
37        name="data_mask", value=UnsignedVector("0b1100_1111"), description=""
38    )
39
40    return register_list
41
42
43def generate(register_list: RegisterList, output_folder: Path):
44    """
45    Generate the artifacts that we are interested in.
46    """
47    CHeaderGenerator(register_list=register_list, output_folder=output_folder).create()
48    CppInterfaceGenerator(register_list=register_list, output_folder=output_folder).create()
49    HtmlPageGenerator(register_list=register_list, output_folder=output_folder).create()
50    VhdlRegisterPackageGenerator(register_list=register_list, output_folder=output_folder).create()
51
52
53def main(output_folder: Path):
54    generate(register_list=parse_toml(), output_folder=output_folder / "toml")
55    generate(register_list=create_from_api(), output_folder=output_folder / "api")
56
57
58if __name__ == "__main__":
59    main(output_folder=Path(sys.argv[1]))

See RegisterList.add_constant() for more Python API details.

Generated code

See below for a description of the code that can be generated with these constants.

Note that the examples on this page set up a register list with only constants, no registers. This allowed of course, but albeit a little bit rare.

HTML page

See HTML file below for the human-readable documentation that is produced by the generate() call in the Python example above.

HTML page

VHDL package

The VHDL code below is produced by the generate() call in the Python example above. Click the button to expand and view the code.

Note that the values are available as vectors rather than integers. The width of the vector is determined by the string value provided by the user above.

Click to expand/collapse code.
Generated VHDL code.
 1-- This file is automatically generated by hdl-registers version 6.1.1-dev.
 2-- Code generator VhdlRegisterPackageGenerator version 1.0.0.
 3-- Generated 2024-12-01 20:51 at commit 2ca830a4377d1e32.
 4-- Register hash ab4682176503ca21e3d1e995f4fb0f197c8c3ae8.
 5
 6library ieee;
 7use ieee.std_logic_1164.all;
 8use ieee.numeric_std.all;
 9use ieee.fixed_pkg.all;
10
11library reg_file;
12use reg_file.reg_file_pkg.all;
13
14
15package caesar_regs_pkg is
16
17  -- ---------------------------------------------------------------------------
18  -- Values of register constants.
19  constant caesar_constant_base_address : unsigned(36 - 1 downto 0) := x"A_0000_0000";
20  constant caesar_constant_data_mask : unsigned(8 - 1 downto 0) := "11001111";
21
22end package;

C++ interface

The C++ interface header code below is produced by the generate() call in the Python example above. Click the button to expand and view the code.

Click to expand/collapse code.
Generated C++ interface class code.
 1// This file is automatically generated by hdl-registers version 6.1.1-dev.
 2// Code generator CppInterfaceGenerator version 1.0.0.
 3// Generated 2024-12-01 20:51 at commit 2ca830a4377d1e32.
 4// Register hash ab4682176503ca21e3d1e995f4fb0f197c8c3ae8.
 5
 6#pragma once
 7
 8#include <cassert>
 9#include <cstdint>
10#include <cstdlib>
11
12namespace fpga_regs
13{
14
15  class ICaesar
16  {
17  public:
18    // Register constant.
19    static const auto base_address = 0xA00000000;
20    // Register constant.
21    static const auto data_mask = 0b11001111;
22
23    // Number of registers within this register map.
24    static const size_t num_registers = 0uL;
25
26    virtual ~ICaesar() {}
27
28  };
29
30} /* namespace fpga_regs */

C header

The C code below is produced by the generate() call in the Python example above.

Click to expand/collapse code.
Generated C code.
 1// This file is automatically generated by hdl-registers version 6.1.1-dev.
 2// Code generator CHeaderGenerator version 1.0.0.
 3// Generated 2024-12-01 20:51 at commit 2ca830a4377d1e32.
 4// Register hash ab4682176503ca21e3d1e995f4fb0f197c8c3ae8.
 5
 6#ifndef CAESAR_REGS_H
 7#define CAESAR_REGS_H
 8
 9// Value of register constant 'base_address'.
10#define CAESAR_BASE_ADDRESS (0xA00000000UL)
11// Value of register constant 'data_mask'.
12#define CAESAR_DATA_MASK (0b11001111UL)
13
14// Number of registers within this register map.
15#define CAESAR_NUM_REGS (0u)
16
17// Type for this register map.
18typedef struct caesar_regs_t
19{
20} caesar_regs_t;
21
22#endif // CAESAR_REGS_H