From c2776f57447ab1d8a18a96b01e4b5823159030e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Fri, 30 Oct 2026 08:38:07 +0000 Subject: [PATCH 1/2] Add JSON-RPC bridge between an editor UI and RegisterMapDocument --- bust/editing/bridge.py | 226 +++++++++++++++++++++++++++++++++++ bust/editing/document.py | 27 ++++- tests/test_editing_bridge.py | 146 ++++++++++++++++++++++ 3 files changed, 397 insertions(+), 2 deletions(-) create mode 100644 bust/editing/bridge.py create mode 100644 tests/test_editing_bridge.py diff --git a/bust/editing/bridge.py b/bust/editing/bridge.py new file mode 100644 index 0000000..1075759 --- /dev/null +++ b/bust/editing/bridge.py @@ -0,0 +1,226 @@ +"""The messages between a register map editor UI and bust. + +The editor in editor-ui/ talks to bust in JSON-RPC 2.0 messages, the same in +every host: cloudbust passes them to bust in Pyodide, an editor on the desktop +to ``python -m bust.editing.bridge`` over stdin and stdout, one message per +line. + +Methods: + schema: The JSON Schema of a register map. + open {text}: Start editing the register map in `text`. + new {bus, module}: Start a register map with no registers. + apply {operations}: Make a change, given as JSON Patch operations. + undo, redo: Step back or forward through the changes. + +Every method but schema returns a state. An accepted state holds the register +map's data and text, bust's warnings, the address and bits bust gives each +register and field, the address a new register would get, and whether undo and redo can step. A +rejected state holds bust's problems, and the register map stays as it was. +Each problem has the path to the value it is about, as a list of keys and +indexes, and the line for problems in the text given to open. +""" + +import json +import sys +from typing import Any, Callable, Dict, List, Optional, TextIO + +from bust.editing.document import EditRejected, RegisterMapDocument +from bust.exceptions import FormatError +from bust.schema import register_map_schema +from bust.validation.schema_check import Problem, check_register_map + +State = Dict[str, Any] + +_TEXT_NAME = "register map" + +# The JSON-RPC 2.0 error codes. +_PARSE_ERROR = -32700 +_INVALID_REQUEST = -32600 +_METHOD_NOT_FOUND = -32601 +_INVALID_PARAMS = -32602 +# In the range JSON-RPC leaves to the server. +_NO_DOCUMENT = -32000 + + +class NoDocument(RuntimeError): + """Raised for a change before open or new.""" + + +class EditorBridge: + """One register map being edited, behind JSON-RPC messages.""" + + def __init__(self) -> None: + self._document: Optional[RegisterMapDocument] = None + self._warnings: List[str] = [] + self._undo: List[RegisterMapDocument] = [] + self._redo: List[RegisterMapDocument] = [] + self._methods: Dict[str, Callable[..., Any]] = { + "schema": register_map_schema, + "open": self.open, + "new": self.new, + "apply": self.apply, + "undo": self.undo, + "redo": self.redo, + } + + def handle(self, message: str) -> str: + """The JSON-RPC response to one JSON-RPC request.""" + try: + request = json.loads(message) + except ValueError as error: + return _error_response(None, _PARSE_ERROR, str(error)) + if not isinstance(request, dict) or not isinstance(request.get("method"), str): + return _error_response(None, _INVALID_REQUEST, "Not a JSON-RPC request") + request_id = request.get("id") + method = self._methods.get(request["method"]) + if method is None: + return _error_response( + request_id, _METHOD_NOT_FOUND, f"No method {request['method']}" + ) + params = request.get("params", {}) + if not isinstance(params, dict): + return _error_response( + request_id, _INVALID_PARAMS, "params must be an object" + ) + try: + result = method(**params) + except TypeError as error: + return _error_response(request_id, _INVALID_PARAMS, str(error)) + except NoDocument as error: + return _error_response(request_id, _NO_DOCUMENT, str(error)) + return json.dumps({"jsonrpc": "2.0", "id": request_id, "result": result}) + + def open(self, text: str) -> State: + try: + document = RegisterMapDocument.from_text(text, _TEXT_NAME) + except FormatError as error: + return _rejected([_syntax_problem(str(error))]) + # Checked here first, with the text, so that each problem has its line. + report = check_register_map(document.data, text) + if report.errors: + return _rejected(report.errors) + return self._start(document) + + def new(self, bus: Dict[str, Any], module: Dict[str, Any]) -> State: + try: + document = RegisterMapDocument.new(bus, module) + except EditRejected as error: + return _rejected(error.problems) + return self._start(document) + + def apply(self, operations: List[Dict[str, Any]]) -> State: + document = self._require_document() + before = RegisterMapDocument.from_text(document.text, _TEXT_NAME) + try: + self._warnings = document.apply(operations) + except EditRejected as error: + return _rejected(error.problems) + if document.text != before.text: + self._undo.append(before) + self._redo.clear() + return self._state() + + def undo(self) -> State: + return self._step(self._undo, self._redo) + + def redo(self) -> State: + return self._step(self._redo, self._undo) + + def _start(self, document: RegisterMapDocument) -> State: + try: + self._warnings = document.check() + except EditRejected as error: + return _rejected(error.problems) + self._document = document + self._undo.clear() + self._redo.clear() + return self._state() + + def _step( + self, source: List[RegisterMapDocument], target: List[RegisterMapDocument] + ) -> State: + if source: + target.append(self._require_document()) + self._document = source.pop() + self._warnings = self._document.check() + return self._state() + + def _require_document(self) -> RegisterMapDocument: + if self._document is None: + raise NoDocument("Call open or new first") + return self._document + + def _state(self) -> State: + document = self._require_document() + return { + "accepted": True, + "data": document.data, + "text": document.text, + "warnings": self._warnings, + "layout": _layout(document), + "nextAddress": document.next_free_address(), + "canUndo": bool(self._undo), + "canRedo": bool(self._redo), + } + + +def _layout(document: RegisterMapDocument) -> Dict[str, Any]: + """Where bust places each register and field, by name, including the + addresses and bits it chose for those that give none.""" + return { + register.name: { + "address": register.address, + "width": register.width, + "fields": { + field.name: [field.pos_low, field.pos_high] for field in register.fields + }, + } + for register in document.module.registers + } + + +def _rejected(problems: List[Problem]) -> State: + return {"accepted": False, "problems": [_problem_json(p) for p in problems]} + + +def _problem_json(problem: Problem) -> Dict[str, Any]: + return { + "path": list(problem.path), + "location": problem.location, + "message": problem.message, + "line": problem.line, + } + + +def _syntax_problem(message: str) -> Problem: + # parse_json_text gives "register map:LINE:COLUMN: message". + prefix = f"{_TEXT_NAME}:" + if message.startswith(prefix): + line, _, rest = message[len(prefix) :].partition(":") + _, _, text = rest.partition(": ") + if line.isdigit() and text: + return Problem((), text, int(line)) + return Problem((), message) + + +def _error_response(request_id: Any, code: int, message: str) -> str: + return json.dumps( + { + "jsonrpc": "2.0", + "id": request_id, + "error": {"code": code, "message": message}, + } + ) + + +def serve(stdin: TextIO, stdout: TextIO) -> None: + """Answer one JSON-RPC request per line until stdin closes.""" + bridge = EditorBridge() + for line in stdin: + if line.strip(): + stdout.write(bridge.handle(line) + "\n") + stdout.flush() + + +if __name__ == "__main__": + serve(sys.stdin, sys.stdout) diff --git a/bust/editing/document.py b/bust/editing/document.py index 92d87c0..eb70eae 100644 --- a/bust/editing/document.py +++ b/bust/editing/document.py @@ -25,7 +25,8 @@ 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 +from bust.utils.json_utils import parse_json_text +from bust.validation.schema_check import Problem, check_register_map Operation = Dict[str, Any] @@ -34,8 +35,16 @@ class EditRejected(ValueError): """Raised for a change that would give a register map bust rejects. The message has one line for each problem. + + Attributes: + problems: The problems, each with its place in the register map if + known. """ + def __init__(self, message: str, problems: Optional[List[Problem]] = None): + super().__init__(message) + self.problems = problems if problems is not None else [Problem((), message)] + class FileChanged(RuntimeError): """Raised when the file changed on disk after the document was read.""" @@ -79,6 +88,18 @@ def open(cls, path: str) -> "RegisterMapDocument": text = fp.read() return cls(text, json_parser(path), saved_text=text) + @classmethod + def from_text(cls, text: str, name: str = "register map") -> "RegisterMapDocument": + """Read a register map from text, as if from a file that holds it. + + Call `check` next. + + Raises: + FormatError: If the text is not JSON or JSON5. The message starts + with `name` and the line. + """ + return cls(text, parse_json_text(text, name), saved_text=text) + @classmethod def new(cls, bus: Dict, module: Dict) -> "RegisterMapDocument": """Start a register map with no registers. @@ -320,7 +341,9 @@ def _build_module(data: Any) -> Tuple[Module, List[str]]: # the same and list every problem the schema finds. report = check_register_map(data) if report.errors: - raise EditRejected("\n".join(str(problem) for problem in report.errors)) + raise EditRejected( + "\n".join(str(problem) for problem in report.errors), report.errors + ) with _captured_warnings() as warnings: warnings.extend(str(problem) for problem in report.warnings) try: diff --git a/tests/test_editing_bridge.py b/tests/test_editing_bridge.py new file mode 100644 index 0000000..c22428a --- /dev/null +++ b/tests/test_editing_bridge.py @@ -0,0 +1,146 @@ +"""EditorBridge answers the JSON-RPC messages of the editor UI.""" + +import io +import json +import os + +from bust.editing.bridge import EditorBridge, serve +from bust.schema import register_map_schema + +_EXAMPLE = os.path.join( + os.path.dirname(os.path.dirname(__file__)), "example", "example_axi.json" +) + +_SMALL = """{ + "bus": {"type": "axi", "addr_width": 16, "data_width": 32}, + "module": { + "name": "m", + "register": [{"name": "ctrl", "sw": "rw", "hw": "r"}] + } +} +""" + + +def _call(bridge, method, request_id=1, **params): + message = {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params} + response = json.loads(bridge.handle(json.dumps(message))) + assert response["id"] == request_id + return response + + +def _result(bridge, method, **params): + return _call(bridge, method, **params)["result"] + + +def test_schema_is_bust_schema(): + assert _result(EditorBridge(), "schema") == register_map_schema() + + +def test_open_returns_data_text_and_warnings(): + with open(_EXAMPLE, encoding="utf-8") as fp: + text = fp.read() + state = _result(EditorBridge(), "open", text=text) + assert state["accepted"] is True + assert state["text"] == text + assert state["data"]["module"]["name"] == "example_axi" + assert state["canUndo"] is False + assert state["layout"]["reg1"]["address"] == 4 + assert state["layout"]["reg7"]["fields"]["field1"] == [1, 4] + assert state["nextAddress"] == 56 + + +def test_open_gives_syntax_errors_their_line(): + state = _result(EditorBridge(), "open", text='{\n "bus": ,\n}') + assert state["accepted"] is False + [problem] = state["problems"] + assert problem["line"] == 2 + assert problem["path"] == [] + + +def test_open_gives_schema_errors_their_path_and_line(): + state = _result(EditorBridge(), "open", text=_SMALL.replace('"rw"', '"rx"')) + assert state["accepted"] is False + [problem] = state["problems"] + assert problem["path"] == ["module", "register", 0, "sw"] + assert problem["location"] == "module.register[0].sw" + assert problem["line"] == 5 + + +def test_apply_changes_the_text_and_can_be_undone_and_redone(): + bridge = EditorBridge() + _result(bridge, "open", text=_SMALL) + operation = {"op": "replace", "path": "/module/register/0/sw", "value": "ro"} + + state = _result(bridge, "apply", operations=[operation]) + assert state["data"]["module"]["register"][0]["sw"] == "ro" + assert '"sw": "ro"' in state["text"] + assert (state["canUndo"], state["canRedo"]) == (True, False) + + state = _result(bridge, "undo") + assert state["text"] == _SMALL + assert (state["canUndo"], state["canRedo"]) == (False, True) + + state = _result(bridge, "redo") + assert state["data"]["module"]["register"][0]["sw"] == "ro" + + +def test_a_rejected_change_has_problems_and_changes_nothing(): + bridge = EditorBridge() + _result(bridge, "open", text=_SMALL) + operation = {"op": "replace", "path": "/module/register/0/sw", "value": "rx"} + + state = _result(bridge, "apply", operations=[operation]) + assert state["accepted"] is False + assert state["problems"][0]["path"] == ["module", "register", 0, "sw"] + assert _result(bridge, "undo")["text"] == _SMALL + + +def test_module_errors_are_rejected_without_a_path(): + bridge = EditorBridge() + _result(bridge, "open", text=_SMALL) + operation = { + "op": "add", + "path": "/module/register/-", + "value": {"name": "ctrl", "sw": "rw", "hw": "r"}, + } + state = _result(bridge, "apply", operations=[operation]) + assert state["accepted"] is False + assert state["problems"][0]["path"] == [] + assert "ctrl" in state["problems"][0]["message"] + + +def test_new_starts_an_empty_register_map(): + state = _result( + EditorBridge(), + "new", + bus={"type": "axi", "addr_width": 16, "data_width": 32}, + module={"name": "m"}, + ) + assert state["accepted"] is True + assert state["data"]["module"]["register"] == [] + + +def test_a_change_before_open_is_an_error(): + response = _call(EditorBridge(), "apply", operations=[]) + assert response["error"]["code"] == -32000 + + +def test_unknown_methods_and_bad_messages_are_errors(): + bridge = EditorBridge() + assert _call(bridge, "save")["error"]["code"] == -32601 + assert _call(bridge, "open", wrong=1)["error"]["code"] == -32602 + assert json.loads(bridge.handle("not json"))["error"]["code"] == -32700 + assert json.loads(bridge.handle("[]"))["error"]["code"] == -32600 + + +def test_serve_answers_one_line_per_request(): + requests = [ + {"jsonrpc": "2.0", "id": 1, "method": "open", "params": {"text": _SMALL}}, + {"jsonrpc": "2.0", "id": 2, "method": "undo"}, + ] + stdin = io.StringIO("".join(json.dumps(r) + "\n" for r in requests)) + stdout = io.StringIO() + serve(stdin, stdout) + responses = [json.loads(line) for line in stdout.getvalue().splitlines()] + assert [r["id"] for r in responses] == [1, 2] + assert all(r["result"]["accepted"] for r in responses) From 7eeeba973f4899bb26f2430ee3d96a17ffe64262 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ola=20Gr=C3=B8ttvik?= Date: Fri, 30 Oct 2026 09:27:31 +0000 Subject: [PATCH 2/2] Give access, reset and bit segments per register in the bridge state --- bust/editing/bridge.py | 31 ++++++++++++++++++++++++++----- tests/test_editing_bridge.py | 16 +++++++++++++++- 2 files changed, 41 insertions(+), 6 deletions(-) diff --git a/bust/editing/bridge.py b/bust/editing/bridge.py index 1075759..a041290 100644 --- a/bust/editing/bridge.py +++ b/bust/editing/bridge.py @@ -13,8 +13,8 @@ undo, redo: Step back or forward through the changes. Every method but schema returns a state. An accepted state holds the register -map's data and text, bust's warnings, the address and bits bust gives each -register and field, the address a new register would get, and whether undo and redo can step. A +map's data and text, bust's warnings, each register and field as bust reads +it (address, bits, access, reset, and the bit segments of the documentation), the address a new register would get, and whether undo and redo can step. A rejected state holds bust's problems, and the register map stays as it was. Each problem has the path to the value it is about, as a list of keys and indexes, and the line for problems in the text given to open. @@ -26,6 +26,7 @@ from bust.editing.document import EditRejected, RegisterMapDocument from bust.exceptions import FormatError +from bust.generators.register_layout import access_text, bit_segments, reset_text from bust.schema import register_map_schema from bust.validation.schema_check import Problem, check_register_map @@ -165,14 +166,34 @@ def _state(self) -> State: def _layout(document: RegisterMapDocument) -> Dict[str, Any]: - """Where bust places each register and field, by name, including the - addresses and bits it chose for those that give none.""" + """How bust reads each register and field, by name: the addresses and bits + it chose for those that give none, and the access and reset values with + the defaults filled in, written as the documentation writes them.""" return { register.name: { "address": register.address, "width": register.width, + "type": register.type.value, + "access": access_text(register), + "reset": reset_text(register.reset, register.width), + "segments": [ + { + "name": segment.name, + "high": segment.high, + "low": segment.low, + "reset": segment.reset, + "isUnused": segment.is_unused, + } + for segment in bit_segments(register) + ], "fields": { - field.name: [field.pos_low, field.pos_high] for field in register.fields + field.name: { + "low": field.pos_low, + "high": field.pos_high, + "access": f"{field.sw.value.upper()}/{field.hw.value.upper()}", + "reset": reset_text(field.reset, field.width), + } + for field in register.fields }, } for register in document.module.registers diff --git a/tests/test_editing_bridge.py b/tests/test_editing_bridge.py index c22428a..311cdaf 100644 --- a/tests/test_editing_bridge.py +++ b/tests/test_editing_bridge.py @@ -45,7 +45,21 @@ def test_open_returns_data_text_and_warnings(): assert state["data"]["module"]["name"] == "example_axi" assert state["canUndo"] is False assert state["layout"]["reg1"]["address"] == 4 - assert state["layout"]["reg7"]["fields"]["field1"] == [1, 4] + reg7 = state["layout"]["reg7"] + assert reg7["fields"]["field1"] == { + "low": 1, + "high": 4, + "access": "RW/R", + "reset": "0xB", + } + assert reg7["access"] == "RW/R" + assert reg7["segments"][0] == { + "name": "reserved", + "high": 31, + "low": 21, + "reset": "-", + "isUnused": True, + } assert state["nextAddress"] == 56