Headers and documentation¶
Next to the VHDL, bust writes headers that give software the addresses and bit
positions of the registers, an address table for IPBus, and documentation of the register map as LaTeX, HTML and, when pdflatex is installed, PDF. This page describes what each file holds and how to use it.
Files¶
bust writes the headers to header/ and the documentation to doc/, in the
output directory of the module described in
Command line.
File |
Content |
Written |
|---|---|---|
|
C header with |
Unless you give |
|
C++ header with constants in a namespace |
Unless you give |
|
Python module with constants in a class |
Unless you give |
|
IPBus address table for uHAL |
For the |
|
LaTeX source of the documentation |
Unless you give |
|
The documentation as one HTML page |
Unless you give |
|
The documentation as PDF |
Unless you give |
Constant names¶
The C, C++ and Python headers define the same constants. Each name starts with
the register name in upper case, followed by the field name for a field
property. In the C header, every name also starts with the module name, as
<MODULE>_<REG>_OFFSET, because C has no namespaces. The C++ and Python
headers put the names in a namespace and a class named after the module
instead.
Two names belong to the module rather than a register: REGMAP_VERSION and
REGMAP_HASH.
Constant |
Value |
|---|---|
|
Address of the register, relative to the base address of the module, in hex. The unit is the address unit of the bus: bytes, or 32-bit words for IPBus. |
|
Number of bits the register uses, up to and including its highest field bit. |
|
Reset value of the whole register. |
|
Software and hardware access, as a string such as |
|
Lowest bit of the field. |
|
Number of bits in the field. |
|
Reset value of the field. |
|
The bits of the field, in their place in the register. |
|
Software and hardware access of the field. |
|
|
|
The |
|
|
|
One constant for each value of an enumerated field. |
|
The |
|
The 32-bit hash of the register map. See Version and hash. |
A register without fields has no field constants. Its ONREAD, ONWRITE and
SINGLEPULSE constants are named after the register alone, as in
REG9_SINGLEPULSE in the AXI4-Lite example of the repository
(EXAMPLE_AXI_REG9_SINGLEPULSE in C).
_OFFSET is an address for a register and a bit position for a field. The
hardware modifiers (we, wel, hwset, hwclr, swmod, swacc) only
concern the hardware side, so the headers leave them out.
Access modes describes the access keywords.
The examples below come from prototype.h, prototype.hpp and prototype.py
of the prototype example in the repository, trimmed to one register. In that
module, reg11 has one enumerated field, field0, with the values STATE0 to
STATE3.
C¶
The C header holds only comments and #define lines, with an include guard
named after the module:
#ifndef PROTOTYPE_H
#define PROTOTYPE_H
/* Register map version and content hash */
#define PROTOTYPE_REGMAP_VERSION "1.0"
#define PROTOTYPE_REGMAP_HASH 0x593FA68E
/* Register: reg11 */
#define PROTOTYPE_REG11_WIDTH 2
#define PROTOTYPE_REG11_OFFSET 0x2c
#define PROTOTYPE_REG11_RESET 0x0
#define PROTOTYPE_REG11_SW "rw"
#define PROTOTYPE_REG11_HW "r"
/* Field: field0 */
#define PROTOTYPE_REG11_FIELD0_OFFSET 0
#define PROTOTYPE_REG11_FIELD0_WIDTH 2
#define PROTOTYPE_REG11_FIELD0_RESET 0x0
#define PROTOTYPE_REG11_FIELD0_MASK 0x3
#define PROTOTYPE_REG11_FIELD0_SW "rw"
#define PROTOTYPE_REG11_FIELD0_HW "r"
#define PROTOTYPE_REG11_FIELD0_STATE0 0
#define PROTOTYPE_REG11_FIELD0_STATE1 1
#define PROTOTYPE_REG11_FIELD0_STATE2 2
#define PROTOTYPE_REG11_FIELD0_STATE3 3
#endif
Add <MODULE>_<REG>_OFFSET to the base address of the module to get the
address of a register. Use _MASK and _OFFSET of a field to read or change it:
#include <stdint.h>
#include "prototype.h"
uint32_t value = read32(PROTOTYPE_BASE + PROTOTYPE_REG11_OFFSET);
uint32_t state = (value & PROTOTYPE_REG11_FIELD0_MASK) >> PROTOTYPE_REG11_FIELD0_OFFSET;
if (state == PROTOTYPE_REG11_FIELD0_STATE0) {
value = (value & ~PROTOTYPE_REG11_FIELD0_MASK)
| (PROTOTYPE_REG11_FIELD0_STATE2 << PROTOTYPE_REG11_FIELD0_OFFSET);
write32(PROTOTYPE_BASE + PROTOTYPE_REG11_OFFSET, value);
}
read32, write32 and PROTOTYPE_BASE stand for whatever your platform uses.
The module name in each constant keeps the headers of two modules apart, so
one source file can include both.
C++¶
The C++ header has the same constants as const values in a namespace named
after the module, in upper case. Numbers are uint32_t and access strings are
std::string:
#ifndef PROTOTYPE_HPP
#define PROTOTYPE_HPP
#include <cstdint>
#include <string>
namespace PROTOTYPE
{
/* Register map version and content hash */
const std::string REGMAP_VERSION = "1.0";
const uint32_t REGMAP_HASH = 0x593FA68E;
/* Register: reg11 */
const uint32_t REG11_WIDTH = 2;
const uint32_t REG11_OFFSET = 0x2c;
const uint32_t REG11_RESET = 0x0;
const std::string REG11_SW = "rw";
const std::string REG11_HW = "r";
/* Field: field0 */
const uint32_t REG11_FIELD0_OFFSET = 0;
const uint32_t REG11_FIELD0_WIDTH = 2;
const uint32_t REG11_FIELD0_RESET = 0x0;
const uint32_t REG11_FIELD0_MASK = 0x3;
const std::string REG11_FIELD0_SW = "rw";
const std::string REG11_FIELD0_HW = "r";
const uint32_t REG11_FIELD0_STATE0 = 0;
const uint32_t REG11_FIELD0_STATE1 = 1;
const uint32_t REG11_FIELD0_STATE2 = 2;
const uint32_t REG11_FIELD0_STATE3 = 3;
};
#endif
Refer to them as PROTOTYPE::REG11_OFFSET.
Python¶
The Python module has the constants as attributes of a class named
<MODULE>_H. It is formatted as black formats it, with upper-case hex digits,
so black leaves it unchanged in a project that uses black:
class PROTOTYPE_H:
"""Register map version and content hash"""
REGMAP_VERSION = "1.0"
REGMAP_HASH = 0x593FA68E
"""Register: reg11"""
REG11_WIDTH = 2
REG11_OFFSET = 0x2C
REG11_RESET = 0x0
REG11_SW = "rw"
REG11_HW = "r"
""" Field: field0 """
REG11_FIELD0_OFFSET = 0
REG11_FIELD0_WIDTH = 2
REG11_FIELD0_RESET = 0x0
REG11_FIELD0_MASK = 0x3
REG11_FIELD0_SW = "rw"
REG11_FIELD0_HW = "r"
REG11_FIELD0_STATE0 = 0
REG11_FIELD0_STATE1 = 1
REG11_FIELD0_STATE2 = 2
REG11_FIELD0_STATE3 = 3
Import the class and use it as a namespace:
from prototype import PROTOTYPE_H as regs
value = read32(base + regs.REG11_OFFSET)
state = (value & regs.REG11_FIELD0_MASK) >> regs.REG11_FIELD0_OFFSET
IPBus address table¶
For a module with the ipbus bus type, bust also writes header/<module>.xml,
an address table for the IPBus software library
uHAL.
It has one top-level node named after the module, one node for each register,
and one child node for each field. The parameters of the top-level node hold
the version of the module and the hash of the register map. This excerpt comes from example_ipbus.xml
in the repository:
<?xml version="1.0" encoding="UTF-8"?>
<node id="example_ipbus" parameters="regmap_version=1.0;regmap_hash=0xFCD085B6">
<node id="reg6" address="0x00000018" permission="r" description="Default RO register" parameters="reset=0x0"/>
<node id="reg7" address="0x0000001C" permission="rw" description="RW register that have multiple fields" parameters="reset=0xad7">
<node id="field0" mask="0x1" permission="rw" description="std_logic that resets to 0x1" parameters="reset=0x1"/>
<node id="field1" mask="0x1e" permission="rw" description="std_logic_vector[3:0] that resets to 0xb is not a valid reset value" parameters="reset=0xb"/>
<node id="field2" mask="0x20" permission="rw" description="std_logic that resets to 0x1" parameters="reset=0x0"/>
<node id="field3" mask="0x1fffc0" permission="rw" description="std_logic_vector[14:0] that resets to 0x2b" parameters="reset=0x2b"/>
</node>
</node>
Attribute |
On |
Value |
|---|---|---|
|
Register, field |
The name from the JSON file. |
|
Register |
The address of the register in 32-bit words, relative to the module. |
|
Field |
The bits of the field in the register, as |
|
Register, field |
|
|
Register, field |
The description from the JSON file, with |
|
Module |
|
|
Register, field |
|
The permission comes from the software access:
Software access |
|
|---|---|
|
|
|
|
|
|
|
No node |
Each field gets the permission of its own sw, so a read-only field in a
read-write register is read-only through uHAL. A register gets the permission
of the summary its fields give, the same value as <REG>_SW in the headers.
Registers and fields that software cannot access get no node, since uHAL cannot
reach them.
The addresses start at 0 for the module. To place the module in your system, refer to the file from your top-level address table, at the base address of the module:
<node id="example_ipbus" module="file://example_ipbus.xml" address="0x00001000"/>
Documentation¶
bust writes the documentation of the register map twice, as doc/<module>.tex and as doc/<module>.html, with the same content and layout. Neither needs anything beyond bust itself. Both contain:
A title with the module name, the
versionof the module, the hash of the register map, and the date and time of the run (for the PDF, the time it was built). Each page hasGenerated by bustand the bust version at the top.The
descriptionof the module.Register List, a table of every register with its number, name, software and hardware access, address, type, width and reset value.
Registers, a section for each register with its description and a diagram of its bits, with the field names, bit positions and reset values. The bits above the highest field are marked unused. A register with fields also gets a list of them, with the description,
swandhwof each field, and itsonread,onwrite,singlepulseand enumeration values where it has them.
In descriptions, a `code` span is set in typewriter type. In the LaTeX document, a character that LaTeX cannot print, such as an emoji, is left out.
This is the section for reg11 from prototype.tex:
\begin{register}{H}{reg11 - RW/R}{0x0000002C} \par Enumerated field. \regnewline
\label{reg11}
\regfield{unused}{30}{2}{-}
\regfield{field0}{2}{0}{{0x0}}
\reglabel{Reset}\regnewline
\begin{regdesc}\begin{reglist}[field0]
\item [field0] (sw: rw, hw: r; values: STATE0=0, STATE1=1, STATE2=2, STATE3=3)
\end{reglist}\end{regdesc}
\end{register}
The HTML page¶
doc/<module>.html is one self-contained file: the styles are in the page and the bit diagrams are inline SVG, so it opens in any browser and can be copied or served on its own. On top of the layout of the LaTeX document it adds links: each row of the register list links to the section of its register, a sidebar lists every register, and each section links back to the register list. The page has a print stylesheet that hides the sidebar and the links back, so printing it to PDF from a browser gives a clean document without pdflatex.
This is the page bust writes for the prototype example, example/example_prototype.json in the repository. Open it on its own to try the links and the print layout.
The PDF¶
When pdflatex is on your PATH, bust runs it once on the .tex file to make the PDF:
pdflatex --interaction=batchmode --output-directory=<doc dir> <doc dir>/<module>.tex
pdflatex must be on your PATH, with the LaTeX packages the document uses:
fancyhdr, datetime, geometry, register, enumitem, calc, tabularx
and listings. On Debian and Ubuntu, the packages texlive-latex-base,
texlive-latex-recommended and texlive-latex-extra provide them.
pdflatex writes <module>.pdf to doc/, together with its <module>.aux
and <module>.log files.
This is the PDF of the prototype example. Open it on its own if your browser does not show it here.
When pdflatex is not on your PATH, bust writes the .tex and .html files, prints pdflatex is not on PATH, so bust skipped the PDF. followed by the path of the HTML page, and exits with status 0.
bust runs pdflatex in batch mode and does not show its output. When
pdflatex reports errors, bust prints pdflatex reported errors. See <doc dir>/<module>.log. When it cannot run pdflatex at all, it prints
Could not run pdflatex (...). Use -p to skip the PDF. In both cases it
carries on: the other files are written and bust exits with status 0.
To build the PDF in your own flow instead, give -p. bust then writes the
.tex and .html files but does not run pdflatex. Give -d to skip the documentation
altogether.