From 9cc4dac48bb8148a7c3bfba22452556855788440 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Tue, 27 Oct 2026 13:09:04 +0000 Subject: [PATCH 1/2] Add reserved_fields module key for unused bits in documentation --- CHANGELOG.md | 6 + bust/core/module.py | 20 +++- bust/core/register.py | 29 +++++ bust/editor/diagram.py | 98 +++++++++------- bust/editor/overview.py | 9 +- bust/editor/session.py | 8 +- bust/schema.py | 6 + bust/templates/latex/documentation.j2 | 21 ++-- docs/command-line.md | 2 +- docs/headers-and-docs.md | 2 +- docs/register-map-format.md | 25 +++++ example/example_prototype/doc/prototype.tex | 1 + tests/test_editor.py | 2 +- tests/test_reserved_fields.py | 117 ++++++++++++++++++++ 14 files changed, 287 insertions(+), 59 deletions(-) create mode 100644 tests/test_reserved_fields.py diff --git a/CHANGELOG.md b/CHANGELOG.md index bb6fa34d..5f720e08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). ## [Unreleased] +### Added +- `reserved_fields` in `module`. With `true`, the documentation and the editor overview show the bits that no field covers as reserved fields, and list them among the fields. + +### Fixed +- The LaTeX bit diagram leaves out no bits between two fields. A gap made by `position` is marked unused, as the editor overview already showed it. + ### Changed - `_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`. diff --git a/bust/core/module.py b/bust/core/module.py index 61a0b96d..5b0bc2cb 100644 --- a/bust/core/module.py +++ b/bust/core/module.py @@ -46,6 +46,7 @@ "description", "version", "byte_addressable", + "reserved_fields", "register", ) @@ -63,6 +64,8 @@ class Module: description: Optional module description. version: Module version string. byte_addressable: Whether addresses are byte-based (defaults to the bus). + reserved_fields: Whether the documentation shows the bits that no field + covers as reserved fields. addr_width: Address bus width in bits. data_width: Data bus width in bits. bus: Bus configuration instance. @@ -80,12 +83,15 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: - description: Module description (default: "") - version: Version string (default: "") - byte_addressable: Use byte addressing (default: from the bus) + - reserved_fields: Document unused bits as reserved fields + (default: False) - register: List of register configurations (required) bus: Bus interface configuration. settings: Project-wide settings. Raises: - FormatError: If byte_addressable is not a boolean. + FormatError: If byte_addressable or reserved_fields is not a + boolean. InvalidAddress: If register addresses conflict. InvalidRegister: If register configuration is invalid. ValueError: If module name is not a valid VHDL identifier. @@ -110,6 +116,7 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: "description": "", "version": "", "byte_addressable": bus.byte_addressable, + "reserved_fields": False, }, ) @@ -119,7 +126,8 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: # Store some config values for easy access self.description: str = self._config.get("description") self.version = self._read_version() - self.byte_addressable = self._read_byte_addressable() + self.byte_addressable = self._read_boolean("byte_addressable") + self.reserved_fields = self._read_boolean("reserved_fields") self.addr_width = bus.addr_width self.data_width = bus.data_width @@ -167,12 +175,12 @@ def add_register(self, reg: Dict) -> None: raise InvalidRegister(reg, e) from e self.registers.append(register) - def _read_byte_addressable(self) -> bool: - """Read byte_addressable, which must be true or false.""" - value = self._config.get("byte_addressable") + def _read_boolean(self, key: str) -> bool: + """Read `key`, which must be true or false.""" + value = self._config.get(key) if isinstance(value, bool): return value - raise FormatError(f"byte_addressable must be true or false (got {value!r})") + raise FormatError(f"{key} must be true or false (got {value!r})") def _read_version(self) -> str: """Read the version, which every generated file carries as a string.""" diff --git a/bust/core/register.py b/bust/core/register.py index b3861960..b671ec28 100644 --- a/bust/core/register.py +++ b/bust/core/register.py @@ -10,6 +10,7 @@ """ import logging +from dataclasses import dataclass from typing import Any, Dict, List, Optional, cast from bust.exceptions import ( @@ -63,6 +64,19 @@ } +@dataclass(frozen=True) +class BitRange: + """A run of bits of a register: one field, or bits that no field covers.""" + + high: int + low: int + field: Optional[Field] + + @property + def width(self) -> int: + return self.high - self.low + 1 + + class Register: """Represents a memory-mapped register in a bus slave module. @@ -244,6 +258,21 @@ def effective_fields(self) -> List["Field"]: """Fields for local-bus generation: real fields, or the implicit one.""" return self.fields if self.fields else [self._implicit_field] + @property + def bit_ranges(self) -> List[BitRange]: + """Every bit up to the data width, from the highest down, with each + run of bits that no field covers as a range of its own.""" + ranges: List[BitRange] = [] + next_high = self.module_data_width - 1 + for field in sorted(self.effective_fields, key=lambda f: -f.pos_high): + if field.pos_high < next_high: + ranges.append(BitRange(next_high, field.pos_high + 1, None)) + ranges.append(BitRange(field.pos_high, field.pos_low, field)) + next_high = field.pos_low - 1 + if next_high >= 0: + ranges.append(BitRange(next_high, 0, None)) + return ranges + def _init_fields(self) -> None: """Initialize fields from configuration for FIELDS type registers.""" fields = self._config.require("fields") diff --git a/bust/editor/diagram.py b/bust/editor/diagram.py index 26a7de37..a5a11570 100644 --- a/bust/editor/diagram.py +++ b/bust/editor/diagram.py @@ -11,6 +11,7 @@ from typing import List, Tuple from bust.core.enums import RegisterType +from bust.core.field import Field from bust.core.module import Module from bust.core.register import Register @@ -32,26 +33,19 @@ def _reset(text: str, width: int) -> str: return str(value) if width < 2 else f"0x{value:X}" -def _segments(register: Register, data_width: int) -> List[_Segment]: +def _segments(register: Register, unused_name: str) -> List[_Segment]: """The fields of `register` from the highest bit down, with the unused bits between them.""" - if register.type == RegisterType.FIELDS: - used = [ - _Segment(f.name, f.pos_high, f.pos_low, _reset(f.reset, f.width)) - for f in register.fields - ] - else: - width = register.width - used = [_Segment(register.name, width - 1, 0, _reset(register.reset, width))] - segments: List[_Segment] = [] - next_high = data_width - 1 - for segment in sorted(used, key=lambda s: s.high, reverse=True): - if segment.high < next_high: - segments.append(_Segment("unused", next_high, segment.high + 1, "-")) - segments.append(segment) - next_high = segment.low - 1 - if next_high >= 0: - segments.append(_Segment("unused", next_high, 0, "-")) + segments = [] + for bits in register.bit_ranges: + if bits.field is None: + segments.append(_Segment(unused_name, bits.high, bits.low, "-")) + continue + name = ( + bits.field.name if register.type == RegisterType.FIELDS else register.name + ) + reset = _reset(bits.field.reset, bits.width) + segments.append(_Segment(name, bits.high, bits.low, reset)) return segments @@ -64,12 +58,20 @@ def bit_width(data_width: int) -> int: return 3 if data_width <= 32 else 2 -def bit_diagram(register: Register, data_width: int) -> List[str]: +def unused_name(module: Module) -> str: + """The name the diagrams give bits that no field covers.""" + return "reserved" if module.reserved_fields else "unused" + + +def bit_diagram( + register: Register, data_width: int, unused: str = "unused" +) -> List[str]: """The lines of the bit diagram of `register`: bit numbers, the boxes with - the field names, and the reset values.""" + the field names, and the reset values. Bits that no field covers are + named `unused`.""" bit = bit_width(data_width) numbers = top = names = bottom = resets = "" - for number, segment in enumerate(_segments(register, data_width)): + for number, segment in enumerate(_segments(register, unused)): high, low = str(segment.high), str(segment.low) bits = high if segment.width == 1 else f"{high} {low}" # A box grows past its bits rather than cut a name short. @@ -120,23 +122,43 @@ def register_heading(register: Register) -> Tuple[str, str]: return f"{register.name} - {_access(register)}", f"0x{register.address:08X}" -def field_notes(register: Register) -> List[Tuple[str, str]]: +RESERVED_NOTE = "Read as 0, writes have no effect." + + +def _bits(high: int, low: int) -> str: + return f"{high}:{low}" if high > low else str(low) + + +def _field_note(field: Field) -> str: + keys = [f"sw: {field.sw.value}", f"hw: {field.hw.value}"] + if field.onread: + keys.append(f"onread: {field.onread.value}") + if field.onwrite: + keys.append(f"onwrite: {field.onwrite.value}") + if field.singlepulse: + keys.append("singlepulse") + text = f"({', '.join(keys)})" + if field.is_enum: + values = ", ".join(f"{e.name}={e.value}" for e in field.enums) + text = f"({', '.join(keys)}; values: {values})" + if field.description: + text = f"{field.description} {text}" + return text + + +def field_notes( + register: Register, reserved_fields: bool = False +) -> List[Tuple[str, str]]: """Each field's name, and its description with its access, as the - documentation lists them under a register.""" + documentation lists them under a register, from the lowest bit up. With + `reserved_fields`, the bits that no field covers are listed as reserved + fields among them.""" notes = [] - for field in register.fields: - keys = [f"sw: {field.sw.value}", f"hw: {field.hw.value}"] - if field.onread: - keys.append(f"onread: {field.onread.value}") - if field.onwrite: - keys.append(f"onwrite: {field.onwrite.value}") - if field.singlepulse: - keys.append("singlepulse") - text = f"({', '.join(keys)})" - if field.is_enum: - values = ", ".join(f"{e.name}={e.value}" for e in field.enums) - text = f"({', '.join(keys)}; values: {values})" - if field.description: - text = f"{field.description} {text}" - notes.append((field.name, text)) + for bits in reversed(register.bit_ranges): + if bits.field is not None: + notes.append((bits.field.name, _field_note(bits.field))) + elif reserved_fields: + notes.append( + ("reserved", f"Bits {_bits(bits.high, bits.low)}. {RESERVED_NOTE}") + ) return notes diff --git a/bust/editor/overview.py b/bust/editor/overview.py index f7b599c7..cf536780 100644 --- a/bust/editor/overview.py +++ b/bust/editor/overview.py @@ -16,6 +16,7 @@ field_notes, register_heading, register_list, + unused_name, ) @@ -70,12 +71,16 @@ def compose(self) -> ComposeResult: ) if register.description: yield Static(register.description, markup=False) - lines: List[str] = bit_diagram(register, module.data_width) + lines: List[str] = bit_diagram( + register, module.data_width, unused_name(module) + ) lines[-1] += " Reset" yield Static("\n".join(lines), classes="diagram", markup=False) if register.type == RegisterType.FIELDS: notes = Text() - for field, note in field_notes(register): + for field, note in field_notes( + register, module.reserved_fields + ): notes.append(f" {field}", style="bold") notes.append(f" {note}\n") notes.rstrip() diff --git a/bust/editor/session.py b/bust/editor/session.py index 07e5a7ea..68c355c7 100644 --- a/bust/editor/session.py +++ b/bust/editor/session.py @@ -265,7 +265,13 @@ def module_properties(self) -> List[Property]: key in data["module"], data["module"].get(key), ) - for key in ("name", "description", "version", "byte_addressable") + for key in ( + "name", + "description", + "version", + "byte_addressable", + "reserved_fields", + ) ] rows += [ Property( diff --git a/bust/schema.py b/bust/schema.py index b79b0cf7..eff178e5 100644 --- a/bust/schema.py +++ b/bust/schema.py @@ -167,6 +167,12 @@ def _string(description: str, **extra: Any) -> Dict[str, Any]: "data words. Default: from the bus.", "type": "boolean", }, + "reserved_fields": { + "description": "true to show the bits that no field covers as " + "reserved fields in the documentation.", + "type": "boolean", + "default": False, + }, "register": { "description": "The registers.", "type": "array", diff --git a/bust/templates/latex/documentation.j2 b/bust/templates/latex/documentation.j2 index e7068c14..c2647d04 100644 --- a/bust/templates/latex/documentation.j2 +++ b/bust/templates/latex/documentation.j2 @@ -61,24 +61,27 @@ \section{Registers} +{% set unused_name = "reserved" if module.reserved_fields else "unused" %} {% for reg in module.registers %} \begin{register}{{ '{' }}H{{ '}' }}{{ '{' }}{{ reg.name | utf8tolatex }} - {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }}{{ '}' }}{{ '{' }}0x{{ "%08X" | format(reg.address) }}{{ '}' }}{% if reg.description %} \par {{ reg.description | utf8tolatex }} \regnewline{% endif +%} \label{{ '{' }}{{ reg.name }}{{ '}' }} -{% if reg.width < module.data_width %} - \regfield{{ '{' }}unused{{ '}' }}{{ '{' }}{{ module.data_width - reg.width }}{{ '}' }}{{ '{' }}{{ reg.width }}{{ '}' }}{{ '{' }}-{{ '}' }} -{% endif %} -{% if reg.type != reg_type_fields %} - \regfield{{ '{' }}{{ '}' }}{{ '{' }}{{ reg.width }}{{ '}' }}{{ '{' }}0{{ '}' }}{{ '{' }}{% if reg.width < 2 %}{{ reg.reset[2:]|int(base=16) }}{% else %}{0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}}{% endif %}{{ '}' }} +{% for bits in reg.bit_ranges %} +{% if bits.field %} + \regfield{{ '{' }}{% if reg.type == reg_type_fields %}{{ bits.field.name | utf8tolatex }}{% endif %}{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}{% if bits.width < 2 %}{{ bits.field.reset[2:]|int(base=16) }}{% else %}{0x{{ "%X" | format(bits.field.reset[2:]|int(base=16)) }}}{% endif %}{{ '}' }} {% else %} -{% for field in reg.fields | reverse %} - \regfield{{ '{' }}{{ field.name | utf8tolatex }}{{ '}' }}{{ '{' }}{{ field.width }}{{ '}' }}{{ '{' }}{{ field.pos_low }}{{ '}' }}{{ '{' }}{% if field.width < 2 %}{{ field.reset[2:]|int(base=16) }}{% else %}{0x{{ "%X" | format(field.reset[2:]|int(base=16)) }}}{% endif %}{{ '}' }} -{% endfor %} + \regfield{{ '{' }}{{ unused_name }}{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}-{{ '}' }} {% endif %} +{% endfor %} \reglabel{Reset}\regnewline {% if reg.type == reg_type_fields %} \begin{{ '{' }}regdesc{{ '}' }}\begin{{ '{' }}reglist{{ '}' }}[{{ reg.fields | map(attribute='name') | min | utf8tolatex }}] -{% for field in reg.fields %} +{% for bits in reg.bit_ranges | reverse if bits.field or module.reserved_fields %} +{% if not bits.field %} + \item [reserved] Bits {% if bits.width > 1 %}{{ bits.high }}:{% endif %}{{ bits.low }}. Read as 0, writes have no effect. +{% else %} +{% set field = bits.field %} \item [{{ field.name | utf8tolatex }}] {{ field.description | utf8tolatex }} (sw: {{ field.sw.value }}, hw: {{ field.hw.value }}{% if field.onread %}, onread: {{ field.onread.value }}{% endif %}{% if field.onwrite %}, onwrite: {{ field.onwrite.value }}{% endif %}{% if field.singlepulse %}, singlepulse{% endif %}{% if field.is_enum %}; values: {% for e in field.enums %}{{ e.name }}={{ e.value }}{% if not loop.last %}, {% endif %}{% endfor %}{% endif %}) +{% endif %} {% endfor %} \end{{ '{' }}reglist{{ '}' }}\end{{ '{' }}regdesc{{ '}' }} {% endif %} \end{register} diff --git a/docs/command-line.md b/docs/command-line.md index 7d219492..bc303c30 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -296,7 +296,7 @@ software and hardware access, address, type, width and reset of each register. Then each register follows with its address, its description and a bit diagram. The diagram draws each field as a box over its bits, with the numbers of its highest and lowest bit above and its reset value below. Bits no -field uses show as `unused`. A box is wider than its bits where its name would +field uses show as `unused`, or as `reserved` with [`reserved_fields`](register-map-format.md#reserved-fields). A box is wider than its bits where its name would not fit. Under the diagram, each field is listed with its description and its access. diff --git a/docs/headers-and-docs.md b/docs/headers-and-docs.md index f7e93ccf..5f446517 100644 --- a/docs/headers-and-docs.md +++ b/docs/headers-and-docs.md @@ -275,7 +275,7 @@ module: 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 + The bits that no field covers are marked unused, or reserved with [`reserved_fields`](register-map-format.md#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. diff --git a/docs/register-map-format.md b/docs/register-map-format.md index 676b4813..e0587061 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -176,6 +176,7 @@ the timing of each protocol. | `version` | string | `""` | The version of the register map. Every generated file carries it, see [Version and hash](#version-and-hash). Printable ASCII characters other than `"`, `\`, `;` and `=`. A module with a `version` register needs the form `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`. | | `description` | string | `""` | Shown in the LaTeX documentation. | | `byte_addressable` | boolean | from the bus | `true` if an address counts bytes, `false` if it counts data words. See [Byte and word addresses](#byte-and-word-addresses). | +| `reserved_fields` | boolean | `false` | `true` to show the bits that no field covers as reserved fields in the documentation. See [Reserved fields](#reserved-fields). | ### Version and hash @@ -474,6 +475,30 @@ Register width: 33 Bits that no field covers read as 0, and writes to them have no effect. +### Reserved fields + +The bit diagrams in the documentation mark the bits that no field covers as `unused`. With `"reserved_fields": true` in `module`, they show as `reserved` fields instead, and the field list of a `fields` register gets an entry for each run of them, in bit order. For `ctrl` in the example: + +```latex + \regfield{reserved}{23}{9}{-} + \regfield{flush}{1}{8}{0} + \regfield{reserved}{4}{4}{-} + \regfield{parity}{2}{2}{{0x0}} + \regfield{rx{\_}en}{1}{1}{0} + \regfield{tx{\_}en}{1}{0}{0} +\reglabel{Reset}\regnewline + \begin{regdesc}\begin{reglist}[flush] + \item [tx{\_}en] Enable the transmitter. (sw: rw, hw: r) + \item [rx{\_}en] Enable the receiver. (sw: rw, hw: r) + \item [parity] Parity bit. (sw: rw, hw: r; values: PAR_NONE=0, PAR_EVEN=1, PAR_ODD=2) + \item [reserved] Bits 7:4. Read as 0, writes have no effect. + \item [flush] Write 1 to empty both FIFOs. (sw: rw, hw: r, singlepulse) + \item [reserved] Bits 31:9. Read as 0, writes have no effect. + \end{reglist}\end{regdesc} +``` + +Reserved fields exist only in the documentation and the editor overview. The VHDL, the headers and the IPBus address table do not change, and neither does the [hash](#version-and-hash). + ## Enumerations A field with an `enums` list has named values. bust generates a VHDL diff --git a/example/example_prototype/doc/prototype.tex b/example/example_prototype/doc/prototype.tex index fc513b6d..fe279e41 100644 --- a/example/example_prototype/doc/prototype.tex +++ b/example/example_prototype/doc/prototype.tex @@ -131,6 +131,7 @@ \section{Registers} \label{reg4} \regfield{unused}{23}{9}{-} \regfield{field1}{1}{8}{0} + \regfield{unused}{4}{4}{-} \regfield{field0}{4}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] diff --git a/tests/test_editor.py b/tests/test_editor.py index 7fbfa873..79ed051b 100644 --- a/tests/test_editor.py +++ b/tests/test_editor.py @@ -486,7 +486,7 @@ async def script(editor): await editor.press("m") await editor.press("down", "down", "enter") await editor.fill(value="2.0") - await editor.press("down", "down", "enter") + await editor.press("down", "down", "down", "enter") await editor.fill(value="apb") await editor.press("escape", "s") diff --git a/tests/test_reserved_fields.py b/tests/test_reserved_fields.py new file mode 100644 index 00000000..55863127 --- /dev/null +++ b/tests/test_reserved_fields.py @@ -0,0 +1,117 @@ +"""reserved_fields shows the bits that no field covers as reserved fields.""" + +import pytest + +from bust.core.bus import Bus +from bust.core.module import Module +from bust.exceptions import FormatError +from bust.generators.documentation_generator import DocumentationGenerator + +_BUS = {"type": "axi", "addr_width": 8, "data_width": 32} + +_CTRL = { + "name": "ctrl", + "sw": "rw", + "hw": "r", + "fields": [ + {"name": "enable", "type": "bit"}, + {"name": "mode", "type": "vector", "width": 2, "position": 4}, + ], +} + +_COUNT = {"name": "count", "type": "vector", "width": 8, "sw": "rw", "hw": "r"} + + +def _module(**keys): + config = {"name": "m", "register": [_CTRL, _COUNT], **keys} + return Module(config, Bus(_BUS), settings=None) + + +def _ranges(register): + return [ + (r.high, r.low, r.field.name if r.field else None) for r in register.bit_ranges + ] + + +def test_bit_ranges_cover_every_bit_from_the_highest_down(): + ctrl, count = _module().registers + + assert _ranges(ctrl) == [ + (31, 6, None), + (5, 4, "mode"), + (3, 1, None), + (0, 0, "enable"), + ] + assert _ranges(count) == [(31, 8, None), (7, 0, "count")] + + +def test_reserved_fields_is_off_by_default(): + assert _module().reserved_fields is False + + +@pytest.mark.parametrize("value", ["true", 1, None]) +def test_reserved_fields_must_be_a_boolean(value): + with pytest.raises(FormatError, match="reserved_fields must be true or false"): + _module(reserved_fields=value) + + +def test_reserved_fields_does_not_change_the_hash(): + assert _module().regmap_hash_hex == _module(reserved_fields=True).regmap_hash_hex + + +def _latex(**keys): + pytest.importorskip("pylatexenc") + return DocumentationGenerator(_module(**keys)).generate_tex_documentation("1.0.0") + + +def test_documentation_marks_every_gap_unused(): + tex = _latex() + + assert ( + " \\regfield{unused}{26}{6}{-}\n" + " \\regfield{mode}{2}{4}{{0x0}}\n" + " \\regfield{unused}{3}{1}{-}\n" + " \\regfield{enable}{1}{0}{0}\n" + ) in tex + assert "\\item [reserved]" not in tex + + +def test_documentation_lists_reserved_fields(): + tex = _latex(reserved_fields=True) + + assert ( + " \\regfield{reserved}{26}{6}{-}\n" + " \\regfield{mode}{2}{4}{{0x0}}\n" + " \\regfield{reserved}{3}{1}{-}\n" + " \\regfield{enable}{1}{0}{0}\n" + ) in tex + assert " \\regfield{reserved}{24}{8}{-}\n \\regfield{}{8}{0}" in tex + assert ( + " \\item [enable] (sw: rw, hw: r)\n" + " \\item [reserved] Bits 3:1. Read as 0, writes have no effect.\n" + " \\item [mode] (sw: rw, hw: r)\n" + " \\item [reserved] Bits 31:6. Read as 0, writes have no effect.\n" + ) in tex + + +def test_the_editor_overview_shows_reserved_fields(): + pytest.importorskip("textual") + from bust.editor.diagram import bit_diagram, field_notes, unused_name + + module = _module(reserved_fields=True) + ctrl = module.registers[0] + + names = bit_diagram(ctrl, 32, unused_name(module))[2] + assert [name.strip() for name in names.split("│")[1:-1]] == [ + "reserved", + "mode", + "reserved", + "enable", + ] + assert [name for name, _ in field_notes(ctrl, module.reserved_fields)] == [ + "enable", + "reserved", + "mode", + "reserved", + ] + assert [name for name, _ in field_notes(ctrl)] == ["enable", "mode"] From 6b7281866a7251c1171b6dbf84fee1b2a70a75dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Thu, 29 Oct 2026 15:15:58 +0000 Subject: [PATCH 2/2] Show unused bits as reserved in all docs and drop reserved_fields --- CHANGELOG.md | 4 +- bust/core/module.py | 20 ++-- bust/editor/diagram.py | 33 ++---- bust/editor/overview.py | 9 +- bust/editor/session.py | 8 +- bust/generators/documentation_generator.py | 6 +- bust/schema.py | 6 -- bust/templates/html/documentation.j2 | 4 +- bust/templates/latex/documentation.j2 | 4 +- bust/templates/markdown/documentation.j2 | 2 +- docs/command-line.md | 2 +- docs/documentation.md | 7 +- docs/register-map-format.md | 7 +- example/example_axi/doc/example_axi.html | 23 ++-- example/example_axi/doc/example_axi.md | 20 ++-- example/example_axi/doc/example_axi.tex | 23 ++-- example/example_ipbus/doc/example_ipbus.html | 23 ++-- example/example_ipbus/doc/example_ipbus.md | 20 ++-- example/example_ipbus/doc/example_ipbus.tex | 23 ++-- example/example_prototype/doc/prototype.html | 37 ++++--- example/example_prototype/doc/prototype.md | 26 ++--- example/example_prototype/doc/prototype.tex | 39 ++++--- tests/test_editor.py | 4 +- tests/test_reserved_fields.py | 105 ++++++------------- 24 files changed, 208 insertions(+), 247 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2315c3c6..34c9705f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,9 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). - `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. - The documentation hosts the register map JSON Schema at https://bust.readthedocs.io/en/stable/register-map.schema.json. A register map may point to it with a `"$schema"` key, which gives completion, hover text and errors in editors with JSON Schema support. The editor adds the key to new register maps. -- `reserved_fields` in `module`. With `true`, the documentation and the editor overview show the bits that no field covers as reserved fields, and list them among the fields. ### Changed +- The documentation and the editor overview show the bits that no field covers as `reserved` instead of `unused`, and list them among the fields with "Read as 0, writes have no effect." - 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. - `_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`. @@ -27,7 +27,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). - The Upgrading from 0.14 page. `--migrate` is described on the command line page. ### Fixed -- The LaTeX bit diagram drew no box for a gap made by `position`, and the Markdown bits table left out the bits below the lowest field. Both now mark them unused, as the editor overview and the HTML page already did. +- The LaTeX bit diagram drew no box for a gap made by `position`, and the Markdown bits table left out the bits below the lowest field. ## [1.0.0] diff --git a/bust/core/module.py b/bust/core/module.py index 5b0bc2cb..61a0b96d 100644 --- a/bust/core/module.py +++ b/bust/core/module.py @@ -46,7 +46,6 @@ "description", "version", "byte_addressable", - "reserved_fields", "register", ) @@ -64,8 +63,6 @@ class Module: description: Optional module description. version: Module version string. byte_addressable: Whether addresses are byte-based (defaults to the bus). - reserved_fields: Whether the documentation shows the bits that no field - covers as reserved fields. addr_width: Address bus width in bits. data_width: Data bus width in bits. bus: Bus configuration instance. @@ -83,15 +80,12 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: - description: Module description (default: "") - version: Version string (default: "") - byte_addressable: Use byte addressing (default: from the bus) - - reserved_fields: Document unused bits as reserved fields - (default: False) - register: List of register configurations (required) bus: Bus interface configuration. settings: Project-wide settings. Raises: - FormatError: If byte_addressable or reserved_fields is not a - boolean. + FormatError: If byte_addressable is not a boolean. InvalidAddress: If register addresses conflict. InvalidRegister: If register configuration is invalid. ValueError: If module name is not a valid VHDL identifier. @@ -116,7 +110,6 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: "description": "", "version": "", "byte_addressable": bus.byte_addressable, - "reserved_fields": False, }, ) @@ -126,8 +119,7 @@ def __init__(self, mod: Dict, bus: "Bus", settings: "Settings") -> None: # Store some config values for easy access self.description: str = self._config.get("description") self.version = self._read_version() - self.byte_addressable = self._read_boolean("byte_addressable") - self.reserved_fields = self._read_boolean("reserved_fields") + self.byte_addressable = self._read_byte_addressable() self.addr_width = bus.addr_width self.data_width = bus.data_width @@ -175,12 +167,12 @@ def add_register(self, reg: Dict) -> None: raise InvalidRegister(reg, e) from e self.registers.append(register) - def _read_boolean(self, key: str) -> bool: - """Read `key`, which must be true or false.""" - value = self._config.get(key) + def _read_byte_addressable(self) -> bool: + """Read byte_addressable, which must be true or false.""" + value = self._config.get("byte_addressable") if isinstance(value, bool): return value - raise FormatError(f"{key} must be true or false (got {value!r})") + raise FormatError(f"byte_addressable must be true or false (got {value!r})") def _read_version(self) -> str: """Read the version, which every generated file carries as a string.""" diff --git a/bust/editor/diagram.py b/bust/editor/diagram.py index ab0a1dc2..cb3f070f 100644 --- a/bust/editor/diagram.py +++ b/bust/editor/diagram.py @@ -34,13 +34,13 @@ def _reset(text: str, width: int) -> str: return str(value) if width < 2 else f"0x{value:X}" -def bit_segments(register: Register, unused_name: str = "unused") -> List[_Segment]: - """The fields of `register` from the highest bit down, with the unused - bits between them.""" +def bit_segments(register: Register) -> List[_Segment]: + """The fields of `register` from the highest bit down, with the bits no + field covers between them as reserved.""" segments = [] for bits in register.bit_ranges: if bits.field is None: - segments.append(_Segment(unused_name, bits.high, bits.low, "-", True)) + segments.append(_Segment("reserved", bits.high, bits.low, "-", True)) continue name = ( bits.field.name if register.type == RegisterType.FIELDS else register.name @@ -59,20 +59,12 @@ def bit_width(data_width: int) -> int: return 3 if data_width <= 32 else 2 -def unused_name(module: Module) -> str: - """The name the diagrams give bits that no field covers.""" - return "reserved" if module.reserved_fields else "unused" - - -def bit_diagram( - register: Register, data_width: int, unused: str = "unused" -) -> List[str]: +def bit_diagram(register: Register, data_width: int) -> List[str]: """The lines of the bit diagram of `register`: bit numbers, the boxes with - the field names, and the reset values. Bits that no field covers are - named `unused`.""" + the field names, and the reset values.""" bit = bit_width(data_width) numbers = top = names = bottom = resets = "" - for number, segment in enumerate(bit_segments(register, unused)): + for number, segment in enumerate(bit_segments(register)): high, low = str(segment.high), str(segment.low) bits = high if segment.width == 1 else f"{high} {low}" # A box grows past its bits rather than cut a name short. @@ -147,18 +139,15 @@ def _field_note(field: Field) -> str: return text -def field_notes( - register: Register, reserved_fields: bool = False -) -> List[Tuple[str, str]]: +def field_notes(register: Register) -> List[Tuple[str, str]]: """Each field's name, and its description with its access, as the - documentation lists them under a register, from the lowest bit up. With - `reserved_fields`, the bits that no field covers are listed as reserved - fields among them.""" + documentation lists them under a register, from the lowest bit up, with + the bits no field covers listed as reserved.""" notes = [] for bits in reversed(register.bit_ranges): if bits.field is not None: notes.append((bits.field.name, _field_note(bits.field))) - elif reserved_fields: + else: notes.append( ("reserved", f"Bits {_bits(bits.high, bits.low)}. {RESERVED_NOTE}") ) diff --git a/bust/editor/overview.py b/bust/editor/overview.py index cf536780..f7b599c7 100644 --- a/bust/editor/overview.py +++ b/bust/editor/overview.py @@ -16,7 +16,6 @@ field_notes, register_heading, register_list, - unused_name, ) @@ -71,16 +70,12 @@ def compose(self) -> ComposeResult: ) if register.description: yield Static(register.description, markup=False) - lines: List[str] = bit_diagram( - register, module.data_width, unused_name(module) - ) + lines: List[str] = bit_diagram(register, module.data_width) lines[-1] += " Reset" yield Static("\n".join(lines), classes="diagram", markup=False) if register.type == RegisterType.FIELDS: notes = Text() - for field, note in field_notes( - register, module.reserved_fields - ): + for field, note in field_notes(register): notes.append(f" {field}", style="bold") notes.append(f" {note}\n") notes.rstrip() diff --git a/bust/editor/session.py b/bust/editor/session.py index 68c355c7..07e5a7ea 100644 --- a/bust/editor/session.py +++ b/bust/editor/session.py @@ -265,13 +265,7 @@ def module_properties(self) -> List[Property]: key in data["module"], data["module"].get(key), ) - for key in ( - "name", - "description", - "version", - "byte_addressable", - "reserved_fields", - ) + for key in ("name", "description", "version", "byte_addressable") ] rows += [ Property( diff --git a/bust/generators/documentation_generator.py b/bust/generators/documentation_generator.py index 0df18cb7..48363808 100644 --- a/bust/generators/documentation_generator.py +++ b/bust/generators/documentation_generator.py @@ -14,7 +14,6 @@ field_notes, register_heading, register_list, - unused_name, ) from bust.jinja_utils.environment import render_template @@ -26,7 +25,7 @@ _MIN_BOX_HEIGHT = 28 -def bit_diagram_svg(register, data_width, unused): +def bit_diagram_svg(register, data_width): """An inline SVG of the bits of `register`, laid out as the LaTeX register package draws them: a box per field with its name, the numbers of its highest and lowest bit above it, and its reset value below. @@ -35,7 +34,7 @@ def bit_diagram_svg(register, data_width, unused): taller to fit the longest such name. """ bit = 24 if data_width <= 32 else 14 - segments = bit_segments(register, unused) + segments = bit_segments(register) is_turned = [len(s.name) * _CHAR_WIDTH + 6 > s.width * bit for s in segments] box_height = max( [_MIN_BOX_HEIGHT] @@ -125,7 +124,6 @@ def _render_template(self, template_name, version=None, **context): "module": self.module, "version": version, "reg_type_fields": RegisterType.FIELDS, - "unused_name": unused_name(self.module), **context, }, ) diff --git a/bust/schema.py b/bust/schema.py index 77db248b..ca1486e4 100644 --- a/bust/schema.py +++ b/bust/schema.py @@ -171,12 +171,6 @@ def _string(description: str, **extra: Any) -> Dict[str, Any]: "data words. Default: from the bus.", "type": "boolean", }, - "reserved_fields": { - "description": "true to show the bits that no field covers as " - "reserved fields in the documentation.", - "type": "boolean", - "default": False, - }, "register": { "description": "The registers.", "type": "array", diff --git a/bust/templates/html/documentation.j2 b/bust/templates/html/documentation.j2 index 335a6d97..6ca4879b 100644 --- a/bust/templates/html/documentation.j2 +++ b/bust/templates/html/documentation.j2 @@ -100,10 +100,10 @@ dl.fields dd { margin: 0 0 0.3rem; } {% if reg.description %}

{{ reg.description | utf8tohtml }}

{% endif %} -
{{ bit_diagram_svg(reg, module.data_width, unused_name) }}
+
{{ bit_diagram_svg(reg, module.data_width) }}
{% if reg.type == reg_type_fields %}
-{% for name, note in field_notes(reg, module.reserved_fields) %} +{% for name, note in field_notes(reg) %}
{{ name | e }}
{{ note | utf8tohtml }}
{% endfor %}
diff --git a/bust/templates/latex/documentation.j2 b/bust/templates/latex/documentation.j2 index b0374666..c30dbe39 100644 --- a/bust/templates/latex/documentation.j2 +++ b/bust/templates/latex/documentation.j2 @@ -68,13 +68,13 @@ {% if bits.field %} \regfield{{ '{' }}{% if reg.type == reg_type_fields %}{{ bits.field.name | utf8tolatex }}{% endif %}{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}{% if bits.width < 2 %}{{ bits.field.reset[2:]|int(base=16) }}{% else %}{0x{{ "%X" | format(bits.field.reset[2:]|int(base=16)) }}}{% endif %}{{ '}' }} {% else %} - \regfield{{ '{' }}{{ unused_name }}{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}-{{ '}' }} + \regfield{{ '{' }}reserved{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}-{{ '}' }} {% endif %} {% endfor %} \reglabel{Reset}\regnewline {% if reg.type == reg_type_fields %} \begin{{ '{' }}regdesc{{ '}' }}\begin{{ '{' }}reglist{{ '}' }}[{{ reg.fields | map(attribute='name') | min | utf8tolatex }}] -{% for bits in reg.bit_ranges | reverse if bits.field or module.reserved_fields %} +{% for bits in reg.bit_ranges | reverse %} {% if not bits.field %} \item [reserved] Bits {% if bits.width > 1 %}{{ bits.high }}:{% endif %}{{ bits.low }}. Read as 0, writes have no effect. {% else %} diff --git a/bust/templates/markdown/documentation.j2 b/bust/templates/markdown/documentation.j2 index 7e19694f..13327d6b 100644 --- a/bust/templates/markdown/documentation.j2 +++ b/bust/templates/markdown/documentation.j2 @@ -46,7 +46,7 @@ Address `0x{{ "%08X" | format(reg.address) }}`, {{ reg.sw.value.upper() }}/{{ re |------|------|----|----|-------|-------------| {% for range in reg.bit_ranges %} {% if not range.field %} -| {{ bits(range.high, range.low) }} | {{ unused_name }} | | | |{% if module.reserved_fields %} Read as 0, writes have no effect.{% endif %} | +| {{ bits(range.high, range.low) }} | reserved | | | | Read as 0, writes have no effect. | {% else %} {% set field = range.field %} {% set notes = field_notes(field) %} diff --git a/docs/command-line.md b/docs/command-line.md index b579a674..956d7af0 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -297,7 +297,7 @@ software and hardware access, address, type, width and reset of each register. Then each register follows with its address, its description and a bit diagram. The diagram draws each field as a box over its bits, with the numbers of its highest and lowest bit above and its reset value below. Bits no -field uses show as `unused`, or as `reserved` with [`reserved_fields`](register-map-format.md#reserved-fields). A box is wider than its bits where its name would +field uses show as `reserved`, see [Reserved fields](register-map-format.md#reserved-fields). A box is wider than its bits where its name would not fit. Under the diagram, each field is listed with its description and its access. diff --git a/docs/documentation.md b/docs/documentation.md index bfe6e48d..19e1496a 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -22,7 +22,7 @@ bust writes documentation of the register map to `doc/`, in the output directory 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 marked unused, or reserved with [`reserved_fields`](register-map-format.md#reserved-fields). A register with fields + The bits that no field covers are shown as [reserved fields](register-map-format.md#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. @@ -34,11 +34,12 @@ 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{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} ``` @@ -84,7 +85,7 @@ 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, or as reserved with [`reserved_fields`](register-map-format.md#reserved-fields). A register without fields gets one row, named after the register. +`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 [reserved](register-map-format.md#reserved-fields). 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. diff --git a/docs/register-map-format.md b/docs/register-map-format.md index 2f872695..281577b4 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -176,7 +176,6 @@ the timing of each protocol. | `version` | string | `""` | The version of the register map. Every generated file carries it, see [Version and hash](#version-and-hash). Printable ASCII characters other than `"`, `\`, `;` and `=`. A module with a `version` register needs the form `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`. | | `description` | string | `""` | Shown in the documentation. | | `byte_addressable` | boolean | from the bus | `true` if an address counts bytes, `false` if it counts data words. See [Byte and word addresses](#byte-and-word-addresses). | -| `reserved_fields` | boolean | `false` | `true` to show the bits that no field covers as reserved fields in the documentation. See [Reserved fields](#reserved-fields). | ### Version and hash @@ -449,7 +448,7 @@ Fields fill the register from bit 0 upwards, in the order you list them. Each field starts at the bit after the previous one, unless it has a `position`. A `position` can leave a gap, but it cannot go back, so list the fields from the lowest bit to the highest. In the example, `flush` sits at bit 8 and bits 4 to -7 of `ctrl` are unused: +7 of `ctrl` are reserved: | Field | Bits | |---|---| @@ -477,7 +476,7 @@ Bits that no field covers read as 0, and writes to them have no effect. ### Reserved fields -The LaTeX, HTML and Markdown documentation and the editor overview mark the bits that no field covers as `unused`. With `"reserved_fields": true` in `module`, they show as `reserved` fields instead, and each run of them gets an entry in the field list of a `fields` register, in bit order. For `ctrl` in the example: +The LaTeX, HTML and Markdown documentation and the editor overview show each run of bits that no field covers as a `reserved` field, in the bit diagram and among the fields, in bit order. For `ctrl` in the example: ```text 31 9 8 7 4 3 2 1 0 @@ -494,7 +493,7 @@ flush Write 1 to empty both FIFOs. (sw: rw, hw: r, singlepulse) reserved Bits 31:9. Read as 0, writes have no effect. ``` -Reserved fields exist only in the documentation and the editor overview. The VHDL, the headers and the IPBus address table do not change, and neither does the [hash](#version-and-hash). +Reserved fields exist only in the documentation and the editor overview, and you do not list them in the JSON file. The VHDL, the headers and the IPBus address table do not change, and neither does the [hash](#version-and-hash). ## Enumerations diff --git a/example/example_axi/doc/example_axi.html b/example/example_axi/doc/example_axi.html index 009184e7..b1307c65 100644 --- a/example/example_axi/doc/example_axi.html +++ b/example/example_axi/doc/example_axi.html @@ -114,31 +114,31 @@

2 Registers

reg0 - RW/R0x00000000

RW std_logic register that resets to 0x0

-
311unused-0reg00
+
311reserved-0reg00

Back to the register list

reg1 - RW/R0x00000004

RW std_logic register that resets to 0x1

-
311unused-0reg11
+
311reserved-0reg11

Back to the register list

reg2 - RO/W0x00000008

RO std_logic register

-
311unused-0reg20
+
311reserved-0reg20

Back to the register list

reg3 - RW/R0x0000000C

RW std_logic_vector[7:0] register that resets to 0x3

-
318unused-70reg30x3
+
318reserved-70reg30x3

Back to the register list

reg4 - RO/W0x00000010

RO std_logic_vector[13:0]

-
3114unused-130reg40x0
+
3114reserved-130reg40x0

Back to the register list

@@ -156,46 +156,49 @@

reg6 - RO/W0x00000018

reg7 - RW/R0x0000001C

RW register that have multiple fields

-
3121unused-206field30x2B5field2041field10xB0field01
+
3121reserved-206field30x2B5field2041field10xB0field01
field0
std_logic that resets to 0x1 (sw: rw, hw: r)
field1
std_logic_vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r)
field2
std_logic that resets to 0x1 (sw: rw, hw: r)
field3
std_logic_vector[14:0] that resets to 0x2b (sw: rw, hw: r)
+
reserved
Bits 31:21. Read as 0, writes have no effect.

Back to the register list

reg8 - RO/W0x00000020

RO register with multiple types of fields

-
3124unused-2321field30x020field20191field10x00field00
+
3124reserved-2321field30x020field20191field10x00field00
field0
std_logic field (sw: ro, hw: w)
field1
std_logic_vector[18:0] field (sw: ro, hw: w)
field2
std_logic field (sw: ro, hw: w)
field3
std_logic_vector[2:0] field (sw: ro, hw: w)
+
reserved
Bits 31:24. Read as 0, writes have no effect.

Back to the register list

reg9 - WO/R0x00000024

PULSE std_logic register that resets to 0x1

-
311unused-0reg91
+
311reserved-0reg91

Back to the register list

reg10 - WO/R0x00000028

PULSE std_logic_vector[3:0] register that resets to 0xA

-
314unused-30reg100xA
+
314reserved-30reg100xA

Back to the register list

reg11 - WO/R0x0000002C

PULSE register with two fields

-
3116unused-15field10140field00x3
+
3116reserved-15field10140field00x3
field0
std_logic_vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse)
field1
std_logic field that resets to 0x0 (sw: wo, hw: r, singlepulse)
+
reserved
Bits 31:16. Read as 0, writes have no effect.

Back to the register list

diff --git a/example/example_axi/doc/example_axi.md b/example/example_axi/doc/example_axi.md index b4a16b9c..5e79954f 100644 --- a/example/example_axi/doc/example_axi.md +++ b/example/example_axi/doc/example_axi.md @@ -33,7 +33,7 @@ RW std_logic register that resets to 0x0 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg0 | rw | r | `0x0` | | ### reg1 @@ -44,7 +44,7 @@ RW std_logic register that resets to 0x1 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg1 | rw | r | `0x1` | | ### reg2 @@ -55,7 +55,7 @@ RO std_logic register | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg2 | ro | w | `0x0` | | ### reg3 @@ -66,7 +66,7 @@ RW std_logic_vector\[7:0\] register that resets to 0x3 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | | 7:0 | reg3 | rw | r | `0x3` | | ### reg4 @@ -77,7 +77,7 @@ RO std_logic_vector\[13:0\] | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:14 | unused | | | | | +| 31:14 | reserved | | | | Read as 0, writes have no effect. | | 13:0 | reg4 | ro | w | `0x0` | | ### reg5 @@ -108,7 +108,7 @@ RW register that have multiple fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:21 | unused | | | | | +| 31:21 | reserved | | | | Read as 0, writes have no effect. | | 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 | @@ -122,7 +122,7 @@ RO register with multiple types of fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:24 | unused | | | | | +| 31:24 | reserved | | | | Read as 0, writes have no effect. | | 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 | @@ -136,7 +136,7 @@ PULSE std_logic register that resets to 0x1 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg9 | wo | r | `0x1` | singlepulse. | ### reg10 @@ -147,7 +147,7 @@ PULSE std_logic_vector\[3:0\] register that resets to 0xA | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:4 | unused | | | | | +| 31:4 | reserved | | | | Read as 0, writes have no effect. | | 3:0 | reg10 | wo | r | `0xA` | singlepulse. | ### reg11 @@ -158,7 +158,7 @@ PULSE register with two fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:16 | unused | | | | | +| 31:16 | reserved | | | | Read as 0, writes have no effect. | | 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_axi/doc/example_axi.tex b/example/example_axi/doc/example_axi.tex index 3e6be197..295e6b0f 100644 --- a/example/example_axi/doc/example_axi.tex +++ b/example/example_axi/doc/example_axi.tex @@ -87,35 +87,35 @@ \section{Registers} \begin{register}{H}{reg0 - RW/R}{0x00000000} \par RW std{\_}logic register that resets to 0x0 \regnewline \label{reg0} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{0} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg1 - RW/R}{0x00000004} \par RW std{\_}logic register that resets to 0x1 \regnewline \label{reg1} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{1} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg2 - RO/W}{0x00000008} \par RO std{\_}logic register \regnewline \label{reg2} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{0} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg3 - RW/R}{0x0000000C} \par RW std{\_}logic{\_}vector[7:0] register that resets to 0x3 \regnewline \label{reg3} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{}{8}{0}{{0x3}} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg4 - RO/W}{0x00000010} \par RO std{\_}logic{\_}vector[13:0] \regnewline \label{reg4} - \regfield{unused}{18}{14}{-} + \regfield{reserved}{18}{14}{-} \regfield{}{14}{0}{{0x0}} \reglabel{Reset}\regnewline \end{register} @@ -134,7 +134,7 @@ \section{Registers} \begin{register}{H}{reg7 - RW/R}{0x0000001C} \par RW register that have multiple fields \regnewline \label{reg7} - \regfield{unused}{11}{21}{-} + \regfield{reserved}{11}{21}{-} \regfield{field3}{15}{6}{{0x2B}} \regfield{field2}{1}{5}{0} \regfield{field1}{4}{1}{{0xB}} @@ -145,12 +145,13 @@ \section{Registers} \item [field1] std{\_}logic{\_}vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r) \item [field2] std{\_}logic that resets to 0x1 (sw: rw, hw: r) \item [field3] std{\_}logic{\_}vector[14:0] that resets to 0x2b (sw: rw, hw: r) + \item [reserved] Bits 31:21. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg8 - RO/W}{0x00000020} \par RO register with multiple types of fields \regnewline \label{reg8} - \regfield{unused}{8}{24}{-} + \regfield{reserved}{8}{24}{-} \regfield{field3}{3}{21}{{0x0}} \regfield{field2}{1}{20}{0} \regfield{field1}{19}{1}{{0x0}} @@ -161,32 +162,34 @@ \section{Registers} \item [field1] std{\_}logic{\_}vector[18:0] field (sw: ro, hw: w) \item [field2] std{\_}logic field (sw: ro, hw: w) \item [field3] std{\_}logic{\_}vector[2:0] field (sw: ro, hw: w) + \item [reserved] Bits 31:24. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg9 - WO/R}{0x00000024} \par PULSE std{\_}logic register that resets to 0x1 \regnewline \label{reg9} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{1} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg10 - WO/R}{0x00000028} \par PULSE std{\_}logic{\_}vector[3:0] register that resets to 0xA \regnewline \label{reg10} - \regfield{unused}{28}{4}{-} + \regfield{reserved}{28}{4}{-} \regfield{}{4}{0}{{0xA}} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg11 - WO/R}{0x0000002C} \par PULSE register with two fields \regnewline \label{reg11} - \regfield{unused}{16}{16}{-} + \regfield{reserved}{16}{16}{-} \regfield{field1}{1}{15}{0} \regfield{field0}{15}{0}{{0x3}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] std{\_}logic{\_}vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse) \item [field1] std{\_}logic field that resets to 0x0 (sw: wo, hw: r, singlepulse) + \item [reserved] Bits 31:16. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} diff --git a/example/example_ipbus/doc/example_ipbus.html b/example/example_ipbus/doc/example_ipbus.html index 99dcfc0d..64c324a6 100644 --- a/example/example_ipbus/doc/example_ipbus.html +++ b/example/example_ipbus/doc/example_ipbus.html @@ -110,31 +110,31 @@

2 Registers

reg0 - RW/R0x00000000

RW std_logic register that resets to 0x0

-
311unused-0reg00
+
311reserved-0reg00

Back to the register list

reg1 - RW/R0x00000004

RW std_logic register that resets to 0x1

-
311unused-0reg11
+
311reserved-0reg11

Back to the register list

reg2 - RO/W0x00000008

RO std_logic register

-
311unused-0reg20
+
311reserved-0reg20

Back to the register list

reg3 - RW/R0x0000000C

RW std_logic_vector[7:0] register that resets to 0x3

-
318unused-70reg30x3
+
318reserved-70reg30x3

Back to the register list

reg4 - RO/W0x00000010

RO std_logic_vector[13:0]

-
3114unused-130reg40x0
+
3114reserved-130reg40x0

Back to the register list

@@ -152,46 +152,49 @@

reg6 - RO/W0x00000018

reg7 - RW/R0x0000001C

RW register that have multiple fields

-
3121unused-206field30x2B5field2041field10xB0field01
+
3121reserved-206field30x2B5field2041field10xB0field01
field0
std_logic that resets to 0x1 (sw: rw, hw: r)
field1
std_logic_vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r)
field2
std_logic that resets to 0x1 (sw: rw, hw: r)
field3
std_logic_vector[14:0] that resets to 0x2b (sw: rw, hw: r)
+
reserved
Bits 31:21. Read as 0, writes have no effect.

Back to the register list

reg8 - RO/W0x00000020

RO register with multiple types of fields

-
3124unused-2321field30x020field20191field10x00field00
+
3124reserved-2321field30x020field20191field10x00field00
field0
std_logic field (sw: ro, hw: w)
field1
std_logic_vector[18:0] field (sw: ro, hw: w)
field2
std_logic field (sw: ro, hw: w)
field3
std_logic_vector[2:0] field (sw: ro, hw: w)
+
reserved
Bits 31:24. Read as 0, writes have no effect.

Back to the register list

reg9 - WO/R0x00000024

PULSE std_logic register that resets to 0x1

-
311unused-0reg91
+
311reserved-0reg91

Back to the register list

reg10 - WO/R0x00000028

PULSE std_logic_vector[3:0] register that resets to 0xA

-
314unused-30reg100xA
+
314reserved-30reg100xA

Back to the register list

reg11 - WO/R0x0000002C

PULSE register with two fields

-
3116unused-15field10140field00x3
+
3116reserved-15field10140field00x3
field0
std_logic_vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse)
field1
std_logic field that resets to 0x0 (sw: wo, hw: r, singlepulse)
+
reserved
Bits 31:16. Read as 0, writes have no effect.

Back to the register list

diff --git a/example/example_ipbus/doc/example_ipbus.md b/example/example_ipbus/doc/example_ipbus.md index 237b947f..82e5d52c 100644 --- a/example/example_ipbus/doc/example_ipbus.md +++ b/example/example_ipbus/doc/example_ipbus.md @@ -31,7 +31,7 @@ RW std_logic register that resets to 0x0 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg0 | rw | r | `0x0` | | ### reg1 @@ -42,7 +42,7 @@ RW std_logic register that resets to 0x1 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg1 | rw | r | `0x1` | | ### reg2 @@ -53,7 +53,7 @@ RO std_logic register | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg2 | ro | w | `0x0` | | ### reg3 @@ -64,7 +64,7 @@ RW std_logic_vector\[7:0\] register that resets to 0x3 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | | 7:0 | reg3 | rw | r | `0x3` | | ### reg4 @@ -75,7 +75,7 @@ RO std_logic_vector\[13:0\] | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:14 | unused | | | | | +| 31:14 | reserved | | | | Read as 0, writes have no effect. | | 13:0 | reg4 | ro | w | `0x0` | | ### reg5 @@ -106,7 +106,7 @@ RW register that have multiple fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:21 | unused | | | | | +| 31:21 | reserved | | | | Read as 0, writes have no effect. | | 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 | @@ -120,7 +120,7 @@ RO register with multiple types of fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:24 | unused | | | | | +| 31:24 | reserved | | | | Read as 0, writes have no effect. | | 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 | @@ -134,7 +134,7 @@ PULSE std_logic register that resets to 0x1 | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | reg9 | wo | r | `0x1` | singlepulse. | ### reg10 @@ -145,7 +145,7 @@ PULSE std_logic_vector\[3:0\] register that resets to 0xA | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:4 | unused | | | | | +| 31:4 | reserved | | | | Read as 0, writes have no effect. | | 3:0 | reg10 | wo | r | `0xA` | singlepulse. | ### reg11 @@ -156,6 +156,6 @@ PULSE register with two fields | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:16 | unused | | | | | +| 31:16 | reserved | | | | Read as 0, writes have no effect. | | 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_ipbus/doc/example_ipbus.tex b/example/example_ipbus/doc/example_ipbus.tex index 6014e9a6..5d7ea93f 100644 --- a/example/example_ipbus/doc/example_ipbus.tex +++ b/example/example_ipbus/doc/example_ipbus.tex @@ -83,35 +83,35 @@ \section{Registers} \begin{register}{H}{reg0 - RW/R}{0x00000000} \par RW std{\_}logic register that resets to 0x0 \regnewline \label{reg0} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{0} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg1 - RW/R}{0x00000004} \par RW std{\_}logic register that resets to 0x1 \regnewline \label{reg1} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{1} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg2 - RO/W}{0x00000008} \par RO std{\_}logic register \regnewline \label{reg2} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{0} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg3 - RW/R}{0x0000000C} \par RW std{\_}logic{\_}vector[7:0] register that resets to 0x3 \regnewline \label{reg3} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{}{8}{0}{{0x3}} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg4 - RO/W}{0x00000010} \par RO std{\_}logic{\_}vector[13:0] \regnewline \label{reg4} - \regfield{unused}{18}{14}{-} + \regfield{reserved}{18}{14}{-} \regfield{}{14}{0}{{0x0}} \reglabel{Reset}\regnewline \end{register} @@ -130,7 +130,7 @@ \section{Registers} \begin{register}{H}{reg7 - RW/R}{0x0000001C} \par RW register that have multiple fields \regnewline \label{reg7} - \regfield{unused}{11}{21}{-} + \regfield{reserved}{11}{21}{-} \regfield{field3}{15}{6}{{0x2B}} \regfield{field2}{1}{5}{0} \regfield{field1}{4}{1}{{0xB}} @@ -141,12 +141,13 @@ \section{Registers} \item [field1] std{\_}logic{\_}vector[3:0] that resets to 0xb is not a valid reset value (sw: rw, hw: r) \item [field2] std{\_}logic that resets to 0x1 (sw: rw, hw: r) \item [field3] std{\_}logic{\_}vector[14:0] that resets to 0x2b (sw: rw, hw: r) + \item [reserved] Bits 31:21. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg8 - RO/W}{0x00000020} \par RO register with multiple types of fields \regnewline \label{reg8} - \regfield{unused}{8}{24}{-} + \regfield{reserved}{8}{24}{-} \regfield{field3}{3}{21}{{0x0}} \regfield{field2}{1}{20}{0} \regfield{field1}{19}{1}{{0x0}} @@ -157,32 +158,34 @@ \section{Registers} \item [field1] std{\_}logic{\_}vector[18:0] field (sw: ro, hw: w) \item [field2] std{\_}logic field (sw: ro, hw: w) \item [field3] std{\_}logic{\_}vector[2:0] field (sw: ro, hw: w) + \item [reserved] Bits 31:24. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg9 - WO/R}{0x00000024} \par PULSE std{\_}logic register that resets to 0x1 \regnewline \label{reg9} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{}{1}{0}{1} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg10 - WO/R}{0x00000028} \par PULSE std{\_}logic{\_}vector[3:0] register that resets to 0xA \regnewline \label{reg10} - \regfield{unused}{28}{4}{-} + \regfield{reserved}{28}{4}{-} \regfield{}{4}{0}{{0xA}} \reglabel{Reset}\regnewline \end{register} \begin{register}{H}{reg11 - WO/R}{0x0000002C} \par PULSE register with two fields \regnewline \label{reg11} - \regfield{unused}{16}{16}{-} + \regfield{reserved}{16}{16}{-} \regfield{field1}{1}{15}{0} \regfield{field0}{15}{0}{{0x3}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] std{\_}logic{\_}vector[14:0] field that resets to 0x3 (sw: wo, hw: r, singlepulse) \item [field1] std{\_}logic field that resets to 0x0 (sw: wo, hw: r, singlepulse) + \item [reserved] Bits 31:16. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} diff --git a/example/example_prototype/doc/prototype.html b/example/example_prototype/doc/prototype.html index 85c0aefe..bab3eb52 100644 --- a/example/example_prototype/doc/prototype.html +++ b/example/example_prototype/doc/prototype.html @@ -110,119 +110,132 @@

2 Registers

reg0 - RW/R0x00000000

Plain rw storage, hardware reads back.

-
313unused-21field10x00field00
+
313reserved-21field10x00field00
field0
(sw: rw, hw: r)
field1
(sw: rw, hw: r)
+
reserved
Bits 31:3. Read as 0, writes have no effect.

Back to the register list

reg1 - RO/W0x00000004

Hardware-driven status, software read-only.

-
316unused-5field204field1030field00x0
+
316reserved-5field204field1030field00x0
field0
(sw: ro, hw: w)
field1
(sw: ro, hw: w)
field2
(sw: ro, hw: w)
+
reserved
Bits 31:6. Read as 0, writes have no effect.

Back to the register list

reg2 - WO/R0x00000008

Write-only command field.

-
311unused-0field00
+
311reserved-0field00
field0
(sw: wo, hw: r)
+
reserved
Bits 31:1. Read as 0, writes have no effect.

Back to the register list

reg3 - RW/NA0x0000000C

Software-only scratch register.

-
318unused-70field00x0
+
318reserved-70field00x0
field0
(sw: rw, hw: na)
+
reserved
Bits 31:8. Read as 0, writes have no effect.

Back to the register list

reg4 - RW/RW0x00000010

Hardware write-enable and hardware set/clear.

-
319unused-8field1074unused-30field00x0
+
319reserved-8field1074reserved-30field00x0
field0
(sw: rw, hw: rw)
+
reserved
Bits 7:4. Read as 0, writes have no effect.
field1
(sw: rw, hw: r)
+
reserved
Bits 31:9. Read as 0, writes have no effect.

Back to the register list

reg5 - RW/R0x00000014

Read side effects.

-
318unused-74field10x030field00x0
+
318reserved-74field10x030field00x0
field0
(sw: rw, hw: r, onread: rclr)
field1
(sw: rw, hw: r, onread: rset)
+
reserved
Bits 31:8. Read as 0, writes have no effect.

Back to the register list

reg6 - RW/R0x00000018

Write-1 onwrite effects.

-
3112unused-118field20x074field10xF30field00x0
+
3112reserved-118field20x074field10xF30field00x0
field0
(sw: rw, hw: r, onwrite: woset)
field1
(sw: rw, hw: r, onwrite: woclr)
field2
(sw: rw, hw: r, onwrite: wot)
+
reserved
Bits 31:12. Read as 0, writes have no effect.

Back to the register list

reg7 - RW/R0x0000001C

Write-0 onwrite effects.

-
3112unused-118field20x074field10xF30field00x0
+
3112reserved-118field20x074field10xF30field00x0
field0
(sw: rw, hw: r, onwrite: wzs)
field1
(sw: rw, hw: r, onwrite: wzc)
field2
(sw: rw, hw: r, onwrite: wzt)
+
reserved
Bits 31:12. Read as 0, writes have no effect.

Back to the register list

reg8 - RW/R0x00000020

Whole-field onwrite effects.

-
318unused-74field10x030field00xF
+
318reserved-74field10x030field00xF
field0
(sw: rw, hw: r, onwrite: wclr)
field1
(sw: rw, hw: r, onwrite: wset)
+
reserved
Bits 31:8. Read as 0, writes have no effect.

Back to the register list

reg9 - RW/R0x00000024

Software-access pulses.

-
318unused-74field10x030field00x0
+
318reserved-74field10x030field00x0
field0
(sw: rw, hw: r)
field1
(sw: rw, hw: r)
+
reserved
Bits 31:8. Read as 0, writes have no effect.

Back to the register list

reg10 - RW/R0x00000028

Single-cycle pulse on software write.

-
314unused-30field00x0
+
314reserved-30field00x0
field0
(sw: rw, hw: r, singlepulse)
+
reserved
Bits 31:4. Read as 0, writes have no effect.

Back to the register list

reg11 - RW/R0x0000002C

Enumerated field.

-
312unused-10field00x0
+
312reserved-10field00x0
field0
(sw: rw, hw: r; values: STATE0=0, STATE1=1, STATE2=2, STATE3=3)
+
reserved
Bits 31:2. Read as 0, writes have no effect.

Back to the register list

diff --git a/example/example_prototype/doc/prototype.md b/example/example_prototype/doc/prototype.md index a7e2e351..ed626d5e 100644 --- a/example/example_prototype/doc/prototype.md +++ b/example/example_prototype/doc/prototype.md @@ -31,7 +31,7 @@ Plain rw storage, hardware reads back. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:3 | unused | | | | | +| 31:3 | reserved | | | | Read as 0, writes have no effect. | | 2:1 | field1 | rw | r | `0x0` | | | 0 | field0 | rw | r | `0x0` | | @@ -43,7 +43,7 @@ Hardware-driven status, software read-only. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:6 | unused | | | | | +| 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. | @@ -56,7 +56,7 @@ Write-only command field. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:1 | unused | | | | | +| 31:1 | reserved | | | | Read as 0, writes have no effect. | | 0 | field0 | wo | r | `0x0` | | ### reg3 @@ -67,7 +67,7 @@ Software-only scratch register. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 31:8 | reserved | | | | Read as 0, writes have no effect. | | 7:0 | field0 | rw | na | `0x0` | | ### reg4 @@ -78,9 +78,9 @@ Hardware write-enable and hardware set/clear. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:9 | unused | | | | | +| 31:9 | reserved | | | | Read as 0, writes have no effect. | | 8 | field1 | rw | r | `0x0` | Modifiers: hwset, hwclr. | -| 7:4 | unused | | | | | +| 7:4 | reserved | | | | Read as 0, writes have no effect. | | 3:0 | field0 | rw | rw | `0x0` | Modifiers: we. | ### reg5 @@ -91,7 +91,7 @@ Read side effects. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 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. | @@ -103,7 +103,7 @@ Write-1 onwrite effects. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:12 | unused | | | | | +| 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. | @@ -116,7 +116,7 @@ Write-0 onwrite effects. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:12 | unused | | | | | +| 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. | @@ -129,7 +129,7 @@ Whole-field onwrite effects. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 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. | @@ -141,7 +141,7 @@ Software-access pulses. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:8 | unused | | | | | +| 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. | @@ -153,7 +153,7 @@ Single-cycle pulse on software write. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:4 | unused | | | | | +| 31:4 | reserved | | | | Read as 0, writes have no effect. | | 3:0 | field0 | rw | r | `0x0` | singlepulse. | ### reg11 @@ -164,5 +164,5 @@ Enumerated field. | Bits | Name | SW | HW | Reset | Description | |------|------|----|----|-------|-------------| -| 31:2 | unused | | | | | +| 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. | diff --git a/example/example_prototype/doc/prototype.tex b/example/example_prototype/doc/prototype.tex index fe279e41..4f9f21ae 100644 --- a/example/example_prototype/doc/prototype.tex +++ b/example/example_prototype/doc/prototype.tex @@ -83,19 +83,20 @@ \section{Registers} \begin{register}{H}{reg0 - RW/R}{0x00000000} \par Plain rw storage, hardware reads back. \regnewline \label{reg0} - \regfield{unused}{29}{3}{-} + \regfield{reserved}{29}{3}{-} \regfield{field1}{2}{1}{{0x0}} \regfield{field0}{1}{0}{0} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: r) \item [field1] (sw: rw, hw: r) + \item [reserved] Bits 31:3. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg1 - RO/W}{0x00000004} \par Hardware-driven status, software read-only. \regnewline \label{reg1} - \regfield{unused}{26}{6}{-} + \regfield{reserved}{26}{6}{-} \regfield{field2}{1}{5}{0} \regfield{field1}{1}{4}{0} \regfield{field0}{4}{0}{{0x0}} @@ -104,57 +105,63 @@ \section{Registers} \item [field0] (sw: ro, hw: w) \item [field1] (sw: ro, hw: w) \item [field2] (sw: ro, hw: w) + \item [reserved] Bits 31:6. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg2 - WO/R}{0x00000008} \par Write-only command field. \regnewline \label{reg2} - \regfield{unused}{31}{1}{-} + \regfield{reserved}{31}{1}{-} \regfield{field0}{1}{0}{0} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: wo, hw: r) + \item [reserved] Bits 31:1. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg3 - RW/NA}{0x0000000C} \par Software-only scratch register. \regnewline \label{reg3} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{field0}{8}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: na) + \item [reserved] Bits 31:8. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg4 - RW/RW}{0x00000010} \par Hardware write-enable and hardware set/clear. \regnewline \label{reg4} - \regfield{unused}{23}{9}{-} + \regfield{reserved}{23}{9}{-} \regfield{field1}{1}{8}{0} - \regfield{unused}{4}{4}{-} + \regfield{reserved}{4}{4}{-} \regfield{field0}{4}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: rw) + \item [reserved] Bits 7:4. Read as 0, writes have no effect. \item [field1] (sw: rw, hw: r) + \item [reserved] Bits 31:9. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg5 - RW/R}{0x00000014} \par Read side effects. \regnewline \label{reg5} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{field1}{4}{4}{{0x0}} \regfield{field0}{4}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: r, onread: rclr) \item [field1] (sw: rw, hw: r, onread: rset) + \item [reserved] Bits 31:8. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg6 - RW/R}{0x00000018} \par Write-1 onwrite effects. \regnewline \label{reg6} - \regfield{unused}{20}{12}{-} + \regfield{reserved}{20}{12}{-} \regfield{field2}{4}{8}{{0x0}} \regfield{field1}{4}{4}{{0xF}} \regfield{field0}{4}{0}{{0x0}} @@ -163,12 +170,13 @@ \section{Registers} \item [field0] (sw: rw, hw: r, onwrite: woset) \item [field1] (sw: rw, hw: r, onwrite: woclr) \item [field2] (sw: rw, hw: r, onwrite: wot) + \item [reserved] Bits 31:12. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg7 - RW/R}{0x0000001C} \par Write-0 onwrite effects. \regnewline \label{reg7} - \regfield{unused}{20}{12}{-} + \regfield{reserved}{20}{12}{-} \regfield{field2}{4}{8}{{0x0}} \regfield{field1}{4}{4}{{0xF}} \regfield{field0}{4}{0}{{0x0}} @@ -177,50 +185,55 @@ \section{Registers} \item [field0] (sw: rw, hw: r, onwrite: wzs) \item [field1] (sw: rw, hw: r, onwrite: wzc) \item [field2] (sw: rw, hw: r, onwrite: wzt) + \item [reserved] Bits 31:12. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg8 - RW/R}{0x00000020} \par Whole-field onwrite effects. \regnewline \label{reg8} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{field1}{4}{4}{{0x0}} \regfield{field0}{4}{0}{{0xF}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: r, onwrite: wclr) \item [field1] (sw: rw, hw: r, onwrite: wset) + \item [reserved] Bits 31:8. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg9 - RW/R}{0x00000024} \par Software-access pulses. \regnewline \label{reg9} - \regfield{unused}{24}{8}{-} + \regfield{reserved}{24}{8}{-} \regfield{field1}{4}{4}{{0x0}} \regfield{field0}{4}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: r) \item [field1] (sw: rw, hw: r) + \item [reserved] Bits 31:8. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg10 - RW/R}{0x00000028} \par Single-cycle pulse on software write. \regnewline \label{reg10} - \regfield{unused}{28}{4}{-} + \regfield{reserved}{28}{4}{-} \regfield{field0}{4}{0}{{0x0}} \reglabel{Reset}\regnewline \begin{regdesc}\begin{reglist}[field0] \item [field0] (sw: rw, hw: r, singlepulse) + \item [reserved] Bits 31:4. Read as 0, writes have no effect. \end{reglist}\end{regdesc} \end{register} \begin{register}{H}{reg11 - RW/R}{0x0000002C} \par Enumerated field. \regnewline \label{reg11} - \regfield{unused}{30}{2}{-} + \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} diff --git a/tests/test_editor.py b/tests/test_editor.py index 46ab0a1d..5dec2edf 100644 --- a/tests/test_editor.py +++ b/tests/test_editor.py @@ -488,7 +488,7 @@ async def script(editor): await editor.press("m") await editor.press("down", "down", "enter") await editor.fill(value="2.0") - await editor.press("down", "down", "down", "enter") + await editor.press("down", "down", "enter") await editor.fill(value="apb") await editor.press("escape", "s") @@ -646,7 +646,7 @@ def test_bit_diagram(): lines = bit_diagram(reg3, 32) assert lines[2].split("│")[1:3] == [ - " " * 33 + "unused" + " " * 32, + " " * 32 + "reserved" + " " * 31, " " * 10 + "reg3" + " " * 9, ] assert lines[1].startswith("┌") and lines[1].endswith("┐") diff --git a/tests/test_reserved_fields.py b/tests/test_reserved_fields.py index 7ed74e7d..319b2136 100644 --- a/tests/test_reserved_fields.py +++ b/tests/test_reserved_fields.py @@ -1,10 +1,9 @@ -"""reserved_fields shows the bits that no field covers as reserved fields.""" +"""The documentation shows the bits that no field covers as reserved fields.""" import pytest from bust.core.bus import Bus from bust.core.module import Module -from bust.exceptions import FormatError from bust.generators.documentation_generator import DocumentationGenerator _BUS = {"type": "axi", "addr_width": 8, "data_width": 32} @@ -22,8 +21,8 @@ _COUNT = {"name": "count", "type": "vector", "width": 8, "sw": "rw", "hw": "r"} -def _module(**keys): - config = {"name": "m", "register": [_CTRL, _COUNT], **keys} +def _module(*registers): + config = {"name": "m", "register": list(registers or (_CTRL, _COUNT))} return Module(config, Bus(_BUS), settings=None) @@ -45,39 +44,9 @@ def test_bit_ranges_cover_every_bit_from_the_highest_down(): assert _ranges(count) == [(31, 8, None), (7, 0, "count")] -def test_reserved_fields_is_off_by_default(): - assert _module().reserved_fields is False - - -@pytest.mark.parametrize("value", ["true", 1, None]) -def test_reserved_fields_must_be_a_boolean(value): - with pytest.raises(FormatError, match="reserved_fields must be true or false"): - _module(reserved_fields=value) - - -def test_reserved_fields_does_not_change_the_hash(): - assert _module().regmap_hash_hex == _module(reserved_fields=True).regmap_hash_hex - - -def _latex(**keys): +def test_latex_documentation_lists_reserved_fields(): pytest.importorskip("pylatexenc") - return DocumentationGenerator(_module(**keys)).generate_tex_documentation("1.0.0") - - -def test_documentation_marks_every_gap_unused(): - tex = _latex() - - assert ( - " \\regfield{unused}{26}{6}{-}\n" - " \\regfield{mode}{2}{4}{{0x0}}\n" - " \\regfield{unused}{3}{1}{-}\n" - " \\regfield{enable}{1}{0}{0}\n" - ) in tex - assert "\\item [reserved]" not in tex - - -def test_documentation_lists_reserved_fields(): - tex = _latex(reserved_fields=True) + tex = DocumentationGenerator(_module()).generate_tex_documentation("1.0.0") assert ( " \\regfield{reserved}{26}{6}{-}\n" @@ -92,34 +61,11 @@ def test_documentation_lists_reserved_fields(): " \\item [mode] (sw: rw, hw: r)\n" " \\item [reserved] Bits 31:6. Read as 0, writes have no effect.\n" ) in tex - - -def test_the_editor_overview_shows_reserved_fields(): - pytest.importorskip("textual") - from bust.editor.diagram import bit_diagram, field_notes, unused_name - - module = _module(reserved_fields=True) - ctrl = module.registers[0] - - names = bit_diagram(ctrl, 32, unused_name(module))[2] - assert [name.strip() for name in names.split("│")[1:-1]] == [ - "reserved", - "mode", - "reserved", - "enable", - ] - assert [name for name, _ in field_notes(ctrl, module.reserved_fields)] == [ - "enable", - "reserved", - "mode", - "reserved", - ] - assert [name for name, _ in field_notes(ctrl)] == ["enable", "mode"] + assert "unused" not in tex def test_html_documentation_lists_reserved_fields(): - html = DocumentationGenerator(_module(reserved_fields=True)) - page = html.generate_html_documentation("1.0.0") + page = DocumentationGenerator(_module()).generate_html_documentation("1.0.0") assert ( "
reserved
Bits 3:1. Read as 0, writes have no effect.
" in page @@ -129,23 +75,38 @@ def test_html_documentation_lists_reserved_fields(): def test_markdown_documentation_lists_reserved_fields(): - doc = DocumentationGenerator(_module(reserved_fields=True)) - page = doc.generate_markdown_documentation("1.0.0") + page = DocumentationGenerator(_module()).generate_markdown_documentation("1.0.0") assert ( "| 31:6 | reserved | | | | Read as 0, writes have no effect. |\n" "| 5:4 | mode |" ) in page assert "| 3:1 | reserved | | | | Read as 0, writes have no effect. |\n" in page - assert "| unused |" not in page -def test_markdown_documentation_marks_unused_bits_below_the_lowest_field(): - low_gap = { - "name": "irq", - "fields": [{"name": "done", "type": "bit", "position": 2}], - } - module = Module({"name": "m", "register": [low_gap]}, Bus(_BUS), settings=None) - page = DocumentationGenerator(module).generate_markdown_documentation("1.0.0") +def test_markdown_documentation_lists_bits_below_the_lowest_field(): + irq = {"name": "irq", "fields": [{"name": "done", "type": "bit", "position": 2}]} + page = DocumentationGenerator(_module(irq)).generate_markdown_documentation("1.0.0") + + assert "| 1:0 | reserved | | | | Read as 0, writes have no effect. |\n" in page + + +def test_the_editor_overview_shows_reserved_fields(): + pytest.importorskip("textual") + from bust.editor.diagram import bit_diagram, field_notes + + ctrl = _module().registers[0] - assert "| 1:0 | unused | | | | |\n" in page + names = bit_diagram(ctrl, 32)[2] + assert [name.strip() for name in names.split("│")[1:-1]] == [ + "reserved", + "mode", + "reserved", + "enable", + ] + assert [name for name, _ in field_notes(ctrl)] == [ + "enable", + "reserved", + "mode", + "reserved", + ]