Reference R27 min readFrameAssembly v3.1.2
llms-full.txt

.frasm Language Spec, Validation Rules & v3.1 Upgrade Map

Formal lexical rules, text/vnd.frameassembly MIME registration, cross-layer semantic checks, and upgrading old v1/v2 .fasm snippets to v3.1.2.

TL;DR — What Matters Here
  • Extension is strictly .frasm (text/vnd.frameassembly, UTF-8) — never .fasm (x86 Flat Assembler / FPGA bitstreams).
  • Program layout: >= 1 host + optional parameterized flow(p1, ...) + 1 compile.
  • validate_semantics rejects mixed IPv4/IPv6 pairs, illegal transport overrides, and out-of-range fields before a single byte is written.

1. .frasm vs. .fasm (Why the r Matters)

Early versions of this hobby project used .fasm, which collided head-on with Tomasz Grysztar’s venerable x86 Flat Assembler (fasm) and FPGA bitstream files. Since v3.0, FrameAssembly lives exclusively at .frasm (text/vnd.frameassembly):

PropertyFrameAssembly (This Project)Flat Assembler (fasm) / FPGA FASM
What it buildsLayer 2-7 network packet captures (.frasm <-> .pcap / .pcapng)x86 / x86-64 CPU machine code (or SymbiFlow FPGA bitstreams)
Extension & MIME.frasm (text/vnd.frameassembly, UTF-8).asm, .fasm, .inc
Line comments// double-slash only; semicolon (x86 fasm) or # hash (FPGA FASM)
Top-level blockshost <id> { ... } -> flow <name>(...) { ... } -> compile { ... }CPU mnemonics (mov, syscall, section)

2. Lexical & Structural Invariants

No significant whitespace, no semicolons, and zero underscore roulette:

  • Built-in tokens (81 protocol names, modifiers, flags, and ns/us/ms/s/m) match ^[a-z0-9]+$ — lowercase letters + digits only.
  • User identifiers (host, flow, formal parameters) match [a-zA-Z_][a-zA-Z0-9_]*(-[a-zA-Z0-9_]+)* (e.g. fw-dmz-01, Core_SW_1), stopping cleanly before -> or <-.
  • Strings use double quotes "..." (\r, \n, \t, \\, \", \xHH, \uXXXX). Hex strings (hexpayload, iv, icv, engineid) accept even-length octets with optional spaces or colons.
  • Every host <id> { ... } requires at least ip <v4|v6> or mac <colon|hyphen|cisco_dot>.
  • Every flow <name>(<p1>[, ...]) { ... } requires parentheses with >= 1 parameter and may only reference its formal parameters inside its body.
  • One compile { ... } block executes frame statements and flow(...) calls top-to-bottom (1 frame statement = 1 Ethernet frame).
spec_canonical_program.frasm12 lines
Open in Playground
// Canonical FrameAssembly v3.1.2: host -> flow(a, b) -> compile
host leaf-sw-01 { ip 10.100.0.1 mac 001c.7300.0001 }
host spine-sw-1 { ip 10.100.0.2 mac 001c.7300.0002 }
flow bfd_up(a, b) {
a -> b bfd state 3 diag 0 mult 3 mydisc 0x1001 yourdisc 0x2002 mintx 50000 minrx 50000 dscp 48 wait 500us
a <- b bfd state 3 diag 0 mult 3 mydisc 0x2002 yourdisc 0x1001 mintx 50000 minrx 50000 dscp 48
}
compile {
bfd_up(leaf-sw-01, spine-sw-1)
}

3. Cross-Layer Semantic Validation (validate_semantics)

Before emitting a single .pcap byte, the compiler enforces cross-layer sanity:

CheckCompiler Rule
MAC-only vs IP hostsMAC-only hosts are valid *only* on the 8 L2 protocols (arp, vlan, qinq, lldp, stp, lacp, eapol, mpls). All 73 L3-L7 protocols require matching-family IPs.
IP-family protocol locksigmp requires IPv4 hosts; ndp and mld require IPv6 hosts.
Transport & TCP-only guardstransport tcp|udp works *only* on the 9 dual-L4 protocols; TCP flags/options (syn, acknum, mss, wscale, sackperm, tsval, tsecr) fail validation on non-TCP frames.
Field & RFC boundsdns/mdns label <= 63B & total <= 253B · snmp3 engineid even-length hex · hsrp hellotime/holdtime 0..255 · max one mpls shim per frame · payload vs hexpayload mutually exclusive.

4. Old v1 / v2 Snippets -> v3.1.2 Upgrade Map

If an older blog post or unprimed LLM hands you v1/v2 syntax, swap these straight across:

Old v1 / v2 ArtifactValid v3.1.2 Replacement
demo.fasm / frameassembly compile demo.fasm -o out.pcapdemo.frasm / frameassembly demo.frasm out.pcap
echo_request, echo_reply, dest_unreach, time_exceededechorequest, echoreply, destunreach, timeexceeded
inner_vlan, sack_perm, ans_ttl, client_helloinnervlan, sackperm, ansttl, clienthello
host "api.local" (on HTTP) / host_hdrhosthdr "api.local"
sport 50000 dport 443 / ack 1001srcport 50000 dstport 443 / ack acknum 1001
loop 3 { ... } or parameterless flow demo { ... }flow demo(a, b) { ... } called inside compile { ... }
host_1 (old reverse output)host1, host2, ...