python-library-ralf-model 0.1.0__py3-none-any.whl

python_library_ralf_model-0.1.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: python-library-ralf-model
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Description-Content-Type: text/markdown
+
+# ralf_model
+
+在 **RALF（Register Abstraction Layer Format）源文本** 与 **`RalfDocument` / 抽象节点类型**（`BlockNode`、`RegisterNode`、`FieldNode`，并实现 `AbstractRalf*`）之间做解析与生成。
+
+## 用法
+
+```python
+from pathlib import Path
+
+from ralf_model import dump_ralf, load_ralf_file, parse_ralf
+
+doc = parse_ralf(Path("chip.ralf").read_text(encoding="utf-8"))
+text = dump_ralf(doc)
+```
+
+亦可使用 `loads_ralf` / `dumps_ralf`、`load_ralf_file` / `dump_ralf_file`（见 `ralf_model.io`）。加载时可传入 **`include_paths`**（类似 ``ralgen -I dir``），配合 **`source`** 行递归展开后再解析；相对路径先相对**当前文件目录**，再依次在各 include 目录检索。
+
+### source 与 include
+
+RALF 常作为 Tcl 脚本。单独成行的 ``source "f.ralf"``、``source {path}``、``source name.ralf``（可有行尾 ``;``、``#`` 注释）会在解析前被展开。不需要展开时：`loads_ralf(..., expand_source=False)` 或 `load_ralf_file(..., expand_source=False)`。
+
+```python
+from pathlib import Path
+from ralf_model import load_ralf_file
+
+doc = load_ralf_file(
+    "top.ralf",
+    include_paths=[Path("ralf_inc"), Path("../shared")],
+)
+```
+
+也可直接使用 ``expand_ralf_sources``、``resolve_source_path``（见 `ralf_model.source_expand`）。
+
+## 能力范围
+
+- **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
+- `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
+
+与 Synopsys `ralgen` 全语法并非字节级兼容；复杂构造若解析失败可再扩展解析器。

python_library_ralf_model-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ralf_model/__init__.py,sha256=k6kVBQxMcUFcdON7X3lVa76vVZrNQ0d0czOIC63sB7k,999
+ralf_model/abc.py,sha256=CjfkbS3dy05uL8vWZzAGQdwMI7CNH3JPeFMdauAa1qI,518
+ralf_model/emit.py,sha256=wEMgPsJxK9H1KbZudCS0obO82w-bwRyUz-dSJukq1UI,2646
+ralf_model/errors.py,sha256=6xoK36ugGOkRLZOvHO9p_kYwHzZoiVNlFSYJL7_NuPk,686
+ralf_model/io.py,sha256=6rIgDZfWcHGTrfLH42cuOhEI0urp5zWeKWf4zbtz73M,1935
+ralf_model/nodes.py,sha256=Wnn3asEeFcUtUFAmnepqC_dJjVcYvFH_0eXv-jg2YUA,2337
+ralf_model/parse.py,sha256=uXGgUZKkFvRMm2Dn1dieRsUKTOHUzEMrVFXJJaqri4w,18823
+ralf_model/source_expand.py,sha256=lBhPLUP3MPTnVzwpW-EU9JMOgSMCStjg99Eg9vUQ_M4,4858
+python_library_ralf_model-0.1.0.dist-info/METADATA,sha256=mrR7oBxPO-cNV8aQN2woQTtGwYHVcM0SPGV7CuXw1d8,2073
+python_library_ralf_model-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_library_ralf_model-0.1.0.dist-info/RECORD,,

python_library_ralf_model-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ralf_model/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ralf_model.abc import AbstractRalfBlock, AbstractRalfField, AbstractRalfRegister
+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.parse import normalize_ralf_whitespace, parse_ralf
+from ralf_model.source_expand import expand_ralf_sources, resolve_source_path
+
+__all__ = [
+    "AbstractRalfBlock",
+    "AbstractRalfField",
+    "AbstractRalfRegister",
+    "BlockNode",
+    "FieldNode",
+    "RalfDocument",
+    "RegisterNode",
+    "RalfError",
+    "RalfParseError",
+    "RalfSourceError",
+    "dump_ralf",
+    "dumps_ralf",
+    "dump_ralf_file",
+    "expand_ralf_sources",
+    "load_ralf_file",
+    "loads_ralf",
+    "parse_ralf",
+    "normalize_ralf_whitespace",
+    "resolve_source_path",
+]

ralf_model/abc.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AbstractRalfField(Protocol):
+    """RALF `field` 对应的对象应至少具备 `name`。"""
+
+    name: str
+
+
+@runtime_checkable
+class AbstractRalfRegister(Protocol):
+    """RALF `register` 对应的对象应至少具备 `name`。"""
+
+    name: str
+
+
+@runtime_checkable
+class AbstractRalfBlock(Protocol):
+    """RALF `block` 对应的对象应至少具备 `name`。"""
+
+    name: str

ralf_model/emit.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+
+
+def _fmt_at_int(v: int) -> str:
+    """`@` 后的偏移（字节或位），采用 Verilog 无尺寸十六进制字面量。"""
+    if v < 0:
+        return str(v)
+    return f"'h{v:x}"
+
+
+def _emit_field(f: FieldNode, indent: str) -> list[str]:
+    head = f"{indent}field {f.name}"
+    if f.offset_bits is not None:
+        head += f" @{_fmt_at_int(f.offset_bits)}"
+    head += " {"
+    lines = [head]
+    inner = indent + "  "
+    for stmt in f.inner_statements:
+        for line in stmt.splitlines():
+            lines.append(f"{inner}{line.strip()}")
+    lines.append(indent + "}")
+    return lines
+
+
+def _emit_register(r: RegisterNode, indent: str) -> list[str]:
+    head = f"{indent}register {r.name}"
+    if r.offset_bytes is not None:
+        head += f" @{_fmt_at_int(r.offset_bytes)}"
+    if r.declaration_only:
+        return [f"{head};"]
+    lines = [head + " {"]
+    inner = indent + "  "
+    if r.bytes_width is not None:
+        lines.append(f"{inner}bytes {r.bytes_width};")
+    for f in r.fields:
+        lines.extend(_emit_field(f, inner))
+    lines.append(indent + "}")
+    return lines
+
+
+def _emit_block_open_line(b: BlockNode, indent: str) -> str:
+    """``block ...`` 行中 `{` 之前的部分（含 `@` / `=` 等）。"""
+    line = f"{indent}block {b.name}"
+    if b.rhs_head is not None:
+        line += f" = {b.rhs_head}"
+        if b.rhs_paren_path is not None:
+            line += f" ({b.rhs_paren_path})"
+        if b.base_address is not None:
+            line += f" @{_fmt_at_int(b.base_address)}"
+    elif b.base_address is not None:
+        line += f" @{_fmt_at_int(b.base_address)}"
+    return line
+
+
+def _emit_block(b: BlockNode, indent: str) -> list[str]:
+    head_line = _emit_block_open_line(b, indent)
+    if not b.has_body:
+        return [f"{head_line};"]
+    lines = [head_line + " {"]
+    inner = indent + "  "
+    if b.bytes_width is not None:
+        lines.append(f"{inner}bytes {b.bytes_width};")
+    for r in b.registers:
+        lines.extend(_emit_register(r, inner))
+    for sub in b.blocks:
+        lines.extend(_emit_block(sub, inner))
+    lines.append(indent + "}")
+    return lines
+
+
+def dump_ralf(doc: RalfDocument) -> str:
+    """将 `RalfDocument` 序列化为 RALF 源文本（规范化排版）。"""
+    out: list[str] = []
+    for i, b in enumerate(doc.blocks):
+        if i:
+            out.append("")
+        out.extend(_emit_block(b, ""))
+    return "\n".join(out) + ("\n" if out else "")

ralf_model/errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class RalfError(Exception):
+    """RALF 解析或生成错误基类。"""
+
+
+class RalfParseError(RalfError):
+    """文本不符合预期语法或词法。"""
+
+    def __init__(self, message: str, *, line: int, col: int) -> None:
+        super().__init__(f"{message} (行 {line}, 列 {col})")
+        self.line = line
+        self.col = col
+
+
+class RalfSourceError(RalfError):
+    """source 展开或路径解析失败（含循环引用、找不到文件）。"""
+
+    def __init__(self, message: str, *, path: Path | None = None) -> None:
+        super().__init__(message)
+        self.path = path

ralf_model/io.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ralf_model.emit import dump_ralf
+from ralf_model.nodes import RalfDocument
+from ralf_model.parse import parse_ralf
+from ralf_model.source_expand import expand_ralf_sources
+
+
+def load_ralf_file(
+    path: str | Path,
+    *,
+    encoding: str = "utf-8",
+    include_paths: Sequence[str | Path] | None = None,
+    expand_source: bool = True,
+) -> RalfDocument:
+    """从文件加载；若 ``expand_source`` 为真，先按 Tcl ``source`` 语义展开（含 ``include_paths`` 检索）。"""
+    p = Path(path).resolve()
+    text = p.read_text(encoding=encoding)
+    inc = tuple(Path(x).resolve() for x in (include_paths or ()))
+    if expand_source:
+        text = expand_ralf_sources(text, current_file=p, include_paths=inc, encoding=encoding)
+    return parse_ralf(text)
+
+
+def loads_ralf(
+    text: str,
+    *,
+    encoding: str = "utf-8",
+    base_dir: str | Path | None = None,
+    include_paths: Sequence[str | Path] | None = None,
+    expand_source: bool = True,
+) -> RalfDocument:
+    """自字符串解析。展开 ``source`` 时相对路径相对 ``base_dir``（默认当前工作目录）。"""
+    bd = Path(base_dir).resolve() if base_dir is not None else Path.cwd()
+    virtual = bd / "__inline__.ralf"
+    inc = tuple(Path(x).resolve() for x in (include_paths or ()))
+    if expand_source:
+        text = expand_ralf_sources(
+            text,
+            current_file=virtual,
+            include_paths=inc,
+            encoding=encoding,
+        )
+    return parse_ralf(text)
+
+
+def dump_ralf_file(doc: RalfDocument, path: str | Path, *, encoding: str = "utf-8") -> None:
+    Path(path).write_text(dump_ralf(doc), encoding=encoding)
+
+
+def dumps_ralf(doc: RalfDocument) -> str:
+    """序列化为字符串，等价于 `dump_ralf`。"""
+    return dump_ralf(doc)

ralf_model/nodes.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FieldNode(BaseModel):
+    """单个 field：`inner_statements` 按源顺序保存每条完整语句（含分号）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    offset_bits: int | None = Field(default=None, description="field 内 `@` 后的位偏移")
+    inner_statements: list[str] = Field(
+        default_factory=list,
+        description='field 花括号内语句，如 bits 1;、reset \'h0;、enum { ... };',
+    )
+
+
+class RegisterNode(BaseModel):
+    """寄存器：可为完整 `{ ... }` 定义，或仅 `register name;` 的前向引用。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    offset_bytes: int | None = Field(default=None, description="register 后的 `@` 字节偏移")
+    bytes_width: int | None = None
+    fields: list[FieldNode] = Field(default_factory=list)
+    declaration_only: bool = False
+
+
+class BlockNode(BaseModel):
+    """层次化 block。
+
+    典型形态：
+    - 定义体：``block 名 { ... }``
+    - 简单映射：``block 名 @地址;``
+    - 实例化：``block 左名 = 右名 [ (路径) ] [ @地址 ] ;`` 或带 ``{ ... }``
+    """
+
+    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="`@` 后的地址；可出现于简单 `block 名 @addr` 或 `=` 形式末尾",
+    )
+    has_body: bool = Field(
+        default=True,
+        description="是否带有 `{ ... }`；仅分号结尾的声明为 False",
+    )
+    bytes_width: int | None = None
+    registers: list[RegisterNode] = Field(default_factory=list)
+    blocks: list[BlockNode] = Field(default_factory=list)
+
+
+class RalfDocument(BaseModel):
+    """顶层 RALF 文件内容（当前实现要求顶层为若干 `block`）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    blocks: list[BlockNode] = Field(default_factory=list)

ralf_model/parse.py

@@ -0,0 +1,554 @@
+from __future__ import annotations
+
+import re
+
+from ralf_model.errors import RalfParseError
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+
+
+class _Parser:
+    def __init__(self, text: str) -> None:
+        self._s = text
+        self._n = len(text)
+        self._i = 0
+        self.line = 1
+        self.col = 1
+
+    def _advance(self, n: int = 1) -> None:
+        for _ in range(n):
+            if self._i >= self._n:
+                return
+            if self._s[self._i] == "\n":
+                self.line += 1
+                self.col = 1
+            else:
+                self.col += 1
+            self._i += 1
+
+    def _peek(self, offset: int = 0) -> str | None:
+        j = self._i + offset
+        return self._s[j] if j < self._n else None
+
+    def _error(self, msg: str) -> None:
+        raise RalfParseError(msg, line=self.line, col=self.col)
+
+    def skip_ws_and_comments(self) -> None:
+        while self._i < self._n:
+            c = self._s[self._i]
+            if c in " \t\r\n":
+                self._advance()
+            elif c == "/" and self._peek(1) == "/":
+                while self._i < self._n and self._s[self._i] != "\n":
+                    self._advance()
+            elif c == "/" and self._peek(1) == "*":
+                self._advance(2)
+                while self._i + 1 < self._n and not (
+                    self._s[self._i] == "*" and self._s[self._i + 1] == "/"
+                ):
+                    self._advance()
+                if self._i + 1 < self._n:
+                    self._advance(2)
+                else:
+                    self._error("未闭合的块注释")
+            else:
+                break
+
+    def expect_char(self, ch: str) -> None:
+        self.skip_ws_and_comments()
+        if self._peek() != ch:
+            self._error(f"期望 {ch!r}，实际为 {self._peek()!r}")
+        self._advance()
+
+    def expect_keyword(self, kw: str) -> None:
+        self.skip_ws_and_comments()
+        start = self._i
+        ident = self._read_ident_raw()
+        if ident is None or ident.lower() != kw.lower():
+            self._i = start
+            self._error(f"期望关键字 {kw!r}")
+
+    def _read_ident_raw(self) -> str | None:
+        if self._i >= self._n:
+            return None
+        c = self._s[self._i]
+        if not (c.isalpha() or c == "_"):
+            return None
+        start = self._i
+        self._advance()
+        while self._i < self._n:
+            c2 = self._s[self._i]
+            if c2.isalnum() or c2 == "_":
+                self._advance()
+            else:
+                break
+        return self._s[start : self._i]
+
+    def read_ident(self) -> str:
+        self.skip_ws_and_comments()
+        ident = self._read_ident_raw()
+        if ident is None:
+            self._error("期望标识符")
+        return ident
+
+    def parse_integer_value(self) -> int:
+        self.skip_ws_and_comments()
+        v, end = _parse_int_literal(self._s, self._i)
+        if end == self._i:
+            self._error("期望整数字面量")
+        while self._i < end:
+            self._advance()
+        return v
+
+    def read_braced_block(self) -> str:
+        """从当前位置的 `{` 起读取一对花括号（含外侧花括号）。"""
+        self.skip_ws_and_comments()
+        if self._peek() != "{":
+            self._error("期望 {")
+        start = self._i
+        depth = 0
+        i = self._i
+        while i < self._n:
+            c = self._s[i]
+            if c == "/" and i + 1 < self._n and self._s[i + 1] == "/":
+                while i < self._n and self._s[i] != "\n":
+                    i += 1
+                continue
+            if c == "/" and i + 1 < self._n and self._s[i + 1] == "*":
+                i += 2
+                while i + 1 < self._n and not (
+                    self._s[i] == "*" and self._s[i + 1] == "/"
+                ):
+                    i += 1
+                i = min(i + 2, self._n)
+                continue
+            if c == "{":
+                depth += 1
+                i += 1
+            elif c == "}":
+                depth -= 1
+                i += 1
+                if depth == 0:
+                    span = self._s[start:i]
+                    while self._i < i:
+                        self._advance()
+                    return span
+                continue
+            else:
+                i += 1
+        self._error("未闭合的 {")
+
+    def read_until_semicolon(self) -> str:
+        """从当前位置读到（不含）`;`，并消费分号。不跨入注释外的换行可简化处理。"""
+        self.skip_ws_and_comments()
+        start = self._i
+        while self._i < self._n:
+            c = self._s[self._i]
+            if c == "/" and self._peek(1) == "/":
+                self._error("行内值不应含注释")
+            if c == ";":
+                text = self._s[start : self._i].strip()
+                self._advance()
+                return text
+            if c == "\n":
+                pass  # allow multiline for complex expressions
+            self._advance()
+        self._error("期望 ;")
+
+    def parse_document(self) -> RalfDocument:
+        blocks: list[BlockNode] = []
+        self.skip_ws_and_comments()
+        while self._i < self._n:
+            kw = self._peek_keyword()
+            if kw == "block":
+                blocks.append(self.parse_block())
+            else:
+                self._error(f"顶层期望 block，得到 {kw!r}")
+            self.skip_ws_and_comments()
+        return RalfDocument(blocks=blocks)
+
+    def _peek_keyword(self) -> str:
+        self.skip_ws_and_comments()
+        save = self._i
+        ident = self._read_ident_raw()
+        self._i = save
+        return ident.lower() if ident else ""
+
+    def read_hierarchical_block_name(self) -> str:
+        """实例名：允许段 `ident`、`.` 分层以及后缀 `[ ... ]`（如 `blk_vh[2]`、`dom[*]`）。"""
+        name = self.read_ident()
+        while True:
+            self.skip_ws_and_comments()
+            if self._peek() == "[":
+                name += self.read_balanced_square_brackets()
+                continue
+            if self._peek() == ".":
+                self._advance()
+                name += "." + self.read_ident()
+                continue
+            break
+        return name
+
+    def read_balanced_square_brackets(self) -> str:
+        """从当前 `[` 读到匹配的 `]`（含括号），并前进游标。"""
+        if self._peek() != "[":
+            self._error("期望 [")
+        start = self._i
+        depth = 0
+        i = self._i
+        while i < self._n:
+            c = self._s[i]
+            if c == "[":
+                depth += 1
+                i += 1
+            elif c == "]":
+                depth -= 1
+                i += 1
+                if depth == 0:
+                    span = self._s[start:i]
+                    while self._i < i:
+                        self._advance()
+                    return span
+            else:
+                i += 1
+        self._error("未闭合的 [")
+
+    def read_round_paren_inner(self) -> str:
+        """读取一对圆括号内的文本（含嵌套括号），游标停在闭合 `)` 之后。"""
+        self.skip_ws_and_comments()
+        self.expect_char("(")
+        start = self._i
+        depth = 1
+        while self._i < self._n and depth:
+            c = self._s[self._i]
+            if c == "(":
+                depth += 1
+            elif c == ")":
+                depth -= 1
+                if depth == 0:
+                    inner = self._s[start : self._i].strip()
+                    self._advance()
+                    return inner
+            self._advance()
+        self._error("未闭合的 (")
+
+    def parse_block_rhs_after_equals(
+        self,
+    ) -> tuple[str, str | None, int | None]:
+        """解析 ``=`` 之后：``层级名 [ (路径) ] [ @地址 ]``，止于 ``;`` 或 ``{{`` 之前。"""
+        head = self.read_hierarchical_block_name()
+        self.skip_ws_and_comments()
+        paren_inner: str | None = None
+        if self._peek() == "(":
+            paren_inner = self.read_round_paren_inner()
+            self.skip_ws_and_comments()
+        addr: int | None = None
+        if self._peek() == "@":
+            self._advance()
+            addr = self.parse_integer_value()
+            self.skip_ws_and_comments()
+        return head, paren_inner, addr
+
+    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()
+            self.expect_char(";")
+            return BlockNode(
+                name=name,
+                base_address=addr,
+                has_body=False,
+                registers=[],
+                blocks=[],
+            )
+
+        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 BlockNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=False,
+                    registers=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, regs, subs = self._parse_block_body()
+                self.expect_char("}")
+                return BlockNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=True,
+                    bytes_width=bw,
+                    registers=regs,
+                    blocks=subs,
+                )
+            self._error("block ... = ... 之后应为 ; 或 {")
+
+        if self._peek() == "{":
+            self._advance()
+            bw, regs, subs = self._parse_block_body()
+            self.expect_char("}")
+            return BlockNode(
+                name=name,
+                has_body=True,
+                bytes_width=bw,
+                registers=regs,
+                blocks=subs,
+            )
+        self._error("block 名称之后应为 @、= 或 {")
+
+    def _parse_block_body(self) -> tuple[int | None, list[RegisterNode], list[BlockNode]]:
+        bw: int | None = None
+        regs: list[RegisterNode] = []
+        subs: 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 == "register":
+                regs.append(self.parse_register())
+            elif kw == "block":
+                subs.append(self.parse_block())
+            else:
+                self._error(f"block 内出现未识别的内容 {kw!r}")
+        return bw, regs, subs
+
+    def parse_register(self) -> RegisterNode:
+        self.expect_keyword("register")
+        name = self.read_ident()
+        self.skip_ws_and_comments()
+        offset: int | None = None
+        if self._peek() == "@":
+            self._advance()
+            offset = self.parse_integer_value()
+        self.skip_ws_and_comments()
+        if self._peek() == ";":
+            self._advance()
+            return RegisterNode(
+                name=name,
+                offset_bytes=offset,
+                declaration_only=True,
+            )
+        if self._peek() == "{":
+            self._advance()
+            rbw, fields = self._parse_register_body()
+            self.expect_char("}")
+            return RegisterNode(
+                name=name,
+                offset_bytes=offset,
+                bytes_width=rbw,
+                fields=fields,
+                declaration_only=False,
+            )
+        self._error("register 后应为 ; 或 {")
+
+    def _parse_register_body(self) -> tuple[int | None, list[FieldNode]]:
+        rbw: int | None = None
+        fields: list[FieldNode] = []
+        while True:
+            self.skip_ws_and_comments()
+            if self._peek() == "}":
+                break
+            kw = self._peek_keyword()
+            if kw == "bytes":
+                self.expect_keyword("bytes")
+                rbw = self.parse_integer_value()
+                self.expect_char(";")
+            elif kw == "field":
+                fields.append(self.parse_field())
+            else:
+                self._error(f"register 体内期望 field 或 bytes，得到 {kw!r}")
+        return rbw, fields
+
+    def parse_field(self) -> FieldNode:
+        self.expect_keyword("field")
+        name = self.read_ident()
+        self.skip_ws_and_comments()
+        off_bits: int | None = None
+        if self._peek() == "@":
+            self._advance()
+            off_bits = self.parse_integer_value()
+        self.expect_char("{")
+        fn = self._parse_field_body()
+        self.expect_char("}")
+        return fn.model_copy(update={"name": name, "offset_bits": off_bits})
+
+    def _parse_field_body(self) -> FieldNode:
+        inner: list[str] = []
+
+        while True:
+            self.skip_ws_and_comments()
+            if self._peek() == "}":
+                break
+            kw = self._peek_keyword()
+            if kw == "bits":
+                self.expect_keyword("bits")
+                bits = self.parse_integer_value()
+                self.expect_char(";")
+                inner.append(f"bits {bits};")
+            elif kw == "reset":
+                self.expect_keyword("reset")
+                reset = self.read_until_semicolon()
+                inner.append(f"reset {reset};")
+            elif kw == "access":
+                self.expect_keyword("access")
+                acc = self.read_ident()
+                self.expect_char(";")
+                inner.append(f"access {acc};")
+            elif kw == "volatile":
+                self.expect_keyword("volatile")
+                self.skip_ws_and_comments()
+                if self._peek() == ";":
+                    self._advance()
+                    inner.append("volatile;")
+                else:
+                    vol = self.read_ident()
+                    self.expect_char(";")
+                    inner.append(f"volatile {vol};")
+            else:
+                inner.append(self._parse_field_raw_statement())
+
+        return FieldNode(name="__tmp__", inner_statements=inner)
+
+    def _parse_field_raw_statement(self) -> str:
+        """解析 field 内未知关键字开头的整句，保留原文用于回写。"""
+        self.skip_ws_and_comments()
+        head = self.read_ident()
+        self.skip_ws_and_comments()
+        if self._peek() == "{":
+            brace = self.read_braced_block()
+            self.skip_ws_and_comments()
+            self.expect_char(";")
+            return f"{head} {brace};"
+        rest = self.read_until_semicolon()
+        if rest:
+            return f"{head} {rest};"
+        return f"{head};"
+
+
+def _parse_int_literal(s: str, start: int) -> tuple[int, int]:
+    """自 `start` 起解析 Verilog 风格整数，返回 (值, 结束下标)。"""
+    n = len(s)
+    i = start
+    while i < n and s[i] in " \t\r\n":
+        i += 1
+    if i >= n:
+        return 0, start
+    j = i
+    if s[i] == "'":
+        return _parse_verilog_unsized(s, i)
+    # decimal width? digits then '
+    k = i
+    while k < n and s[k].isdigit():
+        k += 1
+    if k < n and s[k] == "'":
+        return _parse_verilog_sized(s, i)
+    # plain decimal
+    if s[i].isdigit():
+        while j < n and s[j].isdigit():
+            j += 1
+        return int(s[i:j]), j
+    return 0, start
+
+
+def _parse_verilog_unsized(s: str, i: int) -> tuple[int, int]:
+    """如 'hFF"""
+    n = len(s)
+    if i >= n or s[i] != "'":
+        return 0, i
+    i += 1
+    if i >= n:
+        return 0, i
+    base_ch = s[i].lower()
+    i += 1
+    if i < n and s[i] in "sS":
+        i += 1
+    while i < n and s[i] in " \t":
+        i += 1
+    start_digits = i
+    while i < n:
+        c = s[i]
+        if c == "_" or c.isalnum() or c in "?xzXZ":
+            i += 1
+        else:
+            break
+    digits = s[start_digits:i].replace("_", "")
+    if not digits:
+        return 0, start_digits
+    if base_ch == "h":
+        return int(digits, 16), i
+    if base_ch in ("d",):
+        return int(digits, 10), i
+    if base_ch == "b":
+        return int(digits.replace("?", "0").replace("z", "0").replace("x", "0"), 2), i
+    if base_ch == "o":
+        return int(digits, 8), i
+    return int(digits, 16), i
+
+
+def _parse_verilog_sized(s: str, i: int) -> tuple[int, int]:
+    """如 8'hFF"""
+    n = len(s)
+    j = i
+    while j < n and s[j].isdigit():
+        j += 1
+    if j >= n or s[j] != "'":
+        return 0, i
+    return _parse_verilog_unsized(s, j)
+
+
+_VER_WS = re.compile(r"\s+")
+
+
+def parse_ralf(text: str) -> RalfDocument:
+    """将 RALF 源文本解析为 `RalfDocument`。"""
+    p = _Parser(text)
+    doc = p.parse_document()
+    return doc
+
+
+def normalize_ralf_whitespace(text: str) -> str:
+    """去掉注释与多余空白，用于测试比对（不保证与工具链字节级一致）。"""
+    p = _Parser(text)
+    p.skip_ws_and_comments()
+    out: list[str] = []
+    while p._i < p._n:
+        c = p._s[p._i]
+        if c in " \t\r\n":
+            if out and out[-1] != " ":
+                out.append(" ")
+            p._advance()
+        elif c == "/" and p._peek(1) == "/":
+            while p._i < p._n and p._s[p._i] != "\n":
+                p._advance()
+        elif c == "/" and p._peek(1) == "*":
+            p._advance(2)
+            while p._i + 1 < p._n and not (
+                p._s[p._i] == "*" and p._s[p._i + 1] == "/"
+            ):
+                p._advance()
+            p._advance(min(2, p._n - p._i))
+        else:
+            out.append(c)
+            p._advance()
+    s = "".join(out).strip()
+    return _VER_WS.sub(" ", s)

ralf_model/source_expand.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Sequence
+
+from ralf_model.errors import RalfSourceError
+
+# RALF 常作为 Tcl 脚本；顶层 ``source path`` 常见单独成行（可有尾随 ``;``、``#`` 注释）。
+_SOURCE_HEAD = re.compile(r"^source\s+", re.IGNORECASE)
+
+
+def resolve_source_path(
+    spec: str,
+    *,
+    base_dir: Path,
+    include_paths: Sequence[Path],
+) -> Path:
+    """按 Synopsys ``ralgen -I`` 语义解析 ``source`` 路径。
+
+    顺序：``base_dir / spec``（当前文件所在目录），然后各 ``include_paths / spec``。
+    ``spec`` 为绝对路径时直接查找该路径。
+    """
+    raw = spec.strip()
+    if not raw:
+        raise RalfSourceError("source 路径为空")
+
+    p = Path(raw)
+    if p.is_absolute():
+        if p.is_file():
+            return p.resolve()
+        raise RalfSourceError(f"找不到 source 文件: {p}", path=p)
+
+    candidates = [base_dir / raw, *[inc / raw for inc in include_paths]]
+    for c in candidates:
+        if c.is_file():
+            return c.resolve()
+    searched = [str(x) for x in candidates]
+    raise RalfSourceError(
+        f"找不到 source 文件: {raw!r}，已搜索: {searched}",
+        path=base_dir / raw,
+    )
+
+
+def _strip_line_comment(line: str) -> str:
+    if "#" not in line:
+        return line
+    i = line.index("#")
+    # Tcl 里字符串中的 # 不一定是注释；简化处理：引号外的第一个 #
+    in_dq = False
+    j = 0
+    while j < len(line):
+        c = line[j]
+        if c == '"' and (j == 0 or line[j - 1] != "\\"):
+            in_dq = not in_dq
+        elif c == "#" and not in_dq:
+            return line[:j].rstrip()
+        j += 1
+    return line
+
+
+def _parse_source_argument(line: str) -> str | None:
+    """若整行（去掉注释后）为 ``source <path>``，返回路径规格，否则返回 None。"""
+    s = _strip_line_comment(line).strip()
+    if not s:
+        return None
+    s = s.rstrip(";").strip()
+    m = _SOURCE_HEAD.match(s)
+    if not m:
+        return None
+    rest = s[m.end() :].strip()
+    if not rest:
+        return None
+    if rest.startswith('"'):
+        end = rest.find('"', 1)
+        if end == -1:
+            raise RalfSourceError(f"source 双引号路径未闭合: {line!r}")
+        inner = rest[1:end]
+        tail = rest[end + 1 :].strip().rstrip(";").strip()
+        if tail:
+            raise RalfSourceError(f"source 行含多余内容: {line!r}")
+        return inner
+    if rest.startswith("{"):
+        depth = 0
+        i = 0
+        while i < len(rest):
+            if rest[i] == "{":
+                depth += 1
+            elif rest[i] == "}":
+                depth -= 1
+                if depth == 0:
+                    inner = rest[1:i]
+                    tail = rest[i + 1 :].strip().rstrip(";").strip()
+                    if tail:
+                        raise RalfSourceError(f"source 行含多余内容: {line!r}")
+                    return inner.strip()
+            i += 1
+        raise RalfSourceError(f"source 花括号路径未闭合: {line!r}")
+    parts = rest.split()
+    if len(parts) != 1:
+        raise RalfSourceError(f"无法解析的 source 行（期望单个路径）: {line!r}")
+    return parts[0]
+
+
+def expand_ralf_sources(
+    text: str,
+    *,
+    current_file: Path,
+    include_paths: Sequence[Path] = (),
+    encoding: str = "utf-8",
+    _chain: tuple[Path, ...] = (),
+) -> str:
+    """将 Tcl 风格 ``source path`` 递归展开为单段 RALF 文本后再交给 ``parse_ralf``。
+
+    ``current_file`` 用于确定相对路径的基准目录（通常为 ``path.parent``），并参与循环检测。
+    从内存加载字符串时可使用 ``base_dir / \"__inline__.ralf\"`` 这类占位路径。
+    """
+    cf = current_file.resolve()
+    if cf in _chain:
+        raise RalfSourceError(f"source 形成循环: {' -> '.join(str(p) for p in _chain)} -> {cf}", path=cf)
+
+    chain = _chain + (cf,)
+    inc = tuple(Path(p).resolve() for p in include_paths)
+
+    out: list[str] = []
+    for line in text.splitlines(keepends=True):
+        spec = _parse_source_argument(line)
+        if spec is None:
+            out.append(line)
+            continue
+
+        inner_path = resolve_source_path(spec, base_dir=cf.parent, include_paths=inc)
+        inner_text = inner_path.read_text(encoding=encoding)
+        expanded_inner = expand_ralf_sources(
+            inner_text,
+            current_file=inner_path,
+            include_paths=inc,
+            encoding=encoding,
+            _chain=chain,
+        )
+        out.append(expanded_inner)
+        if expanded_inner and not expanded_inner.endswith("\n"):
+            out.append("\n")
+
+    return "".join(out)