diff --git a/CHANGELOG.md b/CHANGELOG.md index f7c211d..2c56f78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). ### Added - `bust.generate_files` returns every output file as `{path: content}`, without writing to disk or running `pdflatex`. The command line writes that result. - `doc/.html`, the documentation as one self-contained HTML page with inline SVG bit diagrams, links between the register list and the registers, a sidebar and a print stylesheet. +- `doc/.md`, the documentation as Markdown, with the register list and a bits table per register, readable on GitHub. ### Changed - bust builds the PDF only when `pdflatex` is on `PATH`. Without it, bust writes the `.tex` and `.html` files and prints one line saying the PDF was skipped. diff --git a/README.md b/README.md index 509eee1..b37a448 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ A minimal register map with one control register with two fields: bust blinky.json -o out -p ``` -This writes `out/blinky/` with the VHDL in `hdl/`, the testbench in `tb/`, the headers in `header/` and the documentation in `doc/`, as HTML and LaTeX, plus a PDF when `pdflatex` is installed. `hdl/blinky.vhd` is a starter top level that is yours to edit: bust writes it once and leaves it alone after that. Your logic reads `to_hw.ctrl.enable` and `to_hw.ctrl.rate` from `blinky_axi_endpoint`, which bust regenerates on every run. +This writes `out/blinky/` with the VHDL in `hdl/`, the testbench in `tb/`, the headers in `header/` and the documentation in `doc/`, as HTML, Markdown and LaTeX, plus a PDF when `pdflatex` is installed. `hdl/blinky.vhd` is a starter top level that is yours to edit: bust writes it once and leaves it alone after that. Your logic reads `to_hw.ctrl.enable` and `to_hw.ctrl.rate` from `blinky_axi_endpoint`, which bust regenerates on every run. ## How bust is tested diff --git a/bust/__main__.py b/bust/__main__.py index 27566f1..27dcdbc 100644 --- a/bust/__main__.py +++ b/bust/__main__.py @@ -9,7 +9,7 @@ Options: -o DIR Specify output directory (default: the directory of FILE) -f Force overwrite of existing files, except .vhd, which is yours - -d Do not generate documentation (LaTeX, HTML or PDF) + -d Do not generate documentation (LaTeX, HTML, Markdown or PDF) -p Do not generate PDF from LaTeX, even if pdflatex is installed -i Do not generate the include header files (.h, .hpp & .py) --replace-top Replace .vhd with a fresh starter, keeping the old file as .vhd.bak diff --git a/bust/generation.py b/bust/generation.py index 21369ee..e917b2e 100644 --- a/bust/generation.py +++ b/bust/generation.py @@ -69,7 +69,7 @@ def module_outputs( localbus: Include the local-bus VHDL stack, the starter top level and the testbench. headers: Include the language headers. - documentation: Include the LaTeX and HTML documentation. + documentation: Include the LaTeX, HTML and Markdown documentation. Returns: The content of each file by its path relative to the output directory, @@ -112,6 +112,7 @@ def module_outputs( base = f"{name}/{settings.doc_dir}/{name}" outputs[f"{base}.tex"] = doc.generate_tex_documentation() outputs[f"{base}.html"] = doc.generate_html_documentation() + outputs[f"{base}.md"] = doc.generate_markdown_documentation() return outputs diff --git a/bust/generators/documentation_generator.py b/bust/generators/documentation_generator.py index 024b322..da241cd 100644 --- a/bust/generators/documentation_generator.py +++ b/bust/generators/documentation_generator.py @@ -1,7 +1,7 @@ """Documentation generation module for bust. This module provides the DocumentationGenerator class for automatically generating -LaTeX and HTML documentation from module definitions. The generated documentation +LaTeX, HTML and Markdown documentation from module definitions. The generated documentation includes register maps, bit field descriptions, and access modes. """ @@ -89,7 +89,7 @@ def _text(x, y, text, anchor, css_class): class DocumentationGenerator: """Generates documentation for bus slave modules. - The DocumentationGenerator class creates LaTeX and HTML documentation with complete register + The DocumentationGenerator class creates LaTeX, HTML and Markdown documentation with complete register specifications including addresses, bit positions, access modes, and descriptions. @@ -164,3 +164,14 @@ def generate_html_documentation(self, test_version=None): field_notes=field_notes, bit_diagram_svg=bit_diagram_svg, ) + + def generate_markdown_documentation(self, test_version=None): + """Generate Markdown documentation for the module, readable on GitHub. + + Args: + test_version: Version string for testing (default: None, uses bust version). + + Returns: + Markdown document as string. + """ + return self._render_template("markdown/documentation.j2", test_version) diff --git a/bust/jinja_utils/environment.py b/bust/jinja_utils/environment.py index 4a03d98..07656b4 100644 --- a/bust/jinja_utils/environment.py +++ b/bust/jinja_utils/environment.py @@ -34,7 +34,7 @@ def get_environment(additional_filters=None): Environment: Configured Jinja2 environment with: - Template directory set to bust/templates - trim_blocks=True and lstrip_blocks=True for clean output - - Common filters registered (hex_format, utf8tolatex, utf8tohtml, indent_all) + - Common filters registered (hex_format, utf8tolatex, utf8tohtml, markdown_cell, indent_all) - Additional filters if provided """ # Get template directory relative to this module @@ -50,6 +50,7 @@ def get_environment(additional_filters=None): # Register common filters used across modules from bust.jinja_utils.filters import ( align, + markdown_cell, to_binary, utf8tohtml, utf8tolatex, @@ -57,6 +58,7 @@ def get_environment(additional_filters=None): ) env.filters["align"] = align + env.filters["markdown_cell"] = markdown_cell env.filters["to_binary"] = to_binary env.filters["utf8tolatex"] = utf8tolatex env.filters["utf8tohtml"] = utf8tohtml diff --git a/bust/jinja_utils/filters.py b/bust/jinja_utils/filters.py index d35a916..1b12841 100644 --- a/bust/jinja_utils/filters.py +++ b/bust/jinja_utils/filters.py @@ -9,6 +9,7 @@ - wrap: Break a call that is too long after a comma. - utf8tolatex: Convert UTF-8 text to LaTeX-safe encoding. - utf8tohtml: Escape text for HTML, with `code` spans as . +- markdown_cell: Escape text for one cell of a Markdown table. Copyright (c) 2025 Ola Groettvik Licensed under the Apache License, Version 2.0. See the LICENSE file for details. @@ -156,3 +157,21 @@ def _convert_code_spans(text, convert, mark_code): convert(part) if i % 2 == 0 else mark_code(convert(part)) for i, part in enumerate(parts) ) + + +_MARKDOWN_SPECIAL = re.compile(r"([\\*\[\]<>|])") + + +def markdown_cell(text): + """Escape text for one line of Markdown, such as a table cell. + + A `code` span is kept, but a | in it is still escaped, since GitHub splits + the cells of a table row before it reads code spans. Line breaks become + spaces. + """ + parts = re.split(r"(`[^`]*`)", str(text)) + escaped = "".join( + part.replace("|", "\\|") if i % 2 else _MARKDOWN_SPECIAL.sub(r"\\\1", part) + for i, part in enumerate(parts) + ) + return " ".join(escaped.split()) diff --git a/bust/templates/markdown/documentation.j2 b/bust/templates/markdown/documentation.j2 new file mode 100644 index 0000000..1b3639a --- /dev/null +++ b/bust/templates/markdown/documentation.j2 @@ -0,0 +1,56 @@ +{% macro bits(high, low) %}{{ high }}{% if high > low %}:{{ low }}{% endif %}{% endmacro %} +{% macro field_notes(field) %} +{% set notes = [] %} +{% if field.description %}{% set _ = notes.append(field.description | markdown_cell) %}{% endif %} +{% if field.onread %}{% set _ = notes.append("onread: " ~ field.onread.value ~ ".") %}{% endif %} +{% if field.onwrite %}{% set _ = notes.append("onwrite: " ~ field.onwrite.value ~ ".") %}{% endif %} +{% if field.singlepulse %}{% set _ = notes.append("singlepulse.") %}{% endif %} +{% set modifiers = [] %} +{% for name in ["we", "wel", "hwset", "hwclr", "swmod", "swacc"] if field[name] %}{% set _ = modifiers.append(name) %}{% endfor %} +{% if modifiers %}{% set _ = notes.append("Modifiers: " ~ modifiers | join(", ") ~ ".") %}{% endif %} +{% if field.is_enum %} +{% set values = [] %} +{% for e in field.enums %}{% set _ = values.append(e.name ~ "=" ~ e.value) %}{% endfor %} +{% set _ = notes.append("Values: " ~ values | join(", ") ~ ".") %} +{% endif %} +{{ notes | join(" ") }} +{%- endmacro %} +# {{ module.name }} + +Generated by bust v{{ version }}. {% if module.version %}Version: {{ module.version | markdown_cell }}. {% endif %}Register map hash: `0x{{ module.regmap_hash_hex }}`. +{% if module.description %} + +{{ module.description | markdown_cell }} +{% endif %} + +## Register list + +| # | Name | SW/HW | Address | Type | Width | Reset | +|--:|------|-------|---------|------|------:|-------| +{% for reg in module.registers %} +| {{ loop.index0 }} | [{{ reg.name }}](#{{ reg.name | lower }}) | {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }} | `0x{{ "%08X" | format(reg.address) }}` | {{ reg.type.value.upper() }} | {{ reg.width }} | `0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}` | +{% endfor %} + +## Registers +{% for reg in module.registers %} + +### {{ reg.name }} + +Address `0x{{ "%08X" | format(reg.address) }}`, {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }}, reset `0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}`. +{% if reg.description %} + +{{ reg.description | markdown_cell }} +{% endif %} + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +{% set free = namespace(high=module.data_width - 1) %} +{% for field in reg.effective_fields | reverse %} +{% if field.pos_high < free.high %} +| {{ bits(free.high, field.pos_high + 1) }} | unused | | | | | +{% endif %} +{% set notes = field_notes(field) %} +| {{ bits(field.pos_high, field.pos_low) }} | {{ field.name }} | {{ field.sw.value }} | {{ field.hw.value }} | `0x{{ "%X" | format(field.reset[2:]|int(base=16)) }}` |{% if notes %} {{ notes }}{% endif %} | +{% set free.high = field.pos_low - 1 %} +{% endfor %} +{% endfor %} diff --git a/docs/addressing.md b/docs/addressing.md index 0a62f09..1f52218 100644 --- a/docs/addressing.md +++ b/docs/addressing.md @@ -139,5 +139,5 @@ your software adds the base address. In the headers, `_OFFSET` also names the lowest bit of a field, as in `___OFFSET`. That is a bit position inside the register, -not an address. [Headers and documentation](headers-and-docs.md#constant-names) +not an address. [Software headers](headers.md#constant-names) lists the constants. diff --git a/docs/buses.md b/docs/buses.md index 8fcf24d..d9001c5 100644 --- a/docs/buses.md +++ b/docs/buses.md @@ -194,7 +194,7 @@ compile `components/ipbus_core/firmware/hdl/ipbus_package.vhd` from the - With an `addr_width` below 32, the endpoint ignores the upper bits of `ipb_addr`, so decode them before the module, as an IPBus fabric does. - bust also writes an IPBus address table for uHAL. See - [Headers and documentation](headers-and-docs.md). + [Software headers](headers.md#ipbus-address-table). ## SBI diff --git a/docs/command-line.md b/docs/command-line.md index 72bd6a5..a9290f0 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -38,8 +38,8 @@ and exit with status 1. |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-o DIR` | Write the output under `DIR` instead of next to the JSON file. See [Output directory](#output-directory). | | `-f` | Overwrite existing files without asking, except `.vhd`, which is yours. See [Existing files](#existing-files). | -| `-d` | Do not write the documentation: no `.tex` or `.html` file and no PDF. | -| `-p` | Write the `.tex` and `.html` files, but do not run `pdflatex` to make the PDF, even when it is installed. | +| `-d` | Do not write the documentation: no `.tex`, `.html` or `.md` file and no PDF. | +| `-p` | Write the `.tex`, `.html` and `.md` files, but do not run `pdflatex` to make the PDF, even when it is installed. | | `-i` | Do not write the headers: the `.h`, `.hpp` and `.py` files, and for IPBus the `.xml` address table. | | `--replace-top` | Replace `.vhd` with a fresh starter and keep the old file as `.vhd.bak`. Asks first unless you add `-f`. See [Your top level](#your-top-level). | | `-a` | Give every register a new address and save the JSON file. Generates nothing. With `-f`, saves without asking. See [Renumber addresses](#renumber-addresses). | @@ -50,8 +50,7 @@ and exit with status 1. | `-h`, `--help` | Print the usage and a short description of each option, then exit. | Every run that generates files writes the VHDL files and the testbench. No -option turns them off. [Headers and documentation](headers-and-docs.md) -describes the headers, the address table and the documentation. +option turns them off. [Software headers](headers.md) describes the headers and the address table, and [Documentation](documentation.md) the documentation. ## Output directory @@ -70,6 +69,7 @@ out/ │ ├── example_ipbus.aux │ ├── example_ipbus.html │ ├── example_ipbus.log + │ ├── example_ipbus.md │ ├── example_ipbus.pdf │ └── example_ipbus.tex ├── hdl/ @@ -91,8 +91,8 @@ out/ |-----------|-----------------------------------------------------------------------------------------------------------|----------------------------------------------------| | `hdl/` | `_localbus_pkg.vhd`, `_regfile_pkg.vhd`, `_regfile.vhd`, the endpoint, `.vhd` | [Generated HDL](generated-hdl.md) | | `tb/` | `_tb.vhd` | [Testbenches](testbenches.md) | -| `header/` | `.h`, `.hpp`, `.py`, and `.xml` for IPBus | [Headers and documentation](headers-and-docs.md) | -| `doc/` | `.tex`, `.html`, and with `pdflatex` installed `.pdf` and its `.aux` and `.log` files | [Headers and documentation](headers-and-docs.md) | +| `header/` | `.h`, `.hpp`, `.py`, and `.xml` for IPBus | [Software headers](headers.md) | +| `doc/` | `.tex`, `.html`, `.md`, and with `pdflatex` installed `.pdf` and its `.aux` and `.log` files | [Documentation](documentation.md) | The endpoint file is named after the bus: @@ -291,7 +291,7 @@ Delete removes one. ### The overview `o` shows the whole register map the way the -[documentation](headers-and-docs.md) does. It has the module's name, version, +[documentation](documentation.md) does. It has the module's name, version, register map hash and bus, then the register list with the number, name, software and hardware access, address, type, width and reset of each register. Then each register follows with its address, its description and a bit @@ -390,7 +390,7 @@ pdflatex is not on PATH, so bust skipped the PDF. The documentation is in /path/ When `pdflatex` runs but reports errors, bust prints `pdflatex reported errors. See /.log`. In both cases bust still exits with status 0, since every other file was written. -[Headers and documentation](headers-and-docs.md) describes the PDF step. +[Documentation](documentation.md#pdf) describes the PDF step. An error in the register map is printed as a message that names the problem, and bust exits with status 1. A value of the wrong form gives the file, the diff --git a/docs/conf.py b/docs/conf.py index 2c740c5..1beae66 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,8 @@ version = release extensions = ["myst_parser"] -myst_heading_anchors = 3 +# 5 so the register links in the included example Markdown resolve. +myst_heading_anchors = 5 exclude_patterns = ["_build"] html_theme = "furo" diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 0000000..d8a200b --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,95 @@ +# Documentation + +bust writes documentation of the register map to `doc/`, in the output directory of the module described in [Command line](command-line.md#output-directory): 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 | +|-----------------|----------------------------------------|-----------------------------------------------------------------| +| `.html` | The documentation as one HTML page | Unless you give `-d` | +| `.md` | The documentation as Markdown | Unless you give `-d` | +| `.tex` | LaTeX source of the documentation | Unless you give `-d` | +| `.pdf` | The documentation as PDF | Unless you give `-d` or `-p`, when `pdflatex` is on your `PATH` | + +## Content + +`doc/.tex` and `doc/.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 above the highest field are marked unused. 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`: + +```latex +\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/.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: + +```bash +pdflatex --interaction=batchmode --output-directory= /.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 `.pdf` to `doc/`, together with its `.aux` +and `.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 +/.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/.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`](https://github.com/logvik-org/bust/blob/master/example/example_prototype/doc/prototype.md). + +```{include} ../example/example_prototype/doc/prototype.md +:heading-offset: 2 +``` diff --git a/docs/generated-hdl.md b/docs/generated-hdl.md index cf74c9f..df54252 100644 --- a/docs/generated-hdl.md +++ b/docs/generated-hdl.md @@ -93,7 +93,7 @@ your design ### Where the files go The VHDL lands in `hdl/` and the testbench in `tb/`, next to the `header/` and -`doc/` directories of the [headers and documentation](headers-and-docs.md). For +`doc/` directories of the [software headers](headers.md) and the [documentation](documentation.md). For the timer: ```text diff --git a/docs/getting-started.md b/docs/getting-started.md index 5f75ba8..2b904e5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -87,6 +87,7 @@ bust writes one directory per module: out/timer/ ├── doc/ │ ├── timer.html +│ ├── timer.md │ ├── timer.pdf │ └── timer.tex ├── hdl/ @@ -194,7 +195,7 @@ write32(TIMER_BASE + TIMER_CTRL_OFFSET, ctrl); ``` `read32`, `write32` and `TIMER_BASE` stand for whatever your platform uses. -[Headers and documentation](headers-and-docs.md) covers the C++, Python and +[Software headers](headers.md) covers the C++, Python and IPBus outputs. ## Run the testbench diff --git a/docs/headers-and-docs.md b/docs/headers.md similarity index 71% rename from docs/headers-and-docs.md rename to docs/headers.md index 74cc3bf..930af7e 100644 --- a/docs/headers-and-docs.md +++ b/docs/headers.md @@ -1,13 +1,10 @@ -# Headers and documentation +# Software headers -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. +Next to the VHDL, bust writes headers that give software the addresses and bit positions of the registers, and for IPBus an address table. 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](command-line.md#output-directory). +bust writes the headers to `header/`, in the output directory of the module described in [Command line](command-line.md#output-directory). | File | Content | Written | |----------------|---------------------------------------------|--------------------------------------------------| @@ -15,9 +12,6 @@ output directory of the module described in | `.hpp` | C++ header with constants in a namespace | Unless you give `-i` | | `.py` | Python module with constants in a class | Unless you give `-i` | | `.xml` | IPBus address table for uHAL | For the `ipbus` bus type, unless you give `-i` | -| `.tex` | LaTeX source of the documentation | Unless you give `-d` | -| `.html`| The documentation as one HTML page | Unless you give `-d` | -| `.pdf` | The documentation as PDF | Unless you give `-d` or `-p`, when `pdflatex` is on your `PATH` | ## Constant names @@ -260,76 +254,3 @@ module: ```xml ``` - -## Documentation - -bust writes the documentation of the register map twice, as `doc/.tex` and as `doc/.html`, with the same content and layout. Neither needs anything beyond bust itself. Both 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 above the highest field are marked unused. 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`: - -```latex -\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/.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: - -```bash -pdflatex --interaction=batchmode --output-directory= /.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 `.pdf` to `doc/`, together with its `.aux` -and `.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 -/.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. diff --git a/docs/index.md b/docs/index.md index e231a48..5dbbed0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ **bust** generates the register file of an FPGA or ASIC module from a JSON register map. From one file it writes the VHDL register file with its bus endpoint, a self-checking UVVM testbench, C, C++ and Python headers, an IPBus -address table and documentation as HTML, LaTeX and PDF. +address table and documentation as HTML, Markdown, LaTeX and PDF. bust supports six buses: AXI4-Lite, IPBus, SBI, Avalon-MM, Wishbone and APB. @@ -52,8 +52,8 @@ testbench of every bus in CI. and the generics that set its base address and address range. - [Generated HDL](generated-hdl.md): the generated files, the records and how to instantiate the module. -- [Headers and documentation](headers-and-docs.md): the C, C++ and Python - headers, the IPBus address table and the documentation. +- [Documentation](documentation.md): the HTML, Markdown, LaTeX and PDF documentation, with examples. +- [Software headers](headers.md): the C, C++ and Python headers and the IPBus address table. - [Testbenches](testbenches.md): what the testbench checks and how to run it. - [Command line](command-line.md): every option of the `bust` command. @@ -73,7 +73,8 @@ access-modes buses addressing generated-hdl -headers-and-docs +documentation +headers testbenches command-line ``` diff --git a/docs/register-map-format.md b/docs/register-map-format.md index 68ecb39..8f69b5f 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -201,7 +201,7 @@ Both appear in every output: | C header | `_REGMAP_VERSION` | `_REGMAP_HASH` | | C++ and Python headers | `REGMAP_VERSION` | `REGMAP_HASH` | | IPBus address table | `regmap_version=` in the `parameters` of the top node | `regmap_hash=` in the same `parameters` | -| Documentation | Title and page footer (HTML: running header) | Title, under the version | +| Documentation | Title and page footer (HTML: running header, Markdown: line under the title) | Title, under the version | ### Hash and version registers diff --git a/example/example_axi/doc/example_axi.md b/example/example_axi/doc/example_axi.md new file mode 100644 index 0000000..b4a16b9 --- /dev/null +++ b/example/example_axi/doc/example_axi.md @@ -0,0 +1,183 @@ +# example_axi + +Generated by bust v1.0.0-dev. Version: 1.0. Register map hash: `0x0CF519FC`. + +An example module that contain all the register types that are currently supported by bust. + +## Register list + +| # | Name | SW/HW | Address | Type | Width | Reset | +|--:|------|-------|---------|------|------:|-------| +| 0 | [reg0](#reg0) | RW/R | `0x00000000` | BIT | 1 | `0x0` | +| 1 | [reg1](#reg1) | RW/R | `0x00000004` | BIT | 1 | `0x1` | +| 2 | [reg2](#reg2) | RO/W | `0x00000008` | BIT | 1 | `0x0` | +| 3 | [reg3](#reg3) | RW/R | `0x0000000C` | VECTOR | 8 | `0x3` | +| 4 | [reg4](#reg4) | RO/W | `0x00000010` | VECTOR | 14 | `0x0` | +| 5 | [reg5](#reg5) | RW/R | `0x00000014` | DEFAULT | 32 | `0xFFFFFFFF` | +| 6 | [reg6](#reg6) | RO/W | `0x00000018` | DEFAULT | 32 | `0x0` | +| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 21 | `0xAD7` | +| 8 | [reg8](#reg8) | RO/W | `0x00000020` | FIELDS | 24 | `0x0` | +| 9 | [reg9](#reg9) | WO/R | `0x00000024` | BIT | 1 | `0x1` | +| 10 | [reg10](#reg10) | WO/R | `0x00000028` | VECTOR | 4 | `0xA` | +| 11 | [reg11](#reg11) | WO/R | `0x0000002C` | FIELDS | 16 | `0x3` | +| 12 | [regmap_hash](#regmap_hash) | RO/NA | `0x00000030` | HASH | 32 | `0xCF519FC` | +| 13 | [regmap_version](#regmap_version) | RO/NA | `0x00000034` | VERSION | 32 | `0x10000` | + +## Registers + +### reg0 + +Address `0x00000000`, RW/R, reset `0x0`. + +RW std_logic register that resets to 0x0 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg0 | rw | r | `0x0` | | + +### reg1 + +Address `0x00000004`, RW/R, reset `0x1`. + +RW std_logic register that resets to 0x1 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg1 | rw | r | `0x1` | | + +### reg2 + +Address `0x00000008`, RO/W, reset `0x0`. + +RO std_logic register + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg2 | ro | w | `0x0` | | + +### reg3 + +Address `0x0000000C`, RW/R, reset `0x3`. + +RW std_logic_vector\[7:0\] register that resets to 0x3 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:8 | unused | | | | | +| 7:0 | reg3 | rw | r | `0x3` | | + +### reg4 + +Address `0x00000010`, RO/W, reset `0x0`. + +RO std_logic_vector\[13:0\] + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:14 | unused | | | | | +| 13:0 | reg4 | ro | w | `0x0` | | + +### reg5 + +Address `0x00000014`, RW/R, reset `0xFFFFFFFF`. + +Default RW register that resets to 0xFFFFFFFF + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | reg5 | rw | r | `0xFFFFFFFF` | | + +### reg6 + +Address `0x00000018`, RO/W, reset `0x0`. + +Default RO register + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | reg6 | ro | w | `0x0` | | + +### reg7 + +Address `0x0000001C`, RW/R, reset `0xAD7`. + +RW register that have multiple fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:21 | unused | | | | | +| 20:6 | field3 | rw | r | `0x2B` | std_logic_vector\[14:0\] that resets to 0x2b | +| 5 | field2 | rw | r | `0x0` | std_logic that resets to 0x1 | +| 4:1 | field1 | rw | r | `0xB` | std_logic_vector\[3:0\] that resets to 0xb is not a valid reset value | +| 0 | field0 | rw | r | `0x1` | std_logic that resets to 0x1 | + +### reg8 + +Address `0x00000020`, RO/W, reset `0x0`. + +RO register with multiple types of fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:24 | unused | | | | | +| 23:21 | field3 | ro | w | `0x0` | std_logic_vector\[2:0\] field | +| 20 | field2 | ro | w | `0x0` | std_logic field | +| 19:1 | field1 | ro | w | `0x0` | std_logic_vector\[18:0\] field | +| 0 | field0 | ro | w | `0x0` | std_logic field | + +### reg9 + +Address `0x00000024`, WO/R, reset `0x1`. + +PULSE std_logic register that resets to 0x1 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg9 | wo | r | `0x1` | singlepulse. | + +### reg10 + +Address `0x00000028`, WO/R, reset `0xA`. + +PULSE std_logic_vector\[3:0\] register that resets to 0xA + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:4 | unused | | | | | +| 3:0 | reg10 | wo | r | `0xA` | singlepulse. | + +### reg11 + +Address `0x0000002C`, WO/R, reset `0x3`. + +PULSE register with two fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:16 | unused | | | | | +| 15 | field1 | wo | r | `0x0` | std_logic field that resets to 0x0 singlepulse. | +| 14:0 | field0 | wo | r | `0x3` | std_logic_vector\[14:0\] field that resets to 0x3 singlepulse. | + +### regmap_hash + +Address `0x00000030`, RO/NA, reset `0xCF519FC`. + +Hash of the register map, to compare with EXAMPLE_AXI_REGMAP_HASH in the header + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | regmap_hash | ro | na | `0xCF519FC` | | + +### regmap_version + +Address `0x00000034`, RO/NA, reset `0x10000`. + +Version of the register map, 1.0 as 0x00010000 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | regmap_version | ro | na | `0x10000` | | diff --git a/example/example_ipbus/doc/example_ipbus.md b/example/example_ipbus/doc/example_ipbus.md new file mode 100644 index 0000000..237b947 --- /dev/null +++ b/example/example_ipbus/doc/example_ipbus.md @@ -0,0 +1,161 @@ +# example_ipbus + +Generated by bust v1.0.0-dev. Version: 1.0. Register map hash: `0xFCD085B6`. + +An example module that contain all the register types that are currently supported by bust. + +## Register list + +| # | Name | SW/HW | Address | Type | Width | Reset | +|--:|------|-------|---------|------|------:|-------| +| 0 | [reg0](#reg0) | RW/R | `0x00000000` | BIT | 1 | `0x0` | +| 1 | [reg1](#reg1) | RW/R | `0x00000004` | BIT | 1 | `0x1` | +| 2 | [reg2](#reg2) | RO/W | `0x00000008` | BIT | 1 | `0x0` | +| 3 | [reg3](#reg3) | RW/R | `0x0000000C` | VECTOR | 8 | `0x3` | +| 4 | [reg4](#reg4) | RO/W | `0x00000010` | VECTOR | 14 | `0x0` | +| 5 | [reg5](#reg5) | RW/R | `0x00000014` | DEFAULT | 32 | `0xFFFFFFFF` | +| 6 | [reg6](#reg6) | RO/W | `0x00000018` | DEFAULT | 32 | `0x0` | +| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 21 | `0xAD7` | +| 8 | [reg8](#reg8) | RO/W | `0x00000020` | FIELDS | 24 | `0x0` | +| 9 | [reg9](#reg9) | WO/R | `0x00000024` | BIT | 1 | `0x1` | +| 10 | [reg10](#reg10) | WO/R | `0x00000028` | VECTOR | 4 | `0xA` | +| 11 | [reg11](#reg11) | WO/R | `0x0000002C` | FIELDS | 16 | `0x3` | + +## Registers + +### reg0 + +Address `0x00000000`, RW/R, reset `0x0`. + +RW std_logic register that resets to 0x0 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg0 | rw | r | `0x0` | | + +### reg1 + +Address `0x00000004`, RW/R, reset `0x1`. + +RW std_logic register that resets to 0x1 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg1 | rw | r | `0x1` | | + +### reg2 + +Address `0x00000008`, RO/W, reset `0x0`. + +RO std_logic register + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg2 | ro | w | `0x0` | | + +### reg3 + +Address `0x0000000C`, RW/R, reset `0x3`. + +RW std_logic_vector\[7:0\] register that resets to 0x3 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:8 | unused | | | | | +| 7:0 | reg3 | rw | r | `0x3` | | + +### reg4 + +Address `0x00000010`, RO/W, reset `0x0`. + +RO std_logic_vector\[13:0\] + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:14 | unused | | | | | +| 13:0 | reg4 | ro | w | `0x0` | | + +### reg5 + +Address `0x00000014`, RW/R, reset `0xFFFFFFFF`. + +Default RW register that resets to 0xFFFFFFFF + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | reg5 | rw | r | `0xFFFFFFFF` | | + +### reg6 + +Address `0x00000018`, RO/W, reset `0x0`. + +Default RO register + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:0 | reg6 | ro | w | `0x0` | | + +### reg7 + +Address `0x0000001C`, RW/R, reset `0xAD7`. + +RW register that have multiple fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:21 | unused | | | | | +| 20:6 | field3 | rw | r | `0x2B` | std_logic_vector\[14:0\] that resets to 0x2b | +| 5 | field2 | rw | r | `0x0` | std_logic that resets to 0x1 | +| 4:1 | field1 | rw | r | `0xB` | std_logic_vector\[3:0\] that resets to 0xb is not a valid reset value | +| 0 | field0 | rw | r | `0x1` | std_logic that resets to 0x1 | + +### reg8 + +Address `0x00000020`, RO/W, reset `0x0`. + +RO register with multiple types of fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:24 | unused | | | | | +| 23:21 | field3 | ro | w | `0x0` | std_logic_vector\[2:0\] field | +| 20 | field2 | ro | w | `0x0` | std_logic field | +| 19:1 | field1 | ro | w | `0x0` | std_logic_vector\[18:0\] field | +| 0 | field0 | ro | w | `0x0` | std_logic field | + +### reg9 + +Address `0x00000024`, WO/R, reset `0x1`. + +PULSE std_logic register that resets to 0x1 + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:1 | unused | | | | | +| 0 | reg9 | wo | r | `0x1` | singlepulse. | + +### reg10 + +Address `0x00000028`, WO/R, reset `0xA`. + +PULSE std_logic_vector\[3:0\] register that resets to 0xA + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:4 | unused | | | | | +| 3:0 | reg10 | wo | r | `0xA` | singlepulse. | + +### reg11 + +Address `0x0000002C`, WO/R, reset `0x3`. + +PULSE register with two fields + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:16 | unused | | | | | +| 15 | field1 | wo | r | `0x0` | std_logic field that resets to 0x0 singlepulse. | +| 14:0 | field0 | wo | r | `0x3` | std_logic_vector\[14:0\] field that resets to 0x3 singlepulse. | diff --git a/example/example_prototype/doc/prototype.md b/example/example_prototype/doc/prototype.md new file mode 100644 index 0000000..a7e2e35 --- /dev/null +++ b/example/example_prototype/doc/prototype.md @@ -0,0 +1,168 @@ +# 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](#reg0) | RW/R | `0x00000000` | FIELDS | 3 | `0x0` | +| 1 | [reg1](#reg1) | RO/W | `0x00000004` | FIELDS | 6 | `0x0` | +| 2 | [reg2](#reg2) | WO/R | `0x00000008` | FIELDS | 1 | `0x0` | +| 3 | [reg3](#reg3) | RW/NA | `0x0000000C` | FIELDS | 8 | `0x0` | +| 4 | [reg4](#reg4) | RW/RW | `0x00000010` | FIELDS | 9 | `0x0` | +| 5 | [reg5](#reg5) | RW/R | `0x00000014` | FIELDS | 8 | `0x0` | +| 6 | [reg6](#reg6) | RW/R | `0x00000018` | FIELDS | 12 | `0xF0` | +| 7 | [reg7](#reg7) | RW/R | `0x0000001C` | FIELDS | 12 | `0xF0` | +| 8 | [reg8](#reg8) | RW/R | `0x00000020` | FIELDS | 8 | `0xF` | +| 9 | [reg9](#reg9) | RW/R | `0x00000024` | FIELDS | 8 | `0x0` | +| 10 | [reg10](#reg10) | RW/R | `0x00000028` | FIELDS | 4 | `0x0` | +| 11 | [reg11](#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 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 0 | field0 | wo | r | `0x0` | | + +### 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 | `0x0` | | + +### 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 | `0x0` | Modifiers: hwset, hwclr. | +| 7:4 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 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 | unused | | | | | +| 3:0 | field0 | rw | r | `0x0` | singlepulse. | + +### reg11 + +Address `0x0000002C`, RW/R, reset `0x0`. + +Enumerated field. + +| Bits | Name | SW | HW | Reset | Description | +|------|------|----|----|-------|-------------| +| 31:2 | unused | | | | | +| 1:0 | field0 | rw | r | `0x0` | Values: STATE0=0, STATE1=1, STATE2=2, STATE3=3. | diff --git a/tests/test_cli.py b/tests/test_cli.py index 7fe933a..743c327 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -193,6 +193,20 @@ def test_empty_version_leaves_no_version_label_in_the_latex(tmp_path): assert "Version:" not in tex +def test_run_writes_markdown_docs_and_d_skips_them(tmp_path): + path = _write_register_map(tmp_path) + + code, output = _run_bust(tmp_path, str(path), "-o", "out", "-p") + assert code == 0, output + markdown = (tmp_path / "out/timer/doc/timer.md").read_text() + assert "| 0 | [ctrl](#ctrl) | RW/R |" in markdown + assert "### ctrl" in markdown + + code, output = _run_bust(tmp_path, str(path), "-o", "skipped", "-d") + assert code == 0, output + assert not (tmp_path / "skipped/timer/doc/timer.md").exists() + + def test_successful_run_writes_no_debug_log(tmp_path): path = _write_register_map(tmp_path) diff --git a/tests/test_generation.py b/tests/test_generation.py index 7200b10..e08bb42 100644 --- a/tests/test_generation.py +++ b/tests/test_generation.py @@ -112,5 +112,9 @@ def test_docs_without_pdflatex_skip_only_the_pdf(tmp_path, monkeypatch, caplog): _generate(tmp_path, gen_doc=True) doc_dir = os.path.join(str(tmp_path), "example_axi", "doc") - assert sorted(os.listdir(doc_dir)) == ["example_axi.html", "example_axi.tex"] + assert sorted(os.listdir(doc_dir)) == [ + "example_axi.html", + "example_axi.md", + "example_axi.tex", + ] assert "pdflatex is not on PATH, so bust skipped the PDF" in caplog.text diff --git a/tests/test_markdown.py b/tests/test_markdown.py new file mode 100644 index 0000000..40d0793 --- /dev/null +++ b/tests/test_markdown.py @@ -0,0 +1,7 @@ +"""Descriptions in the Markdown documentation.""" + +from bust.jinja_utils.filters import markdown_cell + + +def test_markdown_cell_escapes_markup_but_keeps_code(): + assert markdown_cell("a|b *c* \n`x|y` [e]") == (r"a\|b \*c\* \ `x\|y` \[e\]") diff --git a/tests/test_suite.py b/tests/test_suite.py index c102520..497a3a7 100644 --- a/tests/test_suite.py +++ b/tests/test_suite.py @@ -184,6 +184,11 @@ def test_doc(self): base + ".html", "html doc must match manual file", ) + self._assert_matches( + holder.doc.generate_markdown_documentation("1.0.0-dev"), + base + ".md", + "markdown doc must match manual file", + ) ############## Prototype (full access-mode coverage) ################## @@ -351,6 +356,11 @@ def test_prototype_doc(self): "example/example_prototype/doc/prototype.html", "prototype html doc must match manual file", ) + self._assert_matches( + doc.generate_markdown_documentation("1.0.0-dev"), + "example/example_prototype/doc/prototype.md", + "prototype markdown doc must match manual file", + ) ############## Access-mode combination matrix ##################