Crate fuel_asm

source ·
Expand description

FuelVM instruction and opcodes representation.

Fuel ASM

build crates.io docs discord

Instruction set for the FuelVM.

Compile features

  • std: Unless set, the crate will link to the core-crate instead of the std-crate. More info here.
  • serde: Add support for serde for the types exposed by this crate.

Example

use fuel_asm::*;

// A sample program to perform ecrecover
let program = vec![
    op::move_(0x10, 0x01),     // set r[0x10] := $one
    op::slli(0x20, 0x10, 5),   // set r[0x20] := `r[0x10] << 5 == 32`
    op::slli(0x21, 0x10, 6),   // set r[0x21] := `r[0x10] << 6 == 64`
    op::aloc(0x21),            // alloc `r[0x21] == 64` to the heap
    op::addi(0x10, 0x07, 1),   // set r[0x10] := `$hp + 1` (allocated heap)
    op::move_(0x11, 0x04),     // set r[0x11] := $ssp
    op::add(0x12, 0x04, 0x20), // set r[0x12] := `$ssp + r[0x20]`
    op::ecr(0x10, 0x11, 0x12), // recover public key in memory[r[0x10], 64]
    op::ret(0x01),             // return `1`
];

// Convert program to bytes representation
let bytes: Vec<u8> = program.iter().copied().collect();

// A program can be reconstructed from an iterator of bytes
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_bytes(bytes).collect();
assert_eq!(program, restored.unwrap());

// Every instruction can be described as `u32` big-endian bytes
let halfwords: Vec<u32> = program.iter().copied().collect();
let bytes = halfwords.iter().copied().map(u32::to_be_bytes).flatten();
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_bytes(bytes).collect();
assert_eq!(program, restored.unwrap());

// We can also reconstruct the instructions individually
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_u32s(halfwords).collect();
assert_eq!(program, restored.unwrap());

// An instruction is composed by the opcode representation, register IDs and immediate value.
let instruction = program[1];
assert_eq!(instruction.opcode(), Opcode::SLLI);
let slli = match instruction {
    Instruction::SLLI(slli) => slli,
    _ => panic!("unexpected instruction"),
};
let (ra, rb, imm) = slli.unpack();
assert_eq!(u8::from(ra), 0x20);
assert_eq!(u8::from(rb), 0x10);
assert_eq!(u32::from(imm), 5);

Re-exports

  • pub use args::GMArgs;
  • pub use args::GTFArgs;

Modules

  • macros
    The impl_instructions! macro
  • op
    Definitions and implementations for each unique instruction type, one for each unique Opcode variant.

Structs

  • Flags
    Possible values for the FLAG instruction. See https://github.com/FuelLabs/fuel-specs/blob/master/src/vm/index.md#flags
  • Imm06
    Represents a 6-bit immediate value, guaranteed to be masked by construction.
  • Imm12
    Represents a 12-bit immediate value, guaranteed to be masked by construction.
  • Imm18
    Represents a 18-bit immediate value, guaranteed to be masked by construction.
  • Imm24
    Represents a 24-bit immediate value, guaranteed to be masked by construction.
  • InstructionResult
    Describe a panic reason with the instruction that generated it
  • InvalidOpcode
    Failed to parse a u8 as a valid or non-reserved opcode.
  • RegId
    Represents a 6-bit register ID, guaranteed to be masked by construction.

Enums

  • Instruction
    Representation of a single instruction for the interpreter.
  • Opcode
    Solely the opcode portion of an instruction represented as a single byte.
  • PanicReason
    Panic reason representation for the interpreter.

Traits

Functions

  • from_bytes
    Given an iterator yielding bytes, produces an iterator yielding Instructions.
  • from_u32s
    Given an iterator yielding u32s (i.e. “half words” or “raw instructions”), produces an iterator yielding Instructions.
  • raw_instructions_from_word
    Produce two raw instructions from a word’s hi and lo parts.

Type Definitions