WebAssembly Opcode Table (TOML)

This repository contains a structured reference of the WebAssembly instruction set and its opcodes, formatted as a TOML file.

Overview

The instructions.toml file lists all instructions as an array-of-tables under the key [[instructions]].

Each entry represents a single instruction (or more precisely, a single opcode) and includes details such as its name, category, binary opcode, immediate arguments, and stack signature.

Examples

[[instructions]]
name = "i32.add"
opcode = 0x6A
category = "numeric"
stack-type = { from = [ { type = "i32" }, { type = "i32" } ], to = [ { type = "i32" } ] }
since = "1"

[[instructions]]
name = "table.fill"
opcode = [0xFC, 17]
category = "table"
immediates = [ { type = "tableidx", name = "x" } ]
stack-type = { from = [ { type = "i32" }, { type-of = "x" }, { type = "i32" } ], to = [] }
feature = "reference-types"
since = "2"

Source of data

Original source of data is ohorn/wasm-opcode-table-toml. Later updated using LLM with spec from WebAssembly Spec.

Rust crate (wasm-opcode-table)

This repository is also the wasm-opcode-table crate — a typed schema and parser for instructions.toml. Use it in tools, validators, or codegen without hand-maintaining opcode tables.

Always available:

• Structs for instructions, opcodes, immediates, and stack signatures (StackEntry, ControlFrame, …)
• parse_instructions_toml to parse any TOML string
• validate_instructions_table for control-frame invariants

Optional feature instructions-toml: embeds instructions.toml from the crate package at compile time via include_str! and exposes instructions() for a lazily parsed &'static InstructionsTable.

Usage

[dependencies]
wasm-opcode-table = { version = "0.1", features = ["instructions-toml"] }

use std::fs;
use wasm_opcode_table::{instructions, parse_instructions_toml, Instruction, StackEntry};

// Load and parse from a file (no embed feature required)
let source = fs::read_to_string("instructions.toml")?;
let table = parse_instructions_toml(&source)?;

// Or use the bundled table (requires `instructions-toml`)
let table = instructions();
let add = table.instructions.iter().find(|i| i.name == "i32.add").unwrap();

Contributing

Feel free to create an issue if you find any mistake, or didn't find an instruction you expected. Or create a pull request directly if you want to fix something.

Please avoid storing editors/llms configs in the repository.

Finding missing instructions (script/diff-spectec.rs)

The rust-script in script/diff-spectec.rs compares opcode keys in instructions.toml against a Spectec grammar file from the WebAssembly spec. Use it to see which rows still need to be added to the table.

# One-time: install rust-script
cargo install rust-script

# Fetch the latest binary-instructions grammar (optional)
curl -sL -o spec.instructions.spectec \
  https://raw.githubusercontent.com/WebAssembly/spec/main/specification/wasm-latest/5.3-binary.instructions.spectec

# Compare against the bundled instructions.toml (default second argument)
./script/diff-spectec.rs script/latest-binary-instr.spectec

# Threads atomics (subopcode is varuint, not a second hex byte — see script/threads-binary-instr.spectec)
./script/diff-spectec.rs script/threads-binary-instr.spectec

Prefixed opcodes in TOML use the subopcode value encoded as a varuint after the prefix byte (e.g. [0xFE, 16] for i32.atomic.load, matching wasmparser), not the raw LEB128 wire bytes. Spectec grammars should write 0xFE 16:Bu32, not 0xFE 0x10.

Example output (truncated):

opcode          spectec                              section
--------------  -----------------------------------  ----------------
0x08            THROW x                              control instructions
[0xFB, 24]      BR_ON_CAST l (REF null_1? ht_1) ...  control instructions

Exit code `2` means there are missing opcodes; `0` means the table covers every rule in the Spectec file.

## Tests
Run tests from the repository root: `cargo test --features instructions-toml`.