mipsevm

README

mipsevm

Supported 63 instructions:

Category	Instruction	Description
Arithmetic	add	Add.
Arithmetic	addi	Add immediate (with sign-extension).
Arithmetic	addiu	Add immediate unsigned.
Arithmetic	addu	Add unsigned.
Logical	and	Bitwise AND.
Logical	andi	Bitwise AND immediate.
Conditional Branch	beq	Branch on equal.
Conditional Branch	bgez	Branch on greater than or equal to zero.
Conditional Branch	bgtz	Branch on greater than zero.
Conditional Branch	blez	Branch on less than or equal to zero.
Conditional Branch	bltz	Branch on less than zero.
Conditional Branch	bne	Branch on not equal.
Logical	clo	Count leading ones.
Logical	clz	Count leading zeros.
Arithmetic	div	Divide.
Arithmetic	divu	Divide unsigned.
Unconditional Jump	j	Jump.
Unconditional Jump	jal	Jump and link.
Unconditional Jump	jalr	Jump and link register.
Unconditional Jump	jr	Jump register.
Data Transfer	lb	Load byte.
Data Transfer	lbu	Load byte unsigned.
Data Transfer	lh	Load halfword.
Data Transfer	lhu	Load halfword unsigned.
Data Transfer	ll	Load linked word.
Data Transfer	lui	Load upper immediate.
Data Transfer	lw	Load word.
Data Transfer	lwl	Load word left.
Data Transfer	lwr	Load word right.
Data Transfer	mfhi	Move from HI register.
Data Transfer	mflo	Move from LO register.
Data Transfer	movn	Move conditional on not zero.
Data Transfer	movz	Move conditional on zero.
Data Transfer	mthi	Move to HI register.
Data Transfer	mtlo	Move to LO register.
Arithmetic	mul	Multiply (to produce a word result).
Arithmetic	mult	Multiply.
Arithmetic	multu	Multiply unsigned.
Logical	nor	Bitwise NOR.
Logical	or	Bitwise OR.
Logical	ori	Bitwise OR immediate.
Data Transfer	sb	Store byte.
Data Transfer	sc	Store conditional.
Data Transfer	sh	Store halfword.
Logical	sll	Shift left logical.
Logical	sllv	Shift left logical variable.
Comparison	slt	Set on less than (signed).
Comparison	slti	Set on less than immediate.
Comparison	sltiu	Set on less than immediate unsigned.
Comparison	sltu	Set on less than unsigned.
Logical	sra	Shift right arithmetic.
Logical	srav	Shift right arithmetic variable.
Logical	srl	Shift right logical.
Logical	srlv	Shift right logical variable.
Arithmetic	sub	Subtract.
Arithmetic	subu	Subtract unsigned.
Data Transfer	sw	Store word.
Data Transfer	swl	Store word left.
Data Transfer	swr	Store word right.
Serialization	sync	Synchronize shared memory.
System Calls	syscall	System call.
Logical	xor	Bitwise XOR.
Logical	xori	Bitwise XOR immediate.

To run:

1. Load a program into a state, e.g. using LoadELF.
2. Patch the program if necessary: e.g. using PatchGo for Go programs, PatchStack for empty initial stack, etc.
3. Implement the PreimageOracle interface
4. Instrument the emulator with the state, and pre-image oracle, using NewInstrumentedState
5. Step through the instrumented state with Step(proof), where proof==true if witness data should be generated. Steps are faster with proof==false.
6. Optionally repeat the step on-chain by calling MIPS.sol and PreimageOracle.sol, using the above witness data.

Documentation

Index

• Constants
• func AppendBoolToWitness(witnessData []byte, boolVal bool) []byte
• func VmStatus(exited bool, exitCode uint8) uint8
• type CpuScalars
• type DebugInfo
• type FPVM
• type FPVMState
• type HashFn
• type HexU32
  • func (v HexU32) MarshalText() ([]byte, error)
  • func (v HexU32) String() string
• type LocalContext
• type LoggingWriter
  • func (lw *LoggingWriter) Write(b []byte) (int, error)
• type Metadata
• type PreimageOracle
• type StepWitness
  • func (wit *StepWitness) HasPreimage() bool
• type SymbolMatcher

Constants

const (
	VMStatusValid      = 0
	VMStatusInvalid    = 1
	VMStatusPanic      = 2
	VMStatusUnfinished = 3
)

Functions

func AppendBoolToWitness

func AppendBoolToWitness(witnessData []byte, boolVal bool) []byte

func VmStatus

func VmStatus(exited bool, exitCode uint8) uint8

Types

type CpuScalars

type CpuScalars struct {
	PC     arch.Word `json:"pc"`
	NextPC arch.Word `json:"nextPC"`
	LO     arch.Word `json:"lo"`
	HI     arch.Word `json:"hi"`
}

type DebugInfo

type DebugInfo struct {
	Pages               int            `json:"pages"`
	MemoryUsed          hexutil.Uint64 `json:"memory_used"`
	NumPreimageRequests int            `json:"num_preimage_requests"`
	TotalPreimageSize   int            `json:"total_preimage_size"`
}

type FPVM

type FPVM interface {
	// GetState returns the current state of the VM. The FPVMState is updated by successive calls to Step
	GetState() FPVMState

	// Step executes a single instruction and returns the witness for the step
	Step(includeProof bool) (*StepWitness, error)

	// CheckInfiniteLoop returns true if the vm is stuck in an infinite loop
	CheckInfiniteLoop() bool

	// LastPreimage returns the last preimage accessed by the VM
	LastPreimage() (preimageKey [32]byte, preimage []byte, preimageOffset arch.Word)

	// Traceback prints a traceback of the program to the console
	Traceback()

	// GetDebugInfo returns debug information about the VM
	GetDebugInfo() *DebugInfo

	// InitDebug initializes the debug mode of the VM
	InitDebug() error

	// LookupSymbol returns the symbol located at the specified address.
	// May return an empty string if there's no symbol table available.
	LookupSymbol(addr arch.Word) string
}

type FPVMState

type FPVMState interface {
	serialize.Serializable

	GetMemory() *memory.Memory

	// GetHeap returns the current memory address at the top of the heap
	GetHeap() arch.Word

	// GetPreimageKey returns the most recently accessed preimage key
	GetPreimageKey() common.Hash

	// GetPreimageOffset returns the current offset into the current preimage
	GetPreimageOffset() arch.Word

	// GetPC returns the currently executing program counter
	GetPC() arch.Word

	// GetCpu returns the currently active cpu scalars, including the program counter
	GetCpu() CpuScalars

	// GetRegistersRef returns a pointer to the currently active registers
	GetRegistersRef() *[32]arch.Word

	// GetStep returns the current VM step
	GetStep() uint64

	// GetExited returns whether the state exited bit is set
	GetExited() bool

	// GetExitCode returns the exit code
	GetExitCode() uint8

	// GetLastHint returns optional metadata which is not part of the VM state itself.
	// It is used to remember the last pre-image hint,
	// so a VM can start from any state without fetching prior pre-images,
	// and instead just repeat the last hint on setup,
	// to make sure pre-image requests can be served.
	// The first 4 bytes are a Word length prefix.
	// Warning: the hint MAY NOT BE COMPLETE. I.e. this is buffered,
	// and should only be read when len(LastHint) > 4 && Word(LastHint[:4]) <= len(LastHint[4:])
	GetLastHint() hexutil.Bytes

	// EncodeWitness returns the witness for the current state and the state hash
	EncodeWitness() (witness []byte, hash common.Hash)

	// CreateVM creates a FPVM that can operate on this state.
	CreateVM(logger log.Logger, po PreimageOracle, stdOut, stdErr io.Writer, meta Metadata) FPVM
}

type HashFn

type HashFn func(sw []byte) (common.Hash, error)

type HexU32

type HexU32 uint32

HexU32 to lazy-format integer attributes for logging

func (HexU32) MarshalText

func (v HexU32) MarshalText() ([]byte, error)

func (HexU32) String

func (v HexU32) String() string

type LocalContext

type LocalContext common.Hash

type LoggingWriter

type LoggingWriter struct {
	Log log.Logger
}

LoggingWriter is a simple util to wrap a logger, and expose an io Writer interface, for the program running within the VM to write to.

func (*LoggingWriter) Write

func (lw *LoggingWriter) Write(b []byte) (int, error)

type Metadata

type Metadata interface {
	LookupSymbol(addr arch.Word) string
	CreateSymbolMatcher(name string) SymbolMatcher
}

type PreimageOracle

type PreimageOracle interface {
	Hint(v []byte)
	GetPreimage(k [32]byte) []byte
}

type StepWitness

type StepWitness struct {
	// encoded state witness
	State     []byte
	StateHash common.Hash

	ProofData []byte

	PreimageKey    [32]byte // zeroed when no pre-image is accessed
	PreimageValue  []byte   // including the 8-byte length prefix
	PreimageOffset arch.Word
}

func (*StepWitness) HasPreimage

func (wit *StepWitness) HasPreimage() bool

type SymbolMatcher

type SymbolMatcher func(addr arch.Word) bool