Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
- `<module>_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`.

Expand All @@ -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 `<module>.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
Expand Down
29 changes: 29 additions & 0 deletions bust/core/register.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"""

import logging
from dataclasses import dataclass
from typing import Any, Dict, List, Optional, cast

from bust.exceptions import (
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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")
Expand Down
85 changes: 48 additions & 37 deletions bust/editor/diagram.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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


Expand All @@ -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.
Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion bust/generators/documentation_generator.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
20 changes: 11 additions & 9 deletions bust/templates/latex/documentation.j2
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
12 changes: 6 additions & 6 deletions bust/templates/markdown/documentation.j2
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
2 changes: 1 addition & 1 deletion docs/command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
7 changes: 4 additions & 3 deletions docs/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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}
```
Expand Down Expand Up @@ -84,7 +85,7 @@ altogether.

## Markdown

`doc/<module>.md` holds the register map as Markdown, for reading on GitHub or GitLab or in an editor, with no LaTeX needed. It has a line with the bust version, the `version` of the module and the hash of the register map under the title, then the `description` of the module, a **Register list** table where each name links to its register, and a **Registers** section with a table of the bits of each register. The bits table lists the fields from the highest bit down, with their bits, name, `sw`, `hw`, reset value and description, followed by the `onread`, `onwrite`, `singlepulse`, hardware modifiers and enumeration values where the field has them. Bits that no field uses are listed as unused. A register without fields gets one row, named after the register.
`doc/<module>.md` holds the register map as Markdown, for reading on GitHub or GitLab or in an editor, with no LaTeX needed. It has a line with the bust version, the `version` of the module and the hash of the register map under the title, then the `description` of the module, a **Register list** table where each name links to its register, and a **Registers** section with a table of the bits of each register. The bits table lists the fields from the highest bit down, with their bits, name, `sw`, `hw`, reset value and description, followed by the `onread`, `onwrite`, `singlepulse`, hardware modifiers and enumeration values where the field has them. Bits that no field uses are listed as [reserved](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.

Expand Down
23 changes: 22 additions & 1 deletion docs/register-map-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|
Expand All @@ -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
Expand Down
Loading
Loading