Flash Assembler — Architecture

InputSource

LexerScanner

SyntaxParser

SyntaxAST

SemanticsAnalyzer

SemanticsScheduler

CodegenEncoder

OutputArtifact

Press / to focus · Esc to clear

Front-End — Syntax Module

📄

Source Code

.flash files · entry point

▾

Flash programs use a hardware-oriented assembly language with struct definitions, memory-mapped variables, conditional execution, and instruction handlers.

Language Constructs

Construct	Syntax	Purpose
`import`	`import "file.flash"`	Transitive module inclusion (deduplicated)
`const`	`const X = 8'd42`	Named immediate with explicit bit width
`var`	`var foo = meta[7:0]`	Named memory-mapped variable
`struct`	`struct S { f: 8; }`	Bit-precise structure (no implicit padding)
`union`	`union U { a: 8; b: 16; }`	Overlapping fields at same offset
`enum`	`enum E { A, B=3 }`	Named constants with auto-increment
`cond`	`cond c = f & 0xF == 0x1`	4-bit condition for conditional execution
`handler`	`handler H { mov … }`	Block of grouped instructions
`flow`	`flow { mask … match … action H }`	Packet classification → handler mapping
`target`	`target S3`	Hardware target declaration
`flavour`	`flavour PTA_ACTION`	Hardware sub-configuration

Immediate Formats (Verilog-style)

8'd42 — 8-bit decimal
16'hFFFF — 16-bit hex
4'b1010 — 4-bit binary
0xFF — auto-sized hex
Underscores for readability: 0xFF_FF

Memory Selectors

msgcsmetaout

Three addressing modes: range meta[7:0], base+count cs[0,16], typed meta @ 0 : MyStruct.

📁

Workspace

mod.rs · multi-file management

▾

Collects all source files via breadth-first import traversal, deduplicating by canonical path, to produce a sequence of CompilationUnits.

Key Structs

Struct	Fields	Role
`Workspace`	units, known_paths, report	Root container — all parsed files
`CompilationUnit`	path, rep_path, program, report	Single parsed file
`WorkItem`	canonical_path, rep_path	BFS queue entry

Import Resolution

Start with seed file path from CLI
Canonicalize path, parse into AST
Extract import declarations
Resolve relative to importing file's directory
Skip already-processed paths (dedup by canonical path)
BFS until all transitive imports collected

Handles diamond imports correctly — if A→B and A→C both import D, file D is parsed only once.

🔍

Scanner

scanner.rs · tokenization

▾

Character-by-character lexer producing typed tokens with source spans. Recognizes 16 keywords, multi-radix numbers, strings, comments, and operators.

Token Categories (47 types)

Keywords

condconsthandlerif nextimportstructunion varflavourtargetflow maskmatchactionenum

Operators & Punctuation

&@::: ,--.= ==#-; /' ( ){ }[ ]

Values

WordNumberString GlyphCommentNewlineEOF

Design Decisions

Newline-sensitive — newlines are tokens, significant in handler bodies
Multi-radix — 0x hex, 0o octal, 0b binary, decimal; underscore separators
SourceReader — tracks line/col with single-char lookahead
Error recovery — skips to newline or } on error

🌳

Parser

parser.rs · recursive descent

▾

Hand-written recursive descent parser with single-token lookahead, newline sensitivity, and error recovery. Transforms the token stream into a typed AST.

Parser State

Field	Type	Purpose
`scanner`	Scanner	Token source
`ignore_newlines`	bool	Off in structs, on in handlers
`buffered_token`	Option<Token>	Single-token lookahead
`report`	Vec<ReportItem>	Parse errors and warnings

Key Grammar Rules

Function	Grammar
`parse_program()`	`program_item*`
`parse_handler_def()`	`handler IDENT { handler_item* }`
`parse_instruction()`	`OPCODE operand* (if condition)?`
`parse_struct_def()`	`struct IDENT? { member* }`
`parse_cond_expr()`	`base & mask == value`
`parse_immediate()`	`size'radix_digits`
`parse_flow_decl()`	`flow { mask M match V action A }`
`parse_enum_def()`	`enum IDENT { variant* }`

Error Recovery

recover_to_next_program_item() — skip to next keyword
recover_past_current_instruction() — skip to newline or brace

📐

Abstract Syntax Tree

ast.rs · 11 node types

▾

Strongly-typed tree representing the full program. Every node carries a source Span for precise error messages. Supports 11 top-level declaration types.

ProgramItem Variants

Variant	Struct	Description
`ConstDef`	name, value	Named constant with explicit bit width
`EnumDef`	name, variants[]	Enum with auto-incrementing values
`CondDef`	name, value	Symbolic condition expression
`ObjectDef`	name, value	Memory-mapped variable
`StructDef`	name?, members[]	Named or anonymous struct
`UnionDef`	name?, members[]	Named or anonymous union
`HandlerDef`	name, items[]	Instruction handler block
`FlowDecl`	mask, match, action	Packet classification rule
`ImportDecl`	path	File import
`TargetDecl`	kind	Hardware target (S3)
`FlavourDecl`	flavour	Hardware sub-configuration

Value Types

IdentIntImmediate PathAddrExprCondExpr

Instruction = opcode + operands (Op::Addr, Op::Ref, Op::Imm) + optional condition. Handler items include GroupBreak (--) and Next boundaries.

Middle — Semantics Module

🧠

Semantic Analyzer

model.rs · 7-stage pipeline

▾

Builds the intermediate representation through 7 sequential analysis stages. Validates correctness at each step and builds a symbol table of constants, types, objects, conditions, and handlers.

Model Fields

Field	Type	Purpose
`constants`	HashMap<String, Definition<Imm>>	Named constants & enum values
`layouts`	HashMap<String, ObjectLayout>	Struct/union memory layouts
`objects`	HashMap<String, Definition<Object>>	Memory-mapped variables
`conditions`	HashMap<String, Definition<Condition>>	Symbolic conditions
`handlers`	HashMap<String, Definition<Handler>>	Compiled handlers with groups
`flows`	Vec<Flow>	Packet classification rules
`target`	&'static Target	Hardware configuration
`flavour`	Option<FlavourDecl>	Selected hardware flavour

7 Analysis Stages

#	Stage	Action
1	`process_constant_definitions`	Evaluate const declarations, check duplicates
2	`process_enum_definitions`	Expand enums to qualified constants (`E::V`)
3	`process_type_definitions`	Compute recursive struct/union layouts, detect cycles
4	`process_object_definitions`	Create objects with layout, check memory overlap
5	`process_condition_definitions`	Validate: 4-bit aligned, 4-bit wide, meta-only
6	`process_handlers`	Validate instructions, resolve operands, group & schedule
7	`process_flows`	Validate handler refs, resolve mask/match values

Every model artifact is wrapped in Definition<T> adding name, source_file, and span for precise error messages.

📋

Instruction Scheduler

model.rs · grouping & dependencies

▾

Organizes instructions into execution groups respecting hardware constraints. Builds a dependency graph, performs list scheduling, and pads groups with NOPs.

Grouping Modes

Mode	Trigger	Mechanism
Manual	`--` separators in source	User places group boundaries explicitly
Automatic	No separators	Compiler builds dependency graph and schedules

Dependency Graph

Nodes = instructions. Edges = RAW (Read-After-Write) data dependencies detected by checking if source operands overlap destinations via bit-range intersection.

Constraints

Max 8 ALU instructions per group
Max 7 custom instructions per group
Max 1 load/store per group
Load latency: 5 groups between load and consumer
NOP padding: groups padded to exactly 8 ALU slots
CMP destinations must be exactly 3 bits
All operand widths ≤ 64 bits

💾

Memory Model

memory.rs · types, chunks, overlap

▾

Defines four memory regions, enforces alignment constraints, and uses an IntervalMap for efficient overlap detection between objects.

Memory Regions

Type	Selector	Align	Purpose
Message	`msg`	8-bit	Input packet buffer
CS	`cs`	8-bit	Context store
Meta	`meta`	4-bit	HW + SW metadata
Output	`out`	4-bit	Output vector

Key Structures

Struct	Purpose
`Chunk`	Contiguous bit range: mem_type + low_bit + high_bit
`Memory`	Full descriptor: type + bit_size + access_align
`IntervalMap<T>`	Sorted intervals with binary-search overlap detection
`ObjectLayout`	Recursive struct layout with drill-down into nested fields

📝

Code IR

code.rs · instruction model

▾

Intermediate representation: Handler → InstructionGroup → Instruction → Arg, ready for binary encoding by the code generator.

Hierarchy

Handler ├── name: String └── instr_groups: Vec<InstructionGroup> ├── alu_instrs: Vec<Definition<Instruction>> ├── custom_instrs: Vec<…> └── load_instrs: Vec<…> ├── operation: &'static target::Instruction ├── args: Vec<Definition<Arg>> ├── mem_refs: Vec<Definition<Arg>> └── condition: Option<Condition>

Operand Types

Variant	Content	Example
`Arg::Addr(Chunk)`	Memory range	`meta[7:0]`
`Arg::Imm(Imm)`	Sized immediate	`8'd42`

Condition { base: Chunk, mask: u8, match_value: u8 } — 4-bit condition from meta memory for conditional execution.

Back-End — Codegen Module

⚙️

S3 Encoder

encoder.rs · binary encoding

▾

Transforms the IR into binary S3 machine code. Encodes each instruction group as a 2-byte descriptor header followed by packed ALU and load/store instruction bytes.

Encoding Pipeline

encode(handler) — iterate instruction groups
encode_instr_group() — write 2B descriptor + instruction bytes
alu_instruction_encoding() → 14-byte encoding
load/store_instruction_encoding() → 10-byte encoding
condition_encoding() → 14-bit condition
process_flows() → TCAM entries
write_combined_json() → JSON output with metadata

ALU Instruction (14 bytes = 112 bits)

Type4b

Func6b

Src022b

Src122b

Dest22b

Src222b

Cond14b

Load / Store (10 bytes = 80 bits)

Type4b

Rsvd6b

Base16b

Offset16b

Data16b

Cond14b

Pad8b

Composer Utility

Composer::paste(bits, count, low_bit) — places arbitrary bit-width fields at arbitrary offsets into a byte array, handling cross-byte alignment. The core primitive for all encoding.

🔢

Operand Encoding

encoder.rs · SrcOpEncoding

▾

Each ALU instruction has 3 source operand slots (22 bits each). Memory addresses and immediates are encoded, with large immediates spanning multiple slots.

Operand Slot (22 bits)

DataType4b

Size6b

Addr/Val12b

Data Type Codes

Code	Type
`0b0000`	Message
`0b0001`	Context Store
`0b0010`	Metadata
`0b0100`	Immediate
`0b0111`	Output
`0b1000`	Sequence (extended immediate)

Immediate Extension

≤12 bits — 1 slot
13–24 bits — 2 slots (src0 = low 12 + type, src1 = high 12)
25–36 bits — 3 slots (all three used)
>36 bits — error, exceeds capacity

📦

Artifact & Output

artifact.rs · compiled output

▾

Artifact is a dictionary of compiled handler bytecodes. The encoder also produces a JSON file with instruction memory, TCAM configs, and metadata.

Artifact Structure

Artifact └── handlers: HashMap<String, Vec<u8>> ├── "handler_A" → [0x80, 0x01, …] └── "handler_B" → [0x80, 0x03, …]

JSON Output

{ "metadata": { "version", "timestamp", "signature" }, "target": { "flavour": { "instructions": [{ flow_name, index, mem_group, alu_instructions, ls_instruction }], "tcam": [{ index, mask, match, num_inst_grp, inst_mem_addr }] } } }

TCAM Entry (CSR)

Packs to 45-byte (353-bit) register: valid[352] | mask[351:184] | match[183:16] | num_groups[15:8] | mem_addr[7:0].

🔧

Encoding Constants

constants.rs · bit fields

▾

All magic numbers for S3 encoding: instruction type codes, field widths, bit positions, group descriptor flags, and ALU function codes.

Instruction Types

Constant	Value	Meaning
`INSTR_TYPE_ALU`	`0b0000`	ALU instruction
`INSTR_TYPE_LOAD`	`0b0010`	Memory load
`INSTR_TYPE_STORE`	`0b0011`	Memory store
`INSTR_TYPE_CUSTOM`	`0b0100`	Custom instruction

Group Descriptor (16 bits)

Rsvd5

ALU#4

Cust#3

LS1

V = Valid, L = Last group, H = Halt. ALU# = count, Cust# = custom count, LS = load/store present.

Key Sizes

Constant	Value
`ALU_INSTRUCTION_SIZE`	14 bytes
`LS_INSTRUCTION_SIZE`	10 bytes
`ALU_OPERAND_FIELD_WIDTH`	22 bits
`LOAD_LATENCY_GROUPS`	5 cycles

Target Hardware & Infrastructure

🎯

S3 Target

target.rs · hardware ISA

▾

Defines the S3 flow processor's instruction set (19 ALU + 2 LS), memory layout, constraints, and 8 hardware flavours from JSON configuration.

Instruction Set (21 instructions)

Category	Opcodes
ALU — Data	`mov` `movm` `add` `adds` `sub` `subs` `nop`
ALU — Logic	`or` `and` `xor` `not`
ALU — Shift	`sll` `srl`
ALU — Compare	`cmp` `cmpm` `rngcmp` `wrngcmp` `drngcmp` `sumcmp`
Load / Store	`load` `store`

Hardware Constraints

Constraint	Value
Max ALU / group	8
Max custom / group	7
Max load-store / group	1
Max operand width	64 bits
Condition width	4 bits
Issue slots	8

8 Flavours

Flavour	Cores	TCAM	Instr Mem	Key Feature
`SGE_KEYGEN`	4	32	128	1 KB HW metadata
`SGE_ACTION`	4	96	256	848-bit output
`PTA_KEYGEN`	4	16	96	Key-as-output
`PTA_ACTION`	4	32	128	Data memory access
`PTA_ACU_KEYGEN`	2	16	96	Reduced cores
`PTA_ACU_ACTION`	2	24	128	720-bit output
`RNIC_KEYGEN`	1	32	32	Custom instructions
`RNIC_ACTION`	1	64	64	TCAM index output

🧰

Common Infrastructure

common.rs · spans, errors

▾

Foundation types shared across all compiler phases: source locations, spans, diagnostic notes, and the three-level reporting system.

Core Types

Type	Fields	Purpose
`Location`	line, col (u32)	1-based source position
`Span`	start, end	Range of source characters
`Spanned`	trait	Anything with source location
`Note`	span, message	Diagnostic with position
`ReportItem`	Error / Warning / Info	Classified diagnostic
`Either<T,U>`	Left, Right	Sum type

Each stage collects ReportItems. After each stage, the report is printed. Any Error halts compilation. Format: file:line:col: error: message.

🚀

Driver

main.rs + lib.rs · orchestration

▾

Entry point creates a Workspace from the CLI argument. lib.rs orchestrates the full pipeline: analyze() builds the Model, then encode() produces the Artifact.

Execution Flow

main.rs 1. Parse CLI args → filename 2. Workspace::new(filename) → parse all files 3. Check workspace errors → exit(1) if any 4. process_workspace(workspace) lib.rs — process_workspace() 1. Print per-unit parse reports 2. analyze(workspace) → Model (7 stages) 3. encode(model) → Artifact + JSON lib.rs — analyze() Model::build_model() then per unit: → process_constants → process_enums → process_types → process_objects → process_conditions → process_handlers → process_flows lib.rs — encode() S3Encoder::new() → encode each handler → process_flows → write_combined_json

The run_analysis_stage! macro wraps each stage: iterates units, calls the stage, checks for errors, prints reports, aborts early if needed.

🔨

Tooling & Build

scripts/ · Makefile · tests/

▾

Supporting ecosystem: C/C++ header migration scripts, Makefile for FunSDK deployment, integration tests, and hardware configuration files.

Migration Scripts

Script	Purpose
`c_header_to_flash.py`	C/C++ structs → Flash (auto union detection, nested deps)
`flash_to_c_header.py`	Flash structs → C/C++ headers

Build (Makefile)

Target	Action
`make`	`cargo build --release`
`make test`	`cargo test`
`make install`	Deploy binary + config to `$SDKDIR/bin/`
`make clean`	`cargo clean`

Integration Tests

Diamond import — A→B→D, A→C→D: D parsed once
Broken import — missing file error handling
Cross-directory — relative path resolution with ../

configs/s3_flavours.json defines all 8 flavour specs: memory widths, TCAM depth, instruction memory, core counts.