python-library-ralf-model 0.1.1__tar.gz → 0.1.3__tar.gz

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-ralf-model
-Version: 0.1.1
+Version: 0.1.3
 Requires-Python: >=3.10
 Requires-Dist: pydantic<3,>=2.0
 Description-Content-Type: text/markdown
@@ -41,6 +41,8 @@ doc = load_ralf_file(
 ## 能力范围
 
 - **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- **register**：``register 名 [ (hdl路径) ] [ @字节偏移 ] { ... }`` 或 ``register 名;`` 前向引用。
+- **field**：``field 名 [(hdl路径)] [ @位偏移 ] { ... }``（括号路径可紧贴字段名，如 ``field f(hdl.f)``）。
 - `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
 - `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
 

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/README.md

@@ -34,6 +34,8 @@ doc = load_ralf_file(
 ## 能力范围
 
 - **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- **register**：``register 名 [ (hdl路径) ] [ @字节偏移 ] { ... }`` 或 ``register 名;`` 前向引用。
+- **field**：``field 名 [(hdl路径)] [ @位偏移 ] { ... }``（括号路径可紧贴字段名，如 ``field f(hdl.f)``）。
 - `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
 - `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
 

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-ralf-model"
-version = "0.1.1"
+version = "0.1.3"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/ralf_model/__init__.py

@@ -4,7 +4,7 @@ from ralf_model.abc import AbstractRalfBlock, AbstractRalfField, AbstractRalfReg
 from ralf_model.emit import dump_ralf
 from ralf_model.errors import RalfError, RalfParseError, RalfSourceError
 from ralf_model.io import dump_ralf_file, dumps_ralf, load_ralf_file, loads_ralf
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 from ralf_model.parse import normalize_ralf_whitespace, parse_ralf
 from ralf_model.source_expand import expand_ralf_sources, resolve_source_path
 
@@ -16,6 +16,7 @@ __all__ = [
     "FieldNode",
     "RalfDocument",
     "RegisterNode",
+    "SystemNode",
     "RalfError",
     "RalfParseError",
     "RalfSourceError",

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/ralf_model/emit.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 
 
 def _fmt_at_int(v: int) -> str:
@@ -12,6 +12,8 @@ def _fmt_at_int(v: int) -> str:
 
 def _emit_field(f: FieldNode, indent: str) -> list[str]:
     head = f"{indent}field {f.name}"
+    if f.paren_path is not None:
+        head += f"({f.paren_path})"
     if f.offset_bits is not None:
         head += f" @{_fmt_at_int(f.offset_bits)}"
     head += " {"
@@ -26,6 +28,8 @@ def _emit_field(f: FieldNode, indent: str) -> list[str]:
 
 def _emit_register(r: RegisterNode, indent: str) -> list[str]:
     head = f"{indent}register {r.name}"
+    if r.paren_path is not None:
+        head += f" ({r.paren_path})"
     if r.offset_bytes is not None:
         head += f" @{_fmt_at_int(r.offset_bytes)}"
     if r.declaration_only:
@@ -54,6 +58,35 @@ def _emit_block_open_line(b: BlockNode, indent: str) -> str:
     return line
 
 
+def _emit_system_open_line(s: SystemNode, indent: str) -> str:
+    line = f"{indent}system {s.name}"
+    if s.rhs_head is not None:
+        line += f" = {s.rhs_head}"
+        if s.rhs_paren_path is not None:
+            line += f" ({s.rhs_paren_path})"
+        if s.base_address is not None:
+            line += f" @{_fmt_at_int(s.base_address)}"
+    elif s.base_address is not None:
+        line += f" @{_fmt_at_int(s.base_address)}"
+    return line
+
+
+def _emit_system(s: SystemNode, indent: str) -> list[str]:
+    head_line = _emit_system_open_line(s, indent)
+    if not s.has_body:
+        return [f"{head_line};"]
+    lines = [head_line + " {"]
+    inner = indent + "  "
+    if s.bytes_width is not None:
+        lines.append(f"{inner}bytes {s.bytes_width};")
+    for sub in s.systems:
+        lines.extend(_emit_system(sub, inner))
+    for sub in s.blocks:
+        lines.extend(_emit_block(sub, inner))
+    lines.append(indent + "}")
+    return lines
+
+
 def _emit_block(b: BlockNode, indent: str) -> list[str]:
     head_line = _emit_block_open_line(b, indent)
     if not b.has_body:
@@ -73,8 +106,15 @@ def _emit_block(b: BlockNode, indent: str) -> list[str]:
 def dump_ralf(doc: RalfDocument) -> str:
     """将 `RalfDocument` 序列化为 RALF 源文本（规范化排版）。"""
     out: list[str] = []
-    for i, b in enumerate(doc.blocks):
-        if i:
+    first = True
+    for s in doc.systems:
+        if not first:
+            out.append("")
+        first = False
+        out.extend(_emit_system(s, ""))
+    for b in doc.blocks:
+        if not first:
             out.append("")
+        first = False
         out.extend(_emit_block(b, ""))
     return "\n".join(out) + ("\n" if out else "")

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/ralf_model/nodes.py

@@ -9,6 +9,10 @@ class FieldNode(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str
+    paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 field 名后的圆括号路径内容（不含括号），如 ``field f(hdl.sig)``",
+    )
     offset_bits: int | None = Field(default=None, description="field 内 `@` 后的位偏移")
     inner_statements: list[str] = Field(
         default_factory=list,
@@ -22,6 +26,10 @@ class RegisterNode(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str
+    paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 register 名后的圆括号路径内容（不含括号），如 ``register r (dut.reg)``",
+    )
     offset_bytes: int | None = Field(default=None, description="register 后的 `@` 字节偏移")
     bytes_width: int | None = None
     fields: list[FieldNode] = Field(default_factory=list)
@@ -61,9 +69,37 @@ class BlockNode(BaseModel):
     blocks: list[BlockNode] = Field(default_factory=list)
 
 
+class SystemNode(BaseModel):
+    """层次化 system；体内可嵌套 system 与 block，不含 register。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    rhs_head: str | None = Field(
+        default=None,
+        description="`=` 右侧起始的层级名（含可能的 `[..]` 后缀）",
+    )
+    rhs_paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 rhs_head 后的圆括号路径内容（不含括号）",
+    )
+    base_address: int | None = Field(
+        default=None,
+        description="`@` 后的地址；可出现于简单 `system 名 @addr` 或 `=` 形式末尾",
+    )
+    has_body: bool = Field(
+        default=True,
+        description="是否带有 `{ ... }`；仅分号结尾的声明为 False",
+    )
+    bytes_width: int | None = None
+    systems: list[SystemNode] = Field(default_factory=list)
+    blocks: list[BlockNode] = Field(default_factory=list)
+
+
 class RalfDocument(BaseModel):
-    """顶层 RALF 文件内容（当前实现要求顶层为若干 `block`）。"""
+    """顶层 RALF 文件内容（顶层为若干 `system`；亦兼容顶层 `block`）。"""
 
     model_config = ConfigDict(extra="forbid")
 
+    systems: list[SystemNode] = Field(default_factory=list)
     blocks: list[BlockNode] = Field(default_factory=list)

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/ralf_model/parse.py

@@ -5,7 +5,7 @@ from collections.abc import Sequence
 from pathlib import Path
 
 from ralf_model.errors import RalfParseError
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 
 
 class _Parser:
@@ -39,11 +39,22 @@ class _Parser:
         j = self._i + offset
         return self._s[j] if j < self._n else None
 
-    def _error(self, msg: str) -> None:
+    def _error_location(self) -> tuple[Path | None, int]:
         path = self._path
+        line = self.line
         if self._line_sources and 0 < self.line <= len(self._line_sources):
             path = self._line_sources[self.line - 1]
-        raise RalfParseError(msg, line=self.line, col=self.col, path=path)
+            local = 1
+            idx = self.line - 2
+            while idx >= 0 and self._line_sources[idx] == path:
+                local += 1
+                idx -= 1
+            line = local
+        return path, line
+
+    def _error(self, msg: str) -> None:
+        path, line = self._error_location()
+        raise RalfParseError(msg, line=line, col=self.col, path=path)
 
     def skip_ws_and_comments(self) -> None:
         while self._i < self._n:
@@ -168,16 +179,19 @@ class _Parser:
         self._error("期望 ;")
 
     def parse_document(self) -> RalfDocument:
+        systems: list[SystemNode] = []
         blocks: list[BlockNode] = []
         self.skip_ws_and_comments()
         while self._i < self._n:
             kw = self._peek_keyword()
-            if kw == "block":
+            if kw == "system":
+                systems.append(self.parse_system())
+            elif kw == "block":
                 blocks.append(self.parse_block())
             else:
-                self._error(f"顶层期望 block，得到 {kw!r}")
+                self._error(f"顶层期望 system 或 block，得到 {kw!r}")
             self.skip_ws_and_comments()
-        return RalfDocument(blocks=blocks)
+        return RalfDocument(systems=systems, blocks=blocks)
 
     def _peek_keyword(self) -> str:
         self.skip_ws_and_comments()
@@ -261,8 +275,8 @@ class _Parser:
             self.skip_ws_and_comments()
         return head, paren_inner, addr
 
-    def parse_block(self) -> BlockNode:
-        self.expect_keyword("block")
+    def parse_system(self) -> SystemNode:
+        self.expect_keyword("system")
         name = self.read_hierarchical_block_name()
         self.skip_ws_and_comments()
 
@@ -270,14 +284,128 @@ class _Parser:
             self._advance()
             addr = self.parse_integer_value()
             self.skip_ws_and_comments()
-            self.expect_char(";")
-            return BlockNode(
+            if self._peek() == ";":
+                self._advance()
+                return SystemNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=False,
+                    systems=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, subs_sys, subs_blk = self._parse_system_body()
+                self.expect_char("}")
+                return SystemNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=True,
+                    bytes_width=bw,
+                    systems=subs_sys,
+                    blocks=subs_blk,
+                )
+            self._error("system @地址 之后应为 ; 或 {")
+
+        if self._peek() == "=":
+            self._advance()
+            self.skip_ws_and_comments()
+            rhs_head, rhs_path, addr_rhs = self.parse_block_rhs_after_equals()
+            self.skip_ws_and_comments()
+            if self._peek() == ";":
+                self._advance()
+                return SystemNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=False,
+                    systems=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, subs_sys, subs_blk = self._parse_system_body()
+                self.expect_char("}")
+                return SystemNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=True,
+                    bytes_width=bw,
+                    systems=subs_sys,
+                    blocks=subs_blk,
+                )
+            self._error("system ... = ... 之后应为 ; 或 {")
+
+        if self._peek() == "{":
+            self._advance()
+            bw, subs_sys, subs_blk = self._parse_system_body()
+            self.expect_char("}")
+            return SystemNode(
                 name=name,
-                base_address=addr,
-                has_body=False,
-                registers=[],
-                blocks=[],
+                has_body=True,
+                bytes_width=bw,
+                systems=subs_sys,
+                blocks=subs_blk,
             )
+        self._error("system 名称之后应为 @、= 或 {")
+
+    def _parse_system_body(
+        self,
+    ) -> tuple[int | None, list[SystemNode], list[BlockNode]]:
+        bw: int | None = None
+        subs_sys: list[SystemNode] = []
+        subs_blk: list[BlockNode] = []
+        while True:
+            self.skip_ws_and_comments()
+            if self._peek() == "}":
+                break
+            kw = self._peek_keyword()
+            if kw == "bytes":
+                self.expect_keyword("bytes")
+                bw = self.parse_integer_value()
+                self.expect_char(";")
+            elif kw == "system":
+                subs_sys.append(self.parse_system())
+            elif kw == "block":
+                subs_blk.append(self.parse_block())
+            else:
+                self._error(f"system 内出现未识别的内容 {kw!r}")
+        return bw, subs_sys, subs_blk
+
+    def parse_block(self) -> BlockNode:
+        self.expect_keyword("block")
+        name = self.read_hierarchical_block_name()
+        self.skip_ws_and_comments()
+
+        if self._peek() == "@":
+            self._advance()
+            addr = self.parse_integer_value()
+            self.skip_ws_and_comments()
+            if self._peek() == ";":
+                self._advance()
+                return BlockNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=False,
+                    registers=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, regs, subs = self._parse_block_body()
+                self.expect_char("}")
+                return BlockNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=True,
+                    bytes_width=bw,
+                    registers=regs,
+                    blocks=subs,
+                )
+            self._error("block @地址 之后应为 ; 或 {")
 
         if self._peek() == "=":
             self._advance()
@@ -349,6 +477,10 @@ class _Parser:
         self.expect_keyword("register")
         name = self.read_ident()
         self.skip_ws_and_comments()
+        paren_path: str | None = None
+        if self._peek() == "(":
+            paren_path = self.read_round_paren_inner()
+            self.skip_ws_and_comments()
         offset: int | None = None
         if self._peek() == "@":
             self._advance()
@@ -358,6 +490,7 @@ class _Parser:
             self._advance()
             return RegisterNode(
                 name=name,
+                paren_path=paren_path,
                 offset_bytes=offset,
                 declaration_only=True,
             )
@@ -367,6 +500,7 @@ class _Parser:
             self.expect_char("}")
             return RegisterNode(
                 name=name,
+                paren_path=paren_path,
                 offset_bytes=offset,
                 bytes_width=rbw,
                 fields=fields,
@@ -396,6 +530,10 @@ class _Parser:
         self.expect_keyword("field")
         name = self.read_ident()
         self.skip_ws_and_comments()
+        paren_path: str | None = None
+        if self._peek() == "(":
+            paren_path = self.read_round_paren_inner()
+            self.skip_ws_and_comments()
         off_bits: int | None = None
         if self._peek() == "@":
             self._advance()
@@ -403,7 +541,9 @@ class _Parser:
         self.expect_char("{")
         fn = self._parse_field_body()
         self.expect_char("}")
-        return fn.model_copy(update={"name": name, "offset_bits": off_bits})
+        return fn.model_copy(
+            update={"name": name, "paren_path": paren_path, "offset_bits": off_bits}
+        )
 
     def _parse_field_body(self) -> FieldNode:
         inner: list[str] = []

{python_library_ralf_model-0.1.1 → python_library_ralf_model-0.1.3}/tests/test_ralf_model.py

@@ -148,6 +148,69 @@ block top {
         out = dump_ralf(doc)
         self.assertIn("register R0;", out)
 
+    def test_register_paren_path_at_offset(self) -> None:
+        src = """
+block top {
+  bytes 4;
+  register CTRL (dut.ctrl_reg) @'h0 {
+    bytes 4;
+    field ena(dut.ctrl_reg.en) @1 {
+      bits 1;
+      access rw;
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        reg = doc.blocks[0].registers[0]
+        self.assertEqual(reg.name, "CTRL")
+        self.assertEqual(reg.paren_path, "dut.ctrl_reg")
+        self.assertEqual(reg.offset_bytes, 0)
+        fld = reg.fields[0]
+        self.assertEqual(fld.name, "ena")
+        self.assertEqual(fld.paren_path, "dut.ctrl_reg.en")
+        self.assertEqual(fld.offset_bits, 1)
+        out = dump_ralf(doc)
+        self.assertIn("register CTRL (dut.ctrl_reg) @'h0", out)
+        self.assertIn("field ena(dut.ctrl_reg.en) @'h1", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+    def test_register_paren_path_forward_decl(self) -> None:
+        src = """
+block top {
+  register R0 (hdl.r0) @'h10;
+}
+"""
+        doc = parse_ralf(src)
+        r = doc.blocks[0].registers[0]
+        self.assertTrue(r.declaration_only)
+        self.assertEqual(r.paren_path, "hdl.r0")
+        self.assertEqual(r.offset_bytes, 0x10)
+        out = dump_ralf(doc)
+        self.assertIn("register R0 (hdl.r0) @'h10;", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+    def test_field_paren_path_no_space(self) -> None:
+        src = """
+block top {
+  register r {
+    bytes 4;
+    field sig(hdl.sig) @0 {
+      bits 4;
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        fld = doc.blocks[0].registers[0].fields[0]
+        self.assertEqual(fld.paren_path, "hdl.sig")
+        out = dump_ralf(doc)
+        self.assertIn("field sig(hdl.sig)", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
     def test_block_ref_rhs_with_parentheses(self) -> None:
         src = """
 block top {
@@ -178,6 +241,41 @@ block a {
         self.assertNotIn("//", n)
 
 
+class SystemParseTests(unittest.TestCase):
+    def test_top_system_nests_system_and_block(self) -> None:
+        src = """
+system chip {
+  system cpu @0 {
+    block core {
+      register r @0 {
+        bytes 4;
+        field f {}
+      }
+    }
+  }
+  block peri @'h1000 {
+    register s @0 {
+      bytes 1;
+      field g {}
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        self.assertEqual(len(doc.systems), 1)
+        chip = doc.systems[0]
+        self.assertEqual(chip.name, "chip")
+        self.assertEqual(len(chip.systems), 1)
+        self.assertEqual(chip.systems[0].name, "cpu")
+        self.assertEqual(chip.systems[0].base_address, 0)
+        self.assertEqual(chip.blocks[0].name, "peri")
+        self.assertEqual(chip.blocks[0].base_address, 0x1000)
+        core = chip.systems[0].blocks[0]
+        self.assertEqual(core.registers[0].name, "r")
+        doc2 = parse_ralf(dump_ralf(doc))
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+
 class ParseErrorTests(unittest.TestCase):
     def test_parse_error_includes_file_path(self) -> None:
         with tempfile.TemporaryDirectory() as td:
@@ -200,6 +298,23 @@ class ParseErrorTests(unittest.TestCase):
                 load_ralf_file(top)
             self.assertIn(str(broken), str(ctx.exception))
             self.assertNotIn(str(top.resolve()), str(ctx.exception))
+            self.assertEqual(ctx.exception.line, 2)
+
+    def test_parse_error_line_in_included_file_after_filler(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            inc = root / "inc"
+            inc.mkdir()
+            (inc / "broken.ralf").write_text(
+                "// line1\n// line2\nblock y {\n  ???\n}\n",
+                encoding="utf-8",
+            )
+            top = root / "top.ralf"
+            filler = "\n".join(["// filler"] * 50)
+            top.write_text(filler + '\nsource "inc/broken.ralf"\n', encoding="utf-8")
+            with self.assertRaises(RalfParseError) as ctx:
+                load_ralf_file(top)
+            self.assertEqual(ctx.exception.line, 4)
 
 
 if __name__ == "__main__":