Wasm Parser
The /lib/wasm/parser.hoon library converts Wasm bytecode into UrWasm's Hoon types defined in +wasm-sur, which is nested in the imported /sur/wasm/lia.hoon file. This library implements parsing rules that follow the WebAssembly Core Specification binary format.
+parser
|%
++ parser
=/ sur wasm-sur
|%
:: ...
--
--Parser core. Exposes the nested +wasm-sur namespace as .sur.
+main
++ main
|= wasm=octs
=, sur
^- module
=| out=module
=/ bytes=tape (trip q.wasm)
:: add trailing zeros
=. bytes
%+ weld bytes
^- tape
(reap (sub p.wasm (lent bytes)) '\00')
(scan bytes module:r)Main parsing function that takes a Wasm binary as $octs and returns a parsed $module. Extends the octet stream with trailing zeros to ensure proper parsing then applies the +module:r parsing rule.
+r
Parsing rule core. Parsing rules often use the same name as the types in /sur/wasm.hoon, e.g. +num-type:r is the parsing rule that produces a $num-type:sur.
+womp
Returns a mold of the product of the given $rule.
+bild
Connects an $edge (parsing output) with a rule and a rule-producing gate, returning the result of the rule produced by slamming the gate with the result of the first rule.
Used for conditional parsing based on previously parsed values.
+bonk
Rule modifier. Applies two rules to a $nail, failing if either rule fails to parse or if the rules return different continuations. Returns the result of the second rule otherwise.
+feel
Rule modifier. Tests equality of the parsing result with a given noun. Only succeeds if the parsed value .p.u.q.vex exactly matches the expected value .a.
+u-n
Parse @ integer with bitwidth as an atom. Handles both single-byte and multi-byte cases recursively.
+s-n
Parse @s integer with bitwidth . Implements WebAssembly's signed LEB128 integer encoding with proper sign extension handling for positive and negative integers.
+u32
Parse 32-bit unsigned integer.
+u64
Parse 64-bit unsigned integer.
+f32
Parse 32-bit float.
Reads exactly 4 bytes and reconstructs them into a @rs atom.
+f64
Parse 64-bit float.
Reads exactly 8 bytes and reconstructs them into a @rd atom.
+vec
Parses a Wasm vector.
First parses a u32 length, then parses exactly that many instances of the given rule. This is the standard WebAssembly encoding for variable-length sequences.
+name
Parse Wasm name (UTF-8 string).
Uses +vec to get the length and bytes, then converts the parsed $rule to a @t.
+vec-u32
Parse vector of 32-bit unsigned integers.
+num-type
Parse Wasm number type.
Maps binary opcodes to $num-type values.
+vec-type
Parse Wasm vector type.
+ref-type
Parse Wasm reference type.
Maps binary opcodes to $ref-type values.
+valtype
Parse Wasm value type.
Homogenizes results of +num-type:r, +vec-type:r, and +ref-type:r parsers into $valtypes.
+func-type
Parse Wasm function.
Expects the function type opcode \60, followed by parameter types and result types as vectors. (See $func-type.)
+limits
Parse Wasm memory/table limits.
Either minimum only (%flor) or minimum and maximum (%ceil).
Instruction and Expression Parsing Rules
+expr
Parse Wasm expression as a sequence of instructions terminated by an +end opcode.
+expr-pair
Parse a pair of $expressions for +if statements.
First expression (true branch), followed by optional +else and second expression (false branch).
+end
Parse Wasm end opcode (0x0B).
+else
Parse Wasm else opcode (0x05).
+const-i32
Parse Wasm i32.const opcode (0x41).
+const-i64
Parse Wasm i64.const opcode (0x42).
+const-f32
Parse Wasm f32.const opcode (0x43).
+const-f64
Parse Wasm f64.const opcode (0x44).
+block-op
Parse Wasm block opcode (0x02).
+loop-op
Parse Wasm loop opcode (0x03).
+if-op
Parse Wasm if opcode (0x04).
+form-ranges
Helper function that converts a list of sorted integers into a list of ranges (?(@ [@ @])).
+instr
Main instruction parser. Uses +stew parser to switch on the given text to the appropriate parser.
+select-vec
Parses a typed select instruction with explicit value types.
+br-table
Parse Wasm br_table (branch table) expression with vector of labels and default label.
+instr-zero
Parse instructions with zero arguments by looking up the opcode in the opcode map.
+block
Parse Wasm block expression with block type and body expression.
+loop
Parse Wasm loop expression with block type and body expression.
+if
Parse Wasm if expression with block type and true/false expression pair.
+block-type
Parse Wasm $block-type.
Handler Functions
+handle-one-arg-i32
Handle Wasm instructions that take one 32-bit argument.
Maps opcodes to their corresponding $instruction representations.
+handle-two-args-i32
Handle Wasm instructions that take two 32-bit immediate arguments.
+handle-br-table
Handle Wasm br_table expression (switch statement) by constructing the list of branches with a default index.
+handle-block
Handle Wasm block expression.
+get-valtype
Map byte values to value types for block type parsing.
Map opcodes to value types to construct $valtypes
+handle-loop
Handle Wasm loop expression.
+handle-if
Handle Wasm if expression construction with true and false branches.
+handle-const-f64
Handle Wasm f64.const expression.
+handle-const-f32
Handle Wasm f32.const expression.
+handle-const-i32
Handle Wasm i32.const expression with signed to unsigned conversion.
+handle-const-i64
Handle Wasm i64.const expression with signed to unsigned conversion.
+fc
0xFC extension parser for saturating truncation instructions.
Parser for Wasm instructions prefixed with 0xFC, which includes memory and table operations.
+zero-args
Parse extended instructions with zero additional arguments.
+one-arg
Parse extended instructions with one additional argument.
+two-args
Parse extended instructions with two additional arguments.
+handle-zero
Handle saturating truncation instructions (opcodes 0-7).
+handle-one
Handle extended instructions with one argument.
+handle-two
Handle extended instructions with two arguments.
+fd
0xFD extension parser for SIMD (vector) instructions.
Parser for Wasm SIMD instructions.
+memarg
Handle SIMD memory instructions (vector loads/stores with memory arguments).
+mem-lane
Handle SIMD lane-specific memory operations.
+const
Handle SIMD constant vectors (v128.const).
+shuffle
Handle SIMD shuffle operations with lane indices.
+lane
Handle SIMD lane extract/replace operations.
Section Parsers
+type-section
Parse Wasm module $type-section containing function signatures.
+import-section
Parse Wasm module $import-section containing module dependencies.
+import
Parse individual module $import entry with module name, import name, and description.
+import-desc
Parse module import description (function, table, memory, or global).
+import-func
Parse function import with type index.
+import-tabl
Parse table import with reference type and $limits.
+import-memo
Parse memory import with size limits.
+import-glob
Parse global import with value type and mutability.
+con-var
Parse constant/variable mutability flag.
+function-section
Parse Wasm module $function-section with type indices.
+table-section
Parse Wasm module $table-section.
+table
Parse table definition with reference type and size limits.
+memory-section
Parse Wasm module $memory-section with size limits.
+global-section
Parse Wasm module $global-section.
+global
Parse $global variable with type, mutability, and initial value.
+const-expr
Parse constant $expression (single constant instruction followed by end).
+const-instr
Parse $instructions that can appear in constant instructions.
+export-section
Parse Wasm export section.
+export
Parse export entry with name and description.
+start-section
Parse Wasm module $start-section with start function index.
+elem-section
Parse Wasm module $elem-section for table initialization.
+elem
Parse element segment in one of eight different formats. Each format has different combinations of:
Active/passive/declarative mode.
Table index specification.
Element type annotation.
Initialization
$expressionvs$functionindices.
+elem-kind
Parse element kind (currently only function references references supported).
+elem-0
Parse active element segment with implicit table 0 and function indices.
+elem-1
Parse passive element segment with element kind and function indices.
+elem-2
Parse active element segment with explicit table index, offset expression, element kind, and function indices.
+elem-3
Parse declarative element segment with element kind and function indices.
+elem-4
Parse active element segment with implicit table 0 and initialization expressions.
+elem-5
Parse passive element segment with reference type and initialization expressions.
+elem-6
Parse active element segment with explicit table index, offset expression, reference type, and initialization expressions.
+elem-7
Parse declarative element segment with reference type and initialization expressions.
+handle-elem-0
Convert parsed elem-0 data into standard $elem format with active mode, table 0, and function references.
+handle-elem-1
Convert parsed elem-1 data into standard $elem format with passive mode and function references.
+handle-elem-2
Convert parsed elem-2 data into standard $elem format with active mode, explicit table index, and function references.
+handle-elem-3
Convert parsed elem-3 data into standard $elem format with declarative mode and function references.
+handle-elem-4
Convert parsed elem-4 data into standard $elem format with active mode, table 0, and expression-based initialization.
+handle-elem-5
Convert parsed elem-5 data into standard $elem format with passive mode and expression-based initialization.
+handle-elem-6
Convert parsed elem-6 data into standard $elem format with active mode, explicit table index, and expression-based initialization.
+handle-elem-7
Convert parsed elem-7 data into standard $elem format with declarative mode and expression-based initialization.
+code-section
Parse Wasm module $code-section containing function implementations.
+code
Parse code entry with size validation and function body.
+func
Parse function implementation with local variable declarations and body.
+locals
Parse local variable declaration (count and $valtype).
+handle-locals
Expand compressed local variable declarations into full list.
+data-section
Parse Wasm module $data-section section for memory initialization.
+data
Parse $data segment in active or passive mode with initialization data.
+to-octs
Convert tape to $octs format.
+datacnt-section
Parse Wasm module data count section.
+module
Parse complete Wasm $module with +magic number, +version, and sections.
+module-contents
Parse Wasm $module contents.
+check
Check for optional Wasm module sections, providing default values for missing sections.
+customs
Parse custom Wasm module sections (ignored during parsing).
+magic
Parse Wasm magic number (0x00, 0x61, 0x73, 0x6D) which identifies this file as a Wasm module.
+version
Parse Wasm version number (currently version 1).
+op-map
Maps single-byte Wasm opcodes to their corresponding $instruction representations.
+simd-map
Maps SIMD instruction opcodes to their corresponding vector instruction representations. Includes helper functions for different categories of vector operations.
Last updated