diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e43f9f3..34c9705f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). - 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. ### 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`. @@ -25,6 +26,9 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). - 0.14 conversion in the editor, the 0.14 `.vhd` warning, and `RegisterMode` in the Python API. - 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. + ## [1.0.0] First release of bust 1.0, a rewrite of bust 0.14. Install it with 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 41b6dabf..cb3f070f 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 @@ -33,26 +34,19 @@ def _reset(text: str, width: int) -> str: return str(value) if width < 2 else f"0x{value:X}" -def bit_segments(register: Register, data_width: int) -> 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, "-", True)) - segments.append(segment) - next_high = segment.low - 1 - if next_high >= 0: - segments.append(_Segment("unused", next_high, 0, "-", True)) +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("reserved", bits.high, bits.low, "-", True)) + 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 @@ -70,7 +64,7 @@ def bit_diagram(register: Register, data_width: int) -> List[str]: 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, data_width)): + 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. @@ -121,23 +115,40 @@ def register_heading(register: Register) -> Tuple[str, str]: return f"{register.name} - {_access(register)}", f"0x{register.address:08X}" +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) -> 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 + the bits no field covers listed as reserved.""" 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))) + else: + notes.append( + ("reserved", f"Bits {_bits(bits.high, bits.low)}. {RESERVED_NOTE}") + ) return notes diff --git a/bust/generators/documentation_generator.py b/bust/generators/documentation_generator.py index da241cd5..48363808 100644 --- a/bust/generators/documentation_generator.py +++ b/bust/generators/documentation_generator.py @@ -34,7 +34,7 @@ def bit_diagram_svg(register, data_width): taller to fit the longest such name. """ bit = 24 if data_width <= 32 else 14 - segments = bit_segments(register, data_width) + 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] diff --git a/bust/templates/latex/documentation.j2 b/bust/templates/latex/documentation.j2 index e7068c14..c30dbe39 100644 --- a/bust/templates/latex/documentation.j2 +++ b/bust/templates/latex/documentation.j2 @@ -64,21 +64,23 @@ {% 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{{ '{' }}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 field in reg.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 %} +{% 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/bust/templates/markdown/documentation.j2 b/bust/templates/markdown/documentation.j2 index 1b3639a9..13327d6b 100644 --- a/bust/templates/markdown/documentation.j2 +++ b/bust/templates/markdown/documentation.j2 @@ -44,13 +44,13 @@ Address `0x{{ "%08X" | format(reg.address) }}`, {{ reg.sw.value.upper() }}/{{ re | 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 %} +{% for range in reg.bit_ranges %} +{% if not range.field %} +| {{ bits(range.high, range.low) }} | reserved | | | | Read as 0, writes have no effect. | +{% else %} +{% set field = range.field %} {% 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 %} +{% endif %} {% endfor %} {% endfor %} diff --git a/docs/command-line.md b/docs/command-line.md index a9290f01..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`. 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 d8a200b8..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 above the highest field are marked unused. 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. 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 e17e99e7..281577b4 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -448,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 | |---|---| @@ -474,6 +474,27 @@ Register width: 33 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 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 +┌────────────────────────────────────────────────────────────────────┬───────┬───────────┬────────┬───────┬───────┐ +│ reserved │ flush │ reserved │ parity │ rx_en │ tx_en │ +└────────────────────────────────────────────────────────────────────┴───────┴───────────┴────────┴───────┴───────┘ + - 0 - 0x0 0 0 + +tx_en Enable the transmitter. (sw: rw, hw: r) +rx_en Enable the receiver. (sw: rw, hw: r) +parity Parity bit. (sw: rw, hw: r; values: PAR_NONE=0, PAR_EVEN=1, PAR_ODD=2) +reserved Bits 7:4. Read as 0, writes have no effect. +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, 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 A field with an `enums` list has named values. bust generates a VHDL 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 fc513b6d..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,56 +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{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}} @@ -162,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}} @@ -176,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 97ef0015..5dec2edf 100644 --- a/tests/test_editor.py +++ b/tests/test_editor.py @@ -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 new file mode 100644 index 00000000..319b2136 --- /dev/null +++ b/tests/test_reserved_fields.py @@ -0,0 +1,112 @@ +"""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.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(*registers): + config = {"name": "m", "register": list(registers or (_CTRL, _COUNT))} + 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_latex_documentation_lists_reserved_fields(): + pytest.importorskip("pylatexenc") + tex = DocumentationGenerator(_module()).generate_tex_documentation("1.0.0") + + 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 + assert "unused" not in tex + + +def test_html_documentation_lists_reserved_fields(): + page = DocumentationGenerator(_module()).generate_html_documentation("1.0.0") + + assert ( + "
reserved
Bits 3:1. Read as 0, writes have no effect.
" in page + ) + assert ">reserved" in page + assert ">unused" not in page + + +def test_markdown_documentation_lists_reserved_fields(): + 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 + + +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] + + 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", + ]