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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history).
- `bust.generate_files` returns every output file as `{path: content}`, without writing to disk or running `pdflatex`. The command line writes that result.
- `doc/<module>.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/<module>.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.

### Changed
- bust builds the PDF only when `pdflatex` is on `PATH`. Without it, bust writes the `.tex` and `.html` files and prints one line saying the PDF was skipped.
Expand Down
7 changes: 6 additions & 1 deletion bust/editing/document.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
join_pointer,
split_pointer,
)
from bust.schema import SCHEMA_URL
from bust.settings import Settings
from bust.utils.json_utils import json_parser
from bust.validation.schema_check import check_register_map
Expand Down Expand Up @@ -85,7 +86,11 @@ def new(cls, bus: Dict, module: Dict) -> "RegisterMapDocument":
Raises:
EditRejected: If bust rejects the bus or module settings.
"""
data = {"bus": bus, "module": {**module, "register": []}}
data = {
"$schema": SCHEMA_URL,
"bus": bus,
"module": {**module, "register": []},
}
document = cls(json.dumps(data, indent=4) + "\n", data, saved_text=None)
document.check()
return document
Expand Down
9 changes: 9 additions & 0 deletions bust/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@
SwAccess,
)

# The docs build writes the schema to this address, and Read the Docs rebuilds
# stable on each release. A register map points to it with a "$schema" key.
SCHEMA_URL = "https://bust.readthedocs.io/en/stable/register-map.schema.json"

# The forms parse_number reads. JSON5 0x1c parses to an integer, JSON "0x1c"
# to a string.
_NUMBER_PATTERN = r"^(0[xX][0-9a-fA-F]+|0[bB][01]+|[0-9]+)$"
Expand Down Expand Up @@ -191,11 +195,16 @@ def register_map_schema() -> Dict[str, Any]:
"""The JSON Schema of a register map file."""
schema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": SCHEMA_URL,
"title": "bust register map",
"type": "object",
"required": ["bus", "module"],
"additionalProperties": False,
"properties": {
"$schema": _string(
"The address of this schema, which lets an editor check the "
"file and complete keys. bust ignores it."
),
"bus": {"$ref": "#/$defs/bus"},
"module": {"$ref": "#/$defs/module"},
},
Expand Down
4 changes: 3 additions & 1 deletion bust/validation/schema_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,9 @@
"$ref",
]
)
ANNOTATION_KEYWORDS = frozenset(["$schema", "$defs", "title", "description", "default"])
ANNOTATION_KEYWORDS = frozenset(
["$schema", "$id", "$defs", "title", "description", "default"]
)

_TYPE_NAMES = {
"string": "a string",
Expand Down
12 changes: 12 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
# SPDX-License-Identifier: Apache-2.0
import json
import os
import shutil
import subprocess
import tempfile

from bust._version import __VERSION__
from bust.schema import SCHEMA_URL, register_map_schema

project = "bust"
author = "Ola Groettvik"
Expand Down Expand Up @@ -63,6 +65,15 @@
}


def _write_schema(app, exception):
if exception is not None or app.builder.format != "html":
return
path = os.path.join(app.outdir, os.path.basename(SCHEMA_URL))
with open(path, "w", encoding="utf-8") as fp:
json.dump(register_map_schema(), fp, indent=2)
fp.write("\n")


# The documentation bust generated for the prototype example, put into the
# built site so the docs can show it. Both come from the committed goldens,
# which the tests keep in step with the generator: the HTML is copied, and the
Expand Down Expand Up @@ -111,3 +122,4 @@ def _build_example_pdf(tex, out_dir):

def setup(app):
app.connect("build-finished", _add_example_docs)
app.connect("build-finished", _write_schema)
17 changes: 17 additions & 0 deletions docs/register-map-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -607,3 +607,20 @@ the register map, which step 2 checks. It lists each key with its allowed
values, its default and a short description, for editors and other tools.
bust also reads the values of `sw`, `hw`, `onread`, `onwrite` and `type` in
upper case, which the schema leaves out.

The schema of the latest release is at
<https://bust.readthedocs.io/en/stable/register-map.schema.json>. Point a
register map to it with a `"$schema"` key, and VS Code, JetBrains IDEs and other
editors with JSON Schema support complete keys, show each description on hover
and mark wrong values, with no extension:

```json
{
"$schema": "https://bust.readthedocs.io/en/stable/register-map.schema.json",
"bus": {"type": "axi", "addr_width": 32, "data_width": 32},
"module": {"name": "timer", "register": []}
}
```

bust ignores the key, and the [editor](command-line.md#interactive-editor) adds
it to each register map it creates.
5 changes: 4 additions & 1 deletion tests/test_editing_document.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
RegisterMapDocument,
diff_operations,
)
from bust.schema import SCHEMA_URL

_REPO_ROOT = os.path.dirname(os.path.dirname(__file__))
_EXAMPLES = sorted(
Expand Down Expand Up @@ -202,7 +203,9 @@ def test_a_new_register_map(tmp_path):
assert document.is_modified
assert document.save(path) is True
with open(path, encoding="utf-8") as fp:
assert json.load(fp)["module"]["register"] == [{"name": "ctrl"}]
saved = json.load(fp)
assert saved["$schema"] == SCHEMA_URL
assert saved["module"]["register"] == [{"name": "ctrl"}]
with pytest.raises(FileExistsError):
RegisterMapDocument.new(
{"type": "apb", "addr_width": 8, "data_width": 32}, {"name": "timer"}
Expand Down
2 changes: 2 additions & 0 deletions tests/test_editor.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
QuestionScreen,
TextScreen,
)
from bust.schema import SCHEMA_URL # noqa: E402

_REPO_ROOT = os.path.dirname(os.path.dirname(__file__))
_BLINKY = os.path.join(_REPO_ROOT, "tests", "data", "migrate", "axi", "blinky.json")
Expand Down Expand Up @@ -179,6 +180,7 @@ async def script(editor):

assert f"Saved {path}." in editor.messages
expected = {
"$schema": SCHEMA_URL,
"bus": {"type": "axi", "addr_width": 16, "data_width": 32},
"module": {
"name": "uart",
Expand Down
7 changes: 6 additions & 1 deletion tests/test_schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
from bust.core.field import FIELD_KEYS
from bust.core.module import MODULE_KEYS
from bust.core.register import REGISTER_KEYS
from bust.schema import register_map_schema
from bust.schema import SCHEMA_URL, register_map_schema
from bust.utils.json_utils import json_parser

_REPO_ROOT = os.path.dirname(os.path.dirname(__file__))
Expand Down Expand Up @@ -61,6 +61,11 @@ def test_the_schema_has_the_keys_bust_reads(definition, keys):
assert set(register_map_schema()["$defs"][definition]["properties"]) == keys


def test_a_register_map_may_point_to_the_schema():
assert register_map_schema()["$id"] == SCHEMA_URL
_validator().validate({"$schema": SCHEMA_URL, **_REGISTER_MAP})


def test_numbers_in_both_forms():
register = _REGISTER_MAP["module"]["register"][0]
for address in (28, "28", "0x1c", "0X1C", "0b11100"):
Expand Down
3 changes: 2 additions & 1 deletion tests/test_schema_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

from bust.editing.json_source import JsonSource
from bust.exceptions import FormatError
from bust.schema import register_map_schema
from bust.schema import SCHEMA_URL, register_map_schema
from bust.utils.json_utils import json_parser, parse_json_text
from bust.validation.schema_check import (
ANNOTATION_KEYWORDS,
Expand Down Expand Up @@ -211,6 +211,7 @@ def test_unknown_keys_are_warnings():
(("module", "register", 0, "type"), "VECTOR"),
(("module", "register", 0, "address"), "0X1C"),
(("module", "register", 0, "we"), False),
(("$schema",), SCHEMA_URL),
],
)
def test_forms_bust_reads_are_not_problems(path, value):
Expand Down
Loading