Reference R27 min readFrameAssembly v3.1.2
.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 parameterizedflow(p1, ...)+1 compile. validate_semanticsrejects mixed IPv4/IPv6 pairs, illegaltransportoverrides, 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):
| Property | FrameAssembly (This Project) | Flat Assembler (fasm) / FPGA FASM |
|---|---|---|
| What it builds | Layer 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 blocks | host <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 leastip <v4|v6>ormac <colon|hyphen|cisco_dot>. - Every
flow <name>(<p1>[, ...]) { ... }requires parentheses with>= 1parameter and may only reference its formal parameters inside its body. - One
compile { ... }block executes frame statements andflow(...)calls top-to-bottom (1 frame statement = 1 Ethernet frame).
spec_canonical_program.frasm12 lines
// Canonical FrameAssembly v3.1.2: host -> flow(a, b) -> compilehost 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)}Related protocol references:bfd (BFD)ospf (OSPFv2 / OSPFv3)bgp (BGP-4 / 4-Byte ASN)snmp3 (SNMPv3 USM (authPriv))
3. Cross-Layer Semantic Validation (validate_semantics)
Before emitting a single .pcap byte, the compiler enforces cross-layer sanity:
| Check | Compiler Rule |
|---|---|
| MAC-only vs IP hosts | MAC-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 locks | igmp requires IPv4 hosts; ndp and mld require IPv6 hosts. |
| Transport & TCP-only guards | transport 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 bounds | dns/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 Artifact | Valid v3.1.2 Replacement |
|---|---|
demo.fasm / frameassembly compile demo.fasm -o out.pcap | demo.frasm / frameassembly demo.frasm out.pcap |
echo_request, echo_reply, dest_unreach, time_exceeded | echorequest, echoreply, destunreach, timeexceeded |
inner_vlan, sack_perm, ans_ttl, client_hello | innervlan, sackperm, ansttl, clienthello |
host "api.local" (on HTTP) / host_hdr | hosthdr "api.local" |
sport 50000 dport 443 / ack 1001 | srcport 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, ... |