Enum witnext::Instruction

pub enum Instruction<'a> {
    GetArg {
        nth: usize,
    },
    I32Const {
        val: i32,
    },
    Bitcasts {
        casts: &'a [Bitcast],
    },
    ConstZero {
        tys: &'a [WasmType],
    },
    I32Load {
        offset: i32,
    },
    I32Load8U {
        offset: i32,
    },
    I32Load8S {
        offset: i32,
    },
    I32Load16U {
        offset: i32,
    },
    I32Load16S {
        offset: i32,
    },
    I64Load {
        offset: i32,
    },
    F32Load {
        offset: i32,
    },
    F64Load {
        offset: i32,
    },
    I32Store {
        offset: i32,
    },
    I32Store8 {
        offset: i32,
    },
    I32Store16 {
        offset: i32,
    },
    I64Store {
        offset: i32,
    },
    F32Store {
        offset: i32,
    },
    F64Store {
        offset: i32,
    },
    I32FromChar,
    I64FromU64,
    I64FromS64,
    I32FromU32,
    I32FromS32,
    I32FromU16,
    I32FromS16,
    I32FromU8,
    I32FromS8,
    I32FromUsize,
    I32FromChar8,
    F32FromIf32,
    F64FromIf64,
    S8FromI32,
    U8FromI32,
    S16FromI32,
    U16FromI32,
    S32FromI32,
    U32FromI32,
    S64FromI64,
    U64FromI64,
    CharFromI32,
    If32FromF32,
    If64FromF64,
    Char8FromI32,
    UsizeFromI32,
    I32FromBorrowedHandle {
        ty: &'a NamedType,
    },
    I32FromOwnedHandle {
        ty: &'a NamedType,
    },
    HandleOwnedFromI32 {
        ty: &'a NamedType,
    },
    HandleBorrowedFromI32 {
        ty: &'a NamedType,
    },
    ListCanonLower {
        element: &'a TypeRef,
        malloc: Option<&'a str>,
    },
    ListLower {
        element: &'a TypeRef,
        malloc: Option<&'a str>,
    },
    ListCanonLift {
        element: &'a TypeRef,
        free: Option<&'a str>,
    },
    ListLift {
        element: &'a TypeRef,
        free: Option<&'a str>,
    },
    IterElem,
    IterBasePointer,
    BufferLowerPtrLen {
        buffer: &'a Buffer,
    },
    BufferLowerHandle {
        buffer: &'a Buffer,
    },
    BufferLiftPtrLen {
        buffer: &'a Buffer,
    },
    BufferLiftHandle {
        buffer: &'a Buffer,
    },
    RecordLower {
        ty: &'a RecordDatatype,
        name: Option<&'a NamedType>,
    },
    RecordLift {
        ty: &'a RecordDatatype,
        name: Option<&'a NamedType>,
    },
    I32FromBitflags {
        ty: &'a RecordDatatype,
        name: &'a NamedType,
    },
    I64FromBitflags {
        ty: &'a RecordDatatype,
        name: &'a NamedType,
    },
    BitflagsFromI32 {
        repr: IntRepr,
        ty: &'a RecordDatatype,
        name: &'a NamedType,
    },
    BitflagsFromI64 {
        repr: IntRepr,
        ty: &'a RecordDatatype,
        name: &'a NamedType,
    },
    VariantPayload,
    VariantLower {
        ty: &'a Variant,
        name: Option<&'a NamedType>,
        nresults: usize,
    },
    VariantLift {
        ty: &'a Variant,
        name: Option<&'a NamedType>,
    },
    CallWasm {
        module: &'a str,
        name: &'a str,
        params: &'a [WasmType],
        results: &'a [WasmType],
    },
    CallInterface {
        module: &'a str,
        func: &'a Function,
    },
    Return {
        amt: usize,
    },
    Witx {
        instr: &'a WitxInstruction<'a>,
    },
}

Variants

GetArg

Acquires the specified parameter and places it on the stack. Depending on the context this may refer to wasm parameters or interface types parameters.

Fields of GetArg

nth: usize

I32Const

Pushes the constant val onto the stack.

Fields of I32Const

val: i32

Bitcasts

Casts the top N items on the stack using the Bitcast enum provided. Consumes the same number of operands that this produces.

Fields of Bitcasts

casts: &'a [Bitcast]

ConstZero

Pushes a number of constant zeros for each wasm type on the stack.

Fields of ConstZero

tys: &'a [WasmType]

I32Load

Pops an i32 from the stack and loads a little-endian i32 from it, using the specified constant offset.

Fields of I32Load

offset: i32

I32Load8U

Pops an i32 from the stack and loads a little-endian i8 from it, using the specified constant offset. The value loaded is the zero-extended to 32-bits

Fields of I32Load8U

offset: i32

I32Load8S

Pops an i32 from the stack and loads a little-endian i8 from it, using the specified constant offset. The value loaded is the sign-extended to 32-bits

Fields of I32Load8S

offset: i32

I32Load16U

Pops an i32 from the stack and loads a little-endian i16 from it, using the specified constant offset. The value loaded is the zero-extended to 32-bits

Fields of I32Load16U

offset: i32

I32Load16S

Pops an i32 from the stack and loads a little-endian i16 from it, using the specified constant offset. The value loaded is the sign-extended to 32-bits

Fields of I32Load16S

offset: i32

I64Load

Pops an i32 from the stack and loads a little-endian i64 from it, using the specified constant offset.

Fields of I64Load

offset: i32

F32Load

Pops an i32 from the stack and loads a little-endian f32 from it, using the specified constant offset.

Fields of F32Load

offset: i32

F64Load

Pops an i32 from the stack and loads a little-endian f64 from it, using the specified constant offset.

Fields of F64Load

offset: i32

I32Store

Pops an i32 address from the stack and then an i32 value. Stores the value in little-endian at the pointer specified plus the constant offset.

Fields of I32Store

offset: i32

I32Store8

Pops an i32 address from the stack and then an i32 value. Stores the low 8 bits of the value in little-endian at the pointer specified plus the constant offset.

Fields of I32Store8

offset: i32

I32Store16

Pops an i32 address from the stack and then an i32 value. Stores the low 16 bits of the value in little-endian at the pointer specified plus the constant offset.

Fields of I32Store16

offset: i32

I64Store

Pops an i32 address from the stack and then an i64 value. Stores the value in little-endian at the pointer specified plus the constant offset.

Fields of I64Store

offset: i32

F32Store

Pops an i32 address from the stack and then an f32 value. Stores the value in little-endian at the pointer specified plus the constant offset.

Fields of F32Store

offset: i32

F64Store

Pops an i32 address from the stack and then an f64 value. Stores the value in little-endian at the pointer specified plus the constant offset.

Fields of F64Store

offset: i32

I32FromChar

Converts an interface type char value to a 32-bit integer representing the unicode scalar value.

I64FromU64

Converts an interface type u64 value to a wasm i64.

I64FromS64

Converts an interface type s64 value to a wasm i64.

I32FromU32

Converts an interface type u32 value to a wasm i32.

I32FromS32

Converts an interface type s32 value to a wasm i32.

I32FromU16

Converts an interface type u16 value to a wasm i32.

I32FromS16

Converts an interface type s16 value to a wasm i32.

I32FromU8

Converts an interface type u8 value to a wasm i32.

I32FromS8

Converts an interface type s8 value to a wasm i32.

I32FromUsize

Converts a language-specific usize value to a wasm i32.

I32FromChar8

Converts a language-specific C char value to a wasm i32.

F32FromIf32

Conversion an interface type f32 value to a wasm f32.

This may be a noop for some implementations, but it’s here in case the native language representation of f32 is different than the wasm representation of f32.

F64FromIf64

Conversion an interface type f64 value to a wasm f64.

This may be a noop for some implementations, but it’s here in case the native language representation of f64 is different than the wasm representation of f64.

S8FromI32

Converts a core wasm i32 to an interface type s8.

This will truncate the upper bits of the i32.

U8FromI32

Converts a core wasm i32 to an interface type u8.

This will truncate the upper bits of the i32.

S16FromI32

Converts a core wasm i32 to an interface type s16.

This will truncate the upper bits of the i32.

U16FromI32

Converts a core wasm i32 to an interface type u16.

This will truncate the upper bits of the i32.

S32FromI32

Converts a core wasm i32 to an interface type s32.

U32FromI32

Converts a core wasm i32 to an interface type u32.

S64FromI64

Converts a core wasm i64 to an interface type s64.

U64FromI64

Converts a core wasm i64 to an interface type u64.

CharFromI32

Converts a core wasm i32 to an interface type char.

It’s safe to assume that the i32 is indeed a valid unicode code point.

If32FromF32

Converts a core wasm f32 to an interface type f32.

If64FromF64

Converts a core wasm f64 to an interface type f64.

Char8FromI32

Converts a core wasm i32 to a language-specific C char.

This will truncate the upper bits of the i32.

UsizeFromI32

Converts a core wasm i32 to a language-specific usize.

I32FromBorrowedHandle

Converts a “borrowed” handle into a wasm i32 value.

A “borrowed” handle in this case means one where ownership is not being relinquished. This is only used for lowering interface types parameters.

Situations that this is used are:

• A wasm exported function receives, as a parameter, handles defined by the wasm module itself. This is effectively proof of ownership by an external caller (be it host or wasm module) and the ownership of the handle still lies with the caller. The wasm module is only receiving a reference to the resource.

• A wasm module is calling an import with a handle defined by the import’s module. Sort of the converse of the previous case this means that the wasm module is handing out a reference to a resource that it owns. The type in the wasm module, for example, needs to reflect this.

This instruction is not used for return values in either export/import positions.

Fields of I32FromBorrowedHandle

ty: &'a NamedType

I32FromOwnedHandle

Converts an “owned” handle into a wasm i32 value.

This conversion is used for handle values which are crossing a module boundary for perhaps the first time. Some example cases of when this conversion is used are:

• When a host defines a function to be imported, returned handles use this instruction. Handles being returned to wasm a granting a capability, which means that this new capability is typically wrapped up in a new integer descriptor.

• When a wasm module calls an imported function with a type defined by itself, then it’s granting a capability to the callee. This means that the wasm module’s type is being granted for the first time, possibly, so it needs to be an owned value that’s consumed. Note that this doesn’t actually happen with *.witx today due to the lack of handle type imports.

• When a wasm module export returns a handle defined within the module, then it’s similar to calling an imported function with that handle. The capability is being granted to the caller of the export, so the owned value is wrapped up in an i32.

• When a host is calling a wasm module with a capability defined by the host, its’ similar to the host import returning a capability. This would be granting the wasm module with the capability so an owned version with a fresh handle is passed to the wasm module. Note that this doesn’t happen today with *.witx due to the lack of handle type imports.

Basically this instruction is used for handle->wasm conversions depending on the calling context and where the handle type in question was defined.

Fields of I32FromOwnedHandle

ty: &'a NamedType

HandleOwnedFromI32

Converts a core wasm i32 into an owned handle value.

This is the converse of I32FromOwnedHandle and is used in similar situations:

• A host definition of an import receives a handle defined in the module itself.
• A wasm module calling an import receives a handle defined by the import.
• A wasm module’s export receives a handle defined by an external module.
• A host calling a wasm export receives a handle defined in the module.

Note that like I32FromOwnedHandle the first and third bullets above don’t happen today because witx can’t express type imports just yet.

Fields of HandleOwnedFromI32

ty: &'a NamedType

HandleBorrowedFromI32

Converts a core wasm i32 into a borrowedhandle value.

This is the converse of I32FromBorrowedHandle and is used in similar situations:

• An exported wasm function receives, as a parameter, a handle that is defined by the wasm module.
• An host-defined imported function is receiving a handle, as a parameter, that is defined by the host itself.

Fields of HandleBorrowedFromI32

ty: &'a NamedType

ListCanonLower

Lowers a list where the element’s layout in the native language is expected to match the canonical ABI definition of interface types.

Pops a list value from the stack and pushes the pointer/length onto the stack. If malloc is set to Some then this is expected to consume the list which means that the data needs to be copied. An allocation/copy is expected when:

• A host is calling a wasm export with a list (it needs to copy the list in to the callee’s module, allocating space with malloc)
• A wasm export is returning a list (it’s expected to use malloc to give ownership of the list to the caller.
• A host is returning a list in a import definition, meaning that space needs to be allocated in the caller with malloc).

A copy does not happen (e.g. malloc is None) when:

• A wasm module calls an import with the list. In this situation it’s expected the caller will know how to access this module’s memory (e.g. the host has raw access or wasm-to-wasm communication would copy the list).

If malloc is Some then the adapter is not responsible for cleaning up this list because the other end is receiving the allocation. If malloc is None then the adapter is responsible for cleaning up any temporary allocation it created, if any.

Fields of ListCanonLower

element: &'a TypeRefmalloc: Option<&'a str>

ListLower

Lowers a list where the element’s layout in the native language is not expected to match the canonical ABI definition of interface types.

Pops a list value from the stack and pushes the pointer/length onto the stack. This operation also pops a block from the block stack which is used as the iteration body of writing each element of the list consumed.

The malloc field here behaves the same way as ListCanonLower. It’s only set to None when a wasm module calls a declared import. Otherwise lowering in other contexts requires allocating memory for the receiver to own.

Fields of ListLower

element: &'a TypeRefmalloc: Option<&'a str>

ListCanonLift

Lifts a list which has a canonical representation into an interface types value.

The term “canonical” representation here means that the representation of the interface types value in the native language exactly matches the canonical ABI definition of the type.

This will consume two i32 values from the stack, a pointer and a length, and then produces an interface value list. If the free field is set to Some then the pointer/length should be considered an owned allocation and need to be deallocated by the receiver. If it is set to None then a view is provided but it does not need to be deallocated.

The free field is set to Some in similar situations as described by ListCanonLower. If free is Some then the memory must be deallocated after the lifted list is done being consumed. If it is None then the receiver of the lifted list does not own the memory and must leave the memory as-is.

Fields of ListCanonLift

element: &'a TypeReffree: Option<&'a str>

ListLift

Lifts a list which into an interface types value.

This will consume two i32 values from the stack, a pointer and a length, and then produces an interface value list. Note that the pointer/length popped are owned and need to be deallocated with the wasm free function when the list is no longer needed.

This will also pop a block from the block stack which is how to read each individual element from the list.

Fields of ListLift

element: &'a TypeReffree: Option<&'a str>

IterElem

Pushes an operand onto the stack representing the list item from each iteration of the list.

This is only used inside of blocks related to lowering lists.

IterBasePointer

Pushes an operand onto the stack representing the base pointer of the next element in a list.

This is used for both lifting and lowering lists.

BufferLowerPtrLen

Pops a buffer value, pushes the pointer/length of where it points to in memory.

Fields of BufferLowerPtrLen

buffer: &'a Buffer

BufferLowerHandle

Pops a buffer value, pushes an integer handle for the buffer.

Fields of BufferLowerHandle

buffer: &'a Buffer

BufferLiftPtrLen

Pops a ptr/len, pushes a buffer wrapping that ptr/len of the memory from the origin module.

Fields of BufferLiftPtrLen

buffer: &'a Buffer

BufferLiftHandle

Pops an i32, pushes a buffer wrapping that i32 handle.

Fields of BufferLiftHandle

buffer: &'a Buffer

RecordLower

Pops a record value off the stack, decomposes the record to all of its fields, and then pushes the fields onto the stack.

Fields of RecordLower

ty: &'a RecordDatatypename: Option<&'a NamedType>

RecordLift

Pops all fields for a record off the stack and then composes them into a record.

Fields of RecordLift

ty: &'a RecordDatatypename: Option<&'a NamedType>

I32FromBitflags

Converts a language-specific record-of-bools to the packed representation as an i32.

Fields of I32FromBitflags

ty: &'a RecordDatatypename: &'a NamedType

I64FromBitflags

Converts a language-specific record-of-bools to the packed representation as an i64.

Fields of I64FromBitflags

ty: &'a RecordDatatypename: &'a NamedType

BitflagsFromI32

Converts a core wasm i32 to a language-specific record-of-bools.

Fields of BitflagsFromI32

repr: IntReprty: &'a RecordDatatypename: &'a NamedType

BitflagsFromI64

Converts a core wasm i64 to a language-specific record-of-bools.

Fields of BitflagsFromI64

repr: IntReprty: &'a RecordDatatypename: &'a NamedType

VariantPayload

This is a special instruction used at the entry of blocks used as part of ResultLower, representing that the payload of that variant being matched on should be pushed onto the stack.

VariantLower

Pops a variant off the stack as well as ty.cases.len() blocks from the code generator. Uses each of those blocks and the value from the stack to produce nresults of items.

Fields of VariantLower

ty: &'a Variantname: Option<&'a NamedType>nresults: usize

VariantLift

Pops an i32 off the stack as well as ty.cases.len() blocks from the code generator. Uses each of those blocks and the value from the stack to produce a final variant.

Fields of VariantLift

ty: &'a Variantname: Option<&'a NamedType>

CallWasm

Represents a call to a raw WebAssembly API. The module/name are provided inline as well as the types if necessary.

Fields of CallWasm

module: &'a strname: &'a strparams: &'a [WasmType]results: &'a [WasmType]

CallInterface

Same as CallWasm, except the dual where an interface is being called rather than a raw wasm function.

Fields of CallInterface

module: &'a strfunc: &'a Function

Return

Returns amt values on the stack. This is always the last instruction.

Fields of Return

amt: usize

Witx

An instruction from an extended instruction set that’s specific to *.witx and the “Preview1” ABI.

Fields of Witx

instr: &'a WitxInstruction<'a>

Implementations

impl Instruction<'_>

pub fn operands_len(&self) -> usize

How many operands does this instruction pop from the stack?

pub fn results_len(&self) -> usize

How many results does this instruction push onto the stack?

Trait Implementations

impl<'a> Debug for Instruction<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.