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
108 changes: 2 additions & 106 deletions bust/editor/diagram.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,47 +7,10 @@
box is wider than its bits where its name would not fit.
"""

from dataclasses import dataclass
from typing import List, Tuple
from typing import List

from bust.core.enums import RegisterType
from bust.core.field import Field
from bust.core.module import Module
from bust.core.register import Register


@dataclass
class _Segment:
name: str
high: int
low: int
reset: str
is_unused: bool = False

@property
def width(self) -> int:
return self.high - self.low + 1


def _reset(text: str, width: int) -> str:
value = int(text, 16)
return str(value) if width < 2 else f"0x{value:X}"


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
from bust.generators.register_layout import bit_segments


def _fit(text: str, width: int) -> str:
Expand Down Expand Up @@ -85,70 +48,3 @@ def bit_diagram(register: Register, data_width: int) -> List[str]:
label = " " + high.ljust(inner - len(low) - 2) + low + " "
numbers += " " + label
return [numbers, top + "┐", names + "│", bottom + "┘", resets]


def _access(register: Register) -> str:
return f"{register.sw.value.upper()}/{register.hw.value.upper()}"


def register_list(module: Module) -> Tuple[List[str], List[List[str]]]:
"""The headings and rows of the register list."""
headers = ["#", "Name", "SW/HW", "Address", "Type", "Width", "Reset"]
rows = [
[
str(index),
reg.name,
_access(reg),
f"0x{reg.address:08X}",
reg.type.value.upper(),
str(reg.width),
f"0x{int(reg.reset, 16):X}",
]
for index, reg in enumerate(module.registers)
]
return headers, rows


def register_heading(register: Register) -> Tuple[str, str]:
"""The name and access, and the address, as the documentation heads a
register."""
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, 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)))
else:
notes.append(
("reserved", f"Bits {_bits(bits.high, bits.low)}. {RESERVED_NOTE}")
)
return notes
4 changes: 2 additions & 2 deletions bust/editor/overview.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@

from bust.core.enums import RegisterType
from bust.core.module import Module
from bust.editor.diagram import (
bit_diagram,
from bust.editor.diagram import bit_diagram
from bust.generators.register_layout import (
field_notes,
register_heading,
register_list,
Expand Down
4 changes: 3 additions & 1 deletion bust/generators/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
from module definitions:

- HeaderGenerator: Language header file generation (C, C++, Python)
- DocumentationGenerator: LaTeX documentation generation
- DocumentationGenerator: LaTeX, HTML and Markdown documentation generation
- register_layout: The register list, bit segments and field notes the
documentation and the editor share
- GeneratorFactory: Factory for creating VHDL generators
- vhdl subpackage: VHDL code generators
"""
Expand Down
21 changes: 12 additions & 9 deletions bust/generators/documentation_generator.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@

from bust._version import __VERSION__
from bust.core.enums import RegisterType
from bust.editor.diagram import (
from bust.generators.register_layout import (
RESERVED_NOTE,
bit_segments,
bits_text,
field_notes,
register_heading,
register_list,
Expand Down Expand Up @@ -118,12 +120,20 @@ def _render_template(self, template_name, version=None, **context):
if version is None:
version = __VERSION__

headers, rows = register_list(self.module)
return render_template(
template_name,
{
"module": self.module,
"version": version,
"reg_type_fields": RegisterType.FIELDS,
"list_headers": headers,
"list_rows": list(zip(rows, self.module.registers)),
"register_heading": register_heading,
"bit_segments": bit_segments,
"field_notes": field_notes,
"bits_text": bits_text,
"reserved_note": RESERVED_NOTE,
**context,
},
)
Expand Down Expand Up @@ -154,15 +164,8 @@ def generate_html_documentation(self, test_version=None):
Returns:
HTML document as string.
"""
headers, rows = register_list(self.module)
return self._render_template(
"html/documentation.j2",
test_version,
list_headers=headers,
list_rows=zip(rows, self.module.registers),
register_heading=register_heading,
field_notes=field_notes,
bit_diagram_svg=bit_diagram_svg,
"html/documentation.j2", test_version, bit_diagram_svg=bit_diagram_svg
)

def generate_markdown_documentation(self, test_version=None):
Expand Down
116 changes: 116 additions & 0 deletions bust/generators/register_layout.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
"""The layout the documentation and the editor share: the register list, the
heading of each register, the fields of a register from the highest bit down,
and the notes listed under a register.

The LaTeX, HTML and Markdown documentation and the editor overview all build on
these, so they show the same values in the same form.
"""

from dataclasses import dataclass
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


@dataclass
class BitSegment:
name: str
high: int
low: int
reset: str
is_unused: bool = False

@property
def width(self) -> int:
return self.high - self.low + 1


def reset_text(text: str, width: int) -> str:
value = int(text, 16)
return str(value) if width < 2 else f"0x{value:X}"


def bit_segments(register: Register) -> List[BitSegment]:
"""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(BitSegment("reserved", bits.high, bits.low, "-", True))
continue
name = (
bits.field.name if register.type == RegisterType.FIELDS else register.name
)
reset = reset_text(bits.field.reset, bits.width)
segments.append(BitSegment(name, bits.high, bits.low, reset))
return segments


def access_text(register: Register) -> str:
return f"{register.sw.value.upper()}/{register.hw.value.upper()}"


def register_list(module: Module) -> Tuple[List[str], List[List[str]]]:
"""The headings and rows of the register list."""
headers = ["#", "Name", "SW/HW", "Address", "Type", "Width", "Reset"]
rows = [
[
str(index),
reg.name,
access_text(reg),
f"0x{reg.address:08X}",
reg.type.value.upper(),
str(reg.width),
f"0x{int(reg.reset, 16):X}",
]
for index, reg in enumerate(module.registers)
]
return headers, rows


def register_heading(register: Register) -> Tuple[str, str]:
"""The name and access, and the address, as the documentation heads a
register."""
return f"{register.name} - {access_text(register)}", f"0x{register.address:08X}"


RESERVED_NOTE = "Read as 0, writes have no effect."


def bits_text(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, 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)))
else:
notes.append(
("reserved", f"Bits {bits_text(bits.high, bits.low)}. {RESERVED_NOTE}")
)
return notes
27 changes: 11 additions & 16 deletions bust/templates/latex/documentation.j2
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@
\textbf{\#} & \textbf{Name} & \textbf{SW/HW} & \textbf{Address} & \textbf{Type} & \textbf{Width} &
\textbf{Reset} \\
\hline
{% for reg in module.registers %}
{{ loop.index0 }} & {{ reg.name | utf8tolatex }} & {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }} & \texttt{0x{{ "%08X" | format(reg.address) }}} & {{ reg.type.value.upper() }} & {{ reg.width }} & \texttt{0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}} \\
{% for row, reg in list_rows %}
{{ row[0] }} & {{ row[1] | utf8tolatex }} & {{ row[2] }} & \texttt{{ '{' }}{{ row[3] }}{{ '}' }} & {{ row[4] }} & {{ row[5] }} & \texttt{{ '{' }}{{ row[6] }}{{ '}' }} \\
\hline
{% endfor %}
\end{tabularx}
Expand All @@ -62,25 +62,20 @@
\section{Registers}

{% 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 +%}
{% set title, address = register_heading(reg) %}
\begin{register}{{ '{' }}H{{ '}' }}{{ '{' }}{{ title | utf8tolatex }}{{ '}' }}{{ '{' }}{{ address }}{{ '}' }}{% if reg.description %} \par {{ reg.description | utf8tolatex }} \regnewline{% endif +%}
\label{{ '{' }}{{ reg.name }}{{ '}' }}
{% 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 %}
\regfield{{ '{' }}reserved{{ '}' }}{{ '{' }}{{ bits.width }}{{ '}' }}{{ '{' }}{{ bits.low }}{{ '}' }}{{ '{' }}-{{ '}' }}
{% endif %}
{% for segment in bit_segments(reg) %}
{# A register without fields is one unnamed box, as its name heads it already. #}
{% set name = segment.name if reg.type == reg_type_fields or segment.is_unused else "" %}
{% set reset = segment.reset if segment.width < 2 or segment.is_unused else "{" ~ segment.reset ~ "}" %}
\regfield{{ '{' }}{{ name | utf8tolatex }}{{ '}' }}{{ '{' }}{{ segment.width }}{{ '}' }}{{ '{' }}{{ segment.low }}{{ '}' }}{{ '{' }}{{ reset }}{{ '}' }}
{% 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 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 %}
{% for name, note in field_notes(reg) %}
\item [{{ name | utf8tolatex }}] {{ note | utf8tolatex }}
{% endfor %} \end{{ '{' }}reglist{{ '}' }}\end{{ '{' }}regdesc{{ '}' }}
{% endif %}
\end{register}
Expand Down
13 changes: 6 additions & 7 deletions bust/templates/markdown/documentation.j2
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
{% macro bits(high, low) %}{{ high }}{% if high > low %}:{{ low }}{% endif %}{% endmacro %}
{% macro field_notes(field) %}
{% macro field_cell(field) %}
{% set notes = [] %}
{% if field.description %}{% set _ = notes.append(field.description | markdown_cell) %}{% endif %}
{% if field.onread %}{% set _ = notes.append("onread: " ~ field.onread.value ~ ".") %}{% endif %}
Expand Down Expand Up @@ -27,8 +26,8 @@ Generated by bust v{{ version }}. {% if module.version %}Version: {{ module.vers

| # | Name | SW/HW | Address | Type | Width | Reset |
|--:|------|-------|---------|------|------:|-------|
{% for reg in module.registers %}
| {{ loop.index0 }} | [{{ reg.name }}](#{{ reg.name | lower }}) | {{ reg.sw.value.upper() }}/{{ reg.hw.value.upper() }} | `0x{{ "%08X" | format(reg.address) }}` | {{ reg.type.value.upper() }} | {{ reg.width }} | `0x{{ "%X" | format(reg.reset[2:]|int(base=16)) }}` |
{% for row, reg in list_rows %}
| {{ row[0] }} | [{{ row[1] }}](#{{ reg.name | lower }}) | {{ row[2] }} | `{{ row[3] }}` | {{ row[4] }} | {{ row[5] }} | `{{ row[6] }}` |
{% endfor %}

## Registers
Expand All @@ -46,11 +45,11 @@ 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) }} | reserved | | | | Read as 0, writes have no effect. |
| {{ bits_text(range.high, range.low) }} | reserved | | | | {{ reserved_note }} |
{% 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 notes = field_cell(field) %}
| {{ bits_text(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 %} |
{% endif %}
{% endfor %}
{% endfor %}
Loading
Loading