From 407dd9693bfa780193dd18a6163dd0479eea280a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Tue, 27 Oct 2026 13:05:40 +0000 Subject: [PATCH] Host register map schema at fixed URL and accept a $schema key --- CHANGELOG.md | 3 +++ bust/editing/document.py | 7 ++++++- bust/schema.py | 9 +++++++++ bust/validation/schema_check.py | 4 +++- docs/conf.py | 17 +++++++++++++++++ docs/register-map-format.md | 17 +++++++++++++++++ tests/test_editing_document.py | 5 ++++- tests/test_editor.py | 2 ++ tests/test_schema.py | 7 ++++++- tests/test_schema_check.py | 3 ++- 10 files changed, 69 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bb6fa34d..07e42f0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). ## [Unreleased] +### Added +- 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 - `_regfile_pkg` merges `base_match` and `above_registers` into one function, `is_in_range`. diff --git a/bust/editing/document.py b/bust/editing/document.py index 3b5a3b1d..92d87c0f 100644 --- a/bust/editing/document.py +++ b/bust/editing/document.py @@ -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 @@ -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 diff --git a/bust/schema.py b/bust/schema.py index b79b0cf7..ca1486e4 100644 --- a/bust/schema.py +++ b/bust/schema.py @@ -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]+)$" @@ -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"}, }, diff --git a/bust/validation/schema_check.py b/bust/validation/schema_check.py index 7441d01d..8b24397a 100644 --- a/bust/validation/schema_check.py +++ b/bust/validation/schema_check.py @@ -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", diff --git a/docs/conf.py b/docs/conf.py index 46d6b0a2..8e5523c0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,9 @@ # SPDX-License-Identifier: Apache-2.0 +import json +import os + from bust._version import __VERSION__ +from bust.schema import SCHEMA_URL, register_map_schema project = "bust" author = "Ola Groettvik" @@ -55,3 +59,16 @@ "color-highlighted-background": "#2f2c2a", }, } + + +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") + + +def setup(app): + app.connect("build-finished", _write_schema) diff --git a/docs/register-map-format.md b/docs/register-map-format.md index 676b4813..18b6bfe6 100644 --- a/docs/register-map-format.md +++ b/docs/register-map-format.md @@ -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 +. 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. diff --git a/tests/test_editing_document.py b/tests/test_editing_document.py index f640e740..b4c518dc 100644 --- a/tests/test_editing_document.py +++ b/tests/test_editing_document.py @@ -13,6 +13,7 @@ RegisterMapDocument, diff_operations, ) +from bust.schema import SCHEMA_URL _REPO_ROOT = os.path.dirname(os.path.dirname(__file__)) _EXAMPLES = sorted( @@ -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"} diff --git a/tests/test_editor.py b/tests/test_editor.py index 7fbfa873..97ef0015 100644 --- a/tests/test_editor.py +++ b/tests/test_editor.py @@ -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") @@ -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", diff --git a/tests/test_schema.py b/tests/test_schema.py index bd2a9c21..74a57a50 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -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__)) @@ -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"): diff --git a/tests/test_schema_check.py b/tests/test_schema_check.py index bc35c312..4a1553c4 100644 --- a/tests/test_schema_check.py +++ b/tests/test_schema_check.py @@ -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, @@ -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):