encoding

package
v1.2.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Copyright Consensys Software Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SPDX-License-Identifier: Apache-2.0

Index

Constants

View Source 
const (
	// FAIL instruction
	FAIL uint32 = iota
	// CHECKCAST instruction
	CHECKCAST
	// JMP instruction
	JMP
	// SKIP (unconditional forward branch) instruction
	SKIP
	// SKIP_M (skip table) instruction: dispatches on a source register against a
	// table of (value, target) pairs.
	SKIP_M
	// SEQ_rr (skip forward if equal)
	SEQ_rr
	// SNE_rr (skip forward if not equal)
	SNE_rr
	// SLT_rr (skip forward if less than)
	SLT_rr
	// SGT_rr (skip forward if greater than)
	SGT_rr
	// SLE_rr (skip forward if less than or equal)
	SLE_rr
	// SGE_rr (skip forward if greater than or equal)
	SGE_rr
	// SEQ_rv (skip forward if equal)
	SEQ_rv
	// SNE_rv (skip forward if not equal)
	SNE_rv
	// SLT_rv (skip forward if less than)
	SLT_rv
	// SGT_rr (skip forward if greater than)
	SGT_rv
	// SLE_rv (skip forward if less than or equal)
	SLE_rv
	// SGE_rr (skip forward if greater than or equal)
	SGE_rv
	// ENTER_n instruction
	ENTER_n
	// LEAVE_n instruction
	LEAVE_n
	// RET instruction
	RET
	// RD_ROM_nm instruction
	RD_ROM_nm
	// RD_SROM_nm instruction
	RD_SROM_nm
	// WR_WOM_nm instruction
	WR_WOM_nm
	// WR_SRAM instruction
	RD_RAM_nm
	// WR_RAM_nm instruction
	WR_RAM_nm
	// RD_PRAM_nm instruction
	RD_PRAM_nm
	// WR_PRAM_nm instruction
	WR_PRAM_nm
	// PUSH instruction
	PUSH
	// POP instruction
	POP
	// MOVE instruction
	MOVE
	// LDC (load constant) instruction
	LDC
	// LDC_w (load wide constant) instruction
	LDC_w
	// DESTRUCT instruction
	DESTRUCT
	// CAST instruction
	CAST
	// ADD_2n1 instruction
	ADD_2n1
	// SUB_2n1 instruction [must follow ADD_2n1]
	SUB_2n1
	// MUL_2n1 instruction [must follow SUB_2n1]
	MUL_2n1
	// ADDC (add with constant) instruction
	ADDC
	// SUBC (subtract with constant) instruction
	SUBC
	// MULC (multiply with constant) instruction
	MULC
	// ADD_nm (addition with vector target) instruction
	ADD_nm
	// SUB_nm (subtraction with vector target) instruction [must follow ADD_nm]
	SUB_nm
	// MUL_nm (multiplication with vector target) instruction [must follow SUB_nm]
	MUL_nm
	// CSUB (subtract from constant) instruction
	CSUB
	// DIV instruction
	DIV
	// REM instruction
	REM
	// INTRINSIC instruction (e.g. division hint, wide shift-left)
	INTRINSIC
	// ADDMOD_P instruction
	ADDMOD_P
	// SUBMOD_P instruction
	SUBMOD_P
	// MULMOD_P instruction
	MULMOD_P
	// AND instruction
	AND
	// OR instruction
	OR
	// XOR instruction
	XOR
	// NOT instruction
	NOT
	// SHL instruction
	SHL
	// SHR instruction
	SHR
	// CAT instruction
	CAT
	// DEBUG instruction
	DEBUG
	//
	MAX_BYTECODE
)

Every instruction occupies 32 bits, where the first byte is as follows: 

7   5 4       0

+-----+---------+ | : : | : : : : | +-----+---------+ 

(n)   (opcode)

Currently, n is instruction specific.

View Source 
const (
	// FUNCTION_SYMBOL identifies a program point within a function; its Offset
	// is the address of the corresponding instruction in the compiled bytecode.
	FUNCTION_SYMBOL uint8 = iota
	// STATIC_MEMORY identifies a static (compile-time initialised) read-only
	// memory.
	STATIC_MEMORY
	// READONLY_MEMORY identifies a read-only memory.
	READONLY_MEMORY
	// WRITEONCE_MEMORY identifies a write-once memory.
	WRITEONCE_MEMORY
	// READWRITE_MEMORY identifies a (random access) read-write memory.
	READWRITE_MEMORY
	// PAGED_READWRITE_MEMORY identifies a paged (random access) read-write
	// memory.
	PAGED_READWRITE_MEMORY
)

These constants enumerate the possible kinds of Symbol stored in a SymbolTable. The kind determines how a symbol's Offset should be interpreted: for FUNCTION_SYMBOL it is a bytecode address, whilst for the memory kinds it is a memory-specific identifier (i.e. an index amongst all memories of that kind).

View Source 
const BREAKPOINT = 0x80

BREAKPOINT is a modifier bit (bit 7 of the opcode byte) which, when set, signals that a breakpoint should be triggered immediately before the instruction executes. Like WIDE, it lies above the opcode field, so dispatch (which masks with OPCODE_MASK) is unaffected and both flagged and unflagged instructions reach the same executor.

View Source 
const OPCODE_MASK = 0x3f

OPCODE_MASK is used to extract the actual opcode from the opcode byte. The current format of an opcode byte is: 

7   6   5                   0

+---+---+---+---+---+---+---+---+ | B | W | OPCODE | +---+---+---+---+---+---+---+---+

Here, B is the Breakpoint flag, W is the Wide instruction flag, whilst the lower 6-bits form the opcode itself. For reference, the breakpoint bit signals a breakpoint should be triggered immediately before the current instruction executes.

View Source 
const WIDE = 0x40

WIDE is a modifier bit (bit 6 of the opcode byte) marking the "wide" form of an instruction, whose register operands are u16 rather than u8. Wide forms arise for functions with more than 256 registers. By convention, a wide form keeps its non-register fields in the first instruction word exactly as the narrow form does (where they still fit), whilst its register operands move into subsequent words, packed two per word (least significant half first) in the order they appear in the narrow encoding.

Variables

View Source 
var PRAM_READ = RwMode{5}

PRAM_READ representing reading from a (paged) random-access memory.

View Source 
var PRAM_WRITE = RwMode{6}

PRAM_WRITE representing write to a (paged) random-access memory.

View Source 
var ROM_READ = RwMode{0}

ROM_READ representing reading from a read-only memory.

View Source 
var SRAM_READ = RwMode{3}

SRAM_READ representing reading from a (small) random-access memory.

View Source 
var SRAM_WRITE = RwMode{4}

SRAM_WRITE representing write to a (small) random-access memory.

View Source 
var SROM_READ = RwMode{1}

SROM_READ representing reading from a (static) read-only memory.

View Source 
var WOM_WRITE = RwMode{2}

WOM_WRITE representing writing to a write-once memory.

Functions

func Arith 

func Arith[W word.Word[W]](p bytecode.Arith[W], env Environment[W]) []uint32

Arith encodes an arithmetic bytecode, selecting the most compact instruction form supported by its operands (e.g. load-constant, move, register-register, register-constant, or the general vectored form).

func Bitwise 

func Bitwise[W word.Word[W]](p *bytecode.Bitwise[W]) []uint32

Bitwise encodes a bitwise bytecode (AND/OR/XOR/NOT/SHL/SHR).

func Call 

func Call[W word.Word[W]](pc uint32, p *bytecode.Call[W], env Environment[W]) (codes []uint32)

Call encodes a call bytecode as an ENTER/LEAVE instruction pair: ENTER allocates the callee's frame, binds its arguments and pushes a stack-frame record, whilst LEAVE binds the returns to their destination registers.

func Cat 

func Cat[W word.Word[W]](p *bytecode.Cat[W]) []uint32

Cat encodes a concatenation bytecode.

func CheckCast 

func CheckCast[W word.Word[W]](p *bytecode.CheckCast[W]) []uint32

CheckCast encodes a check-cast bytecode, which checks that the value held in the target register fits within the given bit width.

func Debug 

func Debug[W word.Word[W]](p *bytecode.Debug[W], env Environment[W]) []uint32

Debug encodes a debug bytecode, interning its formatted chunks in the symbol table and referencing them by index.

func DecodeArith_1n1c 

func DecodeArith_1n1c[W word.Word[W]](pc uint32, codes []uint32) (rs, rd uint16, constant W, n uint32)

DecodeArith_1n1c decodes a one-source-plus-constant arithmetic instruction, returning the source and destination registers, constant and instruction width.

func DecodeArith_2n1 

func DecodeArith_2n1(pc uint32, codes []uint32) (rs0, rs1, rd uint16, n uint32)

DecodeArith_2n1 decodes a two-source, one-target arithmetic instruction, returning the source and destination registers and the instruction width.

func DecodeCheckCast 

func DecodeCheckCast(pc uint32, codes []uint32) (rd uint16, bitwidth uint16, n uint32)

DecodeCheckCast decodes a check-cast instruction, returning its register, bit width and instruction width.

func DecodeFieldArithOperands 

func DecodeFieldArithOperands[W word.Word[W]](pc uint32, codes []uint32) (
	rd RegisterId, sources Operands, constant W, n uint32)

DecodeFieldArithOperands extracts the raw operands (target register, source register iterator, constant and instruction width) of a field-arithmetic instruction. It is shared by the disassembler (DecodeFieldArith) and the interpreter's executor.

func DecodeIntrinsicOperands 

func DecodeIntrinsicOperands(pc uint32, codes []uint32) (op Operation, targets, sources Operands, n uint32)

DecodeIntrinsicOperands decodes the operation selector along with the target and source operands of a hint instruction. Each vector is packed as a (base, len) byte pair, hence the iterators range over twice the vector counts.

func DecodeJmp1 

func DecodeJmp1(pc uint32, codes []uint32) (uint32, uint32)

DecodeJmp1 decodes the target of an unconditional jump instruction.

func DecodeLdc_1 

func DecodeLdc_1[W word.Word[W]](pc uint32, codes []uint32) (constant W, rd uint16, n uint32)

DecodeLdc_1 decodes a load-constant instruction carrying a small (u16 or, in the wide form, u24) constant, returning the constant, destination register and instruction width.

func DecodeLdc_w 

func DecodeLdc_w[W word.Word[W]](pc uint32, codes []uint32) (constant W, rd uint16, n uint32)

DecodeLdc_w decodes a load-constant instruction carrying a wide constant, returning the constant, destination register and instruction width.

func DecodeMove_1s1 

func DecodeMove_1s1(pc uint32, codes []uint32) (rs, rd uint16, n uint32)

DecodeMove_1s1 decodes a register-to-register move instruction, returning the source and destination registers and the instruction width.

func DecodeRet1 

func DecodeRet1(pc uint32, codes []uint32) (width uint16, roffset uint32, n uint32)

DecodeRet1 decodes the operands of a return instruction.

func DecodeSkip1 

func DecodeSkip1(pc uint32, codes []uint32) (uint32, uint32)

DecodeSkip1 decodes the target of a forward-skip instruction.

func DecodeSkipIf_rr 

func DecodeSkipIf_rr(pc uint32, codes []uint32) (skip uint32, rs0, rs1 RegisterId, op Cond, n uint32)

DecodeSkipIf_rr decodes the operands of a register-register conditional skip.

func DecodeSkipIf_rv 

func DecodeSkipIf_rv(pc uint32, codes []uint32) (skip uint32, rs0, rs1 RegisterVector, op Cond, n uint32)

DecodeSkipIf_rv decodes the operands of a register-vector conditional branch.

func DivRem 

func DivRem[W word.Word[W]](p *bytecode.DivRem[W]) []uint32

DivRem encodes a division/remainder bytecode; the opcode held within the bytecode selects between quotient (DIV) and remainder (REM).

func Encode 

func Encode[W word.Word[W]](b Bytecode[W], pc uint32, env Environment[W]) []uint32

Encode encodes the given bytecode into its sequence of 32-bit instruction words. Here, pc is the address at which the instruction will reside within the compiled sequence (needed to compute relative branch offsets), whilst env supplies the symbol information required to resolve branch targets, memories and formatted chunks.

func Fail 

func Fail[W word.Word[W]](p *bytecode.Fail[W], env Environment[W]) []uint32

Fail encodes a fail bytecode, interning its formatted chunks in the symbol table and referencing them by index.

func FieldArith 

func FieldArith[W word.Word[W]](p *bytecode.FieldArith[W]) []uint32

FieldArith encodes a field-arithmetic bytecode (ADDMOD_P/SUBMOD_P/MULMOD_P).

func GetRelativeOffset 

func GetRelativeOffset(pc uint32, target Address, width uint) (roff uint32, ok bool)

GetRelativeOffset encodes the width-bit two's complement relative offset from pc to target, returning ok=false when the target is out of range.

func Intrinsic 

func Intrinsic[W word.Word[W]](p *bytecode.Intrinsic[W]) []uint32

Intrinsic encodes an intrinsic bytecode (e.g. DIV_HINT, which supplies the prover with the quotient, remainder and witness for a division, or WIDE_SHL).

func IsWideForm 

func IsWideForm(pc uint32, codes []uint32) bool

IsWideForm checks whether the instruction word at the given position has the WIDE modifier bit set (i.e. carries u16 register operands).

func IsWideRegisterVectors 

func IsWideRegisterVectors(vecs []RegisterVector) bool

IsWideRegisterVectors checks whether any of the given register vectors requires the wide (u16) instruction form, i.e. has a base or length which does not fit within a single byte.

func IsWideRegisters 

func IsWideRegisters(regs ...RegisterId) bool

IsWideRegisters checks whether any of the given registers requires the wide (u16) instruction form, i.e. does not fit within a single byte.

func Jmp 

func Jmp[W word.Word[W]](pc uint32, b *bytecode.Jmp[W], env Environment[W]) []uint32

Jmp encodes an unconditional jump bytecode. A forward branch is preferred as a SKIP instruction (whose unsigned offset offers greater forward range), falling back to a JMP carrying a signed relative offset otherwise.

func MaxCallEncodedLength 

func MaxCallEncodedLength[W word.Word[W]](p *bytecode.Call[W]) uint

MaxCallEncodedLength returns the maximum length (in u32 words) which an encoding of the given call bytecode can occupy, i.e. the size of its wide ENTER/LEAVE pair (the wide form is never smaller than the narrow form).

func MaxEncodedLength 

func MaxEncodedLength[W word.Word[W]](b bytecode.Bytecode[W], env Environment[W]) uint

MaxEncodedLength returns the maximum length (i.e. number of uint32 words) an encoding of the given bytecode can occupy.

func NumCodesPackedSmall 

func NumCodesPackedSmall(n uint) uint32

NumCodesPackedSmall returns the number of 32-bit codes required to pack n bytes, four bytes per code (rounding up).

func NumCodesPackedWide 

func NumCodesPackedWide(n uint) uint32

NumCodesPackedWide returns the number of 32-bit codes required to pack n u16 operands, two per code (rounding up).

func OpIterToArray 

func OpIterToArray[T uint8 | uint16](iter Operands) []T

OpIterToArray extracts n elements from the given iterator into an array.

func PackBytesIntoCodes 

func PackBytesIntoCodes(bytes []byte) []uint32

PackBytesIntoCodes packs a given array of bytes into an array of codes, such that the last code is padded with 0xff.

func PackShortsIntoCodes 

func PackShortsIntoCodes(shorts []uint16) []uint32

PackShortsIntoCodes packs a given array of u16 operands into an array of codes (two per code, least significant half first), such that the last code is padded with 0xffff.

func ReadWrite 

func ReadWrite[W word.Word[W]](p *bytecode.ReadWrite[W], env Environment[W]) []uint32

ReadWrite encodes a memory read/write bytecode, resolving the target memory to its memory-specific identifier via the symbol table. The bytecode records only whether the access is a read or a write; the precise mode (and hence opcode) is recovered here by combining that with the memory's kind, as recorded in the symbol table.

func RegisterVectorsAsBytes 

func RegisterVectorsAsBytes(vecs []RegisterVector) []byte

RegisterVectorsAsBytes packs an array of (small) registers into an array of bytes. This will panic if any register is encountered which does not fit into a byte.

func RegisterVectorsAsShorts 

func RegisterVectorsAsShorts(vecs []RegisterVector) []uint16

RegisterVectorsAsShorts packs an array of register vectors into an array of u16 operands (as base / length pairs), as used by wide instruction forms.

func RegsAsBytes 

func RegsAsBytes(regs []RegisterId) []byte

RegsAsBytes packs an array of (small) registers into an array of bytes. This will panic if any register is encountered which does not fit into a byte.

func RegsAsShorts 

func RegsAsShorts(regs []RegisterId) []uint16

RegsAsShorts packs an array of registers into an array of u16 operands, as used by wide instruction forms.

func Ret 

func Ret[W word.Word[W]](p *bytecode.Ret[W], env Environment[W]) []uint32

Ret encodes a return bytecode, emitting the enclosing function's frame width and the offset of its return registers within the frame.

func Skip 

func Skip[W word.Word[W]](pc uint32, b *bytecode.Skip[W], env Environment[W]) []uint32

Skip encodes an unconditional forward-branch (SKIP) bytecode.

func SkipIf 

func SkipIf[W word.Word[W]](pc Address, b *bytecode.SkipIf[W], env Environment[W]) []uint32

SkipIf encodes a conditional forward-branch bytecode, selecting the register-register or register-vector form according to its operands.

func Switch 

func Switch[W word.Word[W]](p *bytecode.Switch[W], env Environment[W]) []uint32

Switch encodes a multiway-skip (switch) bytecode, which dispatches on a source register against a table of (value, target) pairs.

Types

type Address 

type Address = bytecode.Address

Address just provides a convenient alias to make the code more readable.

func GetBranchTarget 

func GetBranchTarget(offset uint32, relOffset uint32, width uint) Address

GetBranchTarget resolves an absolute branch target from a base offset and a width-bit two's complement relative offset.

type Binary 

type Binary[W word.Word[W]] struct {
	// contains filtered or unexported fields
}

Binary represents a compiled program: the symbol table describing its modules together with the encoded bytecode sequence ready for execution.

func NewBinary 

func NewBinary[W word.Word[W]](env SymbolTable[W], bytecodes []uint32) Binary[W]

NewBinary returns a new Binary[W] initialized with the given parameters.

func (Binary[W]) AddressOf 

func (p Binary[W]) AddressOf(mid uint16) (Symbol, bool)

AddressOf determines the address of a given (function) symbol, or returns an error if no such symbol exists.

func (Binary[W]) Bytecodes 

func (p Binary[W]) Bytecodes() []uint32

Bytecodes returns the raw bytecode sequence

func (Binary[W]) Chunks 

func (p Binary[W]) Chunks(index uint) []bytecode.FormattedChunk

Chunks returns formatted chunks needed for I/O instructions.

func (Binary[W]) Encoding 

func (p Binary[W]) Encoding() (encoded [][]uint32)

Encoding returns the binary encoding of the instruction at the given program point within the given module.

func (Binary[W]) FunctionAt 

func (p Binary[W]) FunctionAt(address Address) Label

FunctionAt determines whether or not there is a symbol associated with a given instruction address.

func (Binary[W]) HasModule 

func (p Binary[W]) HasModule(name string) (uint16, bool)

HasModule returns the identifier for the module with the given name, or returns false if no such module exists.

func (Binary[W]) Module 

func (p Binary[W]) Module(mid uint16) descriptor.Module[W]

Module returns the module with the given identifier.

func (Binary[W]) Modules 

func (p Binary[W]) Modules() []descriptor.Module[W]

Modules returns information about the modules declared within this program.

type Bytecode 

type Bytecode[W word.Word[W]] = bytecode.Bytecode[W]

Bytecode provides a convenient alias

func DecodeCat 

func DecodeCat[W word.Word[W]](pc uint32, codes []uint32) (Bytecode[W], uint32)

DecodeCat decodes a concatenation instruction at the given program counter.

func DecodeIntrinsic 

func DecodeIntrinsic[W word.Word[W]](pc uint32, codes []uint32) (Bytecode[W], uint32)

DecodeIntrinsic decodes an intrinsic instruction at the given program counter.

func DecodeSkipTable 

func DecodeSkipTable[W word.Word[W]](pc uint32, codes []uint32) (Bytecode[W], uint32)

DecodeSkipTable decodes an SMW instruction at the given program counter.

type Cond 

type Cond = bytecode.Condition

Cond just provides a convenient alias to make the code more readable.

type Environment 

type Environment[W word.Word[W]] struct {
	*SymbolTable[W]
	// contains filtered or unexported fields
}

Environment provides a view of a SymbolTable from within a specific (enclosing) module, supplying the context required to encode that module's instructions. In particular, it allows branch targets within the enclosing function to be resolved without having to thread the module identifier through explicitly.

func (*Environment[W]) OffsetFor 

func (p *Environment[W]) OffsetFor(id ModuleId, pp ProgramPoint) uint32

OffsetFor determines the encoded offset for the given program point in the enclosing function.

func (*Environment[W]) Point 

func (p *Environment[W]) Point() ProgramPoint

Point returns the program point for the current bytecode

func (*Environment[W]) RegisterMap 

func (p *Environment[W]) RegisterMap() descriptor.RegisterMap[W]

RegisterMap returns a register map for the enclosing module

type Label 

type Label struct {
	// ModuleId identifies the enclosing module (function or memory) of this
	// label.
	ModuleId uint16
	// Point identifies the program point for this label.  For memory modules,
	// this is always (0,0).
	Point ProgramPoint
}

Label uniquely identifies a labelled entity within the program, and serves as the key under which its resolved Symbol is stored in a SymbolTable.

func (Label) String 

func (p Label) String() string

String returns a human-readable representation of this label of the form "module:(macro,micro)".

type ModuleId 

type ModuleId = bytecode.ModuleId

ModuleId provides a convenient alias

type Operands 

type Operands struct {
	// contains filtered or unexported fields
}

Operands provides a way of iterating operands packed into u32 words without allocating memory. Operands are either u8 (four per word, as used by narrow instruction forms) or u16 (two per word, as used by wide instruction forms); the element width is fixed at construction.

func DecodeArith_nm 

func DecodeArith_nm[W word.Word[W]](pc uint32, codes []uint32) (
	targets, sources Operands, constant W, bitwidth uint, n uint32)

DecodeArith_nm decodes a vectored (multi-target, multi-source) arithmetic instruction, returning iterators over its target and source registers, the constant operand and the instruction width.

func DecodeCatOperands 

func DecodeCatOperands(pc uint32, codes []uint32) (targets, sources Operands, n uint32)

DecodeCatOperands decodes the target and source operands of a concatenation instruction.

func DecodeDebug 

func DecodeDebug(pc uint32, codes []uint32) (index uint, sources Operands, n uint32)

DecodeDebug decodes a debug instruction, returning the index of its formatted chunks, an iterator over its source register vectors and the instruction width.

func DecodeEnter_n 

func DecodeEnter_n(pc uint32, codes []uint32) (width uint16, target uint32, args Operands, n uint32)

DecodeEnter_n decodes the operands of an enter (function entry) instruction.

func DecodeFail 

func DecodeFail(pc uint32, codes []uint32) (index uint, sources Operands, n uint32)

DecodeFail decodes a fail instruction, returning the index of its formatted chunks, an iterator over its source register vectors and the instruction width.

func DecodeLeave_n 

func DecodeLeave_n(pc uint32, codes []uint32) (rets Operands, n uint32)

DecodeLeave_n decodes the operands of a leave (function exit) instruction.

func DecodeReadWrite_sn 

func DecodeReadWrite_sn(pc uint32, codes []uint32) (id uint16, addr, data Operands, n uint32)

DecodeReadWrite_sn decodes the operands of a memory read/write instruction.

func NewOperands 

func NewOperands(n, len uint, data []uint32) Operands

NewOperands constructs an iterator over u8 operands (packed four per word) from a given array of words and starting position.

func NewWideOperands 

func NewWideOperands(n, len uint, data []uint32) Operands

NewWideOperands constructs an iterator over u16 operands (packed two per word) from a given array of words and starting position.

func (*Operands) HasNext 

func (p *Operands) HasNext() bool

HasNext determines whether there are any more operands in this iterator.

func (*Operands) Next 

func (p *Operands) Next() (operand uint16)

Next returns the next operand in this iterator.

type Operation 

type Operation = bytecode.Operation

Operation provides a convenient alias

type ProgramPoint 

type ProgramPoint = descriptor.ProgramPoint

ProgramPoint provides a convenient alias.

type RegisterId 

type RegisterId = bytecode.RegisterId

RegisterId provides a convenient alias

func DecodeBitwise_2n1 

func DecodeBitwise_2n1(pc uint32, codes []uint32) (rd, lhs, rhs RegisterId, bitwidth uint16, n uint32)

DecodeBitwise_2n1 decodes the operands of a two-source bitwise instruction.

func DecodeDivRem_2n1 

func DecodeDivRem_2n1(pc uint32, codes []uint32) (rd, dividend, divisor RegisterId, n uint32)

DecodeDivRem_2n1 decodes the operands of a division/remainder instruction.

type RegisterVector 

type RegisterVector = bytecode.RegisterVector

RegisterVector just provides a convenient alias to make the code more readable.

type RwMode 

type RwMode struct {
	// contains filtered or unexported fields
}

RwMode determines what kind of memory is being operated on (e.g. ROM or RAM, etc) and what operation is being performed (i.e. READ or WRITE). Its tag selects the corresponding opcode (RD_ROM_nm + tag).

func (RwMode) Tag 

func (p RwMode) Tag() uint8

Tag gets the underlying tag for this enum.

type Symbol 

type Symbol struct {
	// Kind distinguishes the entity this symbol refers to (e.g.
	// FUNCTION_SYMBOL, READONLY_MEMORY, etc.), and hence how Offset should be
	// interpreted.
	Kind uint8
	// Offset is the resolved value of this symbol.  For FUNCTION_SYMBOL it is a
	// bytecode address; for memory kinds it is a memory-specific identifier.
	Offset Address
}

Symbol describes the resolved location of a labelled entity (a function program point or a memory) within the compiled program.

func NewSymbol 

func NewSymbol(kind uint8, offset Address) Symbol

NewSymbol constructs a Symbol of the given kind with the given offset.

type SymbolTable 

type SymbolTable[W word.Word[W]] struct {
	// contains filtered or unexported fields
}

SymbolTable records the information needed to encode (and later interpret) a compiled program. Specifically, it holds the program's modules, the formatted chunks referenced by certain instructions, and the mapping from labels to their resolved symbols. It is populated incrementally during compilation as branch targets and memory identifiers are resolved.

func NewSymbolTable 

func NewSymbolTable[W word.Word[W]](modules ...descriptor.Module[W]) SymbolTable[W]

NewSymbolTable constructs an (initially empty) symbol table for the given modules.

func (*SymbolTable[W]) ChunksIndex 

func (p *SymbolTable[W]) ChunksIndex(chunks ...bytecode.FormattedChunk) uint

ChunksIndex returns the index identifying the given sequence of formatted chunks, interning them on first use. That is, if an identical sequence has been seen before its existing index is returned; otherwise, the sequence is stored and a fresh index allocated.

func (*SymbolTable[W]) EnvironmentFor 

func (p *SymbolTable[W]) EnvironmentFor(id ModuleId, point ProgramPoint) Environment[W]

EnvironmentFor returns an Environment which views this symbol table from the perspective of the module with the given identifier (i.e. as the enclosing function during encoding).

func (*SymbolTable[W]) HasSymbol 

func (p *SymbolTable[W]) HasSymbol(lab Label) bool

HasSymbol determines whether a symbol has been recorded for the given label.

func (*SymbolTable[W]) Insert 

func (p *SymbolTable[W]) Insert(lab Label, symbol Symbol)

Insert records (or overwrites) the symbol associated with the given label.

func (*SymbolTable[W]) Module 

func (p *SymbolTable[W]) Module(id ModuleId) descriptor.Module[W]

Module returns the module with the given identifier.

func (*SymbolTable[W]) Modules 

func (p *SymbolTable[W]) Modules() []descriptor.Module[W]

Modules returns all modules (functions and memories) making up the program.

func (*SymbolTable[W]) SymbolAt 

func (p *SymbolTable[W]) SymbolAt(lab Label) Symbol

SymbolAt returns the symbol recorded for the given label. The zero Symbol is returned if no such label has been recorded.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.