feat: implement OR1 assembler (parse → lower → resolve → place → allocate → codegen)

+44 -12

CLAUDE.md

··· 51 51 ## Project Structure 52 52 53 53 - `cm_inst.py` — Instruction set definitions (ALUOp hierarchy, ALUInst, SMInst, Addr) 54 - - `tokens.py` — Token type hierarchy (Token -> CMToken -> DyadToken/MonadToken; SMToken, CfgToken, IOToken) 54 + - `tokens.py` — Token type hierarchy (Token -> CMToken -> DyadToken/MonadToken; SMToken, CfgToken -> LoadInstToken/RouteSetToken, IOToken) 55 55 - `sm_mod.py` — Structure Memory cell model (Presence enum, SMCell dataclass, StructureMem resource) 56 + - `dfasm.lark` — Lark grammar for dfasm graph assembly language 56 57 - `emu/` — Behavioural emulator package (SimPy-based discrete event simulation) 57 58 - `emu/types.py` — Config and internal types (PEConfig, SMConfig, MatchEntry, DeferredRead) 58 59 - `emu/alu.py` — Pure-function ALU: `execute(op, left, right, const) -> (result, bool_out)` ··· 60 61 - `emu/sm.py` — StructureMemory: I-structure semantics with deferred reads 61 62 - `emu/network.py` — `build_topology()` wiring and `System` container 62 63 - `emu/__init__.py` — Public API: exports `System`, `build_topology`, `PEConfig`, `SMConfig` 64 + - `asm/` — Assembler package: dfasm source to emulator-ready config (see `asm/CLAUDE.md`) 65 + - `asm/__init__.py` — Public API: `assemble()`, `assemble_to_tokens()`, `round_trip()`, `serialize_graph()` 66 + - `asm/ir.py` — IR types (IRNode, IREdge, IRGraph, IRDataDef, IRRegion, SystemConfig) 67 + - `asm/errors.py` — Structured error types with source context 68 + - `asm/opcodes.py` — Opcode mnemonic mapping and arity classification 69 + - `asm/lower.py` — CST to IRGraph lowering pass 70 + - `asm/resolve.py` — Name resolution pass 71 + - `asm/place.py` — Placement validation and auto-placement 72 + - `asm/allocate.py` — IRAM offset and context slot allocation 73 + - `asm/codegen.py` — Code generation (direct mode + token stream mode) 74 + - `asm/serialize.py` — IRGraph to dfasm source serializer 63 75 - `tests/` — pytest + hypothesis test suite 64 76 - `tests/conftest.py` — Hypothesis strategies for token/op generation 65 77 - `docs/` — Design documents, implementation plans, test plans ··· 68 80 69 81 - Python 3.12 70 82 - SimPy 4.1 (discrete event simulation) 83 + - Lark (Earley parser for dfasm grammar) 71 84 - pytest + hypothesis (property-based testing) 72 85 - Nix flake for dev environment 73 86 ··· 86 99 - `CMToken(Token)` -- adds `offset`, `ctx`, `data` (frozen dataclass) 87 100 - `DyadToken(CMToken)` -- adds `port: Port`, `gen: int`, `wide: bool` 88 101 - `MonadToken(CMToken)` -- adds `inline: bool` 89 - - `SMToken(Token)` -- `op: MemOp`, `flags`, `data`, `ret: Optional[CMToken]` 102 + - `SMToken(Token)` -- `addr: int`, `op: MemOp`, `flags`, `data`, `ret: Optional[CMToken]` 90 103 - `SysToken(Token)` -- `addr: Optional[int]` 91 - - `CfgToken(SysToken)` -- `op: CfgOp`, `data: list` (LOAD_INST carries ALUInst/SMInst list) 104 + - `CfgToken(SysToken)` -- `op: CfgOp` (base class, no payload) 105 + - `LoadInstToken(CfgToken)` -- `instructions: tuple[ALUInst | SMInst, ...]` 106 + - `RouteSetToken(CfgToken)` -- `pe_routes: tuple[int, ...]`, `sm_routes: tuple[int, ...]` 92 107 - `IOToken(SysToken)` -- `data: Optional[List[int]]` 93 108 94 109 ### Instruction Set (cm_inst.py) ··· 124 139 - `DUAL` -- both dest_l and dest_r (non-switch) 125 140 - `SWITCH` -- SW* routing ops: `bool_out=True` sends data to dest_l, trigger to dest_r; vice versa 126 141 142 + **Output logging:** 143 + - `PE.output_log: list` records every token emitted (for testing and tracing) 144 + 127 145 **CfgToken handling:** 128 - - `CfgOp.LOAD_INST`: writes instruction list into IRAM at `token.addr` base offset 129 - - `CfgOp.ROUTE_SET`: not yet implemented 146 + - `LoadInstToken`: writes `token.instructions` into IRAM at `token.addr` base offset 147 + - `RouteSetToken`: restricts `route_table` to `token.pe_routes` and `sm_routes` to `token.sm_routes` 130 148 131 149 ### Structure Memory (emu/sm.py) 132 150 ··· 153 171 - Every PE gets a `route_table` mapping `pe_id -> simpy.Store` for all PEs 154 172 - Every PE gets `sm_routes` mapping `sm_id -> simpy.Store` for all SMs 155 173 - Every SM gets a `route_table` mapping `pe_id -> simpy.Store` for all PEs 156 - - This creates full-mesh connectivity (any PE can send to any PE or SM) 174 + - Default is full-mesh connectivity (any PE can send to any PE or SM) 175 + - If `PEConfig.allowed_pe_routes` or `allowed_sm_routes` is set, `build_topology` restricts routes at construction time 157 176 158 177 **System API:** 159 - - `System.inject(token: CMToken)` -- seed a CM token into target PE (bypasses FIFO, appends directly) 160 - - `System.inject_sm(sm_id, token: SMToken)` -- seed an SM token into target SM 178 + - `System.inject(token: Token)` -- route token by type: SMToken → target SM, CMToken/CfgToken → target PE (direct append, bypasses FIFO) 179 + - `System.send(token: Token)` -- same routing as inject() but yields `store.put()` (SimPy generator, respects FIFO backpressure) 180 + - `System.load(tokens: list[Token])` -- spawns SimPy process that calls send() for each token in order 181 + 182 + **PEConfig extensions (emu/types.py):** 183 + - `allowed_pe_routes: Optional[set[int]]` -- if set, restrict PE route_table to these PE IDs 184 + - `allowed_sm_routes: Optional[set[int]]` -- if set, restrict PE sm_routes to these SM IDs 161 185 162 186 ### Module Dependency Graph 163 187 164 - Root-level modules (`cm_inst.py`, `tokens.py`, `sm_mod.py`) define the ISA and token types. The `emu/` package imports from root-level modules but root-level modules never import from `emu/`. This keeps the specification layer independent of the simulation layer. 188 + Root-level modules (`cm_inst.py`, `tokens.py`, `sm_mod.py`) define the ISA and token types. The `emu/` package imports from root-level modules but root-level modules never import from `emu/`. The `asm/` package imports from both root-level modules and `emu/types.py` (for PEConfig/SMConfig), but neither root-level modules nor `emu/` import from `asm/`. 165 189 166 190 ``` 167 191 tokens.py <-- cm_inst.py <-- emu/types.py 168 192 ^ | | 169 193 | v v 170 194 sm_mod.py emu/alu.py emu/pe.py <--> emu/sm.py 171 - \ / 172 - emu/network.py 195 + | \ / 196 + | emu/network.py 197 + | ^ 198 + v | 199 + asm/ir.py <-- asm/opcodes.py asm/codegen.py 200 + | | | 201 + v v v 202 + asm/lower.py asm/resolve.py asm/allocate.py 203 + | 204 + asm/place.py 173 205 ``` 174 206 175 -  207 +

+55

asm/CLAUDE.md

··· 1 + # Assembler (asm/) 2 + 3 + Last verified: 2026-02-23 4 + 5 + ## Purpose 6 + 7 + Translates dfasm graph assembly source into emulator-ready configurations. Bridges the gap between human-authored dataflow programs and the emulator's PEConfig/SMConfig/token structures. 8 + 9 + ## Contracts 10 + 11 + - **Exposes**: `assemble(source) -> AssemblyResult`, `assemble_to_tokens(source) -> list`, `serialize_graph(IRGraph) -> str`, `round_trip(source) -> str` 12 + - **Guarantees**: Pipeline is parse -> lower -> resolve -> place -> allocate -> codegen. Each pass returns a new IRGraph (immutable pass pattern). Errors accumulate in `IRGraph.errors` rather than fail-fast. `AssemblyResult` contains valid PEConfig/SMConfig lists and seed MonadTokens. 13 + - **Expects**: Valid dfasm source conforming to `dfasm.lark`. Raises `ValueError` if any pipeline stage reports errors. 14 + 15 + ## Pipeline Passes 16 + 17 + 1. **Lower** (`lower.py`): Lark CST -> IRGraph. Creates IRNodes, IREdges, IRRegions (function/location scopes), IRDataDefs, SystemConfig from @system pragma. Qualifies names with function scope (e.g., `$main.&add`). 18 + 2. **Resolve** (`resolve.py`): Validates all edge endpoints exist. Detects scope violations (cross-function label refs). Generates Levenshtein "did you mean" suggestions. 19 + 3. **Place** (`place.py`): Validates explicit PE placements. Auto-places unplaced nodes via greedy bin-packing with locality heuristic (prefer PE with most connected neighbours). 20 + 4. **Allocate** (`allocate.py`): Assigns IRAM offsets (dyadic first, then monadic). Assigns context slots (one per function scope per PE). Resolves symbolic destinations to `Addr(a, port, pe)`. 21 + 5. **Codegen** (`codegen.py`): Two modes: direct (PEConfig/SMConfig + seeds) and token stream (SM init -> ROUTE_SET -> LOAD_INST -> seeds). Computes route restrictions per PE. 22 + 23 + ## Dependencies 24 + 25 + - **Uses**: `cm_inst` (ALUOp, ALUInst, SMInst, Addr, MemOp), `tokens` (Port, MonadToken, SMToken, CfgToken, CfgOp, MemOp), `sm_mod` (Presence), `emu/types` (PEConfig, SMConfig), `lark` (parser) 26 + - **Used by**: Test suite, user programs 27 + - **Boundary**: `emu/` and root-level modules must NEVER import from `asm/` 28 + 29 + ## Key Decisions 30 + 31 + - Frozen dataclasses for IR types: follows existing `tokens.py`/`cm_inst.py` patterns 32 + - `TypeAwareOpToMnemonicDict` and `TypeAwareMonadicOpsSet` in opcodes.py: required because IntEnum subclasses share numeric values across types (e.g., `ArithOp.ADD == 0 == MemOp.READ`), so plain dict/set lookups would collide 33 + - Errors use `IRGraph.errors` accumulation: all issues are reported rather than stopping at the first error 34 + 35 + ## Invariants 36 + 37 + - Each pass returns a new IRGraph; IRGraphs are never mutated after construction 38 + - Names inside function regions are always qualified: `$funcname.&label` 39 + - After placement, every IRNode has `pe is not None` 40 + - After allocation, every IRNode has `iram_offset` and `ctx` set, and destinations are `ResolvedDest` with concrete `Addr` 41 + - Token stream order is always: SM init -> ROUTE_SET -> LOAD_INST -> seed tokens 42 + 43 + ## Key Files 44 + 45 + - `__init__.py` -- Public API and pipeline orchestration 46 + - `ir.py` -- All IR type definitions (IRNode, IREdge, IRGraph, IRRegion, IRDataDef, SystemConfig, SourceLoc, NameRef, ResolvedDest) 47 + - `opcodes.py` -- Mnemonic-to-opcode mapping and arity (monadic vs dyadic) classification 48 + - `codegen.py` -- `AssemblyResult` dataclass and both code generation modes 49 + 50 + ## Gotchas 51 + 52 + - `MemOp.WRITE` arity depends on const: monadic when const is set (cell_addr from const), dyadic when const is None (cell_addr from left operand) 53 + - `RoutingOp.FREE` (ALU free) and `MemOp.FREE` (SM free) share the name "free" -- assembler uses `free` for ALU and `free_sm` for SM to disambiguate 54 + 55 +

+148

asm/__init__.py

··· 1 + """OR1 Assembler package. 2 + 3 + Public API for assembling dfasm source to emulator-ready configuration: 4 + - assemble(): Parse → Lower → Resolve → Place → Allocate → Codegen (direct mode) 5 + - assemble_to_tokens(): ... → Codegen (token stream mode) 6 + - serialize_graph(): Serialize an IRGraph to dfasm at any pipeline stage 7 + - round_trip(): Parse → Lower → Serialize (convenience for round-trip testing) 8 + """ 9 + 10 + from lark import Lark 11 + from pathlib import Path 12 + 13 + from asm.lower import lower 14 + from asm.resolve import resolve 15 + from asm.place import place 16 + from asm.allocate import allocate 17 + from asm.codegen import generate_direct, generate_tokens, AssemblyResult 18 + from asm.serialize import serialize as _serialize_graph 19 + from asm.ir import IRGraph 20 + 21 + _GRAMMAR_PATH = Path(__file__).parent.parent / "dfasm.lark" 22 + _parser = None 23 + 24 + 25 + def _get_parser(): 26 + """Lazily initialize and cache the Lark parser.""" 27 + global _parser 28 + if _parser is None: 29 + _parser = Lark( 30 + _GRAMMAR_PATH.read_text(), 31 + parser="earley", 32 + propagate_positions=True, 33 + ) 34 + return _parser 35 + 36 + 37 + def _run_pipeline(source: str) -> IRGraph: 38 + """Run the shared assembly pipeline: parse → lower → resolve → place → allocate. 39 + 40 + This is the common pipeline used by both assemble() and assemble_to_tokens(). 41 + Error checking happens after each stage. 42 + 43 + Args: 44 + source: dfasm source code as a string 45 + 46 + Returns: 47 + The fully processed IRGraph ready for code generation 48 + 49 + Raises: 50 + ValueError: If any pipeline stage reports errors 51 + """ 52 + tree = _get_parser().parse(source) 53 + graph = lower(tree) 54 + graph = resolve(graph) 55 + if graph.errors: 56 + raise ValueError(f"Assembly errors: {graph.errors}") 57 + graph = place(graph) 58 + if graph.errors: 59 + raise ValueError(f"Placement errors: {graph.errors}") 60 + graph = allocate(graph) 61 + if graph.errors: 62 + raise ValueError(f"Allocation errors: {graph.errors}") 63 + return graph 64 + 65 + 66 + def assemble(source: str) -> AssemblyResult: 67 + """Assemble dfasm source to direct-mode emulator config. 68 + 69 + Chains the full pipeline: parse → lower → resolve → place → allocate → codegen. 70 + Returns PEConfig/SMConfig lists and seed tokens for direct system setup. 71 + 72 + Args: 73 + source: dfasm source code as a string 74 + 75 + Returns: 76 + AssemblyResult containing pe_configs, sm_configs, and seed_tokens 77 + 78 + Raises: 79 + ValueError: If any pipeline stage reports errors 80 + """ 81 + graph = _run_pipeline(source) 82 + return generate_direct(graph) 83 + 84 + 85 + def assemble_to_tokens(source: str) -> list: 86 + """Assemble dfasm source to hardware-faithful bootstrap token stream. 87 + 88 + Chains the full pipeline: parse → lower → resolve → place → allocate → codegen (token mode). 89 + Returns an ordered sequence: SM init tokens → ROUTE_SET tokens → LOAD_INST tokens → seed tokens. 90 + This sequence is consumable by emulator System.inject() and System.load(). 91 + 92 + Args: 93 + source: dfasm source code as a string 94 + 95 + Returns: 96 + List of tokens (SMToken, CfgToken, MonadToken) in bootstrap order 97 + 98 + Raises: 99 + ValueError: If any pipeline stage reports errors 100 + """ 101 + graph = _run_pipeline(source) 102 + return generate_tokens(graph) 103 + 104 + 105 + def serialize_graph(graph: IRGraph) -> str: 106 + """Serialize an IRGraph to dfasm source text. 107 + 108 + Works at any pipeline stage (after lowering, resolution, placement, or allocation). 109 + Useful for inspecting IR transformations after each pass: 110 + graph = lower(parse(source)) 111 + print(serialize_graph(graph)) # inspect after lowering 112 + 113 + Args: 114 + graph: The IRGraph to serialize 115 + 116 + Returns: 117 + Valid dfasm source text 118 + """ 119 + return _serialize_graph(graph) 120 + 121 + 122 + def round_trip(source: str) -> str: 123 + """Parse, lower, and serialize back to dfasm (convenience for round-trip testing). 124 + 125 + Quick round-trip for testing: source → parse → lower → serialize → source. 126 + Does not run resolution, placement, or allocation. 127 + 128 + Args: 129 + source: dfasm source code as a string 130 + 131 + Returns: 132 + Valid dfasm source text 133 + 134 + Raises: 135 + ValueError: If parsing fails 136 + """ 137 + tree = _get_parser().parse(source) 138 + graph = lower(tree) 139 + return _serialize_graph(graph) 140 + 141 + 142 + __all__ = [ 143 + "assemble", 144 + "assemble_to_tokens", 145 + "round_trip", 146 + "serialize_graph", 147 + "AssemblyResult", 148 + ]

+449

asm/allocate.py

··· 1 + """Resource allocation pass for the OR1 assembler. 2 + 3 + Allocates IRAM offsets, context slots, and resolves symbolic destinations to 4 + concrete Addr values with PE and port information. 5 + 6 + Reference: Phase 4 design doc, Task 3. 7 + """ 8 + 9 + from __future__ import annotations 10 + 11 + from dataclasses import replace 12 + from collections import defaultdict 13 + 14 + from asm.errors import AssemblyError, ErrorCategory 15 + from asm.ir import IRGraph, IRNode, IREdge, SourceLoc, ResolvedDest, collect_all_nodes_and_edges, update_graph_nodes 16 + from asm.opcodes import is_dyadic 17 + from cm_inst import Addr, MemOp 18 + 19 + 20 + 21 + 22 + def _group_nodes_by_pe(nodes: dict[str, IRNode]) -> dict[int, list[IRNode]]: 23 + """Group nodes by their PE assignment. 24 + 25 + Args: 26 + nodes: Dictionary of all nodes 27 + 28 + Returns: 29 + Dictionary mapping PE ID to list of nodes on that PE 30 + """ 31 + groups: dict[int, list[IRNode]] = defaultdict(list) 32 + for node in nodes.values(): 33 + if node.pe is not None: 34 + groups[node.pe].append(node) 35 + return groups 36 + 37 + 38 + def _extract_function_scope(node_name: str) -> str: 39 + """Extract function scope from qualified node name. 40 + 41 + Examples: 42 + "$main.&add" -> "$main" 43 + "$helper.&inc" -> "$helper" 44 + "&top_level" -> "" (root scope) 45 + 46 + Args: 47 + node_name: Qualified node name 48 + 49 + Returns: 50 + Function scope name, or empty string for root scope 51 + """ 52 + if "." in node_name: 53 + return node_name.split(".")[0] 54 + return "" 55 + 56 + 57 + def _assign_iram_offsets( 58 + nodes_on_pe: list[IRNode], 59 + all_nodes: dict[str, IRNode], 60 + iram_capacity: int, 61 + pe_id: int, 62 + ) -> tuple[dict[str, IRNode], list[AssemblyError]]: 63 + """Assign IRAM offsets to nodes on a PE. 64 + 65 + Dyadic instructions get offsets 0..D-1, monadic get D..M-1. 66 + 67 + Args: 68 + nodes_on_pe: List of nodes on this PE 69 + all_nodes: All nodes (for name lookup) 70 + iram_capacity: Maximum IRAM slots for this PE 71 + pe_id: The PE ID (for error messages) 72 + 73 + Returns: 74 + Tuple of (updated_nodes dict, errors list) 75 + """ 76 + errors = [] 77 + updated_nodes = {} 78 + 79 + # Partition into dyadic and monadic, preserving order within each partition 80 + dyadic_nodes = [] 81 + monadic_nodes = [] 82 + 83 + for node in nodes_on_pe: 84 + if is_dyadic(node.opcode, node.const): 85 + dyadic_nodes.append(node) 86 + else: 87 + monadic_nodes.append(node) 88 + 89 + # Assign offsets 90 + total = len(dyadic_nodes) + len(monadic_nodes) 91 + if total > iram_capacity: 92 + # Generate overflow error 93 + error_msg = f"PE{pe_id} IRAM overflow: {total} instructions but only {iram_capacity} slots.\n" 94 + if dyadic_nodes: 95 + dyadic_names = ", ".join([n.name.split('.')[-1] for n in dyadic_nodes]) 96 + error_msg += f" Dyadic: {dyadic_names} ({len(dyadic_nodes)} instructions)\n" 97 + if monadic_nodes: 98 + monadic_names = ", ".join([n.name.split('.')[-1] for n in monadic_nodes]) 99 + error_msg += f" Monadic: {monadic_names} ({len(monadic_nodes)} instructions)" 100 + 101 + error = AssemblyError( 102 + loc=SourceLoc(0, 0), 103 + category=ErrorCategory.RESOURCE, 104 + message=error_msg, 105 + ) 106 + errors.append(error) 107 + return {}, errors 108 + 109 + # Assign offsets 110 + for offset, node in enumerate(dyadic_nodes): 111 + updated_nodes[node.name] = replace(node, iram_offset=offset) 112 + 113 + for offset, node in enumerate(monadic_nodes): 114 + updated_nodes[node.name] = replace(node, iram_offset=len(dyadic_nodes) + offset) 115 + 116 + return updated_nodes, errors 117 + 118 + 119 + def _assign_context_slots( 120 + nodes_on_pe: list[IRNode], 121 + all_nodes: dict[str, IRNode], 122 + ctx_slots: int, 123 + pe_id: int, 124 + ) -> tuple[dict[str, IRNode], list[AssemblyError]]: 125 + """Assign context slots to nodes on a PE. 126 + 127 + Each function scope gets a distinct slot. Top-level (root scope) gets slot 0. 128 + 129 + Args: 130 + nodes_on_pe: List of nodes on this PE 131 + all_nodes: All nodes (for name lookup) 132 + ctx_slots: Maximum context slots for this PE 133 + pe_id: The PE ID (for error messages) 134 + 135 + Returns: 136 + Tuple of (updated_nodes dict, errors list) 137 + """ 138 + errors = [] 139 + updated_nodes = {} 140 + 141 + # Collect function scopes in order of first appearance 142 + scopes_seen = [] 143 + scope_to_ctx = {} 144 + 145 + for node in nodes_on_pe: 146 + scope = _extract_function_scope(node.name) 147 + if scope not in scope_to_ctx: 148 + scopes_seen.append(scope) 149 + if len(scopes_seen) > ctx_slots: 150 + # Generate overflow error 151 + error_msg = ( 152 + f"PE{pe_id} context slot overflow: {len(scopes_seen)} function bodies " 153 + f"but only {ctx_slots} slots.\n" 154 + f" Functions: {', '.join(scopes_seen)}" 155 + ) 156 + error = AssemblyError( 157 + loc=SourceLoc(0, 0), 158 + category=ErrorCategory.RESOURCE, 159 + message=error_msg, 160 + ) 161 + errors.append(error) 162 + return {}, errors 163 + 164 + scope_to_ctx[scope] = len(scopes_seen) - 1 165 + 166 + # Assign context slots 167 + for node in nodes_on_pe: 168 + scope = _extract_function_scope(node.name) 169 + ctx = scope_to_ctx[scope] 170 + updated_nodes[node.name] = replace(node, ctx=ctx) 171 + 172 + return updated_nodes, errors 173 + 174 + 175 + def _assign_sm_ids( 176 + all_nodes: dict[str, IRNode], 177 + sm_count: int, 178 + ) -> tuple[dict[str, IRNode], list[AssemblyError]]: 179 + """Assign SM IDs to MemOp instruction nodes that lack one. 180 + 181 + For single-SM systems, defaults to sm_id=0. For multi-SM systems where 182 + the SM target is ambiguous, reports an error. 183 + 184 + Args: 185 + all_nodes: Dictionary of all nodes 186 + sm_count: Number of SMs in the system 187 + 188 + Returns: 189 + Tuple of (updated nodes dict, list of errors) 190 + """ 191 + errors: list[AssemblyError] = [] 192 + updated: dict[str, IRNode] = {} 193 + 194 + for name, node in all_nodes.items(): 195 + if isinstance(node.opcode, MemOp) and node.sm_id is None: 196 + if sm_count == 0: 197 + errors.append(AssemblyError( 198 + loc=node.loc, 199 + category=ErrorCategory.RESOURCE, 200 + message=f"Node '{name}' uses memory operation '{node.opcode.name}' but system has no SMs.", 201 + )) 202 + elif sm_count == 1: 203 + updated[name] = replace(node, sm_id=0) 204 + else: 205 + errors.append(AssemblyError( 206 + loc=node.loc, 207 + category=ErrorCategory.RESOURCE, 208 + message=( 209 + f"Node '{name}' uses memory operation '{node.opcode.name}' but no SM target specified " 210 + f"and system has {sm_count} SMs. Cannot infer target." 211 + ), 212 + )) 213 + 214 + return updated, errors 215 + 216 + 217 + def _build_edge_index(edges: list[IREdge]) -> dict[str, list[IREdge]]: 218 + """Build index of edges by source node name. 219 + 220 + Args: 221 + edges: List of all edges 222 + 223 + Returns: 224 + Dictionary mapping source name to list of edges from that source 225 + """ 226 + index: dict[str, list[IREdge]] = defaultdict(list) 227 + for edge in edges: 228 + index[edge.source].append(edge) 229 + return index 230 + 231 + 232 + def _resolve_destinations( 233 + nodes_on_pe: dict[str, IRNode], 234 + all_nodes: dict[str, IRNode], 235 + edges_by_source: dict[str, list[IREdge]], 236 + ) -> tuple[dict[str, IRNode], list[AssemblyError]]: 237 + """Resolve NameRef destinations to Addr values. 238 + 239 + Uses edge-to-destination mapping rules: 240 + - source_port=L -> dest_l 241 + - source_port=R -> dest_r 242 + - source_port=None: single edge -> dest_l, two edges -> first dest_l, second dest_r 243 + 244 + Args: 245 + nodes_on_pe: Nodes on this PE (with iram_offset and ctx set) 246 + all_nodes: All nodes in graph 247 + edges_by_source: Edges indexed by source node name 248 + 249 + Returns: 250 + Tuple of (updated_nodes dict, errors list) 251 + """ 252 + errors = [] 253 + updated_nodes = {} 254 + 255 + for node_name, node in nodes_on_pe.items(): 256 + updated_node = node 257 + source_edges = edges_by_source.get(node_name, []) 258 + 259 + # Validate edge count 260 + if len(source_edges) > 2: 261 + error = AssemblyError( 262 + loc=node.loc, 263 + category=ErrorCategory.PORT, 264 + message=f"Node '{node_name}' has {len(source_edges)} outgoing edges, but maximum is 2.", 265 + ) 266 + errors.append(error) 267 + continue 268 + 269 + # Validate source_port conflicts 270 + source_ports = [e.source_port for e in source_edges] 271 + explicit_ports = [p for p in source_ports if p is not None] 272 + if len(explicit_ports) != len(set(explicit_ports)): 273 + error = AssemblyError( 274 + loc=node.loc, 275 + category=ErrorCategory.PORT, 276 + message=f"Node '{node_name}' has conflicting source_port qualifiers.", 277 + ) 278 + errors.append(error) 279 + continue 280 + 281 + # Validate mixed explicit/implicit 282 + if len(explicit_ports) > 0 and len(explicit_ports) < len(source_edges): 283 + error = AssemblyError( 284 + loc=node.loc, 285 + category=ErrorCategory.PORT, 286 + message=f"Node '{node_name}' has mixed explicit and implicit source ports.", 287 + ) 288 + errors.append(error) 289 + continue 290 + 291 + # Resolve edges to destinations 292 + if len(source_edges) == 0: 293 + # No outgoing edges, keep as-is 294 + pass 295 + elif len(source_edges) == 1: 296 + # Single edge -> dest_l 297 + edge = source_edges[0] 298 + dest_node = all_nodes.get(edge.dest) 299 + if dest_node is None: 300 + error = AssemblyError( 301 + loc=edge.loc, 302 + category=ErrorCategory.NAME, 303 + message=f"Edge destination '{edge.dest}' not found.", 304 + ) 305 + errors.append(error) 306 + continue 307 + 308 + addr = Addr( 309 + a=dest_node.iram_offset, 310 + port=edge.port, 311 + pe=dest_node.pe, 312 + ) 313 + resolved = ResolvedDest(name=edge.dest, addr=addr) 314 + updated_node = replace(updated_node, dest_l=resolved) 315 + 316 + else: # len(source_edges) == 2 317 + # Two edges: map by source_port or order 318 + edges = source_edges 319 + if explicit_ports: 320 + # All explicit: sort by port 321 + edges = sorted(edges, key=lambda e: e.source_port) 322 + 323 + for idx, edge in enumerate(edges): 324 + dest_node = all_nodes.get(edge.dest) 325 + if dest_node is None: 326 + error = AssemblyError( 327 + loc=edge.loc, 328 + category=ErrorCategory.NAME, 329 + message=f"Edge destination '{edge.dest}' not found.", 330 + ) 331 + errors.append(error) 332 + continue 333 + 334 + addr = Addr( 335 + a=dest_node.iram_offset, 336 + port=edge.port, 337 + pe=dest_node.pe, 338 + ) 339 + resolved = ResolvedDest(name=edge.dest, addr=addr) 340 + 341 + if idx == 0: 342 + updated_node = replace(updated_node, dest_l=resolved) 343 + else: 344 + updated_node = replace(updated_node, dest_r=resolved) 345 + 346 + updated_nodes[node_name] = updated_node 347 + 348 + return updated_nodes, errors 349 + 350 + 351 + def allocate(graph: IRGraph) -> IRGraph: 352 + """Allocate resources: IRAM offsets, context slots, resolve destinations. 353 + 354 + Args: 355 + graph: The IRGraph to allocate 356 + 357 + Returns: 358 + New IRGraph with all nodes updated and allocation errors appended 359 + """ 360 + errors = list(graph.errors) 361 + system = graph.system 362 + 363 + if system is None: 364 + # Should not happen if place() was called first, but handle gracefully 365 + system_errors = [ 366 + AssemblyError( 367 + loc=SourceLoc(0, 0), 368 + category=ErrorCategory.RESOURCE, 369 + message="Cannot allocate without SystemConfig. Run place() first.", 370 + ) 371 + ] 372 + return replace(graph, errors=errors + system_errors) 373 + 374 + # Collect all nodes and edges 375 + all_nodes, all_edges = collect_all_nodes_and_edges(graph) 376 + edges_by_source = _build_edge_index(all_edges) 377 + 378 + # Assign SM IDs to MemOp nodes that lack explicit SM targets 379 + sm_updated, sm_errors = _assign_sm_ids(all_nodes, system.sm_count) 380 + errors.extend(sm_errors) 381 + all_nodes.update(sm_updated) 382 + 383 + # Group nodes by PE 384 + nodes_by_pe = _group_nodes_by_pe(all_nodes) 385 + 386 + # First pass: assign IRAM offsets and context slots to all nodes 387 + intermediate_nodes = {} 388 + for pe_id, nodes_on_pe in sorted(nodes_by_pe.items()): 389 + # Assign IRAM offsets 390 + iram_updated, iram_errors = _assign_iram_offsets( 391 + nodes_on_pe, 392 + all_nodes, 393 + system.iram_capacity, 394 + pe_id, 395 + ) 396 + errors.extend(iram_errors) 397 + 398 + if iram_errors: 399 + # Skip further processing on this PE if IRAM error 400 + continue 401 + 402 + # Get nodes with iram_offset set 403 + iram_nodes = iram_updated 404 + 405 + # Assign context slots 406 + ctx_updated, ctx_errors = _assign_context_slots( 407 + list(iram_nodes.values()), 408 + all_nodes, 409 + system.ctx_slots, 410 + pe_id, 411 + ) 412 + errors.extend(ctx_errors) 413 + 414 + if ctx_errors: 415 + # Skip further processing on this PE if context error 416 + continue 417 + 418 + intermediate_nodes.update(ctx_updated) 419 + 420 + # Second pass: resolve destinations using intermediate nodes (which have offsets set) 421 + updated_all_nodes = {} 422 + for pe_id in sorted(nodes_by_pe.keys()): 423 + # Get nodes from this PE that made it through offset/slot assignment 424 + nodes_on_this_pe = { 425 + name: node for name, node in intermediate_nodes.items() 426 + if node.pe == pe_id 427 + } 428 + if not nodes_on_this_pe: 429 + # This PE had errors, skip it 430 + continue 431 + 432 + resolved_updated, resolve_errors = _resolve_destinations( 433 + nodes_on_this_pe, 434 + intermediate_nodes, # Use intermediate nodes for lookups, not original 435 + edges_by_source, 436 + ) 437 + errors.extend(resolve_errors) 438 + 439 + updated_all_nodes.update(resolved_updated) 440 + 441 + # Merge updated_all_nodes with intermediate_nodes (for nodes that didn't get resolved destinations) 442 + # This ensures nodes from PEs with errors still get their offsets/slots 443 + final_nodes = dict(intermediate_nodes) 444 + final_nodes.update(updated_all_nodes) 445 + 446 + # Reconstruct the graph with updated nodes 447 + # Need to preserve the tree structure (regions, etc.) 448 + result_graph = update_graph_nodes(graph, final_nodes) 449 + return replace(result_graph, errors=errors)

+282

asm/codegen.py

··· 1 + """Code generation for OR1 assembly. 2 + 3 + Converts fully allocated IRGraphs to emulator-ready configuration objects and 4 + token streams. Two output modes: 5 + 1. Direct mode: Produces PEConfig/SMConfig lists + seed tokens (for direct setup) 6 + 2. Token stream mode: Produces bootstrap sequence (SM init → ROUTE_SET → LOAD_INST → seeds) 7 + 8 + Reference: Phase 6 design doc, Tasks 1-2. 9 + """ 10 + 11 + from dataclasses import dataclass 12 + from collections import defaultdict 13 + 14 + from asm.ir import ( 15 + IRGraph, IRNode, IREdge, ResolvedDest, collect_all_nodes_and_edges, collect_all_data_defs, 16 + DEFAULT_IRAM_CAPACITY, DEFAULT_CTX_SLOTS 17 + ) 18 + from cm_inst import ALUInst, SMInst, MemOp, RoutingOp 19 + from emu.types import PEConfig, SMConfig 20 + from tokens import MonadToken, SMToken, CfgOp, LoadInstToken, RouteSetToken 21 + from sm_mod import Presence 22 + 23 + 24 + @dataclass(frozen=True) 25 + class AssemblyResult: 26 + """Result of code generation in direct mode. 27 + 28 + Attributes: 29 + pe_configs: List of PEConfig objects, one per PE 30 + sm_configs: List of SMConfig objects, one per SM with data_defs 31 + seed_tokens: List of MonadTokens for const nodes with no incoming edges 32 + """ 33 + pe_configs: list[PEConfig] 34 + sm_configs: list[SMConfig] 35 + seed_tokens: list[MonadToken] 36 + 37 + 38 + 39 + 40 + def _build_iram_for_pe( 41 + nodes_on_pe: list[IRNode], 42 + all_nodes: dict[str, IRNode], 43 + ) -> dict[int, ALUInst | SMInst]: 44 + """Build IRAM instruction dict for a single PE. 45 + 46 + Args: 47 + nodes_on_pe: List of IRNodes on this PE 48 + all_nodes: All nodes in graph (for lookups) 49 + 50 + Returns: 51 + Dict mapping IRAM offset to ALUInst or SMInst 52 + """ 53 + iram = {} 54 + 55 + for node in nodes_on_pe: 56 + if node.iram_offset is None: 57 + # Node not allocated, skip 58 + continue 59 + 60 + if isinstance(node.opcode, MemOp): 61 + # Memory operation -> SMInst 62 + inst = SMInst( 63 + op=node.opcode, 64 + sm_id=node.sm_id, 65 + const=node.const, 66 + ret=node.dest_l.addr if isinstance(node.dest_l, ResolvedDest) else None, 67 + ) 68 + else: 69 + # ALU operation -> ALUInst 70 + # Extract Addr from ResolvedDest or keep None 71 + dest_l_addr = None 72 + dest_r_addr = None 73 + 74 + if node.dest_l is not None and isinstance(node.dest_l, ResolvedDest): 75 + dest_l_addr = node.dest_l.addr 76 + 77 + if node.dest_r is not None and isinstance(node.dest_r, ResolvedDest): 78 + dest_r_addr = node.dest_r.addr 79 + 80 + inst = ALUInst( 81 + op=node.opcode, 82 + dest_l=dest_l_addr, 83 + dest_r=dest_r_addr, 84 + const=node.const, 85 + ) 86 + 87 + iram[node.iram_offset] = inst 88 + 89 + return iram 90 + 91 + 92 + def _compute_route_restrictions( 93 + nodes_by_pe: dict[int, list[IRNode]], 94 + all_edges: list[IREdge], 95 + all_nodes: dict[str, IRNode], 96 + pe_id: int, 97 + ) -> tuple[set[int], set[int]]: 98 + """Compute allowed PE and SM routes for a given PE. 99 + 100 + Analyzes all edges involving nodes on this PE to determine which other 101 + PEs and SMs it can route to. Includes self-routes. 102 + 103 + Args: 104 + nodes_by_pe: Dict mapping PE ID to list of nodes on that PE 105 + all_edges: List of all edges in graph 106 + all_nodes: Dict of all nodes 107 + pe_id: The PE we're computing routes for 108 + 109 + Returns: 110 + Tuple of (allowed_pe_routes set, allowed_sm_routes set) 111 + """ 112 + nodes_on_pe_set = {node.name for node in nodes_by_pe.get(pe_id, [])} 113 + 114 + pe_routes = {pe_id} # Always include self-route 115 + sm_routes = set() 116 + 117 + # Scan all edges for those sourced from this PE 118 + for edge in all_edges: 119 + if edge.source in nodes_on_pe_set: 120 + # This edge originates from our PE 121 + dest_node = all_nodes.get(edge.dest) 122 + if dest_node is not None: 123 + if dest_node.pe is not None: 124 + pe_routes.add(dest_node.pe) 125 + 126 + # Scan all nodes on this PE for SM instructions 127 + for node in nodes_by_pe.get(pe_id, []): 128 + if isinstance(node.opcode, MemOp) and node.sm_id is not None: 129 + sm_routes.add(node.sm_id) 130 + 131 + return pe_routes, sm_routes 132 + 133 + 134 + def generate_direct(graph: IRGraph) -> AssemblyResult: 135 + """Generate PEConfig, SMConfig, and seed tokens from an allocated IRGraph. 136 + 137 + Args: 138 + graph: A fully allocated IRGraph (after allocate pass) 139 + 140 + Returns: 141 + AssemblyResult with pe_configs, sm_configs, and seed_tokens 142 + """ 143 + all_nodes, all_edges = collect_all_nodes_and_edges(graph) 144 + all_data_defs = collect_all_data_defs(graph) 145 + 146 + # Group nodes by PE 147 + nodes_by_pe: dict[int, list[IRNode]] = defaultdict(list) 148 + for node in all_nodes.values(): 149 + if node.pe is not None: 150 + nodes_by_pe[node.pe].append(node) 151 + 152 + # Build PEConfigs 153 + pe_configs = [] 154 + for pe_id in sorted(nodes_by_pe.keys()): 155 + nodes_on_pe = nodes_by_pe[pe_id] 156 + 157 + # Build IRAM for this PE 158 + iram = _build_iram_for_pe(nodes_on_pe, all_nodes) 159 + 160 + # Compute route restrictions 161 + allowed_pe_routes, allowed_sm_routes = _compute_route_restrictions( 162 + nodes_by_pe, all_edges, all_nodes, pe_id 163 + ) 164 + 165 + # Create PEConfig 166 + config = PEConfig( 167 + pe_id=pe_id, 168 + iram=iram, 169 + ctx_slots=graph.system.ctx_slots if graph.system else DEFAULT_CTX_SLOTS, 170 + offsets=graph.system.iram_capacity if graph.system else DEFAULT_IRAM_CAPACITY, 171 + allowed_pe_routes=allowed_pe_routes, 172 + allowed_sm_routes=allowed_sm_routes, 173 + ) 174 + pe_configs.append(config) 175 + 176 + # Build SMConfigs from data_defs 177 + sm_configs_by_id: dict[int, dict[int, tuple[Presence, int]]] = defaultdict(dict) 178 + for data_def in all_data_defs: 179 + if data_def.sm_id is not None and data_def.cell_addr is not None: 180 + sm_configs_by_id[data_def.sm_id][data_def.cell_addr] = ( 181 + Presence.FULL, data_def.value 182 + ) 183 + 184 + sm_configs = [] 185 + for sm_id in sorted(sm_configs_by_id.keys()): 186 + initial_cells = sm_configs_by_id[sm_id] 187 + config = SMConfig( 188 + sm_id=sm_id, 189 + initial_cells=initial_cells if initial_cells else None, 190 + ) 191 + sm_configs.append(config) 192 + 193 + # Detect seed tokens: CONST nodes with no incoming edges 194 + seed_tokens = [] 195 + 196 + # Build index of edges by destination 197 + edges_by_dest = defaultdict(list) 198 + for edge in all_edges: 199 + edges_by_dest[edge.dest].append(edge) 200 + 201 + for node in all_nodes.values(): 202 + # Check if this is a CONST node 203 + if node.opcode == RoutingOp.CONST: 204 + # Check if it has no incoming edges 205 + if node.name not in edges_by_dest: 206 + # This is a seed token 207 + token = MonadToken( 208 + target=node.pe if node.pe is not None else 0, 209 + offset=node.iram_offset if node.iram_offset is not None else 0, 210 + ctx=node.ctx if node.ctx is not None else 0, 211 + data=node.const if node.const is not None else 0, 212 + inline=False, 213 + ) 214 + seed_tokens.append(token) 215 + 216 + return AssemblyResult( 217 + pe_configs=pe_configs, 218 + sm_configs=sm_configs, 219 + seed_tokens=seed_tokens, 220 + ) 221 + 222 + 223 + def generate_tokens(graph: IRGraph) -> list: 224 + """Generate bootstrap token sequence from an allocated IRGraph. 225 + 226 + Produces tokens in order: SM init → ROUTE_SET → LOAD_INST → seeds 227 + 228 + Args: 229 + graph: A fully allocated IRGraph (after allocate pass) 230 + 231 + Returns: 232 + List of tokens (SMToken, CfgToken, MonadToken) in bootstrap order 233 + """ 234 + # Use direct mode to get configs and seeds 235 + result = generate_direct(graph) 236 + 237 + tokens = [] 238 + 239 + # 1. SM init tokens 240 + all_data_defs = collect_all_data_defs(graph) 241 + for data_def in all_data_defs: 242 + if data_def.sm_id is not None and data_def.cell_addr is not None: 243 + token = SMToken( 244 + target=data_def.sm_id, 245 + addr=data_def.cell_addr, 246 + op=MemOp.WRITE, 247 + flags=None, 248 + data=data_def.value, 249 + ret=None, 250 + ) 251 + tokens.append(token) 252 + 253 + # 2. ROUTE_SET tokens 254 + for pe_config in result.pe_configs: 255 + pe_routes = sorted(pe_config.allowed_pe_routes or []) 256 + sm_routes = sorted(pe_config.allowed_sm_routes or []) 257 + token = RouteSetToken( 258 + target=pe_config.pe_id, 259 + addr=None, 260 + op=CfgOp.ROUTE_SET, 261 + pe_routes=tuple(pe_routes), 262 + sm_routes=tuple(sm_routes), 263 + ) 264 + tokens.append(token) 265 + 266 + # 3. LOAD_INST tokens 267 + for pe_config in result.pe_configs: 268 + # Get instructions in offset order 269 + offsets = sorted(pe_config.iram.keys()) 270 + iram_instructions = [pe_config.iram[offset] for offset in offsets] 271 + token = LoadInstToken( 272 + target=pe_config.pe_id, 273 + addr=0, 274 + op=CfgOp.LOAD_INST, 275 + instructions=tuple(iram_instructions), 276 + ) 277 + tokens.append(token) 278 + 279 + # 4. Seed tokens 280 + tokens.extend(result.seed_tokens) 281 + 282 + return tokens

+94

asm/errors.py

··· 1 + """Structured error types for OR1 assembler. 2 + 3 + Provides error categories, the AssemblyError dataclass, and utilities for 4 + formatting errors with source context in Rust style. 5 + """ 6 + 7 + from dataclasses import dataclass, field 8 + from enum import Enum 9 + 10 + from asm.ir import SourceLoc 11 + 12 + 13 + class ErrorCategory(Enum): 14 + """Classification of assembly errors.""" 15 + PARSE = "parse" 16 + NAME = "name" 17 + SCOPE = "scope" 18 + PLACEMENT = "placement" 19 + RESOURCE = "resource" 20 + ARITY = "arity" 21 + PORT = "port" 22 + UNREACHABLE = "unreachable" 23 + VALUE = "value" 24 + 25 + 26 + @dataclass(frozen=True) 27 + class AssemblyError: 28 + """Structured error with source location and context. 29 + 30 + Attributes: 31 + loc: Source location where the error occurred 32 + category: Error classification (see ErrorCategory) 33 + message: Human-readable error message 34 + suggestions: Optional list of suggestions for fixing the error 35 + context_lines: Optional source lines for context 36 + """ 37 + loc: SourceLoc 38 + category: ErrorCategory 39 + message: str 40 + suggestions: list[str] = field(default_factory=list) 41 + context_lines: list[str] = field(default_factory=list) 42 + 43 + 44 + def format_error(error: AssemblyError, source: str) -> str: 45 + """Format an error with source context in Rust style. 46 + 47 + Produces output like: 48 + error[SCOPE]: Duplicate label '&add' in function '$main' 49 + --> line 5, column 3 50 + | 51 + 5 | &add <| sub 52 + | ^^^ 53 + = help: First defined at line 2 54 + 55 + Args: 56 + error: The AssemblyError to format 57 + source: The original source text 58 + 59 + Returns: 60 + Formatted error string with source context 61 + """ 62 + lines = source.split('\n') 63 + 64 + # Build the header 65 + result = f"error[{error.category.name}]: {error.message}\n" 66 + result += f" --> line {error.loc.line}, column {error.loc.column}\n" 67 + 68 + # Extract and display the source line 69 + if 0 < error.loc.line <= len(lines): 70 + source_line = lines[error.loc.line - 1] 71 + 72 + # Compute gutter width based on line number 73 + gutter_width = len(str(error.loc.line)) 74 + 75 + result += " " * (gutter_width + 1) + "|\n" 76 + result += f"{error.loc.line:>{gutter_width}} | {source_line}\n" 77 + 78 + # Add carets pointing to the error column(s) 79 + caret_col = error.loc.column 80 + caret_end_col = error.loc.end_column if error.loc.end_column else caret_col + 1 81 + caret_count = max(1, caret_end_col - caret_col) 82 + carets = "^" * caret_count 83 + 84 + result += " " * (gutter_width + 1) + "| " + " " * (caret_col - 1) + carets + "\n" 85 + 86 + # Add suggestions 87 + for suggestion in error.suggestions: 88 + result += f" = help: {suggestion}\n" 89 + 90 + # Add context lines if provided 91 + for line in error.context_lines: 92 + result += f" |\n | {line}\n" 93 + 94 + return result

+292

asm/ir.py

··· 1 + """Intermediate Representation (IR) types for OR1 assembly. 2 + 3 + Frozen dataclasses define the IR node types that represent a lowered assembly 4 + program as a graph with nodes, edges, regions, and data definitions. This module 5 + follows the patterns established in tokens.py and cm_inst.py. 6 + """ 7 + 8 + from __future__ import annotations 9 + 10 + from dataclasses import dataclass, field, replace 11 + from enum import Enum 12 + from typing import TYPE_CHECKING, Iterator, Optional, Union 13 + 14 + from cm_inst import ALUOp, Addr, MemOp 15 + from tokens import Port 16 + 17 + if TYPE_CHECKING: 18 + from asm.errors import AssemblyError 19 + 20 + # Default configuration values for system parameters 21 + DEFAULT_IRAM_CAPACITY = 64 22 + DEFAULT_CTX_SLOTS = 4 23 + 24 + 25 + @dataclass(frozen=True) 26 + class SourceLoc: 27 + """Source location for error reporting. 28 + 29 + Extracted from Lark's meta object during parsing. 30 + """ 31 + line: int 32 + column: int 33 + end_line: Optional[int] = None 34 + end_column: Optional[int] = None 35 + 36 + 37 + @dataclass(frozen=True) 38 + class NameRef: 39 + """Unresolved symbolic reference to a node or label. 40 + 41 + Attributes: 42 + name: The symbolic name (e.g., "&label" or "@node") 43 + port: Optional port specification (L or R) 44 + """ 45 + name: str 46 + port: Optional[Port] = None 47 + 48 + 49 + @dataclass(frozen=True) 50 + class ResolvedDest: 51 + """Fully resolved destination after name resolution. 52 + 53 + Attributes: 54 + name: The qualified name 55 + addr: The resolved Addr (address, port, PE) 56 + """ 57 + name: str 58 + addr: Addr 59 + 60 + 61 + @dataclass(frozen=True) 62 + class IRNode: 63 + """One instruction in the IR graph. 64 + 65 + Represents a single instruction that may be executed by a PE. Can be a dyadic 66 + ALU operation, a monadic routing operation, or a memory (SM) operation. 67 + 68 + Attributes: 69 + name: Qualified name (e.g., "$main.&add" or "&top_level") 70 + opcode: ALUOp or MemOp enum value 71 + dest_l: Left output destination (before name resolution) 72 + dest_r: Right output destination (before name resolution) 73 + const: Optional constant operand 74 + pe: Optional PE placement qualifier 75 + iram_offset: Optional offset in PE's IRAM (populated during allocation) 76 + ctx: Optional context slot (populated during allocation) 77 + loc: Source location for error reporting 78 + args: Optional named arguments dictionary (e.g., {"dest": 0x45}) 79 + sm_id: Optional SM ID for MemOp instructions (populated during lowering) 80 + """ 81 + name: str 82 + opcode: Union[ALUOp, MemOp] 83 + dest_l: Optional[Union[NameRef, ResolvedDest]] = None 84 + dest_r: Optional[Union[NameRef, ResolvedDest]] = None 85 + const: Optional[int] = None 86 + pe: Optional[int] = None 87 + iram_offset: Optional[int] = None 88 + ctx: Optional[int] = None 89 + loc: SourceLoc = SourceLoc(0, 0) 90 + args: Optional[dict[str, int]] = None 91 + sm_id: Optional[int] = None 92 + 93 + 94 + @dataclass(frozen=True) 95 + class IREdge: 96 + """Connection between two IR nodes. 97 + 98 + Attributes: 99 + source: Name of the source node 100 + dest: Name of the destination node 101 + port: Destination input port (L or R) 102 + source_port: Source output slot (L or R); None means allocator infers it 103 + loc: Source location for error reporting 104 + """ 105 + source: str 106 + dest: str 107 + port: Port 108 + source_port: Optional[Port] = None 109 + loc: SourceLoc = SourceLoc(0, 0) 110 + 111 + 112 + class RegionKind(Enum): 113 + """Kind of IR region (nested scope).""" 114 + FUNCTION = "function" 115 + LOCATION = "location" 116 + 117 + 118 + @dataclass(frozen=True) 119 + class IRDataDef: 120 + """Data definition (initialization in structure memory). 121 + 122 + Attributes: 123 + name: Name of the data (e.g., "@hello") 124 + sm_id: Optional SM ID (populated from placement during lowering) 125 + cell_addr: Optional cell address (populated from port during lowering) 126 + value: 16-bit value to store (big-endian packed for multi-char data) 127 + loc: Source location for error reporting 128 + """ 129 + name: str 130 + sm_id: Optional[int] = None 131 + cell_addr: Optional[int] = None 132 + value: int = 0 133 + loc: SourceLoc = SourceLoc(0, 0) 134 + 135 + 136 + @dataclass(frozen=True) 137 + class SystemConfig: 138 + """System configuration from @system pragma. 139 + 140 + Attributes: 141 + pe_count: Number of processing elements 142 + sm_count: Number of structure memory instances 143 + iram_capacity: IRAM size per PE (default 64) 144 + ctx_slots: Number of context slots per PE (default 4) 145 + loc: Source location for error reporting 146 + """ 147 + pe_count: int 148 + sm_count: int 149 + iram_capacity: int = DEFAULT_IRAM_CAPACITY 150 + ctx_slots: int = DEFAULT_CTX_SLOTS 151 + loc: SourceLoc = SourceLoc(0, 0) 152 + 153 + 154 + @dataclass(frozen=True) 155 + class IRRegion: 156 + """Nested scope (function or location region). 157 + 158 + Attributes: 159 + tag: Name of the region (e.g., "$main" or "@data_section") 160 + kind: Type of region (FUNCTION or LOCATION) 161 + body: IRGraph containing statements within this region 162 + loc: Source location for error reporting 163 + """ 164 + tag: str 165 + kind: RegionKind 166 + body: IRGraph 167 + loc: SourceLoc = SourceLoc(0, 0) 168 + 169 + 170 + @dataclass(frozen=True) 171 + class IRGraph: 172 + """Complete IR representation of an assembly program or region. 173 + 174 + This is the primary data structure produced by the Lower pass. It contains 175 + all nodes, edges, nested regions, and data definitions. 176 + 177 + Note: IRGraph is frozen but holds mutable containers. This follows the 178 + PEConfig pattern: each pass returns a new IRGraph, and containers are 179 + never mutated after construction. 180 + 181 + Attributes: 182 + nodes: Dictionary of IRNodes keyed by qualified name 183 + edges: List of IREdges connecting nodes 184 + regions: List of IRRegions (nested scopes) 185 + data_defs: List of IRDataDefs (memory initialization) 186 + system: Optional SystemConfig from @system pragma 187 + errors: List of AssemblyErrors encountered during lowering 188 + """ 189 + nodes: dict[str, IRNode] = field(default_factory=dict) 190 + edges: list[IREdge] = field(default_factory=list) 191 + regions: list[IRRegion] = field(default_factory=list) 192 + data_defs: list[IRDataDef] = field(default_factory=list) 193 + system: Optional[SystemConfig] = None 194 + errors: list[AssemblyError] = field(default_factory=list) 195 + 196 + 197 + def iter_all_subgraphs(graph: IRGraph) -> Iterator[IRGraph]: 198 + """Iterate over a graph and all nested region body graphs recursively. 199 + 200 + Yields the graph itself first, then all graphs in nested regions in depth-first order. 201 + 202 + Args: 203 + graph: The root IRGraph 204 + 205 + Yields: 206 + IRGraph objects from the hierarchy 207 + """ 208 + yield graph 209 + 210 + def _walk_regions(regions: list[IRRegion]) -> Iterator[IRGraph]: 211 + for region in regions: 212 + yield region.body 213 + yield from _walk_regions(region.body.regions) 214 + 215 + yield from _walk_regions(graph.regions) 216 + 217 + 218 + def collect_all_nodes(graph: IRGraph) -> dict[str, IRNode]: 219 + """Collect all nodes from graph and regions recursively. 220 + 221 + Args: 222 + graph: The IRGraph 223 + 224 + Returns: 225 + Dictionary mapping node names to IRNodes 226 + """ 227 + all_nodes = {} 228 + for subgraph in iter_all_subgraphs(graph): 229 + all_nodes.update(subgraph.nodes) 230 + return all_nodes 231 + 232 + 233 + def collect_all_nodes_and_edges(graph: IRGraph) -> tuple[dict[str, IRNode], list[IREdge]]: 234 + """Collect all nodes and edges from graph and regions recursively. 235 + 236 + Args: 237 + graph: The IRGraph 238 + 239 + Returns: 240 + Tuple of (all_nodes dict, all_edges list) 241 + """ 242 + all_nodes = {} 243 + all_edges = [] 244 + for subgraph in iter_all_subgraphs(graph): 245 + all_nodes.update(subgraph.nodes) 246 + all_edges.extend(subgraph.edges) 247 + return all_nodes, all_edges 248 + 249 + 250 + def collect_all_data_defs(graph: IRGraph) -> list[IRDataDef]: 251 + """Collect all data_defs from graph and regions recursively. 252 + 253 + Args: 254 + graph: The IRGraph 255 + 256 + Returns: 257 + List of all IRDataDef objects 258 + """ 259 + all_defs = [] 260 + for subgraph in iter_all_subgraphs(graph): 261 + all_defs.extend(subgraph.data_defs) 262 + return all_defs 263 + 264 + 265 + def update_graph_nodes( 266 + graph: IRGraph, updated_nodes: dict[str, IRNode] 267 + ) -> IRGraph: 268 + """Recursively update nodes in graph and regions. 269 + 270 + This function traverses the graph structure and replaces nodes with updated 271 + versions from the provided dictionary. It preserves the tree structure of 272 + regions and regions-within-regions. 273 + 274 + Args: 275 + graph: The IRGraph to update 276 + updated_nodes: Dictionary mapping node names to updated IRNode instances 277 + 278 + Returns: 279 + New IRGraph with updated nodes 280 + """ 281 + # Update top-level nodes 282 + new_g_nodes = {} 283 + for name, node in graph.nodes.items(): 284 + new_g_nodes[name] = updated_nodes.get(name, node) 285 + 286 + # Update regions recursively 287 + new_regions = [] 288 + for region in graph.regions: 289 + new_body = update_graph_nodes(region.body, updated_nodes) 290 + new_regions.append(replace(region, body=new_body)) 291 + 292 + return replace(graph, nodes=new_g_nodes, regions=new_regions)

+1010

asm/lower.py

··· 1 + """Lower pass: Convert Lark CST to IR graph. 2 + 3 + This module implements a Lark Transformer that converts a parse tree from the 4 + dfasm grammar into an IRGraph. The transformer handles: 5 + - Instruction definitions and node creation 6 + - Plain, strong, and weak edge routing 7 + - Function and location regions 8 + - Data definitions 9 + - System configuration pragmas 10 + - Name qualification (scoping) 11 + - Error collection for reserved names and duplicates 12 + """ 13 + 14 + from typing import Any, Optional, Union, Tuple, List, Dict 15 + from lark import Transformer, v_args, Tree 16 + from lark.lexer import Token as LarkToken 17 + 18 + from asm.ir import ( 19 + IRGraph, IRNode, IREdge, IRRegion, RegionKind, IRDataDef, SystemConfig, 20 + SourceLoc, NameRef, ResolvedDest 21 + ) 22 + from asm.errors import AssemblyError, ErrorCategory 23 + from asm.opcodes import MNEMONIC_TO_OP 24 + from cm_inst import ALUOp, MemOp 25 + from tokens import Port, CfgOp 26 + 27 + # Reserved names that cannot be used as node definitions 28 + _RESERVED_NAMES = frozenset({"@system", "@io", "@debug"}) 29 + 30 + 31 + def _filter_args(args: tuple) -> list: 32 + """Filter out LarkTokens from argument list.""" 33 + return [arg for arg in args if not isinstance(arg, LarkToken)] 34 + 35 + 36 + def _normalize_port(value: Union[int, Port]) -> Port: 37 + """Normalize a port value to Port enum. 38 + 39 + Handles conversion from raw integers (0 for L, 1 for R) to Port enum. 40 + If already a Port, returns as-is. Defaults to Port.L for invalid values. 41 + 42 + Args: 43 + value: An int (0/1) or Port enum value 44 + 45 + Returns: 46 + Normalized Port enum value 47 + """ 48 + if isinstance(value, Port): 49 + return value 50 + if isinstance(value, int): 51 + return Port.L if value == 0 else (Port.R if value == 1 else Port.L) 52 + return Port.L 53 + 54 + 55 + # Structured statement result types 56 + class StatementResult: 57 + """Base class for statement processing results.""" 58 + pass 59 + 60 + 61 + class NodeResult(StatementResult): 62 + """Result from inst_def: one or more IRNodes.""" 63 + def __init__(self, nodes: Dict[str, IRNode]): 64 + self.nodes = nodes 65 + 66 + 67 + class EdgeResult(StatementResult): 68 + """Result from plain_edge or anonymous edges: IREdges.""" 69 + def __init__(self, edges: List[IREdge]): 70 + self.edges = edges 71 + 72 + 73 + class FunctionResult(StatementResult): 74 + """Result from func_def: an IRRegion.""" 75 + def __init__(self, region: IRRegion): 76 + self.region = region 77 + 78 + 79 + class LocationResult(StatementResult): 80 + """Result from location_dir: an IRRegion.""" 81 + def __init__(self, region: IRRegion): 82 + self.region = region 83 + 84 + 85 + class DataDefResult(StatementResult): 86 + """Result from data_def: IRDataDefs.""" 87 + def __init__(self, data_defs: List[IRDataDef]): 88 + self.data_defs = data_defs 89 + 90 + 91 + class CompositeResult(StatementResult): 92 + """Result combining nodes and edges (for strong/weak edges).""" 93 + def __init__(self, nodes: Dict[str, IRNode], edges: List[IREdge]): 94 + self.nodes = nodes 95 + self.edges = edges 96 + 97 + 98 + class LowerTransformer(Transformer): 99 + """Transformer that converts a CST into an IRGraph. 100 + 101 + The transformer collects statement results and then in the `start` rule 102 + organizes them into the final IRGraph structure. 103 + """ 104 + 105 + def __init__(self): 106 + super().__init__() 107 + self._anon_counter: int = 0 108 + self._errors: list[AssemblyError] = [] 109 + self._defined_names: dict[str, SourceLoc] = {} 110 + self._system: Optional[SystemConfig] = None 111 + 112 + def _qualify_name(self, name: str, func_scope: Optional[str]) -> str: 113 + """Apply function scope qualification to a name.""" 114 + if name.startswith("&") and func_scope: 115 + return f"{func_scope}.{name}" 116 + return name 117 + 118 + def _extract_loc(self, meta: Any) -> SourceLoc: 119 + """Extract SourceLoc from Lark's meta object.""" 120 + return SourceLoc( 121 + line=meta.line, 122 + column=meta.column, 123 + end_line=meta.end_line if hasattr(meta, "end_line") else None, 124 + end_column=meta.end_column if hasattr(meta, "end_column") else None, 125 + ) 126 + 127 + def _gen_anon_name(self, func_scope: Optional[str]) -> str: 128 + """Generate an anonymous node name, qualified by current scope.""" 129 + name = f"&__anon_{self._anon_counter}" 130 + self._anon_counter += 1 131 + return self._qualify_name(name, func_scope) 132 + 133 + def _check_reserved_name(self, name: str, loc: SourceLoc) -> bool: 134 + """Check if name is reserved. Return True if reserved (and add error).""" 135 + if name in _RESERVED_NAMES: 136 + self._errors.append(AssemblyError( 137 + loc=loc, 138 + category=ErrorCategory.NAME, 139 + message=f"Reserved name '{name}' cannot be used as a node definition" 140 + )) 141 + return True 142 + return False 143 + 144 + def _check_duplicate_name(self, name: str, loc: SourceLoc) -> bool: 145 + """Check for duplicate definition. Return True if duplicate (and add error).""" 146 + if name in self._defined_names: 147 + prev_loc = self._defined_names[name] 148 + self._errors.append(AssemblyError( 149 + loc=loc, 150 + category=ErrorCategory.SCOPE, 151 + message=f"Duplicate label '{name}'", 152 + suggestions=[f"First defined at line {prev_loc.line}"] 153 + )) 154 + return True 155 + self._defined_names[name] = loc 156 + return False 157 + 158 + def _process_statements( 159 + self, 160 + statements: list, 161 + func_scope: Optional[str] = None 162 + ) -> Tuple[Dict[str, IRNode], List[IREdge], List[IRRegion], List[IRDataDef]]: 163 + """Process a list of statement results and collect them into containers.""" 164 + nodes = {} 165 + edges = [] 166 + regions = [] 167 + data_defs = [] 168 + 169 + # Reset defined names for this scope 170 + prev_defined_names = self._defined_names 171 + self._defined_names = {} 172 + 173 + for stmt in statements: 174 + if isinstance(stmt, NodeResult): 175 + # Qualify and add nodes 176 + for node_name, node in stmt.nodes.items(): 177 + qualified_name = self._qualify_name(node_name, func_scope) 178 + if not self._check_duplicate_name(qualified_name, node.loc): 179 + # Update node with qualified name 180 + qualified_node = IRNode( 181 + name=qualified_name, 182 + opcode=node.opcode, 183 + dest_l=node.dest_l, 184 + dest_r=node.dest_r, 185 + const=node.const, 186 + pe=node.pe, 187 + iram_offset=node.iram_offset, 188 + ctx=node.ctx, 189 + loc=node.loc, 190 + args=node.args, 191 + sm_id=node.sm_id, 192 + ) 193 + nodes[qualified_name] = qualified_node 194 + 195 + elif isinstance(stmt, EdgeResult): 196 + # Qualify and add edges 197 + for edge in stmt.edges: 198 + qualified_edge = IREdge( 199 + source=self._qualify_name(edge.source, func_scope), 200 + dest=self._qualify_name(edge.dest, func_scope), 201 + port=edge.port, 202 + source_port=edge.source_port, 203 + loc=edge.loc, 204 + ) 205 + edges.append(qualified_edge) 206 + 207 + elif isinstance(stmt, CompositeResult): 208 + # Composite: both nodes and edges (strong/weak edges) 209 + for node_name, node in stmt.nodes.items(): 210 + qualified_name = self._qualify_name(node_name, func_scope) 211 + if not self._check_duplicate_name(qualified_name, node.loc): 212 + qualified_node = IRNode( 213 + name=qualified_name, 214 + opcode=node.opcode, 215 + dest_l=node.dest_l, 216 + dest_r=node.dest_r, 217 + const=node.const, 218 + pe=node.pe, 219 + iram_offset=node.iram_offset, 220 + ctx=node.ctx, 221 + loc=node.loc, 222 + args=node.args, 223 + sm_id=node.sm_id, 224 + ) 225 + nodes[qualified_name] = qualified_node 226 + for edge in stmt.edges: 227 + qualified_edge = IREdge( 228 + source=self._qualify_name(edge.source, func_scope), 229 + dest=self._qualify_name(edge.dest, func_scope), 230 + port=edge.port, 231 + source_port=edge.source_port, 232 + loc=edge.loc, 233 + ) 234 + edges.append(qualified_edge) 235 + 236 + elif isinstance(stmt, FunctionResult): 237 + regions.append(stmt.region) 238 + 239 + elif isinstance(stmt, LocationResult): 240 + regions.append(stmt.region) 241 + 242 + elif isinstance(stmt, DataDefResult): 243 + data_defs.extend(stmt.data_defs) 244 + 245 + # Restore defined names 246 + self._defined_names = prev_defined_names 247 + 248 + return nodes, edges, regions, data_defs 249 + 250 + def start(self, items: list) -> IRGraph: 251 + """Process the entire program and return an IRGraph. 252 + 253 + Post-processing: Groups statements following location_dir into that region's body. 254 + """ 255 + # First pass: collect all items 256 + nodes, edges, regions, data_defs = self._process_statements(items, None) 257 + 258 + # Second pass: post-process location regions to collect subsequent statements 259 + # Find LocationResult objects and collect subsequent statements into their body 260 + location_results = [r for r in regions if r.kind == RegionKind.LOCATION] 261 + 262 + # Track which nodes, data_defs, and edges are moved into location regions 263 + moved_node_names = set() 264 + moved_data_names = set() 265 + moved_edge_sources = set() # Track edges by (source, dest) tuple 266 + 267 + if location_results: 268 + # Build a mapping of location regions to their collected body 269 + for loc_region in location_results: 270 + # Find the position of this region in the items list 271 + # by matching the tag 272 + body_nodes = {} 273 + body_edges = [] 274 + body_data_defs = [] 275 + 276 + # Collect subsequent non-region statements 277 + collecting = False 278 + for item in items: 279 + if isinstance(item, LocationResult) and item.region.tag == loc_region.tag: 280 + collecting = True 281 + continue 282 + 283 + if collecting: 284 + # Stop at next region boundary 285 + if isinstance(item, (FunctionResult, LocationResult)): 286 + break 287 + 288 + # Collect into location body 289 + if isinstance(item, NodeResult): 290 + body_nodes.update(item.nodes) 291 + moved_node_names.update(item.nodes.keys()) 292 + elif isinstance(item, EdgeResult): 293 + body_edges.extend(item.edges) 294 + moved_edge_sources.update((e.source, e.dest) for e in item.edges) 295 + elif isinstance(item, DataDefResult): 296 + body_data_defs.extend(item.data_defs) 297 + moved_data_names.update(d.name for d in item.data_defs) 298 + elif isinstance(item, CompositeResult): 299 + body_nodes.update(item.nodes) 300 + moved_node_names.update(item.nodes.keys()) 301 + body_edges.extend(item.edges) 302 + moved_edge_sources.update((e.source, e.dest) for e in item.edges) 303 + 304 + # Update the location region with collected body 305 + if body_nodes or body_edges or body_data_defs: 306 + new_body = IRGraph( 307 + nodes=body_nodes, 308 + edges=body_edges, 309 + regions=[], 310 + data_defs=body_data_defs, 311 + ) 312 + # Find and replace this region in the regions list 313 + regions = [ 314 + IRRegion( 315 + tag=r.tag, 316 + kind=r.kind, 317 + body=new_body if r.tag == loc_region.tag else r.body, 318 + loc=r.loc, 319 + ) 320 + for r in regions 321 + ] 322 + 323 + # Remove items that were moved into location regions from top-level containers 324 + nodes = {k: v for k, v in nodes.items() if k not in moved_node_names} 325 + data_defs = [d for d in data_defs if d.name not in moved_data_names] 326 + edges = [e for e in edges if (e.source, e.dest) not in moved_edge_sources] 327 + 328 + return IRGraph( 329 + nodes=nodes, 330 + edges=edges, 331 + regions=regions, 332 + data_defs=data_defs, 333 + system=self._system, 334 + errors=self._errors, 335 + ) 336 + 337 + @v_args(inline=True, meta=True) 338 + def inst_def(self, meta, *args) -> StatementResult: 339 + """Process instruction definition.""" 340 + loc = self._extract_loc(meta) 341 + 342 + # Filter out tokens (FLOW_IN, etc.) - keep only transformed results 343 + args_list = _filter_args(args) 344 + 345 + # First arg is qualified_ref_dict, second is opcode, rest are arguments 346 + qualified_ref_dict = args_list[0] 347 + opcode = args_list[1] 348 + remaining_args = args_list[2:] if len(args_list) > 2 else [] 349 + 350 + # Extract name (will be qualified later in _process_statements) 351 + name = qualified_ref_dict["name"] 352 + 353 + # Check reserved names 354 + if self._check_reserved_name(name, loc): 355 + return NodeResult({}) 356 + 357 + # If opcode is None (invalid), skip node creation (error already added) 358 + if opcode is None: 359 + return NodeResult({}) 360 + 361 + # Extract placement (PE qualifier) 362 + pe = None 363 + if "placement" in qualified_ref_dict and qualified_ref_dict["placement"]: 364 + placement_str = qualified_ref_dict["placement"] 365 + # Parse placement like "pe0" → extract 0 366 + if placement_str.startswith("pe"): 367 + try: 368 + pe = int(placement_str[2:]) 369 + except ValueError: 370 + pass 371 + 372 + # Extract const and named args from arguments 373 + const = None 374 + args_dict = {} 375 + positional_count = 0 376 + 377 + for arg in remaining_args: 378 + if isinstance(arg, tuple): # named_arg 379 + arg_name, arg_value = arg 380 + args_dict[arg_name] = arg_value 381 + else: 382 + # positional argument 383 + if positional_count == 0 and not isinstance(arg, dict): 384 + const = arg 385 + positional_count += 1 386 + 387 + # Create IRNode 388 + node = IRNode( 389 + name=name, 390 + opcode=opcode, 391 + dest_l=None, 392 + dest_r=None, 393 + const=const, 394 + pe=pe, 395 + loc=loc, 396 + args=args_dict if args_dict else None, 397 + ) 398 + 399 + return NodeResult({name: node}) 400 + 401 + @v_args(inline=True, meta=True) 402 + def plain_edge(self, meta, *args) -> StatementResult: 403 + """Process plain edge (wiring between named nodes). 404 + 405 + The source's port (if specified) becomes source_port (output slot). 406 + The dest's port (if specified) becomes port (input port), defaulting to L. 407 + """ 408 + loc = self._extract_loc(meta) 409 + 410 + args_list = _filter_args(args) 411 + source_dict = args_list[0] 412 + dest_list = args_list[1] 413 + 414 + source_name = source_dict["name"] 415 + # Source port is from the source's port specification 416 + source_port = source_dict.get("port") if "port" in source_dict else None 417 + # Normalize source_port to Port if it's a raw int (convert 0→L, 1→R) 418 + if source_port is not None: 419 + source_port = _normalize_port(source_port) 420 + 421 + edges = [] 422 + for dest_dict in dest_list: 423 + dest_name = dest_dict["name"] 424 + # Dest port is from the dest's port specification, defaults to L 425 + dest_port = dest_dict.get("port") 426 + if dest_port is None: 427 + dest_port = Port.L 428 + else: 429 + # Normalize raw int to Port (0→L, 1→R) 430 + dest_port = _normalize_port(dest_port) 431 + 432 + edge = IREdge( 433 + source=source_name, 434 + dest=dest_name, 435 + port=dest_port, 436 + source_port=source_port, 437 + loc=loc, 438 + ) 439 + edges.append(edge) 440 + 441 + return EdgeResult(edges) 442 + 443 + def _wire_anonymous_node( 444 + self, opcode: Union[ALUOp, MemOp], inputs: list, outputs: list, loc: SourceLoc 445 + ) -> StatementResult: 446 + """Wire inputs and outputs for an anonymous edge node. 447 + 448 + Generates the IRNode for an anonymous edge and all associated edges 449 + (both input and output wiring). This logic is shared between strong_edge 450 + and weak_edge, which differ only in how they parse their arguments. 451 + 452 + Args: 453 + opcode: The instruction opcode 454 + inputs: List of input reference dicts with "name" and optional "port" 455 + outputs: List of output reference dicts with "name" and optional "port" 456 + loc: Source location for error reporting 457 + 458 + Returns: 459 + CompositeResult with anonymous node and all input/output edges 460 + """ 461 + # Generate anonymous node (not qualified yet) 462 + anon_name = f"&__anon_{self._anon_counter}" 463 + self._anon_counter += 1 464 + 465 + # Create anonymous IRNode 466 + anon_node = IRNode( 467 + name=anon_name, 468 + opcode=opcode, 469 + const=None, 470 + loc=loc, 471 + ) 472 + 473 + # Wire inputs: first input → Port.L, second → Port.R 474 + edges = [] 475 + for idx, input_arg in enumerate(inputs): 476 + if isinstance(input_arg, dict) and "name" in input_arg: 477 + # It's a qualified_ref 478 + input_name = input_arg["name"] 479 + input_port = Port.L if idx == 0 else Port.R 480 + edge = IREdge( 481 + source=input_name, 482 + dest=anon_name, 483 + port=input_port, 484 + source_port=None, 485 + loc=loc, 486 + ) 487 + edges.append(edge) 488 + 489 + # Wire outputs 490 + for output_dict in outputs: 491 + output_name = output_dict["name"] 492 + output_port = output_dict.get("port") 493 + if output_port is None: 494 + output_port = Port.L 495 + else: 496 + # Normalize raw int to Port (0→L, 1→R) 497 + output_port = _normalize_port(output_port) 498 + 499 + edge = IREdge( 500 + source=anon_name, 501 + dest=output_name, 502 + port=output_port, 503 + source_port=None, 504 + loc=loc, 505 + ) 506 + edges.append(edge) 507 + 508 + # Return both the node and edges 509 + return CompositeResult({anon_name: anon_node}, edges) 510 + 511 + @v_args(inline=True, meta=True) 512 + def strong_edge(self, meta, *args) -> StatementResult: 513 + """Process strong inline edge (anonymous node with inputs and outputs). 514 + 515 + Syntax: inputs... opcode outputs... 516 + """ 517 + loc = self._extract_loc(meta) 518 + 519 + args_list = _filter_args(args) 520 + opcode = args_list[0] 521 + remaining_args = args_list[1:] 522 + 523 + # If opcode is None (invalid), skip edge creation (error already added) 524 + if opcode is None: 525 + return CompositeResult({}, []) 526 + 527 + # Split arguments into inputs and outputs 528 + inputs = [] 529 + outputs = [] 530 + processing_outputs = False 531 + 532 + for arg in remaining_args: 533 + if isinstance(arg, list): # This is ref_list 534 + processing_outputs = True 535 + outputs = arg 536 + elif not processing_outputs: 537 + inputs.append(arg) 538 + 539 + # Wire the anonymous node and its edges 540 + return self._wire_anonymous_node(opcode, inputs, outputs, loc) 541 + 542 + @v_args(inline=True, meta=True) 543 + def weak_edge(self, meta, *args) -> StatementResult: 544 + """Process weak inline edge (outputs then opcode then inputs). 545 + 546 + Syntax: outputs... opcode inputs... 547 + Semantically identical to strong_edge but syntactically reversed. 548 + """ 549 + loc = self._extract_loc(meta) 550 + 551 + args_list = _filter_args(args) 552 + output_list = args_list[0] 553 + opcode = args_list[1] 554 + remaining_args = args_list[2:] if len(args_list) > 2 else [] 555 + 556 + # If opcode is None (invalid), skip edge creation (error already added) 557 + if opcode is None: 558 + return CompositeResult({}, []) 559 + 560 + inputs = list(remaining_args) 561 + outputs = output_list 562 + 563 + # Wire the anonymous node and its edges 564 + return self._wire_anonymous_node(opcode, inputs, outputs, loc) 565 + 566 + def func_def(self, args: list) -> StatementResult: 567 + """Process function definition (region with nested scope).""" 568 + # Without v_args decorator, args come as a list with LarkToken terminals mixed in 569 + # Filter out tokens and extract the actual data 570 + args_list = _filter_args(args) 571 + 572 + # args[0] is func_ref dict, rest are statement results 573 + func_ref_dict = args_list[0] if args_list else {} 574 + func_name = func_ref_dict.get("name", "$unknown") if isinstance(func_ref_dict, dict) else "$unknown" 575 + statement_results = args_list[1:] if len(args_list) > 1 else [] 576 + 577 + # Try to extract location from the raw args (may have meta on Tree nodes) 578 + loc = SourceLoc(0, 0) 579 + for arg in args: 580 + if hasattr(arg, 'meta'): 581 + try: 582 + loc = self._extract_loc(arg.meta) 583 + break 584 + except (AttributeError, TypeError): 585 + pass 586 + 587 + # Process the statements with the function scope 588 + func_nodes, func_edges, func_regions, func_data_defs = self._process_statements( 589 + statement_results, 590 + func_scope=func_name 591 + ) 592 + 593 + # Create IRRegion for the function 594 + body_graph = IRGraph( 595 + nodes=func_nodes, 596 + edges=func_edges, 597 + regions=func_regions, 598 + data_defs=func_data_defs, 599 + ) 600 + 601 + region = IRRegion( 602 + tag=func_name, 603 + kind=RegionKind.FUNCTION, 604 + body=body_graph, 605 + loc=loc, 606 + ) 607 + 608 + return FunctionResult(region) 609 + 610 + @v_args(inline=True, meta=True) 611 + def data_def(self, meta, *args) -> StatementResult: 612 + """Process data definition.""" 613 + loc = self._extract_loc(meta) 614 + 615 + args_list = _filter_args(args) 616 + qualified_ref_dict = args_list[0] 617 + value_data = args_list[1] if len(args_list) > 1 else None 618 + 619 + name = qualified_ref_dict["name"] 620 + 621 + # Extract SM ID from placement 622 + sm_id = None 623 + if "placement" in qualified_ref_dict and qualified_ref_dict["placement"]: 624 + placement_str = qualified_ref_dict["placement"] 625 + if placement_str.startswith("sm"): 626 + try: 627 + sm_id = int(placement_str[2:]) 628 + except ValueError: 629 + pass 630 + 631 + # Extract cell address from port 632 + # The port value from qualified_ref can be: 633 + # - Port.L/Port.R (for plain edge context) 634 + # - raw int (for data_def context, e.g., :0, :1, :2, etc.) 635 + cell_addr = None 636 + if "port" in qualified_ref_dict and qualified_ref_dict["port"] is not None: 637 + port_val = qualified_ref_dict["port"] 638 + # Extract the numeric value regardless of type 639 + if isinstance(port_val, Port): 640 + cell_addr = int(port_val) 641 + elif isinstance(port_val, int): 642 + cell_addr = port_val 643 + 644 + # Handle value_data 645 + value = 0 646 + if isinstance(value_data, list): 647 + # value_list: pack values 648 + if all(isinstance(v, int) for v in value_data): 649 + # Integer values or char values 650 + if len(value_data) == 1: 651 + value = value_data[0] 652 + else: 653 + # Multiple values: only valid if all are bytes (0-255) 654 + if any(v > 255 for v in value_data): 655 + self._errors.append(AssemblyError( 656 + loc=loc, 657 + category=ErrorCategory.VALUE, 658 + message=f"Multi-value data definition cannot contain values > 255. " 659 + f"Data defs support either a single 16-bit value OR multiple byte-values packed into one word.", 660 + )) 661 + value = value_data[0] # Use first value as fallback 662 + else: 663 + # All bytes: take the already-packed value from value_list 664 + value = value_data[0] # value_list already packs consecutive pairs 665 + else: 666 + value = value_data 667 + 668 + data_def = IRDataDef( 669 + name=name, 670 + sm_id=sm_id, 671 + cell_addr=cell_addr, 672 + value=value, 673 + loc=loc, 674 + ) 675 + 676 + return DataDefResult([data_def]) 677 + 678 + @v_args(inline=True, meta=True) 679 + def location_dir(self, meta, *args) -> StatementResult: 680 + """Process location directive.""" 681 + loc = self._extract_loc(meta) 682 + 683 + args_list = _filter_args(args) 684 + qualified_ref_dict = args_list[0] 685 + 686 + tag = qualified_ref_dict["name"] 687 + 688 + # Create region for location 689 + region = IRRegion( 690 + tag=tag, 691 + kind=RegionKind.LOCATION, 692 + body=IRGraph(), 693 + loc=loc, 694 + ) 695 + 696 + return LocationResult(region) 697 + 698 + @v_args(inline=True, meta=True) 699 + def system_pragma(self, meta, *params) -> Optional[StatementResult]: 700 + """Process @system pragma.""" 701 + loc = self._extract_loc(meta) 702 + 703 + # Filter out tokens 704 + params_list = _filter_args(params) 705 + 706 + # Check for duplicate @system pragma 707 + if self._system is not None: 708 + self._errors.append(AssemblyError( 709 + loc=loc, 710 + category=ErrorCategory.PARSE, 711 + message="Duplicate @system pragma", 712 + )) 713 + return None 714 + 715 + # params are (name, value) tuples from system_param 716 + config_dict = {} 717 + for param_tuple in params_list: 718 + if isinstance(param_tuple, tuple): 719 + param_name, param_value = param_tuple 720 + config_dict[param_name] = param_value 721 + 722 + # Map parameter names 723 + pe_count = config_dict.get("pe") 724 + sm_count = config_dict.get("sm") 725 + iram_capacity = config_dict.get("iram", 64) 726 + ctx_slots = config_dict.get("ctx", 4) 727 + 728 + if pe_count is None or sm_count is None: 729 + self._errors.append(AssemblyError( 730 + loc=loc, 731 + category=ErrorCategory.PARSE, 732 + message="@system pragma requires at least 'pe' and 'sm' parameters", 733 + )) 734 + return None 735 + 736 + self._system = SystemConfig( 737 + pe_count=pe_count, 738 + sm_count=sm_count, 739 + iram_capacity=iram_capacity, 740 + ctx_slots=ctx_slots, 741 + loc=loc, 742 + ) 743 + return None # Don't return a StatementResult for pragmas 744 + 745 + @v_args(inline=True) 746 + def system_param(self, param_name: LarkToken, value) -> tuple[str, int]: 747 + """Process @system parameter.""" 748 + # value can be a token (DEC_LIT or HEX_LIT) or already an int 749 + if isinstance(value, LarkToken): 750 + value = int(str(value), 0) # 0 base handles both decimal and 0x hex 751 + return (str(param_name), value) 752 + 753 + @v_args(inline=True) 754 + def opcode(self, token: LarkToken) -> Optional[Union[ALUOp, MemOp, CfgOp]]: 755 + """Map opcode token to ALUOp, MemOp, or CfgOp enum, or None if invalid.""" 756 + mnemonic = str(token) 757 + if mnemonic not in MNEMONIC_TO_OP: 758 + # Add error but don't crash 759 + self._errors.append(AssemblyError( 760 + loc=SourceLoc(line=token.line, column=token.column), 761 + category=ErrorCategory.PARSE, 762 + message=f"Unknown opcode '{mnemonic}'", 763 + )) 764 + # Return None for invalid mnemonic 765 + return None 766 + 767 + return MNEMONIC_TO_OP[mnemonic] 768 + 769 + @v_args(inline=True) 770 + def qualified_ref(self, *args) -> dict: 771 + """Collect qualified reference components into a dict.""" 772 + ref_type = None 773 + placement = None 774 + port = None 775 + 776 + for arg in args: 777 + if isinstance(arg, dict): 778 + # This is the ref type result 779 + ref_type = arg 780 + elif isinstance(arg, str) and (arg.startswith("pe") or arg.startswith("sm")): 781 + placement = arg 782 + elif isinstance(arg, (Port, int)): 783 + # Accept both Port enum and raw int values 784 + port = arg 785 + 786 + result = ref_type.copy() if ref_type else {} 787 + if placement: 788 + result["placement"] = placement 789 + if port is not None: 790 + result["port"] = port 791 + 792 + return result 793 + 794 + @v_args(inline=True) 795 + def node_ref(self, token: LarkToken) -> dict: 796 + """Process @name reference.""" 797 + return {"name": f"@{token}"} 798 + 799 + @v_args(inline=True) 800 + def label_ref(self, token: LarkToken) -> dict: 801 + """Process &name reference.""" 802 + return {"name": f"&{token}"} 803 + 804 + @v_args(inline=True) 805 + def func_ref(self, token: LarkToken) -> dict: 806 + """Process $name reference.""" 807 + return {"name": f"${token}"} 808 + 809 + @v_args(inline=True) 810 + def placement(self, token: LarkToken) -> str: 811 + """Extract placement specifier.""" 812 + return str(token) 813 + 814 + @v_args(inline=True) 815 + def port(self, token: LarkToken) -> Union[Port, int]: 816 + """Convert port specifier to Port enum or raw int. 817 + 818 + Returns: 819 + Port.L for "L" or "0" 820 + Port.R for "R" or "1" 821 + Raw int for other numeric values (e.g., cell address) 822 + """ 823 + spec = str(token) 824 + if spec in ("L", "0"): 825 + return Port.L 826 + elif spec in ("R", "1"): 827 + return Port.R 828 + else: 829 + # Try to parse as integer (for cell addresses in data_def) 830 + try: 831 + return int(spec) 832 + except ValueError: 833 + # Fall back to Port.L for unparseable values 834 + return Port.L 835 + 836 + @v_args(inline=True) 837 + def hex_literal(self, token: LarkToken) -> int: 838 + """Parse hexadecimal literal.""" 839 + return int(str(token), 16) 840 + 841 + @v_args(inline=True) 842 + def dec_literal(self, token: LarkToken) -> int: 843 + """Parse decimal literal.""" 844 + return int(str(token)) 845 + 846 + def _process_escape_sequences(self, s: str) -> list[int]: 847 + """Process escape sequences in a string. 848 + 849 + Handles: \\n, \\t, \\r, \\0, \\\\, \\\', \\x## 850 + 851 + Args: 852 + s: String with potential escape sequences 853 + 854 + Returns: 855 + List of character codes 856 + """ 857 + result = [] 858 + i = 0 859 + while i < len(s): 860 + if i + 1 < len(s) and s[i] == "\\": 861 + next_char = s[i + 1] 862 + if next_char == "n": 863 + result.append(ord("\n")) 864 + i += 2 865 + elif next_char == "t": 866 + result.append(ord("\t")) 867 + i += 2 868 + elif next_char == "r": 869 + result.append(ord("\r")) 870 + i += 2 871 + elif next_char == "0": 872 + result.append(0) 873 + i += 2 874 + elif next_char == "\\": 875 + result.append(ord("\\")) 876 + i += 2 877 + elif next_char == "'": 878 + result.append(ord("'")) 879 + i += 2 880 + elif next_char == '"': 881 + result.append(ord('"')) 882 + i += 2 883 + elif next_char == "x" and i + 3 < len(s): 884 + # Hex escape: \xHH 885 + hex_str = s[i + 2:i + 4] 886 + try: 887 + result.append(int(hex_str, 16)) 888 + i += 4 889 + except ValueError: 890 + # Invalid hex, just include the character 891 + result.append(ord(s[i])) 892 + i += 1 893 + else: 894 + # Unknown escape, just include the character 895 + result.append(ord(s[i])) 896 + i += 1 897 + else: 898 + result.append(ord(s[i])) 899 + i += 1 900 + return result 901 + 902 + @v_args(inline=True) 903 + def char_literal(self, token: LarkToken) -> int: 904 + """Parse character literal.""" 905 + s = str(token) 906 + # Remove surrounding quotes 907 + s = s[1:-1] 908 + # Handle escape sequences 909 + if s == "\\n": 910 + return ord("\n") 911 + elif s == "\\t": 912 + return ord("\t") 913 + elif s == "\\r": 914 + return ord("\r") 915 + elif s == "\\0": 916 + return 0 917 + elif s == "\\\\": 918 + return ord("\\") 919 + elif s == "\\'": 920 + return ord("'") 921 + elif s.startswith("\\x"): 922 + return int(s[2:], 16) 923 + else: 924 + return ord(s[0]) 925 + 926 + @v_args(inline=True) 927 + def string_literal(self, token: LarkToken) -> list[int]: 928 + """Parse string literal (returns list of character codes).""" 929 + s = str(token)[1:-1] # Remove quotes 930 + return self._process_escape_sequences(s) 931 + 932 + @v_args(inline=True) 933 + def raw_string_literal(self, token: LarkToken) -> list[int]: 934 + """Parse raw string literal (no escape processing).""" 935 + s = str(token)[2:-1] # Remove r" and " 936 + return [ord(c) for c in s] 937 + 938 + @v_args(inline=True) 939 + def byte_string_literal(self, token: LarkToken) -> list[int]: 940 + """Parse byte string literal.""" 941 + s = str(token)[2:-1] # Remove b" and " 942 + return self._process_escape_sequences(s) 943 + 944 + @v_args(inline=True) 945 + def named_arg(self, arg_name: LarkToken, value: Any) -> tuple[str, Any]: 946 + """Process named argument.""" 947 + return (str(arg_name), value) 948 + 949 + @v_args(inline=True) 950 + def ref_list(self, *refs) -> list[dict]: 951 + """Collect reference list.""" 952 + return list(refs) 953 + 954 + @v_args(inline=True) 955 + def value_list(self, *values) -> list[int]: 956 + """Collect value list and pack multi-char values big-endian. 957 + 958 + - Hex/dec literals: returned as single values (not packed) 959 + - Multiple char values: packed big-endian into 16-bit words 960 + - String/list data: chars extracted and packed 961 + """ 962 + # Flatten values (strings return lists of char codes) 963 + result = [] 964 + for value in values: 965 + if isinstance(value, list): 966 + # String data from string_literal, etc. 967 + result.extend(value) 968 + else: 969 + # Single value (char or hex/dec literal) 970 + result.append(value) 971 + 972 + # Only pack if we have multiple values (char pairs) AND all are bytes 973 + if len(result) <= 1: 974 + # Single value: return as-is (whether hex literal or single char) 975 + return result 976 + 977 + all_bytes = all(0 <= v <= 255 for v in result) 978 + if not all_bytes: 979 + # Mixed or large values, return as-is 980 + return result 981 + 982 + # Multiple bytes: pack consecutive pairs big-endian 983 + packed = [] 984 + i = 0 985 + while i < len(result): 986 + if i + 1 < len(result): 987 + # Two bytes: big-endian 988 + val = (result[i] << 8) | result[i + 1] 989 + packed.append(val) 990 + i += 2 991 + else: 992 + # Single byte: pad with 0 in low byte 993 + val = (result[i] << 8) | 0x00 994 + packed.append(val) 995 + i += 1 996 + 997 + return packed 998 + 999 + 1000 + def lower(tree) -> IRGraph: 1001 + """Lower a parse tree into an IRGraph. 1002 + 1003 + Args: 1004 + tree: A Lark parse tree from parsing dfasm source 1005 + 1006 + Returns: 1007 + An IRGraph with nodes, edges, regions, and any errors encountered 1008 + """ 1009 + transformer = LowerTransformer() 1010 + return transformer.transform(tree)

+246

asm/opcodes.py

··· 1 + """Opcode mnemonic mapping and arity classification for OR1 assembly. 2 + 3 + This module provides: 4 + - MNEMONIC_TO_OP: Maps assembly mnemonic strings to ALUOp or MemOp enum values 5 + - OP_TO_MNEMONIC: Reverse mapping for serialization (handles IntEnum value collisions) 6 + - MONADIC_OPS: Set of opcodes that are always monadic 7 + - is_monadic() and is_dyadic(): Functions to check operand arity 8 + """ 9 + 10 + from typing import Optional, Union 11 + from cm_inst import ArithOp, LogicOp, RoutingOp, is_monadic_alu 12 + from tokens import MemOp, CfgOp 13 + 14 + 15 + # Build mnemonic to opcode mapping 16 + MNEMONIC_TO_OP: dict[str, Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp]] = { 17 + # Arithmetic operations 18 + "add": ArithOp.ADD, 19 + "sub": ArithOp.SUB, 20 + "inc": ArithOp.INC, 21 + "dec": ArithOp.DEC, 22 + "shiftl": ArithOp.SHIFT_L, 23 + "shiftr": ArithOp.SHIFT_R, 24 + "ashiftr": ArithOp.ASHFT_R, 25 + # Logic operations 26 + "and": LogicOp.AND, 27 + "or": LogicOp.OR, 28 + "xor": LogicOp.XOR, 29 + "not": LogicOp.NOT, 30 + "eq": LogicOp.EQ, 31 + "lt": LogicOp.LT, 32 + "lte": LogicOp.LTE, 33 + "gt": LogicOp.GT, 34 + "gte": LogicOp.GTE, 35 + # Routing/branch operations 36 + "breq": RoutingOp.BREQ, 37 + "brgt": RoutingOp.BRGT, 38 + "brge": RoutingOp.BRGE, 39 + "brof": RoutingOp.BROF, 40 + "sweq": RoutingOp.SWEQ, 41 + "swgt": RoutingOp.SWGT, 42 + "swge": RoutingOp.SWGE, 43 + "swof": RoutingOp.SWOF, 44 + "gate": RoutingOp.GATE, 45 + "sel": RoutingOp.SEL, 46 + "merge": RoutingOp.MRGE, 47 + "pass": RoutingOp.PASS, 48 + "const": RoutingOp.CONST, 49 + "free": RoutingOp.FREE, # ALU free (distinct from SM free_sm) 50 + # Memory operations 51 + "read": MemOp.READ, 52 + "write": MemOp.WRITE, 53 + "clear": MemOp.CLEAR, 54 + "alloc": MemOp.ALLOC, 55 + "free_sm": MemOp.FREE, # SM free (distinct from ALU free) 56 + "rd_inc": MemOp.RD_INC, 57 + "rd_dec": MemOp.RD_DEC, 58 + "cmp_sw": MemOp.CMP_SW, 59 + # Configuration operations (system-level) 60 + "load_inst": CfgOp.LOAD_INST, 61 + "route_set": CfgOp.ROUTE_SET, 62 + } 63 + 64 + 65 + # Build reverse mapping with type information to avoid IntEnum collisions 66 + _reverse_mapping: dict[tuple[type, int], str] = {} 67 + for mnemonic, op in MNEMONIC_TO_OP.items(): 68 + _reverse_mapping[(type(op), int(op))] = mnemonic 69 + 70 + 71 + class TypeAwareOpToMnemonicDict: 72 + """Collision-free reverse mapping from opcodes to mnemonics. 73 + 74 + Handles IntEnum cross-type equality by using (type, value) tuples internally. 75 + Supports dict-like access: OP_TO_MNEMONIC[ArithOp.ADD] returns "add", 76 + OP_TO_MNEMONIC[MemOp.READ] returns "read", etc. 77 + """ 78 + 79 + def __init__(self, mapping: dict[tuple[type, int], str]): 80 + """Initialize with a type-indexed mapping. 81 + 82 + Args: 83 + mapping: dict from (type, value) tuples to mnemonic strings 84 + """ 85 + self._mapping = mapping 86 + 87 + def __getitem__(self, op: Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp]) -> str: 88 + """Get the mnemonic for an opcode. 89 + 90 + Args: 91 + op: The opcode enum value 92 + 93 + Returns: 94 + The mnemonic string 95 + 96 + Raises: 97 + KeyError: If the opcode is not in the mapping 98 + """ 99 + key = (type(op), int(op)) 100 + if key not in self._mapping: 101 + raise KeyError(f"Opcode {op} ({type(op).__name__}) not found in mapping") 102 + return self._mapping[key] 103 + 104 + def __contains__(self, op: Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp]) -> bool: 105 + """Check if an opcode is in the mapping.""" 106 + return (type(op), int(op)) in self._mapping 107 + 108 + def __iter__(self): 109 + """Iterate over mnemonic strings.""" 110 + return iter(self._mapping.values()) 111 + 112 + def __len__(self) -> int: 113 + """Return the number of opcode-mnemonic pairs.""" 114 + return len(self._mapping) 115 + 116 + def items(self): 117 + """Return an iterator of (opcode_type, mnemonic) pairs for testing. 118 + 119 + This reconstructs the original enum instances from the stored types/values. 120 + """ 121 + result = [] 122 + for (op_type, op_val), mnemonic in self._mapping.items(): 123 + result.append((op_type(op_val), mnemonic)) 124 + return result 125 + 126 + 127 + OP_TO_MNEMONIC: TypeAwareOpToMnemonicDict = TypeAwareOpToMnemonicDict(_reverse_mapping) 128 + 129 + 130 + # Set of opcodes that are always monadic (single input operand). 131 + # We use a frozenset of (type, value) tuples to avoid IntEnum collisions. 132 + _MONADIC_OPS_TUPLES: frozenset[tuple[type, int]] = frozenset([ 133 + # ALU ops: duplicated from cm_inst.is_monadic_alu() for MONADIC_OPS membership testing. 134 + # is_monadic() short-circuits to is_monadic_alu() for ALU ops, so these entries 135 + # are only reached via `op in MONADIC_OPS` (TypeAwareMonadicOpsSet). 136 + (ArithOp, int(ArithOp.INC)), 137 + (ArithOp, int(ArithOp.DEC)), 138 + (ArithOp, int(ArithOp.SHIFT_L)), 139 + (ArithOp, int(ArithOp.SHIFT_R)), 140 + (ArithOp, int(ArithOp.ASHFT_R)), 141 + # Logic: single input 142 + (LogicOp, int(LogicOp.NOT)), 143 + # Routing: single input or no ALU involvement 144 + (RoutingOp, int(RoutingOp.PASS)), 145 + (RoutingOp, int(RoutingOp.CONST)), 146 + (RoutingOp, int(RoutingOp.FREE)), 147 + # Memory: single input (monadic SM operations) 148 + (MemOp, int(MemOp.READ)), 149 + (MemOp, int(MemOp.ALLOC)), 150 + (MemOp, int(MemOp.FREE)), 151 + (MemOp, int(MemOp.CLEAR)), 152 + (MemOp, int(MemOp.RD_INC)), 153 + (MemOp, int(MemOp.RD_DEC)), 154 + ]) 155 + 156 + 157 + class TypeAwareMonadicOpsSet: 158 + """Collision-free set of monadic opcodes. 159 + 160 + Handles IntEnum cross-type equality by using (type, value) tuples internally. 161 + Supports membership testing: ArithOp.INC in MONADIC_OPS returns True, 162 + but ArithOp.ADD in MONADIC_OPS returns False (collision-free). 163 + """ 164 + 165 + def __init__(self, tuples: frozenset[tuple[type, int]]): 166 + """Initialize with type-indexed tuples. 167 + 168 + Args: 169 + tuples: frozenset of (type, value) tuples 170 + """ 171 + self._tuples = tuples 172 + 173 + def __contains__(self, op: Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp]) -> bool: 174 + """Check if an opcode is in the set, handling IntEnum collisions. 175 + 176 + Args: 177 + op: The opcode enum value 178 + 179 + Returns: 180 + True if the opcode is monadic, False otherwise 181 + """ 182 + return (type(op), int(op)) in self._tuples 183 + 184 + def __iter__(self): 185 + """Iterate over opcode instances in the set.""" 186 + for op_type, op_val in self._tuples: 187 + yield op_type(op_val) 188 + 189 + def __len__(self) -> int: 190 + """Return the number of monadic opcodes.""" 191 + return len(self._tuples) 192 + 193 + def __repr__(self) -> str: 194 + """Return a string representation of the set.""" 195 + ops = list(self) 196 + return f"TypeAwareMonadicOpsSet({ops})" 197 + 198 + 199 + MONADIC_OPS: TypeAwareMonadicOpsSet = TypeAwareMonadicOpsSet(_MONADIC_OPS_TUPLES) 200 + 201 + 202 + def is_monadic(op: Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp], const: Optional[int] = None) -> bool: 203 + """Check if an opcode is monadic (single input operand). 204 + 205 + Args: 206 + op: The ALUOp, MemOp, or CfgOp enum value 207 + const: Optional const value. Used to determine monadic form of WRITE. 208 + If const is not None, WRITE is monadic (cell_addr from const). 209 + If const is None, WRITE is dyadic (cell_addr from left operand). 210 + 211 + Returns: 212 + True if the opcode is always monadic, or if it's WRITE with const set. 213 + False for CMP_SW (always dyadic) and WRITE with const=None (dyadic). 214 + CfgOp operations are always monadic (system-level, no ALU involvement). 215 + """ 216 + # CfgOp operations are always monadic (system-level configuration) 217 + if type(op) is CfgOp: 218 + return True 219 + 220 + # Use canonical is_monadic_alu for ALU operations 221 + if isinstance(op, (ArithOp, LogicOp, RoutingOp)): 222 + return is_monadic_alu(op) 223 + 224 + # Handle MemOp operations 225 + op_tuple = (type(op), int(op)) 226 + if op_tuple in _MONADIC_OPS_TUPLES: 227 + return True 228 + 229 + # Special case: WRITE can be monadic (const given) or dyadic (const not given) 230 + if type(op) is MemOp and op == MemOp.WRITE: 231 + return const is not None 232 + 233 + return False 234 + 235 + 236 + def is_dyadic(op: Union[ArithOp, LogicOp, RoutingOp, MemOp, CfgOp], const: Optional[int] = None) -> bool: 237 + """Check if an opcode is dyadic (two input operands). 238 + 239 + Args: 240 + op: The ALUOp, MemOp, or CfgOp enum value 241 + const: Optional const value. Used for context-dependent operations like WRITE. 242 + 243 + Returns: 244 + True if the opcode is dyadic, False otherwise. 245 + """ 246 + return not is_monadic(op, const)

+349

asm/place.py

··· 1 + """Placement validation and auto-placement pass for the OR1 assembler. 2 + 3 + Validates user-provided PE placements and performs auto-placement for unplaced nodes. 4 + Uses a greedy bin-packing algorithm with locality heuristic to assign unplaced nodes 5 + to PEs while respecting IRAM capacity and context slot limits. 6 + 7 + Reference: Phase 4 and Phase 7 design docs. 8 + """ 9 + 10 + from __future__ import annotations 11 + 12 + from collections import Counter, defaultdict 13 + from dataclasses import replace 14 + 15 + from asm.errors import AssemblyError, ErrorCategory 16 + from asm.ir import ( 17 + IRGraph, IRNode, IRRegion, RegionKind, SystemConfig, SourceLoc, collect_all_nodes, 18 + update_graph_nodes, DEFAULT_IRAM_CAPACITY, DEFAULT_CTX_SLOTS 19 + ) 20 + from asm.opcodes import is_dyadic 21 + 22 + 23 + def _infer_system_config(graph: IRGraph) -> SystemConfig: 24 + """Infer a SystemConfig from node placements if none is provided. 25 + 26 + Determines pe_count from the maximum PE ID referenced in node placements + 1. 27 + Uses default capacity values (iram_capacity=64, ctx_slots=4) matching PEConfig defaults. 28 + 29 + Args: 30 + graph: The IRGraph (may have system=None) 31 + 32 + Returns: 33 + SystemConfig with inferred pe_count and default capacity values 34 + """ 35 + max_pe_id = -1 36 + 37 + # Check all nodes recursively 38 + def _find_max_pe(nodes: dict[str, IRNode]) -> None: 39 + nonlocal max_pe_id 40 + for node in nodes.values(): 41 + if node.pe is not None and node.pe > max_pe_id: 42 + max_pe_id = node.pe 43 + 44 + _find_max_pe(graph.nodes) 45 + 46 + # Check nodes in regions 47 + def _check_regions(regions: list[IRRegion]) -> None: 48 + for region in regions: 49 + _find_max_pe(region.body.nodes) 50 + _check_regions(region.body.regions) 51 + 52 + _check_regions(graph.regions) 53 + 54 + pe_count = max(1, max_pe_id + 1) # At least 1 PE 55 + return SystemConfig( 56 + pe_count=pe_count, 57 + sm_count=1, # Default to 1 SM 58 + iram_capacity=DEFAULT_IRAM_CAPACITY, 59 + ctx_slots=DEFAULT_CTX_SLOTS, 60 + loc=SourceLoc(0, 0), 61 + ) 62 + 63 + 64 + 65 + 66 + def _find_node_scope(graph: IRGraph, node_name: str) -> str | None: 67 + """Find the function scope of a node. 68 + 69 + Returns the tag of the function region containing this node, or None if top-level. 70 + 71 + Args: 72 + graph: The IRGraph 73 + node_name: Name of the node to find 74 + 75 + Returns: 76 + Function region tag if node is in a function, None if top-level 77 + """ 78 + # Check if node is in top-level nodes 79 + if node_name in graph.nodes: 80 + return None 81 + 82 + # Search in regions recursively 83 + def _search_regions(regions: list[IRRegion]) -> str | None: 84 + for region in regions: 85 + if region.kind == RegionKind.FUNCTION: 86 + # Check if node is in this function's body 87 + if node_name in region.body.nodes: 88 + return region.tag 89 + # Recursively search nested regions (shouldn't happen with current design) 90 + result = _search_regions(region.body.regions) 91 + if result: 92 + return result 93 + else: 94 + # For LOCATION regions, nodes are still top-level conceptually 95 + if node_name in region.body.nodes: 96 + return None 97 + # Search nested regions 98 + result = _search_regions(region.body.regions) 99 + if result: 100 + return result 101 + return None 102 + 103 + return _search_regions(graph.regions) 104 + 105 + 106 + def _build_adjacency(graph: IRGraph, all_nodes: dict[str, IRNode]) -> dict[str, set[str]]: 107 + """Build adjacency map from edges: node -> set of connected neighbours. 108 + 109 + Args: 110 + graph: The IRGraph 111 + all_nodes: Dictionary of all nodes 112 + 113 + Returns: 114 + Dictionary mapping node names to sets of connected node names 115 + """ 116 + adjacency: dict[str, set[str]] = defaultdict(set) 117 + 118 + def _process_edges(edges: list) -> None: 119 + for edge in edges: 120 + # Both source and dest are neighbours 121 + adjacency[edge.source].add(edge.dest) 122 + adjacency[edge.dest].add(edge.source) 123 + 124 + _process_edges(graph.edges) 125 + 126 + # Also process edges in regions 127 + def _process_regions_edges(regions: list[IRRegion]) -> None: 128 + for region in regions: 129 + _process_edges(region.body.edges) 130 + _process_regions_edges(region.body.regions) 131 + 132 + _process_regions_edges(graph.regions) 133 + 134 + return adjacency 135 + 136 + 137 + def _count_iram_cost(node: IRNode) -> int: 138 + """Count the IRAM slots used by a node. 139 + 140 + Dyadic nodes cost 2 IRAM slots (one dyadic + one matching store entry). 141 + Monadic nodes cost 1 IRAM slot. 142 + 143 + Args: 144 + node: The IRNode 145 + 146 + Returns: 147 + Number of IRAM slots used 148 + """ 149 + # Check if the node is dyadic (two input operands) 150 + if is_dyadic(node.opcode, node.const): 151 + return 2 # Dyadic: uses 2 slots (IRAM + matching store) 152 + return 1 # Monadic: uses 1 slot 153 + 154 + 155 + def _auto_place_nodes( 156 + graph: IRGraph, 157 + system: SystemConfig, 158 + all_nodes: dict[str, IRNode], 159 + adjacency: dict[str, set[str]], 160 + ) -> tuple[dict[str, IRNode], list[AssemblyError]]: 161 + """Auto-place unplaced nodes using greedy bin-packing with locality heuristic. 162 + 163 + Algorithm: 164 + 1. Identify unplaced nodes (pe=None) 165 + 2. For each unplaced node in order: 166 + a. Find PE of connected neighbours (use updated_nodes for current placements) 167 + b. Prefer PE with most neighbours (locality) 168 + c. Tie-break by remaining IRAM capacity 169 + d. If no PE has room, record error and continue 170 + 3. Return updated nodes and any placement errors 171 + 172 + Args: 173 + graph: The IRGraph 174 + system: SystemConfig with pe_count, iram_capacity, ctx_slots 175 + all_nodes: Dictionary of all nodes 176 + adjacency: Adjacency map 177 + 178 + Returns: 179 + Tuple of (updated nodes dict, list of placement errors) 180 + """ 181 + errors: list[AssemblyError] = [] 182 + 183 + # Track resource usage per PE: (iram_used, ctx_used) 184 + iram_used = [0] * system.pe_count 185 + ctx_used = [0] * system.pe_count 186 + 187 + # Copy nodes so we can update placement as we go 188 + updated_nodes = dict(all_nodes) 189 + 190 + # Initialize PE resource usage from explicitly placed nodes 191 + # Track which function scopes have been counted per PE to avoid double-counting 192 + ctx_scopes_per_pe: dict[int, set[str | None]] = {pe_id: set() for pe_id in range(system.pe_count)} 193 + 194 + for node_name, node in updated_nodes.items(): 195 + if node.pe is not None: 196 + iram_cost = _count_iram_cost(node) 197 + iram_used[node.pe] += iram_cost 198 + # Count context slots per function scope, not per node 199 + scope = _find_node_scope(graph, node_name) 200 + if scope not in ctx_scopes_per_pe[node.pe]: 201 + ctx_scopes_per_pe[node.pe].add(scope) 202 + ctx_used[node.pe] += 1 203 + 204 + # For unplaced nodes, we'll track scopes similarly 205 + ctx_scopes_updated: dict[int, set[str | None]] = {pe_id: set(scopes) for pe_id, scopes in ctx_scopes_per_pe.items()} 206 + 207 + # Process nodes in insertion order 208 + for node_name, node in all_nodes.items(): 209 + if node.pe is not None: 210 + # Already placed, skip 211 + continue 212 + 213 + # Find neighbours and their PEs (from updated_nodes to include newly placed nodes) 214 + neighbours = adjacency.get(node_name, set()) 215 + neighbour_pes: list[int] = [] 216 + for neighbour_name in neighbours: 217 + neighbour = updated_nodes.get(neighbour_name) 218 + if neighbour and neighbour.pe is not None: 219 + neighbour_pes.append(neighbour.pe) 220 + 221 + # Count PE occurrences among neighbours (for locality heuristic) 222 + pe_counts: dict[int, int] = Counter(neighbour_pes) 223 + 224 + # Sort PEs by: most neighbours first, then most remaining IRAM 225 + candidate_pes = list(range(system.pe_count)) 226 + candidate_pes.sort( 227 + key=lambda pe: ( 228 + -pe_counts.get(pe, 0), # Negative so most neighbours come first 229 + -(system.iram_capacity - iram_used[pe]), # Then most room 230 + ), 231 + ) 232 + 233 + # Find first PE with room 234 + iram_cost = _count_iram_cost(node) 235 + node_scope = _find_node_scope(graph, node_name) 236 + placed = False 237 + for pe in candidate_pes: 238 + # Check if this scope is new to this PE 239 + scope_is_new = node_scope not in ctx_scopes_updated[pe] 240 + ctx_slots_needed = 1 if scope_is_new else 0 241 + 242 + if ( 243 + iram_used[pe] + iram_cost <= system.iram_capacity 244 + and ctx_used[pe] + ctx_slots_needed <= system.ctx_slots 245 + ): 246 + # Place node on this PE 247 + updated_nodes[node_name] = replace(node, pe=pe) 248 + iram_used[pe] += iram_cost 249 + if scope_is_new: 250 + ctx_scopes_updated[pe].add(node_scope) 251 + ctx_used[pe] += 1 252 + placed = True 253 + break 254 + 255 + if not placed: 256 + # No PE has room - generate error with utilization breakdown 257 + error = _format_placement_overflow_error(node, system, iram_used, ctx_used) 258 + errors.append(error) 259 + 260 + return updated_nodes, errors 261 + 262 + 263 + def _format_placement_overflow_error( 264 + node: IRNode, 265 + system: SystemConfig, 266 + iram_used: list[int], 267 + ctx_used: list[int], 268 + ) -> AssemblyError: 269 + """Format a placement overflow error with per-PE utilization breakdown. 270 + 271 + Args: 272 + node: The node that couldn't be placed 273 + system: SystemConfig 274 + iram_used: List of IRAM slots used per PE 275 + ctx_used: List of context slots used per PE 276 + 277 + Returns: 278 + AssemblyError with detailed breakdown 279 + """ 280 + breakdown_lines = [] 281 + for pe_id in range(system.pe_count): 282 + breakdown_lines.append( 283 + f" PE{pe_id}: {iram_used[pe_id]}/{system.iram_capacity} IRAM slots, " 284 + f"{ctx_used[pe_id]}/{system.ctx_slots} context slots" 285 + ) 286 + 287 + breakdown = "\n".join(breakdown_lines) 288 + message = f"Cannot place node '{node.name}': all PEs are full.\n{breakdown}" 289 + 290 + return AssemblyError( 291 + loc=node.loc, 292 + category=ErrorCategory.PLACEMENT, 293 + message=message, 294 + suggestions=[], 295 + ) 296 + 297 + 298 + def place(graph: IRGraph) -> IRGraph: 299 + """Placement pass: validate explicit placements and auto-place unplaced nodes. 300 + 301 + Process: 302 + 1. Infer or use provided SystemConfig 303 + 2. Validate explicitly placed nodes (pe is not None) 304 + 3. Auto-place any unplaced nodes using greedy bin-packing + locality 305 + 4. Validate all PE IDs are < pe_count 306 + 307 + Args: 308 + graph: The IRGraph to place 309 + 310 + Returns: 311 + New IRGraph with all nodes placed and placement errors appended 312 + """ 313 + # Determine system config 314 + system = graph.system if graph.system is not None else _infer_system_config(graph) 315 + 316 + errors = list(graph.errors) 317 + 318 + # Collect all nodes 319 + all_nodes = collect_all_nodes(graph) 320 + 321 + # First pass: validate explicitly placed nodes (reject invalid PE IDs) 322 + valid_nodes = {} 323 + for node_name, node in all_nodes.items(): 324 + if node.pe is not None and node.pe >= system.pe_count: 325 + error = AssemblyError( 326 + loc=node.loc, 327 + category=ErrorCategory.PLACEMENT, 328 + message=f"Node '{node_name}' placed on PE{node.pe} but system only has {system.pe_count} PEs (0-{system.pe_count - 1}).", 329 + suggestions=[], 330 + ) 331 + errors.append(error) 332 + else: 333 + valid_nodes[node_name] = node 334 + 335 + all_nodes = valid_nodes 336 + 337 + # Check if any nodes are unplaced 338 + unplaced_nodes = [node for node in all_nodes.values() if node.pe is None] 339 + 340 + if unplaced_nodes: 341 + # Auto-place unplaced nodes 342 + adjacency = _build_adjacency(graph, all_nodes) 343 + all_nodes, placement_errors = _auto_place_nodes(graph, system, all_nodes, adjacency) 344 + errors.extend(placement_errors) 345 + 346 + # Update graph with placed nodes 347 + # This ensures nodes inside function scopes receive updated PE assignments 348 + result_graph = update_graph_nodes(graph, all_nodes) 349 + return replace(result_graph, system=system, errors=errors)

+348

asm/resolve.py

··· 1 + """Name resolution pass for the OR1 assembler. 2 + 3 + Resolves all symbolic references in an IRGraph to concrete nodes. Implements: 4 + - Flattening of nested nodes (from regions) into a unified namespace 5 + - Edge validation (all edges reference existing nodes) 6 + - Scope violation detection (cross-function label references) 7 + - Levenshtein distance-based "did you mean" suggestions 8 + - Error accumulation (all issues reported, not fail-fast) 9 + 10 + Reference: Phase 3 design doc. 11 + """ 12 + 13 + from __future__ import annotations 14 + 15 + from collections.abc import Iterable 16 + from dataclasses import replace 17 + from typing import Optional 18 + 19 + from asm.errors import AssemblyError, ErrorCategory 20 + from asm.ir import IRGraph, IRNode, IREdge, IRRegion, SourceLoc, collect_all_nodes 21 + 22 + 23 + def _levenshtein(a: str, b: str) -> int: 24 + """Compute Levenshtein (edit) distance between two strings. 25 + 26 + Args: 27 + a: First string 28 + b: Second string 29 + 30 + Returns: 31 + Minimum edit distance (number of single-character edits) 32 + """ 33 + if len(a) < len(b): 34 + return _levenshtein(b, a) 35 + if not b: 36 + return len(a) 37 + 38 + prev = list(range(len(b) + 1)) 39 + for i, ca in enumerate(a): 40 + curr = [i + 1] 41 + for j, cb in enumerate(b): 42 + curr.append(min( 43 + prev[j + 1] + 1, # deletion 44 + curr[j] + 1, # insertion 45 + prev[j] + (ca != cb), # substitution 46 + )) 47 + prev = curr 48 + return prev[-1] 49 + 50 + 51 + def _build_scope_map(graph: IRGraph) -> dict[str, str]: 52 + """Build a map of node names to their defining scope. 53 + 54 + For top-level nodes, scope is None (empty string in map). 55 + For function-scoped nodes, scope is the function name (e.g., "$foo"). 56 + 57 + Args: 58 + graph: The IRGraph 59 + 60 + Returns: 61 + Dictionary mapping qualified name -> scope tag (or "" for top-level) 62 + """ 63 + scope_map = {} 64 + 65 + # Top-level nodes have empty scope 66 + for name in graph.nodes: 67 + scope_map[name] = "" 68 + 69 + # Walk regions to find function-scoped nodes 70 + def _walk_regions(regions: list[IRRegion], parent_scope: str = "") -> None: 71 + for region in regions: 72 + for name in region.body.nodes: 73 + # Scope is the region tag (e.g., "$foo") 74 + scope_map[name] = region.tag 75 + # Recursively walk nested regions 76 + _walk_regions(region.body.regions, region.tag) 77 + 78 + _walk_regions(graph.regions) 79 + return scope_map 80 + 81 + 82 + def _check_edge_resolved( 83 + edge: IREdge, 84 + flattened: dict[str, IRNode], 85 + scope_map: dict[str, str], 86 + source_scope: str = "", 87 + ) -> Optional[AssemblyError]: 88 + """Validate that an edge's source and dest exist in the flattened namespace. 89 + 90 + If either end is missing, generate an appropriate error: 91 + - NAME error if name doesn't exist anywhere 92 + - SCOPE error if name exists but in a different function scope 93 + - Includes "did you mean" suggestions via Levenshtein distance 94 + 95 + Edges can be either: 96 + 1. Already qualified by Lower pass (e.g., "$bar.&data") 97 + 2. Simple names that need qualification (older style) 98 + 99 + Args: 100 + edge: The IREdge to validate 101 + flattened: Flattened node dictionary 102 + scope_map: Scope map from _build_scope_map 103 + source_scope: The scope context where this edge was defined (e.g., "$foo") 104 + 105 + Returns: 106 + AssemblyError if validation fails, None if passes 107 + """ 108 + # Resolve source 109 + source_name = edge.source 110 + if source_name not in flattened: 111 + # Try with scope qualification if not already qualified 112 + if "." not in source_name and source_scope: 113 + qualified_source = f"{source_scope}.{source_name}" 114 + if qualified_source not in flattened: 115 + return _generate_unresolved_error( 116 + source_name, 117 + edge.loc, 118 + flattened, 119 + scope_map, 120 + ) 121 + source_name = qualified_source 122 + else: 123 + return _generate_unresolved_error( 124 + source_name, 125 + edge.loc, 126 + flattened, 127 + scope_map, 128 + ) 129 + 130 + # Resolve dest 131 + dest_name = edge.dest 132 + if dest_name not in flattened: 133 + # Try with scope qualification if not already qualified 134 + if "." not in dest_name and source_scope: 135 + qualified_dest = f"{source_scope}.{dest_name}" 136 + if qualified_dest not in flattened: 137 + # Check if dest exists in a different scope 138 + if dest_name.startswith("&"): 139 + for full_name, scope in scope_map.items(): 140 + if scope != "" and full_name.endswith("." + dest_name): 141 + # Found in different scope 142 + message = ( 143 + f"Reference to '{dest_name}' not found in this scope. " 144 + f"Did you mean '{full_name}'? (defined in function '{scope}')" 145 + ) 146 + return AssemblyError( 147 + loc=edge.loc, 148 + category=ErrorCategory.SCOPE, 149 + message=message, 150 + suggestions=[], 151 + ) 152 + return _generate_unresolved_error( 153 + dest_name, 154 + edge.loc, 155 + flattened, 156 + scope_map, 157 + ) 158 + dest_name = qualified_dest 159 + else: 160 + # dest_name is already qualified or there's no scope context 161 + # Check if it's a cross-scope reference 162 + if "." in dest_name: 163 + # Already qualified, extract the simple name 164 + simple_name = dest_name.split(".")[-1] 165 + # Check if this simple name exists in any other scope 166 + for full_name, scope in scope_map.items(): 167 + if scope != "" and full_name.endswith("." + simple_name) and full_name != dest_name: 168 + # Found in different scope 169 + message = ( 170 + f"Reference to '{dest_name}' not found. " 171 + f"Did you mean '{full_name}'? (defined in function '{scope}')" 172 + ) 173 + return AssemblyError( 174 + loc=edge.loc, 175 + category=ErrorCategory.SCOPE, 176 + message=message, 177 + suggestions=[], 178 + ) 179 + return _generate_unresolved_error( 180 + dest_name, 181 + edge.loc, 182 + flattened, 183 + scope_map, 184 + ) 185 + 186 + return None 187 + 188 + 189 + def _generate_unresolved_error( 190 + name: str, 191 + loc: SourceLoc, 192 + flattened: dict[str, IRNode], 193 + scope_map: dict[str, str], 194 + ) -> AssemblyError: 195 + """Generate an error for an unresolved name reference. 196 + 197 + Determines whether it's a NAME error (not found) or SCOPE error (found 198 + in different scope), and generates "did you mean" suggestions. 199 + 200 + Args: 201 + name: The unresolved name 202 + loc: Source location of the reference 203 + flattened: Flattened node dictionary 204 + scope_map: Scope map from _build_scope_map 205 + 206 + Returns: 207 + AssemblyError with appropriate category and suggestions 208 + """ 209 + # Check if this name exists in a different scope 210 + # For now, we only need to check if it's a label reference (starts with &) 211 + # and exists in some function scope 212 + if name.startswith("&"): 213 + # Look for this label in any function scope 214 + for full_name, scope in scope_map.items(): 215 + if scope != "" and full_name.endswith("." + name): 216 + # Found the label in a function scope 217 + message = ( 218 + f"Reference to '{name}' not found. " 219 + f"Did you mean '{full_name}'? (defined in function '{scope}')" 220 + ) 221 + return AssemblyError( 222 + loc=loc, 223 + category=ErrorCategory.SCOPE, 224 + message=message, 225 + suggestions=[], 226 + ) 227 + 228 + # Not found anywhere - generate NAME error with suggestions 229 + suggestions = _suggest_names(name, flattened.keys()) 230 + message = f"undefined reference to '{name}'" 231 + 232 + return AssemblyError( 233 + loc=loc, 234 + category=ErrorCategory.NAME, 235 + message=message, 236 + suggestions=suggestions, 237 + ) 238 + 239 + 240 + def _suggest_names(unresolved: str, available_names: Iterable[str]) -> list[str]: 241 + """Generate "did you mean" suggestions via Levenshtein distance. 242 + 243 + Compares unresolved name against all available names, returning suggestions 244 + with distance <= 3, or the closest match if all distances are > 3. 245 + 246 + Args: 247 + unresolved: The unresolved name 248 + available_names: Iterable of available node names 249 + 250 + Returns: 251 + List of suggestion strings (may be empty) 252 + """ 253 + if not available_names: 254 + return [] 255 + 256 + # Compute distances 257 + candidates = [] 258 + for name in available_names: 259 + dist = _levenshtein(unresolved, name) 260 + candidates.append((dist, name)) 261 + 262 + # Sort by distance 263 + candidates.sort(key=lambda x: x[0]) 264 + 265 + # Return suggestions with distance <= 3, or best if all > 3 266 + suggestions = [] 267 + best_distance = candidates[0][0] 268 + 269 + for dist, name in candidates: 270 + if dist <= 3 or dist == best_distance: 271 + suggestions.append(f"Did you mean '{name}'?") 272 + else: 273 + break 274 + 275 + return suggestions 276 + 277 + 278 + def _check_edges_recursive( 279 + graph: IRGraph, 280 + flattened: dict[str, IRNode], 281 + scope_map: dict[str, str], 282 + source_scope: str = "", 283 + ) -> list[AssemblyError]: 284 + """Recursively validate all edges in the graph and its regions. 285 + 286 + Args: 287 + graph: The IRGraph to check 288 + flattened: Flattened node dictionary 289 + scope_map: Scope map 290 + source_scope: The scope context for this graph (e.g., "$foo" for region bodies) 291 + 292 + Returns: 293 + List of AssemblyErrors found 294 + """ 295 + errors = [] 296 + 297 + # Check edges at this level with the current scope context 298 + for edge in graph.edges: 299 + error = _check_edge_resolved(edge, flattened, scope_map, source_scope) 300 + if error: 301 + errors.append(error) 302 + 303 + # Check edges in nested regions, passing the region's scope 304 + for region in graph.regions: 305 + errors.extend( 306 + _check_edges_recursive(region.body, flattened, scope_map, region.tag) 307 + ) 308 + 309 + return errors 310 + 311 + 312 + def resolve(graph: IRGraph) -> IRGraph: 313 + """Resolve all symbolic references in an IRGraph. 314 + 315 + Returns a new IRGraph with all name resolution errors appended to 316 + graph.errors. If there are no errors, the returned graph is structurally 317 + identical to the input (immutable pass pattern). 318 + 319 + The resolution process: 320 + 1. Flattens all nodes (from graph and nested regions) 321 + 2. Builds a scope map (top-level vs function-scoped) 322 + 3. Validates all edges reference existing nodes 323 + 4. Accumulates errors (all issues found, not fail-fast) 324 + 5. Returns new IRGraph with errors appended 325 + 326 + Args: 327 + graph: The IRGraph to resolve 328 + 329 + Returns: 330 + New IRGraph with resolution errors appended to graph.errors 331 + """ 332 + # Skip if already has errors from earlier phases 333 + if graph.errors: 334 + return graph 335 + 336 + # Flatten nodes and build scope map 337 + flattened = collect_all_nodes(graph) 338 + scope_map = _build_scope_map(graph) 339 + 340 + # Check all edges 341 + resolution_errors = _check_edges_recursive(graph, flattened, scope_map) 342 + 343 + # Return new graph with errors appended 344 + if resolution_errors: 345 + new_errors = list(graph.errors) + resolution_errors 346 + return replace(graph, errors=new_errors) 347 + 348 + return graph

+206

asm/serialize.py

··· 1 + """Serialize IRGraph back to dfasm source text. 2 + 3 + This module provides the serialize() function that converts an IRGraph (at any 4 + pipeline stage) back to valid dfasm source, enabling inspection of IR after 5 + lowering, resolution, placement, or allocation. 6 + 7 + The serializer emits: 8 + - inst_def lines for nodes: {qualified_ref}|pe{N} <| {mnemonic}[, {const}] 9 + - plain_edge lines for edges: {source} |> {dest}:{port} 10 + - data_def lines: {name}|sm{id}:{cell} = {value} 11 + - FUNCTION regions: $name |> { ...body... } 12 + - LOCATION regions: bare directive tag followed by body 13 + 14 + Names inside FUNCTION regions are unqualified (prefix stripped). 15 + Anonymous nodes (__anon_*) are always emitted as inst_def + plain_edge, 16 + never as inline syntax. 17 + """ 18 + 19 + from asm.ir import ( 20 + IRGraph, IRNode, IREdge, IRRegion, RegionKind, IRDataDef 21 + ) 22 + from asm.opcodes import OP_TO_MNEMONIC 23 + from tokens import Port 24 + 25 + 26 + def serialize(graph: IRGraph) -> str: 27 + """Serialize an IRGraph to dfasm source text. 28 + 29 + Converts an IRGraph back to valid dfasm source at any pipeline stage. 30 + Useful for inspecting IR after lowering, resolution, placement, or allocation. 31 + 32 + Args: 33 + graph: The IRGraph to serialize 34 + 35 + Returns: 36 + A string containing valid dfasm source text 37 + """ 38 + if not graph.nodes and not graph.regions and not graph.data_defs and not graph.edges: 39 + return "" 40 + 41 + lines = [] 42 + 43 + # Collect all nodes that are inside regions for later exclusion from top-level output 44 + nodes_in_regions: set[str] = set() 45 + edges_in_regions: set[tuple[str, str, Port]] = set() # Track edges by (source, dest, port) tuple 46 + data_defs_in_regions: set[str] = set() 47 + 48 + # First pass: collect what's inside regions 49 + for region in graph.regions: 50 + for node_name in region.body.nodes.keys(): 51 + nodes_in_regions.add(node_name) 52 + for edge in region.body.edges: 53 + edges_in_regions.add((edge.source, edge.dest, edge.port)) 54 + for data_def in region.body.data_defs: 55 + data_defs_in_regions.add(data_def.name) 56 + 57 + # Emit regions in order 58 + for region in graph.regions: 59 + lines.append(_serialize_region(region, graph)) 60 + 61 + # Emit top-level nodes (not inside any region) 62 + for name, node in graph.nodes.items(): 63 + if name not in nodes_in_regions: 64 + lines.append(_serialize_node(name, node, func_scope=None)) 65 + 66 + # Emit top-level edges (not inside any region) 67 + for edge in graph.edges: 68 + edge_key = (edge.source, edge.dest, edge.port) 69 + if edge_key not in edges_in_regions: 70 + lines.append(_serialize_edge(edge)) 71 + 72 + # Emit top-level data_defs (not inside any region) 73 + for data_def in graph.data_defs: 74 + if data_def.name not in data_defs_in_regions: 75 + lines.append(_serialize_data_def(data_def)) 76 + 77 + # Filter out empty lines and join 78 + output = '\n'.join(line for line in lines if line.strip()) 79 + return output + '\n' if output else "" 80 + 81 + 82 + def _serialize_region(region: IRRegion, parent_graph: IRGraph) -> str: 83 + """Serialize a single region (FUNCTION or LOCATION). 84 + 85 + Args: 86 + region: The IRRegion to serialize 87 + parent_graph: Parent IRGraph (for context) 88 + 89 + Returns: 90 + String containing the serialized region 91 + """ 92 + lines = [] 93 + 94 + if region.kind == RegionKind.FUNCTION: 95 + # FUNCTION regions: $name |> { ...body... } 96 + lines.append(f"{region.tag} |> {{") 97 + 98 + # Serialize body with function scope for name unqualification 99 + func_scope = region.tag 100 + for name, node in region.body.nodes.items(): 101 + lines.append(_serialize_node(name, node, func_scope=func_scope)) 102 + 103 + # Edges inside function 104 + for edge in region.body.edges: 105 + lines.append(_serialize_edge(edge, func_scope=func_scope)) 106 + 107 + # Data defs inside function 108 + for data_def in region.body.data_defs: 109 + lines.append(_serialize_data_def(data_def)) 110 + 111 + lines.append("}") 112 + 113 + elif region.kind == RegionKind.LOCATION: 114 + # LOCATION regions: bare directive tag, then body 115 + lines.append(region.tag) 116 + 117 + # Serialize body (no function scope for locations) 118 + for name, node in region.body.nodes.items(): 119 + lines.append(_serialize_node(name, node, func_scope=None)) 120 + 121 + for edge in region.body.edges: 122 + lines.append(_serialize_edge(edge)) 123 + 124 + for data_def in region.body.data_defs: 125 + lines.append(_serialize_data_def(data_def)) 126 + 127 + return '\n'.join(lines) 128 + 129 + 130 + def _serialize_node(name: str, node: IRNode, func_scope: str | None) -> str: 131 + """Serialize a single IR node as an inst_def line. 132 + 133 + Args: 134 + name: The node name 135 + node: The IRNode 136 + func_scope: If provided, unqualify the name by stripping this prefix 137 + 138 + Returns: 139 + String containing the inst_def line 140 + """ 141 + # Unqualify the name if inside a function 142 + if func_scope and name.startswith(f"{func_scope}."): 143 + display_name = name[len(func_scope) + 1:] 144 + else: 145 + display_name = name 146 + 147 + # Get mnemonic 148 + try: 149 + mnemonic = OP_TO_MNEMONIC[node.opcode] 150 + except (KeyError, TypeError): 151 + # Fallback if mnemonic not found 152 + mnemonic = str(node.opcode).lower() 153 + 154 + # Build inst_def line: {ref}|pe{N} <| {mnemonic}[, {const}] 155 + pe_part = f"|pe{node.pe}" if node.pe is not None else "" 156 + line = f"{display_name}{pe_part} <| {mnemonic}" 157 + 158 + # Add const if present 159 + if node.const is not None: 160 + line += f", {node.const}" 161 + 162 + return line 163 + 164 + 165 + def _serialize_edge(edge: IREdge, func_scope: str | None = None) -> str: 166 + """Serialize a single edge as a plain_edge line. 167 + 168 + Args: 169 + edge: The IREdge 170 + func_scope: If provided, unqualify names by stripping this prefix 171 + 172 + Returns: 173 + String containing the plain_edge line 174 + """ 175 + # Unqualify names if inside a function scope 176 + source = edge.source 177 + dest = edge.dest 178 + 179 + if func_scope: 180 + if source.startswith(f"{func_scope}."): 181 + source = source[len(func_scope) + 1:] 182 + if dest.startswith(f"{func_scope}."): 183 + dest = dest[len(func_scope) + 1:] 184 + 185 + # Format port as :L or :R 186 + port_str = ":L" if edge.port == Port.L else ":R" 187 + 188 + return f"{source} |> {dest}{port_str}" 189 + 190 + 191 + def _serialize_data_def(data_def: IRDataDef) -> str: 192 + """Serialize a single data definition. 193 + 194 + Args: 195 + data_def: The IRDataDef 196 + 197 + Returns: 198 + String containing the data_def line 199 + """ 200 + sm_part = f"|sm{data_def.sm_id}" if data_def.sm_id is not None else "" 201 + cell_part = f":{data_def.cell_addr}" if data_def.cell_addr is not None else "" 202 + 203 + # Format value as hex if larger than a byte, decimal otherwise 204 + value_str = f"0x{data_def.value:x}" if data_def.value > 255 else str(data_def.value) 205 + 206 + return f"{data_def.name}{sm_part}{cell_part} = {value_str}"

+44 -15

cm_inst.py

··· 1 1 from dataclasses import dataclass 2 2 from enum import IntEnum 3 - from tokens import CMToken, Port, MemOp 4 - from typing import Optional, Union 5 - 6 - from typing_extensions import IntVar 3 + from tokens import Port, MemOp 4 + from typing import Optional 7 5 8 6 9 7 class ALUOp(IntEnum): ··· 71 69 const: Optional[int] 72 70 73 71 74 - @dataclass 75 - class CMComputeOp(object): 76 - """ 77 - Operation with data tokens 78 - """ 79 - 80 - inst: ALUInst 81 - in_l: Optional[CMToken] 82 - in_r: Optional[CMToken] 83 - 84 - 85 72 @dataclass(frozen=True) 86 73 class SMInst(object): 87 74 """ ··· 101 88 sm_id: int 102 89 const: Optional[int] = None 103 90 ret: Optional[Addr] = None 91 + 92 + 93 + # Monadic ALU operations: take a single operand 94 + # (Defined here as the canonical source of truth for emu and asm modules) 95 + _MONADIC_ARITH_OPS = frozenset({ 96 + ArithOp.INC, 97 + ArithOp.DEC, 98 + ArithOp.SHIFT_L, 99 + ArithOp.SHIFT_R, 100 + ArithOp.ASHFT_R, 101 + }) 102 + 103 + _MONADIC_LOGIC_OPS = frozenset({ 104 + LogicOp.NOT, 105 + }) 106 + 107 + _MONADIC_ROUTING_OPS = frozenset({ 108 + RoutingOp.PASS, 109 + RoutingOp.CONST, 110 + RoutingOp.FREE, 111 + }) 112 + 113 + 114 + def is_monadic_alu(op: ALUOp) -> bool: 115 + """Check if an ALU operation is monadic (single operand). 116 + 117 + This is the canonical source of truth for monadic ALU op classification. 118 + emu/pe.py and asm/opcodes.py use this for ALU ops. 119 + 120 + Args: 121 + op: An ALUOp enum value (ArithOp, LogicOp, or RoutingOp) 122 + 123 + Returns: 124 + True if the operation takes a single operand, False otherwise 125 + """ 126 + if isinstance(op, ArithOp): 127 + return op in _MONADIC_ARITH_OPS 128 + if isinstance(op, LogicOp): 129 + return op in _MONADIC_LOGIC_OPS 130 + if isinstance(op, RoutingOp): 131 + return op in _MONADIC_ROUTING_OPS 132 + return False

+7

dfasm.lark

+539

docs/design-plans/2026-02-22-or1-asm.md

··· 1 + # OR1 Dataflow Assembler & Bootstrap Design 2 + 3 + ## Summary 4 + 5 + This design specifies a multi-pass assembler for the OR1 dataflow CPU that translates human-readable dfasm source code into emulator-ready configurations. The assembler takes a declarative dataflow program — where instructions are nodes and token routing edges describe dependencies — and produces either direct emulator configurations (PEConfig/SMConfig objects with pre-loaded instruction memory) or a hardware-faithful bootstrap token stream (structure memory initialization, routing table configuration, instruction loading, and seed tokens). 6 + 7 + The assembler pipeline consists of five main passes operating on an immutable intermediate representation (IRGraph). The Lower pass desugars syntactic sugar and qualifies names with function scope. The Resolve pass validates symbolic references and detects errors. The Place pass assigns nodes to physical processing elements, either validating user annotations or performing automatic placement via greedy bin-packing. The Allocate pass assigns instruction memory offsets (with dyadic instructions packed first for matching store alignment) and context slots (one per function per PE), then resolves symbolic destinations to concrete hardware addresses. Finally, Codegen produces emulator input in one of two modes: direct configuration objects for immediate execution, or an ordered token stream that mirrors how hardware would bootstrap the machine. The design also includes a serializer that converts an IRGraph back to valid dfasm source, enabling round-trip testing and human inspection of auto-placement results. Error reporting emphasizes source locations with context and "did you mean" suggestions. 8 + 9 + ## Definition of Done 10 + 11 + 1. **Emulator ROUTE_SET support** — `CfgOp.ROUTE_SET` processing in the PE actually restricts the PE's `route_table` to configured destinations (rather than full-mesh). `CfgToken.data` format for ROUTE_SET is defined and implemented. Attempting to route to an unconfigured destination produces a clear error. 12 + 13 + 2. **Assembler pipeline** — A Python module (`lang.py` or package) that takes a dfasm source program, parses it using the existing Lark grammar (`dfasm.lark`), performs semantic analysis (name resolution, type checking, resource allocation), and produces either: 14 + - **Direct mode**: `PEConfig`/`SMConfig` lists + seed tokens for `build_topology()` consumption 15 + - **Token stream mode**: Hardware-faithful ordered bootstrap sequence (SM init → ROUTE_SET → LOAD_INST → seed tokens) 16 + 17 + 3. **Namespace scoping** — `&labels` are scoped to their enclosing `$function`. `@nodes` are global. Cross-function wiring uses `@node` references or explicit edges between function boundaries. 18 + 19 + 4. **Grammar coverage** — The assembler handles: `inst_def`, `plain_edge`, `strong_edge`, `weak_edge`, `func_def`, `data_def`, and `location_dir`. Macros (`#name`) are excluded from this design. 20 + 21 + 5. **Specification and resolution** — 22 + - **Fully specified mode**: User provides PE placement (`|pe0`) and port annotations (`:L`/`:R`). IRAM offsets and context slots are deterministically assigned by the assembler. Detailed error messages when PE resources (IRAM slots, context slots) overflow. 23 + - **Auto-placement mode** (same design, later phase): Assembler fills in PE placement when omitted. First pass expected to be naive (may underutilize PEs), with the architecture supporting progressive improvement. 24 + 25 + 6. **Error reporting** — Clear, actionable error messages for: missing annotations, invalid references, resource overflow (IRAM/context slots), type mismatches (monadic/dyadic arity), unreachable nodes, and malformed programs. 26 + 27 + 7. **Bootstrap ordering** — Token stream output follows hardware-faithful ordering: SM cell initialization → routing configuration (ROUTE_SET) → instruction loading (LOAD_INST) → seed token injection. 28 + 29 + 8. **Serialization** — IRGraph serializes back to valid dfasm source text with full placement qualifiers, enabling round-trip testing (parse → assemble → serialize → parse → compare) and human inspection of auto-placement results. 30 + 31 + 9. **Test suite** — Property-based and integration tests covering: parse → IR round-trips, semantic validation (error cases), resource allocation correctness, output token stream validity, serialization round-trip fidelity, and end-to-end assemble → emulate for reference programs. 32 + 33 + ## Acceptance Criteria 34 + 35 + ### or1-asm.AC1: Grammar & Opcode Mapping 36 + - **or1-asm.AC1.1 Success:** All existing ALU opcodes (`add`, `sub`, `inc`, `dec`, `shiftl`, `shiftr`, `ashiftr`, `and`, `or`, `xor`, `not`, `eq`, `lt`, `lte`, `gt`, `gte`, `breq`, `brgt`, `brge`, `brof`, `sweq`, `swgt`, `swge`, `swof`, `gate`, `sel`, `merge`, `pass`, `const`, `free`) parse and map to correct `ALUOp` enum values 37 + - **or1-asm.AC1.2 Success:** SM memory opcodes (`read`, `write`, `clear`, `alloc`, `rd_inc`, `rd_dec`, `cmp_sw`) parse and map to correct `MemOp` enum values 38 + - **or1-asm.AC1.3 Success:** Arity table correctly classifies all opcodes as monadic or dyadic 39 + - **or1-asm.AC1.4 Failure:** Unknown opcode in source produces parse error with source location 40 + 41 + ### or1-asm.AC2: Lower Pass — Instruction & Edge Handling 42 + - **or1-asm.AC2.1 Success:** `inst_def` (`&label <| opcode`) lowers to IRNode with correct opcode and name 43 + - **or1-asm.AC2.2 Success:** `plain_edge` (`&a |> &b:L`) lowers to IREdge with correct source, dest, and port 44 + - **or1-asm.AC2.3 Success:** `strong_edge` (`add &a, &b |> &c, &d`) desugars into anonymous IRNode + wiring edges 45 + - **or1-asm.AC2.4 Success:** `weak_edge` (`&c, &d sub <| &a, &b`) desugars identically to equivalent strong edge 46 + - **or1-asm.AC2.5 Success:** `data_def` (`@name|sm0:0 = 0x05`) lowers to IRDataDef with correct SM ID, cell address, and value 47 + - **or1-asm.AC2.6 Success:** Multi-value data def (`'h', 'e'`) packs into 16-bit word big-endian (0x6865) 48 + - **or1-asm.AC2.7 Success:** `@system pe=4, sm=1` pragma parsed into SystemConfig 49 + - **or1-asm.AC2.8 Success:** Placement qualifiers (`|pe0`) on inst_def populate IRNode.pe 50 + - **or1-asm.AC2.9 Edge:** Instruction with named args (`&serial <| ior, dest=0x45`) preserves arg values in IRNode 51 + 52 + ### or1-asm.AC3: Lower Pass — Scoping 53 + - **or1-asm.AC3.1 Success:** &labels inside `$func` are qualified as `$func.&label` 54 + - **or1-asm.AC3.2 Success:** @nodes remain global (no function prefix) 55 + - **or1-asm.AC3.3 Success:** Top-level &labels (outside any function) are unqualified 56 + - **or1-asm.AC3.4 Success:** Two functions can each define `&add` without collision 57 + - **or1-asm.AC3.5 Failure:** Defining a reserved name (`@system`) as a node produces error with source location 58 + - **or1-asm.AC3.6 Failure:** Duplicate &label within same function scope produces error 59 + - **or1-asm.AC3.7 Success:** `$func |> { ... }` creates a FUNCTION IRRegion with the function body as a nested IRGraph 60 + - **or1-asm.AC3.8 Success:** Location directive (`@section|sm0`) creates a LOCATION IRRegion containing subsequent statements until the next region boundary 61 + 62 + ### or1-asm.AC4: Name Resolution 63 + - **or1-asm.AC4.1 Success:** All edge references in a valid program resolve to existing nodes 64 + - **or1-asm.AC4.2 Success:** Cross-function wiring via @nodes resolves correctly 65 + - **or1-asm.AC4.3 Failure:** Reference to undefined &label produces error with source context and "did you mean" suggestion 66 + - **or1-asm.AC4.4 Failure:** Reference to &label in different function scope produces scope violation error identifying the label's actual scope 67 + - **or1-asm.AC4.5 Failure:** "Did you mean" suggestion uses Levenshtein distance against in-scope names 68 + 69 + ### or1-asm.AC5: Placement 70 + - **or1-asm.AC5.1 Success:** All nodes with explicit `|peN` placements are accepted when PE exists 71 + - **or1-asm.AC5.2 Failure:** Node placed on nonexistent PE (e.g., `|pe9` when system has 4 PEs) produces error 72 + - **or1-asm.AC5.3 Failure:** Node with no placement and auto-placement disabled produces error identifying the unplaced node 73 + 74 + ### or1-asm.AC6: Resource Allocation 75 + - **or1-asm.AC6.1 Success:** Dyadic instructions are assigned IRAM offsets starting at 0, packed contiguously 76 + - **or1-asm.AC6.2 Success:** Monadic/SM instructions are assigned IRAM offsets above the dyadic range 77 + - **or1-asm.AC6.3 Success:** Each function body on a PE gets a distinct context slot 78 + - **or1-asm.AC6.4 Success:** All NameRef destinations resolve to ResolvedDest with correct Addr (pe, offset, port) 79 + - **or1-asm.AC6.5 Success:** Local edges (same PE) produce Addr with dest PE = source PE 80 + - **or1-asm.AC6.6 Success:** Cross-PE edges produce Addr with dest PE = target PE 81 + - **or1-asm.AC6.7 Failure:** IRAM overflow produces error listing all nodes on the PE and available capacity 82 + - **or1-asm.AC6.8 Failure:** Context slot overflow produces error listing function bodies on the PE 83 + 84 + ### or1-asm.AC7: Emulator ROUTE_SET 85 + - **or1-asm.AC7.1 Success:** ROUTE_SET CfgToken with PE and SM ID lists is accepted by PE without warning 86 + - **or1-asm.AC7.2 Success:** After ROUTE_SET, PE can route to listed PE IDs 87 + - **or1-asm.AC7.3 Success:** After ROUTE_SET, PE can route to listed SM IDs 88 + - **or1-asm.AC7.4 Failure:** After ROUTE_SET, routing to unlisted PE ID raises KeyError 89 + - **or1-asm.AC7.5 Failure:** After ROUTE_SET, routing to unlisted SM ID raises KeyError 90 + - **or1-asm.AC7.6 Success:** PEConfig with pe_routes/sm_routes fields restricts topology in build_topology() 91 + - **or1-asm.AC7.7 Success:** PEConfig with None routes (default) preserves full-mesh behaviour — all existing emulator tests pass unchanged 92 + 93 + ### or1-asm.AC8: Codegen 94 + - **or1-asm.AC8.1 Success:** Direct mode produces valid PEConfig with correct IRAM contents (ALUInst/SMInst objects at assigned offsets) 95 + - **or1-asm.AC8.2 Success:** Direct mode produces valid SMConfig with initial cell values from data_defs 96 + - **or1-asm.AC8.3 Success:** Direct mode produces seed MonadTokens for const nodes with no incoming edges 97 + - **or1-asm.AC8.4 Success:** Direct mode PEConfig includes route restrictions matching edge analysis 98 + - **or1-asm.AC8.5 Success:** Token stream mode emits SM init tokens before ROUTE_SET tokens 99 + - **or1-asm.AC8.6 Success:** Token stream mode emits ROUTE_SET tokens before LOAD_INST tokens 100 + - **or1-asm.AC8.7 Success:** Token stream mode emits LOAD_INST tokens before seed tokens 101 + - **or1-asm.AC8.8 Success:** Token stream mode produces valid tokens consumable by the emulator 102 + - **or1-asm.AC8.9 Edge:** Program with no data_defs produces empty SM init section (no SMConfig / no SM tokens) 103 + - **or1-asm.AC8.10 Edge:** Program using single PE produces ROUTE_SET with only self-routes 104 + 105 + ### or1-asm.AC9: End-to-End 106 + - **or1-asm.AC9.1 Success:** CONST→ADD chain: two const nodes feed an add node, correct sum appears in output 107 + - **or1-asm.AC9.2 Success:** SM round-trip: write to SM cell, read back via deferred read, correct data returns 108 + - **or1-asm.AC9.3 Success:** Cross-PE routing: source node on PE0, dest node on PE1, token arrives correctly 109 + - **or1-asm.AC9.4 Success:** SWITCH routing: branch node routes data token to taken side, trigger to not-taken 110 + - **or1-asm.AC9.5 Success:** Both output modes (direct and token stream) produce identical execution results for same program 111 + 112 + ### or1-asm.AC10: Auto-Placement 113 + - **or1-asm.AC10.1 Success:** Unplaced nodes are assigned to PEs without exceeding IRAM or context slot limits 114 + - **or1-asm.AC10.2 Success:** Explicitly placed nodes are not moved by auto-placement 115 + - **or1-asm.AC10.3 Success:** Connected nodes prefer co-location on same PE (locality heuristic) 116 + - **or1-asm.AC10.4 Failure:** Program too large for available PEs produces error with per-PE utilization breakdown 117 + - **or1-asm.AC10.5 Success:** Auto-placed program assembles and executes correctly end-to-end 118 + 119 + ### or1-asm.AC11: Serialization (IRGraph → dfasm) 120 + - **or1-asm.AC11.1 Success:** Fully resolved IRGraph serializes to valid dfasm source that re-parses without error 121 + - **or1-asm.AC11.2 Success:** Round-trip (parse → lower → resolve → place → allocate → serialize → parse → lower) produces structurally equivalent IRGraph 122 + - **or1-asm.AC11.3 Success:** Serialized output includes PE placement qualifiers on all nodes 123 + - **or1-asm.AC11.4 Success:** Serialized output preserves function scoping structure ($func |> { ... }) 124 + - **or1-asm.AC11.5 Success:** Serialized output includes data_def entries with SM placement and cell addresses 125 + - **or1-asm.AC11.6 Edge:** Anonymous nodes from inline edge desugaring serialize as named inst_def + plain_edge (not back to inline syntax) 126 + - **or1-asm.AC11.7 Success:** FUNCTION regions serialize as `$name |> { ...body... }` with unqualified &label names inside 127 + - **or1-asm.AC11.8 Success:** LOCATION regions serialize as bare directive followed by body contents 128 + 129 + ## Glossary 130 + 131 + - **Dataflow architecture**: A computing model where instruction execution is triggered by token arrival rather than sequential program counter advancement. Instructions fire when all required input tokens are present. 132 + - **PE (Processing Element)**: The fundamental compute unit in OR1. Each PE contains instruction RAM (IRAM), a matching store for pairing dyadic operands, an ALU, and routing logic. 133 + - **SM (Structure Memory)**: Memory units with I-structure semantics — single-assignment cells that support deferred reads. A read to an empty cell blocks until a write arrives. 134 + - **Dyadic instruction**: An instruction requiring two input operands (e.g., ADD, SUB, comparison ops). Must be stored in low IRAM offsets because the offset doubles as the matching store index. 135 + - **Monadic instruction**: An instruction requiring one input operand (e.g., INC, DEC, NOT, CONST). 136 + - **IRAM**: Instruction RAM within each PE. Stores ALUInst and SMInst objects. Limited capacity requires careful allocation. 137 + - **Context slot**: A virtualization mechanism in the PE matching store. Each function body executing on a PE requires a dedicated context slot to isolate its dataflow state. 138 + - **Matching store**: A 2D array within the PE where dyadic tokens wait for their partner. Indexed by [context][offset]. The first token stores its data/port; the second triggers instruction execution. 139 + - **SimPy**: A discrete event simulation library for Python. The emulator uses SimPy processes and stores to model token flow through the dataflow network. 140 + - **Lark**: An Earley parser library for Python. Used to parse dfasm source into a concrete syntax tree before lowering to IRGraph. 141 + - **Frozen dataclass**: A Python dataclass with `frozen=True`, making instances immutable after construction. Used throughout the codebase for IR nodes, tokens, and configurations. 142 + - **Port.L / Port.R**: Enumeration distinguishing left and right input ports on dyadic instructions. Determines operand ordering in ALU operations. 143 + - **CST (Concrete Syntax Tree)**: The parse tree produced by Lark, preserving all syntactic details including whitespace and grammar structure. 144 + - **&label**: Function-scoped symbolic name for an instruction node. Qualified during lowering (e.g., `&add` in `$main` becomes `$main.&add`). 145 + - **@node**: Global symbolic name for an instruction node or data cell. Visible across all functions, used for cross-function wiring. 146 + - **$function**: Function scope delimiter. Groups instruction nodes and provides namespace isolation for &labels. 147 + - **IRRegion**: A tagged container in the graph IR that preserves source-level grouping (function definitions and location directive scopes) for round-trip serialization. Each region wraps a nested IRGraph. 148 + - **ROUTE_SET**: A configuration operation that restricts a PE's routing table to only the PEs and SMs it actually needs to send tokens to (versus full-mesh connectivity). 149 + - **LOAD_INST**: A configuration operation that bulk-loads instruction memory into a PE from a list of ALUInst/SMInst objects. 150 + - **Deferred read**: An I-structure operation where a READ to an empty SM cell registers a continuation. When a WRITE arrives, the read completes and sends the result back via the registered return route. 151 + - **Levenshtein distance**: A string similarity metric measuring the minimum number of single-character edits to transform one string into another. Used for "did you mean" suggestions. 152 + - **Greedy bin-packing**: An allocation heuristic that assigns items (unplaced nodes) to bins (PEs) one at a time, choosing the best fit for each item without backtracking. 153 + - **Round-trip**: The process of parsing source to IR, transforming it, then serializing back to source and re-parsing. Used to validate that serialization preserves semantic equivalence. 154 + 155 + ## Architecture 156 + 157 + ### Pipeline Overview 158 + 159 + The assembler is a multi-pass pipeline where each pass is a pure function `IRGraph → IRGraph`. Immutable intermediate graphs enable backtracking for future placement optimization without requiring undo logic. 160 + 161 + ``` 162 + Source (.dfasm) 163 + │ 164 + ▼ 165 + Parse ─── Lark Earley parser, existing grammar (dfasm.lark) 166 + │ Produces: Lark Tree (concrete syntax tree) 167 + ▼ 168 + Lower ─── Lark Transformer (CST → IRGraph) 169 + │ - Wrap $func bodies in FUNCTION regions, location directive scopes in LOCATION regions 170 + │ - Desugar inline edges (strong/weak) into anonymous nodes + plain edges 171 + │ - Qualify &label names with function scope ($func.&label) 172 + │ - Map opcode mnemonics to existing enums (ALUOp, MemOp) 173 + │ - Extract data definitions and system config pragmas 174 + │ - Validate grammar-level constraints (known opcodes, valid syntax) 175 + │ Produces: IRGraph (unresolved names, no placement, regions preserved) 176 + ▼ 177 + Resolve ── Name resolution pass 178 + │ - Resolve NameRef → IRNode references on all edges 179 + │ - Validate all references exist within scope 180 + │ - Detect duplicate definitions, scope violations 181 + │ Produces: IRGraph (resolved names, no placement) 182 + ▼ 183 + Place ──── Placement pass 184 + │ - Phase 1: validate user-provided |peN placements 185 + │ - Later: auto-place unplaced nodes via greedy bin-packing 186 + │ - Validate PE/SM resource budgets are feasible 187 + │ Produces: IRGraph (all nodes placed) 188 + ▼ 189 + Allocate ─ Resource allocation pass 190 + │ - Assign IRAM offsets per PE (dyadic packed at low offsets) 191 + │ - Assign context slots per PE (one per function body) 192 + │ - Resolve all NameRef destinations to Addr (NameRef → ResolvedDest) 193 + │ - Classify edges as local vs cross-PE 194 + │ Produces: IRGraph (fully resolved, all destinations are ResolvedDest) 195 + ▼ 196 + Codegen ── Output generation 197 + - Direct mode: PEConfig/SMConfig lists + seed tokens 198 + - Token stream mode: SM init → ROUTE_SET → LOAD_INST → seeds 199 + - Compute per-PE route restrictions from edge analysis 200 + ``` 201 + 202 + ### Graph IR 203 + 204 + The IR represents the program as a graph of instruction nodes connected by token-routing edges, organized into regions that preserve source-level structure for round-trip serialization. 205 + 206 + **`IRNode`** — One per instruction in the program. Fields: 207 + - `name: str` — Qualified name (`$func.&label` or `@global`) 208 + - `opcode: ALUOp | MemOp` — From existing enum hierarchy in `cm_inst.py` 209 + - `dest_l: Optional[NameRef | ResolvedDest]` — Left destination, progressively resolved 210 + - `dest_r: Optional[NameRef | ResolvedDest]` — Right destination 211 + - `const: Optional[int]` — Immediate value (for CONST, shifts, SM cell addresses) 212 + - `pe: Optional[int]` — PE placement (None until placed) 213 + - `iram_offset: Optional[int]` — Assigned during allocation 214 + - `ctx: Optional[int]` — Context slot, assigned during allocation 215 + - `loc: SourceLoc` — Line/column from parse tree for error reporting 216 + - `sm_inst: Optional[SMInst]` — For SM operations, carries SM-specific fields (sm_id, ret addr) 217 + 218 + **`IREdge`** — One per wiring connection. Fields: 219 + - `source: str` — Source node qualified name 220 + - `dest: str` — Destination node qualified name 221 + - `port: Port` — `Port.L` or `Port.R` 222 + - `loc: SourceLoc` — Source location for error reporting 223 + 224 + **`RegionKind`** — Enum: `FUNCTION`, `LOCATION` 225 + 226 + **`IRRegion`** — A scoped container that groups statements under a tag. Used to preserve function definitions and location directive scopes in the IR, enabling round-trip serialization. Fields: 227 + - `tag: str` — The region identifier (`$fib` for functions, `@data_section|sm0` for location directives) 228 + - `kind: RegionKind` — `FUNCTION` or `LOCATION` 229 + - `body: IRGraph` — Nested sub-graph containing the region's nodes, edges, data_defs 230 + - `loc: SourceLoc` — Source location of the region-opening statement 231 + 232 + FUNCTION regions serialize as `$name |> { ...body... }`. LOCATION regions serialize as a bare directive (`@name|placement`) followed by the body's contents. A region's scope ends at the next region-opening statement or end of the enclosing scope. 233 + 234 + **`IRGraph`** — Container for the entire program (or a region body). Fields: 235 + - `nodes: dict[str, IRNode]` — Nodes keyed by qualified name 236 + - `edges: list[IREdge]` — All wiring connections 237 + - `regions: list[IRRegion]` — Function definitions and location directive scopes (ordered) 238 + - `data_defs: list[IRDataDef]` — SM cell initial values 239 + - `system: Optional[SystemConfig]` — PE/SM counts from `@system` pragma (top-level only) 240 + - `errors: list[AssemblyError]` — Accumulated errors from any pass 241 + 242 + All IR types are frozen dataclasses. Each pass returns a new `IRGraph` with new/updated nodes; unchanged nodes are shared by reference. Passes walk into region bodies recursively when processing nodes and edges. 243 + 244 + ### Destination Sum Type 245 + 246 + Destinations on IR nodes use a sum type that narrows as passes run: 247 + 248 + **`NameRef`** — Unresolved symbolic reference: 249 + - `name: str` — Target node name (e.g., `$main.&add`) 250 + - `port: Optional[Port]` — Target port 251 + 252 + **`ResolvedDest`** — Fully resolved, retaining symbolic name for round-trip serialization: 253 + - `name: str` — Original symbolic name 254 + - `addr: Addr` — Concrete address (`Addr(a=offset, port=port, pe=pe_id)`) 255 + 256 + After the Allocate pass, all destinations are `ResolvedDest`. Codegen extracts `.addr` to construct `ALUInst`/`SMInst`. Serialization back to dfasm extracts `.name`. 257 + 258 + ### Name Resolution & Scoping 259 + 260 + **Scoping rules:** 261 + - `&label` references are scoped to their enclosing `$function`. Two functions can each have `&add` without conflict. 262 + - `@node` references are global. Visible everywhere, used for cross-function wiring. 263 + - Top-level `&labels` (outside any function) live in a root scope. 264 + - Reserved names (`@system`, `@io`, `@debug`) are rejected as user definitions. 265 + 266 + **Qualified names:** During the Lower pass, &labels are prefixed with their function scope: 267 + - `&add` inside `$fib` → `$fib.&add` 268 + - `&add` at top level → `&add` 269 + - `@counter` → `@counter` (global, no qualification) 270 + 271 + The node dict in `IRGraph` uses qualified names as keys. Name resolution is a flat dict lookup — no scope chain walking needed. Nodes inside FUNCTION regions are stored in the region's body sub-graph but are also accessible via their qualified names in the top-level `nodes` dict (flattened view for resolution; region structure preserved for serialization). 272 + 273 + **Inline edge desugaring (Lower pass):** 274 + - Strong edge `add &a, &b |> &c, &d` creates anonymous node `&__anon_N` with opcode `add`, wires `&a → anon:L`, `&b → anon:R`, `anon → &c`, `anon → &d`. 275 + - Weak edge `&c, &d sub <| &a, &b` produces the same IR (syntax reads outputs-first, same semantics). 276 + - Anonymous nodes receive function-scope qualification like any other &label. 277 + 278 + **Location directive scoping (Lower pass):** 279 + - A location directive (`@data_section|sm0`) opens a LOCATION region. Subsequent statements are grouped into the region until the next region-opening statement (another location directive, a function definition, or end of enclosing scope). 280 + - FUNCTION regions are created from `$func |> { ... }` blocks. The braces provide explicit boundaries. 281 + 282 + ### Resource Allocation 283 + 284 + **IRAM offset assignment (per PE):** 285 + 286 + Per the PE hardware design, dyadic instructions must be packed at low IRAM offsets because the offset doubles as the matching store entry index. The allocator: 287 + 288 + 1. Collects all nodes placed on each PE 289 + 2. Partitions by arity: dyadic ops get offsets 0..N-1, monadic/SM ops get N..M-1 290 + 3. Validates total does not exceed PE IRAM capacity 291 + 4. Reports detailed overflow errors listing every node on the PE and suggesting redistribution 292 + 293 + Arity is derived from opcode: `ArithOp.INC`, `ArithOp.DEC`, `LogicOp.NOT`, shift ops, `RoutingOp.PASS`, `RoutingOp.CONST`, `RoutingOp.FREE` are monadic. SM instructions follow their operand mapping (`cm_inst.py` docstring). Everything else is dyadic. 294 + 295 + **Context slot assignment:** 296 + 297 + One context slot per function body per PE. If PE0 has nodes from `$main` and `$helper`: 298 + - `$main` nodes on PE0 → ctx=0 299 + - `$helper` nodes on PE0 → ctx=1 300 + - Top-level nodes share ctx=0 301 + 302 + Overflow produces an error: "PE0 has 5 function bodies but only 4 context slots." 303 + 304 + ### ROUTE_SET Implementation 305 + 306 + **CfgToken.data format for ROUTE_SET:** 307 + 308 + ```python 309 + # CfgToken(target=pe_id, op=CfgOp.ROUTE_SET, addr=None, 310 + # data={"pe_routes": [0, 2, 3], "sm_routes": [0]}) 311 + ``` 312 + 313 + The data field carries two lists: PE IDs and SM IDs that this PE is allowed to route to. The emulator's `_handle_cfg` for ROUTE_SET filters the existing route_table and sm_routes to only the listed IDs. Subsequent attempts to route to an unlisted destination raise `KeyError`. 314 + 315 + **Route table derivation:** The assembler computes each PE's required routes by analyzing edges in the allocated graph. For each PE, collect the set of destination PE IDs and SM IDs from all its outgoing edges and SM instructions. This becomes the ROUTE_SET data. 316 + 317 + **PEConfig extension:** `PEConfig` gains two optional fields: 318 + - `pe_routes: Optional[set[int]]` — Allowed PE destinations. `None` = full-mesh (backwards compatible). 319 + - `sm_routes: Optional[set[int]]` — Allowed SM destinations. `None` = full-mesh. 320 + 321 + `build_topology()` respects these when wiring route tables. 322 + 323 + ### Codegen 324 + 325 + **Direct mode** (`assemble()` → `AssemblyResult`): 326 + - One `PEConfig` per PE with populated IRAM, context slot count, IRAM offset count, and route restrictions 327 + - One `SMConfig` per SM with initial cell values from data definitions 328 + - List of seed `CMToken`s (monadic trigger tokens for `const` nodes) 329 + 330 + **Token stream mode** (`assemble_to_tokens()` → `list[Token]`): 331 + 332 + Ordered bootstrap sequence: 333 + 1. **SM init** — `SMToken(target=sm_id, op=MemOp.WRITE, ...)` per data definition 334 + 2. **ROUTE_SET** — One `CfgToken(op=CfgOp.ROUTE_SET, ...)` per PE 335 + 3. **LOAD_INST** — One `CfgToken(op=CfgOp.LOAD_INST, data=[...])` per PE carrying the full IRAM 336 + 4. **Seed tokens** — `MonadToken` triggers for `const` instruction nodes (auto-detected: nodes with no incoming edges and `RoutingOp.CONST` opcode) 337 + 338 + ### Serialization (IRGraph → dfasm) 339 + 340 + `asm/serialize.py` converts an IRGraph back to valid dfasm source text. This enables: 341 + - **Round-trip testing:** parse → IR → serialize → parse → compare 342 + - **Debugging:** inspect auto-placement results as human-readable dfasm 343 + - **Lowered output:** emit a "fully specified" dfasm file from a partially-specified input 344 + 345 + The serializer walks the IRGraph's region list in order: 346 + - **FUNCTION regions** emit `$name |> {` followed by the body's nodes/edges, then `}`. Nodes inside use unqualified &label names (the function scope prefix is stripped since the enclosing `$func |> { }` block implies it). 347 + - **LOCATION regions** emit the bare directive (e.g., `@data_section|sm0`) followed by the body's data definitions and other statements. 348 + - **Top-level statements** (nodes/edges/data_defs not inside any region) are emitted directly. 349 + 350 + Within each scope, the serializer emits inst_def + plain_edge form (not inline edges), with explicit PE placement qualifiers on all nodes. Anonymous nodes from inline edge desugaring get their generated names preserved. Data definitions are emitted with SM placement and cell addresses. 351 + 352 + ### Auto-Placement (Later Phase) 353 + 354 + Naive greedy bin-packing strategy: 355 + 356 + 1. Honour explicitly placed nodes (`|peN` annotations) 357 + 2. Walk unplaced nodes in graph order 358 + 3. For each: prefer the PE where the majority of its connected neighbours already live (locality heuristic) 359 + 4. Tie-break by remaining IRAM capacity (most room wins) 360 + 5. Track both IRAM slots and matching store entries (dyadic nodes cost both) 361 + 6. Track context slot budget per PE (each new function body costs a slot) 362 + 7. If no PE has room → error with per-PE utilization breakdown 363 + 364 + **System topology:** Declared via `@system` pragma in the source file: 365 + 366 + ``` 367 + @system pe=4, sm=1 368 + ``` 369 + 370 + If omitted, inferred from max PE/SM ID referenced in explicit placements. Future: reference an external machine description file for heterogeneous configurations. 371 + 372 + ### Error Handling 373 + 374 + **Error accumulation:** Each pass collects errors rather than failing on first. The assembler reports all errors from a single compilation, not one at a time. Errors from earlier passes may prevent later passes from running (e.g., unresolved names block allocation). 375 + 376 + **`AssemblyError` structure:** 377 + - `loc: SourceLoc` — Line, column, optional end position 378 + - `category: ErrorCategory` — Enum: `PARSE`, `NAME`, `SCOPE`, `PLACEMENT`, `RESOURCE`, `ARITY`, `PORT`, `UNREACHABLE` 379 + - `message: str` — Human-readable description 380 + - `suggestions: list[str]` — "Did you mean..." or "Consider moving..." 381 + - `context_lines: list[str]` — Source lines around the error for display 382 + 383 + **Source context display:** Lark's `propagate_positions=True` provides line/column info on every parse tree node. Each `IRNode` and `IREdge` carries a `SourceLoc` from its parse origin. Error formatting shows the relevant source line with a caret pointing to the error position, Rust-style. 384 + 385 + **"Did you mean" suggestions:** For name resolution errors, compute Levenshtein distance against names in scope and suggest close matches. 386 + 387 + ### Grammar Updates 388 + 389 + The existing `dfasm.lark` OPCODE terminal needs SM memory operations added: 390 + 391 + ``` 392 + OPCODE.2: ... existing ops ... 393 + | "read" | "write" | "clear" | "alloc" | "free_sm" 394 + | "rd_inc" | "rd_dec" | "cmp_sw" 395 + ``` 396 + 397 + The `opcodes.py` module maintains the mnemonic ↔ enum mapping table, including both ALU ops and SM ops. 398 + 399 + ## Existing Patterns 400 + 401 + The emulator codebase (`emu/`) establishes patterns this design follows: 402 + 403 + - **Frozen dataclasses for data types.** All token types (`tokens.py`), instruction types (`cm_inst.py`), and config types (`emu/types.py`) use `@dataclass(frozen=True)`. The assembler IR types follow the same convention. 404 + - **IntEnum hierarchies for opcodes.** `ALUOp` with `ArithOp`/`LogicOp`/`RoutingOp` subclasses, `MemOp`, `CfgOp`, `Port`. The assembler reuses these directly — no parallel enum hierarchy. 405 + - **Root-level modules for specification, `emu/` for simulation.** `cm_inst.py`, `tokens.py`, `sm_mod.py` define the ISA. The `emu/` package imports from them. The new `asm/` package follows the same layering — it imports from root-level ISA modules but root-level modules never import from `asm/`. 406 + - **pytest + hypothesis for testing.** Property-based tests with `@given()` strategies defined in `tests/conftest.py`. The assembler test suite follows the same structure. 407 + - **Lark Earley parser.** The grammar (`dfasm.lark`) and test suite (`tests/test_parser.py`) already exist with 38 passing tests. The assembler builds on this foundation. 408 + 409 + **New patterns introduced:** 410 + - **`asm/` package** for the assembler pipeline (no existing compiler/assembler package to follow). 411 + - **Immutable pass pipeline** (`IRGraph → IRGraph`). No existing pattern in the emulator (which mutates state in-place via SimPy processes). This divergence is intentional — assembler passes need backtracking support for future placement optimization. 412 + - **Structured error accumulation.** The emulator uses `logger.warning()` for error cases. The assembler introduces `AssemblyError` with source locations and suggestions for a compiler-quality error experience. 413 + 414 + ## Implementation Phases 415 + 416 +  417 + ### Phase 1: Grammar Updates & Opcode Mapping 418 + 419 + **Goal:** Extend the grammar with SM memory operations and build the opcode mnemonic ↔ enum mapping table that all later phases depend on. 420 + 421 + **Components:** 422 + - `dfasm.lark` — Add SM operation mnemonics to OPCODE terminal 423 + - `asm/opcodes.py` — Mnemonic string ↔ `ALUOp`/`MemOp` mapping, arity table (monadic vs dyadic per opcode) 424 + - `tests/test_parser.py` — New tests for SM operation syntax 425 + - `tests/test_opcodes.py` — Mapping round-trip and arity correctness tests 426 + 427 + **Dependencies:** None (first phase) 428 + 429 + **Done when:** All existing parser tests still pass. New SM op syntax parses. Opcode mapping covers all v0 ops with correct arity classification. Tests pass for `or1-asm.AC1.1`, `or1-asm.AC1.2`. 430 +  431 + 432 +  433 + ### Phase 2: IR Types & Lower Pass 434 + 435 + **Goal:** Define the Graph IR types and implement the Lark Transformer that converts the parse tree into an IRGraph. 436 + 437 + **Components:** 438 + - `asm/ir.py` — `IRNode`, `IREdge`, `IRRegion`, `RegionKind`, `IRGraph`, `IRDataDef`, `NameRef`, `ResolvedDest`, `SystemConfig`, `SourceLoc` frozen dataclasses 439 + - `asm/errors.py` — `AssemblyError`, `ErrorCategory` enum, source context formatting 440 + - `asm/lower.py` — Lark Transformer: CST → IRGraph. Handles region creation (FUNCTION for `$func` blocks, LOCATION for directives), function scope qualification, inline edge desugaring, data def extraction, `@system` pragma parsing. 441 + - `asm/__init__.py` — Package init 442 + - `tests/test_lower.py` — Lower pass tests: scope qualification, inline edge desugaring, data def extraction, error cases 443 + 444 + **Dependencies:** Phase 1 (opcode mapping) 445 + 446 + **Done when:** Parse tree for any valid dfasm program converts to a well-formed IRGraph. Inline edges desugar to anonymous nodes. &labels are function-scoped. @nodes are global. Reserved names are rejected. Tests pass for `or1-asm.AC2.*`, `or1-asm.AC3.*`. 447 +  448 + 449 +  450 + ### Phase 3: Name Resolution 451 + 452 + **Goal:** Resolve all symbolic references in the IRGraph to concrete node connections. 453 + 454 + **Components:** 455 + - `asm/resolve.py` — Name resolution pass: walks edges, resolves NameRef source/dest to IRNode objects, validates references exist in scope, detects duplicates, generates "did you mean" suggestions via Levenshtein distance 456 + - `tests/test_resolve.py` — Resolution tests: valid programs resolve, scope violations caught, duplicate names caught, suggestion quality 457 + 458 + **Dependencies:** Phase 2 (IR types and Lower pass) 459 + 460 + **Done when:** Fully specified programs have all edge references resolved. Scope violations, missing names, and duplicates produce clear errors with source context and suggestions. Tests pass for `or1-asm.AC4.*`. 461 +  462 + 463 +  464 + ### Phase 4: Placement Validation & Allocation 465 + 466 + **Goal:** Validate user-provided PE placements and assign IRAM offsets and context slots. 467 + 468 + **Components:** 469 + - `asm/place.py` — Placement validation pass: verify all nodes have PE assignments, validate PE existence against SystemConfig, detect unplaced nodes 470 + - `asm/allocate.py` — Resource allocation: IRAM offset assignment (dyadic-first packing), context slot assignment (per function body per PE), destination resolution (NameRef → ResolvedDest with concrete Addr) 471 + - `tests/test_place.py` — Placement validation tests: valid placements accepted, missing placements caught, nonexistent PE references caught 472 + - `tests/test_allocate.py` — Allocation tests: dyadic-first IRAM packing, context slot assignment, overflow detection, destination resolution correctness 473 + 474 + **Dependencies:** Phase 3 (resolved names) 475 + 476 + **Done when:** Fully specified programs get deterministic IRAM offsets and context slots. All destinations are ResolvedDest after allocation. Resource overflow produces actionable errors. Tests pass for `or1-asm.AC5.*`, `or1-asm.AC6.*`. 477 +  478 + 479 +  480 + ### Phase 5: Emulator ROUTE_SET Support 481 + 482 + **Goal:** Implement CfgOp.ROUTE_SET in the emulator and extend PEConfig with route restriction fields. 483 + 484 + **Components:** 485 + - `tokens.py` — Document ROUTE_SET data format (dict with `pe_routes` and `sm_routes` keys) 486 + - `emu/pe.py` — Implement `_handle_cfg` for ROUTE_SET: filter `route_table` and `sm_routes` to listed IDs 487 + - `emu/types.py` — Add `pe_routes: Optional[set[int]]` and `sm_routes: Optional[set[int]]` to `PEConfig` 488 + - `emu/network.py` — `build_topology()` respects PEConfig route restrictions when wiring 489 + - `tests/test_pe.py` — ROUTE_SET tests: route restriction applied, unconfigured destination raises error 490 + - `tests/test_network.py` — Topology tests with restricted routes 491 + 492 + **Dependencies:** None (can be done in parallel with Phases 1-4, but listed here for logical flow) 493 + 494 + **Done when:** ROUTE_SET tokens restrict PE routing. PEConfig route fields are respected by build_topology(). Routing to unconfigured destination fails clearly. All existing emulator tests still pass. Tests pass for `or1-asm.AC7.*`. 495 +  496 + 497 +  498 + ### Phase 6: Codegen (Both Modes) 499 + 500 + **Goal:** Generate emulator-ready output from a fully resolved and allocated IRGraph. 501 + 502 + **Components:** 503 + - `asm/codegen.py` — Two codegen paths: 504 + - `generate_direct()`: IRGraph → AssemblyResult (PEConfig/SMConfig lists + seed tokens + route restrictions) 505 + - `generate_tokens()`: IRGraph → ordered token list (SM init → ROUTE_SET → LOAD_INST → seeds) 506 + - Route table computation from edge analysis (which PEs each PE sends to) 507 + - Seed token detection (const nodes with no incoming edges) 508 + - `asm/serialize.py` — IRGraph → dfasm source text. Emits inst_def + plain_edge form with full placement qualifiers. 509 + - `asm/__init__.py` — Public API: `assemble()`, `assemble_to_tokens()`, `serialize()` 510 + - `tests/test_codegen.py` — Codegen tests: correct PEConfig/SMConfig generation, token stream ordering, route restriction computation, seed token detection 511 + - `tests/test_serialize.py` — Serialization tests: round-trip fidelity, placement qualifiers, function scoping, data defs 512 + 513 + **Dependencies:** Phase 4 (fully resolved IRGraph), Phase 5 (ROUTE_SET support in emulator) 514 + 515 + **Done when:** Both output modes produce valid emulator input. Token stream follows hardware bootstrap ordering. Route restrictions are correctly computed. Seed tokens are auto-detected. Serialized dfasm round-trips correctly. Tests pass for `or1-asm.AC8.*`, `or1-asm.AC11.*`. 516 +  517 + 518 +  519 + ### Phase 7: End-to-End Integration & Auto-Placement 520 + 521 + **Goal:** End-to-end assemble → emulate tests for reference programs, plus naive auto-placement. 522 + 523 + **Components:** 524 + - `asm/place.py` — Auto-placement: greedy bin-packing with locality heuristic, respects explicit annotations, reports utilization on failure 525 + - `tests/test_e2e.py` — End-to-end tests: assemble a dfasm program, run it through the emulator, verify correct output. Reference programs: CONST→ADD chain, SM round-trip, SWITCH routing, cross-PE routing 526 + - `tests/test_autoplacement.py` — Auto-placement tests: nodes distributed across PEs, explicit placements honoured, resource limits respected, locality preference verified 527 + 528 + **Dependencies:** Phase 6 (complete assembler pipeline) 529 + 530 + **Done when:** Reference programs assemble and execute correctly end-to-end. Auto-placement produces valid (if suboptimal) placements. Tests pass for `or1-asm.AC9.*`, `or1-asm.AC10.*`. 531 +  532 + 533 + ## Additional Considerations 534 + 535 + **Round-trip fidelity:** The IR preserves both symbolic names (in `ResolvedDest`) and structural grouping (in `IRRegion`) to enable serialization back to valid dfasm. The `asm/serialize.py` module (Phase 6) reconstructs `$func |> { ... }` blocks and location directive scopes from the region tree. This is critical for inspecting auto-placement results and for the round-trip test harness. 536 + 537 + **Machine description evolution:** The `@system pe=4, sm=1` pragma is a minimal starting point. Future iterations may reference external machine description files for heterogeneous configurations (PEs with different IRAM sizes, SMs with different cell counts, memory-mapped I/O regions). The `SystemConfig` type in the IR is the extension point — its fields grow as the machine description language grows. 538 + 539 + **Implementation scoping:** This design has 7 phases. Phase 5 (ROUTE_SET) is independent of the assembler pipeline and can be implemented in parallel with Phases 1-4.

+158

docs/implementation-plans/2026-02-22-or1-asm/phase_01.md

··· 1 + # OR1 Assembler — Phase 1: Grammar Updates & Opcode Mapping 2 + 3 + **Goal:** Extend the grammar with SM memory operations and build the opcode mnemonic ↔ enum mapping table that all later phases depend on. 4 + 5 + **Architecture:** Add SM op mnemonics to the existing Lark Earley grammar's OPCODE terminal, then create an `asm/opcodes.py` module that maps every mnemonic string to its `ALUOp`/`MemOp` enum value and classifies each opcode as monadic or dyadic. 6 + 7 + **Tech Stack:** Python 3.12, Lark (Earley parser), pytest + hypothesis 8 + 9 + **Scope:** 7 phases from original design (this is phase 1 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC1: Grammar & Opcode Mapping 20 + - **or1-asm.AC1.1 Success:** All existing ALU opcodes (`add`, `sub`, `inc`, `dec`, `shiftl`, `shiftr`, `ashiftr`, `and`, `or`, `xor`, `not`, `eq`, `lt`, `lte`, `gt`, `gte`, `breq`, `brgt`, `brge`, `brof`, `sweq`, `swgt`, `swge`, `swof`, `gate`, `sel`, `merge`, `pass`, `const`, `free`) parse and map to correct `ALUOp` enum values 21 + - **or1-asm.AC1.2 Success:** SM memory opcodes (`read`, `write`, `clear`, `alloc`, `rd_inc`, `rd_dec`, `cmp_sw`) parse and map to correct `MemOp` enum values 22 + - **or1-asm.AC1.3 Success:** Arity table correctly classifies all opcodes as monadic or dyadic 23 + - **or1-asm.AC1.4 Failure:** Unknown opcode in source produces parse error with source location 24 + 25 + --- 26 + 27 + ## Codebase Verification Findings 28 + 29 + - ✓ `dfasm.lark` exists with OPCODE terminal at lines 96–105. Already contains ALU, routing, I/O, and config ops. **Missing:** SM memory ops (read, write, clear, alloc, free_sm, rd_inc, rd_dec, cmp_sw). 30 + - ✓ `cm_inst.py` has `ALUOp` base with `ArithOp` (lines 13–20), `LogicOp` (lines 23–32), `RoutingOp` (lines 35–52) subclasses. 31 + - ✓ `tokens.py` has `MemOp` enum (lines 37–46) with values: READ, WRITE, ALLOC, FREE, CLEAR, RD_INC, RD_DEC, CMP_SW. 32 + - ✓ `tests/test_parser.py` has 18 tests (not 38 as design suggested) organized in 7 test classes. Parser fixture uses `Lark(parser="earley", propagate_positions=True)`. 33 + - ✓ `asm/` package does not exist yet. 34 + - ✗ Grammar has `brty`, `swty` opcodes but RoutingOp enum has no BRTY/SWTY values. The opcodes module must handle this — either map them or raise an error. Design AC1.1 does not list `brty`/`swty`, so the opcodes module should map only what the enum supports and leave these as parse-valid but assembly-invalid (caught in later passes). 35 + - ✗ Grammar has `ior`, `iow`, `iorw` but no corresponding enum. Same treatment — parse-valid, assembly-invalid until I/O is implemented. 36 + - ✗ Design says SM grammar should add `free_sm` to disambiguate from ALU `free`. The MemOp enum has `FREE` for SM free. 37 + - ✗ Grammar has no `system_pragma` rule for `@system pe=4, sm=1`. This directive is needed by every program that specifies hardware configuration. Must be added as a new statement type. 38 + 39 + --- 40 + 41 +  42 + 43 +  44 + ### Task 1: Add SM memory operation mnemonics to dfasm.lark grammar 45 + 46 + **Verifies:** or1-asm.AC1.2 (parse support), or1-asm.AC1.4 (unknown opcodes still fail at parse level) 47 + 48 + **Files:** 49 + - Modify: `dfasm.lark:96-105` (OPCODE terminal — add SM ops) 50 + - Modify: `dfasm.lark:4-12` (statement alternation and new `system_pragma` rule) 51 + - Test: `tests/test_parser.py` (add SM op and system pragma parse tests) 52 + 53 + **Implementation:** 54 + 55 + Two grammar changes: 56 + 57 + **1. SM memory ops:** Add SM memory operation mnemonics to the OPCODE terminal in `dfasm.lark`. The new mnemonics are: `read`, `write`, `clear`, `alloc`, `free_sm`, `rd_inc`, `rd_dec`, `cmp_sw`. Add them as a new line group after the existing config ops. 58 + 59 + Note: `free_sm` disambiguates from the ALU `free` opcode at the mnemonic level. Both are valid grammar tokens — the assembler's Lower pass (Phase 2) maps `free_sm` → `MemOp.FREE` and `free` → `RoutingOp.FREE`. 60 + 61 + **2. System pragma:** Add a `system_pragma` rule to the grammar for `@system pe=4, sm=1, iram=128, ctx=2`. This is a new statement type: 62 + 63 + ``` 64 + system_pragma: "@system" system_param ("," system_param)* 65 + system_param: IDENT "=" (DEC_LIT | HEX_LIT) 66 + ``` 67 + 68 + Add `system_pragma` to the `?statement` alternation. The Earley parser disambiguates `@system pe=4, sm=1` (system_pragma, which requires trailing `system_param` rules) from a bare `@system` (which would match `location_dir` via `qualified_ref`). Alternation ordering does not affect Earley disambiguation — the parser uses the grammar structure itself. 69 + 70 + **Testing:** 71 + 72 + Tests must verify: 73 + - or1-asm.AC1.2: Each SM memory opcode parses successfully in an `inst_def` context (e.g., `&cell <| read`) 74 + - or1-asm.AC1.4: An unknown opcode like `foobar` fails to parse 75 + - System pragma: `@system pe=4, sm=1` parses successfully. `@system pe=2, sm=1, iram=128, ctx=2` parses with all four parameters. 76 + 77 + Add a `TestSMOps` class and a `TestSystemPragma` class to `tests/test_parser.py` following the existing pattern (use `parser.parse(dedent(...))` fixture pattern from other test classes). Test each SM op in a minimal `inst_def`. 78 + 79 + Also add a test for unknown opcode parse failure using `pytest.raises(lark.exceptions.UnexpectedToken)` or similar Lark exception. 80 + 81 + **Verification:** 82 + ```bash 83 + python -m pytest tests/test_parser.py -v 84 + ``` 85 + Expected: All existing 18 parser tests pass + new SM op and system pragma tests pass. 86 + 87 + **Commit:** `feat(grammar): add SM memory operation mnemonics to OPCODE terminal` 88 + 89 +  90 + 91 +  92 + ### Task 2: Create asm/opcodes.py — mnemonic mapping and arity table 93 + 94 + **Verifies:** or1-asm.AC1.1, or1-asm.AC1.2, or1-asm.AC1.3 95 + 96 + **Files:** 97 + - Create: `asm/__init__.py` 98 + - Create: `asm/opcodes.py` 99 + - Create: `tests/test_opcodes.py` 100 + 101 + **Implementation:** 102 + 103 + Create the `asm/` package with `__init__.py` (empty for now) and `asm/opcodes.py`. 104 + 105 + `asm/opcodes.py` must provide: 106 + 107 + 1. **`MNEMONIC_TO_OP: dict[str, ALUOp | MemOp]`** — Maps every valid assembly mnemonic string to its enum value. Import `ArithOp`, `LogicOp`, `RoutingOp` from `cm_inst` and `MemOp` from `tokens`. 108 + 109 + Key mappings to get right: 110 + - `"add"` → `ArithOp.ADD`, `"sub"` → `ArithOp.SUB`, etc. 111 + - `"shiftl"` → `ArithOp.SHIFT_L` (note: mnemonic uses no underscore) 112 + - `"shiftr"` → `ArithOp.SHIFT_R` 113 + - `"ashiftr"` → `ArithOp.ASHFT_R` 114 + - `"not"` → `LogicOp.NOT`, `"eq"` → `LogicOp.EQ`, etc. 115 + - `"merge"` → `RoutingOp.MRGE` (mnemonic is `merge`, enum is `MRGE`) 116 + - `"sel"` → `RoutingOp.SEL` 117 + - `"free"` → `RoutingOp.FREE` (ALU free) 118 + - `"free_sm"` → `MemOp.FREE` (SM free) 119 + - `"read"` → `MemOp.READ`, `"write"` → `MemOp.WRITE`, etc. 120 + - `"rd_inc"` → `MemOp.RD_INC`, `"rd_dec"` → `MemOp.RD_DEC`, `"cmp_sw"` → `MemOp.CMP_SW` 121 + 122 + Do NOT include `ior`, `iow`, `iorw`, `load_inst`, `route_set`, `brty`, `swty` in this dict. They are parse-valid grammar tokens but have no assembly-level enum mapping yet. They will be caught as unsupported opcodes in the Lower pass (Phase 2). 123 + 124 + 2. **`OP_TO_MNEMONIC: dict[ALUOp | MemOp, str]`** — Reverse mapping for serialization. Built by inverting `MNEMONIC_TO_OP`. 125 + 126 + 3. **`MONADIC_OPS: frozenset[ALUOp | MemOp]`** — Set of opcodes that are **always** monadic (single input operand). Per the design and `cm_inst.py` docstrings: 127 + - `ArithOp.INC`, `ArithOp.DEC` 128 + - `ArithOp.SHIFT_L`, `ArithOp.SHIFT_R`, `ArithOp.ASHFT_R` (shift amount comes from `const`, not a second operand) 129 + - `LogicOp.NOT` 130 + - `RoutingOp.PASS`, `RoutingOp.CONST`, `RoutingOp.FREE` 131 + - `MemOp.READ`, `MemOp.ALLOC`, `MemOp.FREE`, `MemOp.CLEAR`, `MemOp.RD_INC`, `MemOp.RD_DEC` (always monadic SM ops) 132 + 133 + **NOT in `MONADIC_OPS`** (context-dependent or always dyadic): 134 + - `MemOp.WRITE` — monadic when `const` is set (cell_addr from const, write_data from token.data), dyadic when `const` is None (cell_addr from left operand, write_data from right operand). Per `cm_inst.py:91-97` SMInst operand mapping. 135 + - `MemOp.CMP_SW` — always dyadic (expected=left, new=right, cell_addr from const). Per `cm_inst.py:97`. 136 + 137 + 4. **`def is_monadic(op: ALUOp | MemOp, const: Optional[int] = None) -> bool`** — Returns `True` if the op is always monadic (in `MONADIC_OPS`), or if it's `MemOp.WRITE` with `const is not None` (monadic form). Returns `False` for `MemOp.CMP_SW` (always dyadic) and for `MemOp.WRITE` with `const is None` (dyadic form). 138 + 139 + 5. **`def is_dyadic(op: ALUOp | MemOp, const: Optional[int] = None) -> bool`** — Returns `not is_monadic(op, const)`. 140 + 141 + **Testing:** 142 + 143 + Tests in `tests/test_opcodes.py` must verify: 144 + - or1-asm.AC1.1: Every ALU opcode mnemonic in `MNEMONIC_TO_OP` maps to the correct `ALUOp` subclass value. Enumerate all expected pairs. 145 + - or1-asm.AC1.2: Every SM memory opcode mnemonic maps to the correct `MemOp` value. Enumerate all expected pairs. 146 + - or1-asm.AC1.3: Arity classification is correct for all opcodes. Check known monadic ops return `is_monadic(op) == True` and known dyadic ops return `is_dyadic(op) == True`. Use parametrize for clarity. 147 + - Round-trip: for every entry in `MNEMONIC_TO_OP`, verify `OP_TO_MNEMONIC[MNEMONIC_TO_OP[mnemonic]] == mnemonic`. (`free` → `RoutingOp.FREE` and `free_sm` → `MemOp.FREE` are distinct enum types, so both round-trip without collision.) 148 + 149 + **Verification:** 150 + ```bash 151 + python -m pytest tests/test_opcodes.py -v 152 + ``` 153 + Expected: All tests pass. 154 + 155 + **Commit:** `feat(asm): add opcode mnemonic mapping and arity classification` 156 + 157 +  158 +

+339

docs/implementation-plans/2026-02-22-or1-asm/phase_02.md

··· 1 + # OR1 Assembler — Phase 2: IR Types & Lower Pass 2 + 3 + **Goal:** Define the Graph IR types and implement the Lark Transformer that converts the parse tree into an IRGraph. 4 + 5 + **Architecture:** Frozen dataclasses for all IR types (following existing patterns in `tokens.py`, `cm_inst.py`). A Lark `Transformer` subclass processes the CST bottom-up, producing `IRGraph` with nodes, edges, regions, and data definitions. Function scope qualification happens during lowering. Inline edges (strong/weak) desugar into anonymous nodes + plain edges. 6 + 7 + **Tech Stack:** Python 3.12, Lark (Transformer, v_args), pytest + hypothesis 8 + 9 + **Scope:** 7 phases from original design (this is phase 2 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC2: Lower Pass — Instruction & Edge Handling 20 + - **or1-asm.AC2.1 Success:** `inst_def` (`&label <| opcode`) lowers to IRNode with correct opcode and name 21 + - **or1-asm.AC2.2 Success:** `plain_edge` (`&a |> &b:L`) lowers to IREdge with correct source, dest, and port 22 + - **or1-asm.AC2.3 Success:** `strong_edge` (`add &a, &b |> &c, &d`) desugars into anonymous IRNode + wiring edges 23 + - **or1-asm.AC2.4 Success:** `weak_edge` (`&c, &d sub <| &a, &b`) desugars identically to equivalent strong edge 24 + - **or1-asm.AC2.5 Success:** `data_def` (`@name|sm0:0 = 0x05`) lowers to IRDataDef with correct SM ID, cell address, and value 25 + - **or1-asm.AC2.6 Success:** Multi-value data def (`'h', 'e'`) packs into 16-bit word big-endian (0x6865) 26 + - **or1-asm.AC2.7 Success:** `@system pe=4, sm=1` pragma parsed into SystemConfig 27 + - **or1-asm.AC2.8 Success:** Placement qualifiers (`|pe0`) on inst_def populate IRNode.pe 28 + - **or1-asm.AC2.9 Edge:** Instruction with named args (`&serial <| ior, dest=0x45`) preserves arg values in IRNode 29 + 30 + ### or1-asm.AC3: Lower Pass — Scoping 31 + - **or1-asm.AC3.1 Success:** &labels inside `$func` are qualified as `$func.&label` 32 + - **or1-asm.AC3.2 Success:** @nodes remain global (no function prefix) 33 + - **or1-asm.AC3.3 Success:** Top-level &labels (outside any function) are unqualified 34 + - **or1-asm.AC3.4 Success:** Two functions can each define `&add` without collision 35 + - **or1-asm.AC3.5 Failure:** Defining a reserved name (`@system`) as a node produces error with source location 36 + - **or1-asm.AC3.6 Failure:** Duplicate &label within same function scope produces error 37 + - **or1-asm.AC3.7 Success:** `$func |> { ... }` creates a FUNCTION IRRegion with the function body as a nested IRGraph 38 + - **or1-asm.AC3.8 Success:** Location directive (`@section|sm0`) creates a LOCATION IRRegion containing subsequent statements until the next region boundary 39 + 40 + --- 41 + 42 + ## Codebase Verification Findings 43 + 44 + - ✓ Frozen dataclass patterns well-established: `@dataclass(frozen=True)` with `Optional[T]`, union types via `|`, defaults on optional fields. 45 + - ✓ Grammar rules fully mapped: `inst_def`, `plain_edge`, `strong_edge`, `weak_edge`, `func_def`, `data_def`, `location_dir` with exact child structures. 46 + - ✓ Lark Transformer API: bottom-up processing, method names match rule names, `@v_args(inline=True, meta=True)` for positional args + source location, `visit_tokens=True` for terminal processing. 47 + - ✓ `qualified_ref` grammar rule contains `node_ref | label_ref | func_ref`, optional `placement`, optional `port`. The `?argument` rule is inlined (no tree node). 48 + - ✓ `Port` enum at `tokens.py:8-10` (`L=0, R=1`). `PORT_SPEC` terminal accepts IDENT, HEX_LIT, DEC_LIT — Transformer must normalize to `Port` enum. 49 + - ✓ `asm/` package does not exist yet. 50 + - ✗ Grammar `?argument` and `?positional_arg` rules use `?` prefix — inlined, no tree nodes created. Transformer sees `named_arg`, `qualified_ref`, or value literals directly. 51 + 52 + --- 53 + 54 +  55 + 56 +  57 + ### Task 1: Create IR type definitions in asm/ir.py 58 + 59 + **Verifies:** None (infrastructure — types used by subsequent tasks) 60 + 61 + **Files:** 62 + - Modify: `asm/__init__.py` (created in Phase 1, Task 2) 63 + - Create: `asm/ir.py` 64 + 65 + **Implementation:** 66 + 67 + Create `asm/ir.py` with frozen dataclasses for all IR types. Follow the existing pattern from `cm_inst.py` and `tokens.py`: `@dataclass(frozen=True)`, explicit type annotations, `Optional[T]` for nullable fields. 68 + 69 + Types to define (in dependency order): 70 + 71 + 1. **`SourceLoc`** — `line: int`, `column: int`, `end_line: Optional[int] = None`, `end_column: Optional[int] = None`. Extracted from Lark's `meta` object. 72 + 73 + 2. **`NameRef`** — Unresolved symbolic reference. `name: str`, `port: Optional[Port] = None`. Import `Port` from `tokens`. 74 + 75 + 3. **`ResolvedDest`** — Fully resolved destination. `name: str`, `addr: Addr`. Import `Addr` from `cm_inst`. 76 + 77 + 4. **`IRNode`** — One per instruction. Fields: 78 + - `name: str` — Qualified name 79 + - `opcode: ALUOp | MemOp` — From existing enums 80 + - `dest_l: Optional[NameRef | ResolvedDest] = None` 81 + - `dest_r: Optional[NameRef | ResolvedDest] = None` 82 + - `const: Optional[int] = None` 83 + - `pe: Optional[int] = None` 84 + - `iram_offset: Optional[int] = None` 85 + - `ctx: Optional[int] = None` 86 + - `loc: SourceLoc = SourceLoc(0, 0)` 87 + - `args: Optional[dict[str, int]] = None` — For named args (AC2.9) 88 + - `sm_id: Optional[int] = None` — Target SM ID for MemOp nodes, extracted from arguments or inferred from system config (single SM → 0) 89 + 90 + For nodes with `MemOp` opcodes, the Lower pass populates `sm_id` from the node's arguments. If the program has only one SM (`system.sm_count == 1`), `sm_id` defaults to `0`. The codegen phase uses `sm_id` directly when constructing `SMInst`. 91 + 92 + **Note:** The design plan specifies `sm_inst: Optional[SMInst]` on IRNode. This implementation uses `sm_id: Optional[int]` instead because the full `SMInst` (including `ret` address) is only constructible after destination resolution in Phase 4. The `ret` field is derived from `dest_l.addr` during codegen (Phase 6). Storing `sm_id` alone avoids duplicating resolved address state in the IR. 93 + 94 + 5. **`IREdge`** — `source: str`, `dest: str`, `port: Port`, `source_port: Optional[Port] = None`, `loc: SourceLoc = SourceLoc(0, 0)`. 95 + 96 + `port` is the **destination input port** (which side of the matching store the token enters). `source_port` is the **source output slot** (`:L` means the edge originates from `dest_l`, `:R` from `dest_r`). When `source_port` is `None`, the allocator infers the output slot from edge count (single edge → `dest_l`). 97 + 98 + 6. **`RegionKind`** — `Enum` with `FUNCTION`, `LOCATION`. 99 + 100 + 7. **`IRDataDef`** — `name: str`, `sm_id: Optional[int] = None`, `cell_addr: Optional[int] = None`, `value: int = 0`, `loc: SourceLoc = SourceLoc(0, 0)`. 101 + 102 + 8. **`SystemConfig`** — `pe_count: int`, `sm_count: int`, `iram_capacity: int = 64`, `ctx_slots: int = 4`, `loc: SourceLoc = SourceLoc(0, 0)`. The `iram_capacity` and `ctx_slots` fields allow experimentation with hardware parameters (e.g., `@system pe=4, sm=1, iram=128, ctx=2`). Defaults match PEConfig's current defaults so existing programs work unchanged. 103 + 104 + 9. **`AssemblyError`** — Defined separately in Task 2. 105 + 106 + 10. **`IRGraph`** — Container. `nodes: dict[str, IRNode]`, `edges: list[IREdge]`, `regions: list[IRRegion]`, `data_defs: list[IRDataDef]`, `system: Optional[SystemConfig] = None`, `errors: list[AssemblyError]` with `field(default_factory=list)`. 107 + 108 + Note: `IRGraph` is frozen but holds mutable containers. This follows the `PEConfig` pattern in `emu/types.py:22-28`. Each pass returns a new `IRGraph`; containers are never mutated after construction. 109 + 110 + 11. **`IRRegion`** — `tag: str`, `kind: RegionKind`, `body: IRGraph`, `loc: SourceLoc = SourceLoc(0, 0)`. 111 + 112 + Note: `IRRegion` references `IRGraph` and `IRGraph.regions` holds `list[IRRegion]` — mutual reference. Use forward reference string `'IRGraph'` in `IRRegion` and define `IRGraph` after `IRRegion` in the file, or use `from __future__ import annotations`. 113 + 114 + Use `from __future__ import annotations` at the top of the file to enable forward references throughout. 115 + 116 + Use `from dataclasses import dataclass, field` for `field(default_factory=...)` on mutable defaults. 117 + 118 + **Verification:** 119 + ```bash 120 + python -c "from asm.ir import IRGraph, IRNode, IREdge, IRRegion, SourceLoc, NameRef, ResolvedDest, IRDataDef, SystemConfig, RegionKind; print('OK')" 121 + ``` 122 + Expected: Prints `OK` with no import errors. 123 + 124 + **Commit:** `feat(asm): add IR type definitions` 125 + 126 +  127 + 128 +  129 + ### Task 2: Create error types in asm/errors.py 130 + 131 + **Verifies:** or1-asm.AC3.5 (error with source location), or1-asm.AC3.6 (error for duplicates) 132 + 133 + **Files:** 134 + - Create: `asm/errors.py` 135 + 136 + **Implementation:** 137 + 138 + Create `asm/errors.py` with: 139 + 140 + 1. **`ErrorCategory`** — `Enum` with values: `PARSE`, `NAME`, `SCOPE`, `PLACEMENT`, `RESOURCE`, `ARITY`, `PORT`, `UNREACHABLE`. 141 + 142 + 2. **`AssemblyError`** — Frozen dataclass with: 143 + - `loc: SourceLoc` 144 + - `category: ErrorCategory` 145 + - `message: str` 146 + - `suggestions: list[str] = field(default_factory=list)` 147 + - `context_lines: list[str] = field(default_factory=list)` 148 + 149 + 3. **`format_error(error: AssemblyError, source: str) -> str`** — Takes an error and the original source text, formats it Rust-style with the relevant source line and a caret pointing to the error column. Example output: 150 + ``` 151 + error[SCOPE]: Duplicate label '&add' in function '$main' 152 + --> line 5, column 3 153 + | 154 + 5 | &add <| sub 155 + | ^^^ 156 + = help: First defined at line 2 157 + ``` 158 + 159 + Import `SourceLoc` from `asm.ir`. 160 + 161 + **Verification:** 162 + ```bash 163 + python -c "from asm.errors import AssemblyError, ErrorCategory, format_error; print('OK')" 164 + ``` 165 + 166 + **Commit:** `feat(asm): add structured error types with source context formatting` 167 + 168 +  169 +  170 + 171 +  172 + 173 +  174 + ### Task 3: Implement the Lower pass Transformer in asm/lower.py 175 + 176 + **Verifies:** or1-asm.AC2.1, or1-asm.AC2.2, or1-asm.AC2.3, or1-asm.AC2.4, or1-asm.AC2.5, or1-asm.AC2.6, or1-asm.AC2.7, or1-asm.AC2.8, or1-asm.AC2.9, or1-asm.AC3.1, or1-asm.AC3.2, or1-asm.AC3.3, or1-asm.AC3.4, or1-asm.AC3.5, or1-asm.AC3.6, or1-asm.AC3.7, or1-asm.AC3.8 177 + 178 + **Files:** 179 + - Create: `asm/lower.py` 180 + 181 + **Implementation:** 182 + 183 + Create a Lark `Transformer` subclass called `LowerTransformer` that converts the CST into an `IRGraph`. The transformer is instantiated and called via a module-level `lower(tree: lark.Tree) -> IRGraph` function. 184 + 185 + **Key responsibilities:** 186 + 187 + The transformer maintains state during transformation: 188 + - `_func_scope: Optional[str]` — Current function scope name (e.g., `$main`), `None` when at top level 189 + - `_anon_counter: int` — Counter for anonymous node names from inline edge desugaring 190 + - `_errors: list[AssemblyError]` — Accumulated errors 191 + - `_nodes: dict[str, IRNode]` — Collected nodes 192 + - `_edges: list[IREdge]` — Collected edges 193 + - `_regions: list[IRRegion]` — Collected regions 194 + - `_data_defs: list[IRDataDef]` — Collected data definitions 195 + - `_system: Optional[SystemConfig]` — System config from pragma 196 + - `_defined_names: dict[str, SourceLoc]` — Tracks where names are defined for duplicate detection 197 + 198 + **Grammar rule → Transformer method mapping:** 199 + 200 + - **`start`** — Collects all children (statements, regions) into the final `IRGraph`. 201 + 202 + - **`inst_def`** — Receives `qualified_ref` result (a dict with name, placement, port) + `opcode` result (an `ALUOp | MemOp`) + `argument*` results. Creates an `IRNode`. Qualifies `&label` names with function scope. Checks for reserved names (`@system`, `@io`, `@debug`). Checks for duplicate names within scope. Extracts `const` from positional args, `args` dict from named args. Populates `pe` from placement qualifier (parse the `pe` prefix and extract integer, e.g., `pe0` → `0`). 203 + 204 + - **`plain_edge`** — Receives source `qualified_ref` + `ref_list` of destination `qualified_ref`s. For each destination, creates an `IREdge` with the source's qualified name, destination's qualified name, destination's port (defaulting to `Port.L` if no port specified), and `source_port` from the source `qualified_ref`'s port (e.g., `&branch:L |> &taken:L` produces `IREdge(source="&branch", dest="&taken", port=Port.L, source_port=Port.L)`). If the source has no port qualifier, `source_port` is `None`. 205 + 206 + - **`strong_edge`** — Receives `opcode`, `argument*` (inputs), `ref_list` (outputs). Desugars: 207 + 1. Generate anonymous name: `&__anon_{counter}` (function-scope-qualified) 208 + 2. Create `IRNode` with the opcode and anonymous name 209 + 3. Wire inputs: for each input argument that is a ref, create `IREdge(source=input_ref, dest=anon_name, port=...)`. First input → `Port.L`, second → `Port.R`. 210 + 4. Wire outputs: for each output ref in `ref_list`, create `IREdge(source=anon_name, dest=output_ref, port=output_port)`. 211 + 212 + - **`weak_edge`** — Receives `ref_list` (outputs), `opcode`, `argument*` (inputs). Same desugaring as `strong_edge` — outputs come first syntactically but semantics are identical. 213 + 214 + - **`func_def`** — Receives `func_ref` name + child statements. Sets `_func_scope` to the function name, processes children (which will qualify labels), then creates an `IRRegion(tag=func_name, kind=RegionKind.FUNCTION, body=IRGraph(...))` containing the function's nodes/edges/data_defs. Resets `_func_scope` to previous value after. 215 + 216 + - **`data_def`** — Receives `qualified_ref` (with optional placement and port used for SM ID and cell address) + value list or macro call. Extracts SM ID from placement (e.g., `sm0` → `0`), cell address from port (e.g., `:0` → `0`), and value from the value list. For multi-value char data (AC2.6), pack char values pairwise into 16-bit words big-endian: `(ord(c1) << 8) | ord(c2)`. If the char count is odd, the last char is zero-padded in the low byte: `(ord(c_last) << 8) | 0x00`. A single char value produces one 16-bit word. Integer values are stored directly as 16-bit words (one per value). 217 + 218 + - **`location_dir`** — Receives `qualified_ref`. Creates an `IRRegion(tag=..., kind=RegionKind.LOCATION, body=IRGraph(...))`. Subsequent statements until the next region boundary are grouped into this region's body. 219 + 220 + - **`opcode`** — Receives the OPCODE token. Uses `MNEMONIC_TO_OP` from `asm.opcodes` to map the mnemonic string to its enum value. If the mnemonic is not in the mapping (e.g., `ior`, `brty`), adds an `AssemblyError` with `ErrorCategory.PARSE`. 221 + 222 + - **`qualified_ref`** — Collects the ref type (`node_ref`, `label_ref`, `func_ref`), optional `placement`, optional `port` into a dict or intermediate object. 223 + 224 + - **`hex_literal`**, **`dec_literal`**, **`char_literal`** — Convert token values to Python `int`. 225 + 226 + - **`named_arg`** — Returns a `(name, value)` tuple. 227 + 228 + - **`system_pragma`** — Receives `system_param` results (list of `(name, value)` tuples). Constructs `SystemConfig` from the parameters. Valid parameter names: `pe` (pe_count), `sm` (sm_count), `iram` (iram_capacity), `ctx` (ctx_slots). Unknown parameter names produce an `AssemblyError`. Stores result in `self._system`. If a `system_pragma` was already seen, produces an error (duplicate `@system`). 229 + 230 + - **`system_param`** — Returns a `(name: str, value: int)` tuple from `IDENT "=" number`. 231 + 232 + - **`placement`** — Extracts the IDENT token value (e.g., `pe0`, `sm0`). 233 + 234 + - **`port`** — Extracts PORT_SPEC token and normalizes: `"L"` → `Port.L`, `"R"` → `Port.R`, `"0"` → `Port.L`, `"1"` → `Port.R`. 235 + 236 + **Name qualification rules:** 237 + - `&label` inside `$func` → `$func.&label` 238 + - `&label` at top level → `&label` 239 + - `@node` anywhere → `@node` (no qualification) 240 + - `$func` → `$func` (no qualification) 241 + 242 + **Source location extraction:** 243 + Use `@v_args(meta=True)` on transformer methods. Extract `SourceLoc(line=meta.line, column=meta.column, end_line=meta.end_line, end_column=meta.end_column)` from the `meta` parameter. 244 + 245 + **Reserved name check:** 246 + If a `node_ref` (starting with `@`) matches `@system`, `@io`, or `@debug`, add `AssemblyError(category=ErrorCategory.NAME, message="Reserved name '@system' cannot be used as a node definition")`. 247 + 248 + **Duplicate name check:** 249 + Track defined names in `_defined_names`. If a qualified name is already defined, add `AssemblyError(category=ErrorCategory.SCOPE, message="Duplicate label '&add' in function '$main'")` with the source location of both definitions. 250 + 251 + **Module-level API:** 252 + ```python 253 + def lower(tree: lark.Tree) -> IRGraph: 254 + transformer = LowerTransformer() 255 + return transformer.transform(tree) 256 + ``` 257 + 258 + **Verification:** 259 + ```bash 260 + python -c "from asm.lower import lower; print('OK')" 261 + ``` 262 + 263 + **Commit:** `feat(asm): implement Lower pass (CST → IRGraph)` 264 + 265 +  266 + 267 +  268 + ### Task 4: Lower pass tests 269 + 270 + **Verifies:** or1-asm.AC2.1, or1-asm.AC2.2, or1-asm.AC2.3, or1-asm.AC2.4, or1-asm.AC2.5, or1-asm.AC2.6, or1-asm.AC2.7, or1-asm.AC2.8, or1-asm.AC2.9, or1-asm.AC3.1, or1-asm.AC3.2, or1-asm.AC3.3, or1-asm.AC3.4, or1-asm.AC3.5, or1-asm.AC3.6, or1-asm.AC3.7, or1-asm.AC3.8 271 + 272 + **Files:** 273 + - Create: `tests/test_lower.py` 274 + 275 + **Implementation:** 276 + 277 + Create a test file that parses dfasm source through the Lark parser and then lowers it via the `lower()` function. Reuse the same parser fixture pattern from `tests/test_parser.py`. 278 + 279 + The test file needs a helper that combines parsing and lowering: 280 + 281 + ```python 282 + def parse_and_lower(parser, source: str) -> IRGraph: 283 + tree = parser.parse(dedent(source)) 284 + return lower(tree) 285 + ``` 286 + 287 + **Test classes and what each verifies:** 288 + 289 + **`TestInstDef`** — Tests for AC2.1, AC2.8, AC2.9: 290 + - Parse `&my_add <| add` → IRGraph has node named `&my_add` with opcode `ArithOp.ADD` 291 + - Parse `&my_const <| const, 42` → IRNode has `const=42` 292 + - Parse `&my_add|pe0 <| add` → IRNode has `pe=0` 293 + - Parse `&serial <| ior, dest=0x45` → should produce error (ior not in MNEMONIC_TO_OP) OR if handled, node has `args={"dest": 0x45}` 294 + 295 + **`TestPlainEdge`** — Tests for AC2.2: 296 + - Parse `&a <| pass` + `&b <| add` + `&a |> &b:L` → IREdge with `source="&a"`, `dest="&b"`, `port=Port.L` 297 + - Parse `&a |> &b:R` → port is `Port.R` 298 + - Parse `&a |> &b, &c` → two IREdges (fanout) 299 + 300 + **`TestStrongEdge`** — Tests for AC2.3: 301 + - Parse `add &a, &b |> &c, &d` → anonymous IRNode with `ArithOp.ADD`, edges from `&a` → anon:L, `&b` → anon:R, anon → `&c`, anon → `&d` 302 + - Verify anonymous node name starts with `&__anon_` 303 + 304 + **`TestWeakEdge`** — Tests for AC2.4: 305 + - Parse `&c, &d sub <| &a, &b` → produces identical IR structure to equivalent strong edge `sub &a, &b |> &c, &d` 306 + 307 + **`TestDataDef`** — Tests for AC2.5, AC2.6: 308 + - Parse `@hello|sm0:0 = 0x05` → `IRDataDef(name="@hello", sm_id=0, cell_addr=0, value=5)` 309 + - Parse `@hello|sm0:1 = 'h', 'e'` → `IRDataDef(name="@hello", sm_id=0, cell_addr=1, value=0x6865)` (big-endian packing) 310 + 311 + **`TestSystemConfig`** — Tests for AC2.7: 312 + - This requires the `@system pe=4, sm=1` pragma syntax. Verify how the grammar currently handles this. If the grammar has a rule for it (check `inst_def` with named args on a `@system` node ref), test that it produces `SystemConfig(pe_count=4, sm_count=1)`. If the grammar doesn't have a dedicated rule, the Lower pass must detect `@system` node refs with named args and special-case them. 313 + - Parse `@system pe=4, sm=1, iram=128, ctx=2` → `SystemConfig(pe_count=4, sm_count=1, iram_capacity=128, ctx_slots=2)` 314 + - Parse `@system pe=4, sm=1` with no iram/ctx → defaults: `SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4)` 315 + 316 + **`TestFunctionScoping`** — Tests for AC3.1, AC3.2, AC3.3, AC3.4: 317 + - Parse `$main |> { &add <| add }` → node named `$main.&add`, inside a FUNCTION region 318 + - Parse `@global <| pass` at top level → node named `@global` (no qualification) 319 + - Parse `&top <| pass` at top level → node named `&top` (unqualified) 320 + - Parse `$foo |> { &add <| add }` + `$bar |> { &add <| sub }` → two nodes: `$foo.&add` and `$bar.&add` (no collision) 321 + 322 + **`TestRegions`** — Tests for AC3.7, AC3.8: 323 + - Parse `$func |> { &a <| add }` → `IRRegion(tag="$func", kind=RegionKind.FUNCTION)` with body containing the `&a` node 324 + - Parse `@data_section|sm0` followed by data defs → `IRRegion(tag="@data_section", kind=RegionKind.LOCATION)` 325 + 326 + **`TestErrorCases`** — Tests for AC3.5, AC3.6: 327 + - Parse a program with `@system <| add` (using reserved name) → `IRGraph.errors` contains error with `ErrorCategory.NAME` and source location 328 + - Parse a program with duplicate `&add` in same function → `IRGraph.errors` contains error with `ErrorCategory.SCOPE` 329 + 330 + **Verification:** 331 + ```bash 332 + python -m pytest tests/test_lower.py -v 333 + ``` 334 + Expected: All tests pass. 335 + 336 + **Commit:** `test(asm): add Lower pass tests for instruction/edge/scoping/error handling` 337 + 338 +  339 +

+142

docs/implementation-plans/2026-02-22-or1-asm/phase_03.md

··· 1 + # OR1 Assembler — Phase 3: Name Resolution 2 + 3 + **Goal:** Resolve all symbolic references in the IRGraph to concrete node connections. 4 + 5 + **Architecture:** A pure function `resolve(graph: IRGraph) -> IRGraph` that walks all edges, validates that source and dest names exist in the node dict, detects scope violations, and generates "did you mean" suggestions via Levenshtein distance for unresolved names. Errors are accumulated (not fail-fast) so all issues surface in one compilation. 6 + 7 + **Tech Stack:** Python 3.12, pytest 8 + 9 + **Scope:** 7 phases from original design (this is phase 3 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC4: Name Resolution 20 + - **or1-asm.AC4.1 Success:** All edge references in a valid program resolve to existing nodes 21 + - **or1-asm.AC4.2 Success:** Cross-function wiring via @nodes resolves correctly 22 + - **or1-asm.AC4.3 Failure:** Reference to undefined &label produces error with source context and "did you mean" suggestion 23 + - **or1-asm.AC4.4 Failure:** Reference to &label in different function scope produces scope violation error identifying the label's actual scope 24 + - **or1-asm.AC4.5 Failure:** "Did you mean" suggestion uses Levenshtein distance against in-scope names 25 + 26 + --- 27 + 28 +  29 + 30 +  31 + ### Task 1: Implement name resolution pass in asm/resolve.py 32 + 33 + **Verifies:** or1-asm.AC4.1, or1-asm.AC4.2, or1-asm.AC4.3, or1-asm.AC4.4, or1-asm.AC4.5 34 + 35 + **Files:** 36 + - Create: `asm/resolve.py` 37 + 38 + **Implementation:** 39 + 40 + Create `asm/resolve.py` with a `resolve(graph: IRGraph) -> IRGraph` function. 41 + 42 + **Resolution approach (from design):** The `IRGraph.nodes` dict uses qualified names as keys. Name resolution is a flat dict lookup — no scope chain walking needed. Nodes inside FUNCTION regions are accessible via their qualified names in the top-level `nodes` dict (flattened view). 43 + 44 + The resolve pass needs to: 45 + 46 + 1. **Build the full node dict** — Collect all nodes from the top-level graph AND from region bodies (recursively). Nodes in FUNCTION regions have qualified names (e.g., `$main.&add`), so the flattened dict has no collisions (Phase 2's Lower pass ensures uniqueness). 47 + 48 + 2. **Walk all edges** — For each `IREdge` in the graph (and recursively in regions), check that both `edge.source` and `edge.dest` exist in the flattened node dict. 49 + 50 + 3. **Scope validation** — When a `&label` reference fails to resolve: 51 + - Check if the name exists in a DIFFERENT function scope (e.g., `&add` doesn't exist at top level, but `$foo.&add` does). If so, produce a scope violation error: "Reference to '&add' not found. Did you mean '$foo.&add'? (defined in function '$foo')" 52 + - If not, produce a "did you mean" suggestion by computing Levenshtein distance against all in-scope names. 53 + 54 + 4. **Levenshtein distance** — Implement a simple edit distance function. Compare the unresolved name against all names in the flattened node dict. Suggest names with distance ≤ 3 (or the closest match if all distances are > 3). 55 + 56 + Implementation: standard dynamic programming, O(n*m) where n and m are string lengths. No external dependency needed. 57 + 58 + ```python 59 + def _levenshtein(a: str, b: str) -> int: 60 + if len(a) < len(b): 61 + return _levenshtein(b, a) 62 + if not b: 63 + return len(a) 64 + prev = list(range(len(b) + 1)) 65 + for i, ca in enumerate(a): 66 + curr = [i + 1] 67 + for j, cb in enumerate(b): 68 + curr.append(min( 69 + prev[j + 1] + 1, 70 + curr[j] + 1, 71 + prev[j] + (ca != cb), 72 + )) 73 + prev = curr 74 + return prev[-1] 75 + ``` 76 + 77 + 5. **Error accumulation** — Collect all resolution errors and return a new `IRGraph` with the errors appended to `graph.errors`. If there are errors, later passes should check `graph.errors` and skip processing. 78 + 79 + 6. **Validate edges reference known ports** — If an edge specifies `port=Port.L` on a destination that is monadic, that's fine (monadic instructions ignore port). No error needed for port mismatches at this stage — that's a later concern. 80 + 81 + The function returns a new `IRGraph` (immutable pass pattern). If all names resolve, the returned graph is structurally identical but validates that the program is well-formed. The actual NameRef → ResolvedDest conversion happens in Phase 4 (Allocate), because it requires IRAM offsets which don't exist yet. 82 + 83 + **Verification:** 84 + ```bash 85 + python -c "from asm.resolve import resolve; print('OK')" 86 + ``` 87 + 88 + **Commit:** `feat(asm): implement name resolution pass with Levenshtein suggestions` 89 + 90 +  91 + 92 +  93 + ### Task 2: Name resolution tests 94 + 95 + **Verifies:** or1-asm.AC4.1, or1-asm.AC4.2, or1-asm.AC4.3, or1-asm.AC4.4, or1-asm.AC4.5 96 + 97 + **Files:** 98 + - Create: `tests/test_resolve.py` 99 + 100 + **Implementation:** 101 + 102 + Tests that parse → lower → resolve programs and check the results. Reuse the parser fixture and `parse_and_lower` helper pattern. 103 + 104 + ```python 105 + def parse_lower_resolve(parser, source: str) -> IRGraph: 106 + tree = parser.parse(dedent(source)) 107 + graph = lower(tree) 108 + return resolve(graph) 109 + ``` 110 + 111 + **Test classes:** 112 + 113 + **`TestValidResolution`** — Tests for AC4.1, AC4.2: 114 + - Simple program with two nodes and an edge between them resolves with no errors 115 + - Cross-function wiring via `@global_node`: `$foo |> { &a <| pass }` + `$bar |> { &b <| add }` + `@bridge <| pass` + edges `$foo.&a |> @bridge` and `@bridge |> $bar.&b:L` — all resolve correctly (graph.errors is empty) 116 + - Program with function-scoped labels and edges within the same function resolve correctly 117 + 118 + **`TestUndefinedReference`** — Tests for AC4.3: 119 + - Edge references `&nonexistent` → error with `ErrorCategory.NAME`, message includes "undefined" 120 + - Error has source location (line/column from the edge's loc) 121 + - If a similar name exists (e.g., `&nonexistant` when `&nonexistent` exists), the suggestion is present 122 + 123 + **`TestScopeViolation`** — Tests for AC4.4: 124 + - `$foo |> { &private <| pass }` with top-level edge referencing `&private` → error identifies that `&private` exists in `$foo` scope 125 + - Error message includes something like "defined in function '$foo'" 126 + 127 + **`TestLevenshteinSuggestions`** — Tests for AC4.5: 128 + - Reference to `&ad` when `&add` exists → suggestion includes `&add` 129 + - Reference to `&addd` when `&add` exists → suggestion includes `&add` (distance 1) 130 + - Reference to `&completely_wrong` when only `&add` exists → no suggestion (distance too large) or best-effort suggestion 131 + - Test the `_levenshtein` function directly: verify `_levenshtein("kitten", "sitting") == 3` 132 + 133 + **Verification:** 134 + ```bash 135 + python -m pytest tests/test_resolve.py -v 136 + ``` 137 + Expected: All tests pass. 138 + 139 + **Commit:** `test(asm): add name resolution tests with scope and suggestion coverage` 140 + 141 +  142 +

+259

docs/implementation-plans/2026-02-22-or1-asm/phase_04.md

··· 1 + # OR1 Assembler — Phase 4: Placement Validation & Allocation 2 + 3 + **Goal:** Validate user-provided PE placements and assign IRAM offsets and context slots. 4 + 5 + **Architecture:** Two pure-function passes: `place(graph) -> IRGraph` validates placements, `allocate(graph) -> IRGraph` assigns offsets/slots and resolves destinations. Placement validation checks all nodes have PE assignments and validates against SystemConfig. Allocation packs dyadic instructions first (low offsets), assigns context slots per function body per PE, and converts all NameRef destinations to ResolvedDest with concrete Addr values. 6 + 7 + **Tech Stack:** Python 3.12, pytest 8 + 9 + **Scope:** 7 phases from original design (this is phase 4 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC5: Placement 20 + - **or1-asm.AC5.1 Success:** All nodes with explicit `|peN` placements are accepted when PE exists 21 + - **or1-asm.AC5.2 Failure:** Node placed on nonexistent PE (e.g., `|pe9` when system has 4 PEs) produces error 22 + - **or1-asm.AC5.3 Failure:** Node with no placement and auto-placement disabled produces error identifying the unplaced node 23 + 24 + ### or1-asm.AC6: Resource Allocation 25 + - **or1-asm.AC6.1 Success:** Dyadic instructions are assigned IRAM offsets starting at 0, packed contiguously 26 + - **or1-asm.AC6.2 Success:** Monadic/SM instructions are assigned IRAM offsets above the dyadic range 27 + - **or1-asm.AC6.3 Success:** Each function body on a PE gets a distinct context slot 28 + - **or1-asm.AC6.4 Success:** All NameRef destinations resolve to ResolvedDest with correct Addr (pe, offset, port) 29 + - **or1-asm.AC6.5 Success:** Local edges (same PE) produce Addr with dest PE = source PE 30 + - **or1-asm.AC6.6 Success:** Cross-PE edges produce Addr with dest PE = target PE 31 + - **or1-asm.AC6.7 Failure:** IRAM overflow produces error listing all nodes on the PE and available capacity 32 + - **or1-asm.AC6.8 Failure:** Context slot overflow produces error listing function bodies on the PE 33 + 34 + --- 35 + 36 + ## Codebase Verification Findings 37 + 38 + - ✓ `PEConfig` at `emu/types.py:22-28`: `pe_id`, `iram: dict[int, ALUInst | SMInst]`, `ctx_slots: int = 4`, `offsets: int = 64`, `gen_counters: Optional[list[int]] = None` 39 + - ✓ `Addr` at `cm_inst.py:55-59`: `a: int` (IRAM offset), `port: Port`, `pe: Optional[int]` 40 + - ✓ PE fetches via `self._fetch(token.offset)` at `emu/pe.py:59`. Matching store indexed by `[token.ctx][token.offset]` at `emu/pe.py:86-97`. 41 + - ✓ `MONADIC_OPS` defined in Phase 1's `asm/opcodes.py` provides arity classification. 42 + - ✓ Default PE capacity: 64 IRAM slots, 4 context slots. These are now configurable via `@system pe=4, sm=1, iram=128, ctx=2` (Phase 2's SystemConfig has `iram_capacity` and `ctx_slots` fields). Allocation must use `graph.system.iram_capacity` and `graph.system.ctx_slots` instead of hardcoded defaults. 43 + 44 + --- 45 + 46 +  47 + 48 +  49 + ### Task 1: Implement placement validation in asm/place.py 50 + 51 + **Verifies:** or1-asm.AC5.1, or1-asm.AC5.2, or1-asm.AC5.3 52 + 53 + **Files:** 54 + - Create: `asm/place.py` 55 + 56 + **Implementation:** 57 + 58 + Create `asm/place.py` with a `place(graph: IRGraph) -> IRGraph` function. 59 + 60 + The placement pass validates user-provided PE placements. In this phase (Phase 4), auto-placement is not implemented — all nodes must have explicit `|peN` annotations from the source. 61 + 62 + **Logic:** 63 + 64 + 1. **Determine system config** — Get `pe_count` and `sm_count` from `graph.system` (SystemConfig). If `graph.system is None`, infer `pe_count` from the maximum PE ID referenced in node placements + 1, and use default capacity values (`iram_capacity=64`, `ctx_slots=4`) matching `PEConfig` defaults. 65 + 66 + 2. **Validate all nodes have placements** — Walk all nodes (top-level and inside regions recursively). If any node has `pe is None`, add an error: 67 + ``` 68 + error[PLACEMENT]: Node '&add' has no PE placement. Add a placement qualifier like '|pe0'. 69 + ``` 70 + 71 + 3. **Validate PE existence** — For each node with `pe` set, check that `pe < pe_count`. If not: 72 + ``` 73 + error[PLACEMENT]: Node '&add' placed on PE9 but system only has 4 PEs (0-3). 74 + ``` 75 + 76 + 4. **Return** — New `IRGraph` with any errors appended. If no errors, the graph is unchanged. 77 + 78 + **Verification:** 79 + ```bash 80 + python -c "from asm.place import place; print('OK')" 81 + ``` 82 + 83 + **Commit:** `feat(asm): implement placement validation pass` 84 + 85 +  86 + 87 +  88 + ### Task 2: Placement validation tests 89 + 90 + **Verifies:** or1-asm.AC5.1, or1-asm.AC5.2, or1-asm.AC5.3 91 + 92 + **Files:** 93 + - Create: `tests/test_place.py` 94 + 95 + **Implementation:** 96 + 97 + Tests that construct IRGraphs directly (no parsing needed — work at the IR level) and run them through `place()`. 98 + 99 + Helper to create minimal IRGraphs with nodes: 100 + ```python 101 + def make_graph(nodes: dict[str, IRNode], system: SystemConfig = None) -> IRGraph: 102 + return IRGraph(nodes=nodes, edges=[], regions=[], data_defs=[], system=system, errors=[]) 103 + ``` 104 + 105 + **Test classes:** 106 + 107 + **`TestValidPlacement`** — AC5.1: 108 + - All nodes have PE assignments within range → no errors 109 + - System with 4 PEs, nodes on pe0, pe1, pe2, pe3 → accepted 110 + 111 + **`TestNonexistentPE`** — AC5.2: 112 + - Node on pe9 with SystemConfig(pe_count=4) → error mentioning PE9 and available range 113 + - Verify error category is `ErrorCategory.PLACEMENT` 114 + 115 + **`TestUnplacedNode`** — AC5.3: 116 + - Node with `pe=None` → error identifying the node name 117 + - Verify error suggests adding `|peN` qualifier 118 + 119 + **Verification:** 120 + ```bash 121 + python -m pytest tests/test_place.py -v 122 + ``` 123 + 124 + **Commit:** `test(asm): add placement validation tests` 125 + 126 +  127 +  128 + 129 +  130 + 131 +  132 + ### Task 3: Implement resource allocation in asm/allocate.py 133 + 134 + **Verifies:** or1-asm.AC6.1, or1-asm.AC6.2, or1-asm.AC6.3, or1-asm.AC6.4, or1-asm.AC6.5, or1-asm.AC6.6, or1-asm.AC6.7, or1-asm.AC6.8 135 + 136 + **Files:** 137 + - Create: `asm/allocate.py` 138 + 139 + **Implementation:** 140 + 141 + Create `asm/allocate.py` with an `allocate(graph: IRGraph) -> IRGraph` function. 142 + 143 + The allocate pass assigns IRAM offsets, context slots, and resolves all symbolic destinations to concrete `Addr` values. 144 + 145 + **Logic:** 146 + 147 + 1. **Group nodes by PE** — Walk all nodes, partition into `dict[int, list[IRNode]]` keyed by `node.pe`. 148 + 149 + 2. **Assign IRAM offsets per PE:** 150 + - Partition nodes on each PE into dyadic and monadic using `is_dyadic(node.opcode, node.const)` from `asm.opcodes`. Note: `MemOp.WRITE` arity depends on whether `const` is set (monadic) or not (dyadic). `MemOp.CMP_SW` is always dyadic. 151 + - Assign dyadic instructions offsets 0, 1, 2, ..., D-1. 152 + - Assign monadic/SM instructions offsets D, D+1, ..., M-1. 153 + - Validate total M ≤ `graph.system.iram_capacity` (default 64, configurable via `@system iram=N`). On overflow: 154 + ``` 155 + error[RESOURCE]: PE0 IRAM overflow: 70 instructions but only 64 slots. 156 + Dyadic: &add, &sub, &mul, ... (45 instructions) 157 + Monadic: &inc, &const_1, ... (25 instructions) 158 + ``` 159 + - Create updated IRNodes with `iram_offset` set. Since IRNode is frozen, construct new instances using `dataclasses.replace()`. 160 + 161 + 3. **Assign context slots per PE:** 162 + - Determine which function bodies are present on each PE. For each PE, collect the set of function scopes from node names (e.g., nodes `$main.&add` and `$main.&sub` both belong to `$main`; nodes `$helper.&inc` belong to `$helper`; nodes `&top_level` belong to the root scope). 163 + - Assign context slot 0 to root scope / first function, slot 1 to second function, etc. 164 + - Validate total ≤ `graph.system.ctx_slots` (default 4, configurable via `@system ctx=N`). On overflow: 165 + ``` 166 + error[RESOURCE]: PE0 context slot overflow: 5 function bodies but only 4 slots. 167 + Functions: $main, $helper, $fib, $util, $extra 168 + ``` 169 + - Update IRNodes with `ctx` set. 170 + 171 + 4. **Resolve destinations (NameRef → ResolvedDest):** 172 + - Walk all nodes. For each node with `dest_l` or `dest_r` that is a `NameRef`: 173 + - Look up the destination node by name in the graph's node dict. 174 + - Get the destination's `iram_offset` and `pe`. 175 + - Construct `Addr(a=dest_node.iram_offset, port=nameref.port or Port.L, pe=dest_node.pe)`. 176 + - Replace the `NameRef` with `ResolvedDest(name=nameref.name, addr=addr)`. 177 + - Local edges: source and dest on same PE → `Addr.pe` = source PE (or `None` — the PE routes locally). 178 + - Cross-PE edges: `Addr.pe` = destination PE. 179 + 180 + 5. **Return** — New `IRGraph` with all nodes updated (iram_offset, ctx, resolved destinations) and any errors. 181 + 182 + **Edge-to-destination mapping rules:** 183 + 184 + Destinations on `IRNode.dest_l` and `dest_r` are populated during allocation by analyzing edges. For each source node, group its outgoing edges (edges where this node is `source`), then assign output slots using the edge's `source_port` field: 185 + 186 + - **`source_port == Port.L`** → edge maps to `dest_l`. 187 + - **`source_port == Port.R`** → edge maps to `dest_r`. 188 + - **`source_port is None`** (no source port qualifier) → infer from edge count: 189 + - Single outgoing edge → `dest_l`. 190 + - Two outgoing edges, both without source port → first declared edge (in `graph.edges` order) → `dest_l`, second → `dest_r`. 191 + 192 + The `port` on an `IREdge` specifies the **input** port on the destination node (which side of the matching store the token enters). The `source_port` specifies the **output slot** on the source node. The `Addr` constructed is: `Addr(a=dest_node.iram_offset, port=edge.port, pe=dest_node.pe)`. 193 + 194 + This convention is especially important for SWITCH ops (`sweq`, `swgt`, `swge`, `swof`): the emulator sends data to `dest_l` (taken path) and trigger to `dest_r` (not-taken path) when `bool_out=True`. Users disambiguate with source-side port qualifiers: 195 + ``` 196 + &branch:L |> &taken:L ; dest_l = taken path (data when true) 197 + &branch:R |> &not_taken:L ; dest_r = not-taken path (trigger when true) 198 + ``` 199 + 200 + **SM instruction return routes:** SM instruction nodes (`MemOp` opcodes) use the same edge-to-destination mapping as ALU nodes. For SM `read` instructions, `dest_l` serves as the return address — the codegen phase (Phase 6) maps `node.dest_l.addr` to `SMInst.ret`. 201 + 202 + **Validation:** 203 + - If a node has more than two outgoing edges, add an error — the hardware supports at most two destinations per instruction. 204 + - If two edges claim the same source_port (e.g., both `:L`), add an error — conflicting output slot assignment. 205 + - If one edge has source_port and the other doesn't for the same source node, add an error — mixed explicit/implicit output slots. 206 + 207 + **Verification:** 208 + ```bash 209 + python -c "from asm.allocate import allocate; print('OK')" 210 + ``` 211 + 212 + **Commit:** `feat(asm): implement resource allocation (IRAM offsets, context slots, destination resolution)` 213 + 214 +  215 + 216 +  217 + ### Task 4: Resource allocation tests 218 + 219 + **Verifies:** or1-asm.AC6.1, or1-asm.AC6.2, or1-asm.AC6.3, or1-asm.AC6.4, or1-asm.AC6.5, or1-asm.AC6.6, or1-asm.AC6.7, or1-asm.AC6.8 220 + 221 + **Files:** 222 + - Create: `tests/test_allocate.py` 223 + 224 + **Implementation:** 225 + 226 + Tests that construct IR-level graphs and run through `allocate()`. Build helpers to create test IRGraphs with nodes on specific PEs, with edges. 227 + 228 + **Test classes:** 229 + 230 + **`TestIRAMPacking`** — AC6.1, AC6.2: 231 + - PE with 2 dyadic (ADD, SUB) and 2 monadic (INC, CONST) nodes → dyadic get offsets 0, 1; monadic get offsets 2, 3 232 + - PE with only monadic → offsets start at 0 (no dyadic to pack first) 233 + - PE with only dyadic → offsets 0..N-1, no gap 234 + 235 + **`TestContextSlots`** — AC6.3: 236 + - PE with nodes from `$main` and `$helper` → two distinct context slots (0 and 1) 237 + - PE with nodes from only `$main` → single context slot (0) 238 + - Top-level nodes get ctx=0 239 + 240 + **`TestDestinationResolution`** — AC6.4, AC6.5, AC6.6: 241 + - Local edge (same PE): source dest_l has Addr with `pe` matching source PE 242 + - Cross-PE edge: source dest_l has Addr with `pe` matching target PE 243 + - Resolved Addr has correct `a` (IRAM offset of destination node) and `port` 244 + 245 + **`TestOverflow`** — AC6.7, AC6.8: 246 + - PE with 65 nodes (exceeds default 64 IRAM slots) → error with category `RESOURCE`, message lists node count and capacity 247 + - PE with 5 function bodies (exceeds default 4 ctx_slots) → error lists all function names 248 + - SystemConfig with `iram_capacity=8`: PE with 9 nodes → overflow at custom limit 249 + - SystemConfig with `ctx_slots=2`: PE with 3 function bodies → overflow at custom limit 250 + 251 + **Verification:** 252 + ```bash 253 + python -m pytest tests/test_allocate.py -v 254 + ``` 255 + 256 + **Commit:** `test(asm): add resource allocation tests for IRAM packing, context slots, and overflow` 257 + 258 +  259 +

+197

docs/implementation-plans/2026-02-22-or1-asm/phase_05.md

··· 1 + # OR1 Assembler — Phase 5: Emulator ROUTE_SET Support 2 + 3 + **Goal:** Implement CfgOp.ROUTE_SET in the emulator and extend PEConfig with route restriction fields. 4 + 5 + **Architecture:** Three modifications to the emulator: (1) add `pe_routes` and `sm_routes` optional fields to PEConfig, (2) implement the ROUTE_SET handler in PE._handle_cfg that filters route tables to listed IDs, (3) make build_topology respect PEConfig route restrictions when wiring. Backwards compatible — `None` routes preserve full-mesh behaviour. 6 + 7 + **Tech Stack:** Python 3.12, SimPy 4.1, pytest 8 + 9 + **Scope:** 7 phases from original design (this is phase 5 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC7: Emulator ROUTE_SET 20 + - **or1-asm.AC7.1 Success:** ROUTE_SET CfgToken with PE and SM ID lists is accepted by PE without warning 21 + - **or1-asm.AC7.2 Success:** After ROUTE_SET, PE can route to listed PE IDs 22 + - **or1-asm.AC7.3 Success:** After ROUTE_SET, PE can route to listed SM IDs 23 + - **or1-asm.AC7.4 Failure:** After ROUTE_SET, routing to unlisted PE ID raises KeyError 24 + - **or1-asm.AC7.5 Failure:** After ROUTE_SET, routing to unlisted SM ID raises KeyError 25 + - **or1-asm.AC7.6 Success:** PEConfig with pe_routes/sm_routes fields restricts topology in build_topology() 26 + - **or1-asm.AC7.7 Success:** PEConfig with None routes (default) preserves full-mesh behaviour — all existing emulator tests pass unchanged 27 + 28 + --- 29 + 30 + ## Codebase Verification Findings 31 + 32 + - ✓ `CfgOp.ROUTE_SET = 1` exists at `tokens.py:68-70`. `CfgToken.data` typed as `list` with comment "ROUTE_SET: TBD". 33 + - ✓ `_handle_cfg` in `emu/pe.py:70-81` has LOAD_INST implemented and ROUTE_SET as stub (`TODO` + warning log). 34 + - ✓ `route_table: dict[int, simpy.Store]` and `sm_routes: dict[int, simpy.Store]` on PE at `emu/pe.py:33-34`, populated by `build_topology()`. 35 + - ✓ `build_topology` at `emu/network.py:30-74` creates full-mesh: all PEs → all PEs, all PEs → all SMs, all SMs → all PEs. 36 + - ✓ PE uses `self.route_table[dest.pe].put(token)` for output routing at `emu/pe.py:126-150` and `self.sm_routes[inst.sm_id].put(...)` at `emu/pe.py:172`. 37 + - ✓ PEConfig at `emu/types.py:22-28` does NOT have pe_routes/sm_routes fields yet. 38 + - ✓ Existing CfgToken LOAD_INST test at `tests/test_integration.py:611-671`. No ROUTE_SET tests exist. 39 + 40 + --- 41 + 42 +  43 + 44 +  45 + ### Task 1: Add route restriction fields to PEConfig and define ROUTE_SET data format 46 + 47 + **Verifies:** or1-asm.AC7.6, or1-asm.AC7.7 48 + 49 + **Files:** 50 + - Modify: `emu/types.py:22-28` (PEConfig) 51 + - Modify: `tokens.py:76` (CfgToken.data comment) 52 + 53 + **Implementation:** 54 + 55 + Add two optional fields to `PEConfig`: 56 + 57 + ```python 58 + @dataclass(frozen=True) 59 + class PEConfig: 60 + pe_id: int 61 + iram: dict[int, ALUInst | SMInst] 62 + ctx_slots: int = 4 63 + offsets: int = 64 64 + gen_counters: Optional[list[int]] = None 65 + allowed_pe_routes: Optional[set[int]] = None 66 + allowed_sm_routes: Optional[set[int]] = None 67 + ``` 68 + 69 + - `allowed_pe_routes: Optional[set[int]] = None` — Set of PE IDs this PE can route to. `None` means full-mesh (all PEs). 70 + - `allowed_sm_routes: Optional[set[int]] = None` — Set of SM IDs this PE can route to. `None` means full-mesh (all SMs). 71 + 72 + The field names use `allowed_` prefix to avoid confusion with the PE instance's runtime attributes (`route_table: dict[int, Store]` and `sm_routes: dict[int, Store]`). Config fields are sets of ints; runtime attributes are dicts of SimPy stores. 73 + 74 + Update `CfgToken.data` comment in `tokens.py` to document the ROUTE_SET format: 75 + 76 + ```python 77 + @dataclass(frozen=True) 78 + class CfgToken(SysToken): 79 + op: CfgOp 80 + data: list # LOAD_INST: list[ALUInst | SMInst]; ROUTE_SET: [list[int], list[int]] (pe_ids, sm_ids) 81 + ``` 82 + 83 + ROUTE_SET data format: `[pe_ids_list, sm_ids_list]` — a list of two lists. First element is the list of allowed PE IDs, second is allowed SM IDs. This keeps `data` as a plain `list` (matching LOAD_INST's list type) while being unambiguous. 84 + 85 + **Note:** The design plan described ROUTE_SET data as `{pe_routes: [...], sm_routes: [...]}` (dict). This implementation uses a list-of-two-lists instead, because `CfgToken.data` is typed as `list` and LOAD_INST already uses a flat list. Using a nested list `[[pe_ids], [sm_ids]]` is structurally equivalent and avoids mixed typing on the `data` field. 86 + 87 + **Verification:** 88 + ```bash 89 + python -m pytest tests/ -v 90 + ``` 91 + Expected: All existing tests pass unchanged (None defaults preserve full-mesh). 92 + 93 + **Commit:** `feat(emu): add route restriction fields to PEConfig and define ROUTE_SET data format` 94 + 95 +  96 + 97 +  98 + ### Task 2: Implement ROUTE_SET handler in PE and restricted wiring in build_topology 99 + 100 + **Verifies:** or1-asm.AC7.1, or1-asm.AC7.2, or1-asm.AC7.3, or1-asm.AC7.4, or1-asm.AC7.5, or1-asm.AC7.6 101 + 102 + **Files:** 103 + - Modify: `emu/pe.py:77-79` (_handle_cfg ROUTE_SET case) 104 + - Modify: `emu/network.py:64-69` (build_topology route wiring) 105 + 106 + **Implementation:** 107 + 108 + **PE._handle_cfg ROUTE_SET (emu/pe.py:77-79):** 109 + 110 + Replace the stub with: 111 + 112 + ```python 113 + elif token.op == CfgOp.ROUTE_SET: 114 + pe_ids, sm_ids = token.data[0], token.data[1] 115 + self.route_table = { 116 + pid: store for pid, store in self.route_table.items() 117 + if pid in pe_ids 118 + } 119 + self.sm_routes = { 120 + sid: store for sid, store in self.sm_routes.items() 121 + if sid in sm_ids 122 + } 123 + ``` 124 + 125 + After ROUTE_SET, only the listed PE/SM IDs remain in the route dicts. Any subsequent attempt to route to an unlisted ID will raise `KeyError` from the dict lookup in `_emit()` — this is the desired behaviour for AC7.4 and AC7.5 (no extra error handling needed, the dict access naturally fails). 126 + 127 + **build_topology route restriction (emu/network.py:64-69):** 128 + 129 + After the full-mesh wiring loop, add restriction logic: 130 + 131 + ```python 132 + for cfg in pe_configs: 133 + pe = pes[cfg.pe_id] 134 + if cfg.allowed_pe_routes is not None: 135 + pe.route_table = { 136 + pid: store for pid, store in pe.route_table.items() 137 + if pid in cfg.allowed_pe_routes 138 + } 139 + if cfg.allowed_sm_routes is not None: 140 + pe.sm_routes = { 141 + sid: store for sid, store in pe.sm_routes.items() 142 + if sid in cfg.allowed_sm_routes 143 + } 144 + ``` 145 + 146 + This applies route restrictions at topology build time (for direct mode codegen) by filtering the full-mesh routes post-hoc. This is intentional — modifying the existing wiring loop would be more invasive for minimal benefit, since route restriction only runs once at startup. The ROUTE_SET CfgToken handler applies the same filtering at runtime (for token stream mode). Both produce the same result. 147 + 148 + **Verification:** 149 + ```bash 150 + python -m pytest tests/ -v 151 + ``` 152 + Expected: All existing tests still pass (full-mesh unchanged when restrictions are None). 153 + 154 + **Commit:** `feat(emu): implement ROUTE_SET handler and restricted topology wiring` 155 + 156 +  157 + 158 +  159 + ### Task 3: ROUTE_SET and restricted topology tests 160 + 161 + **Verifies:** or1-asm.AC7.1, or1-asm.AC7.2, or1-asm.AC7.3, or1-asm.AC7.4, or1-asm.AC7.5, or1-asm.AC7.6, or1-asm.AC7.7 162 + 163 + **Files:** 164 + - Modify: `tests/test_pe.py` (add ROUTE_SET CfgToken tests) 165 + - Modify: `tests/test_network.py` (add restricted topology tests) 166 + 167 + **Implementation:** 168 + 169 + **tests/test_pe.py — New class `TestRouteSet`:** 170 + 171 + Tests for AC7.1–AC7.5 using direct PE manipulation: 172 + 173 + - AC7.1: Create PE with full-mesh route_table (3 PEs, 1 SM). Send ROUTE_SET CfgToken with `data=[[0, 2], [0]]`. No warning logged. Verify `route_table` has keys {0, 2} and `sm_routes` has key {0}. 174 + - AC7.2: After ROUTE_SET allowing PE 0 and PE 2, send a token routed to PE 0 → succeeds (token arrives in store). 175 + - AC7.3: After ROUTE_SET allowing SM 0, PE emits SM token to SM 0 → succeeds. 176 + - AC7.4: After ROUTE_SET allowing only PE 0, attempt to route to PE 1 → raises KeyError. 177 + - AC7.5: After ROUTE_SET allowing only SM 0, attempt to route to SM 1 → raises KeyError. 178 + 179 + For AC7.4/AC7.5, the test should verify that the PE's `_emit` process raises KeyError when accessing the restricted route_table. Since this happens inside a SimPy process, the test needs to catch the exception from the environment run. 180 + 181 + **tests/test_network.py — New class `TestRestrictedTopology`:** 182 + 183 + Tests for AC7.6, AC7.7: 184 + 185 + - AC7.6: Build topology with `PEConfig(pe_id=0, iram={}, allowed_pe_routes={1}, allowed_sm_routes={0})`. Verify PE 0's route_table has only key 1 and sm_routes has only key 0. 186 + - AC7.7: Build topology with default PEConfig (no route restrictions). Verify PE gets full-mesh route_table with all PE IDs and sm_routes with all SM IDs. Run existing test scenarios to confirm no regression. 187 + 188 + **Verification:** 189 + ```bash 190 + python -m pytest tests/test_pe.py tests/test_network.py -v 191 + ``` 192 + Expected: All new tests pass, all existing tests pass. 193 + 194 + **Commit:** `test(emu): add ROUTE_SET and restricted topology tests` 195 + 196 +  197 +

+363

docs/implementation-plans/2026-02-22-or1-asm/phase_06.md

··· 1 + # OR1 Assembler — Phase 6: Codegen (Both Modes) 2 + 3 + **Goal:** Generate emulator-ready output from a fully resolved and allocated IRGraph. 4 + 5 + **Architecture:** Two codegen paths (direct mode producing PEConfig/SMConfig lists + seed tokens, and token stream mode producing an ordered bootstrap sequence) plus a serializer that converts IRGraph back to valid dfasm source. A public API module (`asm/__init__.py`) exposes `assemble()`, `assemble_to_tokens()`, `serialize_graph()`, and `serialize()` as the top-level entry points. `serialize_graph()` works at any pipeline stage for IR inspection; `assemble()` and `assemble_to_tokens()` chain the full pipeline. 6 + 7 + **Tech Stack:** Python 3.12, pytest, Lark 8 + 9 + **Scope:** 7 phases from original design (this is phase 6 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC8: Codegen 20 + - **or1-asm.AC8.1 Success:** Direct mode produces valid PEConfig with correct IRAM contents (ALUInst/SMInst objects at assigned offsets) 21 + - **or1-asm.AC8.2 Success:** Direct mode produces valid SMConfig with initial cell values from data_defs 22 + - **or1-asm.AC8.3 Success:** Direct mode produces seed MonadTokens for const nodes with no incoming edges 23 + - **or1-asm.AC8.4 Success:** Direct mode PEConfig includes route restrictions matching edge analysis 24 + - **or1-asm.AC8.5 Success:** Token stream mode emits SM init tokens before ROUTE_SET tokens 25 + - **or1-asm.AC8.6 Success:** Token stream mode emits ROUTE_SET tokens before LOAD_INST tokens 26 + - **or1-asm.AC8.7 Success:** Token stream mode emits LOAD_INST tokens before seed tokens 27 + - **or1-asm.AC8.8 Success:** Token stream mode produces valid tokens consumable by the emulator 28 + - **or1-asm.AC8.9 Edge:** Program with no data_defs produces empty SM init section (no SMConfig / no SM tokens) 29 + - **or1-asm.AC8.10 Edge:** Program using single PE produces ROUTE_SET with only self-routes 30 + 31 + ### or1-asm.AC11: Serialization (IRGraph → dfasm) 32 + - **or1-asm.AC11.1 Success:** Fully resolved IRGraph serializes to valid dfasm source that re-parses without error 33 + - **or1-asm.AC11.2 Success:** Round-trip (parse → lower → resolve → place → allocate → serialize → parse → lower) produces structurally equivalent IRGraph 34 + - **or1-asm.AC11.3 Success:** Serialized output includes PE placement qualifiers on all nodes 35 + - **or1-asm.AC11.4 Success:** Serialized output preserves function scoping structure ($func |> { ... }) 36 + - **or1-asm.AC11.5 Success:** Serialized output includes data_def entries with SM placement and cell addresses 37 + - **or1-asm.AC11.6 Edge:** Anonymous nodes from inline edge desugaring serialize as named inst_def + plain_edge (not back to inline syntax) 38 + - **or1-asm.AC11.7 Success:** FUNCTION regions serialize as `$name |> { ...body... }` with unqualified &label names inside 39 + - **or1-asm.AC11.8 Success:** LOCATION regions serialize as bare directive followed by body contents 40 + 41 + --- 42 + 43 + ## Codebase Verification Findings 44 + 45 + - ✓ `PEConfig` at `emu/types.py:22-28`: `pe_id`, `iram: dict[int, ALUInst | SMInst]`, `ctx_slots`, `offsets`, `gen_counters`, + Phase 5 adds `allowed_pe_routes`, `allowed_sm_routes`. 46 + - ✓ `SMConfig` at `emu/types.py:31-35`: `sm_id`, `cell_count=512`, `initial_cells: Optional[dict[int, tuple[Presence, Optional[int]]]]`. 47 + - ✓ `ALUInst` at `cm_inst.py:63-71`: `op`, `dest_l: Optional[Addr]`, `dest_r: Optional[Addr]`, `const: Optional[int]` — no defaults. 48 + - ✓ `SMInst` at `cm_inst.py:85-103`: `op`, `sm_id`, `const=None`, `ret=None`. 49 + - ✓ `MonadToken` at `tokens.py:32-34`: `target`, `offset`, `ctx`, `data`, `inline`. 50 + - ✓ `SMToken` at `tokens.py:50-56`: `target` (cell addr), `op`, `flags`, `data`, `ret`. 51 + - ✓ `CfgToken` at `tokens.py:74-76`: `target`, `addr`, `op: CfgOp`, `data: list`. 52 + - ✓ `System.inject(token)` and `System.inject_sm(sm_id, token)` at `emu/network.py:21-27`. 53 + - ✓ `Presence.FULL` from `sm_mod.py:11-15` needed for SMConfig `initial_cells`. 54 + 55 + --- 56 + 57 +  58 + 59 +  60 + ### Task 1: Implement codegen module with both output modes 61 + 62 + **Verifies:** or1-asm.AC8.1, or1-asm.AC8.2, or1-asm.AC8.3, or1-asm.AC8.4, or1-asm.AC8.5, or1-asm.AC8.6, or1-asm.AC8.7, or1-asm.AC8.8, or1-asm.AC8.9, or1-asm.AC8.10 63 + 64 + **Files:** 65 + - Create: `asm/codegen.py` 66 + 67 + **Implementation:** 68 + 69 + Create `asm/codegen.py` with two functions and a result type. 70 + 71 + **`AssemblyResult`** — Frozen dataclass: 72 + - `pe_configs: list[PEConfig]` 73 + - `sm_configs: list[SMConfig]` 74 + - `seed_tokens: list[MonadToken]` 75 + 76 + **`generate_direct(graph: IRGraph) -> AssemblyResult`:** 77 + 78 + Produces PEConfig/SMConfig lists and seed tokens from a fully allocated IRGraph. 79 + 80 + 1. **Build IRAM per PE:** Group all nodes by `node.pe`. For each PE, construct the `iram` dict mapping `node.iram_offset` to the appropriate instruction: 81 + - If `node.opcode` is an `ALUOp`: create `ALUInst(op=node.opcode, dest_l=node.dest_l.addr if node.dest_l else None, dest_r=node.dest_r.addr if node.dest_r else None, const=node.const)`. Extract `.addr` from `ResolvedDest` for each destination. 82 + - If `node.opcode` is a `MemOp`: create `SMInst(op=node.opcode, sm_id=node.sm_id, const=node.const, ret=node.dest_l.addr if node.dest_l else None)`. The `sm_id` field on `IRNode` is populated during the Lower pass (Phase 2) from the node's arguments or inferred from system config. 83 + 84 + 2. **Compute route restrictions per PE:** For each PE, analyse all edges involving nodes on that PE. Collect the set of destination PE IDs (from cross-PE edges) and SM IDs (from SM instructions). Include self-routes (the PE's own ID) for local routing. This produces `allowed_pe_routes` and `allowed_sm_routes` for the PEConfig. 85 + 86 + 3. **Build PEConfig per PE:** 87 + ```python 88 + PEConfig( 89 + pe_id=pe_id, 90 + iram=iram_dict, 91 + ctx_slots=graph.system.ctx_slots, 92 + offsets=graph.system.iram_capacity, 93 + allowed_pe_routes=computed_pe_routes, 94 + allowed_sm_routes=computed_sm_routes, 95 + ) 96 + ``` 97 + 98 + 4. **Build SMConfig per SM:** For each SM referenced in `graph.data_defs`, create `SMConfig(sm_id=sm_id, initial_cells={cell_addr: (Presence.FULL, value) for each data_def targeting this SM})`. Import `Presence` from `sm_mod`. 99 + 100 + 5. **Detect seed tokens:** Find all nodes with `RoutingOp.CONST` opcode that have no incoming edges (no edge in `graph.edges` has this node as `dest`). For each, create: 101 + ```python 102 + MonadToken( 103 + target=node.pe, 104 + offset=node.iram_offset, 105 + ctx=node.ctx, 106 + data=node.const or 0, 107 + inline=False, 108 + ) 109 + ``` 110 + 111 + 6. **Return** `AssemblyResult(pe_configs, sm_configs, seed_tokens)`. 112 + 113 + **`generate_tokens(graph: IRGraph) -> list`:** 114 + 115 + Produces an ordered bootstrap token sequence: 116 + 117 + 1. **SM init tokens** — For each data_def, create `SMToken(target=cell_addr, op=MemOp.WRITE, flags=None, data=value, ret=None)` paired with the SM ID for injection. 118 + 119 + 2. **ROUTE_SET tokens** — For each PE, create `CfgToken(target=pe_id, addr=None, op=CfgOp.ROUTE_SET, data=[list(pe_route_ids), list(sm_route_ids)])`. 120 + 121 + 3. **LOAD_INST tokens** — For each PE, create `CfgToken(target=pe_id, addr=0, op=CfgOp.LOAD_INST, data=list(iram_instructions_in_offset_order))`. 122 + 123 + 4. **Seed tokens** — Same MonadTokens as in direct mode. 124 + 125 + Return the concatenated list in this exact order: SM init → ROUTE_SET → LOAD_INST → seeds. 126 + 127 + **Edge cases:** 128 + - No data_defs → empty SM init section, no SMConfigs (AC8.9) 129 + - Single PE → ROUTE_SET with only self-route `[pe_id]` (AC8.10) 130 + 131 + **Verification:** 132 + ```bash 133 + python -c "from asm.codegen import generate_direct, generate_tokens, AssemblyResult; print('OK')" 134 + ``` 135 + 136 + **Commit:** `feat(asm): implement codegen with direct and token stream modes` 137 + 138 +  139 + 140 +  141 + ### Task 2: Codegen tests 142 + 143 + **Verifies:** or1-asm.AC8.1, or1-asm.AC8.2, or1-asm.AC8.3, or1-asm.AC8.4, or1-asm.AC8.5, or1-asm.AC8.6, or1-asm.AC8.7, or1-asm.AC8.8, or1-asm.AC8.9, or1-asm.AC8.10 144 + 145 + **Files:** 146 + - Create: `tests/test_codegen.py` 147 + 148 + **Implementation:** 149 + 150 + Tests that construct fully-allocated IRGraphs and run through codegen. Build helpers to create test graphs with resolved destinations. 151 + 152 + **Test classes:** 153 + 154 + **`TestDirectMode`** — AC8.1, AC8.2, AC8.3, AC8.4: 155 + - AC8.1: Graph with two nodes (ADD on pe0, CONST on pe0) → PEConfig has IRAM with ALUInst at correct offsets 156 + - AC8.2: Graph with data_def `@val|sm0:5 = 42` → SMConfig has `initial_cells={5: (Presence.FULL, 42)}` 157 + - AC8.3: Graph with CONST node and no incoming edges → seed_tokens contains MonadToken targeting correct PE/offset/ctx 158 + - AC8.4: Graph with cross-PE edge (pe0 → pe1) → PEConfig for pe0 has `allowed_pe_routes` containing pe1's ID 159 + 160 + **`TestTokenStream`** — AC8.5, AC8.6, AC8.7, AC8.8: 161 + - AC8.5-8.7: Generate token stream from a graph with data_defs, multiple PEs, and const nodes. Verify ordering: all SMTokens come before all ROUTE_SET CfgTokens, all ROUTE_SET before all LOAD_INST, all LOAD_INST before all seed MonadTokens. 162 + - AC8.8: Inject generated token stream into emulator via System.inject/inject_sm, run environment, verify execution produces correct results. 163 + 164 + **`TestEdgeCases`** — AC8.9, AC8.10: 165 + - AC8.9: Graph with no data_defs → `generate_direct().sm_configs` is empty; `generate_tokens()` has no SMToken entries 166 + - AC8.10: Single-PE graph → ROUTE_SET data contains only `[[pe_id], []]` or `[[pe_id], [sm_ids]]` 167 + 168 + **Verification:** 169 + ```bash 170 + python -m pytest tests/test_codegen.py -v 171 + ``` 172 + 173 + **Commit:** `test(asm): add codegen tests for direct mode, token stream, and edge cases` 174 + 175 +  176 +  177 + 178 +  179 + 180 +  181 + ### Task 3: Implement serializer (IRGraph → dfasm) 182 + 183 + **Verifies:** or1-asm.AC11.1, or1-asm.AC11.2, or1-asm.AC11.3, or1-asm.AC11.4, or1-asm.AC11.5, or1-asm.AC11.6, or1-asm.AC11.7, or1-asm.AC11.8 184 + 185 + **Files:** 186 + - Create: `asm/serialize.py` 187 + 188 + **Implementation:** 189 + 190 + Create `asm/serialize.py` with a `serialize(graph: IRGraph) -> str` function that converts an IRGraph back to valid dfasm source text. 191 + 192 + **Algorithm:** 193 + 194 + The serializer walks the IRGraph's region list in order, emitting text for each region and for top-level statements not inside any region. 195 + 196 + 1. **FUNCTION regions** — Emit `$name |> {`, then the body (nodes, edges, data_defs), then `}`. Nodes inside use unqualified &label names — strip the function scope prefix from node names (e.g., `$main.&add` → `&add`). 197 + 198 + 2. **LOCATION regions** — Emit the bare directive tag (e.g., `@data_section|sm0`), then the body's data definitions and other statements. 199 + 200 + 3. **Top-level statements** — Nodes/edges/data_defs not inside any region are emitted directly. 201 + 202 + **Emission rules:** 203 + 204 + - **inst_def:** `{qualified_ref}|pe{pe} <| {mnemonic}` with optional `, {const}` for const values. Use `OP_TO_MNEMONIC` from `asm.opcodes` for mnemonic lookup. 205 + 206 + - **plain_edge:** `{source_ref} |> {dest_ref}:{port}` for each edge. Emit one line per edge. 207 + 208 + - **data_def:** `{name}|sm{sm_id}:{cell_addr} = {hex_value}` 209 + 210 + - **Placement qualifiers:** Always emit `|pe{N}` on all nodes (AC11.3). This means even auto-placed nodes get explicit qualifiers in the output. 211 + 212 + - **Anonymous nodes:** Nodes with `__anon_` in their name are emitted as `inst_def + plain_edge` form (AC11.6), not back to inline edge syntax. 213 + 214 + - **Name unqualification in functions:** Inside a FUNCTION region body, strip the `$func.` prefix from &label names. The enclosing `$func |> { }` block implies the scope. 215 + 216 + - **Port formatting:** `Port.L` → `:L`, `Port.R` → `:R`. 217 + 218 + **Verification:** 219 + ```bash 220 + python -c "from asm.serialize import serialize; print('OK')" 221 + ``` 222 + 223 + **Commit:** `feat(asm): implement IRGraph → dfasm serializer` 224 + 225 +  226 + 227 +  228 + ### Task 4: Serialization tests 229 + 230 + **Verifies:** or1-asm.AC11.1, or1-asm.AC11.2, or1-asm.AC11.3, or1-asm.AC11.4, or1-asm.AC11.5, or1-asm.AC11.6, or1-asm.AC11.7, or1-asm.AC11.8 231 + 232 + **Files:** 233 + - Create: `tests/test_serialize.py` 234 + 235 + **Implementation:** 236 + 237 + **Test classes:** 238 + 239 + **`TestRoundTrip`** — AC11.1, AC11.2: 240 + - Parse a fully-specified dfasm program → lower → resolve → place → allocate → serialize → re-parse → lower → compare. The two IRGraphs should be structurally equivalent (same node names, opcodes, edges, data_defs). 241 + - Use multiple test programs: simple (2 nodes + 1 edge), complex (function with multiple nodes), data defs. 242 + 243 + **`TestPlacementQualifiers`** — AC11.3: 244 + - Serialize an IRGraph where all nodes have PE assignments → every `inst_def` line in output contains `|pe{N}`. 245 + 246 + **`TestFunctionScoping`** — AC11.4, AC11.7: 247 + - Serialize an IRGraph with a FUNCTION region → output contains `$name |> {` ... `}` block. 248 + - Node names inside the function block are unqualified (no `$func.` prefix). 249 + 250 + **`TestDataDefs`** — AC11.5: 251 + - Serialize an IRGraph with data_defs → output contains lines like `@name|sm0:5 = 0x2a`. 252 + 253 + **`TestAnonymousNodes`** — AC11.6: 254 + - Serialize an IRGraph with `__anon_` nodes → output uses `inst_def` + `plain_edge` form (named instructions and explicit edges). 255 + 256 + **`TestLocationRegions`** — AC11.8: 257 + - Serialize an IRGraph with a LOCATION region → output contains the bare directive tag followed by body contents. 258 + 259 + **Verification:** 260 + ```bash 261 + python -m pytest tests/test_serialize.py -v 262 + ``` 263 + 264 + **Commit:** `test(asm): add serialization round-trip and formatting tests` 265 + 266 +  267 +  268 + 269 +  270 + ### Task 5: Public API in asm/__init__.py 271 + 272 + **Verifies:** None (infrastructure — wires the pipeline together) 273 + 274 + **Files:** 275 + - Modify: `asm/__init__.py` 276 + 277 + **Implementation:** 278 + 279 + Wire up the full assembler pipeline as public API functions: 280 + 281 + ```python 282 + from lark import Lark 283 + from pathlib import Path 284 + 285 + from asm.lower import lower 286 + from asm.resolve import resolve 287 + from asm.place import place 288 + from asm.allocate import allocate 289 + from asm.codegen import generate_direct, generate_tokens, AssemblyResult 290 + from asm.serialize import serialize as _serialize_graph 291 + from asm.ir import IRGraph 292 + 293 + _GRAMMAR_PATH = Path(__file__).parent.parent / "dfasm.lark" 294 + _parser = None 295 + 296 + def _get_parser(): 297 + global _parser 298 + if _parser is None: 299 + _parser = Lark( 300 + _GRAMMAR_PATH.read_text(), 301 + parser="earley", 302 + propagate_positions=True, 303 + ) 304 + return _parser 305 + 306 + def assemble(source: str) -> AssemblyResult: 307 + """Assemble dfasm source to direct-mode emulator config.""" 308 + tree = _get_parser().parse(source) 309 + graph = lower(tree) 310 + graph = resolve(graph) 311 + if graph.errors: 312 + raise ValueError(f"Assembly errors: {graph.errors}") 313 + graph = place(graph) 314 + if graph.errors: 315 + raise ValueError(f"Placement errors: {graph.errors}") 316 + graph = allocate(graph) 317 + if graph.errors: 318 + raise ValueError(f"Allocation errors: {graph.errors}") 319 + return generate_direct(graph) 320 + 321 + def assemble_to_tokens(source: str) -> list: 322 + """Assemble dfasm source to hardware-faithful bootstrap token stream.""" 323 + tree = _get_parser().parse(source) 324 + graph = lower(tree) 325 + graph = resolve(graph) 326 + if graph.errors: 327 + raise ValueError(f"Assembly errors: {graph.errors}") 328 + graph = place(graph) 329 + if graph.errors: 330 + raise ValueError(f"Placement errors: {graph.errors}") 331 + graph = allocate(graph) 332 + if graph.errors: 333 + raise ValueError(f"Allocation errors: {graph.errors}") 334 + return generate_tokens(graph) 335 + 336 + def serialize_graph(graph: IRGraph) -> str: 337 + """Serialize an IRGraph to dfasm source text. 338 + 339 + Use this after any pipeline stage to inspect the IR: 340 + graph = lower(parse(source)) 341 + print(serialize_graph(graph)) # inspect after lowering 342 + """ 343 + return _serialize_graph(graph) 344 + 345 + def serialize(source: str) -> str: 346 + """Parse, lower, and serialize back to dfasm (convenience for round-trip testing).""" 347 + tree = _get_parser().parse(source) 348 + graph = lower(tree) 349 + return _serialize_graph(graph) 350 + ``` 351 + 352 + `serialize_graph()` accepts an `IRGraph` at any pipeline stage and converts it back to dfasm. This enables inspecting IR after lowering, resolution, placement, or allocation — useful for debugging auto-placement decisions or verifying pass outputs. 353 + 354 + `serialize()` is a convenience wrapper that parses source text, lowers, and serializes (for quick round-trip tests). 355 + 356 + **Verification:** 357 + ```bash 358 + python -c "from asm import assemble, assemble_to_tokens, serialize, serialize_graph; print('OK')" 359 + ``` 360 + 361 + **Commit:** `feat(asm): wire up public API (assemble, assemble_to_tokens, serialize, serialize_graph)` 362 + 363 +

+280

docs/implementation-plans/2026-02-22-or1-asm/phase_07.md

··· 1 + # OR1 Assembler — Phase 7: End-to-End Integration & Auto-Placement 2 + 3 + **Goal:** End-to-end assemble → emulate tests for reference programs, plus naive auto-placement. 4 + 5 + **Architecture:** Extend `asm/place.py` with a greedy bin-packing auto-placer that honours explicit annotations and uses a locality heuristic. Write end-to-end integration tests that assemble dfasm source, feed the output to the emulator, and verify correct execution results. Both direct and token stream modes must produce identical results. 6 + 7 + **Tech Stack:** Python 3.12, SimPy 4.1, pytest, Lark 8 + 9 + **Scope:** 7 phases from original design (this is phase 7 of 7) 10 + 11 + **Codebase verified:** 2026-02-22 12 + 13 + --- 14 + 15 + ## Acceptance Criteria Coverage 16 + 17 + This phase implements and tests: 18 + 19 + ### or1-asm.AC9: End-to-End 20 + - **or1-asm.AC9.1 Success:** CONST→ADD chain: two const nodes feed an add node, correct sum appears in output 21 + - **or1-asm.AC9.2 Success:** SM round-trip: write to SM cell, read back via deferred read, correct data returns 22 + - **or1-asm.AC9.3 Success:** Cross-PE routing: source node on PE0, dest node on PE1, token arrives correctly 23 + - **or1-asm.AC9.4 Success:** SWITCH routing: branch node routes data token to taken side, trigger to not-taken 24 + - **or1-asm.AC9.5 Success:** Both output modes (direct and token stream) produce identical execution results for same program 25 + 26 + ### or1-asm.AC10: Auto-Placement 27 + - **or1-asm.AC10.1 Success:** Unplaced nodes are assigned to PEs without exceeding IRAM or context slot limits 28 + - **or1-asm.AC10.2 Success:** Explicitly placed nodes are not moved by auto-placement 29 + - **or1-asm.AC10.3 Success:** Connected nodes prefer co-location on same PE (locality heuristic) 30 + - **or1-asm.AC10.4 Failure:** Program too large for available PEs produces error with per-PE utilization breakdown 31 + - **or1-asm.AC10.5 Success:** Auto-placed program assembles and executes correctly end-to-end 32 + 33 + --- 34 + 35 +  36 + 37 +  38 + ### Task 1: Implement auto-placement in asm/place.py 39 + 40 + **Verifies:** or1-asm.AC10.1, or1-asm.AC10.2, or1-asm.AC10.3, or1-asm.AC10.4 41 + 42 + **Files:** 43 + - Modify: `asm/place.py` (extend the existing placement validation pass) 44 + 45 + **Implementation:** 46 + 47 + Extend the `place()` function to handle unplaced nodes (those with `pe=None`) when auto-placement is enabled (which it should be by default; the existing Phase 4 validation should become a pre-check within the broader place function). 48 + 49 + **Auto-placement algorithm (greedy bin-packing with locality heuristic):** 50 + 51 + Per the design plan (lines 354-370): 52 + 53 + 1. **Honour explicitly placed nodes** — Nodes with `|peN` annotations keep their placement. 54 + 55 + 2. **Build adjacency info** — From edges, build a map of each node to its neighbours (connected nodes). 56 + 57 + 3. **Walk unplaced nodes in graph order** (iterate `graph.nodes` in insertion order). 58 + 59 + 4. **For each unplaced node:** 60 + a. Determine which PEs its connected neighbours are already placed on. 61 + b. Prefer the PE where the majority of neighbours live (locality heuristic). 62 + c. Tie-break by remaining IRAM capacity (most room wins). 63 + d. Track resource usage per PE: 64 + - IRAM slots used (dyadic nodes cost both an IRAM slot AND a matching store entry) 65 + - Context slots used (each new function body on a PE costs one slot) 66 + e. Validate capacity: IRAM count ≤ `graph.system.iram_capacity`, context count ≤ `graph.system.ctx_slots`. 67 + 68 + 5. **If no PE has room** → error with per-PE utilization breakdown: 69 + ``` 70 + error[PLACEMENT]: Cannot place node '&overflow_node': all PEs are full. 71 + PE0: 64/64 IRAM slots (32 dyadic, 32 monadic), 4/4 context slots 72 + PE1: 60/64 IRAM slots (30 dyadic, 30 monadic), 3/4 context slots 73 + ... 74 + ``` 75 + 76 + 6. **Return** new IRGraph with all nodes placed. 77 + 78 + **Integration with existing validation:** 79 + 80 + The `place()` function should: 81 + 1. First, validate explicitly placed nodes (existing logic from Phase 4). 82 + 2. Then, attempt to auto-place any nodes with `pe=None`. 83 + 3. If all nodes were already placed, auto-placement is a no-op. 84 + 4. If some nodes are unplaced and can't be placed → error. 85 + 86 + **Verification:** 87 + ```bash 88 + python -c "from asm.place import place; print('OK')" 89 + ``` 90 + 91 + **Commit:** `feat(asm): implement auto-placement with greedy bin-packing and locality heuristic` 92 + 93 +  94 + 95 +  96 + ### Task 2: Auto-placement tests 97 + 98 + **Verifies:** or1-asm.AC10.1, or1-asm.AC10.2, or1-asm.AC10.3, or1-asm.AC10.4 99 + 100 + **Files:** 101 + - Create: `tests/test_autoplacement.py` 102 + 103 + **Implementation:** 104 + 105 + Tests that construct IR-level graphs with mixed placed/unplaced nodes and run through `place()`. 106 + 107 + **Test classes:** 108 + 109 + **`TestBasicAutoPlacement`** — AC10.1: 110 + - Graph with 4 unplaced nodes and SystemConfig(pe_count=2) → all nodes get PE assignments, no PE exceeds IRAM or ctx limits. 111 + - Verify every node has `pe is not None` after placement. 112 + 113 + **`TestExplicitPreserved`** — AC10.2: 114 + - Mix of explicitly placed (pe=0, pe=1) and unplaced nodes → explicitly placed nodes retain their original PE assignment. 115 + - Verify placed nodes have same PE before and after. 116 + 117 + **`TestLocalityHeuristic`** — AC10.3: 118 + - Two connected nodes (edge between them), both unplaced, SystemConfig(pe_count=4) → they end up on the same PE (locality preference). 119 + - Cluster of 3 interconnected nodes → all on same PE. 120 + 121 + **`TestOverflow`** — AC10.4: 122 + - 200 unplaced nodes with SystemConfig(pe_count=2, iram_capacity=64) → error with utilization breakdown. 123 + - Error message includes per-PE slot counts. 124 + 125 + **Verification:** 126 + ```bash 127 + python -m pytest tests/test_autoplacement.py -v 128 + ``` 129 + 130 + **Commit:** `test(asm): add auto-placement tests for resource allocation and locality` 131 + 132 +  133 +  134 + 135 +  136 + 137 +  138 + ### Task 3: End-to-end integration tests (direct mode) 139 + 140 + **Verifies:** or1-asm.AC9.1, or1-asm.AC9.2, or1-asm.AC9.3, or1-asm.AC9.4 141 + 142 + **Files:** 143 + - Create: `tests/test_e2e.py` 144 + 145 + **Implementation:** 146 + 147 + End-to-end tests that assemble dfasm source via `asm.assemble()`, feed the result to `build_topology()`, inject seed tokens, run the emulator, and verify output. 148 + 149 + Helper function: 150 + ```python 151 + def run_program(source: str, collect_pe: int = 0, until: int = 1000) -> list: 152 + """Assemble source, run through emulator, collect output from specified PE.""" 153 + result = assemble(source) 154 + env = simpy.Environment() 155 + sys = build_topology(env, result.pe_configs, result.sm_configs) 156 + # Replace output routes with collector stores for verification 157 + collector = simpy.Store(env, capacity=100) 158 + # ... wire collector to capture output tokens 159 + for seed in result.seed_tokens: 160 + sys.inject(seed) 161 + env.run(until=until) 162 + return collector.items 163 + ``` 164 + 165 + **Reference programs:** 166 + 167 + **AC9.1 — CONST→ADD chain:** 168 + ``` 169 + @system pe=1, sm=0 170 + &c1|pe0 <| const, 3 171 + &c2|pe0 <| const, 7 172 + &result|pe0 <| add 173 + &c1|pe0 |> &result|pe0:L 174 + &c2|pe0 |> &result|pe0:R 175 + ``` 176 + Expected: `result` node fires with data = 10 (3 + 7). 177 + 178 + **AC9.2 — SM round-trip:** 179 + ``` 180 + @system pe=1, sm=1 181 + @val|sm0:5 = 0x42 182 + &trigger|pe0 <| const, 1 183 + &reader|pe0 <| read, 5 184 + &sink|pe0 <| pass 185 + &trigger|pe0 |> &reader|pe0:L 186 + &reader|pe0 |> &sink|pe0:L 187 + ``` 188 + This test uses the data_def to pre-initialize SM0 cell 5 with `0x42`. A `const` node fires a trigger token into `&reader`, which is a monadic `read` instruction with `const=5` (cell address). The allocator sets the `SMInst.ret` field from the outgoing edge to `&sink`. The SM reads cell 5 (FULL, value 0x42) and routes the result back to `&sink` via the return route. 189 + 190 + Expected: `sink` node fires with data = 0x42. 191 + 192 + **Note:** The SM `read` instruction's argument syntax (`read, 5`) specifies the cell address as `const`. The SM ID is inferred from the system config (single SM → sm_id=0) or from an explicit argument if the Lower pass supports it. The exact argument mapping for SM opcodes is defined by Phase 2's Transformer. 193 + 194 + **AC9.3 — Cross-PE routing:** 195 + ``` 196 + @system pe=2, sm=0 197 + &source|pe0 <| const, 99 198 + &dest|pe1 <| pass 199 + &source|pe0 |> &dest|pe1:L 200 + ``` 201 + Expected: `dest` on PE1 fires with data = 99. 202 + 203 + **AC9.4 — SWITCH routing:** 204 + ``` 205 + @system pe=1, sm=0 206 + &val|pe0 <| const, 5 207 + &cmp|pe0 <| const, 5 208 + &branch|pe0 <| sweq 209 + &taken|pe0 <| pass 210 + &not_taken|pe0 <| pass 211 + &val|pe0 |> &branch|pe0:L 212 + &cmp|pe0 |> &branch|pe0:R 213 + &branch|pe0:L |> &taken|pe0:L 214 + &branch|pe0:R |> &not_taken|pe0:L 215 + ``` 216 + The source-side port qualifiers (`:L` / `:R` on `&branch`) specify which output slot each edge originates from. `sweq` with equal inputs (5 == 5): `bool_out=True`, so data goes to `dest_l` (taken) and trigger goes to `dest_r` (not_taken). 217 + 218 + Expected: `taken` fires with data = 5, `not_taken` fires with trigger token. 219 + 220 + **Verification:** 221 + ```bash 222 + python -m pytest tests/test_e2e.py -v 223 + ``` 224 + 225 + **Commit:** `test(asm): add end-to-end integration tests for reference programs` 226 + 227 +  228 + 229 +  230 + ### Task 4: Token stream mode e2e + mode equivalence + auto-placed e2e 231 + 232 + **Verifies:** or1-asm.AC9.5, or1-asm.AC10.5 233 + 234 + **Files:** 235 + - Modify: `tests/test_e2e.py` (add token stream and auto-placement tests) 236 + 237 + **Implementation:** 238 + 239 + **AC9.5 — Mode equivalence:** 240 + 241 + For each reference program from Task 3, also run via `assemble_to_tokens()`. Inject the token stream into the emulator (SM init via `inject_sm`, CfgTokens and seed tokens via PE input stores). Compare outputs — both modes must produce identical results. 242 + 243 + Helper: 244 + ```python 245 + def run_program_tokens(source: str, collect_pe: int = 0, until: int = 1000) -> list: 246 + """Assemble source to token stream, inject into emulator, collect output.""" 247 + tokens = assemble_to_tokens(source) 248 + env = simpy.Environment() 249 + # Build minimal topology (empty PEs/SMs), let token stream configure them 250 + # ... inject tokens in order 251 + env.run(until=until) 252 + return collector.items 253 + ``` 254 + 255 + Test: for each reference program, assert `run_program(source)` output == `run_program_tokens(source)` output. 256 + 257 + **AC10.5 — Auto-placed e2e:** 258 + 259 + Write versions of the reference programs WITHOUT explicit `|peN` placement qualifiers (but with `@system pe=N`). The auto-placer should assign PEs and the programs should still execute correctly. 260 + 261 + ``` 262 + @system pe=2, sm=0 263 + &c1 <| const, 3 264 + &c2 <| const, 7 265 + &result <| add 266 + &c1 |> &result:L 267 + &c2 |> &result:R 268 + ``` 269 + 270 + Expected: same result as the explicitly-placed version (data = 10). 271 + 272 + **Verification:** 273 + ```bash 274 + python -m pytest tests/test_e2e.py -v 275 + ``` 276 + 277 + **Commit:** `test(asm): add token stream mode equivalence and auto-placed e2e tests` 278 + 279 +  280 +

+764

docs/implementation-plans/2026-02-22-or1-asm/test-requirements.md

··· 1 + # OR1 Assembler -- Test Requirements 2 + 3 + This document maps every acceptance criterion (`or1-asm.AC{N}.{M}`) to either an automated test or a documented human verification. Each criterion is traceable to its implementation phase, the test file that covers it, and the test type. 4 + 5 +  6 + 7 + --- 8 + 9 + ## Summary Table 10 + 11 + | AC ID | Description | Test Type | Test File | Phase | 12 + |---|---|---|---|---| 13 + | AC1.1 | ALU opcodes parse and map to ALUOp | Unit | `tests/test_opcodes.py` | 1 | 14 + | AC1.2 | SM opcodes parse and map to MemOp | Unit | `tests/test_opcodes.py`, `tests/test_parser.py` | 1 | 15 + | AC1.3 | Arity table correctness | Unit | `tests/test_opcodes.py` | 1 | 16 + | AC1.4 | Unknown opcode produces parse error | Unit | `tests/test_parser.py` | 1 | 17 + | AC2.1 | inst_def lowers to IRNode | Unit | `tests/test_lower.py` | 2 | 18 + | AC2.2 | plain_edge lowers to IREdge | Unit | `tests/test_lower.py` | 2 | 19 + | AC2.3 | strong_edge desugars to anon node + edges | Unit | `tests/test_lower.py` | 2 | 20 + | AC2.4 | weak_edge desugars identically to strong_edge | Unit | `tests/test_lower.py` | 2 | 21 + | AC2.5 | data_def lowers to IRDataDef | Unit | `tests/test_lower.py` | 2 | 22 + | AC2.6 | Multi-value data packs big-endian | Unit | `tests/test_lower.py` | 2 | 23 + | AC2.7 | @system pragma parsed into SystemConfig | Unit | `tests/test_lower.py` | 2 | 24 + | AC2.8 | Placement qualifiers populate IRNode.pe | Unit | `tests/test_lower.py` | 2 | 25 + | AC2.9 | Named args preserved in IRNode | Unit | `tests/test_lower.py` | 2 | 26 + | AC3.1 | &labels qualified with $func scope | Unit | `tests/test_lower.py` | 2 | 27 + | AC3.2 | @nodes remain global | Unit | `tests/test_lower.py` | 2 | 28 + | AC3.3 | Top-level &labels unqualified | Unit | `tests/test_lower.py` | 2 | 29 + | AC3.4 | Same &label in two functions no collision | Unit | `tests/test_lower.py` | 2 | 30 + | AC3.5 | Reserved name produces error | Unit | `tests/test_lower.py` | 2 | 31 + | AC3.6 | Duplicate &label produces error | Unit | `tests/test_lower.py` | 2 | 32 + | AC3.7 | func_def creates FUNCTION IRRegion | Unit | `tests/test_lower.py` | 2 | 33 + | AC3.8 | Location directive creates LOCATION IRRegion | Unit | `tests/test_lower.py` | 2 | 34 + | AC4.1 | Valid program resolves all references | Unit | `tests/test_resolve.py` | 3 | 35 + | AC4.2 | Cross-function @node wiring resolves | Unit | `tests/test_resolve.py` | 3 | 36 + | AC4.3 | Undefined &label produces error + suggestion | Unit | `tests/test_resolve.py` | 3 | 37 + | AC4.4 | Cross-scope &label produces scope error | Unit | `tests/test_resolve.py` | 3 | 38 + | AC4.5 | Did-you-mean uses Levenshtein distance | Unit | `tests/test_resolve.py` | 3 | 39 + | AC5.1 | Valid PE placements accepted | Unit | `tests/test_place.py` | 4 | 40 + | AC5.2 | Nonexistent PE produces error | Unit | `tests/test_place.py` | 4 | 41 + | AC5.3 | Unplaced node (no auto-placement) produces error | Unit | `tests/test_place.py` | 4 | 42 + | AC6.1 | Dyadic IRAM offsets packed at 0 | Unit | `tests/test_allocate.py` | 4 | 43 + | AC6.2 | Monadic offsets above dyadic range | Unit | `tests/test_allocate.py` | 4 | 44 + | AC6.3 | Distinct context slots per function per PE | Unit | `tests/test_allocate.py` | 4 | 45 + | AC6.4 | NameRef resolves to ResolvedDest w/ Addr | Unit | `tests/test_allocate.py` | 4 | 46 + | AC6.5 | Local edges produce same-PE Addr | Unit | `tests/test_allocate.py` | 4 | 47 + | AC6.6 | Cross-PE edges produce target-PE Addr | Unit | `tests/test_allocate.py` | 4 | 48 + | AC6.7 | IRAM overflow produces error | Unit | `tests/test_allocate.py` | 4 | 49 + | AC6.8 | Context slot overflow produces error | Unit | `tests/test_allocate.py` | 4 | 50 + | AC7.1 | ROUTE_SET CfgToken accepted by PE | Integration | `tests/test_pe.py` | 5 | 51 + | AC7.2 | After ROUTE_SET, listed PEs reachable | Integration | `tests/test_pe.py` | 5 | 52 + | AC7.3 | After ROUTE_SET, listed SMs reachable | Integration | `tests/test_pe.py` | 5 | 53 + | AC7.4 | After ROUTE_SET, unlisted PE raises KeyError | Integration | `tests/test_pe.py` | 5 | 54 + | AC7.5 | After ROUTE_SET, unlisted SM raises KeyError | Integration | `tests/test_pe.py` | 5 | 55 + | AC7.6 | PEConfig route fields restrict topology | Integration | `tests/test_network.py` | 5 | 56 + | AC7.7 | None routes preserve full-mesh (regression) | Integration | `tests/test_network.py` | 5 | 57 + | AC8.1 | Direct mode PEConfig has correct IRAM | Unit | `tests/test_codegen.py` | 6 | 58 + | AC8.2 | Direct mode SMConfig has initial cells | Unit | `tests/test_codegen.py` | 6 | 59 + | AC8.3 | Direct mode seed MonadTokens for const nodes | Unit | `tests/test_codegen.py` | 6 | 60 + | AC8.4 | Direct mode route restrictions match edges | Unit | `tests/test_codegen.py` | 6 | 61 + | AC8.5 | Token stream: SM init before ROUTE_SET | Unit | `tests/test_codegen.py` | 6 | 62 + | AC8.6 | Token stream: ROUTE_SET before LOAD_INST | Unit | `tests/test_codegen.py` | 6 | 63 + | AC8.7 | Token stream: LOAD_INST before seeds | Unit | `tests/test_codegen.py` | 6 | 64 + | AC8.8 | Token stream consumable by emulator | Integration | `tests/test_codegen.py` | 6 | 65 + | AC8.9 | No data_defs produces empty SM section | Unit | `tests/test_codegen.py` | 6 | 66 + | AC8.10 | Single PE ROUTE_SET has self-routes only | Unit | `tests/test_codegen.py` | 6 | 67 + | AC9.1 | CONST+ADD chain produces correct sum | E2E | `tests/test_e2e.py` | 7 | 68 + | AC9.2 | SM write+read round-trip returns data | E2E | `tests/test_e2e.py` | 7 | 69 + | AC9.3 | Cross-PE routing delivers token | E2E | `tests/test_e2e.py` | 7 | 70 + | AC9.4 | SWITCH routes data/trigger correctly | E2E | `tests/test_e2e.py` | 7 | 71 + | AC9.5 | Direct and token stream modes equivalent | E2E | `tests/test_e2e.py` | 7 | 72 + | AC10.1 | Auto-placement respects resource limits | Unit | `tests/test_autoplacement.py` | 7 | 73 + | AC10.2 | Explicit placements not moved | Unit | `tests/test_autoplacement.py` | 7 | 74 + | AC10.3 | Connected nodes prefer co-location | Unit | `tests/test_autoplacement.py` | 7 | 75 + | AC10.4 | Too-large program produces utilization error | Unit | `tests/test_autoplacement.py` | 7 | 76 + | AC10.5 | Auto-placed program executes correctly | E2E | `tests/test_e2e.py` | 7 | 77 + | AC11.1 | Serialized IRGraph re-parses without error | Integration | `tests/test_serialize.py` | 6 | 78 + | AC11.2 | Round-trip produces equivalent IRGraph | Integration | `tests/test_serialize.py` | 6 | 79 + | AC11.3 | Serialized output has PE qualifiers | Unit | `tests/test_serialize.py` | 6 | 80 + | AC11.4 | Serialized output preserves function scoping | Unit | `tests/test_serialize.py` | 6 | 81 + | AC11.5 | Serialized output includes data_defs | Unit | `tests/test_serialize.py` | 6 | 82 + | AC11.6 | Anonymous nodes serialize as inst_def+edge | Unit | `tests/test_serialize.py` | 6 | 83 + | AC11.7 | FUNCTION regions serialize as $name |> {...} | Unit | `tests/test_serialize.py` | 6 | 84 + | AC11.8 | LOCATION regions serialize as directive+body | Unit | `tests/test_serialize.py` | 6 | 85 + 86 + **Totals:** 68 acceptance criteria, 68 automated tests (0 human-only verification). 87 + 88 + --- 89 + 90 + ## Detailed Test Specifications by AC Group 91 + 92 + ### AC1: Grammar & Opcode Mapping 93 + 94 + **Implementation phase:** Phase 1 (Grammar Updates & Opcode Mapping) 95 + 96 + **Key implementation decisions affecting tests:** 97 + - SM memory ops added to the `OPCODE` terminal in `dfasm.lark`. The mnemonic `free_sm` disambiguates SM free from ALU `free`. 98 + - `asm/opcodes.py` provides `MNEMONIC_TO_OP`, `OP_TO_MNEMONIC`, `MONADIC_OPS`, `is_monadic()`, and `is_dyadic()`. 99 + - `MemOp.WRITE` arity is context-dependent: monadic when `const` is set (cell addr from const), dyadic when `const is None` (cell addr from left operand). `MemOp.CMP_SW` is always dyadic. The `is_monadic(op, const)` function takes an optional `const` parameter to handle this. 100 + - Grammar tokens `ior`, `iow`, `iorw`, `brty`, `swty` are parse-valid but NOT in `MNEMONIC_TO_OP`. They will be caught as unsupported opcodes in the Lower pass (Phase 2), not at the grammar level. 101 + 102 + #### or1-asm.AC1.1 -- ALU opcodes parse and map to ALUOp 103 + - **Test type:** Unit 104 + - **File:** `tests/test_opcodes.py` 105 + - **Test class/method:** `TestMnemonicMapping` (parametrized) 106 + - **Approach:** Enumerate all 30 ALU opcode mnemonics from the design (`add`, `sub`, `inc`, `dec`, `shiftl`, `shiftr`, `ashiftr`, `and`, `or`, `xor`, `not`, `eq`, `lt`, `lte`, `gt`, `gte`, `breq`, `brgt`, `brge`, `brof`, `sweq`, `swgt`, `swge`, `swof`, `gate`, `sel`, `merge`, `pass`, `const`, `free`). For each, assert `MNEMONIC_TO_OP[mnemonic]` returns the correct `ALUOp` subclass value (e.g., `ArithOp.ADD`, `LogicOp.NOT`, `RoutingOp.CONST`). 107 + - **Verification:** Also verify `OP_TO_MNEMONIC[MNEMONIC_TO_OP[m]] == m` for round-trip fidelity. 108 + 109 + #### or1-asm.AC1.2 -- SM opcodes parse and map to MemOp 110 + - **Test type:** Unit 111 + - **Files:** `tests/test_opcodes.py`, `tests/test_parser.py` 112 + - **Test class/method:** `TestMnemonicMapping` (parametrized) in `test_opcodes.py`; `TestSMOps` in `test_parser.py` 113 + - **Approach (opcodes):** Enumerate all 8 SM mnemonics (`read`, `write`, `clear`, `alloc`, `free_sm`, `rd_inc`, `rd_dec`, `cmp_sw`). Assert each maps to the correct `MemOp` value (e.g., `MemOp.READ`, `MemOp.FREE`). 114 + - **Approach (parser):** Parse each SM op in a minimal `inst_def` context (e.g., `&cell <| read`) and verify it produces a valid parse tree. This validates the grammar change. 115 + 116 + #### or1-asm.AC1.3 -- Arity table correctly classifies opcodes 117 + - **Test type:** Unit 118 + - **File:** `tests/test_opcodes.py` 119 + - **Test class/method:** `TestArityClassification` (parametrized) 120 + - **Approach:** Test `is_monadic()` and `is_dyadic()` for all opcodes. Parametrize with known monadic ops (`INC`, `DEC`, `SHIFT_L`, `SHIFT_R`, `ASHFT_R`, `NOT`, `PASS`, `CONST`, `FREE`, `MemOp.READ`, `MemOp.ALLOC`, `MemOp.FREE`, `MemOp.CLEAR`, `MemOp.RD_INC`, `MemOp.RD_DEC`) and known dyadic ops (`ADD`, `SUB`, `AND`, `OR`, `XOR`, `EQ`, `LT`, `LTE`, `GT`, `GTE`, `BREQ`, `BRGT`, `BRGE`, `BROF`, `SWEQ`, `SWGT`, `SWGE`, `SWOF`, `GATE`, `SEL`, `MRGE`, `MemOp.CMP_SW`). 121 + - **Special case:** `MemOp.WRITE` must be tested with both `const=5` (monadic) and `const=None` (dyadic). 122 + 123 + #### or1-asm.AC1.4 -- Unknown opcode produces parse error 124 + - **Test type:** Unit 125 + - **File:** `tests/test_parser.py` 126 + - **Test class/method:** `TestSMOps::test_unknown_opcode` or similar 127 + - **Approach:** Parse `&x <| foobar` and assert it raises a Lark parse exception (e.g., `lark.exceptions.UnexpectedToken`). Verify that the error includes source location information (line/column). 128 + 129 + --- 130 + 131 + ### AC2: Lower Pass -- Instruction & Edge Handling 132 + 133 + **Implementation phase:** Phase 2 (IR Types & Lower Pass) 134 + 135 + **Key implementation decisions affecting tests:** 136 + - The Lower pass is a Lark `Transformer` subclass (`LowerTransformer`) invoked via `lower(tree) -> IRGraph`. 137 + - IRNode uses `sm_id: Optional[int]` instead of the design's `sm_inst: Optional[SMInst]`, because the full `SMInst` (including `ret` address) is only constructible after destination resolution. This deviation is documented in Phase 2, Task 1. 138 + - `@system` pragma is parsed via a dedicated `system_pragma` grammar rule added in Phase 1. 139 + - IREdge has both `port` (destination input port) and `source_port` (source output slot) fields. `source_port` is extracted from the source `qualified_ref`'s port qualifier. 140 + 141 + #### or1-asm.AC2.1 -- inst_def lowers to IRNode 142 + - **Test type:** Unit 143 + - **File:** `tests/test_lower.py` 144 + - **Test class/method:** `TestInstDef` 145 + - **Approach:** Parse `&my_add <| add` through parser + `lower()`. Assert the resulting `IRGraph.nodes` contains a node keyed `"&my_add"` with `opcode == ArithOp.ADD`. Also test `&my_const <| const, 42` produces `IRNode(const=42)`. 146 + 147 + #### or1-asm.AC2.2 -- plain_edge lowers to IREdge 148 + - **Test type:** Unit 149 + - **File:** `tests/test_lower.py` 150 + - **Test class/method:** `TestPlainEdge` 151 + - **Approach:** Parse `&a <| pass` + `&b <| add` + `&a |> &b:L`. Assert `IRGraph.edges` contains an `IREdge(source="&a", dest="&b", port=Port.L)`. Also test `:R` port and fanout (`&a |> &b, &c` producing two edges). 152 + 153 + #### or1-asm.AC2.3 -- strong_edge desugars to anon node + edges 154 + - **Test type:** Unit 155 + - **File:** `tests/test_lower.py` 156 + - **Test class/method:** `TestStrongEdge` 157 + - **Approach:** Parse `add &a, &b |> &c, &d` (with prerequisite `&a`, `&b`, `&c`, `&d` definitions). Assert an anonymous IRNode (name matching `&__anon_*`) with `ArithOp.ADD` exists, plus edges: `&a -> anon:L`, `&b -> anon:R`, `anon -> &c`, `anon -> &d`. 158 + 159 + #### or1-asm.AC2.4 -- weak_edge desugars identically 160 + - **Test type:** Unit 161 + - **File:** `tests/test_lower.py` 162 + - **Test class/method:** `TestWeakEdge` 163 + - **Approach:** Parse `&c, &d sub <| &a, &b` and the equivalent strong edge `sub &a, &b |> &c, &d`. Compare the two IRGraphs structurally: same anonymous node opcode, same edge topology (ignoring anonymous node name suffixes). 164 + 165 + #### or1-asm.AC2.5 -- data_def lowers to IRDataDef 166 + - **Test type:** Unit 167 + - **File:** `tests/test_lower.py` 168 + - **Test class/method:** `TestDataDef` 169 + - **Approach:** Parse `@hello|sm0:0 = 0x05`. Assert `IRGraph.data_defs` contains `IRDataDef(name="@hello", sm_id=0, cell_addr=0, value=5)`. 170 + 171 + #### or1-asm.AC2.6 -- Multi-value data packs big-endian 172 + - **Test type:** Unit 173 + - **File:** `tests/test_lower.py` 174 + - **Test class/method:** `TestDataDef::test_multi_value_packing` 175 + - **Approach:** Parse `@hello|sm0:1 = 'h', 'e'`. Assert `value == 0x6865` (big-endian: `ord('h') << 8 | ord('e')`). Also test single char and odd-count char packing. 176 + 177 + #### or1-asm.AC2.7 -- @system pragma parsed into SystemConfig 178 + - **Test type:** Unit 179 + - **File:** `tests/test_lower.py` 180 + - **Test class/method:** `TestSystemConfig` 181 + - **Approach:** Parse `@system pe=4, sm=1`. Assert `IRGraph.system == SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4)` (defaults for iram/ctx). Also test `@system pe=4, sm=1, iram=128, ctx=2` produces `SystemConfig(pe_count=4, sm_count=1, iram_capacity=128, ctx_slots=2)`. 182 + 183 + #### or1-asm.AC2.8 -- Placement qualifiers populate IRNode.pe 184 + - **Test type:** Unit 185 + - **File:** `tests/test_lower.py` 186 + - **Test class/method:** `TestInstDef::test_placement` 187 + - **Approach:** Parse `&my_add|pe0 <| add`. Assert `IRGraph.nodes["&my_add"].pe == 0`. 188 + 189 + #### or1-asm.AC2.9 -- Named args preserved in IRNode 190 + - **Test type:** Unit 191 + - **File:** `tests/test_lower.py` 192 + - **Test class/method:** `TestInstDef::test_named_args` 193 + - **Approach:** Parse `&serial <| ior, dest=0x45`. Since `ior` is not in `MNEMONIC_TO_OP`, this should produce an error in `IRGraph.errors` with `ErrorCategory.PARSE`. If a mapped opcode with named args is used instead (as a fallback test), verify `IRNode.args` dict contains the named argument. The edge case is that AC2.9 specifically uses `ior`, which is an unsupported opcode. The test should assert either: (a) the error is raised, or (b) if a fallback opcode is used, the named arg is preserved. Per Phase 2 design, the Lower pass maps the opcode via `MNEMONIC_TO_OP` and adds an error for unmapped mnemonics, so the primary test validates the error path. A secondary test with a valid opcode + named arg validates preservation. 194 + 195 + --- 196 + 197 + ### AC3: Lower Pass -- Scoping 198 + 199 + **Implementation phase:** Phase 2 (IR Types & Lower Pass) 200 + 201 + **Key implementation decisions affecting tests:** 202 + - Name qualification happens during the Lower pass via `LowerTransformer._func_scope`. 203 + - `IRRegion` with `RegionKind.FUNCTION` wraps function bodies; `RegionKind.LOCATION` wraps location directive scopes. 204 + - Reserved names: `@system`, `@io`, `@debug`. 205 + - Duplicate detection uses `_defined_names: dict[str, SourceLoc]`. 206 + 207 + #### or1-asm.AC3.1 -- &labels qualified with $func scope 208 + - **Test type:** Unit 209 + - **File:** `tests/test_lower.py` 210 + - **Test class/method:** `TestFunctionScoping::test_label_qualification` 211 + - **Approach:** Parse `$main |> { &add <| add }`. Assert node is keyed as `"$main.&add"` in the IRGraph. 212 + 213 + #### or1-asm.AC3.2 -- @nodes remain global 214 + - **Test type:** Unit 215 + - **File:** `tests/test_lower.py` 216 + - **Test class/method:** `TestFunctionScoping::test_global_node` 217 + - **Approach:** Parse `@global_node <| pass` (at top level or inside a function). Assert node is keyed as `"@global_node"` with no function prefix. 218 + 219 + #### or1-asm.AC3.3 -- Top-level &labels unqualified 220 + - **Test type:** Unit 221 + - **File:** `tests/test_lower.py` 222 + - **Test class/method:** `TestFunctionScoping::test_top_level_label` 223 + - **Approach:** Parse `&top <| pass` at top level (outside any `$func`). Assert node is keyed as `"&top"`. 224 + 225 + #### or1-asm.AC3.4 -- Two functions each define &add without collision 226 + - **Test type:** Unit 227 + - **File:** `tests/test_lower.py` 228 + - **Test class/method:** `TestFunctionScoping::test_no_collision` 229 + - **Approach:** Parse `$foo |> { &add <| add }` and `$bar |> { &add <| sub }`. Assert two distinct nodes exist: `"$foo.&add"` and `"$bar.&add"`, with different opcodes. 230 + 231 + #### or1-asm.AC3.5 -- Reserved name produces error 232 + - **Test type:** Unit 233 + - **File:** `tests/test_lower.py` 234 + - **Test class/method:** `TestErrorCases::test_reserved_name` 235 + - **Approach:** Parse `@system <| add`. Assert `IRGraph.errors` contains an error with `ErrorCategory.NAME` and a message mentioning "reserved". Verify error has source location (line, column). 236 + 237 + #### or1-asm.AC3.6 -- Duplicate &label produces error 238 + - **Test type:** Unit 239 + - **File:** `tests/test_lower.py` 240 + - **Test class/method:** `TestErrorCases::test_duplicate_label` 241 + - **Approach:** Parse a program with two `&add <| add` definitions in the same function scope. Assert `IRGraph.errors` contains an error with `ErrorCategory.SCOPE` mentioning "duplicate". 242 + 243 + #### or1-asm.AC3.7 -- func_def creates FUNCTION IRRegion 244 + - **Test type:** Unit 245 + - **File:** `tests/test_lower.py` 246 + - **Test class/method:** `TestRegions::test_function_region` 247 + - **Approach:** Parse `$func |> { &a <| add }`. Assert `IRGraph.regions` contains an `IRRegion(tag="$func", kind=RegionKind.FUNCTION)` whose `body` sub-graph contains the `&a` node (or `$func.&a`). 248 + 249 + #### or1-asm.AC3.8 -- Location directive creates LOCATION IRRegion 250 + - **Test type:** Unit 251 + - **File:** `tests/test_lower.py` 252 + - **Test class/method:** `TestRegions::test_location_region` 253 + - **Approach:** Parse `@data_section|sm0` followed by data definitions. Assert `IRGraph.regions` contains an `IRRegion` with `kind=RegionKind.LOCATION` whose body contains the data definitions. 254 + 255 + --- 256 + 257 + ### AC4: Name Resolution 258 + 259 + **Implementation phase:** Phase 3 (Name Resolution) 260 + 261 + **Key implementation decisions affecting tests:** 262 + - Resolution is a flat dict lookup against a flattened node dict (nodes from all scopes, keyed by qualified name). 263 + - The resolve pass does NOT convert `NameRef` to `ResolvedDest` -- it only validates that references exist. Actual destination resolution happens in Phase 4 (Allocate). 264 + - Levenshtein distance is implemented as a standard DP algorithm in `asm/resolve.py`. Suggestions are offered for names with distance <= 3. 265 + - Scope violation detection: when `&label` fails to resolve, the resolver checks if `$func.&label` exists in any function scope. 266 + 267 + #### or1-asm.AC4.1 -- Valid program resolves all references 268 + - **Test type:** Unit 269 + - **File:** `tests/test_resolve.py` 270 + - **Test class/method:** `TestValidResolution::test_simple_resolution` 271 + - **Approach:** Parse+lower a simple program with two nodes and an edge between them. Run `resolve()`. Assert `graph.errors` is empty. 272 + 273 + #### or1-asm.AC4.2 -- Cross-function @node wiring resolves 274 + - **Test type:** Unit 275 + - **File:** `tests/test_resolve.py` 276 + - **Test class/method:** `TestValidResolution::test_cross_function_global` 277 + - **Approach:** Parse+lower a program with `$foo |> { &a <| pass }`, `$bar |> { &b <| add }`, `@bridge <| pass`, and edges wiring through `@bridge`. Run `resolve()`. Assert no errors. 278 + 279 + #### or1-asm.AC4.3 -- Undefined &label produces error with suggestion 280 + - **Test type:** Unit 281 + - **File:** `tests/test_resolve.py` 282 + - **Test class/method:** `TestUndefinedReference::test_undefined_label` 283 + - **Approach:** Parse+lower a program with an edge referencing `&nonexistent`. Run `resolve()`. Assert error with `ErrorCategory.NAME`, message includes "undefined", and source location is present. If a similar name exists (e.g., `&nonexistant` vs `&nonexistent`), assert suggestion is present. 284 + 285 + #### or1-asm.AC4.4 -- Cross-scope &label produces scope violation error 286 + - **Test type:** Unit 287 + - **File:** `tests/test_resolve.py` 288 + - **Test class/method:** `TestScopeViolation::test_cross_scope_reference` 289 + - **Approach:** Parse+lower `$foo |> { &private <| pass }` with a top-level edge referencing `&private` (unqualified). Run `resolve()`. Assert error message identifies that `&private` exists in `$foo` scope. 290 + 291 + #### or1-asm.AC4.5 -- Did-you-mean uses Levenshtein distance 292 + - **Test type:** Unit 293 + - **File:** `tests/test_resolve.py` 294 + - **Test class/method:** `TestLevenshteinSuggestions` 295 + - **Approach:** (1) Test `_levenshtein` function directly: `_levenshtein("kitten", "sitting") == 3`. (2) Parse+lower a program with reference to `&ad` when `&add` exists. Run `resolve()`. Assert suggestion includes `&add`. (3) Test that very distant names produce no suggestion or best-effort. 296 + 297 + --- 298 + 299 + ### AC5: Placement 300 + 301 + **Implementation phase:** Phase 4 (Placement Validation & Allocation) 302 + 303 + **Key implementation decisions affecting tests:** 304 + - Phase 4 implements placement validation only; auto-placement is Phase 7. 305 + - `place()` infers `pe_count` from max PE ID + 1 if `graph.system` is None. 306 + - Tests construct IRGraphs directly (not via parsing), operating at the IR level. 307 + 308 + #### or1-asm.AC5.1 -- Valid PE placements accepted 309 + - **Test type:** Unit 310 + - **File:** `tests/test_place.py` 311 + - **Test class/method:** `TestValidPlacement` 312 + - **Approach:** Construct IRGraph with nodes on pe0, pe1, pe2, pe3 and `SystemConfig(pe_count=4)`. Run `place()`. Assert no errors. 313 + 314 + #### or1-asm.AC5.2 -- Nonexistent PE produces error 315 + - **Test type:** Unit 316 + - **File:** `tests/test_place.py` 317 + - **Test class/method:** `TestNonexistentPE` 318 + - **Approach:** Construct IRGraph with a node on pe9, `SystemConfig(pe_count=4)`. Run `place()`. Assert error with `ErrorCategory.PLACEMENT` mentioning PE9 and available range (0-3). 319 + 320 + #### or1-asm.AC5.3 -- Unplaced node produces error 321 + - **Test type:** Unit 322 + - **File:** `tests/test_place.py` 323 + - **Test class/method:** `TestUnplacedNode` 324 + - **Approach:** Construct IRGraph with a node having `pe=None`. Run `place()` (before Phase 7 auto-placement). Assert error identifying the unplaced node name and suggesting `|peN` qualifier. 325 + 326 + --- 327 + 328 + ### AC6: Resource Allocation 329 + 330 + **Implementation phase:** Phase 4 (Placement Validation & Allocation) 331 + 332 + **Key implementation decisions affecting tests:** 333 + - Dyadic-first IRAM packing: dyadic instructions at offsets 0..D-1, monadic/SM at D..M-1. 334 + - Context slots: one per function body per PE. Root scope / first function gets ctx=0. 335 + - `MemOp.WRITE` arity depends on `const`: monadic when const is set, dyadic when None. 336 + - Edge-to-destination mapping uses `source_port` (source-side port qualifier) to determine which output slot an edge occupies. This is critical for SWITCH ops. 337 + - Capacity limits come from `graph.system.iram_capacity` and `graph.system.ctx_slots` (defaults 64, 4). 338 + - Tests construct IR-level graphs directly. 339 + 340 + #### or1-asm.AC6.1 -- Dyadic IRAM offsets packed at 0 341 + - **Test type:** Unit 342 + - **File:** `tests/test_allocate.py` 343 + - **Test class/method:** `TestIRAMPacking::test_dyadic_packed_first` 344 + - **Approach:** Construct a PE with 2 dyadic (ADD, SUB) and 2 monadic (INC, CONST) nodes. Run `allocate()`. Assert dyadic nodes have `iram_offset` in {0, 1} and monadic nodes have `iram_offset` in {2, 3}. 345 + 346 + #### or1-asm.AC6.2 -- Monadic offsets above dyadic range 347 + - **Test type:** Unit 348 + - **File:** `tests/test_allocate.py` 349 + - **Test class/method:** `TestIRAMPacking::test_monadic_above_dyadic` 350 + - **Approach:** Same test as AC6.1, asserting all monadic offsets are strictly greater than all dyadic offsets. Also test a PE with only monadic ops (offsets start at 0) and only dyadic ops (contiguous from 0). 351 + 352 + #### or1-asm.AC6.3 -- Distinct context slots per function per PE 353 + - **Test type:** Unit 354 + - **File:** `tests/test_allocate.py` 355 + - **Test class/method:** `TestContextSlots` 356 + - **Approach:** Construct PE with nodes from `$main` and `$helper`. Run `allocate()`. Assert `$main` nodes have `ctx=0`, `$helper` nodes have `ctx=1` (or vice versa, so long as they differ). Also test single function (all ctx=0) and top-level nodes (ctx=0). 357 + 358 + #### or1-asm.AC6.4 -- NameRef resolves to ResolvedDest w/ Addr 359 + - **Test type:** Unit 360 + - **File:** `tests/test_allocate.py` 361 + - **Test class/method:** `TestDestinationResolution::test_resolved_addr` 362 + - **Approach:** Construct graph with node A (`dest_l=NameRef("B", Port.L)`) and node B. Run `allocate()`. Assert A's `dest_l` is a `ResolvedDest` with `.name == "B"` and `.addr == Addr(a=B.iram_offset, port=Port.L, pe=B.pe)`. 363 + 364 + #### or1-asm.AC6.5 -- Local edges produce same-PE Addr 365 + - **Test type:** Unit 366 + - **File:** `tests/test_allocate.py` 367 + - **Test class/method:** `TestDestinationResolution::test_local_edge` 368 + - **Approach:** Both nodes on pe0. After `allocate()`, assert `ResolvedDest.addr.pe` equals the source PE (pe0). 369 + 370 + #### or1-asm.AC6.6 -- Cross-PE edges produce target-PE Addr 371 + - **Test type:** Unit 372 + - **File:** `tests/test_allocate.py` 373 + - **Test class/method:** `TestDestinationResolution::test_cross_pe_edge` 374 + - **Approach:** Source on pe0, dest on pe1. After `allocate()`, assert `ResolvedDest.addr.pe == 1`. 375 + 376 + #### or1-asm.AC6.7 -- IRAM overflow produces error 377 + - **Test type:** Unit 378 + - **File:** `tests/test_allocate.py` 379 + - **Test class/method:** `TestOverflow::test_iram_overflow` 380 + - **Approach:** Construct PE with 65 nodes and `SystemConfig(iram_capacity=64)`. Run `allocate()`. Assert error with `ErrorCategory.RESOURCE`, message mentions node count and capacity. Also test with custom `iram_capacity=8` and 9 nodes. 381 + 382 + #### or1-asm.AC6.8 -- Context slot overflow produces error 383 + - **Test type:** Unit 384 + - **File:** `tests/test_allocate.py` 385 + - **Test class/method:** `TestOverflow::test_context_overflow` 386 + - **Approach:** Construct PE with 5 function bodies and `SystemConfig(ctx_slots=4)`. Run `allocate()`. Assert error with `ErrorCategory.RESOURCE`, message lists all function names. Also test custom `ctx_slots=2` with 3 functions. 387 + 388 + --- 389 + 390 + ### AC7: Emulator ROUTE_SET 391 + 392 + **Implementation phase:** Phase 5 (Emulator ROUTE_SET Support) 393 + 394 + **Key implementation decisions affecting tests:** 395 + - ROUTE_SET data format: `[pe_ids_list, sm_ids_list]` (list of two lists), NOT the dict format from the original design. This keeps `CfgToken.data` uniformly typed as `list`. 396 + - PEConfig fields: `allowed_pe_routes: Optional[set[int]]`, `allowed_sm_routes: Optional[set[int]]` (using `allowed_` prefix to avoid confusion with runtime `route_table`/`sm_routes` dicts). 397 + - `build_topology()` applies route restrictions post-hoc (filter full-mesh after wiring). 398 + - KeyError for unlisted routes is the natural dict access failure -- no special error handling needed. 399 + - All existing emulator tests must pass unchanged (backwards compatibility via `None` defaults). 400 + 401 + #### or1-asm.AC7.1 -- ROUTE_SET CfgToken accepted by PE 402 + - **Test type:** Integration 403 + - **File:** `tests/test_pe.py` 404 + - **Test class/method:** `TestRouteSet::test_route_set_accepted` 405 + - **Approach:** Create PE with full-mesh routes (3 PEs, 1 SM). Send `CfgToken(op=CfgOp.ROUTE_SET, data=[[0, 2], [0]])`. Assert no warning logged. Verify `route_table` keys become {0, 2} and `sm_routes` keys become {0}. 406 + 407 + #### or1-asm.AC7.2 -- After ROUTE_SET, listed PEs reachable 408 + - **Test type:** Integration 409 + - **File:** `tests/test_pe.py` 410 + - **Test class/method:** `TestRouteSet::test_listed_pe_reachable` 411 + - **Approach:** After ROUTE_SET allowing PE 0 and PE 2, send a token routed to PE 0 or PE 2. Assert it arrives in the target store. 412 + 413 + #### or1-asm.AC7.3 -- After ROUTE_SET, listed SMs reachable 414 + - **Test type:** Integration 415 + - **File:** `tests/test_pe.py` 416 + - **Test class/method:** `TestRouteSet::test_listed_sm_reachable` 417 + - **Approach:** After ROUTE_SET allowing SM 0, emit an SM token to SM 0. Assert it arrives. 418 + 419 + #### or1-asm.AC7.4 -- After ROUTE_SET, unlisted PE raises KeyError 420 + - **Test type:** Integration 421 + - **File:** `tests/test_pe.py` 422 + - **Test class/method:** `TestRouteSet::test_unlisted_pe_raises` 423 + - **Approach:** After ROUTE_SET allowing only PE 0, attempt to route to PE 1. Since this occurs inside a SimPy process, catch the exception from the environment run and assert it is a `KeyError`. 424 + 425 + #### or1-asm.AC7.5 -- After ROUTE_SET, unlisted SM raises KeyError 426 + - **Test type:** Integration 427 + - **File:** `tests/test_pe.py` 428 + - **Test class/method:** `TestRouteSet::test_unlisted_sm_raises` 429 + - **Approach:** After ROUTE_SET allowing only SM 0, attempt to emit SM token to SM 1. Catch `KeyError` from the SimPy process. 430 + 431 + #### or1-asm.AC7.6 -- PEConfig route fields restrict topology 432 + - **Test type:** Integration 433 + - **File:** `tests/test_network.py` 434 + - **Test class/method:** `TestRestrictedTopology::test_peconfig_restricts_routes` 435 + - **Approach:** Build topology with `PEConfig(pe_id=0, iram={}, allowed_pe_routes={1}, allowed_sm_routes={0})`. Verify PE 0's `route_table` has only key 1 and `sm_routes` has only key 0. 436 + 437 + #### or1-asm.AC7.7 -- None routes preserve full-mesh (regression) 438 + - **Test type:** Integration 439 + - **File:** `tests/test_network.py` 440 + - **Test class/method:** `TestRestrictedTopology::test_default_full_mesh` 441 + - **Approach:** Build topology with default `PEConfig` (no route restrictions, fields are `None`). Verify PE gets full-mesh `route_table` with all PE IDs and `sm_routes` with all SM IDs. Additionally, confirm all existing emulator tests pass unchanged (pytest run of full test suite). 442 + 443 + --- 444 + 445 + ### AC8: Codegen 446 + 447 + **Implementation phase:** Phase 6 (Codegen) 448 + 449 + **Key implementation decisions affecting tests:** 450 + - `generate_direct(graph) -> AssemblyResult` with `pe_configs`, `sm_configs`, `seed_tokens`. 451 + - `generate_tokens(graph) -> list` producing ordered bootstrap sequence. 452 + - ALU nodes produce `ALUInst`; SM nodes produce `SMInst` with `ret=node.dest_l.addr`. 453 + - Seed tokens: `RoutingOp.CONST` nodes with no incoming edges produce `MonadToken`. 454 + - SMConfig uses `initial_cells={cell_addr: (Presence.FULL, value)}` from data_defs. 455 + - Route restrictions computed from edge analysis (outgoing edges + SM instructions). 456 + - Token stream ordering: SM init -> ROUTE_SET -> LOAD_INST -> seeds. 457 + 458 + #### or1-asm.AC8.1 -- Direct mode PEConfig has correct IRAM 459 + - **Test type:** Unit 460 + - **File:** `tests/test_codegen.py` 461 + - **Test class/method:** `TestDirectMode::test_iram_contents` 462 + - **Approach:** Construct allocated graph with ADD and CONST nodes. Run `generate_direct()`. Assert `PEConfig.iram` dict has `ALUInst` at the ADD node's offset and an appropriate instruction at the CONST offset, with correct `dest_l`, `dest_r`, and `const` values. 463 + 464 + #### or1-asm.AC8.2 -- Direct mode SMConfig has initial cells 465 + - **Test type:** Unit 466 + - **File:** `tests/test_codegen.py` 467 + - **Test class/method:** `TestDirectMode::test_sm_initial_cells` 468 + - **Approach:** Construct graph with `IRDataDef(sm_id=0, cell_addr=5, value=42)`. Run `generate_direct()`. Assert `SMConfig.initial_cells == {5: (Presence.FULL, 42)}`. 469 + 470 + #### or1-asm.AC8.3 -- Direct mode seed MonadTokens 471 + - **Test type:** Unit 472 + - **File:** `tests/test_codegen.py` 473 + - **Test class/method:** `TestDirectMode::test_seed_tokens` 474 + - **Approach:** Construct graph with a CONST node having no incoming edges. Run `generate_direct()`. Assert `seed_tokens` contains a `MonadToken` with `target=node.pe`, `offset=node.iram_offset`, `ctx=node.ctx`, `data=node.const`. 475 + 476 + #### or1-asm.AC8.4 -- Direct mode route restrictions match edges 477 + - **Test type:** Unit 478 + - **File:** `tests/test_codegen.py` 479 + - **Test class/method:** `TestDirectMode::test_route_restrictions` 480 + - **Approach:** Construct graph with a cross-PE edge (pe0 -> pe1). Run `generate_direct()`. Assert `PEConfig` for pe0 has `allowed_pe_routes` containing pe1's ID (and pe0's own ID for self-routing). 481 + 482 + #### or1-asm.AC8.5 -- Token stream: SM init before ROUTE_SET 483 + - **Test type:** Unit 484 + - **File:** `tests/test_codegen.py` 485 + - **Test class/method:** `TestTokenStream::test_ordering_sm_before_route_set` 486 + - **Approach:** Construct graph with data_defs and multiple PEs. Run `generate_tokens()`. Find the index of the last `SMToken` and the first `CfgToken` with `op=CfgOp.ROUTE_SET`. Assert last_sm_index < first_route_set_index. 487 + 488 + #### or1-asm.AC8.6 -- Token stream: ROUTE_SET before LOAD_INST 489 + - **Test type:** Unit 490 + - **File:** `tests/test_codegen.py` 491 + - **Test class/method:** `TestTokenStream::test_ordering_route_set_before_load_inst` 492 + - **Approach:** Find last ROUTE_SET index and first LOAD_INST index. Assert ordering. 493 + 494 + #### or1-asm.AC8.7 -- Token stream: LOAD_INST before seeds 495 + - **Test type:** Unit 496 + - **File:** `tests/test_codegen.py` 497 + - **Test class/method:** `TestTokenStream::test_ordering_load_inst_before_seeds` 498 + - **Approach:** Find last LOAD_INST index and first MonadToken index. Assert ordering. 499 + 500 + #### or1-asm.AC8.8 -- Token stream consumable by emulator 501 + - **Test type:** Integration 502 + - **File:** `tests/test_codegen.py` 503 + - **Test class/method:** `TestTokenStream::test_emulator_consumable` 504 + - **Approach:** Generate token stream from a simple graph. Inject into emulator via `System.inject`/`inject_sm`. Run environment. Assert no exceptions raised and execution produces expected output. This bridges the codegen unit tests with emulator integration. 505 + 506 + #### or1-asm.AC8.9 -- No data_defs produces empty SM section 507 + - **Test type:** Unit 508 + - **File:** `tests/test_codegen.py` 509 + - **Test class/method:** `TestEdgeCases::test_no_data_defs` 510 + - **Approach:** Construct graph with no data_defs. Run `generate_direct()` and `generate_tokens()`. Assert `sm_configs` is empty and token list has no `SMToken` entries. 511 + 512 + #### or1-asm.AC8.10 -- Single PE ROUTE_SET has self-routes only 513 + - **Test type:** Unit 514 + - **File:** `tests/test_codegen.py` 515 + - **Test class/method:** `TestEdgeCases::test_single_pe_self_routes` 516 + - **Approach:** Construct single-PE graph with no SM instructions. Run `generate_tokens()`. Find ROUTE_SET token and assert `data == [[pe_id], []]` (or `[[pe_id], [sm_ids]]` if SM is used). 517 + 518 + --- 519 + 520 + ### AC9: End-to-End 521 + 522 + **Implementation phase:** Phase 7 (End-to-End Integration & Auto-Placement) 523 + 524 + **Key implementation decisions affecting tests:** 525 + - Tests use the public API `assemble()` and `assemble_to_tokens()`. 526 + - A helper function `run_program(source)` assembles, builds topology, injects seeds, runs, and collects output. 527 + - Token stream mode requires a separate helper that injects tokens in order and lets them configure the emulator at runtime. 528 + - Reference programs are written as inline dfasm source strings in the test file. 529 + - Source-side port qualifiers (`:L`/`:R` on the source node) disambiguate SWITCH output slots. 530 + 531 + #### or1-asm.AC9.1 -- CONST+ADD chain 532 + - **Test type:** E2E 533 + - **File:** `tests/test_e2e.py` 534 + - **Test class/method:** `TestDirectMode::test_const_add_chain` 535 + - **Approach:** Assemble a program with two const nodes (3, 7) feeding an add node. Run through emulator. Assert the add node fires with data = 10. 536 + - **Reference program:** 537 + ``` 538 + @system pe=1, sm=0 539 + &c1|pe0 <| const, 3 540 + &c2|pe0 <| const, 7 541 + &result|pe0 <| add 542 + &c1 |> &result:L 543 + &c2 |> &result:R 544 + ``` 545 + 546 + #### or1-asm.AC9.2 -- SM round-trip 547 + - **Test type:** E2E 548 + - **File:** `tests/test_e2e.py` 549 + - **Test class/method:** `TestDirectMode::test_sm_roundtrip` 550 + - **Approach:** Assemble a program that pre-initializes SM cell 5 with `0x42` via data_def, reads it via a triggered `read` instruction, and routes the result to a sink node. Assert sink fires with data = 0x42. 551 + - **Reference program:** 552 + ``` 553 + @system pe=1, sm=1 554 + @val|sm0:5 = 0x42 555 + &trigger|pe0 <| const, 1 556 + &reader|pe0 <| read, 5 557 + &sink|pe0 <| pass 558 + &trigger |> &reader:L 559 + &reader |> &sink:L 560 + ``` 561 + 562 + #### or1-asm.AC9.3 -- Cross-PE routing 563 + - **Test type:** E2E 564 + - **File:** `tests/test_e2e.py` 565 + - **Test class/method:** `TestDirectMode::test_cross_pe_routing` 566 + - **Approach:** Assemble a program with a const node on PE0 and a pass node on PE1. Assert token arrives at PE1 with correct data. 567 + - **Reference program:** 568 + ``` 569 + @system pe=2, sm=0 570 + &source|pe0 <| const, 99 571 + &dest|pe1 <| pass 572 + &source |> &dest:L 573 + ``` 574 + 575 + #### or1-asm.AC9.4 -- SWITCH routing 576 + - **Test type:** E2E 577 + - **File:** `tests/test_e2e.py` 578 + - **Test class/method:** `TestDirectMode::test_switch_routing` 579 + - **Approach:** Assemble a program with `sweq` comparing two equal values (5 == 5). Source-side port qualifiers route `&branch:L |> &taken:L` (data on match) and `&branch:R |> &not_taken:L` (trigger on match). Assert `taken` fires with data = 5 and `not_taken` fires with a trigger token. 580 + - **Reference program:** 581 + ``` 582 + @system pe=1, sm=0 583 + &val|pe0 <| const, 5 584 + &cmp|pe0 <| const, 5 585 + &branch|pe0 <| sweq 586 + &taken|pe0 <| pass 587 + &not_taken|pe0 <| pass 588 + &val |> &branch:L 589 + &cmp |> &branch:R 590 + &branch:L |> &taken:L 591 + &branch:R |> &not_taken:L 592 + ``` 593 + 594 + #### or1-asm.AC9.5 -- Both modes produce identical results 595 + - **Test type:** E2E 596 + - **File:** `tests/test_e2e.py` 597 + - **Test class/method:** `TestModeEquivalence` 598 + - **Approach:** For each reference program from AC9.1-AC9.4, run through both `run_program()` (direct mode) and `run_program_tokens()` (token stream mode). Compare output token data. Assert both produce identical results. 599 + 600 + --- 601 + 602 + ### AC10: Auto-Placement 603 + 604 + **Implementation phase:** Phase 7 (End-to-End Integration & Auto-Placement) 605 + 606 + **Key implementation decisions affecting tests:** 607 + - Auto-placement extends `place()` in `asm/place.py` with greedy bin-packing. 608 + - Locality heuristic: prefer the PE where the majority of connected neighbours already live. 609 + - Tie-break: remaining IRAM capacity (most room wins). 610 + - Tracks IRAM slots (dyadic cost both IRAM + matching store), context slots (per function body per PE). 611 + - Explicitly placed nodes are honoured and never moved. 612 + 613 + #### or1-asm.AC10.1 -- Unplaced nodes assigned within limits 614 + - **Test type:** Unit 615 + - **File:** `tests/test_autoplacement.py` 616 + - **Test class/method:** `TestBasicAutoPlacement::test_nodes_assigned` 617 + - **Approach:** Construct graph with 4 unplaced nodes and `SystemConfig(pe_count=2)`. Run `place()`. Assert every node has `pe is not None` and no PE exceeds IRAM or ctx limits. 618 + 619 + #### or1-asm.AC10.2 -- Explicit placements not moved 620 + - **Test type:** Unit 621 + - **File:** `tests/test_autoplacement.py` 622 + - **Test class/method:** `TestExplicitPreserved::test_explicit_preserved` 623 + - **Approach:** Mix of explicitly placed (pe=0, pe=1) and unplaced nodes. Run `place()`. Assert explicitly placed nodes retain their original PE assignment. 624 + 625 + #### or1-asm.AC10.3 -- Connected nodes prefer co-location 626 + - **Test type:** Unit 627 + - **File:** `tests/test_autoplacement.py` 628 + - **Test class/method:** `TestLocalityHeuristic::test_connected_colocation` 629 + - **Approach:** Two connected nodes (edge between them), both unplaced, `SystemConfig(pe_count=4)`. Run `place()`. Assert both end up on the same PE. Also test a cluster of 3 interconnected nodes. 630 + 631 + #### or1-asm.AC10.4 -- Too-large program produces utilization error 632 + - **Test type:** Unit 633 + - **File:** `tests/test_autoplacement.py` 634 + - **Test class/method:** `TestOverflow::test_too_large` 635 + - **Approach:** 200 unplaced nodes with `SystemConfig(pe_count=2, iram_capacity=64)`. Run `place()`. Assert error with `ErrorCategory.PLACEMENT` containing per-PE utilization breakdown (slot counts in the message). 636 + 637 + #### or1-asm.AC10.5 -- Auto-placed program executes correctly 638 + - **Test type:** E2E 639 + - **File:** `tests/test_e2e.py` 640 + - **Test class/method:** `TestAutoPlacedE2E::test_const_add_auto_placed` 641 + - **Approach:** Assemble the CONST+ADD reference program WITHOUT `|peN` qualifiers but with `@system pe=2`. Assert same result as explicitly-placed version (data = 10). This validates that auto-placement produces a valid, executable placement. 642 + 643 + --- 644 + 645 + ### AC11: Serialization (IRGraph -> dfasm) 646 + 647 + **Implementation phase:** Phase 6 (Codegen) 648 + 649 + **Key implementation decisions affecting tests:** 650 + - `serialize(graph: IRGraph) -> str` converts IRGraph back to valid dfasm. 651 + - Walks region list in order: FUNCTION regions emit `$name |> { ... }`, LOCATION regions emit directive + body. 652 + - Inside functions, &label names are unqualified (scope prefix stripped). 653 + - Always emits `inst_def` + `plain_edge` form (not inline edge syntax), even for anonymous nodes. 654 + - All nodes get explicit PE placement qualifiers. 655 + - Uses `OP_TO_MNEMONIC` for mnemonic lookup. 656 + - The public API exposes both `serialize_graph(graph)` (any pipeline stage) and `serialize(source)` (convenience round-trip). 657 + 658 + #### or1-asm.AC11.1 -- Serialized IRGraph re-parses without error 659 + - **Test type:** Integration 660 + - **File:** `tests/test_serialize.py` 661 + - **Test class/method:** `TestRoundTrip::test_reparse` 662 + - **Approach:** Parse a fully-specified dfasm program through the full pipeline (lower, resolve, place, allocate). Serialize the result. Re-parse the serialized text. Assert no parse errors. Use multiple test programs: simple (2 nodes + 1 edge), complex (function with nodes), data defs. 663 + 664 + #### or1-asm.AC11.2 -- Round-trip produces equivalent IRGraph 665 + - **Test type:** Integration 666 + - **File:** `tests/test_serialize.py` 667 + - **Test class/method:** `TestRoundTrip::test_structural_equivalence` 668 + - **Approach:** Parse -> lower -> resolve -> place -> allocate -> serialize -> parse -> lower. Compare the two IRGraphs: same node names (set equality on `nodes.keys()`), same opcodes per node, same edge topology, same data_defs. The second graph will not have allocation info (iram_offset, ctx, ResolvedDest), but node names, opcodes, and edge connections should match. 669 + 670 + #### or1-asm.AC11.3 -- PE placement qualifiers on all nodes 671 + - **Test type:** Unit 672 + - **File:** `tests/test_serialize.py` 673 + - **Test class/method:** `TestPlacementQualifiers::test_all_nodes_qualified` 674 + - **Approach:** Serialize an IRGraph where all nodes have PE assignments. Scan the output text for `inst_def` lines. Assert every line matching the inst_def pattern contains `|pe{N}`. 675 + 676 + #### or1-asm.AC11.4 -- Function scoping preserved 677 + - **Test type:** Unit 678 + - **File:** `tests/test_serialize.py` 679 + - **Test class/method:** `TestFunctionScoping::test_func_block` 680 + - **Approach:** Serialize an IRGraph with a FUNCTION region. Assert output contains `$name |> {` and matching `}` block. 681 + 682 + #### or1-asm.AC11.5 -- data_def entries with SM placement 683 + - **Test type:** Unit 684 + - **File:** `tests/test_serialize.py` 685 + - **Test class/method:** `TestDataDefs::test_data_def_output` 686 + - **Approach:** Serialize an IRGraph with data_defs. Assert output contains lines matching `@name|sm{N}:{addr} = {value}` pattern. 687 + 688 + #### or1-asm.AC11.6 -- Anonymous nodes serialize as inst_def + edge 689 + - **Test type:** Unit 690 + - **File:** `tests/test_serialize.py` 691 + - **Test class/method:** `TestAnonymousNodes::test_anon_explicit_form` 692 + - **Approach:** Serialize an IRGraph containing `__anon_` nodes from inline edge desugaring. Assert the output has `inst_def` lines for the anonymous nodes and explicit `plain_edge` lines (NOT inline strong/weak edge syntax). 693 + 694 + #### or1-asm.AC11.7 -- FUNCTION regions serialize as $name |> { ... } 695 + - **Test type:** Unit 696 + - **File:** `tests/test_serialize.py` 697 + - **Test class/method:** `TestFunctionScoping::test_unqualified_labels` 698 + - **Approach:** Serialize an IRGraph with a FUNCTION region containing nodes like `$main.&add`. Assert the output inside the `$main |> { ... }` block uses `&add` (unqualified), not `$main.&add`. 699 + 700 + #### or1-asm.AC11.8 -- LOCATION regions serialize as directive + body 701 + - **Test type:** Unit 702 + - **File:** `tests/test_serialize.py` 703 + - **Test class/method:** `TestLocationRegions::test_location_output` 704 + - **Approach:** Serialize an IRGraph with a LOCATION region tagged `@data_section|sm0`. Assert the output contains the bare directive `@data_section|sm0` followed by the body's data definitions. 705 + 706 + --- 707 + 708 + ## Human Verification 709 + 710 + All 68 acceptance criteria are fully automatable. No criteria require human-only verification. 711 + 712 + **Rationale:** Every criterion specifies a concrete, observable outcome -- either a data structure with specific field values, an error message with specific content and category, or an emulator execution producing a specific numeric result. None of the criteria involve subjective judgment (e.g., "code quality", "readability", "performance adequate for typical workloads") or require interaction with external systems beyond the test environment. 713 + 714 + The closest candidates for human verification were: 715 + - **Error message quality** (AC3.5, AC3.6, AC4.3, AC4.4, AC6.7, AC6.8, AC10.4): These specify that errors include source location, suggestions, and context. The automated tests verify the presence and content of these fields programmatically (e.g., asserting `error.loc.line > 0`, asserting `"did you mean" in error.suggestions`). The `format_error()` function's visual output could benefit from manual review during development, but the acceptance criteria only require specific data to be present, not visual aesthetics. 716 + - **Serialization readability** (AC11.*): These specify structural properties of the output text (contains `|peN`, uses `$name |> {` blocks, etc.), all of which are verifiable via string pattern matching in tests. 717 + 718 + --- 719 + 720 + ## Test File Summary 721 + 722 + | Test File | Phase | AC Groups | Count | Type | 723 + |---|---|---|---|---| 724 + | `tests/test_parser.py` | 1 | AC1 | 2 | Unit | 725 + | `tests/test_opcodes.py` | 1 | AC1 | 3 | Unit | 726 + | `tests/test_lower.py` | 2 | AC2, AC3 | 17 | Unit | 727 + | `tests/test_resolve.py` | 3 | AC4 | 5 | Unit | 728 + | `tests/test_place.py` | 4 | AC5 | 3 | Unit | 729 + | `tests/test_allocate.py` | 4 | AC6 | 8 | Unit | 730 + | `tests/test_pe.py` | 5 | AC7 | 5 | Integration | 731 + | `tests/test_network.py` | 5 | AC7 | 2 | Integration | 732 + | `tests/test_codegen.py` | 6 | AC8 | 10 | Unit/Integration | 733 + | `tests/test_serialize.py` | 6 | AC11 | 8 | Unit/Integration | 734 + | `tests/test_e2e.py` | 7 | AC9, AC10 | 6 | E2E | 735 + | `tests/test_autoplacement.py` | 7 | AC10 | 4 | Unit | 736 + 737 + **Notes:** 738 + - `tests/test_parser.py` and `tests/test_pe.py` are existing test files that gain new test classes/methods (not new files). All other test files in this table are created new. 739 + - `tests/test_network.py` is also an existing file that gains a new test class. 740 + - Test counts above are per-AC-criterion, not per-test-method. A single test method may cover multiple closely related assertions, or a single AC may be covered by multiple test methods across classes. 741 + 742 + --- 743 + 744 + ## Implementation Decision Cross-References 745 + 746 + This section documents where implementation decisions made during planning require specific test attention. 747 + 748 + ### IRNode.sm_id vs IRNode.sm_inst (Phase 2) 749 + The design plan specified `sm_inst: Optional[SMInst]` on IRNode. The implementation uses `sm_id: Optional[int]` instead, because `SMInst.ret` is only constructible after destination resolution (Phase 4). Tests for AC8.1 must verify that codegen constructs `SMInst` correctly from `IRNode.sm_id` + `IRNode.dest_l.addr` at codegen time. 750 + 751 + ### ROUTE_SET data format (Phase 5) 752 + The design plan specified ROUTE_SET data as `{"pe_routes": [...], "sm_routes": [...]}` (dict). The implementation uses `[[pe_ids], [sm_ids]]` (list of two lists) to maintain uniform `list` typing on `CfgToken.data`. Tests for AC7.1-AC7.5 must use the list-of-lists format, and tests for AC8.5-AC8.7 token stream ordering must match this format. 753 + 754 + ### PEConfig field naming (Phase 5) 755 + PEConfig uses `allowed_pe_routes` and `allowed_sm_routes` (with `allowed_` prefix) to avoid confusion with the PE's runtime `route_table` and `sm_routes` dict attributes. Tests for AC7.6 reference `PEConfig.allowed_pe_routes`, not `PEConfig.pe_routes`. 756 + 757 + ### MemOp.WRITE arity context-dependence (Phase 1, Phase 4) 758 + `is_monadic(MemOp.WRITE, const=5)` returns True (monadic form); `is_monadic(MemOp.WRITE, const=None)` returns False (dyadic form). Tests for AC1.3 must exercise both branches. Tests for AC6.1/AC6.2 must verify that a `MemOp.WRITE` node with `const` set is classified as monadic for IRAM packing purposes. 759 + 760 + ### Edge-to-destination mapping via source_port (Phase 4) 761 + The allocator uses `IREdge.source_port` to determine which output slot (`dest_l` or `dest_r`) each edge occupies. This is critical for SWITCH ops (AC9.4). Tests for AC6.4 should verify that source_port-qualified edges map to the correct destination slot on the source node. 762 + 763 + ### build_topology post-hoc filtering (Phase 5) 764 + `build_topology()` applies route restrictions by filtering the full-mesh after wiring, not by modifying the wiring loop. Tests for AC7.6 verify the end result (restricted route tables) without depending on the implementation strategy.

+89

docs/test-plans/2026-02-22-or1-asm.md

··· 1 + # OR1 Assembler — Human Test Plan 2 + 3 + **Coverage Result:** PASS — 68/68 acceptance criteria have automated tests (451 tests total) 4 + 5 + ## Prerequisites 6 + 7 + - Python 3.12 with SimPy 4.1, pytest, hypothesis, lark (`nix develop`) 8 + - All automated tests passing: `python -m pytest tests/ -v` 9 + - Working directory: `/home/orual/Projects/or1-design` 10 + 11 + ## Phase 1: Grammar and Opcode Verification 12 + 13 + | Step | Action | Expected | 14 + |------|--------|----------| 15 + | 1.1 | Count entries in `asm/opcodes.py` `MNEMONIC_TO_OP` | 38 entries: 30 ALU + 8 SM | 16 + | 1.2 | Verify `free` and `free_sm` are distinct | `free` → `RoutingOp.FREE`, `free_sm` → `MemOp.FREE` | 17 + | 1.3 | Parse `&x <| foobar` via Lark | `UnexpectedToken` with line/column | 18 + 19 + ## Phase 2: Lower Pass Functional Check 20 + 21 + | Step | Action | Expected | 22 + |------|--------|----------| 23 + | 2.1 | Lower `@system pe=4, sm=1` + `&a|pe0 <| add` | SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4), `&a` in nodes | 24 + | 2.2 | Parse duplicate `&add` in same scope | Error with `ErrorCategory.SCOPE` | 25 + | 2.3 | Parse `@system pe=4, sm=1, iram=128, ctx=2` | iram_capacity=128, ctx_slots=2 | 26 + 27 + ## Phase 3: Name Resolution Spot Check 28 + 29 + | Step | Action | Expected | 30 + |------|--------|----------| 31 + | 3.1 | Reference `&typo` when `&input` exists | Error with "undefined" + Levenshtein suggestion | 32 + | 3.2 | Top-level edge to function-scoped `&private` | Error with `ErrorCategory.SCOPE` mentioning `$foo` | 33 + 34 + ## Phase 4: Placement and Allocation Verification 35 + 36 + | Step | Action | Expected | 37 + |------|--------|----------| 38 + | 4.1 | Node on PE9, SystemConfig(pe_count=4) | Error mentioning "PE9" and "0-3" | 39 + | 4.2 | 65 nodes on one PE, iram_capacity=64 | Error with IRAM overflow | 40 + 41 + ## Phase 5: ROUTE_SET Emulator Integration 42 + 43 + | Step | Action | Expected | 44 + |------|--------|----------| 45 + | 5.1 | Restrict PE0 to `allowed_pe_routes={1}`, inspect route_table | Keys = `{1}` | 46 + | 5.2 | Default PEConfig, inspect route_table | Full-mesh keys | 47 + 48 + ## Phase 6: Codegen Output Inspection 49 + 50 + | Step | Action | Expected | 51 + |------|--------|----------| 52 + | 6.1 | Assemble CONST(3)+CONST(7)→ADD, inspect IRAM | ALUInst with correct opcodes and Addr | 53 + | 6.2 | Assemble `@val|sm0:5 = 0x42`, inspect sm_configs | `{5: (Presence.FULL, 66)}` | 54 + | 6.3 | Generate token stream, print types in order | SMToken → CfgToken(ROUTE_SET) → CfgToken(LOAD_INST) → MonadToken | 55 + 56 + ## Phase 7: Serialization Round-Trip 57 + 58 + | Step | Action | Expected | 59 + |------|--------|----------| 60 + | 7.1 | Serialize fully-processed IRGraph, inspect | `|peN` qualifiers, function blocks, data_defs, anon nodes | 61 + | 7.2 | Re-parse serialized output | No errors, matching nodes and edges | 62 + 63 + ## End-to-End Scenarios 64 + 65 + ### CONST+ADD Chain (AC9.1) 66 + Assemble `const(3) + const(7) → add → pass`, run emulator. **Expected:** PE0 emits data=10. 67 + 68 + ### SM Write+Read Round-Trip (AC9.2) 69 + Pre-init SM cell 5 with 0x42, triggered read with relay chain. **Expected:** PE1 emits data=66. 70 + 71 + ### Cross-PE Routing (AC9.3) 72 + CONST(99) PE0 → PASS PE1 → PASS PE2. **Expected:** PE0 emits data=99. 73 + 74 + ### SWITCH Routing (AC9.4) 75 + Two CONST(5) feed SWEQ with source-port edges. **Expected:** data=5 (taken) and data=0 (trigger). 76 + 77 + ### Auto-Placement (AC10.5) 78 + Unplaced CONST+ADD chain. **Expected:** Same result (8) as explicitly placed version. 79 + 80 + ### Mode Equivalence (AC9.5) 81 + CONST(10)+CONST(20)→ADD in both modes. **Expected:** Both produce 30. 82 + 83 + ## Human-Only Review (Recommended) 84 + 85 + | Aspect | Why | Steps | 86 + |--------|-----|-------| 87 + | Error message readability | Automated tests check fields, not clarity | Run resolve on typo program, inspect output | 88 + | Serialization formatting | Tests check structure, not layout | Serialize complex graph, inspect indentation | 89 + | Token stream ordering | Tests check pairwise order, not holistic sense | Generate tokens for 4-PE 2-SM graph, inspect full list |

+26 -30

emu/alu.py

··· 15 15 return val - 0x10000 if val & 0x8000 else val 16 16 17 17 18 + def _compare(op_fn, left: int, right: int) -> bool: 19 + """Helper for comparison operations with signed semantics. 20 + 21 + Args: 22 + op_fn: A comparison function (e.g., lambda a, b: a == b) 23 + left: Left operand (interpreted as signed) 24 + right: Right operand (interpreted as signed) 25 + 26 + Returns: 27 + Boolean result of the comparison 28 + """ 29 + return op_fn(to_signed(left), to_signed(right)) 30 + 31 + 18 32 def execute(op: ALUOp, left: int, right: int | None, const: int | None) -> tuple[int, bool]: 19 33 """ 20 34 Execute an ALU operation. ··· 77 91 case LogicOp.NOT: 78 92 return (~left) & UINT16_MASK, False 79 93 case LogicOp.EQ: 80 - sl, sr = to_signed(left), to_signed(right) 81 - cmp = sl == sr 94 + cmp = _compare(lambda a, b: a == b, left, right) 82 95 return (0x0001 if cmp else 0x0000), cmp 83 96 case LogicOp.LT: 84 - sl, sr = to_signed(left), to_signed(right) 85 - cmp = sl < sr 97 + cmp = _compare(lambda a, b: a < b, left, right) 86 98 return (0x0001 if cmp else 0x0000), cmp 87 99 case LogicOp.LTE: 88 - sl, sr = to_signed(left), to_signed(right) 89 - cmp = sl <= sr 100 + cmp = _compare(lambda a, b: a <= b, left, right) 90 101 return (0x0001 if cmp else 0x0000), cmp 91 102 case LogicOp.GT: 92 - sl, sr = to_signed(left), to_signed(right) 93 - cmp = sl > sr 103 + cmp = _compare(lambda a, b: a > b, left, right) 94 104 return (0x0001 if cmp else 0x0000), cmp 95 105 case LogicOp.GTE: 96 - sl, sr = to_signed(left), to_signed(right) 97 - cmp = sl >= sr 106 + cmp = _compare(lambda a, b: a >= b, left, right) 98 107 return (0x0001 if cmp else 0x0000), cmp 99 108 case _: 100 109 raise ValueError(f"Unknown logic op: {op}") ··· 103 112 def _execute_routing(op: RoutingOp, left: int, right: int | None, const: int | None) -> tuple[int, bool]: 104 113 """Execute routing operations.""" 105 114 match op: 106 - case RoutingOp.BREQ: 107 - cmp = to_signed(left) == to_signed(right) 108 - return left, cmp 109 - case RoutingOp.BRGT: 110 - cmp = to_signed(left) > to_signed(right) 111 - return left, cmp 112 - case RoutingOp.BRGE: 113 - cmp = to_signed(left) >= to_signed(right) 115 + case RoutingOp.BREQ | RoutingOp.SWEQ: 116 + cmp = _compare(lambda a, b: a == b, left, right) 114 117 return left, cmp 115 - case RoutingOp.BROF: 116 - raw = left + right 117 - cmp = raw > UINT16_MASK 118 + case RoutingOp.BRGT | RoutingOp.SWGT: 119 + cmp = _compare(lambda a, b: a > b, left, right) 118 120 return left, cmp 119 - case RoutingOp.SWEQ: 120 - cmp = to_signed(left) == to_signed(right) 121 - return left, cmp 122 - case RoutingOp.SWGT: 123 - cmp = to_signed(left) > to_signed(right) 121 + case RoutingOp.BRGE | RoutingOp.SWGE: 122 + cmp = _compare(lambda a, b: a >= b, left, right) 124 123 return left, cmp 125 - case RoutingOp.SWGE: 126 - cmp = to_signed(left) >= to_signed(right) 127 - return left, cmp 128 - case RoutingOp.SWOF: 124 + case RoutingOp.BROF | RoutingOp.SWOF: 129 125 raw = left + right 130 126 cmp = raw > UINT16_MASK 131 127 return left, cmp

+49 -7

emu/network.py

··· 4 4 from emu.sm import StructureMemory 5 5 from emu.types import PEConfig, SMConfig 6 6 from sm_mod import SMCell 7 - from tokens import CMToken, SMToken 7 + from tokens import CMToken, CfgToken, SMToken, Token 8 8 9 9 10 10 class System: ··· 18 18 self.pes = pes 19 19 self.sms = sms 20 20 21 - def inject(self, token: CMToken) -> None: 22 - """Inject a seed CM token into the target PE's input store.""" 23 - self.pes[token.target].input_store.items.append(token) 21 + def inject(self, token: Token) -> None: 22 + """Inject a token into the appropriate element's input store (direct append). 24 23 25 - def inject_sm(self, sm_id: int, token: SMToken) -> None: 26 - """Inject a seed SM token into a specific SM's input store.""" 27 - self.sms[sm_id].input_store.items.append(token) 24 + Routes by type: SMToken → target SM, CMToken/CfgToken → target PE. 25 + Uses direct list append (bypasses SimPy put), suitable for pre-simulation setup. 26 + """ 27 + store = self._target_store(token) 28 + store.items.append(token) 29 + 30 + def send(self, token: Token): 31 + """Inject a token via SimPy store.put() (generator, yields). 32 + 33 + Same routing as inject() but respects FIFO backpressure. 34 + Must be called from within a SimPy process or env.process(). 35 + """ 36 + store = self._target_store(token) 37 + yield store.put(token) 38 + 39 + def load(self, tokens: list[Token]) -> None: 40 + """Spawn a SimPy process that sends each token via store.put(). 41 + 42 + Tokens are injected in order, respecting FIFO capacity. 43 + """ 44 + def _loader(): 45 + for token in tokens: 46 + yield from self.send(token) 47 + self.env.process(_loader()) 48 + 49 + def _target_store(self, token: Token) -> simpy.Store: 50 + """Resolve the destination store for a token.""" 51 + if isinstance(token, SMToken): 52 + return self.sms[token.target].input_store 53 + if isinstance(token, (CMToken, CfgToken)): 54 + return self.pes[token.target].input_store 55 + raise TypeError(f"Unknown token type: {type(token).__name__}") 28 56 29 57 30 58 def build_topology( ··· 70 98 71 99 for sm in sms.values(): 72 100 sm.route_table.update(pe_stores) 101 + 102 + # Apply route restrictions based on PEConfig allowed_pe_routes and allowed_sm_routes 103 + for cfg in pe_configs: 104 + pe = pes[cfg.pe_id] 105 + if cfg.allowed_pe_routes is not None: 106 + pe.route_table = { 107 + pid: store for pid, store in pe.route_table.items() 108 + if pid in cfg.allowed_pe_routes 109 + } 110 + if cfg.allowed_sm_routes is not None: 111 + pe.sm_routes = { 112 + sid: store for sid, store in pe.sm_routes.items() 113 + if sid in cfg.allowed_sm_routes 114 + } 73 115 74 116 return System(env, pes, sms)

+70 -25

emu/pe.py

··· 1 1 import logging 2 + from enum import Enum 2 3 from typing import Optional 3 4 4 5 import simpy 5 6 6 - from cm_inst import ALUInst, Addr, RoutingOp, SMInst 7 + from cm_inst import ALUInst, Addr, ArithOp, LogicOp, RoutingOp, SMInst, is_monadic_alu 7 8 from emu.alu import execute 8 9 from emu.types import MatchEntry 9 - from tokens import CMToken, CfgOp, CfgToken, DyadToken, MemOp, MonadToken, Port, SMToken 10 + from tokens import ( 11 + CMToken, CfgOp, CfgToken, DyadToken, LoadInstToken, MemOp, 12 + MonadToken, Port, RouteSetToken, SMToken, 13 + ) 10 14 11 15 logger = logging.getLogger(__name__) 12 16 13 17 18 + class OutputMode(Enum): 19 + """Output routing mode for ALU instructions.""" 20 + SUPPRESS = "SUPPRESS" 21 + SINGLE = "SINGLE" 22 + DUAL = "DUAL" 23 + SWITCH = "SWITCH" 24 + 25 + 14 26 class ProcessingElement: 15 27 def __init__( 16 28 self, ··· 34 46 self.gen_counters: list[int] = [0] * ctx_slots 35 47 self._ctx_slots = ctx_slots 36 48 self._offsets = offsets 49 + self.output_log: list = [] 37 50 self.process = env.process(self._run()) 38 51 39 52 def _run(self): ··· 47 60 if isinstance(token, MonadToken): 48 61 operands = self._match_monadic(token) 49 62 elif isinstance(token, DyadToken): 50 - operands = self._match_dyadic(token) 63 + inst = self._fetch(token.offset) 64 + if inst is not None and self._is_monadic_instruction(inst): 65 + operands = (token.data, None) 66 + else: 67 + operands = self._match_dyadic(token) 51 68 else: 52 69 logger.warning("PE%d: unknown token type: %s", self.pe_id, type(token)) 53 70 continue ··· 62 79 continue 63 80 64 81 if isinstance(inst, SMInst): 65 - yield from self._emit_sm(inst, left, right) 82 + yield from self._emit_sm(inst, left, right, token.ctx) 66 83 else: 67 84 result, bool_out = execute(inst.op, left, right, inst.const) 68 85 yield from self._emit(inst, result, bool_out, token.ctx) 69 86 70 87 def _handle_cfg(self, token: CfgToken) -> None: 71 88 """Handle configuration tokens for dynamic IRAM updates and routing setup.""" 72 - if token.op == CfgOp.LOAD_INST: 73 - # Load instructions into IRAM starting at specified address 89 + if isinstance(token, LoadInstToken): 74 90 base_addr = token.addr if token.addr is not None else 0 75 - for i, inst in enumerate(token.data): 91 + for i, inst in enumerate(token.instructions): 76 92 self.iram[base_addr + i] = inst 77 - elif token.op == CfgOp.ROUTE_SET: 78 - # TODO: Implement dynamic routing configuration 79 - logger.warning("PE%d: ROUTE_SET not yet implemented", self.pe_id) 93 + elif isinstance(token, RouteSetToken): 94 + self.route_table = { 95 + pid: store for pid, store in self.route_table.items() 96 + if pid in token.pe_routes 97 + } 98 + self.sm_routes = { 99 + sid: store for sid, store in self.sm_routes.items() 100 + if sid in token.sm_routes 101 + } 80 102 else: 81 103 logger.warning("PE%d: unknown CfgOp: %s", self.pe_id, token.op) 82 104 ··· 115 137 def _fetch(self, offset: int) -> Optional[ALUInst | SMInst]: 116 138 return self.iram.get(offset) 117 139 140 + def _is_monadic_instruction(self, inst: ALUInst | SMInst) -> bool: 141 + """Check if an instruction expects a single operand. 142 + 143 + When a DyadToken arrives at a monadic instruction's offset, the PE 144 + bypasses the matching store and fires immediately with (data, None). 145 + """ 146 + if isinstance(inst, SMInst): 147 + if inst.op == MemOp.WRITE and inst.const is None: 148 + return False 149 + if inst.op == MemOp.CMP_SW: 150 + return False 151 + return True 152 + 153 + # For ALU instructions, use canonical is_monadic_alu 154 + return is_monadic_alu(inst.op) 155 + 118 156 def _emit(self, inst: ALUInst, result: int, bool_out: bool, ctx: int): 119 157 mode = self._output_mode(inst, bool_out) 120 158 121 - if mode == "SUPPRESS": 159 + if mode == OutputMode.SUPPRESS: 122 160 return 123 161 124 - if mode == "SINGLE": 162 + if mode == OutputMode.SINGLE: 125 163 out_token = self._make_output_token(inst.dest_l, result, ctx) 164 + self.output_log.append(out_token) 126 165 yield self.route_table[inst.dest_l.pe].put(out_token) 127 166 128 - elif mode == "DUAL": 167 + elif mode == OutputMode.DUAL: 129 168 out_l = self._make_output_token(inst.dest_l, result, ctx) 130 169 out_r = self._make_output_token(inst.dest_r, result, ctx) 170 + self.output_log.append(out_l) 171 + self.output_log.append(out_r) 131 172 yield self.route_table[inst.dest_l.pe].put(out_l) 132 173 yield self.route_table[inst.dest_r.pe].put(out_r) 133 174 134 - elif mode == "SWITCH": 175 + elif mode == OutputMode.SWITCH: 135 176 if bool_out: 136 177 taken, not_taken = inst.dest_l, inst.dest_r 137 178 else: 138 179 taken, not_taken = inst.dest_r, inst.dest_l 139 180 140 181 data_token = self._make_output_token(taken, result, ctx) 182 + self.output_log.append(data_token) 141 183 yield self.route_table[taken.pe].put(data_token) 142 184 143 185 trigger_token = MonadToken( ··· 147 189 data=0, 148 190 inline=True, 149 191 ) 192 + self.output_log.append(trigger_token) 150 193 yield self.route_table[not_taken.pe].put(trigger_token) 151 194 152 - def _emit_sm(self, inst: SMInst, left: int, right: int | None): 195 + def _emit_sm(self, inst: SMInst, left: int, right: int | None, ctx: int): 153 196 cell_addr = inst.const if inst.const is not None else left 154 197 data = left if inst.const is not None else right 155 198 ··· 158 201 ret = CMToken( 159 202 target=inst.ret.pe, 160 203 offset=inst.ret.a, 161 - ctx=0, 204 + ctx=ctx, 162 205 data=0, 163 206 ) 164 207 165 208 sm_token = SMToken( 166 - target=cell_addr, 209 + target=inst.sm_id, 210 + addr=cell_addr, 167 211 op=inst.op, 168 212 flags=left if inst.op == MemOp.CMP_SW and right is not None else None, 169 213 data=data, 170 214 ret=ret, 171 215 ) 216 + self.output_log.append(sm_token) 172 217 yield self.sm_routes[inst.sm_id].put(sm_token) 173 218 174 - def _output_mode(self, inst: ALUInst, bool_out: bool) -> str: 219 + def _output_mode(self, inst: ALUInst, bool_out: bool) -> OutputMode: 175 220 if inst.op == RoutingOp.FREE: 176 - return "SUPPRESS" 221 + return OutputMode.SUPPRESS 177 222 if inst.op == RoutingOp.GATE and not bool_out: 178 - return "SUPPRESS" 223 + return OutputMode.SUPPRESS 179 224 if inst.dest_l is None: 180 - return "SUPPRESS" 225 + return OutputMode.SUPPRESS 181 226 if inst.dest_r is None: 182 - return "SINGLE" 227 + return OutputMode.SINGLE 183 228 if isinstance(inst.op, RoutingOp) and inst.op in ( 184 229 RoutingOp.SWEQ, RoutingOp.SWGT, RoutingOp.SWGE, RoutingOp.SWOF, 185 230 ): 186 - return "SWITCH" 187 - return "DUAL" 231 + return OutputMode.SWITCH 232 + return OutputMode.DUAL 188 233 189 234 def _make_output_token(self, dest: Addr, data: int, ctx: int) -> DyadToken: 190 235 return DyadToken( ··· 193 238 ctx=ctx, 194 239 data=data, 195 240 port=dest.port, 196 - gen=0, 241 + gen=self.gen_counters[ctx], 197 242 wide=False, 198 243 )

+3 -2

emu/sm.py

··· 3 3 4 4 import simpy 5 5 6 + from emu.alu import UINT16_MASK 6 7 from emu.types import DeferredRead 7 8 from sm_mod import Presence, SMCell 8 9 from tokens import CMToken, MemOp, MonadToken, SMToken ··· 38 39 logger.warning("SM%d: unexpected token type: %s", self.sm_id, type(token)) 39 40 continue 40 41 41 - addr = token.target 42 + addr = token.addr 42 43 op = token.op 43 44 44 45 match op: ··· 128 129 return 129 130 130 131 old_value = cell.data_l if cell.data_l is not None else 0 131 - cell.data_l = (old_value + delta) & 0xFFFF 132 + cell.data_l = (old_value + delta) & UINT16_MASK 132 133 yield from self._send_result(token.ret, old_value) 133 134 134 135 def _handle_cas(self, addr: int, token: SMToken):

+2

emu/types.py

··· 26 26 ctx_slots: int = 4 27 27 offsets: int = 64 28 28 gen_counters: Optional[list[int]] = None 29 + allowed_pe_routes: Optional[set[int]] = None 30 + allowed_sm_routes: Optional[set[int]] = None 29 31 30 32 31 33 @dataclass(frozen=True)

lang.py

This is a binary file and will not be displayed.

+1 -13

sm_mod.py

··· 1 1 from dataclasses import dataclass 2 2 from enum import IntEnum 3 - from tokens import CMToken, SMToken, Token 4 - from typing import List, Optional, Tuple 5 - 6 - import simpy 7 - from simpy import Environment, Resource 3 + from typing import List, Optional 8 4 9 5 10 6 class Presence(IntEnum): ··· 19 15 pres: Presence 20 16 data_l: Optional[int] # data or length 21 17 data_r: Optional[List[int]] # optional data 22 - 23 - 24 - class StructureMem(Resource): 25 - cells: List[SMCell] 26 - 27 - def __init__(self, env: Environment, size: int = 512, capacity: int = 2): 28 - super().__init__(env, capacity) 29 - self.cells = [SMCell(Presence.EMPTY, None, None)] * size

+18 -1

tests/conftest.py

··· 1 + from pathlib import Path 2 + 3 + import pytest 1 4 from hypothesis import strategies as st 5 + from lark import Lark 2 6 3 7 from cm_inst import ArithOp, LogicOp, RoutingOp 4 8 from tokens import CMToken, DyadToken, MemOp, MonadToken, Port, SMToken 9 + 10 + GRAMMAR_PATH = Path(__file__).parent.parent / "dfasm.lark" 5 11 6 12 uint16 = st.integers(min_value=0, max_value=0xFFFF) 7 13 int16 = st.integers(min_value=-32768, max_value=32767) ··· 52 58 _data = draw(uint16) if data is None else data 53 59 ret = CMToken(target=0, offset=0, ctx=0, data=0) 54 60 return SMToken( 55 - target=_addr, 61 + target=0, 62 + addr=_addr, 56 63 op=_op, 57 64 flags=None, 58 65 data=_data, ··· 68 75 ctx=draw(st.integers(min_value=0, max_value=3)), 69 76 data=0, 70 77 ) 78 + 79 + 80 + @pytest.fixture(scope="session") 81 + def parser(): 82 + """Get the dfasm parser.""" 83 + return Lark( 84 + GRAMMAR_PATH.read_text(), 85 + parser="earley", 86 + propagate_positions=True, 87 + )

+19

tests/helpers.py

··· 1 + """Shared test helper functions for the OR1 assembler test suite.""" 2 + 3 + from textwrap import dedent 4 + 5 + from asm.lower import lower 6 + from asm.resolve import resolve 7 + 8 + 9 + def parse_and_lower(parser, source: str): 10 + """Parse source code and lower the resulting CST to IRGraph.""" 11 + tree = parser.parse(dedent(source)) 12 + return lower(tree) 13 + 14 + 15 + def parse_lower_resolve(parser, source: str): 16 + """Parse source code, lower to IRGraph, then resolve names.""" 17 + tree = parser.parse(dedent(source)) 18 + graph = lower(tree) 19 + return resolve(graph)

+19

tests/pipeline.py

··· 1 + """Assembler pipeline helpers for the OR1 test suite.""" 2 + 3 + from textwrap import dedent 4 + 5 + from asm.lower import lower 6 + from asm.resolve import resolve 7 + 8 + 9 + def parse_and_lower(parser, source: str): 10 + """Parse source code and lower the resulting CST to IRGraph.""" 11 + tree = parser.parse(dedent(source)) 12 + return lower(tree) 13 + 14 + 15 + def parse_lower_resolve(parser, source: str): 16 + """Parse source code, lower to IRGraph, then resolve names.""" 17 + tree = parser.parse(dedent(source)) 18 + graph = lower(tree) 19 + return resolve(graph)

+735

tests/test_allocate.py

··· 1 + """Tests for the Resource allocation pass. 2 + 3 + Tests verify: 4 + - or1-asm.AC6.1: Dyadic instructions are assigned IRAM offsets starting at 0 5 + - or1-asm.AC6.2: Monadic/SM instructions are assigned IRAM offsets above dyadic range 6 + - or1-asm.AC6.3: Each function body on a PE gets a distinct context slot 7 + - or1-asm.AC6.4: All NameRef destinations resolve to ResolvedDest with correct Addr 8 + - or1-asm.AC6.5: Local edges (same PE) produce Addr with dest PE = source PE 9 + - or1-asm.AC6.6: Cross-PE edges produce Addr with dest PE = target PE 10 + - or1-asm.AC6.7: IRAM overflow produces error 11 + - or1-asm.AC6.8: Context slot overflow produces error 12 + """ 13 + 14 + from asm.allocate import allocate 15 + from asm.ir import ( 16 + IRGraph, 17 + IRNode, 18 + IREdge, 19 + SystemConfig, 20 + SourceLoc, 21 + NameRef, 22 + ResolvedDest, 23 + ) 24 + from asm.errors import ErrorCategory 25 + from cm_inst import ArithOp 26 + from tokens import Port, MemOp 27 + 28 + 29 + class TestIRAMPacking: 30 + """AC6.1, AC6.2: IRAM offset assignment (dyadic first, then monadic).""" 31 + 32 + def test_mixed_dyadic_and_monadic(self): 33 + """PE with 2 dyadic (ADD, SUB) and 2 monadic (INC, CONST).""" 34 + nodes = { 35 + "&add": IRNode( 36 + name="&add", 37 + opcode=ArithOp.ADD, 38 + pe=0, 39 + loc=SourceLoc(1, 1), 40 + ), 41 + "&sub": IRNode( 42 + name="&sub", 43 + opcode=ArithOp.SUB, 44 + pe=0, 45 + loc=SourceLoc(2, 1), 46 + ), 47 + "&inc": IRNode( 48 + name="&inc", 49 + opcode=ArithOp.INC, 50 + pe=0, 51 + loc=SourceLoc(3, 1), 52 + ), 53 + "&const_1": IRNode( 54 + name="&const_1", 55 + opcode=ArithOp.ADD, # Using const operand makes it monadic 56 + pe=0, 57 + const=1, 58 + loc=SourceLoc(4, 1), 59 + ), 60 + } 61 + system = SystemConfig(pe_count=1, sm_count=1) 62 + graph = IRGraph(nodes, system=system) 63 + result = allocate(graph) 64 + 65 + assert len(result.errors) == 0 66 + 67 + # Dyadic nodes should get offsets 0, 1 68 + add_node = result.nodes["&add"] 69 + sub_node = result.nodes["&sub"] 70 + assert add_node.iram_offset == 0 71 + assert sub_node.iram_offset == 1 72 + 73 + # Monadic nodes should get offsets starting at 2 74 + inc_node = result.nodes["&inc"] 75 + const_node = result.nodes["&const_1"] 76 + assert const_node.iram_offset == 2 77 + assert inc_node.iram_offset == 3 78 + 79 + def test_only_monadic(self): 80 + """PE with only monadic instructions.""" 81 + nodes = { 82 + "&inc": IRNode( 83 + name="&inc", 84 + opcode=ArithOp.INC, 85 + pe=0, 86 + loc=SourceLoc(1, 1), 87 + ), 88 + "&dec": IRNode( 89 + name="&dec", 90 + opcode=ArithOp.DEC, 91 + pe=0, 92 + loc=SourceLoc(2, 1), 93 + ), 94 + } 95 + system = SystemConfig(pe_count=1, sm_count=1) 96 + graph = IRGraph(nodes, system=system) 97 + result = allocate(graph) 98 + 99 + assert len(result.errors) == 0 100 + inc_node = result.nodes["&inc"] 101 + dec_node = result.nodes["&dec"] 102 + assert inc_node.iram_offset == 0 103 + assert dec_node.iram_offset == 1 104 + 105 + def test_only_dyadic(self): 106 + """PE with only dyadic instructions.""" 107 + nodes = { 108 + "&add": IRNode( 109 + name="&add", 110 + opcode=ArithOp.ADD, 111 + pe=0, 112 + loc=SourceLoc(1, 1), 113 + ), 114 + "&sub": IRNode( 115 + name="&sub", 116 + opcode=ArithOp.SUB, 117 + pe=0, 118 + loc=SourceLoc(2, 1), 119 + ), 120 + } 121 + system = SystemConfig(pe_count=1, sm_count=1) 122 + graph = IRGraph(nodes, system=system) 123 + result = allocate(graph) 124 + 125 + assert len(result.errors) == 0 126 + add_node = result.nodes["&add"] 127 + sub_node = result.nodes["&sub"] 128 + assert add_node.iram_offset == 0 129 + assert sub_node.iram_offset == 1 130 + 131 + 132 + class TestContextSlots: 133 + """AC6.3: Context slot assignment per function scope per PE.""" 134 + 135 + def test_single_function_scope(self): 136 + """PE with nodes from only $main.""" 137 + nodes = { 138 + "$main.&add": IRNode( 139 + name="$main.&add", 140 + opcode=ArithOp.ADD, 141 + pe=0, 142 + loc=SourceLoc(1, 1), 143 + ), 144 + "$main.&sub": IRNode( 145 + name="$main.&sub", 146 + opcode=ArithOp.SUB, 147 + pe=0, 148 + loc=SourceLoc(2, 1), 149 + ), 150 + } 151 + system = SystemConfig(pe_count=1, sm_count=1) 152 + graph = IRGraph(nodes, system=system) 153 + result = allocate(graph) 154 + 155 + assert len(result.errors) == 0 156 + add_node = result.nodes["$main.&add"] 157 + sub_node = result.nodes["$main.&sub"] 158 + # Both should have ctx=0 (same function scope) 159 + assert add_node.ctx == 0 160 + assert sub_node.ctx == 0 161 + 162 + def test_multiple_function_scopes(self): 163 + """PE with nodes from $main and $helper.""" 164 + nodes = { 165 + "$main.&add": IRNode( 166 + name="$main.&add", 167 + opcode=ArithOp.ADD, 168 + pe=0, 169 + loc=SourceLoc(1, 1), 170 + ), 171 + "$main.&sub": IRNode( 172 + name="$main.&sub", 173 + opcode=ArithOp.SUB, 174 + pe=0, 175 + loc=SourceLoc(2, 1), 176 + ), 177 + "$helper.&inc": IRNode( 178 + name="$helper.&inc", 179 + opcode=ArithOp.INC, 180 + pe=0, 181 + loc=SourceLoc(3, 1), 182 + ), 183 + } 184 + system = SystemConfig(pe_count=1, sm_count=1) 185 + graph = IRGraph(nodes, system=system) 186 + result = allocate(graph) 187 + 188 + assert len(result.errors) == 0 189 + add_node = result.nodes["$main.&add"] 190 + helper_node = result.nodes["$helper.&inc"] 191 + # $main should get ctx=0, $helper should get ctx=1 192 + assert add_node.ctx == 0 193 + assert helper_node.ctx == 1 194 + 195 + def test_toplevel_nodes(self): 196 + """Top-level nodes (no function scope) get ctx=0.""" 197 + nodes = { 198 + "&add": IRNode( 199 + name="&add", 200 + opcode=ArithOp.ADD, 201 + pe=0, 202 + loc=SourceLoc(1, 1), 203 + ), 204 + "&sub": IRNode( 205 + name="&sub", 206 + opcode=ArithOp.SUB, 207 + pe=0, 208 + loc=SourceLoc(2, 1), 209 + ), 210 + } 211 + system = SystemConfig(pe_count=1, sm_count=1) 212 + graph = IRGraph(nodes, system=system) 213 + result = allocate(graph) 214 + 215 + assert len(result.errors) == 0 216 + add_node = result.nodes["&add"] 217 + sub_node = result.nodes["&sub"] 218 + assert add_node.ctx == 0 219 + assert sub_node.ctx == 0 220 + 221 + def test_multiple_functions_order_preserved(self): 222 + """Context slots assigned in order of first appearance.""" 223 + nodes = { 224 + "$fib.&a": IRNode( 225 + name="$fib.&a", 226 + opcode=ArithOp.ADD, 227 + pe=0, 228 + loc=SourceLoc(1, 1), 229 + ), 230 + "$main.&b": IRNode( 231 + name="$main.&b", 232 + opcode=ArithOp.SUB, 233 + pe=0, 234 + loc=SourceLoc(2, 1), 235 + ), 236 + "$helper.&c": IRNode( 237 + name="$helper.&c", 238 + opcode=ArithOp.INC, 239 + pe=0, 240 + loc=SourceLoc(3, 1), 241 + ), 242 + "$fib.&d": IRNode( 243 + name="$fib.&d", 244 + opcode=ArithOp.DEC, 245 + pe=0, 246 + loc=SourceLoc(4, 1), 247 + ), 248 + } 249 + system = SystemConfig(pe_count=1, sm_count=1) 250 + graph = IRGraph(nodes, system=system) 251 + result = allocate(graph) 252 + 253 + assert len(result.errors) == 0 254 + a_node = result.nodes["$fib.&a"] 255 + b_node = result.nodes["$main.&b"] 256 + c_node = result.nodes["$helper.&c"] 257 + d_node = result.nodes["$fib.&d"] 258 + # First appearance order: $fib (ctx=0), $main (ctx=1), $helper (ctx=2) 259 + assert a_node.ctx == 0 260 + assert d_node.ctx == 0 # Same function as first 261 + assert b_node.ctx == 1 262 + assert c_node.ctx == 2 263 + 264 + 265 + class TestDestinationResolution: 266 + """AC6.4, AC6.5, AC6.6: NameRef resolution to Addr with local/cross-PE edges.""" 267 + 268 + def test_single_dest_l_local_edge(self): 269 + """Local edge: dest_l has Addr with pe matching source.""" 270 + nodes = { 271 + "&add": IRNode( 272 + name="&add", 273 + opcode=ArithOp.ADD, 274 + pe=0, 275 + dest_l=NameRef(name="&sub", port=Port.L), 276 + loc=SourceLoc(1, 1), 277 + ), 278 + "&sub": IRNode( 279 + name="&sub", 280 + opcode=ArithOp.SUB, 281 + pe=0, 282 + loc=SourceLoc(2, 1), 283 + ), 284 + } 285 + edges = [ 286 + IREdge(source="&add", dest="&sub", port=Port.L, loc=SourceLoc(1, 5)) 287 + ] 288 + system = SystemConfig(pe_count=1, sm_count=1) 289 + graph = IRGraph(nodes, edges=edges, system=system) 290 + result = allocate(graph) 291 + 292 + assert len(result.errors) == 0 293 + add_node = result.nodes["&add"] 294 + sub_node = result.nodes["&sub"] 295 + 296 + # dest_l should be resolved 297 + assert isinstance(add_node.dest_l, ResolvedDest) 298 + assert add_node.dest_l.addr.a == sub_node.iram_offset 299 + assert add_node.dest_l.addr.pe == 0 # Same PE 300 + 301 + def test_cross_pe_edge(self): 302 + """Cross-PE edge: Addr.pe = destination PE.""" 303 + nodes = { 304 + "&add": IRNode( 305 + name="&add", 306 + opcode=ArithOp.ADD, 307 + pe=0, 308 + dest_l=NameRef(name="&sub", port=Port.L), 309 + loc=SourceLoc(1, 1), 310 + ), 311 + "&sub": IRNode( 312 + name="&sub", 313 + opcode=ArithOp.SUB, 314 + pe=1, 315 + loc=SourceLoc(2, 1), 316 + ), 317 + } 318 + edges = [ 319 + IREdge(source="&add", dest="&sub", port=Port.L, loc=SourceLoc(1, 5)) 320 + ] 321 + system = SystemConfig(pe_count=2, sm_count=1) 322 + graph = IRGraph(nodes, edges=edges, system=system) 323 + result = allocate(graph) 324 + 325 + assert len(result.errors) == 0 326 + add_node = result.nodes["&add"] 327 + sub_node = result.nodes["&sub"] 328 + 329 + # dest_l should be resolved with destination PE 330 + assert isinstance(add_node.dest_l, ResolvedDest) 331 + assert add_node.dest_l.addr.a == sub_node.iram_offset 332 + assert add_node.dest_l.addr.pe == 1 # Destination PE 333 + 334 + def test_dual_destinations_with_source_ports(self): 335 + """Dual destinations with source port qualifiers (source_port L and R).""" 336 + nodes = { 337 + "&branch": IRNode( 338 + name="&branch", 339 + opcode=ArithOp.ADD, 340 + pe=0, 341 + dest_l=NameRef(name="&taken", port=Port.L), 342 + dest_r=NameRef(name="&not_taken", port=Port.L), 343 + loc=SourceLoc(1, 1), 344 + ), 345 + "&taken": IRNode( 346 + name="&taken", 347 + opcode=ArithOp.SUB, 348 + pe=0, 349 + loc=SourceLoc(2, 1), 350 + ), 351 + "&not_taken": IRNode( 352 + name="&not_taken", 353 + opcode=ArithOp.INC, 354 + pe=0, 355 + loc=SourceLoc(3, 1), 356 + ), 357 + } 358 + edges = [ 359 + IREdge( 360 + source="&branch", 361 + dest="&taken", 362 + port=Port.L, 363 + source_port=Port.L, 364 + loc=SourceLoc(1, 5), 365 + ), 366 + IREdge( 367 + source="&branch", 368 + dest="&not_taken", 369 + port=Port.L, 370 + source_port=Port.R, 371 + loc=SourceLoc(1, 15), 372 + ), 373 + ] 374 + system = SystemConfig(pe_count=1, sm_count=1) 375 + graph = IRGraph(nodes, edges=edges, system=system) 376 + result = allocate(graph) 377 + 378 + assert len(result.errors) == 0 379 + branch_node = result.nodes["&branch"] 380 + 381 + # Both dest_l and dest_r should be resolved 382 + assert isinstance(branch_node.dest_l, ResolvedDest) 383 + assert isinstance(branch_node.dest_r, ResolvedDest) 384 + 385 + def test_single_implicit_edge_maps_to_dest_l(self): 386 + """Single edge without source_port → dest_l.""" 387 + nodes = { 388 + "&a": IRNode( 389 + name="&a", 390 + opcode=ArithOp.ADD, 391 + pe=0, 392 + dest_l=NameRef(name="&b", port=Port.L), 393 + loc=SourceLoc(1, 1), 394 + ), 395 + "&b": IRNode( 396 + name="&b", 397 + opcode=ArithOp.SUB, 398 + pe=0, 399 + loc=SourceLoc(2, 1), 400 + ), 401 + } 402 + edges = [ 403 + IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(1, 5)) 404 + ] 405 + system = SystemConfig(pe_count=1, sm_count=1) 406 + graph = IRGraph(nodes, edges=edges, system=system) 407 + result = allocate(graph) 408 + 409 + assert len(result.errors) == 0 410 + a_node = result.nodes["&a"] 411 + assert isinstance(a_node.dest_l, ResolvedDest) 412 + 413 + 414 + class TestOverflow: 415 + """AC6.7, AC6.8: IRAM and context slot overflow errors.""" 416 + 417 + def test_iram_overflow_default_capacity(self): 418 + """PE with 65 nodes exceeds default 64 IRAM slots.""" 419 + nodes = {} 420 + for i in range(65): 421 + nodes[f"&node_{i}"] = IRNode( 422 + name=f"&node_{i}", 423 + opcode=ArithOp.ADD, 424 + pe=0, 425 + loc=SourceLoc(i + 1, 1), 426 + ) 427 + system = SystemConfig(pe_count=1, sm_count=1, iram_capacity=64) 428 + graph = IRGraph(nodes, system=system) 429 + result = allocate(graph) 430 + 431 + assert len(result.errors) > 0 432 + error = result.errors[0] 433 + assert error.category == ErrorCategory.RESOURCE 434 + assert "IRAM" in error.message or "overflow" in error.message.lower() 435 + 436 + def test_iram_overflow_custom_capacity(self): 437 + """PE with 9 nodes exceeds custom IRAM limit of 8.""" 438 + nodes = {} 439 + for i in range(9): 440 + nodes[f"&node_{i}"] = IRNode( 441 + name=f"&node_{i}", 442 + opcode=ArithOp.ADD, 443 + pe=0, 444 + loc=SourceLoc(i + 1, 1), 445 + ) 446 + system = SystemConfig(pe_count=1, sm_count=1, iram_capacity=8) 447 + graph = IRGraph(nodes, system=system) 448 + result = allocate(graph) 449 + 450 + assert len(result.errors) > 0 451 + error = result.errors[0] 452 + assert error.category == ErrorCategory.RESOURCE 453 + 454 + def test_ctx_slot_overflow_default_capacity(self): 455 + """PE with 5 function bodies exceeds default 4 ctx slots.""" 456 + nodes = { 457 + "$main.&a": IRNode( 458 + name="$main.&a", 459 + opcode=ArithOp.ADD, 460 + pe=0, 461 + loc=SourceLoc(1, 1), 462 + ), 463 + "$fib.&b": IRNode( 464 + name="$fib.&b", 465 + opcode=ArithOp.SUB, 466 + pe=0, 467 + loc=SourceLoc(2, 1), 468 + ), 469 + "$helper.&c": IRNode( 470 + name="$helper.&c", 471 + opcode=ArithOp.INC, 472 + pe=0, 473 + loc=SourceLoc(3, 1), 474 + ), 475 + "$util.&d": IRNode( 476 + name="$util.&d", 477 + opcode=ArithOp.DEC, 478 + pe=0, 479 + loc=SourceLoc(4, 1), 480 + ), 481 + "$extra.&e": IRNode( 482 + name="$extra.&e", 483 + opcode=ArithOp.ADD, 484 + pe=0, 485 + loc=SourceLoc(5, 1), 486 + ), 487 + } 488 + system = SystemConfig(pe_count=1, sm_count=1, ctx_slots=4) 489 + graph = IRGraph(nodes, system=system) 490 + result = allocate(graph) 491 + 492 + assert len(result.errors) > 0 493 + error = result.errors[0] 494 + assert error.category == ErrorCategory.RESOURCE 495 + assert "context" in error.message.lower() or "ctx" in error.message.lower() 496 + 497 + def test_ctx_slot_overflow_custom_capacity(self): 498 + """PE with 3 function bodies exceeds custom ctx_slots of 2.""" 499 + nodes = { 500 + "$main.&a": IRNode( 501 + name="$main.&a", 502 + opcode=ArithOp.ADD, 503 + pe=0, 504 + loc=SourceLoc(1, 1), 505 + ), 506 + "$helper.&b": IRNode( 507 + name="$helper.&b", 508 + opcode=ArithOp.SUB, 509 + pe=0, 510 + loc=SourceLoc(2, 1), 511 + ), 512 + "$util.&c": IRNode( 513 + name="$util.&c", 514 + opcode=ArithOp.INC, 515 + pe=0, 516 + loc=SourceLoc(3, 1), 517 + ), 518 + } 519 + system = SystemConfig(pe_count=1, sm_count=1, ctx_slots=2) 520 + graph = IRGraph(nodes, system=system) 521 + result = allocate(graph) 522 + 523 + assert len(result.errors) > 0 524 + error = result.errors[0] 525 + assert error.category == ErrorCategory.RESOURCE 526 + 527 + 528 + class TestMultiplePEs: 529 + """Multiple PEs with independent allocation.""" 530 + 531 + def test_separate_pe_allocations(self): 532 + """Different PEs get independent IRAM offsets.""" 533 + nodes = { 534 + "&a0": IRNode(name="&a0", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 535 + "&b0": IRNode(name="&b0", opcode=ArithOp.SUB, pe=0, loc=SourceLoc(2, 1)), 536 + "&a1": IRNode(name="&a1", opcode=ArithOp.ADD, pe=1, loc=SourceLoc(3, 1)), 537 + "&b1": IRNode(name="&b1", opcode=ArithOp.SUB, pe=1, loc=SourceLoc(4, 1)), 538 + } 539 + system = SystemConfig(pe_count=2, sm_count=1) 540 + graph = IRGraph(nodes, system=system) 541 + result = allocate(graph) 542 + 543 + assert len(result.errors) == 0 544 + # Each PE should have its own offset space 545 + a0 = result.nodes["&a0"] 546 + b0 = result.nodes["&b0"] 547 + a1 = result.nodes["&a1"] 548 + b1 = result.nodes["&b1"] 549 + 550 + # PE0 nodes start at 0 551 + assert a0.iram_offset == 0 552 + assert b0.iram_offset == 1 553 + 554 + # PE1 nodes also start at 0 555 + assert a1.iram_offset == 0 556 + assert b1.iram_offset == 1 557 + 558 + 559 + class TestMemoryOps: 560 + """Memory operations (SM instructions) are monadic.""" 561 + 562 + def test_read_is_monadic(self): 563 + """READ instruction is monadic.""" 564 + nodes = { 565 + "&add": IRNode( 566 + name="&add", 567 + opcode=ArithOp.ADD, 568 + pe=0, 569 + loc=SourceLoc(1, 1), 570 + ), 571 + "&read": IRNode( 572 + name="&read", 573 + opcode=MemOp.READ, 574 + pe=0, 575 + loc=SourceLoc(2, 1), 576 + ), 577 + } 578 + system = SystemConfig(pe_count=1, sm_count=1) 579 + graph = IRGraph(nodes, system=system) 580 + result = allocate(graph) 581 + 582 + assert len(result.errors) == 0 583 + add_node = result.nodes["&add"] 584 + read_node = result.nodes["&read"] 585 + # Dyadic ADD gets offset 0, monadic READ gets offset 1 586 + assert add_node.iram_offset == 0 587 + assert read_node.iram_offset == 1 588 + 589 + def test_write_with_const_is_monadic(self): 590 + """WRITE with const is monadic.""" 591 + nodes = { 592 + "&add": IRNode( 593 + name="&add", 594 + opcode=ArithOp.ADD, 595 + pe=0, 596 + loc=SourceLoc(1, 1), 597 + ), 598 + "&write": IRNode( 599 + name="&write", 600 + opcode=MemOp.WRITE, 601 + const=0x10, 602 + pe=0, 603 + loc=SourceLoc(2, 1), 604 + ), 605 + } 606 + system = SystemConfig(pe_count=1, sm_count=1) 607 + graph = IRGraph(nodes, system=system) 608 + result = allocate(graph) 609 + 610 + assert len(result.errors) == 0 611 + add_node = result.nodes["&add"] 612 + write_node = result.nodes["&write"] 613 + # Dyadic ADD gets offset 0, monadic WRITE gets offset 1 614 + assert add_node.iram_offset == 0 615 + assert write_node.iram_offset == 1 616 + 617 + def test_write_without_const_is_dyadic(self): 618 + """WRITE without const is dyadic.""" 619 + nodes = { 620 + "&add": IRNode( 621 + name="&add", 622 + opcode=ArithOp.ADD, 623 + pe=0, 624 + loc=SourceLoc(1, 1), 625 + ), 626 + "&write": IRNode( 627 + name="&write", 628 + opcode=MemOp.WRITE, 629 + const=None, 630 + pe=0, 631 + loc=SourceLoc(2, 1), 632 + ), 633 + } 634 + system = SystemConfig(pe_count=1, sm_count=1) 635 + graph = IRGraph(nodes, system=system) 636 + result = allocate(graph) 637 + 638 + assert len(result.errors) == 0 639 + add_node = result.nodes["&add"] 640 + write_node = result.nodes["&write"] 641 + # Both are dyadic, so ADD gets 0, WRITE gets 1 642 + assert add_node.iram_offset == 0 643 + assert write_node.iram_offset == 1 644 + 645 + 646 + class TestErrorValidation: 647 + """Test edge-to-destination validation errors.""" 648 + 649 + def test_more_than_two_outgoing_edges(self): 650 + """Node with 3+ outgoing edges produces error.""" 651 + nodes = { 652 + "&a": IRNode( 653 + name="&a", 654 + opcode=ArithOp.ADD, 655 + pe=0, 656 + dest_l=NameRef(name="&b", port=Port.L), 657 + dest_r=NameRef(name="&c", port=Port.L), 658 + loc=SourceLoc(1, 1), 659 + ), 660 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=0, loc=SourceLoc(2, 1)), 661 + "&c": IRNode(name="&c", opcode=ArithOp.INC, pe=0, loc=SourceLoc(3, 1)), 662 + "&d": IRNode(name="&d", opcode=ArithOp.DEC, pe=0, loc=SourceLoc(4, 1)), 663 + } 664 + edges = [ 665 + IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(1, 5)), 666 + IREdge(source="&a", dest="&c", port=Port.L, loc=SourceLoc(1, 10)), 667 + IREdge(source="&a", dest="&d", port=Port.L, loc=SourceLoc(1, 15)), 668 + ] 669 + system = SystemConfig(pe_count=1, sm_count=1) 670 + graph = IRGraph(nodes, edges=edges, system=system) 671 + result = allocate(graph) 672 + 673 + # Should have error about too many edges 674 + assert len(result.errors) > 0 675 + 676 + def test_conflicting_source_ports(self): 677 + """Two edges with same source_port produces error.""" 678 + nodes = { 679 + "&a": IRNode( 680 + name="&a", 681 + opcode=ArithOp.ADD, 682 + pe=0, 683 + dest_l=NameRef(name="&b", port=Port.L), 684 + dest_r=NameRef(name="&c", port=Port.L), 685 + loc=SourceLoc(1, 1), 686 + ), 687 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=0, loc=SourceLoc(2, 1)), 688 + "&c": IRNode(name="&c", opcode=ArithOp.INC, pe=0, loc=SourceLoc(3, 1)), 689 + } 690 + edges = [ 691 + IREdge(source="&a", dest="&b", port=Port.L, source_port=Port.L), 692 + IREdge(source="&a", dest="&c", port=Port.L, source_port=Port.L), 693 + ] 694 + system = SystemConfig(pe_count=1, sm_count=1) 695 + graph = IRGraph(nodes, edges=edges, system=system) 696 + result = allocate(graph) 697 + 698 + # Should have error about conflicting ports 699 + assert len(result.errors) > 0 700 + 701 + 702 + class TestSMReturnRoutes: 703 + """SM read instructions use dest_l as return route.""" 704 + 705 + def test_read_with_return_address(self): 706 + """READ instruction's dest_l is resolved as return address.""" 707 + nodes = { 708 + "&read": IRNode( 709 + name="&read", 710 + opcode=MemOp.READ, 711 + pe=0, 712 + dest_l=NameRef(name="&next", port=Port.L), 713 + loc=SourceLoc(1, 1), 714 + ), 715 + "&next": IRNode( 716 + name="&next", 717 + opcode=ArithOp.ADD, 718 + pe=0, 719 + loc=SourceLoc(2, 1), 720 + ), 721 + } 722 + edges = [ 723 + IREdge(source="&read", dest="&next", port=Port.L) 724 + ] 725 + system = SystemConfig(pe_count=1, sm_count=1) 726 + graph = IRGraph(nodes, edges=edges, system=system) 727 + result = allocate(graph) 728 + 729 + assert len(result.errors) == 0 730 + read_node = result.nodes["&read"] 731 + next_node = result.nodes["&next"] 732 + 733 + # dest_l should be resolved 734 + assert isinstance(read_node.dest_l, ResolvedDest) 735 + assert read_node.dest_l.addr.a == next_node.iram_offset

+17

tests/test_alu.py

··· 13 13 - or1-emu.AC2.9: Signed boundary edge case 14 14 """ 15 15 16 + import pytest 16 17 from hypothesis import given, example 17 18 18 19 from emu.alu import execute, to_signed ··· 363 364 for op in [ArithOp.ADD, LogicOp.AND, RoutingOp.PASS]: 364 365 _, bool_out = execute(op, a, b, None) 365 366 assert isinstance(bool_out, bool) 367 + 368 + 369 + class TestUnknownOpcode: 370 + """Test handling of unknown opcodes.""" 371 + 372 + def test_unknown_opcode_raises_value_error(self): 373 + """Unknown opcode raises ValueError.""" 374 + # Create an invalid opcode-like value that's not in any ALUOp enum 375 + class UnknownOp: 376 + def __repr__(self): 377 + return "UnknownOp" 378 + 379 + unknown_op = UnknownOp() 380 + 381 + with pytest.raises(ValueError, match="Unknown ALU operation"): 382 + execute(unknown_op, 0x1234, 0x5678, None)

+258

tests/test_autoplacement.py

··· 1 + """Tests for auto-placement in the placement pass. 2 + 3 + Tests verify: 4 + - or1-asm.AC10.1: Unplaced nodes are assigned to PEs without exceeding limits 5 + - or1-asm.AC10.2: Explicitly placed nodes are not moved by auto-placement 6 + - or1-asm.AC10.3: Connected nodes prefer co-location on same PE (locality heuristic) 7 + - or1-asm.AC10.4: Program too large for available PEs produces error with per-PE utilization breakdown 8 + """ 9 + 10 + from asm.place import place 11 + from asm.ir import IRGraph, IRNode, IREdge, SystemConfig, SourceLoc, IRRegion, RegionKind 12 + import asm.ir 13 + from asm.errors import ErrorCategory 14 + from cm_inst import ArithOp, LogicOp 15 + from tokens import Port 16 + 17 + 18 + class TestBasicAutoPlacement: 19 + """AC10.1: Unplaced nodes are assigned to PEs without exceeding limits.""" 20 + 21 + def test_four_unplaced_nodes_two_pes(self): 22 + """Four unplaced nodes with SystemConfig(pe_count=2) get assigned.""" 23 + nodes = { 24 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=None, loc=SourceLoc(1, 1)), 25 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 26 + "&c": IRNode(name="&c", opcode=ArithOp.INC, pe=None, loc=SourceLoc(3, 1)), 27 + "&d": IRNode(name="&d", opcode=ArithOp.DEC, pe=None, loc=SourceLoc(4, 1)), 28 + } 29 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 30 + graph = IRGraph(nodes, system=system) 31 + result = place(graph) 32 + 33 + # Should have no errors 34 + assert len(result.errors) == 0, f"Expected no errors, got: {[e.message for e in result.errors]}" 35 + 36 + # All nodes should have PE assignments 37 + for node_name in nodes.keys(): 38 + assert result.nodes[node_name].pe is not None, f"{node_name} still unplaced" 39 + assert 0 <= result.nodes[node_name].pe < 2, f"{node_name} on invalid PE" 40 + 41 + def test_monadic_node_placement(self): 42 + """Monadic nodes take up only 1 IRAM slot.""" 43 + # CONST is monadic (RoutingOp.CONST) 44 + from cm_inst import RoutingOp 45 + nodes = { 46 + "&c1": IRNode(name="&c1", opcode=RoutingOp.CONST, pe=None, const=5, loc=SourceLoc(1, 1)), 47 + "&c2": IRNode(name="&c2", opcode=RoutingOp.CONST, pe=None, const=10, loc=SourceLoc(2, 1)), 48 + } 49 + system = SystemConfig(pe_count=1, sm_count=1, iram_capacity=64, ctx_slots=4) 50 + graph = IRGraph(nodes, system=system) 51 + result = place(graph) 52 + 53 + assert len(result.errors) == 0 54 + for node in result.nodes.values(): 55 + assert node.pe == 0 56 + 57 + 58 + class TestExplicitPreserved: 59 + """AC10.2: Explicitly placed nodes are not moved by auto-placement.""" 60 + 61 + def test_mixed_placed_and_unplaced(self): 62 + """Explicitly placed nodes keep their PE; unplaced ones get assigned.""" 63 + nodes = { 64 + "&placed0": IRNode(name="&placed0", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 65 + "&placed1": IRNode(name="&placed1", opcode=ArithOp.SUB, pe=1, loc=SourceLoc(2, 1)), 66 + "&unplaced1": IRNode(name="&unplaced1", opcode=ArithOp.INC, pe=None, loc=SourceLoc(3, 1)), 67 + "&unplaced2": IRNode(name="&unplaced2", opcode=ArithOp.DEC, pe=None, loc=SourceLoc(4, 1)), 68 + } 69 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 70 + graph = IRGraph(nodes, system=system) 71 + result = place(graph) 72 + 73 + assert len(result.errors) == 0 74 + # Explicitly placed nodes keep their PE 75 + assert result.nodes["&placed0"].pe == 0 76 + assert result.nodes["&placed1"].pe == 1 77 + # Unplaced nodes get assigned 78 + assert result.nodes["&unplaced1"].pe is not None 79 + assert result.nodes["&unplaced2"].pe is not None 80 + 81 + def test_all_explicit_placement(self): 82 + """All nodes explicitly placed - no auto-placement needed.""" 83 + nodes = { 84 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 85 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=1, loc=SourceLoc(2, 1)), 86 + } 87 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 88 + graph = IRGraph(nodes, system=system) 89 + result = place(graph) 90 + 91 + assert len(result.errors) == 0 92 + assert result.nodes["&a"].pe == 0 93 + assert result.nodes["&b"].pe == 1 94 + 95 + 96 + class TestLocalityHeuristic: 97 + """AC10.3: Connected nodes prefer co-location on same PE.""" 98 + 99 + def test_two_connected_unplaced_nodes(self): 100 + """Two connected unplaced nodes end up on the same PE.""" 101 + nodes = { 102 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=None, loc=SourceLoc(1, 1)), 103 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 104 + } 105 + edges = [ 106 + IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(3, 1)), 107 + ] 108 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 109 + graph = IRGraph(nodes, edges=edges, system=system) 110 + result = place(graph) 111 + 112 + assert len(result.errors) == 0 113 + # Both nodes should be on the same PE 114 + assert result.nodes["&a"].pe == result.nodes["&b"].pe 115 + 116 + def test_cluster_of_three_interconnected_nodes(self): 117 + """Cluster of 3 interconnected nodes end up on the same PE.""" 118 + nodes = { 119 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=None, loc=SourceLoc(1, 1)), 120 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 121 + "&c": IRNode(name="&c", opcode=ArithOp.INC, pe=None, loc=SourceLoc(3, 1)), 122 + } 123 + edges = [ 124 + IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(4, 1)), 125 + IREdge(source="&b", dest="&c", port=Port.L, loc=SourceLoc(5, 1)), 126 + IREdge(source="&a", dest="&c", port=Port.R, loc=SourceLoc(6, 1)), 127 + ] 128 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 129 + graph = IRGraph(nodes, edges=edges, system=system) 130 + result = place(graph) 131 + 132 + assert len(result.errors) == 0 133 + # All three nodes should be on the same PE 134 + pe_a = result.nodes["&a"].pe 135 + pe_b = result.nodes["&b"].pe 136 + pe_c = result.nodes["&c"].pe 137 + assert pe_a == pe_b == pe_c 138 + 139 + def test_locality_with_mixed_placed_unplaced(self): 140 + """Unplaced node prefers PE of its connected placed neighbour.""" 141 + nodes = { 142 + "&placed": IRNode(name="&placed", opcode=ArithOp.ADD, pe=1, loc=SourceLoc(1, 1)), 143 + "&unplaced": IRNode(name="&unplaced", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 144 + } 145 + edges = [ 146 + IREdge(source="&placed", dest="&unplaced", port=Port.L, loc=SourceLoc(3, 1)), 147 + ] 148 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 149 + graph = IRGraph(nodes, edges=edges, system=system) 150 + result = place(graph) 151 + 152 + assert len(result.errors) == 0 153 + # Unplaced node should prefer PE1 (where placed node is) 154 + assert result.nodes["&unplaced"].pe == 1 155 + 156 + 157 + class TestOverflow: 158 + """AC10.4: Program too large produces error with per-PE utilization breakdown.""" 159 + 160 + def test_200_nodes_overflow_error(self): 161 + """200 unplaced nodes with limited resources produce overflow error.""" 162 + # Create 200 monadic nodes (each takes 1 IRAM slot) 163 + nodes = {} 164 + for i in range(200): 165 + nodes[f"&n{i}"] = IRNode( 166 + name=f"&n{i}", 167 + opcode=ArithOp.INC, 168 + pe=None, 169 + loc=SourceLoc(i + 1, 1), 170 + ) 171 + 172 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 173 + graph = IRGraph(nodes, system=system) 174 + result = place(graph) 175 + 176 + # Should have error(s) about placement failure 177 + assert len(result.errors) > 0 178 + error = result.errors[0] 179 + assert error.category == ErrorCategory.PLACEMENT 180 + assert "Cannot place" in error.message or "full" in error.message.lower() 181 + # Error message should include per-PE utilization info 182 + assert "PE0" in error.message or "IRAM" in error.message 183 + 184 + def test_overflow_error_includes_breakdown(self): 185 + """Overflow error includes per-PE slot utilization breakdown.""" 186 + # 130 monadic nodes: on 2 PEs with 64 IRAM capacity each, this overflows 187 + nodes = {} 188 + for i in range(130): 189 + nodes[f"&n{i}"] = IRNode( 190 + name=f"&n{i}", 191 + opcode=ArithOp.INC, 192 + pe=None, 193 + loc=SourceLoc(i + 1, 1), 194 + ) 195 + 196 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 197 + graph = IRGraph(nodes, system=system) 198 + result = place(graph) 199 + 200 + assert len(result.errors) > 0 201 + error_msg = result.errors[0].message 202 + # Should mention PE utilization 203 + assert any(x in error_msg for x in ["PE", "IRAM", "full", "capacity"]) 204 + 205 + 206 + class TestFunctionScopedNodesPlacement: 207 + """Verify auto-placed nodes inside function scopes receive PE assignments.""" 208 + 209 + def test_function_scoped_node_gets_pe_assignment(self): 210 + """Nodes inside function regions should get PE assignments after place().""" 211 + # Create a graph with a function region containing unplaced nodes 212 + func_nodes = { 213 + "$main.&add": IRNode( 214 + name="$main.&add", 215 + opcode=ArithOp.ADD, 216 + pe=None, 217 + loc=SourceLoc(1, 1), 218 + ), 219 + "$main.&inc": IRNode( 220 + name="$main.&inc", 221 + opcode=ArithOp.INC, 222 + pe=None, 223 + loc=SourceLoc(2, 1), 224 + ), 225 + } 226 + 227 + func_region = IRGraph(nodes=func_nodes, edges=[], regions=[], data_defs=[], errors=[]) 228 + 229 + main_region = asm.ir.IRRegion( 230 + tag="$main", 231 + kind=asm.ir.RegionKind.FUNCTION, 232 + body=func_region, 233 + loc=SourceLoc(0, 1), 234 + ) 235 + 236 + graph = IRGraph( 237 + nodes={}, 238 + edges=[], 239 + regions=[main_region], 240 + data_defs=[], 241 + system=SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4), 242 + errors=[], 243 + ) 244 + 245 + result = place(graph) 246 + 247 + # Verify no errors 248 + assert len(result.errors) == 0, f"Expected no errors, got: {[e.message for e in result.errors]}" 249 + 250 + # Verify nodes inside the function region received PE assignments 251 + assert len(result.regions) == 1 252 + result_func = result.regions[0] 253 + assert result_func.tag == "$main" 254 + 255 + # Check that nodes in the function body have PE assignments 256 + for node_name, node in result_func.body.nodes.items(): 257 + assert node.pe is not None, f"Node {node_name} in function scope still has pe=None" 258 + assert 0 <= node.pe < 2, f"Node {node_name} has invalid PE {node.pe}"

+567

tests/test_codegen.py

··· 1 + """Tests for code generation. 2 + 3 + Tests verify: 4 + - or1-asm.AC8.1: Direct mode produces valid PEConfig with correct IRAM contents 5 + - or1-asm.AC8.2: Direct mode produces valid SMConfig with initial cell values 6 + - or1-asm.AC8.3: Direct mode produces seed MonadTokens for const nodes with no incoming edges 7 + - or1-asm.AC8.4: Direct mode PEConfig includes route restrictions matching edge analysis 8 + - or1-asm.AC8.5: Token stream mode emits SM init tokens before ROUTE_SET tokens 9 + - or1-asm.AC8.6: Token stream mode emits ROUTE_SET tokens before LOAD_INST tokens 10 + - or1-asm.AC8.7: Token stream mode emits LOAD_INST tokens before seed tokens 11 + - or1-asm.AC8.8: Token stream mode produces valid tokens consumable by emulator 12 + - or1-asm.AC8.9: Program with no data_defs produces empty SM init section 13 + - or1-asm.AC8.10: Single PE program produces ROUTE_SET with only self-routes 14 + """ 15 + 16 + from asm.codegen import generate_direct, generate_tokens, AssemblyResult 17 + from asm.ir import ( 18 + IRGraph, 19 + IRNode, 20 + IREdge, 21 + IRDataDef, 22 + SystemConfig, 23 + SourceLoc, 24 + ResolvedDest, 25 + ) 26 + from cm_inst import ArithOp, RoutingOp, Addr, MemOp, ALUInst, SMInst 27 + from tokens import Port, MonadToken, SMToken, CfgToken, CfgOp, LoadInstToken, RouteSetToken 28 + from emu.types import PEConfig, SMConfig 29 + from sm_mod import Presence 30 + 31 + 32 + class TestDirectMode: 33 + """AC8.1, AC8.2, AC8.3, AC8.4: Direct mode code generation.""" 34 + 35 + def test_ac81_simple_alu_instructions(self): 36 + """AC8.1: Two ALU nodes on PE0 produce PEConfig with correct IRAM. 37 + 38 + Tests that: 39 + - ALU instructions are correctly converted to ALUInst 40 + - They are placed in IRAM at assigned offsets 41 + """ 42 + # Create two simple dyadic ALU nodes 43 + add_node = IRNode( 44 + name="&add", 45 + opcode=ArithOp.ADD, 46 + pe=0, 47 + iram_offset=0, 48 + ctx=0, 49 + loc=SourceLoc(1, 1), 50 + ) 51 + sub_node = IRNode( 52 + name="&sub", 53 + opcode=ArithOp.SUB, 54 + pe=0, 55 + iram_offset=1, 56 + ctx=0, 57 + loc=SourceLoc(2, 1), 58 + ) 59 + system = SystemConfig(pe_count=1, sm_count=1) 60 + graph = IRGraph( 61 + {"&add": add_node, "&sub": sub_node}, 62 + system=system, 63 + ) 64 + 65 + result = generate_direct(graph) 66 + 67 + assert len(result.pe_configs) == 1 68 + pe_config = result.pe_configs[0] 69 + assert pe_config.pe_id == 0 70 + assert len(pe_config.iram) == 2 71 + assert 0 in pe_config.iram 72 + assert 1 in pe_config.iram 73 + 74 + # Check the instruction types 75 + inst_0 = pe_config.iram[0] 76 + inst_1 = pe_config.iram[1] 77 + assert isinstance(inst_0, ALUInst) # Is an ALUInst 78 + assert isinstance(inst_1, ALUInst) # Is an ALUInst 79 + assert inst_0.op == ArithOp.ADD 80 + assert inst_1.op == ArithOp.SUB 81 + 82 + def test_ac82_data_defs_to_smconfig(self): 83 + """AC8.2: Data definitions produce SMConfig with initial cell values. 84 + 85 + Tests that: 86 + - Data defs with SM placement are converted to SMConfig 87 + - initial_cells dict contains correct (Presence.FULL, value) tuples 88 + """ 89 + data_def = IRDataDef( 90 + name="@val", 91 + sm_id=0, 92 + cell_addr=5, 93 + value=42, 94 + loc=SourceLoc(1, 1), 95 + ) 96 + graph = IRGraph({}, data_defs=[data_def], system=SystemConfig(1, 1)) 97 + 98 + result = generate_direct(graph) 99 + 100 + assert len(result.sm_configs) == 1 101 + sm_config = result.sm_configs[0] 102 + assert sm_config.sm_id == 0 103 + assert sm_config.initial_cells is not None 104 + assert 5 in sm_config.initial_cells 105 + pres, val = sm_config.initial_cells[5] 106 + assert pres == Presence.FULL 107 + assert val == 42 108 + 109 + def test_ac83_const_node_seed_token(self): 110 + """AC8.3: CONST node with no incoming edges produces seed MonadToken. 111 + 112 + Tests that: 113 + - CONST nodes are detected 114 + - Nodes with no incoming edges are marked as seeds 115 + - MonadToken has correct target PE, offset, ctx, data 116 + """ 117 + const_node = IRNode( 118 + name="&seed", 119 + opcode=RoutingOp.CONST, 120 + pe=0, 121 + iram_offset=2, 122 + ctx=0, 123 + const=99, 124 + loc=SourceLoc(1, 1), 125 + ) 126 + graph = IRGraph({"&seed": const_node}, system=SystemConfig(1, 1)) 127 + 128 + result = generate_direct(graph) 129 + 130 + assert len(result.seed_tokens) == 1 131 + token = result.seed_tokens[0] 132 + assert isinstance(token, MonadToken) 133 + assert token.target == 0 134 + assert token.offset == 2 135 + assert token.ctx == 0 136 + assert token.data == 99 137 + assert token.inline == False 138 + 139 + def test_ac84_route_restrictions(self): 140 + """AC8.4: Cross-PE edges produce correct allowed_pe_routes. 141 + 142 + Tests that: 143 + - Edges from PE0 to PE1 add PE1 to PE0's allowed_pe_routes 144 + - Self-routes are always included 145 + """ 146 + # PE0 node connecting to PE1 node 147 + node_pe0 = IRNode( 148 + name="&a", 149 + opcode=ArithOp.ADD, 150 + pe=0, 151 + iram_offset=0, 152 + ctx=0, 153 + dest_l=ResolvedDest( 154 + name="&b", 155 + addr=Addr(a=0, port=Port.L, pe=1), 156 + ), 157 + loc=SourceLoc(1, 1), 158 + ) 159 + node_pe1 = IRNode( 160 + name="&b", 161 + opcode=ArithOp.ADD, 162 + pe=1, 163 + iram_offset=0, 164 + ctx=0, 165 + loc=SourceLoc(2, 1), 166 + ) 167 + edge = IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(1, 1)) 168 + system = SystemConfig(pe_count=2, sm_count=1) 169 + graph = IRGraph( 170 + {"&a": node_pe0, "&b": node_pe1}, 171 + edges=[edge], 172 + system=system, 173 + ) 174 + 175 + result = generate_direct(graph) 176 + 177 + assert len(result.pe_configs) == 2 178 + pe0_config = next(c for c in result.pe_configs if c.pe_id == 0) 179 + pe1_config = next(c for c in result.pe_configs if c.pe_id == 1) 180 + 181 + # PE0 should have routes to {0, 1} 182 + assert 0 in pe0_config.allowed_pe_routes 183 + assert 1 in pe0_config.allowed_pe_routes 184 + 185 + # PE1 should have route to {1} (self only, no incoming cross-PE edges) 186 + assert 1 in pe1_config.allowed_pe_routes 187 + 188 + def test_sm_instructions_in_iram(self): 189 + """Verify SMInst objects are correctly created and placed in IRAM. 190 + 191 + Tests that MemOp instructions produce SMInst in IRAM. 192 + """ 193 + sm_node = IRNode( 194 + name="&read", 195 + opcode=MemOp.READ, 196 + pe=0, 197 + iram_offset=0, 198 + ctx=0, 199 + sm_id=0, 200 + const=42, 201 + dest_l=ResolvedDest( 202 + name="&out", 203 + addr=Addr(a=1, port=Port.L, pe=0), 204 + ), 205 + loc=SourceLoc(1, 1), 206 + ) 207 + graph = IRGraph({"&read": sm_node}, system=SystemConfig(1, 1)) 208 + 209 + result = generate_direct(graph) 210 + 211 + assert len(result.pe_configs) == 1 212 + pe_config = result.pe_configs[0] 213 + assert 0 in pe_config.iram 214 + inst = pe_config.iram[0] 215 + assert isinstance(inst, SMInst) # Is an SMInst 216 + assert inst.op == MemOp.READ 217 + assert inst.sm_id == 0 218 + assert inst.const == 42 219 + 220 + 221 + class TestTokenStream: 222 + """AC8.5, AC8.6, AC8.7, AC8.8: Token stream generation and ordering.""" 223 + 224 + def test_ac85_ac86_ac87_token_ordering(self): 225 + """AC8.5-8.7: Tokens are emitted in correct order. 226 + 227 + Tests that: 228 + - SM init tokens come first 229 + - ROUTE_SET tokens come next 230 + - LOAD_INST tokens come next 231 + - Seed tokens come last 232 + """ 233 + # Create a multi-PE graph with data_defs 234 + data_def = IRDataDef( 235 + name="@val", 236 + sm_id=0, 237 + cell_addr=5, 238 + value=42, 239 + loc=SourceLoc(1, 1), 240 + ) 241 + node1 = IRNode( 242 + name="&a", 243 + opcode=ArithOp.ADD, 244 + pe=0, 245 + iram_offset=0, 246 + ctx=0, 247 + loc=SourceLoc(1, 1), 248 + ) 249 + node2 = IRNode( 250 + name="&b", 251 + opcode=RoutingOp.CONST, 252 + pe=0, 253 + iram_offset=1, 254 + ctx=0, 255 + const=10, 256 + loc=SourceLoc(2, 1), 257 + ) 258 + system = SystemConfig(pe_count=1, sm_count=1) 259 + graph = IRGraph( 260 + {"&a": node1, "&b": node2}, 261 + data_defs=[data_def], 262 + system=system, 263 + ) 264 + 265 + tokens = generate_tokens(graph) 266 + 267 + # Find positions of token types 268 + smtoken_indices = [ 269 + i for i, t in enumerate(tokens) 270 + if isinstance(t, SMToken) 271 + ] 272 + route_set_indices = [ 273 + i for i, t in enumerate(tokens) 274 + if isinstance(t, CfgToken) and t.op == CfgOp.ROUTE_SET 275 + ] 276 + load_inst_indices = [ 277 + i for i, t in enumerate(tokens) 278 + if isinstance(t, CfgToken) and t.op == CfgOp.LOAD_INST 279 + ] 280 + seed_indices = [ 281 + i for i, t in enumerate(tokens) if isinstance(t, MonadToken) 282 + ] 283 + 284 + # Verify order: SM < ROUTE_SET < LOAD_INST < seed 285 + assert smtoken_indices, "Should have at least one SM token" 286 + assert route_set_indices, "Should have at least one ROUTE_SET token" 287 + assert load_inst_indices, "Should have at least one LOAD_INST token" 288 + assert seed_indices, "Should have at least one seed token" 289 + assert max(smtoken_indices) < min(route_set_indices), "SM tokens should come before ROUTE_SET" 290 + assert max(route_set_indices) < min(load_inst_indices), "ROUTE_SET should come before LOAD_INST" 291 + assert max(load_inst_indices) < min(seed_indices), "LOAD_INST should come before seed tokens" 292 + 293 + def test_ac88_tokens_are_valid(self): 294 + """AC8.8: Generated tokens are valid and consumable by emulator. 295 + 296 + Tests that: 297 + - All tokens have required fields set 298 + - Token structure matches emulator expectations 299 + - Tokens can be injected into an emulator System and execution completes 300 + """ 301 + from emu.network import build_topology 302 + import simpy 303 + 304 + data_def = IRDataDef( 305 + name="@val", 306 + sm_id=0, 307 + cell_addr=5, 308 + value=42, 309 + loc=SourceLoc(1, 1), 310 + ) 311 + node = IRNode( 312 + name="&add", 313 + opcode=ArithOp.ADD, 314 + pe=0, 315 + iram_offset=0, 316 + ctx=0, 317 + loc=SourceLoc(1, 1), 318 + ) 319 + system = SystemConfig(pe_count=1, sm_count=1) 320 + graph = IRGraph( 321 + {"&add": node}, 322 + data_defs=[data_def], 323 + system=system, 324 + ) 325 + 326 + result = generate_direct(graph) 327 + tokens = generate_tokens(graph) 328 + 329 + # Build emulator system from AssemblyResult configs 330 + env = simpy.Environment() 331 + emu_system = build_topology( 332 + env, 333 + result.pe_configs, 334 + result.sm_configs, 335 + fifo_capacity=16, 336 + ) 337 + 338 + # Inject tokens into the system following the sequence: 339 + # 1. SM init tokens (paired with SM ID) 340 + # 2. ROUTE_SET and LOAD_INST CfgTokens 341 + # 3. Seed MonadTokens 342 + for token in tokens: 343 + if isinstance(token, SMToken): 344 + emu_system.inject(token) 345 + elif isinstance(token, CfgToken): 346 + emu_system.inject(token) 347 + elif isinstance(token, MonadToken): 348 + emu_system.inject(token) 349 + 350 + # Run the simulation for enough steps to complete initialization 351 + env.run(until=1000) 352 + 353 + # Verify token structure 354 + for token in tokens: 355 + if isinstance(token, SMToken): 356 + assert isinstance(token.target, int) 357 + assert isinstance(token.addr, int) 358 + assert isinstance(token.op, MemOp) 359 + assert token.op == MemOp.WRITE 360 + elif isinstance(token, RouteSetToken): 361 + assert isinstance(token.target, int) 362 + assert isinstance(token.op, CfgOp) 363 + assert isinstance(token.pe_routes, tuple) 364 + assert isinstance(token.sm_routes, tuple) 365 + elif isinstance(token, LoadInstToken): 366 + assert isinstance(token.target, int) 367 + assert isinstance(token.op, CfgOp) 368 + assert isinstance(token.instructions, tuple) 369 + elif isinstance(token, MonadToken): 370 + assert isinstance(token.target, int) 371 + assert isinstance(token.offset, int) 372 + assert isinstance(token.ctx, int) 373 + assert isinstance(token.data, int) 374 + 375 + 376 + class TestEdgeCases: 377 + """AC8.9, AC8.10: Edge cases for code generation.""" 378 + 379 + def test_ac89_no_data_defs(self): 380 + """AC8.9: Program with no data_defs produces no SMConfig or SM tokens. 381 + 382 + Tests that: 383 + - sm_configs list is empty 384 + - Token stream has no SMTokens 385 + """ 386 + node = IRNode( 387 + name="&add", 388 + opcode=ArithOp.ADD, 389 + pe=0, 390 + iram_offset=0, 391 + ctx=0, 392 + loc=SourceLoc(1, 1), 393 + ) 394 + system = SystemConfig(pe_count=1, sm_count=1) 395 + graph = IRGraph({"&add": node}, system=system) 396 + 397 + result = generate_direct(graph) 398 + assert len(result.sm_configs) == 0 399 + 400 + tokens = generate_tokens(graph) 401 + sm_tokens = [t for t in tokens if isinstance(t, SMToken)] 402 + assert len(sm_tokens) == 0 403 + 404 + def test_ac810_single_pe_self_route(self): 405 + """AC8.10: Single-PE program ROUTE_SET contains only self-route. 406 + 407 + Tests that: 408 + - allowed_pe_routes contains only the PE's own ID 409 + - Single-PE graph produces ROUTE_SET with pe_routes=[pe_id] 410 + """ 411 + node = IRNode( 412 + name="&add", 413 + opcode=ArithOp.ADD, 414 + pe=0, 415 + iram_offset=0, 416 + ctx=0, 417 + loc=SourceLoc(1, 1), 418 + ) 419 + system = SystemConfig(pe_count=1, sm_count=1) 420 + graph = IRGraph({"&add": node}, system=system) 421 + 422 + result = generate_direct(graph) 423 + assert len(result.pe_configs) == 1 424 + pe_config = result.pe_configs[0] 425 + assert pe_config.allowed_pe_routes == {0} 426 + 427 + tokens = generate_tokens(graph) 428 + route_set_tokens = [ 429 + t for t in tokens 430 + if isinstance(t, RouteSetToken) 431 + ] 432 + assert len(route_set_tokens) == 1 433 + token = route_set_tokens[0] 434 + assert token.pe_routes == (0,) 435 + 436 + def test_multiple_data_defs_same_sm(self): 437 + """Multiple data_defs targeting same SM produce single SMConfig. 438 + 439 + Tests that: 440 + - Multiple data_defs for SM0 are merged into single SMConfig 441 + - initial_cells contains all entries 442 + """ 443 + data_def1 = IRDataDef( 444 + name="@val1", 445 + sm_id=0, 446 + cell_addr=5, 447 + value=42, 448 + loc=SourceLoc(1, 1), 449 + ) 450 + data_def2 = IRDataDef( 451 + name="@val2", 452 + sm_id=0, 453 + cell_addr=10, 454 + value=99, 455 + loc=SourceLoc(2, 1), 456 + ) 457 + system = SystemConfig(pe_count=1, sm_count=1) 458 + graph = IRGraph({}, data_defs=[data_def1, data_def2], system=system) 459 + 460 + result = generate_direct(graph) 461 + 462 + assert len(result.sm_configs) == 1 463 + sm_config = result.sm_configs[0] 464 + assert sm_config.sm_id == 0 465 + assert len(sm_config.initial_cells) == 2 466 + assert sm_config.initial_cells[5] == (Presence.FULL, 42) 467 + assert sm_config.initial_cells[10] == (Presence.FULL, 99) 468 + 469 + def test_const_node_with_incoming_edge_not_seed(self): 470 + """CONST node with incoming edge is not a seed token. 471 + 472 + Tests that: 473 + - Only CONST nodes with NO incoming edges produce seed_tokens 474 + """ 475 + source_node = IRNode( 476 + name="&src", 477 + opcode=ArithOp.ADD, 478 + pe=0, 479 + iram_offset=0, 480 + ctx=0, 481 + loc=SourceLoc(1, 1), 482 + ) 483 + const_node = IRNode( 484 + name="&const", 485 + opcode=RoutingOp.CONST, 486 + pe=0, 487 + iram_offset=1, 488 + ctx=0, 489 + const=5, 490 + loc=SourceLoc(2, 1), 491 + ) 492 + edge = IREdge(source="&src", dest="&const", port=Port.L, loc=SourceLoc(1, 1)) 493 + system = SystemConfig(pe_count=1, sm_count=1) 494 + graph = IRGraph( 495 + {"&src": source_node, "&const": const_node}, 496 + edges=[edge], 497 + system=system, 498 + ) 499 + 500 + result = generate_direct(graph) 501 + 502 + # The CONST node has an incoming edge, so it should NOT be a seed 503 + assert len(result.seed_tokens) == 0 504 + 505 + 506 + class TestMultiPERouting: 507 + """Extended tests for multi-PE routing scenarios.""" 508 + 509 + def test_multi_pe_route_computation(self): 510 + """Multi-PE graph with multiple cross-PE edges. 511 + 512 + Tests route computation across multiple PEs with various edge patterns. 513 + """ 514 + # Create a 3-PE system with cross-PE edges 515 + node_pe0 = IRNode( 516 + name="&a", 517 + opcode=ArithOp.ADD, 518 + pe=0, 519 + iram_offset=0, 520 + ctx=0, 521 + dest_l=ResolvedDest( 522 + name="&b", 523 + addr=Addr(a=0, port=Port.L, pe=1), 524 + ), 525 + loc=SourceLoc(1, 1), 526 + ) 527 + node_pe1 = IRNode( 528 + name="&b", 529 + opcode=ArithOp.SUB, 530 + pe=1, 531 + iram_offset=0, 532 + ctx=0, 533 + dest_l=ResolvedDest( 534 + name="&c", 535 + addr=Addr(a=0, port=Port.L, pe=2), 536 + ), 537 + loc=SourceLoc(2, 1), 538 + ) 539 + node_pe2 = IRNode( 540 + name="&c", 541 + opcode=ArithOp.INC, 542 + pe=2, 543 + iram_offset=0, 544 + ctx=0, 545 + loc=SourceLoc(3, 1), 546 + ) 547 + edge1 = IREdge(source="&a", dest="&b", port=Port.L, loc=SourceLoc(1, 1)) 548 + edge2 = IREdge(source="&b", dest="&c", port=Port.L, loc=SourceLoc(2, 1)) 549 + system = SystemConfig(pe_count=3, sm_count=1) 550 + graph = IRGraph( 551 + {"&a": node_pe0, "&b": node_pe1, "&c": node_pe2}, 552 + edges=[edge1, edge2], 553 + system=system, 554 + ) 555 + 556 + result = generate_direct(graph) 557 + 558 + pe0_config = next(c for c in result.pe_configs if c.pe_id == 0) 559 + pe1_config = next(c for c in result.pe_configs if c.pe_id == 1) 560 + pe2_config = next(c for c in result.pe_configs if c.pe_id == 2) 561 + 562 + # PE0 -> PE1 563 + assert 1 in pe0_config.allowed_pe_routes 564 + # PE1 -> PE2 565 + assert 2 in pe1_config.allowed_pe_routes 566 + # PE2 has no outgoing edges 567 + assert pe2_config.allowed_pe_routes == {2}

+380

tests/test_e2e.py

··· 1 + """End-to-end integration tests: assemble source, emulate, verify results. 2 + 3 + Tests verify: 4 + - or1-asm.AC9.1: CONST→ADD chain produces correct sum 5 + - or1-asm.AC9.2: SM round-trip (write, deferred read) returns correct value 6 + - or1-asm.AC9.3: Cross-PE routing delivers token to destination PE 7 + - or1-asm.AC9.4: SWITCH routing sends data to taken path, trigger to not_taken 8 + - or1-asm.AC9.5: Token stream mode produces identical results to direct mode 9 + - or1-asm.AC10.5: Auto-placed (unplaced) programs assemble and execute correctly 10 + """ 11 + 12 + import simpy 13 + 14 + from asm import assemble, assemble_to_tokens 15 + from emu import build_topology 16 + from tokens import CfgToken, MonadToken, SMToken 17 + 18 + 19 + def run_program_direct(source: str, until: int = 1000) -> dict: 20 + """Assemble source in direct mode, run through emulator. 21 + 22 + Args: 23 + source: dfasm source code as a string 24 + until: Simulation timeout in time units (default: 1000) 25 + 26 + Returns: 27 + Dict mapping PE ID to list of output tokens from that PE 28 + """ 29 + result = assemble(source) 30 + env = simpy.Environment() 31 + sys = build_topology(env, result.pe_configs, result.sm_configs) 32 + 33 + # Inject seed tokens 34 + for seed in result.seed_tokens: 35 + sys.inject(seed) 36 + 37 + env.run(until=until) 38 + 39 + # Collect output from each PE's output_log 40 + outputs = {} 41 + for pe_id, pe in sys.pes.items(): 42 + outputs[pe_id] = list(pe.output_log) 43 + 44 + return outputs 45 + 46 + 47 + def run_program_tokens(source: str, until: int = 1000) -> dict: 48 + """Assemble source to token stream mode, run through emulator. 49 + 50 + Builds topology normally, injects all tokens, runs simulation, and collects 51 + output from each PE's output_log. 52 + 53 + Args: 54 + source: dfasm source code as a string 55 + until: Simulation timeout in time units (default: 1000) 56 + 57 + Returns: 58 + Dict mapping PE ID to list of output tokens collected from that PE 59 + """ 60 + tokens = assemble_to_tokens(source) 61 + env = simpy.Environment() 62 + 63 + # Extract PE and SM counts from tokens 64 + max_pe_id = 0 65 + max_sm_id = 0 66 + 67 + for token in tokens: 68 + if isinstance(token, SMToken): 69 + max_sm_id = max(max_sm_id, token.target) 70 + elif isinstance(token, CfgToken): 71 + max_pe_id = max(max_pe_id, token.target) 72 + elif isinstance(token, MonadToken): 73 + max_pe_id = max(max_pe_id, token.target) 74 + 75 + # Create minimal PE configs (empty IRAM - will be filled by LOAD_INST) 76 + from emu.types import PEConfig, SMConfig 77 + pe_configs = [PEConfig(i, {}) for i in range(max_pe_id + 1)] 78 + sm_configs = [SMConfig(i) for i in range(max_sm_id + 1)] 79 + 80 + sys = build_topology(env, pe_configs, sm_configs) 81 + 82 + # Inject tokens in order (do NOT modify route_table) 83 + for token in tokens: 84 + sys.inject(token) 85 + 86 + env.run(until=until) 87 + 88 + # Collect output from each PE's output_log 89 + outputs = {} 90 + for i in range(max_pe_id + 1): 91 + outputs[i] = list(sys.pes[i].output_log) 92 + 93 + return outputs 94 + 95 + 96 + class TestAC91ConstToAddChain: 97 + """AC9.1: CONST→ADD chain produces correct sum.""" 98 + 99 + def test_const_add_chain_direct(self): 100 + """Direct mode: two const nodes feed an add node, should produce sum (10).""" 101 + source = """ 102 + @system pe=2, sm=0 103 + &c1|pe0 <| const, 3 104 + &c2|pe0 <| const, 7 105 + &result|pe0 <| add 106 + &output|pe1 <| pass 107 + &c1|pe0 |> &result|pe0:L 108 + &c2|pe0 |> &result|pe0:R 109 + &result|pe0 |> &output|pe1:L 110 + """ 111 + outputs = run_program_direct(source) 112 + # Result PE produces the sum: 3 + 7 = 10 113 + result_outputs = outputs[0] 114 + assert any(t.data == 10 for t in result_outputs if hasattr(t, 'data')), \ 115 + f"Expected result 10 in PE0 outputs, got {[t.data for t in result_outputs if hasattr(t, 'data')]}" 116 + 117 + def test_const_add_chain_tokens(self): 118 + """Token stream mode: const add chain should produce sum (10).""" 119 + source = """ 120 + @system pe=2, sm=0 121 + &c1|pe0 <| const, 3 122 + &c2|pe0 <| const, 7 123 + &result|pe0 <| add 124 + &output|pe1 <| pass 125 + &c1|pe0 |> &result|pe0:L 126 + &c2|pe0 |> &result|pe0:R 127 + &result|pe0 |> &output|pe1:L 128 + """ 129 + outputs = run_program_tokens(source) 130 + # Result PE produces the sum: 3 + 7 = 10 131 + result_outputs = outputs[0] 132 + assert any(t.data == 10 for t in result_outputs if hasattr(t, 'data')), \ 133 + f"Expected result 10 in PE0 outputs, got {[t.data for t in result_outputs if hasattr(t, 'data')]}" 134 + 135 + 136 + class TestAC92SMMRoundTrip: 137 + """AC9.2: SM round-trip (write, deferred read) returns correct value.""" 138 + 139 + def test_sm_read_deferred_direct(self): 140 + """Direct mode: SM write+read round-trip returns stored value 0x42.""" 141 + source = """ 142 + @system pe=3, sm=1 143 + @val|sm0:5 = 0x42 144 + &trigger|pe0 <| const, 1 145 + &reader|pe0 <| read, 5 146 + &relay|pe1 <| pass 147 + &sink|pe2 <| pass 148 + &trigger|pe0 |> &reader|pe0:L 149 + &reader|pe0 |> &relay|pe1:L 150 + &relay|pe1 |> &sink|pe2:L 151 + """ 152 + outputs = run_program_direct(source) 153 + relay_outputs = [t.data for t in outputs[1] if hasattr(t, 'data')] 154 + assert 66 in relay_outputs, \ 155 + f"Expected SM read value 66 (0x42) in PE1 outputs, got {relay_outputs}" 156 + 157 + def test_sm_read_deferred_tokens(self): 158 + """Token stream mode: SM write+read round-trip returns stored value 0x42.""" 159 + source = """ 160 + @system pe=3, sm=1 161 + @val|sm0:5 = 0x42 162 + &trigger|pe0 <| const, 1 163 + &reader|pe0 <| read, 5 164 + &relay|pe1 <| pass 165 + &sink|pe2 <| pass 166 + &trigger|pe0 |> &reader|pe0:L 167 + &reader|pe0 |> &relay|pe1:L 168 + &relay|pe1 |> &sink|pe2:L 169 + """ 170 + outputs = run_program_tokens(source) 171 + relay_outputs = [t.data for t in outputs[1] if hasattr(t, 'data')] 172 + assert 66 in relay_outputs, \ 173 + f"Expected SM read value 66 (0x42) in PE1 outputs, got {relay_outputs}" 174 + 175 + 176 + class TestAC93CrossPERouting: 177 + """AC9.3: Cross-PE routing delivers token to destination PE.""" 178 + 179 + def test_cross_pe_routing_direct(self): 180 + """Direct mode: cross-PE routing assembles and PE0 emits token to PE1.""" 181 + source = """ 182 + @system pe=3, sm=0 183 + &source|pe0 <| const, 99 184 + &dest|pe1 <| pass 185 + &output|pe2 <| pass 186 + &source|pe0 |> &dest|pe1:L 187 + &dest|pe1 |> &output|pe2:L 188 + """ 189 + outputs = run_program_direct(source) 190 + # PE0 should emit the constant value 99 to PE1 191 + source_outputs = outputs[0] 192 + assert any(t.data == 99 for t in source_outputs if hasattr(t, 'data')), \ 193 + f"Expected value 99 in PE0 outputs, got {[t.data for t in source_outputs if hasattr(t, 'data')]}" 194 + 195 + def test_cross_pe_routing_tokens(self): 196 + """Token stream mode: cross-PE routing assembles and PE0 emits token to PE1.""" 197 + source = """ 198 + @system pe=3, sm=0 199 + &source|pe0 <| const, 99 200 + &dest|pe1 <| pass 201 + &output|pe2 <| pass 202 + &source|pe0 |> &dest|pe1:L 203 + &dest|pe1 |> &output|pe2:L 204 + """ 205 + outputs = run_program_tokens(source) 206 + # PE0 should emit the constant value 99 to PE1 207 + source_outputs = outputs[0] 208 + assert any(t.data == 99 for t in source_outputs if hasattr(t, 'data')), \ 209 + f"Expected value 99 in PE0 outputs, got {[t.data for t in source_outputs if hasattr(t, 'data')]}" 210 + 211 + 212 + class TestAC94SwitchRouting: 213 + """AC9.4: SWITCH routing sends data to taken path, trigger to not_taken.""" 214 + 215 + def test_switch_equal_inputs_direct(self): 216 + """Direct mode: SWITCH correctly routes data to taken and trigger to not_taken.""" 217 + source = """ 218 + @system pe=3, sm=0 219 + &val|pe0 <| const, 5 220 + &cmp|pe0 <| const, 5 221 + &branch|pe0 <| sweq 222 + &taken|pe1 <| pass 223 + &not_taken|pe1 <| pass 224 + &output|pe2 <| pass 225 + &val|pe0 |> &branch|pe0:L 226 + &cmp|pe0 |> &branch|pe0:R 227 + &branch|pe0:L |> &taken|pe1:L 228 + &branch|pe0:R |> &not_taken|pe1:L 229 + &taken|pe1 |> &output|pe2:L 230 + &not_taken|pe1 |> &output|pe2:R 231 + """ 232 + outputs = run_program_direct(source) 233 + # PE0 should emit data (5) to taken and trigger (0) to not_taken 234 + pe0_outputs = [t.data for t in outputs[0] if hasattr(t, 'data')] 235 + assert 5 in pe0_outputs, f"Expected data value 5 emitted from PE0, got {pe0_outputs}" 236 + assert 0 in pe0_outputs, f"Expected trigger value 0 emitted from PE0, got {pe0_outputs}" 237 + 238 + def test_switch_equal_inputs_tokens(self): 239 + """Token stream mode: SWITCH correctly routes data to taken and trigger to not_taken.""" 240 + source = """ 241 + @system pe=3, sm=0 242 + &val|pe0 <| const, 5 243 + &cmp|pe0 <| const, 5 244 + &branch|pe0 <| sweq 245 + &taken|pe1 <| pass 246 + &not_taken|pe1 <| pass 247 + &output|pe2 <| pass 248 + &val|pe0 |> &branch|pe0:L 249 + &cmp|pe0 |> &branch|pe0:R 250 + &branch|pe0:L |> &taken|pe1:L 251 + &branch|pe0:R |> &not_taken|pe1:L 252 + &taken|pe1 |> &output|pe2:L 253 + &not_taken|pe1 |> &output|pe2:R 254 + """ 255 + outputs = run_program_tokens(source) 256 + # PE0 should emit data (5) to taken and trigger (0) to not_taken 257 + pe0_outputs = [t.data for t in outputs[0] if hasattr(t, 'data')] 258 + assert 5 in pe0_outputs, f"Expected data value 5 emitted from PE0, got {pe0_outputs}" 259 + assert 0 in pe0_outputs, f"Expected trigger value 0 emitted from PE0, got {pe0_outputs}" 260 + 261 + 262 + class TestAC95ModeEquivalence: 263 + """AC9.5: Both output modes (direct and token stream) produce identical results.""" 264 + 265 + def test_mode_equivalence_complex_graph(self): 266 + """Complex program produces same result (30) in both direct and token modes.""" 267 + source = """ 268 + @system pe=3, sm=0 269 + &a|pe0 <| const, 10 270 + &b|pe0 <| const, 20 271 + &sum|pe0 <| add 272 + &out|pe1 <| pass 273 + &ext|pe2 <| pass 274 + &a|pe0 |> &sum|pe0:L 275 + &b|pe0 |> &sum|pe0:R 276 + &sum|pe0 |> &out|pe1:L 277 + &out|pe1 |> &ext|pe2:L 278 + """ 279 + # Both modes should produce the same result: 30 (10 + 20) 280 + direct_outputs = run_program_direct(source) 281 + token_outputs = run_program_tokens(source) 282 + 283 + # Get result from PE0 in both modes (where sum is computed and emitted) 284 + direct_result = [t.data for t in direct_outputs[0] if hasattr(t, 'data')] 285 + token_result = [t.data for t in token_outputs[0] if hasattr(t, 'data')] 286 + 287 + # Both should produce 30 (10 + 20) 288 + assert 30 in direct_result, f"Direct mode: expected 30 in PE0, got {direct_result}" 289 + assert 30 in token_result, f"Token mode: expected 30 in PE0, got {token_result}" 290 + 291 + 292 + class TestAC105AutoPlacedE2E: 293 + """AC10.5: Auto-placed (unplaced) programs assemble and execute correctly.""" 294 + 295 + def test_autoplaced_const_add_chain(self): 296 + """Unplaced const-add program auto-places and produces correct sum.""" 297 + source = """ 298 + @system pe=3, sm=0 299 + &c1 <| const, 3 300 + &c2 <| const, 7 301 + &result <| add 302 + &output <| pass 303 + &c1 |> &result:L 304 + &c2 |> &result:R 305 + &result |> &output:L 306 + """ 307 + outputs = run_program_direct(source) 308 + # Find which PE has the output by checking all outputs 309 + all_values = [] 310 + for pe_outputs in outputs.values(): 311 + all_values.extend([t.data for t in pe_outputs if hasattr(t, 'data')]) 312 + assert 10 in all_values, f"Expected sum 10 in any PE output, got {all_values}" 313 + 314 + def test_autoplaced_cross_pe_routing(self): 315 + """Unplaced cross-PE routing auto-places and produces 99 in both modes.""" 316 + source = """ 317 + @system pe=3, sm=0 318 + &source <| const, 99 319 + &dest <| pass 320 + &output <| pass 321 + &source |> &dest:L 322 + &dest |> &output:L 323 + """ 324 + # Both modes should produce 99 somewhere 325 + direct_outputs = run_program_direct(source) 326 + token_outputs = run_program_tokens(source) 327 + 328 + # Check direct mode - source node should emit 99 329 + direct_values = [] 330 + for pe_outputs in direct_outputs.values(): 331 + direct_values.extend([t.data for t in pe_outputs if hasattr(t, 'data')]) 332 + assert 99 in direct_values, f"Direct mode: expected 99, got {direct_values}" 333 + 334 + # Check token mode - source node should emit 99 335 + token_values = [] 336 + for pe_outputs in token_outputs.values(): 337 + token_values.extend([t.data for t in pe_outputs if hasattr(t, 'data')]) 338 + assert 99 in token_values, f"Token mode: expected 99, got {token_values}" 339 + 340 + def test_autoplaced_vs_explicit_equivalence(self): 341 + """Auto-placed program produces same result (8) as explicitly-placed version.""" 342 + explicit = """ 343 + @system pe=3, sm=0 344 + &c1|pe0 <| const, 5 345 + &c2|pe0 <| const, 3 346 + &result|pe1 <| add 347 + &output|pe2 <| pass 348 + &c1|pe0 |> &result|pe1:L 349 + &c2|pe0 |> &result|pe1:R 350 + &result|pe1 |> &output|pe2:L 351 + """ 352 + autoplaced = """ 353 + @system pe=3, sm=0 354 + &c1 <| const, 5 355 + &c2 <| const, 3 356 + &result <| add 357 + &output <| pass 358 + &c1 |> &result:L 359 + &c2 |> &result:R 360 + &result |> &output:L 361 + """ 362 + # Both should produce 8 (5 + 3) in both modes 363 + explicit_direct = run_program_direct(explicit) 364 + explicit_tokens = run_program_tokens(explicit) 365 + autoplaced_direct = run_program_direct(autoplaced) 366 + autoplaced_tokens = run_program_tokens(autoplaced) 367 + 368 + # Verify all modes produce 8 369 + for mode_name, outputs in [ 370 + ("explicit_direct", explicit_direct), 371 + ("explicit_tokens", explicit_tokens), 372 + ("autoplaced_direct", autoplaced_direct), 373 + ("autoplaced_tokens", autoplaced_tokens), 374 + ]: 375 + all_values = [] 376 + for pe_outputs in outputs.values(): 377 + all_values.extend([t.data for t in pe_outputs if hasattr(t, 'data')]) 378 + assert 8 in all_values, f"{mode_name}: expected 8, got {all_values}" 379 + 380 +

+18 -15

tests/test_integration.py

··· 4 4 Verifies: 5 5 - or1-emu.AC5.1: IRAM initialization — PE has expected instructions at expected offsets 6 6 - or1-emu.AC5.2: SM cell initialization — SM cells match config 7 - - or1-emu.AC5.3: Token injection — inject() and inject_sm() deliver tokens to correct stores 7 + - or1-emu.AC5.3: Token injection — inject() routes tokens to correct stores by type 8 8 """ 9 9 10 10 import simpy ··· 12 12 from cm_inst import ALUInst, ArithOp, RoutingOp, Addr, SMInst 13 13 from emu import build_topology, PEConfig, SMConfig 14 14 from sm_mod import Presence 15 - from tokens import CMToken, MonadToken, SMToken, MemOp, Port, DyadToken, CfgToken, CfgOp 15 + from tokens import CMToken, MonadToken, SMToken, MemOp, Port, DyadToken, CfgToken, CfgOp, LoadInstToken 16 16 17 17 18 18 class TestAC51IRAMInitialization: ··· 179 179 assert sys.pes[1].input_store.items[0].data == 20 180 180 181 181 def test_inject_sm_token_to_sm(self): 182 - """inject_sm() delivers SMToken to correct SM's input_store.""" 182 + """inject() delivers SMToken to correct SM's input_store.""" 183 183 env = simpy.Environment() 184 184 185 185 sys = build_topology( ··· 190 190 191 191 # Create and inject token to SM0 192 192 token = SMToken( 193 - target=5, # cell address (not SM id) 193 + target=0, 194 + addr=5, 194 195 op=MemOp.READ, 195 196 flags=None, 196 197 data=None, 197 198 ret=CMToken(target=0, offset=0, ctx=0, data=0), 198 199 ) 199 200 200 - sys.inject_sm(0, token) 201 + sys.inject(token) 201 202 202 203 # Verify token is in SM0's input_store 203 204 assert len(sys.sms[0].input_store.items) == 1 204 205 assert sys.sms[0].input_store.items[0] == token 205 206 206 207 def test_inject_sm_multiple_tokens_to_correct_sms(self): 207 - """inject_sm() places tokens in correct SM based on sm_id parameter.""" 208 + """inject() routes SMTokens to correct SM based on token.target.""" 208 209 env = simpy.Environment() 209 210 210 211 sys = build_topology( ··· 215 216 216 217 # Inject token to SM0 217 218 token0 = SMToken( 218 - target=10, 219 + target=0, 220 + addr=10, 219 221 op=MemOp.WRITE, 220 222 flags=None, 221 223 data=42, 222 224 ret=None, 223 225 ) 224 - sys.inject_sm(0, token0) 226 + sys.inject(token0) 225 227 226 228 # Inject token to SM1 227 229 token1 = SMToken( 228 - target=20, 230 + target=1, 231 + addr=20, 229 232 op=MemOp.READ, 230 233 flags=None, 231 234 data=None, 232 235 ret=CMToken(target=0, offset=0, ctx=0, data=0), 233 236 ) 234 - sys.inject_sm(1, token1) 237 + sys.inject(token1) 235 238 236 239 # Verify tokens arrived at correct SMs 237 240 assert len(sys.sms[0].input_store.items) == 1 238 - assert sys.sms[0].input_store.items[0].target == 10 241 + assert sys.sms[0].input_store.items[0].addr == 10 239 242 240 243 assert len(sys.sms[1].input_store.items) == 1 241 - assert sys.sms[1].input_store.items[0].target == 20 244 + assert sys.sms[1].input_store.items[0].addr == 20 242 245 243 246 244 247 class TestAC51GenCounterInitialization: ··· 637 640 const=42, 638 641 ) 639 642 640 - # Create CfgToken to load instruction at offset 0 641 - cfg_token = CfgToken( 643 + # Create LoadInstToken to load instruction at offset 0 644 + cfg_token = LoadInstToken( 642 645 target=0, 643 646 addr=0, 644 647 op=CfgOp.LOAD_INST, 645 - data=[const_inst], 648 + instructions=(const_inst,), 646 649 ) 647 650 648 651 # Function to send CfgToken then seed token

+575

tests/test_lower.py

··· 1 + """Tests for the Lower pass (CST → IRGraph transformation). 2 + 3 + Tests verify: 4 + - Instruction definition (inst_def) → IRNode with opcode, placement, named args 5 + - Plain edges → IREdge with correct source, dest, ports 6 + - Strong/weak inline edges → anonymous nodes + wiring 7 + - Data definitions → IRDataDef with SM ID, cell address, packed values 8 + - System pragma → SystemConfig with pe_count, sm_count, etc. 9 + - Function scoping → qualified names, nested IRRegions 10 + - Location directives → LOCATION IRRegions 11 + - Error handling → reserved names, duplicate definitions 12 + """ 13 + 14 + from tests.pipeline import parse_and_lower 15 + 16 + from asm.ir import RegionKind, SourceLoc 17 + from asm.errors import ErrorCategory 18 + from cm_inst import ArithOp, LogicOp, RoutingOp 19 + from tokens import Port, MemOp 20 + 21 + 22 + class TestInstDef: 23 + """Tests for instruction definition (AC2.1, AC2.8, AC2.9).""" 24 + 25 + def test_basic_instruction(self, parser): 26 + """Parse simple instruction definition.""" 27 + graph = parse_and_lower(parser, """\ 28 + &my_add <| add 29 + """) 30 + 31 + assert "&my_add" in graph.nodes 32 + node = graph.nodes["&my_add"] 33 + assert node.opcode == ArithOp.ADD 34 + assert node.name == "&my_add" 35 + 36 + def test_instruction_with_const(self, parser): 37 + """Parse instruction with constant operand.""" 38 + graph = parse_and_lower(parser, """\ 39 + &my_const <| const, 42 40 + """) 41 + 42 + assert "&my_const" in graph.nodes 43 + node = graph.nodes["&my_const"] 44 + assert node.opcode == RoutingOp.CONST 45 + assert node.const == 42 46 + 47 + def test_instruction_with_hex_const(self, parser): 48 + """Parse instruction with hexadecimal constant.""" 49 + graph = parse_and_lower(parser, """\ 50 + &mask <| const, 0xFF 51 + """) 52 + 53 + assert "&mask" in graph.nodes 54 + node = graph.nodes["&mask"] 55 + assert node.const == 0xFF 56 + 57 + def test_instruction_with_pe_placement(self, parser): 58 + """Parse instruction with PE placement qualifier (AC2.8).""" 59 + graph = parse_and_lower(parser, """\ 60 + &my_add|pe0 <| add 61 + """) 62 + 63 + assert "&my_add" in graph.nodes 64 + node = graph.nodes["&my_add"] 65 + assert node.pe == 0 66 + 67 + def test_instruction_with_pe_placement_nonzero(self, parser): 68 + """Parse instruction with non-zero PE placement.""" 69 + graph = parse_and_lower(parser, """\ 70 + &result|pe2 <| pass 71 + """) 72 + 73 + assert "&result" in graph.nodes 74 + node = graph.nodes["&result"] 75 + assert node.pe == 2 76 + 77 + def test_instruction_with_named_args(self, parser): 78 + """Parse instruction with named arguments (AC2.9).""" 79 + graph = parse_and_lower(parser, """\ 80 + &serial <| ior, dest=0x45 81 + """) 82 + 83 + # ior is not in MNEMONIC_TO_OP, so we should have an error 84 + # but the instruction should still be created or we should check errors 85 + assert len(graph.errors) > 0 86 + 87 + def test_shift_instruction(self, parser): 88 + """Parse shift instruction.""" 89 + graph = parse_and_lower(parser, """\ 90 + &shift_left <| shiftl 91 + """) 92 + 93 + assert "&shift_left" in graph.nodes 94 + node = graph.nodes["&shift_left"] 95 + assert node.opcode == ArithOp.SHIFT_L 96 + 97 + 98 + class TestPlainEdge: 99 + """Tests for plain edges (AC2.2).""" 100 + 101 + def test_basic_plain_edge(self, parser): 102 + """Parse basic plain edge.""" 103 + graph = parse_and_lower(parser, """\ 104 + &a <| pass 105 + &b <| add 106 + &a |> &b:L 107 + """) 108 + 109 + assert len(graph.edges) == 1 110 + edge = graph.edges[0] 111 + assert edge.source == "&a" 112 + assert edge.dest == "&b" 113 + assert edge.port == Port.L 114 + 115 + def test_plain_edge_to_right_port(self, parser): 116 + """Parse plain edge to right port.""" 117 + graph = parse_and_lower(parser, """\ 118 + &a <| pass 119 + &b <| add 120 + &a |> &b:R 121 + """) 122 + 123 + assert len(graph.edges) == 1 124 + edge = graph.edges[0] 125 + assert edge.port == Port.R 126 + 127 + def test_plain_edge_fanout(self, parser): 128 + """Parse fanout (one source to multiple destinations).""" 129 + graph = parse_and_lower(parser, """\ 130 + &a <| pass 131 + &b <| add 132 + &c <| sub 133 + &a |> &b:L, &c:R 134 + """) 135 + 136 + assert len(graph.edges) == 2 137 + assert graph.edges[0].dest == "&b" 138 + assert graph.edges[0].port == Port.L 139 + assert graph.edges[1].dest == "&c" 140 + assert graph.edges[1].port == Port.R 141 + 142 + def test_plain_edge_with_source_port(self, parser): 143 + """Parse plain edge with source port specification.""" 144 + graph = parse_and_lower(parser, """\ 145 + &a:L <| pass 146 + &b <| add 147 + &a:L |> &b:L 148 + """) 149 + 150 + assert len(graph.edges) == 1 151 + edge = graph.edges[0] 152 + assert edge.source_port == Port.L 153 + 154 + 155 + class TestStrongEdge: 156 + """Tests for strong inline edges (AC2.3).""" 157 + 158 + def test_basic_strong_edge(self, parser): 159 + """Parse basic strong inline edge.""" 160 + graph = parse_and_lower(parser, """\ 161 + &a <| pass 162 + &b <| pass 163 + &c <| pass 164 + &d <| pass 165 + add &a, &b |> &c, &d 166 + """) 167 + 168 + # Should create anonymous node 169 + anon_nodes = [n for n in graph.nodes.keys() if n.startswith("&__anon_")] 170 + assert len(anon_nodes) == 1 171 + anon_name = anon_nodes[0] 172 + 173 + anon_node = graph.nodes[anon_name] 174 + assert anon_node.opcode == ArithOp.ADD 175 + 176 + # Should create 4 edges: 2 inputs, 2 outputs 177 + assert len(graph.edges) == 4 178 + 179 + # Verify input edges 180 + input_edges = [e for e in graph.edges if e.dest == anon_name] 181 + assert len(input_edges) == 2 182 + left_input = [e for e in input_edges if e.port == Port.L][0] 183 + right_input = [e for e in input_edges if e.port == Port.R][0] 184 + assert left_input.source == "&a" 185 + assert right_input.source == "&b" 186 + 187 + # Verify output edges 188 + output_edges = [e for e in graph.edges if e.source == anon_name] 189 + assert len(output_edges) == 2 190 + 191 + def test_strong_edge_anonymous_name_format(self, parser): 192 + """Verify anonymous nodes have correct naming.""" 193 + graph = parse_and_lower(parser, """\ 194 + &a <| pass 195 + &b <| pass 196 + add &a |> &b 197 + """) 198 + 199 + anon_nodes = [n for n in graph.nodes.keys() if n.startswith("&__anon_")] 200 + assert len(anon_nodes) == 1 201 + assert anon_nodes[0].startswith("&__anon_") 202 + 203 + 204 + class TestWeakEdge: 205 + """Tests for weak inline edges (AC2.4).""" 206 + 207 + def test_basic_weak_edge(self, parser): 208 + """Parse basic weak inline edge.""" 209 + graph = parse_and_lower(parser, """\ 210 + &a <| pass 211 + &b <| pass 212 + &c <| pass 213 + &d <| pass 214 + &c, &d sub <| &a, &b 215 + """) 216 + 217 + # Should create anonymous node 218 + anon_nodes = [n for n in graph.nodes.keys() if n.startswith("&__anon_")] 219 + assert len(anon_nodes) == 1 220 + anon_name = anon_nodes[0] 221 + 222 + anon_node = graph.nodes[anon_name] 223 + assert anon_node.opcode == ArithOp.SUB 224 + 225 + def test_weak_edge_equivalent_to_strong(self, parser): 226 + """Verify weak edge produces same IR as equivalent strong edge.""" 227 + # Parse weak edge version 228 + graph_weak = parse_and_lower(parser, """\ 229 + &a <| pass 230 + &b <| pass 231 + &c <| pass 232 + &d <| pass 233 + &c, &d sub <| &a, &b 234 + """) 235 + 236 + # Parse strong edge version 237 + graph_strong = parse_and_lower(parser, """\ 238 + &a <| pass 239 + &b <| pass 240 + &c <| pass 241 + &d <| pass 242 + sub &a, &b |> &c, &d 243 + """) 244 + 245 + # Both should have one anonymous node 246 + anon_weak = [n for n in graph_weak.nodes.keys() if n.startswith("&__anon_")] 247 + anon_strong = [n for n in graph_strong.nodes.keys() if n.startswith("&__anon_")] 248 + assert len(anon_weak) == 1 249 + assert len(anon_strong) == 1 250 + 251 + # Both should have the same opcodes for the anon nodes 252 + assert graph_weak.nodes[anon_weak[0]].opcode == graph_strong.nodes[anon_strong[0]].opcode 253 + 254 + 255 + class TestDataDef: 256 + """Tests for data definitions (AC2.5, AC2.6).""" 257 + 258 + def test_basic_data_def(self, parser): 259 + """Parse basic data definition.""" 260 + graph = parse_and_lower(parser, """\ 261 + @hello|sm0:0 = 0x05 262 + """) 263 + 264 + assert len(graph.data_defs) == 1 265 + data_def = graph.data_defs[0] 266 + assert data_def.name == "@hello" 267 + assert data_def.sm_id == 0 268 + assert data_def.cell_addr == 0 269 + assert data_def.value == 0x05 270 + 271 + def test_data_def_with_different_sm(self, parser): 272 + """Parse data definition with different SM.""" 273 + graph = parse_and_lower(parser, """\ 274 + @data|sm1:2 = 0x42 275 + """) 276 + 277 + data_def = graph.data_defs[0] 278 + assert data_def.sm_id == 1 279 + assert data_def.cell_addr == 2 280 + 281 + def test_data_def_char_pair_big_endian(self, parser): 282 + """Parse data definition with char pair (big-endian packing) (AC2.6).""" 283 + graph = parse_and_lower(parser, """\ 284 + @hello|sm0:0 = 'h', 'e' 285 + """) 286 + 287 + data_def = graph.data_defs[0] 288 + # 'h' = 0x68, 'e' = 0x65 289 + # Big-endian: (0x68 << 8) | 0x65 = 0x6865 290 + expected = (ord('h') << 8) | ord('e') 291 + assert data_def.value == expected 292 + 293 + def test_data_def_char_pair_he_le(self, parser): 294 + """Verify big-endian packing of char pair.""" 295 + graph = parse_and_lower(parser, """\ 296 + @data|sm0:1 = 'l', 'l' 297 + """) 298 + 299 + data_def = graph.data_defs[0] 300 + expected = (ord('l') << 8) | ord('l') 301 + assert data_def.value == expected 302 + 303 + 304 + class TestSystemConfig: 305 + """Tests for system pragma (AC2.7).""" 306 + 307 + def test_system_pragma_minimal(self, parser): 308 + """Parse minimal system pragma.""" 309 + graph = parse_and_lower(parser, """\ 310 + @system pe=4, sm=1 311 + """) 312 + 313 + assert graph.system is not None 314 + assert graph.system.pe_count == 4 315 + assert graph.system.sm_count == 1 316 + assert graph.system.iram_capacity == 64 # default 317 + assert graph.system.ctx_slots == 4 # default 318 + 319 + def test_system_pragma_full(self, parser): 320 + """Parse full system pragma.""" 321 + graph = parse_and_lower(parser, """\ 322 + @system pe=2, sm=1, iram=128, ctx=2 323 + """) 324 + 325 + assert graph.system.pe_count == 2 326 + assert graph.system.sm_count == 1 327 + assert graph.system.iram_capacity == 128 328 + assert graph.system.ctx_slots == 2 329 + 330 + def test_system_pragma_hex_values(self, parser): 331 + """Parse system pragma with hexadecimal values.""" 332 + graph = parse_and_lower(parser, """\ 333 + @system pe=0x04, sm=0x01 334 + """) 335 + 336 + assert graph.system.pe_count == 4 337 + assert graph.system.sm_count == 1 338 + 339 + 340 + class TestFunctionScoping: 341 + """Tests for function scoping (AC3.1, AC3.2, AC3.3, AC3.4).""" 342 + 343 + def test_label_inside_function_qualified(self, parser): 344 + """Verify labels inside functions are qualified (AC3.1).""" 345 + graph = parse_and_lower(parser, """\ 346 + $main |> { 347 + &add <| add 348 + } 349 + """) 350 + 351 + # Label should be qualified in the function region 352 + assert len(graph.regions) == 1 353 + region = graph.regions[0] 354 + assert "$main.&add" in region.body.nodes 355 + node = region.body.nodes["$main.&add"] 356 + assert node.opcode == ArithOp.ADD 357 + 358 + def test_global_node_not_qualified(self, parser): 359 + """Verify @nodes are never qualified (AC3.2).""" 360 + graph = parse_and_lower(parser, """\ 361 + @global <| pass 362 + """) 363 + 364 + # Should not be qualified 365 + assert "@global" in graph.nodes 366 + assert "$main.@global" not in graph.nodes 367 + 368 + def test_top_level_label_not_qualified(self, parser): 369 + """Verify top-level labels are not qualified (AC3.3).""" 370 + graph = parse_and_lower(parser, """\ 371 + &top <| pass 372 + """) 373 + 374 + # Should not be qualified 375 + assert "&top" in graph.nodes 376 + assert "$main.&top" not in graph.nodes 377 + 378 + def test_same_label_in_different_functions(self, parser): 379 + """Verify functions can each define &add without collision (AC3.4).""" 380 + graph = parse_and_lower(parser, """\ 381 + $foo |> { 382 + &add <| add 383 + } 384 + $bar |> { 385 + &add <| sub 386 + } 387 + """) 388 + 389 + # Both should exist with different names in their respective regions 390 + assert len(graph.regions) == 2 391 + foo_region = next(r for r in graph.regions if r.tag == "$foo") 392 + bar_region = next(r for r in graph.regions if r.tag == "$bar") 393 + assert "$foo.&add" in foo_region.body.nodes 394 + assert "$bar.&add" in bar_region.body.nodes 395 + assert foo_region.body.nodes["$foo.&add"].opcode == ArithOp.ADD 396 + assert bar_region.body.nodes["$bar.&add"].opcode == ArithOp.SUB 397 + 398 + 399 + class TestRegions: 400 + """Tests for regions (AC3.7, AC3.8).""" 401 + 402 + def test_function_region_creation(self, parser): 403 + """Verify function creates FUNCTION region (AC3.7).""" 404 + graph = parse_and_lower(parser, """\ 405 + $func |> { 406 + &a <| add 407 + } 408 + """) 409 + 410 + assert len(graph.regions) == 1 411 + region = graph.regions[0] 412 + assert region.tag == "$func" 413 + assert region.kind == RegionKind.FUNCTION 414 + assert "$func.&a" in region.body.nodes 415 + 416 + def test_location_directive_creates_region(self, parser): 417 + """Verify location directive creates LOCATION region (AC3.8).""" 418 + graph = parse_and_lower(parser, """\ 419 + @data_section|sm0 420 + """) 421 + 422 + assert len(graph.regions) == 1 423 + region = graph.regions[0] 424 + assert region.tag == "@data_section" 425 + assert region.kind == RegionKind.LOCATION 426 + 427 + 428 + class TestErrorCases: 429 + """Tests for error handling (AC3.5, AC3.6).""" 430 + 431 + def test_reserved_name_system_error(self, parser): 432 + """Verify reserved name @system produces error (AC3.5).""" 433 + graph = parse_and_lower(parser, """\ 434 + @system <| add 435 + """) 436 + 437 + # Should have an error (note: @system is a keyword, might parse as pragma) 438 + # If it parses as inst_def, check for NAME error 439 + assert len(graph.errors) > 0 440 + assert any(e.category == ErrorCategory.NAME for e in graph.errors) 441 + 442 + def test_duplicate_label_in_function_error(self, parser): 443 + """Verify duplicate labels in same function produce error (AC3.6).""" 444 + graph = parse_and_lower(parser, """\ 445 + $main |> { 446 + &add <| add 447 + &add <| sub 448 + } 449 + """) 450 + 451 + # Should have a SCOPE error 452 + assert len(graph.errors) > 0 453 + assert any(e.category == ErrorCategory.SCOPE for e in graph.errors) 454 + 455 + def test_duplicate_label_at_top_level_error(self, parser): 456 + """Verify duplicate labels at top level produce error.""" 457 + graph = parse_and_lower(parser, """\ 458 + &label <| add 459 + &label <| sub 460 + """) 461 + 462 + # Should have a SCOPE error 463 + assert len(graph.errors) > 0 464 + assert any(e.category == ErrorCategory.SCOPE for e in graph.errors) 465 + 466 + 467 + class TestMemOps: 468 + """Tests for memory operations.""" 469 + 470 + def test_read_op(self, parser): 471 + """Parse READ operation.""" 472 + graph = parse_and_lower(parser, """\ 473 + &cell <| read 474 + """) 475 + 476 + node = graph.nodes["&cell"] 477 + assert node.opcode == MemOp.READ 478 + 479 + def test_write_op(self, parser): 480 + """Parse WRITE operation.""" 481 + graph = parse_and_lower(parser, """\ 482 + &cell <| write 483 + """) 484 + 485 + node = graph.nodes["&cell"] 486 + assert node.opcode == MemOp.WRITE 487 + 488 + def test_rd_inc_op(self, parser): 489 + """Parse RD_INC operation.""" 490 + graph = parse_and_lower(parser, """\ 491 + &cell <| rd_inc 492 + """) 493 + 494 + node = graph.nodes["&cell"] 495 + assert node.opcode == MemOp.RD_INC 496 + 497 + 498 + class TestEdgeCases: 499 + """Tests for edge cases and integration.""" 500 + 501 + def test_empty_program(self, parser): 502 + """Parse empty program.""" 503 + graph = parse_and_lower(parser, "") 504 + 505 + assert len(graph.nodes) == 0 506 + assert len(graph.edges) == 0 507 + 508 + def test_program_with_comments(self, parser): 509 + """Parse program with comments.""" 510 + graph = parse_and_lower(parser, """\ 511 + &my_add <| add ; this is a comment 512 + &a |> &my_add:L ; wire a to add left 513 + """) 514 + 515 + assert "&my_add" in graph.nodes 516 + assert len(graph.edges) == 1 517 + 518 + def test_multiple_instructions(self, parser): 519 + """Parse multiple instructions.""" 520 + graph = parse_and_lower(parser, """\ 521 + &a <| add 522 + &b <| sub 523 + &c <| pass 524 + """) 525 + 526 + assert len(graph.nodes) == 3 527 + assert "&a" in graph.nodes 528 + assert "&b" in graph.nodes 529 + assert "&c" in graph.nodes 530 + 531 + def test_complex_graph(self, parser): 532 + """Parse a more complex program.""" 533 + graph = parse_and_lower(parser, """\ 534 + @system pe=4, sm=1 535 + 536 + &init <| const, 0 537 + &loop_add <| add 538 + &cmp <| lte 539 + &branch <| breq 540 + 541 + &init |> &loop_add:L 542 + &loop_add |> &cmp:L 543 + &cmp |> &branch:L 544 + """) 545 + 546 + assert graph.system.pe_count == 4 547 + assert len(graph.nodes) == 4 548 + assert len(graph.edges) == 3 549 + 550 + 551 + class TestScalingAnonymousCounters: 552 + """Tests that anonymous counter properly increments.""" 553 + 554 + def test_multiple_strong_edges_increment_counter(self, parser): 555 + """Verify each strong edge gets unique anonymous name.""" 556 + graph = parse_and_lower(parser, """\ 557 + &a <| pass 558 + &b <| pass 559 + &c <| pass 560 + &d <| pass 561 + &e <| pass 562 + &f <| pass 563 + add &a |> &b 564 + sub &c |> &d 565 + inc &e |> &f 566 + """) 567 + 568 + anon_nodes = [n for n in graph.nodes.keys() if n.startswith("&__anon_")] 569 + assert len(anon_nodes) == 3 570 + # Verify they have different counter values 571 + counters = set() 572 + for name in anon_nodes: 573 + counter_str = name.split("_")[-1] 574 + counters.add(int(counter_str)) 575 + assert len(counters) == 3

+228 -3

tests/test_network.py

··· 10 10 11 11 import simpy 12 12 13 - from cm_inst import Addr, ALUInst, MemOp, RoutingOp, SMInst 13 + from cm_inst import Addr, ALUInst, ArithOp, MemOp, RoutingOp, SMInst 14 14 from emu import build_topology, PEConfig, SMConfig 15 15 from emu.pe import ProcessingElement 16 16 from sm_mod import Presence ··· 134 134 # Create a READ token for cell 5, returning to PE0 135 135 return_route = CMToken(target=0, offset=10, ctx=0, data=0) 136 136 sm_token = SMToken( 137 - target=5, 137 + target=0, 138 + addr=5, 138 139 op=MemOp.READ, 139 140 flags=None, 140 141 data=None, 141 142 ret=return_route, 142 143 ) 143 144 144 - sys.inject_sm(0, sm_token) 145 + sys.inject(sm_token) 145 146 146 147 env.run() 147 148 ··· 509 510 cell = sys.sms[0].cells[10] 510 511 assert cell.pres == Presence.FULL 511 512 assert cell.data_l == 88 513 + 514 + 515 + class TestRestrictedTopology: 516 + """Test restricted topology via PEConfig allowed routes (AC7.6–AC7.7). 517 + 518 + Verifies: 519 + - AC7.6: build_topology applies route restrictions from PEConfig 520 + - AC7.7: PEConfig with None routes preserves full-mesh (backward compatibility) 521 + """ 522 + 523 + def test_ac76_restricted_topology_pe_routes(self): 524 + """AC7.6: build_topology restricts PE routes based on allowed_pe_routes.""" 525 + env = simpy.Environment() 526 + 527 + # Create 3 PEs but restrict PE 0 to only route to PE 1 528 + pe0_config = PEConfig(pe_id=0, iram={}, allowed_pe_routes={1}) 529 + pe1_config = PEConfig(pe_id=1, iram={}) 530 + pe2_config = PEConfig(pe_id=2, iram={}) 531 + 532 + sys = build_topology(env, [pe0_config, pe1_config, pe2_config], []) 533 + 534 + # PE 0 should only have PE 1 in its route_table 535 + pe0 = sys.pes[0] 536 + assert set(pe0.route_table.keys()) == {1} 537 + 538 + def test_ac76_restricted_topology_sm_routes(self): 539 + """AC7.6: build_topology restricts SM routes based on allowed_sm_routes.""" 540 + env = simpy.Environment() 541 + 542 + # Create PE 0 restricted to SM 0 only (not SM 1) 543 + pe0_config = PEConfig(pe_id=0, iram={}, allowed_sm_routes={0}) 544 + sm0_config = SMConfig(sm_id=0) 545 + sm1_config = SMConfig(sm_id=1) 546 + 547 + sys = build_topology(env, [pe0_config], [sm0_config, sm1_config]) 548 + 549 + # PE 0 should only have SM 0 in its sm_routes 550 + pe0 = sys.pes[0] 551 + assert set(pe0.sm_routes.keys()) == {0} 552 + 553 + def test_ac76_restricted_topology_both_pe_and_sm(self): 554 + """AC7.6: build_topology applies both PE and SM route restrictions.""" 555 + env = simpy.Environment() 556 + 557 + # Create PE 0 restricted to PE 1 and SM 0 only 558 + pe0_config = PEConfig( 559 + pe_id=0, 560 + iram={}, 561 + allowed_pe_routes={1}, 562 + allowed_sm_routes={0} 563 + ) 564 + pe1_config = PEConfig(pe_id=1, iram={}) 565 + pe2_config = PEConfig(pe_id=2, iram={}) 566 + sm0_config = SMConfig(sm_id=0) 567 + sm1_config = SMConfig(sm_id=1) 568 + 569 + sys = build_topology( 570 + env, 571 + [pe0_config, pe1_config, pe2_config], 572 + [sm0_config, sm1_config] 573 + ) 574 + 575 + # PE 0 should be restricted in both dimensions 576 + pe0 = sys.pes[0] 577 + assert set(pe0.route_table.keys()) == {1} 578 + assert set(pe0.sm_routes.keys()) == {0} 579 + 580 + # PE 1 and PE 2 should have full-mesh (no restrictions) 581 + pe1 = sys.pes[1] 582 + assert set(pe1.route_table.keys()) == {0, 1, 2} 583 + assert set(pe1.sm_routes.keys()) == {0, 1} 584 + 585 + pe2 = sys.pes[2] 586 + assert set(pe2.route_table.keys()) == {0, 1, 2} 587 + assert set(pe2.sm_routes.keys()) == {0, 1} 588 + 589 + def test_ac77_none_routes_preserves_full_mesh(self): 590 + """AC7.7: PEConfig with None routes preserves full-mesh topology (backward compat).""" 591 + env = simpy.Environment() 592 + 593 + # Create 3 PEs with no route restrictions (None) 594 + pe0_config = PEConfig(pe_id=0, iram={}) # allowed_pe_routes=None, allowed_sm_routes=None 595 + pe1_config = PEConfig(pe_id=1, iram={}) 596 + pe2_config = PEConfig(pe_id=2, iram={}) 597 + sm0_config = SMConfig(sm_id=0) 598 + sm1_config = SMConfig(sm_id=1) 599 + 600 + sys = build_topology( 601 + env, 602 + [pe0_config, pe1_config, pe2_config], 603 + [sm0_config, sm1_config] 604 + ) 605 + 606 + # All PEs should have full-mesh routes 607 + for pe_id in [0, 1, 2]: 608 + pe = sys.pes[pe_id] 609 + assert set(pe.route_table.keys()) == {0, 1, 2} 610 + assert set(pe.sm_routes.keys()) == {0, 1} 611 + 612 + def test_ac77_existing_tests_still_pass(self): 613 + """AC7.7: Existing test scenarios still work with full-mesh (regression test).""" 614 + env = simpy.Environment() 615 + 616 + # This is the basic test from test_integration.py: CONST feeds ADD 617 + pe0_iram = { 618 + 0: ALUInst( 619 + op=RoutingOp.CONST, 620 + dest_l=Addr(a=0, port=Port.L, pe=1), 621 + dest_r=None, 622 + const=7, 623 + ), 624 + 1: ALUInst( 625 + op=RoutingOp.CONST, 626 + dest_l=Addr(a=0, port=Port.R, pe=1), 627 + dest_r=None, 628 + const=3, 629 + ), 630 + } 631 + 632 + pe1_iram = { 633 + 0: ALUInst( 634 + op=ArithOp.ADD, 635 + dest_l=Addr(a=0, port=Port.L, pe=2), 636 + dest_r=None, 637 + const=None, 638 + ), 639 + } 640 + 641 + sys = build_topology( 642 + env, 643 + [ 644 + PEConfig(pe_id=0, iram=pe0_iram), 645 + PEConfig(pe_id=1, iram=pe1_iram), 646 + PEConfig(pe_id=2, iram={}), 647 + ], 648 + [], 649 + ) 650 + 651 + # All PEs should have full-mesh routes 652 + for pe_id in [0, 1, 2]: 653 + pe = sys.pes[pe_id] 654 + assert set(pe.route_table.keys()) == {0, 1, 2} 655 + 656 + # Collector to verify routing works 657 + collector_store = simpy.Store(env, capacity=100) 658 + sys.pes[1].route_table[2] = collector_store 659 + 660 + # Inject tokens 661 + def injector(): 662 + yield sys.pes[0].input_store.put(MonadToken(target=0, offset=0, ctx=0, data=0, inline=False)) 663 + yield sys.pes[0].input_store.put(MonadToken(target=0, offset=1, ctx=0, data=0, inline=False)) 664 + 665 + env.process(injector()) 666 + env.run() 667 + 668 + # Verify result: 7 + 3 = 10 routed to collector 669 + assert len(collector_store.items) > 0 670 + result = collector_store.items[0] 671 + assert result.data == 10 672 + 673 + 674 + class TestSystemInjectTokenAPI: 675 + """Test System.inject() unified API.""" 676 + 677 + def test_inject_token_monad(self): 678 + """System.inject() can inject MonadToken and PE executes it.""" 679 + env = simpy.Environment() 680 + 681 + # PE0 with PASS instruction routing to PE1 682 + pe0_iram = { 683 + 0: ALUInst( 684 + op=RoutingOp.PASS, 685 + dest_l=Addr(a=0, port=Port.L, pe=1), 686 + dest_r=None, 687 + const=None, 688 + ) 689 + } 690 + 691 + sys = build_topology(env, [PEConfig(0, pe0_iram), PEConfig(1, {})], []) 692 + 693 + # Inject MonadToken via unified API 694 + token = MonadToken(target=0, offset=0, ctx=0, data=0xABCD, inline=False) 695 + sys.inject(token) 696 + 697 + env.run() 698 + 699 + # PE0 should have executed PASS and emitted the token 700 + assert len(sys.pes[0].output_log) >= 1 701 + emitted = [t for t in sys.pes[0].output_log if hasattr(t, 'data') and t.data == 0xABCD] 702 + assert len(emitted) == 1 703 + 704 + def test_inject_token_dyad(self): 705 + """System.inject() can inject DyadToken.""" 706 + env = simpy.Environment() 707 + 708 + # PE0 with ADD instruction 709 + pe0_iram = { 710 + 0: ALUInst( 711 + op=ArithOp.ADD, 712 + dest_l=Addr(a=0, port=Port.L, pe=1), 713 + dest_r=None, 714 + const=None, 715 + ) 716 + } 717 + 718 + sys = build_topology(env, [PEConfig(0, pe0_iram), PEConfig(1, {})], []) 719 + 720 + # Set up output stores 721 + output_store = simpy.Store(env, capacity=10) 722 + sys.pes[0].route_table[1] = output_store 723 + 724 + # Create and inject first DyadToken 725 + token1 = DyadToken(target=0, offset=0, ctx=0, data=10, port=Port.L, gen=0, wide=False) 726 + sys.inject(token1) 727 + 728 + # Create and inject second DyadToken to fire the instruction 729 + token2 = DyadToken(target=0, offset=0, ctx=0, data=20, port=Port.R, gen=0, wide=False) 730 + sys.inject(token2) 731 + 732 + env.run() 733 + 734 + # Verify ADD result (10 + 20 = 30) 735 + assert len(output_store.items) == 1 736 + assert output_store.items[0].data == 30

+332

tests/test_opcodes.py

··· 1 + """Tests for asm.opcodes module — mnemonic mapping and arity classification.""" 2 + 3 + import pytest 4 + from cm_inst import ArithOp, LogicOp, RoutingOp 5 + from tokens import MemOp, CfgOp 6 + from asm.opcodes import ( 7 + MNEMONIC_TO_OP, 8 + OP_TO_MNEMONIC, 9 + MONADIC_OPS, 10 + is_monadic, 11 + is_dyadic, 12 + ) 13 + 14 + 15 + class TestMnemonicToOpMapping: 16 + """Verify all ALU opcodes map to correct enum values.""" 17 + 18 + def test_arithmetic_opcodes(self): 19 + """or1-asm.AC1.1: Arithmetic opcodes map correctly.""" 20 + assert MNEMONIC_TO_OP["add"] == ArithOp.ADD 21 + assert MNEMONIC_TO_OP["sub"] == ArithOp.SUB 22 + assert MNEMONIC_TO_OP["inc"] == ArithOp.INC 23 + assert MNEMONIC_TO_OP["dec"] == ArithOp.DEC 24 + assert MNEMONIC_TO_OP["shiftl"] == ArithOp.SHIFT_L 25 + assert MNEMONIC_TO_OP["shiftr"] == ArithOp.SHIFT_R 26 + assert MNEMONIC_TO_OP["ashiftr"] == ArithOp.ASHFT_R 27 + 28 + def test_logic_opcodes(self): 29 + """or1-asm.AC1.1: Logic opcodes map correctly.""" 30 + assert MNEMONIC_TO_OP["and"] == LogicOp.AND 31 + assert MNEMONIC_TO_OP["or"] == LogicOp.OR 32 + assert MNEMONIC_TO_OP["xor"] == LogicOp.XOR 33 + assert MNEMONIC_TO_OP["not"] == LogicOp.NOT 34 + assert MNEMONIC_TO_OP["eq"] == LogicOp.EQ 35 + assert MNEMONIC_TO_OP["lt"] == LogicOp.LT 36 + assert MNEMONIC_TO_OP["lte"] == LogicOp.LTE 37 + assert MNEMONIC_TO_OP["gt"] == LogicOp.GT 38 + assert MNEMONIC_TO_OP["gte"] == LogicOp.GTE 39 + 40 + def test_branch_opcodes(self): 41 + """or1-asm.AC1.1: Branch opcodes map correctly.""" 42 + assert MNEMONIC_TO_OP["breq"] == RoutingOp.BREQ 43 + assert MNEMONIC_TO_OP["brgt"] == RoutingOp.BRGT 44 + assert MNEMONIC_TO_OP["brge"] == RoutingOp.BRGE 45 + assert MNEMONIC_TO_OP["brof"] == RoutingOp.BROF 46 + 47 + def test_switch_opcodes(self): 48 + """or1-asm.AC1.1: Switch opcodes map correctly.""" 49 + assert MNEMONIC_TO_OP["sweq"] == RoutingOp.SWEQ 50 + assert MNEMONIC_TO_OP["swgt"] == RoutingOp.SWGT 51 + assert MNEMONIC_TO_OP["swge"] == RoutingOp.SWGE 52 + assert MNEMONIC_TO_OP["swof"] == RoutingOp.SWOF 53 + 54 + def test_control_opcodes(self): 55 + """or1-asm.AC1.1: Control/routing opcodes map correctly.""" 56 + assert MNEMONIC_TO_OP["gate"] == RoutingOp.GATE 57 + assert MNEMONIC_TO_OP["sel"] == RoutingOp.SEL 58 + assert MNEMONIC_TO_OP["merge"] == RoutingOp.MRGE 59 + assert MNEMONIC_TO_OP["pass"] == RoutingOp.PASS 60 + assert MNEMONIC_TO_OP["const"] == RoutingOp.CONST 61 + assert MNEMONIC_TO_OP["free"] == RoutingOp.FREE 62 + 63 + def test_memory_opcodes(self): 64 + """or1-asm.AC1.2: Memory opcodes map correctly.""" 65 + assert MNEMONIC_TO_OP["read"] == MemOp.READ 66 + assert MNEMONIC_TO_OP["write"] == MemOp.WRITE 67 + assert MNEMONIC_TO_OP["clear"] == MemOp.CLEAR 68 + assert MNEMONIC_TO_OP["alloc"] == MemOp.ALLOC 69 + assert MNEMONIC_TO_OP["free_sm"] == MemOp.FREE 70 + assert MNEMONIC_TO_OP["rd_inc"] == MemOp.RD_INC 71 + assert MNEMONIC_TO_OP["rd_dec"] == MemOp.RD_DEC 72 + assert MNEMONIC_TO_OP["cmp_sw"] == MemOp.CMP_SW 73 + 74 + def test_configuration_opcodes(self): 75 + """or1-asm.AC1.3: Configuration opcodes map correctly.""" 76 + assert MNEMONIC_TO_OP["load_inst"] == CfgOp.LOAD_INST 77 + assert MNEMONIC_TO_OP["route_set"] == CfgOp.ROUTE_SET 78 + 79 + def test_mnemonic_to_op_count(self): 80 + """Verify all expected mnemonics are present.""" 81 + # Total: 7 arithmetic + 9 logic + 4 branch + 4 switch + 6 control + 8 memory + 2 config = 40 82 + expected_count = 40 83 + assert len(MNEMONIC_TO_OP) == expected_count 84 + 85 + 86 + class TestOpcodeRoundTrip: 87 + """Verify round-trip mapping: mnemonic -> op -> mnemonic.""" 88 + 89 + @pytest.mark.parametrize( 90 + "mnemonic", 91 + [ 92 + # Arithmetic 93 + "add", "sub", "inc", "dec", "shiftl", "shiftr", "ashiftr", 94 + # Logic 95 + "and", "or", "xor", "not", "eq", "lt", "lte", "gt", "gte", 96 + # Branch 97 + "breq", "brgt", "brge", "brof", 98 + # Switch 99 + "sweq", "swgt", "swge", "swof", 100 + # Control 101 + "gate", "sel", "merge", "pass", "const", "free", 102 + # Memory 103 + "read", "write", "clear", "alloc", "free_sm", "rd_inc", "rd_dec", "cmp_sw", 104 + # Configuration 105 + "load_inst", "route_set", 106 + ] 107 + ) 108 + def test_round_trip(self, mnemonic): 109 + """Every mnemonic should round-trip through the mapping.""" 110 + op = MNEMONIC_TO_OP[mnemonic] 111 + recovered_mnemonic = OP_TO_MNEMONIC[op] 112 + assert recovered_mnemonic == mnemonic 113 + 114 + @pytest.mark.parametrize( 115 + "mnemonic", 116 + [ 117 + # Arithmetic 118 + "add", "sub", "inc", "dec", "shiftl", "shiftr", "ashiftr", 119 + # Logic 120 + "and", "or", "xor", "not", "eq", "lt", "lte", "gt", "gte", 121 + # Branch 122 + "breq", "brgt", "brge", "brof", 123 + # Switch 124 + "sweq", "swgt", "swge", "swof", 125 + # Control 126 + "gate", "sel", "merge", "pass", "const", "free", 127 + # Memory 128 + "read", "write", "clear", "alloc", "free_sm", "rd_inc", "rd_dec", "cmp_sw", 129 + # Configuration 130 + "load_inst", "route_set", 131 + ] 132 + ) 133 + def test_round_trip_via_dict(self, mnemonic): 134 + """Every mnemonic should round-trip via OP_TO_MNEMONIC dict directly. 135 + 136 + This test verifies the dict is collision-free. For example: 137 + - OP_TO_MNEMONIC[ArithOp.ADD] must return 'add' (not 'read') 138 + - OP_TO_MNEMONIC[MemOp.READ] must return 'read' (not overwritten) 139 + """ 140 + op = MNEMONIC_TO_OP[mnemonic] 141 + recovered_mnemonic = OP_TO_MNEMONIC[op] 142 + assert recovered_mnemonic == mnemonic 143 + 144 + 145 + class TestMonadicOpsSet: 146 + """Verify MONADIC_OPS contains exactly the right opcodes.""" 147 + 148 + def test_monadic_ops_size(self): 149 + """MONADIC_OPS should have exactly 15 opcodes (collision-free). 150 + 151 + Without collision-free implementation, this would be 12 due to IntEnum 152 + collisions (e.g., ArithOp.INC colliding with some MemOp value). 153 + """ 154 + assert len(MONADIC_OPS) == 15 155 + 156 + def test_monadic_opcodes_present(self): 157 + """All known monadic opcodes should be in the set.""" 158 + monadic_list = [ 159 + # Arithmetic (single input + const) 160 + ArithOp.INC, ArithOp.DEC, 161 + ArithOp.SHIFT_L, ArithOp.SHIFT_R, ArithOp.ASHFT_R, 162 + # Logic 163 + LogicOp.NOT, 164 + # Routing 165 + RoutingOp.PASS, RoutingOp.CONST, RoutingOp.FREE, 166 + # Memory 167 + MemOp.READ, MemOp.ALLOC, MemOp.FREE, MemOp.CLEAR, 168 + MemOp.RD_INC, MemOp.RD_DEC, 169 + ] 170 + for op in monadic_list: 171 + assert op in MONADIC_OPS, f"{op} should be in MONADIC_OPS" 172 + assert is_monadic(op), f"{op} should be monadic" 173 + 174 + def test_collision_free_membership(self): 175 + """MONADIC_OPS membership must be collision-free. 176 + 177 + Due to IntEnum cross-type equality, ArithOp.ADD (0) equals MemOp.READ (0). 178 + Without collision-free implementation, ArithOp.ADD in MONADIC_OPS would 179 + return True because MemOp.READ is in the set. 180 + """ 181 + # ArithOp.ADD and MemOp.READ have the same value (0) so they're equal 182 + assert ArithOp.ADD == MemOp.READ 183 + # But only MemOp.READ should be in MONADIC_OPS, not ArithOp.ADD 184 + assert MemOp.READ in MONADIC_OPS 185 + assert ArithOp.ADD not in MONADIC_OPS 186 + 187 + def test_context_dependent_not_in_monadic(self): 188 + """WRITE should not be in MONADIC_OPS (context-dependent).""" 189 + assert not is_monadic(MemOp.WRITE, const=None) 190 + 191 + def test_always_dyadic_not_in_monadic(self): 192 + """CMP_SW should not be in MONADIC_OPS (always dyadic).""" 193 + assert not is_monadic(MemOp.CMP_SW) 194 + 195 + def test_dyadic_opcodes_not_in_monadic(self): 196 + """All known dyadic opcodes should be dyadic.""" 197 + dyadic_list = [ 198 + # Arithmetic (two inputs) 199 + ArithOp.ADD, ArithOp.SUB, 200 + # Logic (two inputs) 201 + LogicOp.AND, LogicOp.OR, LogicOp.XOR, 202 + LogicOp.EQ, LogicOp.LT, LogicOp.LTE, LogicOp.GT, LogicOp.GTE, 203 + # Branch/switch (two inputs + dest) 204 + RoutingOp.BREQ, RoutingOp.BRGT, RoutingOp.BRGE, RoutingOp.BROF, 205 + RoutingOp.SWEQ, RoutingOp.SWGT, RoutingOp.SWGE, RoutingOp.SWOF, 206 + RoutingOp.GATE, RoutingOp.SEL, RoutingOp.MRGE, 207 + # Memory 208 + MemOp.WRITE, # Usually dyadic 209 + MemOp.CMP_SW, # Always dyadic 210 + ] 211 + for op in dyadic_list: 212 + assert is_dyadic(op), f"{op} should be dyadic" 213 + 214 + 215 + class TestIsMonadicFunction: 216 + """Verify is_monadic() function works correctly.""" 217 + 218 + @pytest.mark.parametrize( 219 + "op", 220 + [ 221 + ArithOp.INC, ArithOp.DEC, 222 + ArithOp.SHIFT_L, ArithOp.SHIFT_R, ArithOp.ASHFT_R, 223 + LogicOp.NOT, 224 + RoutingOp.PASS, RoutingOp.CONST, RoutingOp.FREE, 225 + MemOp.READ, MemOp.ALLOC, MemOp.FREE, MemOp.CLEAR, 226 + MemOp.RD_INC, MemOp.RD_DEC, 227 + CfgOp.LOAD_INST, CfgOp.ROUTE_SET, 228 + ] 229 + ) 230 + def test_always_monadic_opcodes(self, op): 231 + """Always-monadic opcodes should return True regardless of const.""" 232 + assert is_monadic(op) is True 233 + assert is_monadic(op, const=None) is True 234 + assert is_monadic(op, const=42) is True 235 + 236 + def test_write_monadic_with_const(self): 237 + """WRITE with const should be monadic.""" 238 + assert is_monadic(MemOp.WRITE, const=42) is True 239 + 240 + def test_write_dyadic_without_const(self): 241 + """WRITE without const should be dyadic.""" 242 + assert is_monadic(MemOp.WRITE, const=None) is False 243 + assert is_monadic(MemOp.WRITE) is False 244 + 245 + def test_cmp_sw_always_dyadic(self): 246 + """CMP_SW should always be dyadic.""" 247 + assert is_monadic(MemOp.CMP_SW) is False 248 + assert is_monadic(MemOp.CMP_SW, const=None) is False 249 + assert is_monadic(MemOp.CMP_SW, const=42) is False 250 + 251 + @pytest.mark.parametrize( 252 + "op", 253 + [ 254 + ArithOp.ADD, ArithOp.SUB, 255 + LogicOp.AND, LogicOp.OR, LogicOp.XOR, 256 + LogicOp.EQ, LogicOp.LT, LogicOp.LTE, LogicOp.GT, LogicOp.GTE, 257 + RoutingOp.BREQ, RoutingOp.BRGT, RoutingOp.BRGE, RoutingOp.BROF, 258 + RoutingOp.SWEQ, RoutingOp.SWGT, RoutingOp.SWGE, RoutingOp.SWOF, 259 + RoutingOp.GATE, RoutingOp.SEL, RoutingOp.MRGE, 260 + ] 261 + ) 262 + def test_dyadic_opcodes(self, op): 263 + """Dyadic opcodes should return False.""" 264 + assert is_monadic(op) is False 265 + 266 + 267 + class TestIsDyadicFunction: 268 + """Verify is_dyadic() function is the inverse of is_monadic().""" 269 + 270 + @pytest.mark.parametrize( 271 + "op", 272 + [ 273 + ArithOp.INC, ArithOp.DEC, 274 + ArithOp.SHIFT_L, ArithOp.SHIFT_R, ArithOp.ASHFT_R, 275 + LogicOp.NOT, 276 + RoutingOp.PASS, RoutingOp.CONST, RoutingOp.FREE, 277 + MemOp.READ, MemOp.ALLOC, MemOp.FREE, MemOp.CLEAR, 278 + MemOp.RD_INC, MemOp.RD_DEC, 279 + CfgOp.LOAD_INST, CfgOp.ROUTE_SET, 280 + ] 281 + ) 282 + def test_always_monadic_is_not_dyadic(self, op): 283 + """Always-monadic should be not dyadic.""" 284 + assert is_dyadic(op) is False 285 + 286 + def test_write_context_dependent(self): 287 + """WRITE arity is context-dependent via const.""" 288 + assert is_dyadic(MemOp.WRITE, const=42) is False # monadic 289 + assert is_dyadic(MemOp.WRITE, const=None) is True # dyadic 290 + 291 + def test_cmp_sw_always_dyadic(self): 292 + """CMP_SW is always dyadic.""" 293 + assert is_dyadic(MemOp.CMP_SW) is True 294 + assert is_dyadic(MemOp.CMP_SW, const=42) is True 295 + 296 + @pytest.mark.parametrize( 297 + "op", 298 + [ 299 + ArithOp.ADD, ArithOp.SUB, 300 + LogicOp.AND, LogicOp.OR, LogicOp.XOR, 301 + LogicOp.EQ, LogicOp.LT, LogicOp.LTE, LogicOp.GT, LogicOp.GTE, 302 + RoutingOp.BREQ, RoutingOp.BRGT, RoutingOp.BRGE, RoutingOp.BROF, 303 + RoutingOp.SWEQ, RoutingOp.SWGT, RoutingOp.SWGE, RoutingOp.SWOF, 304 + RoutingOp.GATE, RoutingOp.SEL, RoutingOp.MRGE, 305 + ] 306 + ) 307 + def test_dyadic_opcodes_is_dyadic(self, op): 308 + """Dyadic opcodes should be dyadic.""" 309 + assert is_dyadic(op) is True 310 + 311 + 312 + class TestFreeDisambiguation: 313 + """Verify free (ALU) and free_sm (SM) are distinct and round-trip correctly.""" 314 + 315 + def test_free_is_routing_op(self): 316 + """The free mnemonic should map to ALU RoutingOp.FREE.""" 317 + assert MNEMONIC_TO_OP["free"] == RoutingOp.FREE 318 + 319 + def test_free_sm_is_memop(self): 320 + """The free_sm mnemonic should map to SM MemOp.FREE.""" 321 + assert MNEMONIC_TO_OP["free_sm"] == MemOp.FREE 322 + 323 + def test_both_free_round_trip(self): 324 + """Both free and free_sm should round-trip correctly.""" 325 + # free -> RoutingOp.FREE -> free 326 + assert OP_TO_MNEMONIC[RoutingOp.FREE] == "free" 327 + assert OP_TO_MNEMONIC[MemOp.FREE] == "free_sm" 328 + 329 + def test_no_collision(self): 330 + """Distinct enum types should not collide in reverse mapping.""" 331 + # RoutingOp.FREE and MemOp.FREE are different enum values 332 + assert RoutingOp.FREE != MemOp.FREE

+179 -31

tests/test_parser.py

··· 3 3 from textwrap import dedent 4 4 5 5 import pytest 6 - from lark import Lark 7 - from pathlib import Path 8 - 9 - GRAMMAR_PATH = Path(__file__).parent.parent / "dfasm.lark" 10 - 11 - 12 - @pytest.fixture(scope="module") 13 - def parser(): 14 - return Lark( 15 - GRAMMAR_PATH.read_text(), 16 - parser="earley", 17 - propagate_positions=True, 18 - ) 6 + from lark import exceptions, LarkError 19 7 20 8 21 9 class TestInstDefs: 22 10 def test_basic_instructions(self, parser): 23 - parser.parse(dedent("""\ 11 + tree = parser.parse(dedent("""\ 24 12 &my_add <| add 25 13 &my_sub <| sub 26 14 &my_const <| const, 10 27 15 &my_shift <| shiftl 28 16 &my_not <| not 29 17 """)) 18 + assert tree.data == "start" 19 + assert len(tree.children) == 5 20 + assert all(child.data == "inst_def" for child in tree.children) 30 21 31 22 def test_hex_const(self, parser): 32 - parser.parse(dedent("""\ 23 + tree = parser.parse(dedent("""\ 33 24 &mask <| const, 0xFF 34 25 """)) 26 + assert tree.data == "start" 27 + assert len(tree.children) == 1 28 + assert tree.children[0].data == "inst_def" 35 29 36 30 def test_named_args(self, parser): 37 - parser.parse(dedent("""\ 31 + tree = parser.parse(dedent("""\ 38 32 &serial <| ior, dest=0x45, addr=0x91, data=0x43 39 33 """)) 34 + assert tree.data == "start" 35 + assert len(tree.children) == 1 36 + assert tree.children[0].data == "inst_def" 40 37 41 38 def test_system_config(self, parser): 42 - parser.parse(dedent("""\ 39 + tree = parser.parse(dedent("""\ 43 40 &loader <| load_inst, dest=0x01, addr=0x00, data_l=0xABCD, data_h=0x1234 44 41 """)) 42 + assert tree.data == "start" 43 + assert len(tree.children) == 1 44 + assert tree.children[0].data == "inst_def" 45 45 46 46 47 47 class TestEdges: 48 48 def test_plain_edges(self, parser): 49 - parser.parse(dedent("""\ 49 + tree = parser.parse(dedent("""\ 50 50 &a |> &b:L 51 51 &a |> &b:R 52 52 &c |> &d, &e 53 53 """)) 54 + assert tree.data == "start" 55 + assert len(tree.children) == 3 56 + assert all(child.data == "plain_edge" for child in tree.children) 54 57 55 58 def test_strong_inline_edge(self, parser): 56 - parser.parse(dedent("""\ 59 + tree = parser.parse(dedent("""\ 57 60 add &a, &b |> &c, &d 58 61 """)) 62 + assert tree.data == "start" 63 + assert len(tree.children) == 1 64 + assert tree.children[0].data == "strong_edge" 59 65 60 66 def test_weak_inline_edge(self, parser): 61 - parser.parse(dedent("""\ 67 + tree = parser.parse(dedent("""\ 62 68 &c, &d sub <| &a, &b 63 69 """)) 70 + assert tree.data == "start" 71 + assert len(tree.children) == 1 72 + assert tree.children[0].data == "weak_edge" 64 73 65 74 def test_fanout(self, parser): 66 - parser.parse(dedent("""\ 75 + tree = parser.parse(dedent("""\ 67 76 &splitter <| pass 68 77 &input |> &splitter:L 69 78 &splitter |> &consumer_a:L, &consumer_b:R 70 79 """)) 80 + assert tree.data == "start" 81 + assert len(tree.children) == 3 82 + assert tree.children[0].data == "inst_def" 83 + assert tree.children[1].data == "plain_edge" 84 + assert tree.children[2].data == "plain_edge" 71 85 72 86 73 87 class TestFunctions: 74 88 def test_fib_function(self, parser): 75 - parser.parse(dedent("""\ 89 + tree = parser.parse(dedent("""\ 76 90 $fib |> { 77 91 &const_n <| const, 10 78 92 &sub1 <| sub ··· 86 100 &sub1 |> &recurse_a:L 87 101 } 88 102 """)) 103 + assert tree.data == "start" 104 + assert len(tree.children) == 1 105 + assert tree.children[0].data == "func_def" 89 106 90 107 91 108 class TestPlacement: 92 109 def test_pe_qualifiers(self, parser): 93 - parser.parse(dedent("""\ 110 + tree = parser.parse(dedent("""\ 94 111 &my_add|pe0 <| add 95 112 &result|pe1 <| pass 96 113 &my_add|pe0 |> &result|pe1:L 97 114 """)) 115 + assert tree.data == "start" 116 + assert len(tree.children) == 3 117 + assert tree.children[0].data == "inst_def" 118 + assert tree.children[1].data == "inst_def" 119 + assert tree.children[2].data == "plain_edge" 98 120 99 121 def test_location_directive(self, parser): 100 - parser.parse(dedent("""\ 122 + tree = parser.parse(dedent("""\ 101 123 @data_section|sm0 102 124 """)) 125 + assert tree.data == "start" 126 + assert len(tree.children) == 1 127 + assert tree.children[0].data == "location_dir" 103 128 104 129 105 130 class TestDataDefs: 106 131 def test_hex_data(self, parser): 107 - parser.parse(dedent("""\ 132 + tree = parser.parse(dedent("""\ 108 133 @hello|sm0:0 = 0x05 109 134 @hello|sm0:1 = 'h', 'e' 110 135 @hello|sm0:2 = 'l', 'l' 111 136 """)) 137 + assert tree.data == "start" 138 + assert len(tree.children) == 3 139 + assert all(child.data == "data_def" for child in tree.children) 112 140 113 141 def test_macro_invocation(self, parser): 114 - parser.parse(dedent("""\ 142 + tree = parser.parse(dedent("""\ 115 143 @hello = #str "hello" 116 144 """)) 145 + assert tree.data == "start" 146 + assert len(tree.children) == 1 147 + assert tree.children[0].data == "data_def" 117 148 118 149 def test_multi_line_string(self, parser): 119 - parser.parse(dedent('''\ 150 + tree = parser.parse(dedent('''\ 120 151 @msg = "hello 121 152 world" 122 153 ''')) 154 + assert tree.data == "start" 155 + assert len(tree.children) == 1 156 + assert tree.children[0].data == "data_def" 123 157 124 158 def test_raw_string(self, parser): 125 - parser.parse(dedent("""\ 159 + tree = parser.parse(dedent("""\ 126 160 @path = r"no\\escapes\\here" 127 161 """)) 162 + assert tree.data == "start" 163 + assert len(tree.children) == 1 164 + assert tree.children[0].data == "data_def" 128 165 129 166 def test_byte_string(self, parser): 130 - parser.parse(dedent("""\ 167 + tree = parser.parse(dedent("""\ 131 168 @raw_data = b"\\x01\\x02\\x03" 132 169 """)) 170 + assert tree.data == "start" 171 + assert len(tree.children) == 1 172 + assert tree.children[0].data == "data_def" 133 173 134 174 135 175 class TestComments: 136 176 def test_inline_comments(self, parser): 137 - parser.parse(dedent("""\ 177 + tree = parser.parse(dedent("""\ 138 178 &my_add <| add ; this is a comment 139 179 &a |> &b:L ; wire a to b left port 140 180 """)) 181 + assert tree.data == "start" 182 + assert len(tree.children) == 2 183 + assert tree.children[0].data == "inst_def" 184 + assert tree.children[1].data == "plain_edge" 141 185 142 186 143 187 class TestMixedPrograms: 144 188 def test_mixed_program(self, parser): 145 - parser.parse(dedent("""\ 189 + tree = parser.parse(dedent("""\ 146 190 @counter|sm0:0 = 0x00 147 191 148 192 $main |> { ··· 157 201 &loop_add |> &output:L 158 202 } 159 203 """)) 204 + assert tree.data == "start" 205 + assert len(tree.children) == 2 206 + assert tree.children[0].data == "data_def" 207 + assert tree.children[1].data == "func_def" 208 + 209 + 210 + class TestSMOps: 211 + def test_read_op(self, parser): 212 + tree = parser.parse(dedent("""\ 213 + &cell <| read 214 + """)) 215 + assert tree.data == "start" 216 + assert len(tree.children) == 1 217 + assert tree.children[0].data == "inst_def" 218 + 219 + def test_write_op(self, parser): 220 + tree = parser.parse(dedent("""\ 221 + &cell <| write 222 + """)) 223 + assert tree.data == "start" 224 + assert len(tree.children) == 1 225 + assert tree.children[0].data == "inst_def" 226 + 227 + def test_clear_op(self, parser): 228 + tree = parser.parse(dedent("""\ 229 + &cell <| clear 230 + """)) 231 + assert tree.data == "start" 232 + assert len(tree.children) == 1 233 + assert tree.children[0].data == "inst_def" 234 + 235 + def test_alloc_op(self, parser): 236 + tree = parser.parse(dedent("""\ 237 + &cell <| alloc 238 + """)) 239 + assert tree.data == "start" 240 + assert len(tree.children) == 1 241 + assert tree.children[0].data == "inst_def" 242 + 243 + def test_free_sm_op(self, parser): 244 + tree = parser.parse(dedent("""\ 245 + &cell <| free_sm 246 + """)) 247 + assert tree.data == "start" 248 + assert len(tree.children) == 1 249 + assert tree.children[0].data == "inst_def" 250 + 251 + def test_rd_inc_op(self, parser): 252 + tree = parser.parse(dedent("""\ 253 + &cell <| rd_inc 254 + """)) 255 + assert tree.data == "start" 256 + assert len(tree.children) == 1 257 + assert tree.children[0].data == "inst_def" 258 + 259 + def test_rd_dec_op(self, parser): 260 + tree = parser.parse(dedent("""\ 261 + &cell <| rd_dec 262 + """)) 263 + assert tree.data == "start" 264 + assert len(tree.children) == 1 265 + assert tree.children[0].data == "inst_def" 266 + 267 + def test_cmp_sw_op(self, parser): 268 + tree = parser.parse(dedent("""\ 269 + &cell <| cmp_sw 270 + """)) 271 + assert tree.data == "start" 272 + assert len(tree.children) == 1 273 + assert tree.children[0].data == "inst_def" 274 + 275 + 276 + class TestSystemPragma: 277 + def test_system_pragma_minimal(self, parser): 278 + tree = parser.parse(dedent("""\ 279 + @system pe=4, sm=1 280 + """)) 281 + assert tree.data == "start" 282 + assert len(tree.children) == 1 283 + assert tree.children[0].data == "system_pragma" 284 + 285 + def test_system_pragma_full(self, parser): 286 + tree = parser.parse(dedent("""\ 287 + @system pe=2, sm=1, iram=128, ctx=2 288 + """)) 289 + assert tree.data == "start" 290 + assert len(tree.children) == 1 291 + assert tree.children[0].data == "system_pragma" 292 + 293 + def test_system_pragma_with_hex(self, parser): 294 + tree = parser.parse(dedent("""\ 295 + @system pe=0x04, sm=0x01 296 + """)) 297 + assert tree.data == "start" 298 + assert len(tree.children) == 1 299 + assert tree.children[0].data == "system_pragma" 300 + 301 + 302 + class TestUnknownOpcodes: 303 + def test_unknown_opcode_fails(self, parser): 304 + with pytest.raises((exceptions.UnexpectedToken, exceptions.UnexpectedCharacters)): 305 + parser.parse(dedent("""\ 306 + &unknown <| foobar 307 + """))

+510 -1

tests/test_pe.py

··· 13 13 - AC1.9: Non-existent offset doesn't crash 14 14 """ 15 15 16 + import pytest 16 17 import simpy 17 18 from hypothesis import given 18 19 19 - from cm_inst import Addr, ALUInst, RoutingOp, ArithOp 20 + from cm_inst import Addr, ALUInst, RoutingOp, ArithOp, SMInst, MemOp 20 21 from emu.pe import ProcessingElement 21 22 from tests.conftest import dyad_token 22 23 from tokens import DyadToken, MonadToken, Port ··· 454 455 455 456 # No output (instruction doesn't exist) 456 457 assert len(output_store.items) == 0 458 + 459 + 460 + class TestRouteSet: 461 + """Test ROUTE_SET CfgToken handler (AC7.1–AC7.5). 462 + 463 + Verifies: 464 + - AC7.1: ROUTE_SET CfgToken accepted without warning 465 + - AC7.2: PE can route to allowed PE IDs 466 + - AC7.3: PE can route to allowed SM IDs 467 + - AC7.4: Routing to unlisted PE ID raises KeyError 468 + - AC7.5: Routing to unlisted SM ID raises KeyError 469 + """ 470 + 471 + def test_ac71_route_set_accepted_no_warning(self): 472 + """AC7.1: ROUTE_SET CfgToken accepted without warning.""" 473 + from tokens import CfgOp, RouteSetToken 474 + 475 + env = simpy.Environment() 476 + pe = ProcessingElement(env, 0, {}) 477 + 478 + # Set up full-mesh routes (3 PEs, 1 SM) 479 + pe_store_0 = simpy.Store(env) 480 + pe_store_1 = simpy.Store(env) 481 + pe_store_2 = simpy.Store(env) 482 + sm_store_0 = simpy.Store(env) 483 + 484 + pe.route_table[0] = pe_store_0 485 + pe.route_table[1] = pe_store_1 486 + pe.route_table[2] = pe_store_2 487 + pe.sm_routes[0] = sm_store_0 488 + 489 + # Create ROUTE_SET: allow PE 0 and PE 2, allow SM 0 490 + route_set_token = RouteSetToken( 491 + target=0, 492 + addr=None, 493 + op=CfgOp.ROUTE_SET, 494 + pe_routes=(0, 2), 495 + sm_routes=(0,), 496 + ) 497 + 498 + # Call _handle_cfg 499 + pe._handle_cfg(route_set_token) 500 + 501 + # No exception, no warning (check with logging) 502 + assert len(pe.route_table) == 2 503 + assert 0 in pe.route_table 504 + assert 2 in pe.route_table 505 + assert len(pe.sm_routes) == 1 506 + assert 0 in pe.sm_routes 507 + 508 + def test_ac72_route_to_allowed_pe_succeeds(self): 509 + """AC7.2: After ROUTE_SET, PE can route to allowed PE ID.""" 510 + from tokens import CfgOp, RouteSetToken 511 + 512 + env = simpy.Environment() 513 + 514 + # PE 0 with PASS instruction 515 + iram = { 516 + 0: ALUInst( 517 + op=RoutingOp.PASS, 518 + dest_l=Addr(a=0, port=Port.L, pe=0), 519 + dest_r=None, 520 + const=None, 521 + ) 522 + } 523 + pe = ProcessingElement(env, 0, iram) 524 + 525 + # Full-mesh route_table 526 + pe_store_0 = simpy.Store(env) 527 + pe_store_1 = simpy.Store(env) 528 + pe_store_2 = simpy.Store(env) 529 + pe.route_table[0] = pe_store_0 530 + pe.route_table[1] = pe_store_1 531 + pe.route_table[2] = pe_store_2 532 + 533 + # ROUTE_SET: allow PE 0 and PE 2 534 + route_set_token = RouteSetToken( 535 + target=0, 536 + addr=None, 537 + op=CfgOp.ROUTE_SET, 538 + pe_routes=(0, 2), 539 + sm_routes=(), 540 + ) 541 + pe._handle_cfg(route_set_token) 542 + 543 + # Inject token and route to PE 0 (allowed) 544 + token = MonadToken(target=0, offset=0, ctx=0, data=42, inline=False) 545 + 546 + def inject(): 547 + yield pe.input_store.put(route_set_token) # Apply restriction first 548 + yield env.timeout(10) 549 + yield pe.input_store.put(token) 550 + 551 + env.process(inject()) 552 + env.run(until=200) 553 + 554 + # Token should have been routed to PE 0 with correct data and target 555 + assert len(pe_store_0.items) > 0 556 + routed_token = pe_store_0.items[0] 557 + assert isinstance(routed_token, DyadToken) 558 + assert routed_token.data == 42 # Token data preserved 559 + assert routed_token.target == 0 # Routed to PE 0 560 + 561 + def test_ac73_route_to_allowed_sm_succeeds(self): 562 + """AC7.3: After ROUTE_SET, PE can route to allowed SM ID.""" 563 + from tokens import CfgOp, RouteSetToken 564 + 565 + env = simpy.Environment() 566 + 567 + # PE 0 with READ to SM 0 568 + iram = { 569 + 0: SMInst( 570 + op=MemOp.READ, 571 + sm_id=0, 572 + const=10, 573 + ret=Addr(a=0, port=Port.L, pe=0), 574 + ) 575 + } 576 + pe = ProcessingElement(env, 0, iram) 577 + 578 + # Full-mesh sm_routes 579 + sm_store_0 = simpy.Store(env) 580 + sm_store_1 = simpy.Store(env) 581 + pe.sm_routes[0] = sm_store_0 582 + pe.sm_routes[1] = sm_store_1 583 + 584 + # ROUTE_SET: allow SM 0 585 + route_set_token = RouteSetToken( 586 + target=0, 587 + addr=None, 588 + op=CfgOp.ROUTE_SET, 589 + pe_routes=(), 590 + sm_routes=(0,), 591 + ) 592 + pe._handle_cfg(route_set_token) 593 + 594 + # Inject token to trigger SM READ 595 + token = MonadToken(target=0, offset=0, ctx=0, data=5, inline=False) 596 + 597 + def inject(): 598 + yield pe.input_store.put(route_set_token) 599 + yield env.timeout(10) 600 + yield pe.input_store.put(token) 601 + 602 + env.process(inject()) 603 + env.run(until=200) 604 + 605 + # SM token should have been routed to SM 0 with correct target 606 + assert len(sm_store_0.items) > 0 607 + routed_token = sm_store_0.items[0] 608 + from tokens import SMToken 609 + assert isinstance(routed_token, SMToken) 610 + assert routed_token.addr == 10 # Cell address from const 611 + 612 + def test_ac74_route_to_unlisted_pe_raises_keyerror(self): 613 + """AC7.4: After ROUTE_SET, routing to unlisted PE ID raises KeyError.""" 614 + from tokens import CfgOp, RouteSetToken 615 + 616 + env = simpy.Environment() 617 + 618 + # PE 0 with PASS instruction routing to PE 1 619 + iram = { 620 + 0: ALUInst( 621 + op=RoutingOp.PASS, 622 + dest_l=Addr(a=0, port=Port.L, pe=1), 623 + dest_r=None, 624 + const=None, 625 + ) 626 + } 627 + pe = ProcessingElement(env, 0, iram) 628 + 629 + # Full-mesh route_table (PEs 0, 1, 2) 630 + pe.route_table[0] = simpy.Store(env) 631 + pe.route_table[1] = simpy.Store(env) 632 + pe.route_table[2] = simpy.Store(env) 633 + 634 + # ROUTE_SET: allow only PE 0 and 2 (exclude PE 1) 635 + route_set_token = RouteSetToken( 636 + target=0, 637 + addr=None, 638 + op=CfgOp.ROUTE_SET, 639 + pe_routes=(0, 2), 640 + sm_routes=(), 641 + ) 642 + pe._handle_cfg(route_set_token) 643 + 644 + # Inject token targeting PE 1 (not allowed) 645 + token = MonadToken(target=0, offset=0, ctx=0, data=42, inline=False) 646 + 647 + def inject(): 648 + yield pe.input_store.put(route_set_token) 649 + yield env.timeout(10) 650 + yield pe.input_store.put(token) 651 + 652 + env.process(inject()) 653 + 654 + # Should raise KeyError when trying to access route_table[1] 655 + with pytest.raises(KeyError): 656 + env.run(until=200) 657 + 658 + def test_ac75_route_to_unlisted_sm_raises_keyerror(self): 659 + """AC7.5: After ROUTE_SET, routing to unlisted SM ID raises KeyError.""" 660 + from tokens import CfgOp, RouteSetToken 661 + 662 + env = simpy.Environment() 663 + 664 + # PE 0 with READ to SM 1 665 + iram = { 666 + 0: SMInst( 667 + op=MemOp.READ, 668 + sm_id=1, 669 + const=10, 670 + ret=Addr(a=0, port=Port.L, pe=0), 671 + ) 672 + } 673 + pe = ProcessingElement(env, 0, iram) 674 + 675 + # Full-mesh sm_routes (SMs 0, 1) 676 + pe.sm_routes[0] = simpy.Store(env) 677 + pe.sm_routes[1] = simpy.Store(env) 678 + 679 + # ROUTE_SET: allow only SM 0 (exclude SM 1) 680 + route_set_token = RouteSetToken( 681 + target=0, 682 + addr=None, 683 + op=CfgOp.ROUTE_SET, 684 + pe_routes=(), 685 + sm_routes=(0,), 686 + ) 687 + pe._handle_cfg(route_set_token) 688 + 689 + # Inject token targeting SM 1 (not allowed) 690 + token = MonadToken(target=0, offset=0, ctx=0, data=5, inline=False) 691 + 692 + def inject(): 693 + yield pe.input_store.put(route_set_token) 694 + yield env.timeout(10) 695 + yield pe.input_store.put(token) 696 + 697 + env.process(inject()) 698 + 699 + # Should raise KeyError when trying to access sm_routes[1] 700 + with pytest.raises(KeyError): 701 + env.run(until=200) 702 + 703 + 704 + class TestMatchingStoreCleared: 705 + """Property-based test: Matching store is cleared after firing.""" 706 + 707 + @given(dyad_token(target=0, offset=5, ctx=1, gen=0)) 708 + def test_matching_store_cleared_after_firing(self, token_l: DyadToken): 709 + """After token pair fires, matching store slot is reset.""" 710 + env = simpy.Environment() 711 + iram = {5: ALUInst(op=ArithOp.ADD, dest_l=Addr(a=0, port=Port.L, pe=1), dest_r=None, const=None)} 712 + pe = ProcessingElement(env, 0, iram) 713 + 714 + output_store = simpy.Store(env, capacity=10) 715 + pe.route_table[1] = output_store 716 + 717 + # Create matching right token with same offset/ctx 718 + token_r = DyadToken( 719 + target=0, 720 + offset=token_l.offset, 721 + ctx=token_l.ctx, 722 + data=0x5555, 723 + port=Port.R, 724 + gen=token_l.gen, 725 + wide=False, 726 + ) 727 + 728 + ctx_idx = token_l.ctx % 4 729 + offset_idx = token_l.offset % 64 730 + 731 + def inject(): 732 + yield pe.input_store.put(token_l) 733 + yield pe.input_store.put(token_r) 734 + 735 + env.process(inject()) 736 + env.run(until=100) 737 + 738 + # After firing, matching store should be clear 739 + assert not pe.matching_store[ctx_idx][offset_idx].occupied 740 + 741 + 742 + class TestOutputTokenCountMatchesMode: 743 + """Property-based test: Output token count matches output mode.""" 744 + 745 + @given(dyad_token(target=0, offset=0, ctx=0, gen=0)) 746 + def test_suppress_mode_produces_zero_tokens(self, token_l: DyadToken): 747 + """FREE instruction (SUPPRESS mode) produces zero output tokens.""" 748 + env = simpy.Environment() 749 + # FREE is SUPPRESS mode 750 + iram = {0: ALUInst(op=RoutingOp.FREE, dest_l=None, dest_r=None, const=None)} 751 + pe = ProcessingElement(env, 0, iram) 752 + 753 + output_store = simpy.Store(env, capacity=10) 754 + pe.route_table[1] = output_store 755 + 756 + token_r = DyadToken( 757 + target=0, 758 + offset=token_l.offset, 759 + ctx=token_l.ctx, 760 + data=0x2222, 761 + port=Port.R, 762 + gen=token_l.gen, 763 + wide=False, 764 + ) 765 + 766 + def inject(): 767 + yield pe.input_store.put(token_l) 768 + yield pe.input_store.put(token_r) 769 + 770 + env.process(inject()) 771 + env.run(until=100) 772 + 773 + # SUPPRESS mode produces zero outputs 774 + assert len(output_store.items) == 0 775 + 776 + @given(dyad_token(target=0, offset=0, ctx=0, gen=0)) 777 + def test_single_mode_produces_one_token(self, token_l: DyadToken): 778 + """SINGLE mode produces one output token.""" 779 + env = simpy.Environment() 780 + # ADD with only dest_l is SINGLE mode 781 + iram = {0: ALUInst(op=ArithOp.ADD, dest_l=Addr(a=0, port=Port.L, pe=1), dest_r=None, const=None)} 782 + pe = ProcessingElement(env, 0, iram) 783 + 784 + output_store = simpy.Store(env, capacity=10) 785 + pe.route_table[1] = output_store 786 + 787 + token_r = DyadToken( 788 + target=0, 789 + offset=token_l.offset, 790 + ctx=token_l.ctx, 791 + data=0x2222, 792 + port=Port.R, 793 + gen=token_l.gen, 794 + wide=False, 795 + ) 796 + 797 + def inject(): 798 + yield pe.input_store.put(token_l) 799 + yield pe.input_store.put(token_r) 800 + 801 + env.process(inject()) 802 + env.run(until=100) 803 + 804 + # SINGLE mode produces exactly one output 805 + assert len(output_store.items) == 1 806 + 807 + @given(dyad_token(target=0, offset=0, ctx=0, gen=0)) 808 + def test_dual_mode_produces_two_tokens(self, token_l: DyadToken): 809 + """DUAL mode produces two output tokens (one per destination).""" 810 + env = simpy.Environment() 811 + # ADD with both dest_l and dest_r is DUAL mode 812 + iram = {0: ALUInst( 813 + op=ArithOp.ADD, 814 + dest_l=Addr(a=0, port=Port.L, pe=1), 815 + dest_r=Addr(a=1, port=Port.L, pe=2), 816 + const=None 817 + )} 818 + pe = ProcessingElement(env, 0, iram) 819 + 820 + output_store_l = simpy.Store(env, capacity=10) 821 + output_store_r = simpy.Store(env, capacity=10) 822 + pe.route_table[1] = output_store_l 823 + pe.route_table[2] = output_store_r 824 + 825 + token_r = DyadToken( 826 + target=0, 827 + offset=token_l.offset, 828 + ctx=token_l.ctx, 829 + data=0x2222, 830 + port=Port.R, 831 + gen=token_l.gen, 832 + wide=False, 833 + ) 834 + 835 + def inject(): 836 + yield pe.input_store.put(token_l) 837 + yield pe.input_store.put(token_r) 838 + 839 + env.process(inject()) 840 + env.run(until=100) 841 + 842 + # DUAL mode produces two outputs 843 + assert len(output_store_l.items) == 1 844 + assert len(output_store_r.items) == 1 845 + 846 + @given(dyad_token(target=0, offset=0, ctx=0, gen=0)) 847 + def test_switch_mode_produces_two_tokens(self, token_l: DyadToken): 848 + """SWITCH mode produces two output tokens (data + trigger).""" 849 + env = simpy.Environment() 850 + # SWEQ with both dests is SWITCH mode 851 + iram = {0: ALUInst( 852 + op=RoutingOp.SWEQ, 853 + dest_l=Addr(a=0, port=Port.L, pe=1), 854 + dest_r=Addr(a=1, port=Port.L, pe=2), 855 + const=None 856 + )} 857 + pe = ProcessingElement(env, 0, iram) 858 + 859 + output_store_l = simpy.Store(env, capacity=10) 860 + output_store_r = simpy.Store(env, capacity=10) 861 + pe.route_table[1] = output_store_l 862 + pe.route_table[2] = output_store_r 863 + 864 + token_r = DyadToken( 865 + target=0, 866 + offset=token_l.offset, 867 + ctx=token_l.ctx, 868 + data=token_l.data, # Same data for true condition 869 + port=Port.R, 870 + gen=token_l.gen, 871 + wide=False, 872 + ) 873 + 874 + def inject(): 875 + yield pe.input_store.put(token_l) 876 + yield pe.input_store.put(token_r) 877 + 878 + env.process(inject()) 879 + env.run(until=100) 880 + 881 + # SWITCH mode produces two outputs 882 + assert len(output_store_l.items) == 1 883 + assert len(output_store_r.items) == 1 884 + 885 + 886 + class TestStaleTokensProduceNoOutput: 887 + """Property-based test: Stale tokens (gen mismatch) produce no output.""" 888 + 889 + @given(dyad_token(target=0, offset=10, ctx=2, gen=0)) 890 + def test_stale_token_no_output(self, token_l: DyadToken): 891 + """Stale token (gen mismatch) produces no output.""" 892 + env = simpy.Environment() 893 + iram = {10: ALUInst(op=ArithOp.ADD, dest_l=Addr(a=0, port=Port.L, pe=1), dest_r=None, const=None)} 894 + pe = ProcessingElement(env, 0, iram) 895 + 896 + output_store = simpy.Store(env, capacity=10) 897 + pe.route_table[1] = output_store 898 + 899 + # Set gen_counter to be different from token's gen 900 + ctx_idx = token_l.ctx % 4 901 + pe.gen_counters[ctx_idx] = (token_l.gen + 1) % 4 902 + 903 + # Create stale token with mismatched gen 904 + token_stale = DyadToken( 905 + target=token_l.target, 906 + offset=token_l.offset, 907 + ctx=token_l.ctx, 908 + data=token_l.data, 909 + port=Port.L, 910 + gen=token_l.gen, # Stale gen 911 + wide=False, 912 + ) 913 + 914 + def inject(): 915 + yield pe.input_store.put(token_stale) 916 + 917 + env.process(inject()) 918 + env.run(until=100) 919 + 920 + # Stale token should produce no output 921 + assert len(output_store.items) == 0 922 + 923 + 924 + class TestBoundaryEdgeCases: 925 + """Test boundary and edge cases for PE operations.""" 926 + 927 + def test_load_inst_at_non_zero_base_address(self): 928 + """LOAD_INST CfgToken can load instructions at non-zero base address.""" 929 + from tokens import CfgOp, LoadInstToken 930 + 931 + env = simpy.Environment() 932 + pe = ProcessingElement(env, 0, {}) 933 + 934 + # Set up output store to collect results 935 + output_store = simpy.Store(env, capacity=10) 936 + pe.route_table[1] = output_store 937 + 938 + # Create LOAD_INST to load PASS instruction at offset 5 939 + load_inst_token = LoadInstToken( 940 + target=0, 941 + addr=5, # Non-zero base address 942 + op=CfgOp.LOAD_INST, 943 + instructions=(ALUInst( 944 + op=RoutingOp.PASS, 945 + dest_l=Addr(a=0, port=Port.L, pe=1), 946 + dest_r=None, 947 + const=None, 948 + ),), 949 + ) 950 + 951 + def inject(): 952 + # Inject LOAD_INST config token 953 + yield pe.input_store.put(load_inst_token) 954 + yield env.timeout(10) 955 + # Now inject MonadToken targeting offset 5 956 + seed_token = MonadToken(target=0, offset=5, ctx=0, data=0x1234, inline=False) 957 + yield pe.input_store.put(seed_token) 958 + 959 + env.process(inject()) 960 + env.run(until=100) 961 + 962 + # Verify instruction was loaded and executed 963 + assert len(output_store.items) == 1 964 + result = output_store.items[0] 965 + assert result.data == 0x1234 # PASS returns left operand

+192

tests/test_place.py

··· 1 + """Tests for the Placement validation pass. 2 + 3 + Tests verify: 4 + - or1-asm.AC5.1: Valid placements are accepted 5 + - or1-asm.AC5.2: Placement on nonexistent PE produces error 6 + - or1-asm.AC5.3: Unplaced node produces error 7 + """ 8 + 9 + from asm.place import place 10 + from asm.ir import IRGraph, IRNode, SystemConfig, SourceLoc 11 + from asm.errors import ErrorCategory 12 + from cm_inst import ArithOp 13 + 14 + 15 + class TestValidPlacement: 16 + """AC5.1: All nodes with explicit PE placements are accepted when PE exists.""" 17 + 18 + def test_single_node_pe0(self): 19 + """Single node on PE0.""" 20 + node = IRNode( 21 + name="&add", 22 + opcode=ArithOp.ADD, 23 + pe=0, 24 + loc=SourceLoc(1, 1), 25 + ) 26 + graph = IRGraph({"&add": node}) 27 + result = place(graph) 28 + 29 + assert len(result.errors) == 0 30 + assert result.system is not None 31 + assert result.system.pe_count >= 1 32 + 33 + def test_multiple_nodes_different_pes(self): 34 + """Multiple nodes on different PEs.""" 35 + nodes = { 36 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 37 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=1, loc=SourceLoc(2, 1)), 38 + "&inc": IRNode(name="&inc", opcode=ArithOp.INC, pe=2, loc=SourceLoc(3, 1)), 39 + "&dec": IRNode(name="&dec", opcode=ArithOp.DEC, pe=3, loc=SourceLoc(4, 1)), 40 + } 41 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 42 + graph = IRGraph(nodes, system=system) 43 + result = place(graph) 44 + 45 + assert len(result.errors) == 0 46 + assert result.system.pe_count == 4 47 + 48 + def test_system_config_inferred(self): 49 + """System config is inferred from max PE ID.""" 50 + node = IRNode( 51 + name="&add", 52 + opcode=ArithOp.ADD, 53 + pe=3, 54 + loc=SourceLoc(1, 1), 55 + ) 56 + graph = IRGraph({"&add": node}, system=None) 57 + result = place(graph) 58 + 59 + assert len(result.errors) == 0 60 + assert result.system is not None 61 + assert result.system.pe_count >= 4 # At least 4 PEs (0-3) 62 + 63 + 64 + class TestNonexistentPE: 65 + """AC5.2: Node placed on nonexistent PE produces error.""" 66 + 67 + def test_node_on_pe9_with_4_pes(self): 68 + """Node on PE9 when system only has 4 PEs.""" 69 + node = IRNode( 70 + name="&add", 71 + opcode=ArithOp.ADD, 72 + pe=9, 73 + loc=SourceLoc(5, 10), 74 + ) 75 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 76 + graph = IRGraph({"&add": node}, system=system) 77 + result = place(graph) 78 + 79 + assert len(result.errors) == 1 80 + error = result.errors[0] 81 + assert error.category == ErrorCategory.PLACEMENT 82 + assert "PE9" in error.message 83 + assert "4 PEs" in error.message 84 + assert "0-3" in error.message 85 + 86 + def test_node_on_pe1_with_1_pe(self): 87 + """Node on PE1 when system only has 1 PE.""" 88 + node = IRNode( 89 + name="&add", 90 + opcode=ArithOp.ADD, 91 + pe=1, 92 + loc=SourceLoc(1, 1), 93 + ) 94 + system = SystemConfig(pe_count=1, sm_count=1, iram_capacity=64, ctx_slots=4) 95 + graph = IRGraph({"&add": node}, system=system) 96 + result = place(graph) 97 + 98 + assert len(result.errors) == 1 99 + error = result.errors[0] 100 + assert error.category == ErrorCategory.PLACEMENT 101 + assert "PE1" in error.message 102 + assert "0-0" in error.message 103 + 104 + def test_multiple_nodes_one_invalid_pe(self): 105 + """Multiple nodes, one on invalid PE.""" 106 + nodes = { 107 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 108 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=5, loc=SourceLoc(2, 1)), 109 + "&inc": IRNode(name="&inc", opcode=ArithOp.INC, pe=1, loc=SourceLoc(3, 1)), 110 + } 111 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 112 + graph = IRGraph(nodes, system=system) 113 + result = place(graph) 114 + 115 + assert len(result.errors) == 1 116 + error = result.errors[0] 117 + assert error.category == ErrorCategory.PLACEMENT 118 + assert "&sub" in error.message 119 + assert "PE5" in error.message 120 + 121 + 122 + class TestUnplacedNode: 123 + """AC10.1: Unplaced nodes are auto-placed without explicit annotations (Phase 7).""" 124 + 125 + def test_single_unplaced_node(self): 126 + """Single unplaced node gets auto-placed.""" 127 + node = IRNode( 128 + name="&add", 129 + opcode=ArithOp.ADD, 130 + pe=None, 131 + loc=SourceLoc(5, 3), 132 + ) 133 + graph = IRGraph({"&add": node}) 134 + result = place(graph) 135 + 136 + # Phase 7: auto-placement should succeed 137 + assert len(result.errors) == 0 138 + assert result.nodes["&add"].pe is not None 139 + 140 + def test_multiple_nodes_some_unplaced(self): 141 + """Unplaced nodes get auto-placed (Phase 7).""" 142 + nodes = { 143 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 144 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 145 + "&inc": IRNode(name="&inc", opcode=ArithOp.INC, pe=None, loc=SourceLoc(3, 1)), 146 + } 147 + system = SystemConfig(pe_count=2, sm_count=1, iram_capacity=64, ctx_slots=4) 148 + graph = IRGraph(nodes, system=system) 149 + result = place(graph) 150 + 151 + # Phase 7: auto-placement should succeed 152 + assert len(result.errors) == 0 153 + assert result.nodes["&sub"].pe is not None 154 + assert result.nodes["&inc"].pe is not None 155 + 156 + def test_all_nodes_unplaced(self): 157 + """All unplaced nodes get auto-placed (Phase 7).""" 158 + nodes = { 159 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=None, loc=SourceLoc(1, 1)), 160 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 161 + } 162 + graph = IRGraph(nodes) 163 + result = place(graph) 164 + 165 + # Phase 7: auto-placement should succeed 166 + assert len(result.errors) == 0 167 + for node in result.nodes.values(): 168 + assert node.pe is not None 169 + 170 + 171 + class TestMixedErrors: 172 + """Combined placement errors.""" 173 + 174 + def test_unplaced_and_invalid_pe(self): 175 + """Invalid PE placement produces error; unplaced nodes are auto-placed.""" 176 + nodes = { 177 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0, loc=SourceLoc(1, 1)), 178 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=None, loc=SourceLoc(2, 1)), 179 + "&inc": IRNode(name="&inc", opcode=ArithOp.INC, pe=9, loc=SourceLoc(3, 1)), 180 + } 181 + system = SystemConfig(pe_count=4, sm_count=1, iram_capacity=64, ctx_slots=4) 182 + graph = IRGraph(nodes, system=system) 183 + result = place(graph) 184 + 185 + # Should have 1 error for invalid PE placement on &inc; &sub is auto-placed 186 + assert len(result.errors) == 1 187 + error = result.errors[0] 188 + assert error.category == ErrorCategory.PLACEMENT 189 + assert "&inc" in error.message 190 + assert "PE9" in error.message 191 + # &sub should be auto-placed 192 + assert result.nodes["&sub"].pe is not None

+362

tests/test_resolve.py

··· 1 + """Tests for the Resolve pass (name resolution in IRGraph). 2 + 3 + Tests verify: 4 + - Valid programs with all names resolved (AC4.1, AC4.2) 5 + - Undefined name references with "did you mean" suggestions (AC4.3) 6 + - Scope violations when cross-referencing function-local labels (AC4.4) 7 + - Levenshtein distance computation for suggestions (AC4.5) 8 + """ 9 + 10 + from tests.pipeline import parse_lower_resolve 11 + 12 + from asm.resolve import _levenshtein 13 + from asm.errors import ErrorCategory 14 + 15 + 16 + class TestValidResolution: 17 + """Tests for successful name resolution (AC4.1, AC4.2).""" 18 + 19 + def test_simple_two_node_edge_resolves(self, parser): 20 + """Simple program with two nodes and an edge between them resolves with no errors.""" 21 + graph = parse_lower_resolve( 22 + parser, 23 + """\ 24 + &a <| pass 25 + &b <| add 26 + &a |> &b:L 27 + """, 28 + ) 29 + 30 + # Should have no resolution errors 31 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 32 + scope_errors = [e for e in graph.errors if e.category == ErrorCategory.SCOPE] 33 + assert len(name_errors) == 0, f"Unexpected NAME errors: {name_errors}" 34 + assert len(scope_errors) == 0, f"Unexpected SCOPE errors: {scope_errors}" 35 + 36 + def test_cross_function_wiring_via_global_nodes(self, parser): 37 + """Cross-function wiring via @nodes resolves correctly. 38 + 39 + Test that a global node can be wired to and from function-scoped labels. 40 + After lowering, these are stored as region.body edges with simple names, 41 + but when resolved, they reference the flattened qualified names. 42 + """ 43 + graph = parse_lower_resolve( 44 + parser, 45 + """\ 46 + @bridge <| pass 47 + 48 + $foo |> { 49 + &a <| pass 50 + &a |> @bridge:L 51 + } 52 + 53 + $bar |> { 54 + &b <| add 55 + @bridge |> &b:L 56 + } 57 + """, 58 + ) 59 + 60 + # Should have no resolution errors 61 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 62 + assert len(name_errors) == 0, f"Unexpected NAME errors: {name_errors}" 63 + 64 + def test_function_scoped_labels_within_same_function_resolve(self, parser): 65 + """Program with function-scoped labels and edges within same function resolve correctly.""" 66 + graph = parse_lower_resolve( 67 + parser, 68 + """\ 69 + $main |> { 70 + &input <| pass 71 + &process <| add 72 + &output <| pass 73 + &input |> &process:L 74 + &process |> &output:L 75 + } 76 + """, 77 + ) 78 + 79 + # Should have no resolution errors 80 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 81 + assert len(name_errors) == 0, f"Unexpected NAME errors: {name_errors}" 82 + 83 + def test_global_and_function_nodes_coexist(self, parser): 84 + """Program with both global @nodes and function-scoped &labels resolves correctly.""" 85 + graph = parse_lower_resolve( 86 + parser, 87 + """\ 88 + @global <| pass 89 + 90 + $worker |> { 91 + &local <| add 92 + &local |> @global:L 93 + } 94 + """, 95 + ) 96 + 97 + # Should have no resolution errors 98 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 99 + assert len(name_errors) == 0, f"Unexpected NAME errors: {name_errors}" 100 + 101 + 102 + class TestUndefinedReference: 103 + """Tests for undefined name errors with suggestions (AC4.3).""" 104 + 105 + def test_undefined_label_produces_name_error(self, parser): 106 + """Edge referencing undefined &nonexistent produces error with NAME category.""" 107 + graph = parse_lower_resolve( 108 + parser, 109 + """\ 110 + &a <| pass 111 + &b <| add 112 + &a |> &nonexistent:L 113 + """, 114 + ) 115 + 116 + # Should have a NAME error 117 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 118 + assert len(name_errors) == 1 119 + error = name_errors[0] 120 + assert "undefined" in error.message.lower() 121 + 122 + def test_error_includes_source_location(self, parser): 123 + """NAME error includes source location (line/column).""" 124 + graph = parse_lower_resolve( 125 + parser, 126 + """\ 127 + &a <| pass 128 + &b <| add 129 + &a |> &nonexistent:L 130 + """, 131 + ) 132 + 133 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 134 + assert len(name_errors) == 1 135 + error = name_errors[0] 136 + # Error should have a valid location 137 + assert error.loc.line > 0 138 + assert error.loc.column >= 0 139 + 140 + def test_suggestion_for_similar_name(self, parser): 141 + """Reference to &nonexistant suggests &nonexistent if it exists.""" 142 + graph = parse_lower_resolve( 143 + parser, 144 + """\ 145 + &nonexistent <| pass 146 + &a <| add 147 + &a |> &nonexistant:L 148 + """, 149 + ) 150 + 151 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 152 + assert len(name_errors) == 1 153 + error = name_errors[0] 154 + # Should have suggestions 155 + assert len(error.suggestions) > 0 156 + 157 + 158 + class TestScopeViolation: 159 + """Tests for scope violation errors (AC4.4).""" 160 + 161 + def test_cross_scope_reference_produces_scope_error(self, parser): 162 + """Reference to function-local label from top level produces SCOPE error.""" 163 + graph = parse_lower_resolve( 164 + parser, 165 + """\ 166 + $foo |> { 167 + &private <| pass 168 + } 169 + 170 + &top <| add 171 + &top |> &private:L 172 + """, 173 + ) 174 + 175 + # Should have a SCOPE error, not NAME 176 + scope_errors = [e for e in graph.errors if e.category == ErrorCategory.SCOPE] 177 + assert len(scope_errors) == 1 178 + error = scope_errors[0] 179 + # Error should identify the function containing the label 180 + assert "$foo" in error.message or "function" in error.message.lower() 181 + 182 + def test_scope_error_mentions_actual_scope(self, parser): 183 + """Scope error message mentions the function where label is actually defined.""" 184 + graph = parse_lower_resolve( 185 + parser, 186 + """\ 187 + $foo |> { 188 + &private <| pass 189 + } 190 + 191 + $bar |> { 192 + &x <| add 193 + } 194 + 195 + &top <| pass 196 + &top |> &private:L 197 + """, 198 + ) 199 + 200 + scope_errors = [e for e in graph.errors if e.category == ErrorCategory.SCOPE] 201 + assert len(scope_errors) == 1 202 + error = scope_errors[0] 203 + assert "$foo" in error.message 204 + 205 + def test_reference_from_different_function_is_scope_error(self, parser): 206 + """Reference to label in $foo from within $bar produces SCOPE error.""" 207 + graph = parse_lower_resolve( 208 + parser, 209 + """\ 210 + $foo |> { 211 + &data <| const, 42 212 + } 213 + 214 + $bar |> { 215 + &use <| add 216 + &use |> &data:L 217 + } 218 + """, 219 + ) 220 + 221 + # Should have a SCOPE error 222 + scope_errors = [e for e in graph.errors if e.category == ErrorCategory.SCOPE] 223 + assert len(scope_errors) == 1 224 + 225 + 226 + class TestLevenshteinSuggestions: 227 + """Tests for Levenshtein distance suggestions (AC4.5).""" 228 + 229 + def test_levenshtein_kitten_sitting(self): 230 + """Direct test: _levenshtein("kitten", "sitting") == 3.""" 231 + distance = _levenshtein("kitten", "sitting") 232 + assert distance == 3 233 + 234 + def test_levenshtein_identical_strings(self): 235 + """_levenshtein identical strings returns 0.""" 236 + assert _levenshtein("test", "test") == 0 237 + 238 + def test_levenshtein_empty_string(self): 239 + """_levenshtein empty string.""" 240 + assert _levenshtein("", "") == 0 241 + assert _levenshtein("abc", "") == 3 242 + assert _levenshtein("", "abc") == 3 243 + 244 + def test_levenshtein_single_insertion(self): 245 + """_levenshtein single character insertion.""" 246 + assert _levenshtein("add", "addd") == 1 247 + 248 + def test_levenshtein_single_deletion(self): 249 + """_levenshtein single character deletion.""" 250 + assert _levenshtein("addd", "add") == 1 251 + 252 + def test_levenshtein_single_substitution(self): 253 + """_levenshtein single character substitution.""" 254 + assert _levenshtein("cat", "bat") == 1 255 + 256 + def test_suggestion_for_typo_one_char(self, parser): 257 + """Reference to &ad suggests &add (distance 1).""" 258 + graph = parse_lower_resolve( 259 + parser, 260 + """\ 261 + &add <| pass 262 + &x <| pass 263 + &x |> &ad:L 264 + """, 265 + ) 266 + 267 + # Should have NAME error with suggestion 268 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 269 + assert len(name_errors) == 1 270 + error = name_errors[0] 271 + assert len(error.suggestions) > 0 272 + # Suggestion should include &add 273 + suggestion_text = " ".join(error.suggestions) 274 + assert "add" in suggestion_text 275 + 276 + def test_suggestion_for_typo_two_chars(self, parser): 277 + """Reference to &addd suggests &add (distance 1).""" 278 + graph = parse_lower_resolve( 279 + parser, 280 + """\ 281 + &add <| pass 282 + &x <| pass 283 + &x |> &addd:L 284 + """, 285 + ) 286 + 287 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 288 + assert len(name_errors) == 1 289 + error = name_errors[0] 290 + assert len(error.suggestions) > 0 291 + suggestion_text = " ".join(error.suggestions) 292 + assert "add" in suggestion_text 293 + 294 + def test_no_suggestion_for_completely_wrong_name(self, parser): 295 + """Reference to &completely_wrong with no similar names may have no suggestion.""" 296 + graph = parse_lower_resolve( 297 + parser, 298 + """\ 299 + &add <| pass 300 + &x <| pass 301 + &x |> &completely_wrong:L 302 + """, 303 + ) 304 + 305 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 306 + assert len(name_errors) == 1 307 + # May or may not have suggestions depending on implementation 308 + # (best-effort or distance threshold) 309 + 310 + def test_multiple_errors_all_collected(self, parser): 311 + """Multiple undefined references all produce errors (error accumulation).""" 312 + graph = parse_lower_resolve( 313 + parser, 314 + """\ 315 + &a <| pass 316 + &b <| add 317 + &a |> &undef1:L 318 + &b |> &undef2:R 319 + """, 320 + ) 321 + 322 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 323 + # Should have 2 NAME errors (both undefined refs) 324 + assert len(name_errors) == 2 325 + 326 + 327 + class TestEdgeCases: 328 + """Edge case tests for resolution.""" 329 + 330 + def test_empty_program_resolves(self, parser): 331 + """Empty program resolves with no errors.""" 332 + graph = parse_lower_resolve(parser, "") 333 + assert len(graph.errors) == 0 334 + 335 + def test_program_only_defs_no_edges_resolves(self, parser): 336 + """Program with only definitions and no edges resolves with no errors.""" 337 + graph = parse_lower_resolve( 338 + parser, 339 + """\ 340 + &a <| pass 341 + &b <| add 342 + &c <| sub 343 + """, 344 + ) 345 + 346 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 347 + assert len(name_errors) == 0 348 + 349 + def test_circular_wiring_resolves(self, parser): 350 + """Circular wiring (feedback loops) resolves correctly.""" 351 + graph = parse_lower_resolve( 352 + parser, 353 + """\ 354 + &a <| pass 355 + &b <| add 356 + &a |> &b:L 357 + &b |> &a:R 358 + """, 359 + ) 360 + 361 + name_errors = [e for e in graph.errors if e.category == ErrorCategory.NAME] 362 + assert len(name_errors) == 0

+267

tests/test_serialize.py

··· 1 + """Tests for IRGraph serialization to dfasm source. 2 + 3 + Tests verify the serialize() function converts IRGraphs back to valid dfasm source 4 + and preserves structural information through round-trip parsing and lowering. 5 + """ 6 + 7 + from tests.pipeline import parse_and_lower, parse_lower_resolve 8 + 9 + from asm.ir import ( 10 + IRGraph, IRNode, IREdge, IRRegion, RegionKind, IRDataDef 11 + ) 12 + from asm.serialize import serialize 13 + from asm.opcodes import OP_TO_MNEMONIC 14 + from cm_inst import MemOp, ArithOp, LogicOp, RoutingOp 15 + from tokens import Port 16 + 17 + 18 + class TestRoundTrip: 19 + """AC11.1, AC11.2: Round-trip parse → lower → serialize → parse → lower""" 20 + 21 + def test_simple_two_node_graph(self, parser): 22 + """AC11.1: Simple graph with two nodes and one edge round-trips.""" 23 + source = """ 24 + &add|pe0 <| add 25 + &const|pe0 <| const, 42 26 + &add |> &const:L 27 + """ 28 + # Parse and lower to get baseline IRGraph 29 + graph1 = parse_and_lower(parser, source) 30 + 31 + # Serialize and re-parse, lower 32 + serialized = serialize(graph1) 33 + graph2 = parse_and_lower(parser, serialized) 34 + 35 + # Check structural equivalence 36 + assert set(graph1.nodes.keys()) == set(graph2.nodes.keys()) 37 + assert len(graph1.edges) == len(graph2.edges) 38 + 39 + def test_single_node_roundtrip(self, parser): 40 + """AC11.1: Single node without edges round-trips.""" 41 + source = "&foo|pe0 <| add" 42 + 43 + graph1 = parse_and_lower(parser, source) 44 + serialized = serialize(graph1) 45 + graph2 = parse_and_lower(parser, serialized) 46 + 47 + assert set(graph1.nodes.keys()) == set(graph2.nodes.keys()) 48 + assert len(graph1.edges) == len(graph2.edges) 49 + 50 + def test_graph_with_multiple_edges(self, parser): 51 + """AC11.2: Graph with multiple edges preserves edge count.""" 52 + source = """ 53 + &a|pe0 <| add 54 + &b|pe0 <| sub 55 + &c|pe1 <| add 56 + &a |> &b:L 57 + &a |> &c:R 58 + &b |> &c:L 59 + """ 60 + graph1 = parse_and_lower(parser, source) 61 + serialized = serialize(graph1) 62 + graph2 = parse_and_lower(parser, serialized) 63 + 64 + assert len(graph1.edges) == len(graph2.edges) 65 + assert set(graph1.nodes.keys()) == set(graph2.nodes.keys()) 66 + 67 + 68 + class TestPlacementQualifiers: 69 + """AC11.3: All inst_def lines include |pe{N} qualifiers.""" 70 + 71 + def test_all_nodes_have_pe_qualifier(self): 72 + """AC11.3: Serialized output contains |pe{N} on every inst_def.""" 73 + # Create a graph with nodes on different PEs 74 + nodes = { 75 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=0), 76 + "&b": IRNode(name="&b", opcode=ArithOp.SUB, pe=1), 77 + "&c": IRNode(name="&c", opcode=RoutingOp.CONST, const=42, pe=0), 78 + } 79 + graph = IRGraph(nodes=nodes) 80 + 81 + serialized = serialize(graph) 82 + lines = serialized.strip().split('\n') 83 + 84 + # Filter to inst_def lines (contain '<|') 85 + inst_lines = [l for l in lines if '<|' in l] 86 + 87 + # Each should contain |pe{N} 88 + for line in inst_lines: 89 + assert '|pe' in line, f"Missing PE qualifier in: {line}" 90 + 91 + 92 + class TestFunctionScoping: 93 + """AC11.4, AC11.7: FUNCTION regions serialize with scoping blocks.""" 94 + 95 + def test_function_region_structure(self): 96 + """AC11.4, AC11.7: FUNCTION regions emit $name |> { ... } blocks.""" 97 + # Create a function region with unqualified node names inside 98 + func_nodes = { 99 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0), 100 + "&const": IRNode(name="&const", opcode=RoutingOp.CONST, const=10, pe=0), 101 + } 102 + func_body = IRGraph(nodes=func_nodes) 103 + func_region = IRRegion(tag="$main", kind=RegionKind.FUNCTION, body=func_body) 104 + 105 + graph = IRGraph(regions=[func_region]) 106 + serialized = serialize(graph) 107 + 108 + # Check for function block syntax 109 + assert "$main |>" in serialized 110 + assert "{" in serialized 111 + assert "}" in serialized 112 + 113 + # Check that node names inside are unqualified (no $main. prefix) 114 + assert "&add|pe0 <| add" in serialized or "&add|pe0 <| add" in serialized.replace('\n', ' ') 115 + 116 + def test_unqualified_names_in_function(self): 117 + """AC11.7: Names inside FUNCTION regions are unqualified.""" 118 + func_nodes = { 119 + "&label": IRNode(name="&label", opcode=ArithOp.ADD, pe=0), 120 + } 121 + func_body = IRGraph(nodes=func_nodes) 122 + func_region = IRRegion(tag="$main", kind=RegionKind.FUNCTION, body=func_body) 123 + 124 + graph = IRGraph(regions=[func_region]) 125 + serialized = serialize(graph) 126 + 127 + # Should not contain the qualified name $main.&label 128 + assert "$main.&label" not in serialized 129 + # Should contain unqualified &label 130 + assert "&label" in serialized 131 + 132 + 133 + class TestDataDefs: 134 + """AC11.5: data_def entries serialize with SM placement and cell addresses.""" 135 + 136 + def test_data_def_serialization(self): 137 + """AC11.5: Data definitions serialize as @name|sm{id}:{cell} = {value}.""" 138 + data_defs = [ 139 + IRDataDef(name="@hello", sm_id=0, cell_addr=5, value=0x2a), 140 + IRDataDef(name="@world", sm_id=1, cell_addr=10, value=0x3f), 141 + ] 142 + graph = IRGraph(data_defs=data_defs) 143 + 144 + serialized = serialize(graph) 145 + 146 + # Check for data def entries 147 + assert "@hello|sm0:5 =" in serialized 148 + assert "@world|sm1:10 =" in serialized 149 + # Check hex values are present 150 + assert "0x2a" in serialized or "42" in serialized 151 + assert "0x3f" in serialized or "63" in serialized 152 + 153 + 154 + class TestAnonymousNodes: 155 + """AC11.6: Anonymous nodes serialize as inst_def + plain_edge, not inline.""" 156 + 157 + def test_anonymous_node_not_inline(self): 158 + """AC11.6: Nodes with __anon_ in name use inst_def + plain_edge form.""" 159 + nodes = { 160 + "&source": IRNode(name="&source", opcode=ArithOp.ADD, pe=0), 161 + "__anon_1": IRNode(name="__anon_1", opcode=ArithOp.SUB, pe=0), 162 + "&dest": IRNode(name="&dest", opcode=ArithOp.ADD, pe=1), 163 + } 164 + edges = [ 165 + IREdge(source="&source", dest="__anon_1", port=Port.L), 166 + IREdge(source="__anon_1", dest="&dest", port=Port.R), 167 + ] 168 + graph = IRGraph(nodes=nodes, edges=edges) 169 + 170 + serialized = serialize(graph) 171 + 172 + # Anonymous node should be defined as a separate inst_def, not inline 173 + assert "__anon_1|pe0 <|" in serialized 174 + # Should have explicit edges, not inline syntax 175 + assert "&source |> __anon_1:L" in serialized 176 + assert "__anon_1 |> &dest:R" in serialized 177 + 178 + 179 + class TestLocationRegions: 180 + """AC11.8: LOCATION regions serialize as bare directive + body.""" 181 + 182 + def test_location_region_structure(self): 183 + """AC11.8: LOCATION regions emit bare directive tag followed by body.""" 184 + # Create a location region with data definitions inside 185 + loc_data = [ 186 + IRDataDef(name="@data1", sm_id=0, cell_addr=5, value=100), 187 + ] 188 + loc_body = IRGraph(data_defs=loc_data) 189 + loc_region = IRRegion(tag="@data_section", kind=RegionKind.LOCATION, body=loc_body) 190 + 191 + graph = IRGraph(regions=[loc_region]) 192 + serialized = serialize(graph) 193 + 194 + # Location directive should appear as bare tag (not in $func |> form) 195 + assert "@data_section" in serialized 196 + # Body content should follow 197 + assert "@data1|sm0:5" in serialized 198 + 199 + 200 + class TestEdgeSerialization: 201 + """Edges serialize as plain_edge form.""" 202 + 203 + def test_edge_port_notation(self): 204 + """Edges serialize with :L and :R port notation.""" 205 + nodes = { 206 + "&a": IRNode(name="&a", opcode=ArithOp.ADD, pe=0), 207 + "&b": IRNode(name="&b", opcode=ArithOp.ADD, pe=1), 208 + } 209 + edges = [ 210 + IREdge(source="&a", dest="&b", port=Port.L), 211 + ] 212 + graph = IRGraph(nodes=nodes, edges=edges) 213 + 214 + serialized = serialize(graph) 215 + 216 + # Should contain edge with port notation 217 + assert "|> &b:L" in serialized 218 + 219 + 220 + class TestMnemonicUsage: 221 + """Opcodes serialize using OP_TO_MNEMONIC.""" 222 + 223 + def test_various_opcodes(self): 224 + """Different opcodes serialize with correct mnemonics.""" 225 + nodes = { 226 + "&add": IRNode(name="&add", opcode=ArithOp.ADD, pe=0), 227 + "&sub": IRNode(name="&sub", opcode=ArithOp.SUB, pe=0), 228 + "&and": IRNode(name="&and", opcode=LogicOp.AND, pe=0), 229 + "&read": IRNode(name="&read", opcode=MemOp.READ, pe=0), 230 + } 231 + graph = IRGraph(nodes=nodes) 232 + 233 + serialized = serialize(graph) 234 + 235 + # Check that mnemonics appear 236 + assert "add" in serialized 237 + assert "sub" in serialized 238 + assert "and" in serialized 239 + assert "read" in serialized 240 + 241 + 242 + class TestConstValues: 243 + """Const values serialize in inst_def format.""" 244 + 245 + def test_const_node_with_value(self): 246 + """Nodes with const values serialize with const argument.""" 247 + nodes = { 248 + "&c": IRNode(name="&c", opcode=RoutingOp.CONST, const=255, pe=0), 249 + } 250 + graph = IRGraph(nodes=nodes) 251 + 252 + serialized = serialize(graph) 253 + 254 + # Should include const value 255 + assert "const, 255" in serialized or "const, 0xff" in serialized 256 + 257 + 258 + class TestEmptyGraph: 259 + """Edge case: empty graph.""" 260 + 261 + def test_empty_graph_serializes(self): 262 + """AC11.1: Empty graph serializes to empty or whitespace string.""" 263 + graph = IRGraph() 264 + serialized = serialize(graph) 265 + 266 + # Should not raise, should be empty or whitespace 267 + assert serialized.strip() == ""

+330 -33

tests/test_sm.py

··· 14 14 """ 15 15 16 16 import simpy 17 - from hypothesis import given 17 + from hypothesis import given, strategies as st 18 18 19 19 from emu.sm import StructureMemory 20 20 from sm_mod import Presence 21 - from tests.conftest import sm_token 21 + from tests.conftest import sm_token, sm_return_route, uint16 22 22 from tokens import CMToken, MemOp, SMToken 23 23 24 24 ··· 47 47 48 48 # Inject READ token targeting cell 10 49 49 ret_route = CMToken(target=0, offset=5, ctx=1, data=0) 50 - read_token = SMToken(target=10, op=MemOp.READ, flags=None, data=None, ret=ret_route) 50 + read_token = SMToken(target=0, addr=10, op=MemOp.READ, flags=None, data=None, ret=ret_route) 51 51 inject_token(env, sm.input_store, read_token) 52 52 53 53 # Run simulation ··· 77 77 78 78 # Inject READ token targeting cell 20 79 79 ret_route = CMToken(target=0, offset=7, ctx=2, data=0) 80 - read_token = SMToken(target=20, op=MemOp.READ, flags=None, data=None, ret=ret_route) 80 + read_token = SMToken(target=0, addr=20, op=MemOp.READ, flags=None, data=None, ret=ret_route) 81 81 inject_token(env, sm.input_store, read_token) 82 82 83 83 # Run simulation ··· 108 108 109 109 # Set up deferred read on cell 30 110 110 ret_route = CMToken(target=0, offset=8, ctx=3, data=0) 111 - read_token = SMToken(target=30, op=MemOp.READ, flags=None, data=None, ret=ret_route) 111 + read_token = SMToken(target=0, addr=30, op=MemOp.READ, flags=None, data=None, ret=ret_route) 112 112 inject_token(env, sm.input_store, read_token) 113 113 114 114 # Run to let deferred read be set up 115 115 env.run(until=10) 116 116 117 117 # Now inject WRITE to cell 30 118 - write_token = SMToken(target=30, op=MemOp.WRITE, flags=None, data=0xDEAD, ret=None) 118 + write_token = SMToken(target=0, addr=30, op=MemOp.WRITE, flags=None, data=0xDEAD, ret=None) 119 119 inject_token(env, sm.input_store, write_token) 120 120 121 121 # Continue simulation ··· 147 147 assert sm.cells[40].pres == Presence.EMPTY 148 148 149 149 # Inject WRITE 150 - write_token = SMToken(target=40, op=MemOp.WRITE, flags=None, data=0xCAFE, ret=None) 150 + write_token = SMToken(target=0, addr=40, op=MemOp.WRITE, flags=None, data=0xCAFE, ret=None) 151 151 inject_token(env, sm.input_store, write_token) 152 152 153 153 env.run(until=100) ··· 164 164 sm.cells[50].pres = Presence.RESERVED 165 165 166 166 # Inject WRITE 167 - write_token = SMToken(target=50, op=MemOp.WRITE, flags=None, data=0xF00D, ret=None) 167 + write_token = SMToken(target=0, addr=50, op=MemOp.WRITE, flags=None, data=0xF00D, ret=None) 168 168 inject_token(env, sm.input_store, write_token) 169 169 170 170 env.run(until=100) ··· 186 186 sm.cells[60].data_l = 0x1234 187 187 188 188 # Inject CLEAR 189 - clear_token = SMToken(target=60, op=MemOp.CLEAR, flags=None, data=None, ret=None) 189 + clear_token = SMToken(target=0, addr=60, op=MemOp.CLEAR, flags=None, data=None, ret=None) 190 190 inject_token(env, sm.input_store, clear_token) 191 191 192 192 env.run(until=100) ··· 205 205 206 206 # Set up deferred read on cell 70 207 207 ret_route = CMToken(target=0, offset=10, ctx=0, data=0) 208 - read_token = SMToken(target=70, op=MemOp.READ, flags=None, data=None, ret=ret_route) 208 + read_token = SMToken(target=0, addr=70, op=MemOp.READ, flags=None, data=None, ret=ret_route) 209 209 inject_token(env, sm.input_store, read_token) 210 210 211 211 env.run(until=10) 212 212 213 213 # Now inject CLEAR on cell 70 214 - clear_token = SMToken(target=70, op=MemOp.CLEAR, flags=None, data=None, ret=None) 214 + clear_token = SMToken(target=0, addr=70, op=MemOp.CLEAR, flags=None, data=None, ret=None) 215 215 inject_token(env, sm.input_store, clear_token) 216 216 217 217 env.run(until=100) ··· 238 238 sm.cells[80].data_l = 0x5555 239 239 240 240 # Inject WRITE with data Y 241 - write_token = SMToken(target=80, op=MemOp.WRITE, flags=None, data=0xAAAA, ret=None) 241 + write_token = SMToken(target=0, addr=80, op=MemOp.WRITE, flags=None, data=0xAAAA, ret=None) 242 242 inject_token(env, sm.input_store, write_token) 243 243 244 244 env.run(until=100) ··· 265 265 266 266 # Inject RD_INC 267 267 ret_route = CMToken(target=0, offset=11, ctx=0, data=0) 268 - inc_token = SMToken(target=100, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 268 + inc_token = SMToken(target=0, addr=100, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 269 269 inject_token(env, sm.input_store, inc_token) 270 270 271 271 env.run(until=100) ··· 291 291 292 292 # Inject RD_INC 293 293 ret_route = CMToken(target=0, offset=12, ctx=0, data=0) 294 - inc_token = SMToken(target=110, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 294 + inc_token = SMToken(target=0, addr=110, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 295 295 inject_token(env, sm.input_store, inc_token) 296 296 297 297 env.run(until=100) ··· 317 317 318 318 # Inject RD_DEC 319 319 ret_route = CMToken(target=0, offset=13, ctx=0, data=0) 320 - dec_token = SMToken(target=120, op=MemOp.RD_DEC, flags=None, data=None, ret=ret_route) 320 + dec_token = SMToken(target=0, addr=120, op=MemOp.RD_DEC, flags=None, data=None, ret=ret_route) 321 321 inject_token(env, sm.input_store, dec_token) 322 322 323 323 env.run(until=100) ··· 338 338 339 339 # Inject RD_INC 340 340 ret_route = CMToken(target=0, offset=14, ctx=0, data=0) 341 - inc_token = SMToken(target=130, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 341 + inc_token = SMToken(target=0, addr=130, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 342 342 inject_token(env, sm.input_store, inc_token) 343 343 344 344 # Create collector ··· 365 365 366 366 # Inject RD_INC on cell 256 (should be rejected) 367 367 ret_route = CMToken(target=0, offset=15, ctx=0, data=0) 368 - inc_token = SMToken(target=256, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 368 + inc_token = SMToken(target=0, addr=256, op=MemOp.RD_INC, flags=None, data=None, ret=ret_route) 369 369 inject_token(env, sm.input_store, inc_token) 370 370 371 371 env.run(until=100) ··· 392 392 393 393 ret_a = CMToken(target=0, offset=20, ctx=0, data=0) 394 394 ret_b = CMToken(target=0, offset=21, ctx=1, data=0) 395 - read_a = SMToken(target=140, op=MemOp.READ, flags=None, data=None, ret=ret_a) 396 - read_b = SMToken(target=150, op=MemOp.READ, flags=None, data=None, ret=ret_b) 395 + read_a = SMToken(target=0, addr=140, op=MemOp.READ, flags=None, data=None, ret=ret_a) 396 + read_b = SMToken(target=0, addr=150, op=MemOp.READ, flags=None, data=None, ret=ret_b) 397 397 398 398 # Inject both READs before any WRITE 399 399 inject_token(env, sm.input_store, read_a) ··· 408 408 assert sm.cells[150].pres == Presence.EMPTY 409 409 410 410 # Satisfy first deferred by writing to A 411 - write_a = SMToken(target=140, op=MemOp.WRITE, flags=None, data=0x1111, ret=None) 411 + write_a = SMToken(target=0, addr=140, op=MemOp.WRITE, flags=None, data=0x1111, ret=None) 412 412 inject_token(env, sm.input_store, write_a) 413 413 env.run(until=50) 414 414 ··· 418 418 assert sm.deferred_read.cell_addr == 150 419 419 420 420 # Satisfy second deferred 421 - write_b = SMToken(target=150, op=MemOp.WRITE, flags=None, data=0x2222, ret=None) 421 + write_b = SMToken(target=0, addr=150, op=MemOp.WRITE, flags=None, data=0x2222, ret=None) 422 422 inject_token(env, sm.input_store, write_b) 423 423 env.run(until=200) 424 424 ··· 428 428 assert collector.items[1].data == 0x2222 429 429 assert sm.cells[150].pres == Presence.FULL 430 430 assert sm.cells[150].data_l == 0x2222 431 - assert len(collector.items) == 2 432 - assert collector.items[0].data == 0x1111 433 - assert collector.items[1].data == 0x2222 434 431 435 432 436 433 class TestAC3_9CAS: ··· 450 447 451 448 # Inject CMP_SW with flags=10 (expected), data=99 (new) 452 449 ret_route = CMToken(target=0, offset=22, ctx=0, data=0) 453 - cas_token = SMToken(target=160, op=MemOp.CMP_SW, flags=10, data=99, ret=ret_route) 450 + cas_token = SMToken(target=0, addr=160, op=MemOp.CMP_SW, flags=10, data=99, ret=ret_route) 454 451 inject_token(env, sm.input_store, cas_token) 455 452 456 453 env.run(until=100) ··· 476 473 477 474 # Inject CMP_SW with flags=20 (mismatch), data=99 (new) 478 475 ret_route = CMToken(target=0, offset=23, ctx=0, data=0) 479 - cas_token = SMToken(target=170, op=MemOp.CMP_SW, flags=20, data=99, ret=ret_route) 476 + cas_token = SMToken(target=0, addr=170, op=MemOp.CMP_SW, flags=20, data=99, ret=ret_route) 480 477 inject_token(env, sm.input_store, cas_token) 481 478 482 479 env.run(until=100) ··· 502 499 503 500 # Inject CMP_SW on cell 256 (should be rejected) 504 501 ret_route = CMToken(target=0, offset=24, ctx=0, data=0) 505 - cas_token = SMToken(target=256, op=MemOp.CMP_SW, flags=10, data=99, ret=ret_route) 502 + cas_token = SMToken(target=0, addr=256, op=MemOp.CMP_SW, flags=10, data=99, ret=ret_route) 506 503 inject_token(env, sm.input_store, cas_token) 507 504 508 505 env.run(until=100) ··· 529 526 if token.ret is None: 530 527 token = SMToken( 531 528 target=token.target, 529 + addr=token.addr, 532 530 op=token.op, 533 531 flags=token.flags, 534 532 data=token.data, ··· 537 535 538 536 # Pre-populate target cell as FULL if it's an atomic operation 539 537 if token.op in (MemOp.RD_INC, MemOp.RD_DEC, MemOp.CMP_SW): 540 - sm.cells[token.target].pres = Presence.FULL 541 - sm.cells[token.target].data_l = 0x1234 538 + sm.cells[token.addr].pres = Presence.FULL 539 + sm.cells[token.addr].data_l = 0x1234 542 540 543 541 inject_token(env, sm.input_store, token) 544 542 545 543 # Run simulation 546 544 env.run(until=100) 547 545 548 - # Verify cell is in valid state 549 - cell = sm.cells[token.target] 546 + # Verify cell is in valid state and specific transitions per op type 547 + cell = sm.cells[token.addr] 550 548 assert cell.pres in (Presence.EMPTY, Presence.RESERVED, Presence.FULL, Presence.WAITING) 551 549 550 + # Verify specific state transitions per operation type 551 + if token.op == MemOp.WRITE: 552 + # WRITE should set cell to FULL 553 + assert cell.pres == Presence.FULL 554 + assert cell.data_l == token.data 555 + elif token.op == MemOp.READ: 556 + # READ on empty cell should set to WAITING 557 + if cell.pres == Presence.WAITING: 558 + assert sm.deferred_read is not None 559 + else: 560 + assert cell.pres in (Presence.EMPTY, Presence.FULL) 561 + elif token.op == MemOp.CLEAR: 562 + # CLEAR should set to EMPTY 563 + assert cell.pres == Presence.EMPTY 564 + elif token.op == MemOp.ALLOC: 565 + # ALLOC on EMPTY should set to RESERVED 566 + assert cell.pres == Presence.RESERVED 567 + elif token.op in (MemOp.RD_INC, MemOp.RD_DEC): 568 + # Atomic ops on FULL should stay FULL with modified data 569 + assert cell.pres == Presence.FULL 570 + elif token.op == MemOp.CMP_SW: 571 + # CMP_SW on FULL should stay FULL (data may change) 572 + assert cell.pres == Presence.FULL 573 + 552 574 553 575 class TestWriteAlwaysSetsDataL: 554 576 """Property-based test: WRITE always sets data_l to the written value.""" ··· 566 588 env.run(until=100) 567 589 568 590 # Verify data_l is set to token.data 569 - assert sm.cells[token.target].data_l == token.data 570 - assert sm.cells[token.target].pres == Presence.FULL 591 + assert sm.cells[token.addr].data_l == token.data 592 + assert sm.cells[token.addr].pres == Presence.FULL 593 + 594 + 595 + class TestWriteReadRoundtrip: 596 + """Property-based test: WRITE→READ roundtrip always returns written value.""" 597 + 598 + @given(sm_token(op=MemOp.WRITE), sm_return_route()) 599 + def test_write_read_roundtrip(self, write_token, read_route): 600 + """WRITE→READ roundtrip always returns written value.""" 601 + env = simpy.Environment() 602 + sm = StructureMemory(env, 0, cell_count=512) 603 + 604 + # Create collector for results 605 + collector = simpy.Store(env) 606 + sm.route_table[0] = collector 607 + 608 + # Inject WRITE 609 + inject_token(env, sm.input_store, write_token) 610 + env.run(until=10) 611 + 612 + # Now READ from same cell with return route 613 + read_token = SMToken( 614 + target=write_token.target, 615 + addr=write_token.addr, 616 + op=MemOp.READ, 617 + flags=None, 618 + data=None, 619 + ret=read_route, 620 + ) 621 + inject_token(env, sm.input_store, read_token) 622 + env.run(until=100) 623 + 624 + # Verify result token has written data 625 + assert len(collector.items) == 1 626 + result = collector.items[0] 627 + assert result.data == write_token.data 628 + 629 + 630 + class TestClearAlwaysEmptifies: 631 + """Property-based test: CLEAR on any state produces EMPTY.""" 632 + 633 + @given(sm_token(op=MemOp.CLEAR)) 634 + def test_clear_on_any_state(self, token): 635 + """CLEAR on any state produces EMPTY.""" 636 + env = simpy.Environment() 637 + sm = StructureMemory(env, 0, cell_count=512) 638 + 639 + # Pre-set cell to a random state (FULL with data) 640 + sm.cells[token.addr].pres = Presence.FULL 641 + sm.cells[token.addr].data_l = 0xBEEF 642 + 643 + # Inject CLEAR 644 + inject_token(env, sm.input_store, token) 645 + env.run(until=100) 646 + 647 + # Verify cell is EMPTY 648 + assert sm.cells[token.addr].pres == Presence.EMPTY 649 + assert sm.cells[token.addr].data_l is None 650 + 651 + 652 + class TestRDIncDecRestores: 653 + """Property-based test: RD_INC then RD_DEC restores original value (mod 16-bit).""" 654 + 655 + @given(uint16, sm_return_route(), sm_return_route()) 656 + def test_rd_inc_dec_restores(self, original_value, return_route_inc, return_route_dec): 657 + """RD_INC then RD_DEC restores original value.""" 658 + env = simpy.Environment() 659 + sm = StructureMemory(env, 0, cell_count=512) 660 + 661 + # Create collector for results 662 + collector = simpy.Store(env) 663 + sm.route_table[0] = collector 664 + 665 + # Set cell to original value 666 + sm.cells[100].pres = Presence.FULL 667 + sm.cells[100].data_l = original_value 668 + 669 + # Inject RD_INC 670 + inc_token = SMToken( 671 + target=0, 672 + addr=100, 673 + op=MemOp.RD_INC, 674 + flags=None, 675 + data=None, 676 + ret=return_route_inc, 677 + ) 678 + inject_token(env, sm.input_store, inc_token) 679 + env.run(until=10) 680 + 681 + # Cell now has (original_value + 1) & 0xFFFF 682 + # Inject RD_DEC 683 + dec_token = SMToken( 684 + target=0, 685 + addr=100, 686 + op=MemOp.RD_DEC, 687 + flags=None, 688 + data=None, 689 + ret=return_route_dec, 690 + ) 691 + inject_token(env, sm.input_store, dec_token) 692 + env.run(until=100) 693 + 694 + # Cell should be back to original_value 695 + assert sm.cells[100].data_l == original_value 696 + 697 + 698 + class TestAtomicOpsOnNonFullRejected: 699 + """Property-based test: Atomic ops on non-FULL cells are rejected.""" 700 + 701 + @given(sm_token(op=MemOp.RD_INC), sm_return_route()) 702 + def test_rd_inc_on_non_full_rejected(self, token, return_route): 703 + """RD_INC on non-FULL cell is rejected.""" 704 + env = simpy.Environment() 705 + sm = StructureMemory(env, 0, cell_count=512) 706 + 707 + # Create collector 708 + collector = simpy.Store(env) 709 + sm.route_table[0] = collector 710 + 711 + # Ensure cell is EMPTY (not FULL) 712 + assert sm.cells[token.addr].pres == Presence.EMPTY 713 + 714 + # Create RD_INC token with return route 715 + inc_token = SMToken( 716 + target=token.target, 717 + addr=token.addr, 718 + op=MemOp.RD_INC, 719 + flags=None, 720 + data=None, 721 + ret=return_route, 722 + ) 723 + 724 + inject_token(env, sm.input_store, inc_token) 725 + env.run(until=100) 726 + 727 + # Verify no result token and cell still EMPTY 728 + assert len(collector.items) == 0 729 + assert sm.cells[token.addr].pres == Presence.EMPTY 730 + 731 + @given(sm_token(op=MemOp.RD_DEC), sm_return_route()) 732 + def test_rd_dec_on_non_full_rejected(self, token, return_route): 733 + """RD_DEC on non-FULL cell is rejected.""" 734 + env = simpy.Environment() 735 + sm = StructureMemory(env, 0, cell_count=512) 736 + 737 + # Create collector 738 + collector = simpy.Store(env) 739 + sm.route_table[0] = collector 740 + 741 + # Ensure cell is EMPTY 742 + assert sm.cells[token.addr].pres == Presence.EMPTY 743 + 744 + # Create RD_DEC token 745 + dec_token = SMToken( 746 + target=token.target, 747 + addr=token.addr, 748 + op=MemOp.RD_DEC, 749 + flags=None, 750 + data=None, 751 + ret=return_route, 752 + ) 753 + 754 + inject_token(env, sm.input_store, dec_token) 755 + env.run(until=100) 756 + 757 + # Verify no result token and cell still EMPTY 758 + assert len(collector.items) == 0 759 + assert sm.cells[token.addr].pres == Presence.EMPTY 760 + 761 + @given(sm_token(op=MemOp.CMP_SW), sm_return_route()) 762 + def test_cmp_sw_on_non_full_rejected(self, token, return_route): 763 + """CMP_SW on non-FULL cell is rejected.""" 764 + env = simpy.Environment() 765 + sm = StructureMemory(env, 0, cell_count=512) 766 + 767 + # Create collector 768 + collector = simpy.Store(env) 769 + sm.route_table[0] = collector 770 + 771 + # Ensure cell is EMPTY 772 + assert sm.cells[token.addr].pres == Presence.EMPTY 773 + 774 + # Create CMP_SW token 775 + cas_token = SMToken( 776 + target=token.target, 777 + addr=token.addr, 778 + op=MemOp.CMP_SW, 779 + flags=0x1234, 780 + data=0x5678, 781 + ret=return_route, 782 + ) 783 + 784 + inject_token(env, sm.input_store, cas_token) 785 + env.run(until=100) 786 + 787 + # Verify no result token and cell still EMPTY 788 + assert len(collector.items) == 0 789 + assert sm.cells[token.addr].pres == Presence.EMPTY 790 + 791 + 792 + class TestBoundaryEdgeCases: 793 + """Test boundary and edge cases for SM operations.""" 794 + 795 + def test_rd_dec_wrapping_0x0000_to_0xffff(self): 796 + """RD_DEC on 0x0000 wraps to 0xFFFF.""" 797 + env = simpy.Environment() 798 + sm = StructureMemory(env, 0, cell_count=512) 799 + 800 + # Set cell 150 to FULL with value 0 801 + sm.cells[150].pres = Presence.FULL 802 + sm.cells[150].data_l = 0x0000 803 + 804 + # Create collector 805 + collector = simpy.Store(env) 806 + sm.route_table[0] = collector 807 + 808 + # Inject RD_DEC 809 + ret_route = CMToken(target=0, offset=16, ctx=0, data=0) 810 + dec_token = SMToken(target=0, addr=150, op=MemOp.RD_DEC, flags=None, data=None, ret=ret_route) 811 + inject_token(env, sm.input_store, dec_token) 812 + 813 + env.run(until=100) 814 + 815 + # Verify cell wrapped to 0xFFFF 816 + assert sm.cells[150].data_l == 0xFFFF 817 + 818 + # Verify result token has old value (0) 819 + assert len(collector.items) == 1 820 + assert collector.items[0].data == 0x0000 821 + 822 + def test_alloc_empty_to_reserved(self): 823 + """ALLOC changes cell from EMPTY to RESERVED.""" 824 + env = simpy.Environment() 825 + sm = StructureMemory(env, 0, cell_count=512) 826 + 827 + # Cell 200 starts EMPTY 828 + assert sm.cells[200].pres == Presence.EMPTY 829 + 830 + # Inject ALLOC 831 + alloc_token = SMToken(target=0, addr=200, op=MemOp.ALLOC, flags=None, data=None, ret=None) 832 + inject_token(env, sm.input_store, alloc_token) 833 + 834 + env.run(until=100) 835 + 836 + # Verify cell is now RESERVED 837 + assert sm.cells[200].pres == Presence.RESERVED 838 + 839 + def test_cmp_sw_on_non_full_cell_rejected(self): 840 + """CMP_SW on non-FULL cell (EMPTY state) is rejected.""" 841 + env = simpy.Environment() 842 + sm = StructureMemory(env, 0, cell_count=512) 843 + 844 + # Create collector 845 + collector = simpy.Store(env) 846 + sm.route_table[0] = collector 847 + 848 + # Cell 210 is EMPTY 849 + assert sm.cells[210].pres == Presence.EMPTY 850 + 851 + # Inject CMP_SW on EMPTY cell 852 + ret_route = CMToken(target=0, offset=17, ctx=0, data=0) 853 + cas_token = SMToken( 854 + target=0, 855 + addr=210, 856 + op=MemOp.CMP_SW, 857 + flags=0x1111, 858 + data=0x2222, 859 + ret=ret_route 860 + ) 861 + inject_token(env, sm.input_store, cas_token) 862 + 863 + env.run(until=100) 864 + 865 + # Verify no result token and cell still EMPTY 866 + assert len(collector.items) == 0 867 + assert sm.cells[210].pres == Presence.EMPTY

+13 -4

tokens.py

··· 1 1 from dataclasses import dataclass 2 2 from enum import Enum, IntEnum 3 - from typing import List, Optional, Tuple 4 - 5 - from simpy import Event 3 + from typing import List, Optional 6 4 7 5 8 6 class Port(IntEnum): ··· 49 47 50 48 @dataclass(frozen=True) 51 49 class SMToken(Token): 50 + addr: int 52 51 op: MemOp 53 52 flags: Optional[int] # TBD 54 53 data: Optional[int] ··· 73 72 @dataclass(frozen=True) 74 73 class CfgToken(SysToken): 75 74 op: CfgOp 76 - data: list # LOAD_INST: list of ALUInst | SMInst; ROUTE_SET: TBD 75 + 76 + 77 + @dataclass(frozen=True) 78 + class LoadInstToken(CfgToken): 79 + instructions: tuple # tuple[ALUInst | SMInst, ...] 80 + 81 + 82 + @dataclass(frozen=True) 83 + class RouteSetToken(CfgToken): 84 + pe_routes: tuple # tuple[int, ...] 85 + sm_routes: tuple # tuple[int, ...]