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

<module>.html

The documentation as one HTML page

Unless you give -d

<module>.md

The documentation as Markdown

Unless you give -d

<module>.tex

LaTeX source of the documentation

Unless you give -d

<module>.pdf

The documentation as PDF

Unless you give -d or -p, when pdflatex is on your PATH

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 version of 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 has Generated by bust and the bust version at the top.

  • The description of 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 that no field covers are shown as reserved fields. A register with fields also gets a list of them, with the description, sw and hw of each field, and its onread, onwrite, singlepulse and 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{reserved}{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)
    \item [reserved] Bits 31:2. Read as 0, writes have no effect.
  \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 reserved. 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

reg0

RW/R

0x00000000

FIELDS

3

0x0

1

reg1

RO/W

0x00000004

FIELDS

6

0x0

2

reg2

WO/R

0x00000008

FIELDS

1

0x0

3

reg3

RW/NA

0x0000000C

FIELDS

8

0x0

4

reg4

RW/RW

0x00000010

FIELDS

9

0x0

5

reg5

RW/R

0x00000014

FIELDS

8

0x0

6

reg6

RW/R

0x00000018

FIELDS

12

0xF0

7

reg7

RW/R

0x0000001C

FIELDS

12

0xF0

8

reg8

RW/R

0x00000020

FIELDS

8

0xF

9

reg9

RW/R

0x00000024

FIELDS

8

0x0

10

reg10

RW/R

0x00000028

FIELDS

4

0x0

11

reg11

RW/R

0x0000002C

FIELDS

2

0x0

Registers

reg0

Address 0x00000000, RW/R, reset 0x0.

Plain rw storage, hardware reads back.

Bits

Name

SW

HW

Reset

Description

31:3

reserved

Read as 0, writes have no effect.

2:1

field1

rw

r

0x0

0

field0

rw

r

0x0

reg1

Address 0x00000004, RO/W, reset 0x0.

Hardware-driven status, software read-only.

Bits

Name

SW

HW

Reset

Description

31:6

reserved

Read as 0, writes have no effect.

5

field2

ro

w

0x0

Modifiers: wel.

4

field1

ro

w

0x0

3:0

field0

ro

w

0x0

Modifiers: we.

reg2

Address 0x00000008, WO/R, reset 0x0.

Write-only command field.

Bits

Name

SW

HW

Reset

Description

31:1

reserved

Read as 0, writes have no effect.

0

field0

wo

r

0x0

reg3

Address 0x0000000C, RW/NA, reset 0x0.

Software-only scratch register.

Bits

Name

SW

HW

Reset

Description

31:8

reserved

Read as 0, writes have no effect.

7:0

field0

rw

na

0x0

reg4

Address 0x00000010, RW/RW, reset 0x0.

Hardware write-enable and hardware set/clear.

Bits

Name

SW

HW

Reset

Description

31:9

reserved

Read as 0, writes have no effect.

8

field1

rw

r

0x0

Modifiers: hwset, hwclr.

7:4

reserved

Read as 0, writes have no effect.

3:0

field0

rw

rw

0x0

Modifiers: we.

reg5

Address 0x00000014, RW/R, reset 0x0.

Read side effects.

Bits

Name

SW

HW

Reset

Description

31:8

reserved

Read as 0, writes have no effect.

7:4

field1

rw

r

0x0

onread: rset.

3:0

field0

rw

r

0x0

onread: rclr.

reg6

Address 0x00000018, RW/R, reset 0xF0.

Write-1 onwrite effects.

Bits

Name

SW

HW

Reset

Description

31:12

reserved

Read as 0, writes have no effect.

11:8

field2

rw

r

0x0

onwrite: wot.

7:4

field1

rw

r

0xF

onwrite: woclr.

3:0

field0

rw

r

0x0

onwrite: woset.

reg7

Address 0x0000001C, RW/R, reset 0xF0.

Write-0 onwrite effects.

Bits

Name

SW

HW

Reset

Description

31:12

reserved

Read as 0, writes have no effect.

11:8

field2

rw

r

0x0

onwrite: wzt.

7:4

field1

rw

r

0xF

onwrite: wzc.

3:0

field0

rw

r

0x0

onwrite: wzs.

reg8

Address 0x00000020, RW/R, reset 0xF.

Whole-field onwrite effects.

Bits

Name

SW

HW

Reset

Description

31:8

reserved

Read as 0, writes have no effect.

7:4

field1

rw

r

0x0

onwrite: wset.

3:0

field0

rw

r

0xF

onwrite: wclr.

reg9

Address 0x00000024, RW/R, reset 0x0.

Software-access pulses.

Bits

Name

SW

HW

Reset

Description

31:8

reserved

Read as 0, writes have no effect.

7:4

field1

rw

r

0x0

Modifiers: swacc.

3:0

field0

rw

r

0x0

Modifiers: swmod.

reg10

Address 0x00000028, RW/R, reset 0x0.

Single-cycle pulse on software write.

Bits

Name

SW

HW

Reset

Description

31:4

reserved

Read as 0, writes have no effect.

3:0

field0

rw

r

0x0

singlepulse.

reg11

Address 0x0000002C, RW/R, reset 0x0.

Enumerated field.

Bits

Name

SW

HW

Reset

Description

31:2

reserved

Read as 0, writes have no effect.

1:0

field0

rw

r

0x0

Values: STATE0=0, STATE1=1, STATE2=2, STATE3=3.