Documentation¶
bust writes documentation of the register map to doc/, in the output directory of the module described in Command line: as HTML, Markdown and LaTeX, and as PDF when pdflatex is installed. None of it needs anything beyond bust itself, except the PDF. This page describes each file and shows it for the prototype example.
File |
Content |
Written |
|---|---|---|
|
The documentation as one HTML page |
Unless you give |
|
The documentation as Markdown |
Unless you give |
|
LaTeX source of the documentation |
Unless you give |
|
The documentation as PDF |
Unless you give |
Content¶
doc/<module>.tex and doc/<module>.html have the same content and layout, and the PDF is built from the .tex file. They 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}
HTML¶
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.
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.
Markdown¶
doc/<module>.md holds the register map as Markdown, for reading on GitHub or GitLab or in an editor, with no LaTeX needed. It has a line with the bust version, the version of the module and the hash of the register map under the title, then the description of the module, a Register list table where each name links to its register, and a Registers section with a table of the bits of each register. The bits table lists the fields from the highest bit down, with their bits, name, sw, hw, reset value and description, followed by the onread, onwrite, singlepulse, hardware modifiers and enumeration values where the field has them. Bits that no field uses are listed as unused. A register without fields gets one row, named after the register.
In descriptions, a `code` span is kept, and the characters that Markdown would read as markup, such as * and |, are escaped. Line breaks become spaces.
This is prototype.md of the prototype example as this site renders it. The file itself is example/example_prototype/doc/prototype.md.
prototype¶
Generated by bust v1.0.0-dev. Version: 1.0. Register map hash: 0x593FA68E.
Comprehensive example exercising every v1 access mode, mirroring the prototype demo module (reg0..reg11).
Register list¶
# |
Name |
SW/HW |
Address |
Type |
Width |
Reset |
|---|---|---|---|---|---|---|
0 |
RW/R |
|
FIELDS |
3 |
|
|
1 |
RO/W |
|
FIELDS |
6 |
|
|
2 |
WO/R |
|
FIELDS |
1 |
|
|
3 |
RW/NA |
|
FIELDS |
8 |
|
|
4 |
RW/RW |
|
FIELDS |
9 |
|
|
5 |
RW/R |
|
FIELDS |
8 |
|
|
6 |
RW/R |
|
FIELDS |
12 |
|
|
7 |
RW/R |
|
FIELDS |
12 |
|
|
8 |
RW/R |
|
FIELDS |
8 |
|
|
9 |
RW/R |
|
FIELDS |
8 |
|
|
10 |
RW/R |
|
FIELDS |
4 |
|
|
11 |
RW/R |
|
FIELDS |
2 |
|
Registers¶
reg0¶
Address 0x00000000, RW/R, reset 0x0.
Plain rw storage, hardware reads back.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:3 |
unused |
||||
2:1 |
field1 |
rw |
r |
|
|
0 |
field0 |
rw |
r |
|
reg1¶
Address 0x00000004, RO/W, reset 0x0.
Hardware-driven status, software read-only.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:6 |
unused |
||||
5 |
field2 |
ro |
w |
|
Modifiers: wel. |
4 |
field1 |
ro |
w |
|
|
3:0 |
field0 |
ro |
w |
|
Modifiers: we. |
reg2¶
Address 0x00000008, WO/R, reset 0x0.
Write-only command field.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:1 |
unused |
||||
0 |
field0 |
wo |
r |
|
reg3¶
Address 0x0000000C, RW/NA, reset 0x0.
Software-only scratch register.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:8 |
unused |
||||
7:0 |
field0 |
rw |
na |
|
reg4¶
Address 0x00000010, RW/RW, reset 0x0.
Hardware write-enable and hardware set/clear.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:9 |
unused |
||||
8 |
field1 |
rw |
r |
|
Modifiers: hwset, hwclr. |
7:4 |
unused |
||||
3:0 |
field0 |
rw |
rw |
|
Modifiers: we. |
reg5¶
Address 0x00000014, RW/R, reset 0x0.
Read side effects.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:8 |
unused |
||||
7:4 |
field1 |
rw |
r |
|
onread: rset. |
3:0 |
field0 |
rw |
r |
|
onread: rclr. |
reg6¶
Address 0x00000018, RW/R, reset 0xF0.
Write-1 onwrite effects.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:12 |
unused |
||||
11:8 |
field2 |
rw |
r |
|
onwrite: wot. |
7:4 |
field1 |
rw |
r |
|
onwrite: woclr. |
3:0 |
field0 |
rw |
r |
|
onwrite: woset. |
reg7¶
Address 0x0000001C, RW/R, reset 0xF0.
Write-0 onwrite effects.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:12 |
unused |
||||
11:8 |
field2 |
rw |
r |
|
onwrite: wzt. |
7:4 |
field1 |
rw |
r |
|
onwrite: wzc. |
3:0 |
field0 |
rw |
r |
|
onwrite: wzs. |
reg8¶
Address 0x00000020, RW/R, reset 0xF.
Whole-field onwrite effects.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:8 |
unused |
||||
7:4 |
field1 |
rw |
r |
|
onwrite: wset. |
3:0 |
field0 |
rw |
r |
|
onwrite: wclr. |
reg9¶
Address 0x00000024, RW/R, reset 0x0.
Software-access pulses.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:8 |
unused |
||||
7:4 |
field1 |
rw |
r |
|
Modifiers: swacc. |
3:0 |
field0 |
rw |
r |
|
Modifiers: swmod. |
reg10¶
Address 0x00000028, RW/R, reset 0x0.
Single-cycle pulse on software write.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:4 |
unused |
||||
3:0 |
field0 |
rw |
r |
|
singlepulse. |
reg11¶
Address 0x0000002C, RW/R, reset 0x0.
Enumerated field.
Bits |
Name |
SW |
HW |
Reset |
Description |
|---|---|---|---|---|---|
31:2 |
unused |
||||
1:0 |
field0 |
rw |
r |
|
Values: STATE0=0, STATE1=1, STATE2=2, STATE3=3. |