Merge pull request #6050 from ethereum-optimism/cannon

Move Cannon into monorepo

.circleci/config.yml

@@ -59,6 +59,38 @@ commands:
             pip3 install -r requirements.txt
             python3 main.py "<<parameters.patterns>>"
 jobs:
+  cannon-go-lint-and-test:
+    docker:
+      - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/ci-builder:latest
+    resource_class: medium
+    steps:
+      - checkout
+      - check-changed:
+          patterns: cannon,packages/contracts-bedrock/contracts/cannon
+      - run:
+          name: prep Cannon results dir
+          command: mkdir -p /tmp/test-results
+      - run:
+          name: build Cannon example binaries
+          command: make elf  # only compile ELF binaries with Go, we do not have MIPS GCC for creating the debug-dumps.
+          working_directory: cannon/example
+      - run:
+          name: Cannon Go lint
+          command: |
+            golangci-lint run -E goimports,sqlclosecheck,bodyclose,asciicheck,misspell,errorlint --timeout 5m -e "errors.As" -e "errors.Is" ./...
+          working_directory: cannon
+      - run:
+          name: Cannon Go tests
+          command: |
+            gotestsum --format=standard-verbose --junitfile=/tmp/test-results/cannon.xml \
+            -- -parallel=2 -coverpkg=github.com/ethereum-optimism/optimism/cannon/... -coverprofile=coverage.out ./...
+          working_directory: cannon
+      - run:
+          name: upload Cannon coverage
+          command: codecov --verbose --clean --flags cannon-go-tests
+      - store_test_results:
+          path: /tmp/test-results
+
   yarn-monorepo:
     docker:
       - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/ci-builder:latest
@@ -1387,6 +1419,7 @@ workflows:
             - op-challenger-docker-build
       - check-generated-mocks-op-node
       - check-generated-mocks-op-service
+      - cannon-go-lint-and-test
   release:
     jobs:
       - hold:

cannon/.gitignore

+node_modules
+artifacts
+cache
+.*.swp
+venv
+.idea
+*.log
+example/bin
+contracts/out
+state.json
+*.json
+*.pprof
+*.out

cannon/LICENSE

+MIT License
+
+Copyright (c) 2021 Optimism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cannon/README.md

+<!--![cannon](https://upload.wikimedia.org/wikipedia/commons/8/80/Cannon%2C_Château_du_Haut-Koenigsbourg%2C_France.jpg)-->
+<!--![cannon](https://cdn1.epicgames.com/ue/product/Featured/SCIFIWEAPONBUNDLE_featured-894x488-83fbc936b6d86edcbbe892b1a6780224.png)-->
+<!--![cannon](https://static.wikia.nocookie.net/ageofempires/images/8/80/Bombard_cannon_aoe2DE.png/revision/latest/top-crop/width/360/height/360?cb=20200331021834)-->
+<!--![cannon](https://paradacreativa.es/wp-content/uploads/2021/05/Canon-orbital-GTA-01.jpg)-->
+
+---
+
+Cannon *(cannon cannon cannon)* is an onchain MIPS instruction emulator.
+Cannon supports EVM-equivalent fault proofs by enabling Geth to run onchain,
+one instruction at a time, as part of an interactive dispute game.
+
+* It's Go code
+* ...that runs an EVM
+* ...emulating a MIPS machine
+* ...running compiled Go code
+* ...that runs an EVM
+
+For more information, see [Docs](./docs/README.md).
+
+## Usage
+
+```shell
+# Build op-program server-mode and MIPS-client binaries.
+cd ../op-program
+make op-program # build
+
+# Switch back to cannon, and build the CLI
+cd ../cannon
+go build -o cannon .
+
+# Transform MIPS op-program client binary into first VM state.
+# This outputs state.json (VM state) and meta.json (for debug symbols).
+./cannon load-elf --path=../op-program/bin/op-program-client.elf
+
+# Run cannon emulator (with example inputs)
+# Note that the server-mode op-program command is passed into cannon (after the --),
+# it runs as sub-process to provide the pre-image data.
+#
+# Note:
+#  - The L2 RPC is an archive L2 node on OP goerli.
+#  - The L1 RPC is a non-archive RPC, also change `--l1.rpckind` to reflect the correct L1 RPC type.
+./cannon run
+--pprof.cpu
+--info-at '%10000000'
+--proof-at never
+--input ./state.json
+--
+../op-program/bin/op-program
+--l2 http://127.0.0.1:8745
+--l1 http://127.0.0.1:8645
+--l1.trustrpc
+--l1.rpckind debug_geth
+--log.format terminal
+--l2.head 0xedc79de4d616a9100fdd42192224580daee81ea3d6303de8089d48a6c1bf4816
+--network goerli
+--l1.head 0x204f815790ca3bb43526ad60ebcc64784ec809bdc3550e82b54a0172f981efab
+--l2.claim 0x530658ab1b1b3ff4829731fc8d5955f0e6b8410db2cd65b572067ba58df1f2b9
+--l2.blocknumber 8813570
+--datadir /tmp/fpp-database
+--server
+
+# Add --proof-at '=12345' (or pick other pattern, see --help)
+# to pick a step to build a proof for (e.g. exact step, every N steps, etc.)
+
+# Also see `./cannon run --help` for more options
+```
+
+## Contracts
+
+The Cannon contracts:
+- `MIPS.sol`: A MIPS emulator implementation, to run a single instruction onchain, with merkleized VM memory.
+- `PreimageOracle.sol`: implements the pre-image oracle ABI, to support the instruction execution pre-image requests.
+
+The smart-contracts are integrated into the Optimism monorepo contracts:
+[`../packages/contracts-bedrock/contracts/cannon`](../packages/contracts-bedrock/contracts/cannon)
+
+## `mipsevm`
+
+`mipsevm` is Go tooling to test the onchain MIPS implementation, and generate proof data.
+
+## `example`
+
+Example programs that can be run and proven with Cannon.
+Optional dependency, but required for `mipsevm` Go tests.
+See [`example/Makefile`](./example/Makefile) for building the example MIPS binaries.
+
+## License
+
+MIT, see [`LICENSE`](./LICENSE) file.
+
+**Note: This code is unaudited.**
+In NO WAY should it be used to secure any monetary value before testing and auditing.
+This is experimental software, and should be treated as such.
+The authors of this project make no guarantees of security of ANY KIND.

cannon/cmd/json.go

+package cmd
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+)
+
+func loadJSON[X any](inputPath string) (*X, error) {
+	if inputPath == "" {
+		return nil, errors.New("no path specified")
+	}
+	f, err := os.OpenFile(inputPath, os.O_RDONLY, 0)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open file %q: %w", inputPath, err)
+	}
+	defer f.Close()
+	var state X
+	if err := json.NewDecoder(f).Decode(&state); err != nil {
+		return nil, fmt.Errorf("failed to decode file %q: %w", inputPath, err)
+	}
+	return &state, nil
+}
+
+func writeJSON[X any](outputPath string, value X, outIfEmpty bool) error {
+	var out io.Writer
+	if outputPath != "" {
+		f, err := os.OpenFile(outputPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0755)
+		if err != nil {
+			return fmt.Errorf("failed to open output file: %w", err)
+		}
+		defer f.Close()
+		out = f
+	} else if outIfEmpty {
+		out = os.Stdout
+	} else {
+		return nil
+	}
+	enc := json.NewEncoder(out)
+	if err := enc.Encode(value); err != nil {
+		return fmt.Errorf("failed to encode to JSON: %w", err)
+	}
+	_, err := out.Write([]byte{'\n'})
+	if err != nil {
+		return fmt.Errorf("failed to append new-line: %w", err)
+	}
+	return nil
+}

cannon/cmd/load_elf.go

+package cmd
+
+import (
+	"debug/elf"
+	"fmt"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/ethereum-optimism/optimism/cannon/mipsevm"
+)
+
+var (
+	LoadELFPathFlag = &cli.PathFlag{
+		Name:      "path",
+		Usage:     "Path to 32-bit big-endian MIPS ELF file",
+		TakesFile: true,
+		Required:  true,
+	}
+	LoadELFPatchFlag = &cli.StringSliceFlag{
+		Name:     "patch",
+		Usage:    "Type of patching to do",
+		Value:    cli.NewStringSlice("go", "stack"),
+		Required: false,
+	}
+	LoadELFOutFlag = &cli.PathFlag{
+		Name:     "out",
+		Usage:    "Output path to write JSON state to. State is dumped to stdout if set to empty string.",
+		Value:    "state.json",
+		Required: false,
+	}
+	LoadELFMetaFlag = &cli.PathFlag{
+		Name:     "meta",
+		Usage:    "Write metadata file, for symbol lookup during program execution. None if empty.",
+		Value:    "meta.json",
+		Required: false,
+	}
+)
+
+func LoadELF(ctx *cli.Context) error {
+	elfPath := ctx.Path(LoadELFPathFlag.Name)
+	elfProgram, err := elf.Open(elfPath)
+	if err != nil {
+		return fmt.Errorf("failed to open ELF file %q: %w", elfPath, err)
+	}
+	if elfProgram.Machine != elf.EM_MIPS {
+		return fmt.Errorf("ELF is not big-endian MIPS R3000, but got %q", elfProgram.Machine.String())
+	}
+	state, err := mipsevm.LoadELF(elfProgram)
+	if err != nil {
+		return fmt.Errorf("failed to load ELF data into VM state: %w", err)
+	}
+	for _, typ := range ctx.StringSlice(LoadELFPatchFlag.Name) {
+		switch typ {
+		case "stack":
+			err = mipsevm.PatchStack(state)
+		case "go":
+			err = mipsevm.PatchGo(elfProgram, state)
+		default:
+			return fmt.Errorf("unrecognized form of patching: %q", typ)
+		}
+		if err != nil {
+			return fmt.Errorf("failed to apply patch %s: %w", typ, err)
+		}
+	}
+	meta, err := mipsevm.MakeMetadata(elfProgram)
+	if err != nil {
+		return fmt.Errorf("failed to compute program metadata: %w", err)
+	}
+	if err := writeJSON[*mipsevm.Metadata](ctx.Path(LoadELFMetaFlag.Name), meta, false); err != nil {
+		return fmt.Errorf("failed to output metadata: %w", err)
+	}
+	return writeJSON[*mipsevm.State](ctx.Path(LoadELFOutFlag.Name), state, true)
+}
+
+var LoadELFCommand = &cli.Command{
+	Name:        "load-elf",
+	Usage:       "Load ELF file into Cannon JSON state",
+	Description: "Load ELF file into Cannon JSON state, optionally patch out functions",
+	Action:      LoadELF,
+	Flags: []cli.Flag{
+		LoadELFPathFlag,
+		LoadELFPatchFlag,
+		LoadELFOutFlag,
+		LoadELFMetaFlag,
+	},
+}

cannon/cmd/log.go

+package cmd
+
+import (
+	"io"
+
+	"github.com/ethereum/go-ethereum/log"
+)
+
+func Logger(w io.Writer, lvl log.Lvl) log.Logger {
+	h := log.StreamHandler(w, log.LogfmtFormat())
+	h = log.SyncHandler(h)
+	h = log.LvlFilterHandler(lvl, h)
+	l := log.New()
+	l.SetHandler(h)
+	return l
+}

cannon/cmd/matcher.go

+package cmd
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/ethereum-optimism/optimism/cannon/mipsevm"
+)
+
+type StepMatcher func(st *mipsevm.State) bool
+
+type StepMatcherFlag struct {
+	repr    string
+	matcher StepMatcher
+}
+
+func MustStepMatcherFlag(pattern string) *StepMatcherFlag {
+	out := new(StepMatcherFlag)
+	if err := out.Set(pattern); err != nil {
+		panic(err)
+	}
+	return out
+}
+
+func (m *StepMatcherFlag) Set(value string) error {
+	m.repr = value
+	if value == "" || value == "never" {
+		m.matcher = func(st *mipsevm.State) bool {
+			return false
+		}
+	} else if value == "always" {
+		m.matcher = func(st *mipsevm.State) bool {
+			return true
+		}
+	} else if strings.HasPrefix(value, "=") {
+		when, err := strconv.ParseUint(value[1:], 0, 64)
+		if err != nil {
+			return fmt.Errorf("failed to parse step number: %w", err)
+		}
+		m.matcher = func(st *mipsevm.State) bool {
+			return st.Step == when
+		}
+	} else if strings.HasPrefix(value, "%") {
+		when, err := strconv.ParseUint(value[1:], 0, 64)
+		if err != nil {
+			return fmt.Errorf("failed to parse step interval number: %w", err)
+		}
+		m.matcher = func(st *mipsevm.State) bool {
+			return st.Step%when == 0
+		}
+	} else {
+		return fmt.Errorf("unrecognized step matcher: %q", value)
+	}
+	return nil
+}
+
+func (m *StepMatcherFlag) String() string {
+	return m.repr
+}
+
+func (m *StepMatcherFlag) Matcher() StepMatcher {
+	if m.matcher == nil { // Set(value) is not called for omitted inputs, default to never matching.
+		return func(st *mipsevm.State) bool {
+			return false
+		}
+	}
+	return m.matcher
+}

cannon/cmd/run.go

+package cmd
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/log"
+	"github.com/urfave/cli/v2"
+
+	"github.com/pkg/profile"
+
+	"github.com/ethereum-optimism/optimism/cannon/mipsevm"
+	preimage "github.com/ethereum-optimism/optimism/op-preimage"
+)
+
+var (
+	RunInputFlag = &cli.PathFlag{
+		Name:      "input",
+		Usage:     "path of input JSON state. Stdin if left empty.",
+		TakesFile: true,
+		Value:     "state.json",
+		Required:  true,
+	}
+	RunOutputFlag = &cli.PathFlag{
+		Name:      "output",
+		Usage:     "path of output JSON state. Stdout if left empty.",
+		TakesFile: true,
+		Value:     "out.json",
+		Required:  false,
+	}
+	patternHelp    = "'never' (default), 'always', '=123' at exactly step 123, '%123' for every 123 steps"
+	RunProofAtFlag = &cli.GenericFlag{
+		Name:     "proof-at",
+		Usage:    "step pattern to output proof at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunProofFmtFlag = &cli.StringFlag{
+		Name:     "proof-fmt",
+		Usage:    "format for proof data output file names. Proof data is written to stdout if empty.",
+		Value:    "proof-%d.json",
+		Required: false,
+	}
+	RunSnapshotAtFlag = &cli.GenericFlag{
+		Name:     "snapshot-at",
+		Usage:    "step pattern to output snapshots at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunSnapshotFmtFlag = &cli.StringFlag{
+		Name:     "snapshot-fmt",
+		Usage:    "format for snapshot output file names.",
+		Value:    "state-%d.json",
+		Required: false,
+	}
+	RunStopAtFlag = &cli.GenericFlag{
+		Name:     "stop-at",
+		Usage:    "step pattern to stop at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunMetaFlag = &cli.PathFlag{
+		Name:     "meta",
+		Usage:    "path to metadata file for symbol lookup for enhanced debugging info durign execution.",
+		Value:    "meta.json",
+		Required: false,
+	}
+	RunInfoAtFlag = &cli.GenericFlag{
+		Name:     "info-at",
+		Usage:    "step pattern to print info at: " + patternHelp,
+		Value:    MustStepMatcherFlag("%100000"),
+		Required: false,
+	}
+	RunPProfCPU = &cli.BoolFlag{
+		Name:  "pprof.cpu",
+		Usage: "enable pprof cpu profiling",
+	}
+)
+
+type Proof struct {
+	Step uint64 `json:"step"`
+
+	Pre  common.Hash `json:"pre"`
+	Post common.Hash `json:"post"`
+
+	StepInput   hexutil.Bytes `json:"step-input"`
+	OracleInput hexutil.Bytes `json:"oracle-input"`
+}
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+type rawKey [32]byte
+
+func (rk rawKey) PreimageKey() [32]byte {
+	return rk
+}
+
+type ProcessPreimageOracle struct {
+	pCl *preimage.OracleClient
+	hCl *preimage.HintWriter
+	cmd *exec.Cmd
+}
+
+func NewProcessPreimageOracle(name string, args []string) (*ProcessPreimageOracle, error) {
+	if name == "" {
+		return &ProcessPreimageOracle{}, nil
+	}
+
+	pClientRW, pOracleRW, err := preimage.CreateBidirectionalChannel()
+	if err != nil {
+		return nil, err
+	}
+	hClientRW, hOracleRW, err := preimage.CreateBidirectionalChannel()
+	if err != nil {
+		return nil, err
+	}
+
+	cmd := exec.Command(name, args...) // nosemgrep
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.ExtraFiles = []*os.File{
+		hOracleRW.Reader(),
+		hOracleRW.Writer(),
+		pOracleRW.Reader(),
+		pOracleRW.Writer(),
+	}
+	out := &ProcessPreimageOracle{
+		pCl: preimage.NewOracleClient(pClientRW),
+		hCl: preimage.NewHintWriter(hClientRW),
+		cmd: cmd,
+	}
+	return out, nil
+}
+
+func (p *ProcessPreimageOracle) Hint(v []byte) {
+	if p.hCl == nil { // no hint processor
+		return
+	}
+	p.hCl.Hint(rawHint(v))
+}
+
+func (p *ProcessPreimageOracle) GetPreimage(k [32]byte) []byte {
+	if p.pCl == nil {
+		panic("no pre-image retriever available")
+	}
+	return p.pCl.Get(rawKey(k))
+}
+
+func (p *ProcessPreimageOracle) Start() error {
+	if p.cmd == nil {
+		return nil
+	}
+	return p.cmd.Start()
+}
+
+func (p *ProcessPreimageOracle) Close() error {
+	if p.cmd == nil {
+		return nil
+	}
+	_ = p.cmd.Process.Signal(os.Interrupt)
+	// Go 1.20 feature, to introduce later
+	//p.cmd.WaitDelay = time.Second * 10
+	err := p.cmd.Wait()
+	if err, ok := err.(*exec.ExitError); ok {
+		if err.Success() {
+			return nil
+		}
+	}
+	return err
+}
+
+type StepFn func(proof bool) (*mipsevm.StepWitness, error)
+
+func Guard(proc *os.ProcessState, fn StepFn) StepFn {
+	return func(proof bool) (*mipsevm.StepWitness, error) {
+		wit, err := fn(proof)
+		if err != nil {
+			if proc.Exited() {
+				return nil, fmt.Errorf("pre-image server exited with code %d, resulting in err %w", proc.ExitCode(), err)
+			} else {
+				return nil, err
+			}
+		}
+		return wit, nil
+	}
+}
+
+var _ mipsevm.PreimageOracle = (*ProcessPreimageOracle)(nil)
+
+func Run(ctx *cli.Context) error {
+	if ctx.Bool(RunPProfCPU.Name) {
+		defer profile.Start(profile.NoShutdownHook, profile.ProfilePath("."), profile.CPUProfile).Stop()
+	}
+
+	state, err := loadJSON[mipsevm.State](ctx.Path(RunInputFlag.Name))
+	if err != nil {
+		return err
+	}
+
+	l := Logger(os.Stderr, log.LvlInfo)
+	outLog := &mipsevm.LoggingWriter{Name: "program std-out", Log: l}
+	errLog := &mipsevm.LoggingWriter{Name: "program std-err", Log: l}
+
+	// split CLI args after first '--'
+	args := ctx.Args().Slice()
+	for i, arg := range args {
+		if arg == "--" {
+			args = args[i+1:]
+			break
+		}
+	}
+	if len(args) == 0 {
+		args = []string{""}
+	}
+
+	po, err := NewProcessPreimageOracle(args[0], args[1:])
+	if err != nil {
+		return fmt.Errorf("failed to create pre-image oracle process: %w", err)
+	}
+	if err := po.Start(); err != nil {
+		return fmt.Errorf("failed to start pre-image oracle server: %w", err)
+	}
+	defer func() {
+		if err := po.Close(); err != nil {
+			l.Error("failed to close pre-image server", "err", err)
+		}
+	}()
+
+	stopAt := ctx.Generic(RunStopAtFlag.Name).(*StepMatcherFlag).Matcher()
+	proofAt := ctx.Generic(RunProofAtFlag.Name).(*StepMatcherFlag).Matcher()
+	snapshotAt := ctx.Generic(RunSnapshotAtFlag.Name).(*StepMatcherFlag).Matcher()
+	infoAt := ctx.Generic(RunInfoAtFlag.Name).(*StepMatcherFlag).Matcher()
+
+	var meta *mipsevm.Metadata
+	if metaPath := ctx.Path(RunMetaFlag.Name); metaPath == "" {
+		l.Info("no metadata file specified, defaulting to empty metadata")
+		meta = &mipsevm.Metadata{Symbols: nil} // provide empty metadata by default
+	} else {
+		if m, err := loadJSON[mipsevm.Metadata](metaPath); err != nil {
+			return fmt.Errorf("failed to load metadata: %w", err)
+		} else {
+			meta = m
+		}
+	}
+
+	us := mipsevm.NewInstrumentedState(state, po, outLog, errLog)
+	proofFmt := ctx.String(RunProofFmtFlag.Name)
+	snapshotFmt := ctx.String(RunSnapshotFmtFlag.Name)
+
+	stepFn := us.Step
+	if po.cmd != nil {
+		stepFn = Guard(po.cmd.ProcessState, stepFn)
+	}
+
+	start := time.Now()
+	startStep := state.Step
+
+	// avoid symbol lookups every instruction by preparing a matcher func
+	sleepCheck := meta.SymbolMatcher("runtime.notesleep")
+
+	for !state.Exited {
+		if state.Step%100 == 0 { // don't do the ctx err check (includes lock) too often
+			if err := ctx.Context.Err(); err != nil {
+				return err
+			}
+		}
+
+		step := state.Step
+
+		if infoAt(state) {
+			delta := time.Since(start)
+			l.Info("processing",
+				"step", step,
+				"pc", mipsevm.HexU32(state.PC),
+				"insn", mipsevm.HexU32(state.Memory.GetMemory(state.PC)),
+				"ips", float64(step-startStep)/(float64(delta)/float64(time.Second)),
+				"pages", state.Memory.PageCount(),
+				"mem", state.Memory.Usage(),
+				"name", meta.LookupSymbol(state.PC),
+			)
+		}
+
+		if sleepCheck(state.PC) { // don't loop forever when we get stuck because of an unexpected bad program
+			return fmt.Errorf("got stuck in Go sleep at step %d", step)
+		}
+
+		if stopAt(state) {
+			break
+		}
+
+		if snapshotAt(state) {
+			if err := writeJSON[*mipsevm.State](fmt.Sprintf(snapshotFmt, step), state, false); err != nil {
+				return fmt.Errorf("failed to write state snapshot: %w", err)
+			}
+		}
+
+		if proofAt(state) {
+			preStateHash := crypto.Keccak256Hash(state.EncodeWitness())
+			witness, err := stepFn(true)
+			if err != nil {
+				return fmt.Errorf("failed at proof-gen step %d (PC: %08x): %w", step, state.PC, err)
+			}
+			postStateHash := crypto.Keccak256Hash(state.EncodeWitness())
+			proof := &Proof{
+				Step:      step,
+				Pre:       preStateHash,
+				Post:      postStateHash,
+				StepInput: witness.EncodeStepInput(),
+			}
+			if witness.HasPreimage() {
+				inp, err := witness.EncodePreimageOracleInput()
+				if err != nil {
+					return fmt.Errorf("failed to encode pre-image oracle input: %w", err)
+				}
+				proof.OracleInput = inp
+			}
+			if err := writeJSON[*Proof](fmt.Sprintf(proofFmt, step), proof, true); err != nil {
+				return fmt.Errorf("failed to write proof data: %w", err)
+			}
+		} else {
+			_, err = stepFn(false)
+			if err != nil {
+				return fmt.Errorf("failed at step %d (PC: %08x): %w", step, state.PC, err)
+			}
+		}
+	}
+
+	if err := writeJSON[*mipsevm.State](ctx.Path(RunOutputFlag.Name), state, true); err != nil {
+		return fmt.Errorf("failed to write state output: %w", err)
+	}
+	return nil
+}
+
+var RunCommand = &cli.Command{
+	Name:        "run",
+	Usage:       "Run VM step(s) and generate proof data to replicate onchain.",
+	Description: "Run VM step(s) and generate proof data to replicate onchain. See flags to match when to output a proof, a snapshot, or to stop early.",
+	Action:      Run,
+	Flags: []cli.Flag{
+		RunInputFlag,
+		RunOutputFlag,
+		RunProofAtFlag,
+		RunProofFmtFlag,
+		RunSnapshotAtFlag,
+		RunSnapshotFmtFlag,
+		RunStopAtFlag,
+		RunMetaFlag,
+		RunInfoAtFlag,
+		RunPProfCPU,
+	},
+}

cannon/docs/README.md

+# Cannon Overview
+
+Cannon has two main components:
+- Onchain `MIPS.sol`: EVM implementation to verify execution of a single MIPS instruction.
+- Offchain `mipsevm`: Go implementation to produce a proof for any MIPS instruction to verify onchain.
+
+Between these two modes of operation, the [witness data](#witness-data) is essential,
+to reproduce the same instruction onchain as offchain.
+
+## Onchain `MIPS.sol`
+
+This is an onchain implementation of big-endian 32-bit MIPS instruction execution.
+This covers MIPS III, R3000, as required by the `mips` Go compiler/runtime target.
+
+The systemcall instruction is implemented to simulate a minimal subset of the Linux kernel,
+just enough to serve the needs of a basic Go program:
+allocate memory, read/write to certain file-descriptors, and exit.
+
+Note that this does not include concurrency related system calls: when running Go programs,
+the GC has to be disabled, since it runs concurrently.
+This is done by patching out specific runtime functions that start the GC,
+by simply inserting jumps to the return-address, before the functions spin up any additional threads.
+
+
+## Offchain `mipsevm`
+
+This is an instrumented emulator, also running big-endian 32-bit MIPS, that executes one step at a time,
+and maintains the same state as used for onchain execution.
+The difference is that it has access to the full memory, and pre-image oracle.
+And as it executes each step, it can optionally produce the witness data for the step, to repeat it onchain.
+
+The Cannon CLI is used to load a program into an initial state,
+transition it N steps quickly without witness generation, and 1 step while producing a witness.
+
+`mipsevm` is backed by the Unicorn emulator, but instrumented for proof generation,
+and handles delay-slots by isolating each individual instruction and tracking `nextPC`
+to emulate the delayed `PC` changes after delay-slot execution.
+
+## Witness Data
+
+There are 3 types of witness data involved in onchain execution:
+- [Packed State](#packed-state)
+- [Memory proofs](#memory-proofs)
+- [Pre-image data](#pre-image-data)
+
+### Packed State
+
+The following state is packed together, and provided in every executed onchain instruction:
+```solidity
+struct State {
+  bytes32 memRoot;
+  bytes32 preimageKey;
+  uint32 preimageOffset;
+  uint32 pc;
+  uint32 nextPC;
+  uint32 lo;
+  uint32 hi;
+  uint32 heap;
+  uint8 exitCode;
+  bool exited;
+  uint64 step;
+  uint32[32] registers;
+}
+```
+
+The packed state is small! The `State` data can be packed in such a small amount of EVM words,
+that it is more efficient to fully provide it, than to create a proof for each individual part involved in execution.
+
+The memory is represented as a merkle-tree root, committing to a binary merkle tree of all memory data,
+see [memory proofs](#memory-proofs).
+
+The `State` covers all general purpose registers, as well as the `lo`, `hi` and `pc` values.
+
+`nextPC` helps pre-schedule the program counter change, to emulate delay-slot behavior of MIPS
+after branch and jump instructions.
+
+The program stops changing the state when `exited` is set to true. The exit-code is remembered,
+to determine if the program is successful, or panicked/exited in some unexpected way.
+This outcome can be used to determine truthiness of claims that are verified as part of the program execution.
+
+The `heap` value is a special value, used to emulate a growing heap, to map new memory upon `mmap` calls by the program.
+No memory reads/writes are actually illegal however, mmap-ing is purely to satisfy program runtimes that
+need the memory-pointer result of the syscall to locate free memory.
+
+The `preimageKey` and `preimageOffset` are backing the in-flight communication of [pre-image data](#pre-image-data).
+
+The VM `stateHash` is computed as `keccak256(encoded_packed_state)`,
+where `encoded_packed_state` is the concatenation of all state-values (all `uint` values are big-endian).
+
+
+### Memory proofs
+
+Simplicity is key here. Previous versions of Cannon used to overlap memory and register state,
+and represent it with a Merkle Patricia Trie.
+This added a lot of complexity, as there would be multiple dynamically-sized MPT proofs,
+with read and write operations, during a single instruction.
+
+Instead, memory in Cannon is now represented as a binary merkle tree:
+The tree has a fixed-depth of 27 levels, with leaf values of 32 bytes each.
+This spans the full 32-bit address space: `2**27 * 32 = 2**32`.
+Each leaf contains the memory at that part of the tree.
+
+The tree is efficiently allocated, since the root of fully zeroed sub-trees
+can be computed without actually creating the full-subtree: `zero_hash[d] = hash(zero_hash[d-1], zero_hash[d-1])`,
+until the base-case of `zero_hash[0] == bytes32(0)`.
+
+Nodes in this memory tree are combined as: `out = keccak256(left ++ right)`, where `++` is concatenation,
+and `left` and `right` are the 32-byte outputs of the respective sub-trees or the leaf values themselves.
+Individual leaf nodes are not hashed.
+
+The proof format is a concatenated byte array of 28 `bytes32`. The first `bytes32` is the leaf value,
+and the remaining 27 `bytes32` are the sibling nodes up till the root of the tree,
+along the branch of the leaf value, starting from the bottom.
+
+To verify the proof, start with the leaf value as `node`, and combine it with respective sibling values:
+`node = keccak256(node ++ sibling)` or `node = keccak256(sibling ++ node)`,
+depending the position of `node` at that level of the tree.
+
+During the onchain execution, each instruction only executes 1 or 2 memory reads, followed by 0 or 1 writes,
+where the write is over the same memory as was last read.
+
+The memory access is specifically:
+- instruction (4 byte) read at `PC`
+- load or syscall mem read, always aligned 4 bytes, read at any `addr`
+- store or syscall mem write, always aligned 4 bytes, at ths same `addr`
+
+Writing only once, at the last read leaf, also means that the leaf can be safely updated and the same proof-data
+that was used to verify the read, can be used to reconstruct the new `memRoot` of the memory tree,
+since all sibling data that is combined with the new leaf value was already authenticated during the read part.
+
+### Pre-image data
+
+Pre-image data is accessed through syscalls exclusively.
+The OP-stack fault-proof [Pre-image Oracle specs](../../specs/fault-proof.md#pre-image-oracle)
+define the ABI for communicating pre-images.
+
+This ABI is implemented by the VM by intercepting the `read`/`write` syscalls to specific file descriptors:
+- `hint client read = 3`: used by the client to send hint data to the host. Optional, implemented as blocking.
+- `hint client write = 4`: used by the client to wait for the host. Always instant, since the above is implemented as blocking.
+- `preimage client read = 5`: used by the client to read pre-image data, starting from the latest pre-image reading offset.
+- `preimage client write = 6`: used by the client to change the pre-image key. The key may change a little bit at a time. The last 32 written bytes count as key for retrieval when reading the pre-image. Changing the key also resets the read offset to 0.
+
+The data is loaded into `PreimageOracle.sol` using the respective loading function based on the pre-image type.
+And then retrieved during execution of the `read` syscall.
+
+Note that although the oracle provides up to 32 bytes of the pre-image,
+Cannon only supports reading at most 4 bytes at a time, to unify the memory operations with regular load/stores.
+
+
+## Usage in Dispute Game
+
+The onchain MIPS execution functions as base-case of an interactive dispute game.
+The dispute game narrows down a sequence of disputed instructions to a single disputed instruction.
+This instruction can then be executed onchain to determine objective truth.
+
+The Dispute Game itself is out of scope for Cannon: Cannon is just one example of a fault-proof VM that
+can be used to resolve disputes.

cannon/example/Makefile

+all: elf dump
+
+.PHONY: elf
+elf: $(patsubst %/go.mod,bin/%.elf,$(wildcard */go.mod))
+
+.PHONY: dump
+dump: $(patsubst %/go.mod,bin/%.dump,$(wildcard */go.mod))
+
+bin:
+	mkdir bin
+
+# take any directory with a go mod, and build an ELF
+# verify output with: readelf -h bin/<name>.elf
+# result is mips32, big endian, R3000
+bin/%.elf: bin
+	cd $(@:bin/%.elf=%) && GOOS=linux GOARCH=mips GOMIPS=softfloat go build -o ../$@ .
+
+# take any ELF and dump it
+# TODO: currently have the little-endian toolchain, but should use the big-endian one. The -EB compat flag works though.
+bin/%.dump: bin/%.elf
+	mipsel-linux-gnu-objdump -D --disassembler-options=no-aliases --wide --source -m mips:3000 -EB $(@:%.dump=%.elf) > $@

cannon/example/claim/go.mod

+module claim
+
+go 1.20
+
+require github.com/ethereum-optimism/optimism v0.0.0
+
+require (
+	golang.org/x/crypto v0.8.0 // indirect
+	golang.org/x/sys v0.7.0 // indirect
+)
+
+replace github.com/ethereum-optimism/optimism v0.0.0 => ../../..

cannon/example/claim/go.sum

+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+golang.org/x/crypto v0.8.0 h1:pd9TJtTueMTVQXzk8E2XESSMQDj/U7OUu0PqJqPXQjQ=
+golang.org/x/crypto v0.8.0/go.mod h1:mRqEX+O9/h5TFCrQhkgjo2yKi0yYA+9ecGkdQoHrywE=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

cannon/example/claim/main.go

+package main
+
+import (
+	"encoding/binary"
+	"fmt"
+	"os"
+
+	"github.com/ethereum-optimism/optimism/op-preimage"
+)
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+func main() {
+	_, _ = os.Stderr.Write([]byte("started!"))
+
+	po := preimage.NewOracleClient(preimage.ClientPreimageChannel())
+	hinter := preimage.NewHintWriter(preimage.ClientHinterChannel())
+
+	preHash := *(*[32]byte)(po.Get(preimage.LocalIndexKey(0)))
+	diffHash := *(*[32]byte)(po.Get(preimage.LocalIndexKey(1)))
+	claimData := *(*[8]byte)(po.Get(preimage.LocalIndexKey(2)))
+
+	// Hints are used to indicate which things the program will access,
+	// so the server can be prepared to serve the corresponding pre-images.
+	hinter.Hint(rawHint(fmt.Sprintf("fetch-state %x", preHash)))
+	pre := po.Get(preimage.Keccak256Key(preHash))
+
+	// Multiple pre-images may be fetched based on a hint.
+	// E.g. when we need all values of a merkle-tree.
+	hinter.Hint(rawHint(fmt.Sprintf("fetch-diff %x", diffHash)))
+	diff := po.Get(preimage.Keccak256Key(diffHash))
+	diffPartA := po.Get(preimage.Keccak256Key(*(*[32]byte)(diff[:32])))
+	diffPartB := po.Get(preimage.Keccak256Key(*(*[32]byte)(diff[32:])))
+
+	// Example state-transition function: s' = s*a + b
+	s := binary.BigEndian.Uint64(pre)
+	a := binary.BigEndian.Uint64(diffPartA)
+	b := binary.BigEndian.Uint64(diffPartB)
+	fmt.Printf("computing %d * %d + %d\n", s, a, b)
+	sOut := s*a + b
+
+	sClaim := binary.BigEndian.Uint64(claimData[:])
+	if sOut != sClaim {
+		fmt.Printf("claim %d is bad! Correct result is %d\n", sOut, sClaim)
+		os.Exit(1)
+	} else {
+		fmt.Printf("claim %d is good!\n", sOut)
+		os.Exit(0)
+	}
+}

cannon/example/hello/go.mod

+module hello
+

cannon/example/hello/main.go

+package main
+
+import "os"
+
+func main() {
+	_, _ = os.Stdout.Write([]byte("hello world!\n"))
+}

cannon/main.go

+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/ethereum-optimism/optimism/cannon/cmd"
+)
+
+func main() {
+	app := cli.NewApp()
+	app.Name = "cannon"
+	app.Usage = "MIPS Fault Proof tool"
+	app.Description = "MIPS Fault Proof tool"
+	app.Commands = []*cli.Command{
+		cmd.LoadELFCommand,
+		cmd.RunCommand,
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		for {
+			<-c
+			cancel()
+			fmt.Println("\r\nExiting...")
+		}
+	}()
+
+	err := app.RunContext(ctx, os.Args)
+	if err != nil {
+		if errors.Is(err, ctx.Err()) {
+			_, _ = fmt.Fprintf(os.Stderr, "command interrupted")
+			os.Exit(130)
+		} else {
+			_, _ = fmt.Fprintf(os.Stderr, "error: %v", err)
+			os.Exit(1)
+		}
+	}
+}

cannon/mipsevm/.gitignore

+mipsevm
+mipsevm.test
+*.prof

cannon/mipsevm/README.md

+# `mipsevm`
+
+Supported 55 instructions:
+```
+'addi', 'addiu', 'addu', 'and', 'andi',
+'b', 'beq', 'beqz', 'bgez', 'bgtz', 'blez', 'bltz', 'bne', 'bnez',
+'clz', 'divu',
+'j', 'jal', 'jalr', 'jr',
+'lb', 'lbu', 'lui', 'lw', 'lwr',
+'mfhi', 'mflo', 'move', 'movn', 'movz', 'mtlo', 'mul', 'multu',
+'negu', 'nop', 'not', 'or', 'ori',
+'sb', 'sll', 'sllv', 'slt', 'slti', 'sltiu', 'sltu', 'sra', 'srl', 'srlv', 'subu', 'sw', 'swr', 'sync', 'syscall',
+'xor', 'xori'
+```
+
+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.
+4. Implement the `PreimageOracle` interface
+5. Instrument the emulator with the state, and pre-image oracle, using `NewInstrumentedState`
+6. Step through the instrumented state with `Step(proof)`,
+   where `proof==true` if witness data should be generated. Steps are faster with `proof==false`.
+7. Optionally repeat the step on-chain by calling `MIPS.sol` and `PreimageOracle.sol`, using the above witness data.

cannon/mipsevm/evm.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"math/big"
+	"os"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/consensus"
+	"github.com/ethereum/go-ethereum/consensus/ethash"
+	"github.com/ethereum/go-ethereum/core"
+	"github.com/ethereum/go-ethereum/core/rawdb"
+	"github.com/ethereum/go-ethereum/core/state"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/vm"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/params"
+
+	"github.com/ethereum-optimism/optimism/op-bindings/bindings"
+	"github.com/ethereum-optimism/optimism/op-chain-ops/srcmap"
+)
+
+var (
+	StepBytes4                      = crypto.Keccak256([]byte("Step(bytes,bytes)"))[:4]
+	CheatBytes4                     = crypto.Keccak256([]byte("cheat(uint256,bytes32,bytes32,uint256)"))[:4]
+	LoadKeccak256PreimagePartBytes4 = crypto.Keccak256([]byte("loadKeccak256PreimagePart(uint256,bytes)"))[:4]
+)
+
+// LoadContracts loads the Cannon contracts, from op-bindings package
+func LoadContracts() (*Contracts, error) {
+	var mips, oracle Contract
+	mips.DeployedBytecode.Object = hexutil.MustDecode(bindings.MIPSDeployedBin)
+	mips.DeployedBytecode.SourceMap = bindings.MIPSDeployedSourceMap
+	oracle.DeployedBytecode.Object = hexutil.MustDecode(bindings.PreimageOracleDeployedBin)
+	oracle.DeployedBytecode.SourceMap = bindings.PreimageOracleDeployedSourceMap
+	return &Contracts{
+		MIPS:   &mips,
+		Oracle: &oracle,
+	}, nil
+}
+
+// LoadContractsFromFiles loads the Cannon contracts, from local filesystem
+func LoadContractsFromFiles() (*Contracts, error) {
+	mips, err := LoadContract("MIPS")
+	if err != nil {
+		return nil, err
+	}
+	oracle, err := LoadContract("Oracle")
+	if err != nil {
+		return nil, err
+	}
+	return &Contracts{
+		MIPS:   mips,
+		Oracle: oracle,
+	}, nil
+}
+
+func LoadContract(name string) (*Contract, error) {
+	dat, err := os.ReadFile(fmt.Sprintf("../../packages/contracts-bedrock/forge-artifacts/%s.sol/%s.json", name, name))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read contract JSON definition of %q: %w", name, err)
+	}
+	var out Contract
+	if err := json.Unmarshal(dat, &out); err != nil {
+		return nil, fmt.Errorf("failed to parse contract JSON definition of %q: %w", name, err)
+	}
+	return &out, nil
+}
+
+type Contract struct {
+	DeployedBytecode struct {
+		Object    hexutil.Bytes `json:"object"`
+		SourceMap string        `json:"sourceMap"`
+	} `json:"deployedBytecode"`
+
+	// ignore abi,bytecode,etc.
+}
+
+func (c *Contract) SourceMap(sourcePaths []string) (*srcmap.SourceMap, error) {
+	return srcmap.ParseSourceMap(sourcePaths, c.DeployedBytecode.Object, c.DeployedBytecode.SourceMap)
+}
+
+type Contracts struct {
+	MIPS   *Contract
+	Oracle *Contract
+}
+
+type Addresses struct {
+	MIPS         common.Address
+	Oracle       common.Address
+	Sender       common.Address
+	FeeRecipient common.Address
+}
+
+func NewEVMEnv(contracts *Contracts, addrs *Addresses) (*vm.EVM, *state.StateDB) {
+	chainCfg := params.MainnetChainConfig
+	offsetBlocks := uint64(1000) // blocks after shanghai fork
+	bc := &testChain{startTime: *chainCfg.ShanghaiTime + offsetBlocks*12}
+	header := bc.GetHeader(common.Hash{}, 17034870+offsetBlocks)
+	db := rawdb.NewMemoryDatabase()
+	statedb := state.NewDatabase(db)
+	state, err := state.New(types.EmptyRootHash, statedb, nil)
+	if err != nil {
+		panic(fmt.Errorf("failed to create memory state db: %w", err))
+	}
+	blockContext := core.NewEVMBlockContext(header, bc, nil, chainCfg, state)
+	vmCfg := vm.Config{}
+
+	env := vm.NewEVM(blockContext, vm.TxContext{}, state, chainCfg, vmCfg)
+	// pre-deploy the contracts
+	env.StateDB.SetCode(addrs.MIPS, contracts.MIPS.DeployedBytecode.Object)
+	env.StateDB.SetCode(addrs.Oracle, contracts.Oracle.DeployedBytecode.Object)
+	env.StateDB.SetState(addrs.MIPS, common.Hash{}, addrs.Oracle.Hash())
+
+	rules := env.ChainConfig().Rules(header.Number, true, header.Time)
+	env.StateDB.Prepare(rules, addrs.Sender, addrs.FeeRecipient, &addrs.MIPS, vm.ActivePrecompiles(rules), nil)
+	return env, state
+}
+
+type testChain struct {
+	startTime uint64
+}
+
+func (d *testChain) Engine() consensus.Engine {
+	return ethash.NewFullFaker()
+}
+
+func (d *testChain) GetHeader(h common.Hash, n uint64) *types.Header {
+	parentHash := common.Hash{0: 0xff}
+	binary.BigEndian.PutUint64(parentHash[1:], n-1)
+	return &types.Header{
+		ParentHash:      parentHash,
+		UncleHash:       types.EmptyUncleHash,
+		Coinbase:        common.Address{},
+		Root:            common.Hash{},
+		TxHash:          types.EmptyTxsHash,
+		ReceiptHash:     types.EmptyReceiptsHash,
+		Bloom:           types.Bloom{},
+		Difficulty:      big.NewInt(0),
+		Number:          new(big.Int).SetUint64(n),
+		GasLimit:        30_000_000,
+		GasUsed:         0,
+		Time:            d.startTime + n*12,
+		Extra:           nil,
+		MixDigest:       common.Hash{},
+		Nonce:           types.BlockNonce{},
+		BaseFee:         big.NewInt(7),
+		WithdrawalsHash: &types.EmptyWithdrawalsHash,
+	}
+}

cannon/mipsevm/evm_test.go

+package mipsevm
+
+import (
+	"bytes"
+	"debug/elf"
+	"io"
+	"math/big"
+	"os"
+	"path"
+	"testing"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/vm"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/eth/tracers/logger"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ethereum-optimism/optimism/op-chain-ops/srcmap"
+)
+
+func testContractsSetup(t *testing.T) (*Contracts, *Addresses) {
+	contracts, err := LoadContracts()
+	require.NoError(t, err)
+
+	addrs := &Addresses{
+		MIPS:         common.Address{0: 0xff, 19: 1},
+		Oracle:       common.Address{0: 0xff, 19: 2},
+		Sender:       common.Address{0x13, 0x37},
+		FeeRecipient: common.Address{0xaa},
+	}
+
+	return contracts, addrs
+}
+
+func SourceMapTracer(t *testing.T, contracts *Contracts, addrs *Addresses) vm.EVMLogger {
+	mipsSrcMap, err := contracts.MIPS.SourceMap([]string{"../../packages/contracts-bedrock/contracts/cannon/MIPS.sol"})
+	require.NoError(t, err)
+	oracleSrcMap, err := contracts.Oracle.SourceMap([]string{"../../packages/contracts-bedrock/contracts/cannon/PreimageOracle.sol"})
+	require.NoError(t, err)
+
+	return srcmap.NewSourceMapTracer(map[common.Address]*srcmap.SourceMap{addrs.MIPS: mipsSrcMap, addrs.Oracle: oracleSrcMap}, os.Stdout)
+}
+
+func MarkdownTracer() vm.EVMLogger {
+	return logger.NewMarkdownLogger(&logger.Config{}, os.Stdout)
+}
+
+func TestEVM(t *testing.T) {
+	testFiles, err := os.ReadDir("open_mips_tests/test/bin")
+	require.NoError(t, err)
+
+	contracts, addrs := testContractsSetup(t)
+	var tracer vm.EVMLogger // no-tracer by default, but see SourceMapTracer and MarkdownTracer
+	//tracer = SourceMapTracer(t, contracts, addrs)
+	sender := common.Address{0x13, 0x37}
+
+	for _, f := range testFiles {
+		t.Run(f.Name(), func(t *testing.T) {
+			if f.Name() == "oracle.bin" {
+				t.Skip("oracle test needs to be updated to use syscall pre-image oracle")
+			}
+
+			env, evmState := NewEVMEnv(contracts, addrs)
+			env.Config.Tracer = tracer
+
+			fn := path.Join("open_mips_tests/test/bin", f.Name())
+			programMem, err := os.ReadFile(fn)
+			require.NoError(t, err)
+			state := &State{PC: 0, NextPC: 4, Memory: NewMemory()}
+			err = state.Memory.SetMemoryRange(0, bytes.NewReader(programMem))
+			require.NoError(t, err, "load program into state")
+
+			// set the return address ($ra) to jump into when test completes
+			state.Registers[31] = endAddr
+
+			us := NewInstrumentedState(state, nil, os.Stdout, os.Stderr)
+
+			for i := 0; i < 1000; i++ {
+				if us.state.PC == endAddr {
+					break
+				}
+				insn := state.Memory.GetMemory(state.PC)
+				t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+
+				stepWitness, err := us.Step(true)
+				require.NoError(t, err)
+				input := stepWitness.EncodeStepInput()
+				startingGas := uint64(30_000_000)
+
+				// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+				snap := env.StateDB.Snapshot()
+				ret, leftOverGas, err := env.Call(vm.AccountRef(sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+				require.NoError(t, err, "evm should not fail")
+				require.Len(t, ret, 32, "expecting 32-byte state hash")
+				// remember state hash, to check it against state
+				postHash := common.Hash(*(*[32]byte)(ret))
+				logs := evmState.Logs()
+				require.Equal(t, 1, len(logs), "expecting a log with post-state")
+				evmPost := logs[0].Data
+				require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+				env.StateDB.RevertToSnapshot(snap)
+
+				t.Logf("EVM step took %d gas, and returned stateHash %s", startingGas-leftOverGas, postHash)
+
+				// verify the post-state matches.
+				// TODO: maybe more readable to decode the evmPost state, and do attribute-wise comparison.
+				uniPost := us.state.EncodeWitness()
+				require.Equal(t, hexutil.Bytes(uniPost).String(), hexutil.Bytes(evmPost).String(),
+					"unicorn produced different state than EVM")
+			}
+			require.Equal(t, uint32(endAddr), state.PC, "must reach end")
+			// inspect test result
+			done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
+			require.Equal(t, done, uint32(1), "must be done")
+			require.Equal(t, result, uint32(1), "must have success result")
+		})
+	}
+}
+
+func TestHelloEVM(t *testing.T) {
+	contracts, addrs := testContractsSetup(t)
+	var tracer vm.EVMLogger // no-tracer by default, but see SourceMapTracer and MarkdownTracer
+	//tracer = SourceMapTracer(t, contracts, addrs)
+	sender := common.Address{0x13, 0x37}
+
+	elfProgram, err := elf.Open("../example/bin/hello.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, nil, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	env, evmState := NewEVMEnv(contracts, addrs)
+	env.Config.Tracer = tracer
+
+	start := time.Now()
+	for i := 0; i < 400_000; i++ {
+		if us.state.Exited {
+			break
+		}
+		insn := state.Memory.GetMemory(state.PC)
+		if i%1000 == 0 { // avoid spamming test logs, we are executing many steps
+			t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+		}
+
+		stepWitness, err := us.Step(true)
+		require.NoError(t, err)
+		input := stepWitness.EncodeStepInput()
+		startingGas := uint64(30_000_000)
+
+		// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+		snap := env.StateDB.Snapshot()
+		ret, leftOverGas, err := env.Call(vm.AccountRef(sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+		require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		require.Len(t, ret, 32, "expecting 32-byte state hash")
+		// remember state hash, to check it against state
+		postHash := common.Hash(*(*[32]byte)(ret))
+		logs := evmState.Logs()
+		require.Equal(t, 1, len(logs), "expecting a log with post-state")
+		evmPost := logs[0].Data
+		require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+		env.StateDB.RevertToSnapshot(snap)
+
+		//t.Logf("EVM step took %d gas, and returned stateHash %s", startingGas-leftOverGas, postHash)
+
+		// verify the post-state matches.
+		// TODO: maybe more readable to decode the evmPost state, and do attribute-wise comparison.
+		uniPost := us.state.EncodeWitness()
+		require.Equal(t, hexutil.Bytes(uniPost).String(), hexutil.Bytes(evmPost).String(),
+			"unicorn produced different state than EVM")
+	}
+	end := time.Now()
+	delta := end.Sub(start)
+	t.Logf("test took %s, %d instructions, %s per instruction", delta, state.Step, delta/time.Duration(state.Step))
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, "hello world!\n", stdOutBuf.String(), "stdout says hello")
+	require.Equal(t, "", stdErrBuf.String(), "stderr silent")
+}
+
+func TestClaimEVM(t *testing.T) {
+	contracts, addrs := testContractsSetup(t)
+	var tracer vm.EVMLogger // no-tracer by default, but see SourceMapTracer and MarkdownTracer
+	//tracer = SourceMapTracer(t, contracts, addrs)
+
+	elfProgram, err := elf.Open("../example/bin/claim.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	oracle, expectedStdOut, expectedStdErr := claimTestOracle(t)
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, oracle, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	env, evmState := NewEVMEnv(contracts, addrs)
+	env.Config.Tracer = tracer
+
+	for i := 0; i < 2000_000; i++ {
+		if us.state.Exited {
+			break
+		}
+
+		insn := state.Memory.GetMemory(state.PC)
+		if i%1000 == 0 { // avoid spamming test logs, we are executing many steps
+			t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+		}
+
+		stepWitness, err := us.Step(true)
+		require.NoError(t, err)
+		input := stepWitness.EncodeStepInput()
+		startingGas := uint64(30_000_000)
+
+		// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+		snap := env.StateDB.Snapshot()
+
+		// prepare pre-image oracle data, if any
+		if stepWitness.HasPreimage() {
+			poInput, err := stepWitness.EncodePreimageOracleInput()
+			require.NoError(t, err, "encode preimage oracle input")
+			_, leftOverGas, err := env.Call(vm.AccountRef(addrs.Sender), addrs.Oracle, poInput, startingGas, big.NewInt(0))
+			require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		}
+
+		ret, leftOverGas, err := env.Call(vm.AccountRef(addrs.Sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+		require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		require.Len(t, ret, 32, "expecting 32-byte state hash")
+		// remember state hash, to check it against state
+		postHash := common.Hash(*(*[32]byte)(ret))
+		logs := evmState.Logs()
+		require.Equal(t, 1, len(logs), "expecting a log with post-state")
+		evmPost := logs[0].Data
+		require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+		env.StateDB.RevertToSnapshot(snap)
+	}
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, expectedStdOut, stdOutBuf.String(), "stdout")
+	require.Equal(t, expectedStdErr, stdErrBuf.String(), "stderr")
+}

cannon/mipsevm/instrumented.go

+package mipsevm
+
+import (
+	"io"
+)
+
+type PreimageOracle interface {
+	Hint(v []byte)
+	GetPreimage(k [32]byte) []byte
+}
+
+type InstrumentedState struct {
+	state *State
+
+	stdOut io.Writer
+	stdErr io.Writer
+
+	lastMemAccess   uint32
+	memProofEnabled bool
+	memProof        [28 * 32]byte
+
+	preimageOracle PreimageOracle
+
+	// cached pre-image data, including 8 byte length prefix
+	lastPreimage []byte
+	// key for above preimage
+	lastPreimageKey [32]byte
+	// offset we last read from, or max uint32 if nothing is read this step
+	lastPreimageOffset uint32
+}
+
+const (
+	fdStdin         = 0
+	fdStdout        = 1
+	fdStderr        = 2
+	fdHintRead      = 3
+	fdHintWrite     = 4
+	fdPreimageRead  = 5
+	fdPreimageWrite = 6
+)
+
+const (
+	MipsEBADF  = 0x9
+	MipsEINVAL = 0x16
+)
+
+func NewInstrumentedState(state *State, po PreimageOracle, stdOut, stdErr io.Writer) *InstrumentedState {
+	return &InstrumentedState{
+		state:          state,
+		stdOut:         stdOut,
+		stdErr:         stdErr,
+		preimageOracle: po,
+	}
+}
+
+func (m *InstrumentedState) Step(proof bool) (wit *StepWitness, err error) {
+	m.memProofEnabled = proof
+	m.lastMemAccess = ^uint32(0)
+	m.lastPreimageOffset = ^uint32(0)
+
+	if proof {
+		insnProof := m.state.Memory.MerkleProof(m.state.PC)
+		wit = &StepWitness{
+			State:    m.state.EncodeWitness(),
+			MemProof: insnProof[:],
+		}
+	}
+	err = m.mipsStep()
+	if err != nil {
+		return nil, err
+	}
+
+	if proof {
+		wit.MemProof = append(wit.MemProof, m.memProof[:]...)
+		if m.lastPreimageOffset != ^uint32(0) {
+			wit.PreimageOffset = m.lastPreimageOffset
+			wit.PreimageKey = m.lastPreimageKey
+			wit.PreimageValue = m.lastPreimage
+		}
+	}
+	return
+}

cannon/mipsevm/logw.go

+package mipsevm
+
+import (
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/log"
+)
+
+// 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.
+type LoggingWriter struct {
+	Name string
+	Log  log.Logger
+}
+
+func logAsText(b string) bool {
+	for _, c := range b {
+		if (c < 0x20 || c >= 0x7F) && (c != '\n' && c != '\t') {
+			return false
+		}
+	}
+	return true
+}
+
+func (lw *LoggingWriter) Write(b []byte) (int, error) {
+	t := string(b)
+	if logAsText(t) {
+		lw.Log.Info("", "text", t)
+	} else {
+		lw.Log.Info("", "data", hexutil.Bytes(b))
+	}
+	return len(b), nil
+}

cannon/mipsevm/memory.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/bits"
+	"sort"
+
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+// Note: 2**12 = 4 KiB, the minimum page-size in Unicorn for mmap
+// as well as the Go runtime min phys page size.
+const (
+	PageAddrSize = 12
+	PageKeySize  = 32 - PageAddrSize
+	PageSize     = 1 << PageAddrSize
+	PageAddrMask = PageSize - 1
+	MaxPageCount = 1 << PageKeySize
+	PageKeyMask  = MaxPageCount - 1
+)
+
+func HashPair(left, right [32]byte) [32]byte {
+	out := crypto.Keccak256Hash(left[:], right[:])
+	//fmt.Printf("0x%x 0x%x -> 0x%x\n", left, right, out)
+	return out
+}
+
+var zeroHashes = func() [256][32]byte {
+	// empty parts of the tree are all zero. Precompute the hash of each full-zero range sub-tree level.
+	var out [256][32]byte
+	for i := 1; i < 256; i++ {
+		out[i] = HashPair(out[i-1], out[i-1])
+	}
+	return out
+}()
+
+type Memory struct {
+	// generalized index -> merkle root or nil if invalidated
+	nodes map[uint64]*[32]byte
+
+	// pageIndex -> cached page
+	pages map[uint32]*CachedPage
+
+	// Note: since we don't de-alloc pages, we don't do ref-counting.
+	// Once a page exists, it doesn't leave memory
+
+	// two caches: we often read instructions from one page, and do memory things with another page.
+	// this prevents map lookups each instruction
+	lastPageKeys [2]uint32
+	lastPage     [2]*CachedPage
+}
+
+func NewMemory() *Memory {
+	return &Memory{
+		nodes:        make(map[uint64]*[32]byte),
+		pages:        make(map[uint32]*CachedPage),
+		lastPageKeys: [2]uint32{^uint32(0), ^uint32(0)}, // default to invalid keys, to not match any pages
+	}
+}
+
+func (m *Memory) PageCount() int {
+	return len(m.pages)
+}
+
+func (m *Memory) ForEachPage(fn func(pageIndex uint32, page *Page) error) error {
+	for pageIndex, cachedPage := range m.pages {
+		if err := fn(pageIndex, cachedPage.Data); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (m *Memory) Invalidate(addr uint32) {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+
+	// find page, and invalidate addr within it
+	if p, ok := m.pageLookup(addr >> PageAddrSize); ok {
+		prevValid := p.Ok[1]
+		p.Invalidate(addr & PageAddrMask)
+		if !prevValid { // if the page was already invalid before, then nodes to mem-root will also still be.
+			return
+		}
+	} else { // no page? nothing to invalidate
+		return
+	}
+
+	// find the gindex of the first page covering the address
+	gindex := ((uint64(1) << 32) | uint64(addr)) >> PageAddrSize
+
+	for gindex > 0 {
+		m.nodes[gindex] = nil
+		gindex >>= 1
+	}
+}
+
+func (m *Memory) MerkleizeSubtree(gindex uint64) [32]byte {
+	l := uint64(bits.Len64(gindex))
+	if l > 28 {
+		panic("gindex too deep")
+	}
+	if l > PageKeySize {
+		depthIntoPage := l - 1 - PageKeySize
+		pageIndex := (gindex >> depthIntoPage) & PageKeyMask
+		if p, ok := m.pages[uint32(pageIndex)]; ok {
+			pageGindex := (1 << depthIntoPage) | (gindex & ((1 << depthIntoPage) - 1))
+			return p.MerkleizeSubtree(pageGindex)
+		} else {
+			return zeroHashes[28-l] // page does not exist
+		}
+	}
+	if l > PageKeySize+1 {
+		panic("cannot jump into intermediate node of page")
+	}
+	n, ok := m.nodes[gindex]
+	if !ok {
+		// if the node doesn't exist, the whole sub-tree is zeroed
+		return zeroHashes[28-l]
+	}
+	if n != nil {
+		return *n
+	}
+	left := m.MerkleizeSubtree(gindex << 1)
+	right := m.MerkleizeSubtree((gindex << 1) | 1)
+	r := HashPair(left, right)
+	m.nodes[gindex] = &r
+	return r
+}
+
+func (m *Memory) MerkleProof(addr uint32) (out [28 * 32]byte) {
+	proof := m.traverseBranch(1, addr, 0)
+	// encode the proof
+	for i := 0; i < 28; i++ {
+		copy(out[i*32:(i+1)*32], proof[i][:])
+	}
+	return out
+}
+
+func (m *Memory) traverseBranch(parent uint64, addr uint32, depth uint8) (proof [][32]byte) {
+	if depth == 32-5 {
+		proof = make([][32]byte, 0, 32-5+1)
+		proof = append(proof, m.MerkleizeSubtree(parent))
+		return
+	}
+	if depth > 32-5 {
+		panic("traversed too deep")
+	}
+	self := parent << 1
+	sibling := self | 1
+	if addr&(1<<(31-depth)) != 0 {
+		self, sibling = sibling, self
+	}
+	proof = m.traverseBranch(self, addr, depth+1)
+	siblingNode := m.MerkleizeSubtree(sibling)
+	proof = append(proof, siblingNode)
+	return
+}
+
+func (m *Memory) MerkleRoot() [32]byte {
+	return m.MerkleizeSubtree(1)
+}
+
+func (m *Memory) pageLookup(pageIndex uint32) (*CachedPage, bool) {
+	// hit caches
+	if pageIndex == m.lastPageKeys[0] {
+		return m.lastPage[0], true
+	}
+	if pageIndex == m.lastPageKeys[1] {
+		return m.lastPage[1], true
+	}
+	p, ok := m.pages[pageIndex]
+
+	// only cache existing pages.
+	if ok {
+		m.lastPageKeys[1] = m.lastPageKeys[0]
+		m.lastPage[1] = m.lastPage[0]
+		m.lastPageKeys[0] = pageIndex
+		m.lastPage[0] = p
+	}
+
+	return p, ok
+}
+
+func (m *Memory) SetMemory(addr uint32, v uint32) {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+
+	pageIndex := addr >> PageAddrSize
+	pageAddr := addr & PageAddrMask
+	p, ok := m.pageLookup(pageIndex)
+	if !ok {
+		// allocate the page if we have not already.
+		// Go may mmap relatively large ranges, but we only allocate the pages just in time.
+		p = m.AllocPage(pageIndex)
+	} else {
+		m.Invalidate(addr) // invalidate this branch of memory, now that the value changed
+	}
+	binary.BigEndian.PutUint32(p.Data[pageAddr:pageAddr+4], v)
+}
+
+func (m *Memory) GetMemory(addr uint32) uint32 {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+	p, ok := m.pageLookup(addr >> PageAddrSize)
+	if !ok {
+		return 0
+	}
+	pageAddr := addr & PageAddrMask
+	return binary.BigEndian.Uint32(p.Data[pageAddr : pageAddr+4])
+}
+
+func (m *Memory) AllocPage(pageIndex uint32) *CachedPage {
+	p := &CachedPage{Data: new(Page)}
+	m.pages[pageIndex] = p
+	// make nodes to root
+	k := (1 << PageKeySize) | uint64(pageIndex)
+	for k > 0 {
+		m.nodes[k] = nil
+		k >>= 1
+	}
+	return p
+}
+
+type pageEntry struct {
+	Index uint32 `json:"index"`
+	Data  *Page  `json:"data"`
+}
+
+func (m *Memory) MarshalJSON() ([]byte, error) { // nosemgrep
+	pages := make([]pageEntry, 0, len(m.pages))
+	for k, p := range m.pages {
+		pages = append(pages, pageEntry{
+			Index: k,
+			Data:  p.Data,
+		})
+	}
+	sort.Slice(pages, func(i, j int) bool {
+		return pages[i].Index < pages[j].Index
+	})
+	return json.Marshal(pages)
+}
+
+func (m *Memory) UnmarshalJSON(data []byte) error {
+	var pages []pageEntry
+	if err := json.Unmarshal(data, &pages); err != nil {
+		return err
+	}
+	m.nodes = make(map[uint64]*[32]byte)
+	m.pages = make(map[uint32]*CachedPage)
+	m.lastPageKeys = [2]uint32{^uint32(0), ^uint32(0)}
+	m.lastPage = [2]*CachedPage{nil, nil}
+	for i, p := range pages {
+		if _, ok := m.pages[p.Index]; ok {
+			return fmt.Errorf("cannot load duplicate page, entry %d, page index %d", i, p.Index)
+		}
+		m.AllocPage(p.Index).Data = p.Data
+	}
+	return nil
+}
+
+func (m *Memory) SetMemoryRange(addr uint32, r io.Reader) error {
+	for {
+		pageIndex := addr >> PageAddrSize
+		pageAddr := addr & PageAddrMask
+		p, ok := m.pageLookup(pageIndex)
+		if !ok {
+			p = m.AllocPage(pageIndex)
+		}
+		p.InvalidateFull()
+		n, err := r.Read(p.Data[pageAddr:])
+		if err != nil {
+			if err == io.EOF {
+				return nil
+			}
+			return err
+		}
+		addr += uint32(n)
+	}
+}
+
+type memReader struct {
+	m     *Memory
+	addr  uint32
+	count uint32
+}
+
+func (r *memReader) Read(dest []byte) (n int, err error) {
+	if r.count == 0 {
+		return 0, io.EOF
+	}
+
+	// Keep iterating over memory until we have all our data.
+	// It may wrap around the address range, and may not be aligned
+	endAddr := r.addr + r.count
+
+	pageIndex := r.addr >> PageAddrSize
+	start := r.addr & PageAddrMask
+	end := uint32(PageSize)
+
+	if pageIndex == (endAddr >> PageAddrSize) {
+		end = endAddr & PageAddrMask
+	}
+	p, ok := r.m.pageLookup(pageIndex)
+	if ok {
+		n = copy(dest, p.Data[start:end])
+	} else {
+		n = copy(dest, make([]byte, end-start)) // default to zeroes
+	}
+	r.addr += uint32(n)
+	r.count -= uint32(n)
+	return n, nil
+}
+
+func (m *Memory) ReadMemoryRange(addr uint32, count uint32) io.Reader {
+	return &memReader{m: m, addr: addr, count: count}
+}
+
+func (m *Memory) Usage() string {
+	total := uint64(len(m.pages)) * PageSize
+	const unit = 1024
+	if total < unit {
+		return fmt.Sprintf("%d B", total)
+	}
+	div, exp := uint64(unit), 0
+	for n := total / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	// KiB, MiB, GiB, TiB, ...
+	return fmt.Sprintf("%.1f %ciB", float64(total)/float64(div), "KMGTPE"[exp])
+}

cannon/mipsevm/memory_test.go

+package mipsevm
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestMemoryMerkleProof(t *testing.T) {
+	t.Run("nearly empty tree", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0x10000, 0xaabbccdd)
+		proof := m.MerkleProof(0x10000)
+		require.Equal(t, uint32(0xaabbccdd), binary.BigEndian.Uint32(proof[:4]))
+		for i := 0; i < 32-5; i++ {
+			require.Equal(t, zeroHashes[i][:], proof[32+i*32:32+i*32+32], "empty siblings")
+		}
+	})
+	t.Run("fuller tree", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0x10000, 0xaabbccdd)
+		m.SetMemory(0x80004, 42)
+		m.SetMemory(0x13370000, 123)
+		root := m.MerkleRoot()
+		proof := m.MerkleProof(0x80004)
+		require.Equal(t, uint32(42), binary.BigEndian.Uint32(proof[4:8]))
+		node := *(*[32]byte)(proof[:32])
+		path := uint32(0x80004) >> 5
+		for i := 32; i < len(proof); i += 32 {
+			sib := *(*[32]byte)(proof[i : i+32])
+			if path&1 != 0 {
+				node = HashPair(sib, node)
+			} else {
+				node = HashPair(node, sib)
+			}
+			path >>= 1
+		}
+		require.Equal(t, root, node, "proof must verify")
+	})
+}
+
+func TestMemoryMerkleRoot(t *testing.T) {
+	t.Run("empty", func(t *testing.T) {
+		m := NewMemory()
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "fully zeroed memory should have expected zero hash")
+	})
+	t.Run("empty page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "fully zeroed memory should have expected zero hash")
+	})
+	t.Run("single page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 1)
+		root := m.MerkleRoot()
+		require.NotEqual(t, zeroHashes[32-5], root, "non-zero memory")
+	})
+	t.Run("repeat zero", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		m.SetMemory(0xF004, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "zero still")
+	})
+	t.Run("two empty pages", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(PageSize*3, 0)
+		m.SetMemory(PageSize*10, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "zero still")
+	})
+	t.Run("random few pages", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(PageSize*3, 1)
+		m.SetMemory(PageSize*5, 42)
+		m.SetMemory(PageSize*6, 123)
+		p3 := m.MerkleizeSubtree((1 << PageKeySize) | 3)
+		p5 := m.MerkleizeSubtree((1 << PageKeySize) | 5)
+		p6 := m.MerkleizeSubtree((1 << PageKeySize) | 6)
+		z := zeroHashes[PageAddrSize-5]
+		r1 := HashPair(
+			HashPair(
+				HashPair(z, z),  // 0,1
+				HashPair(z, p3), // 2,3
+			),
+			HashPair(
+				HashPair(z, p5), // 4,5
+				HashPair(p6, z), // 6,7
+			),
+		)
+		r2 := m.MerkleizeSubtree(1 << (PageKeySize - 3))
+		require.Equal(t, r1, r2, "expecting manual page combination to match subtree merkle func")
+	})
+	t.Run("invalidate page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		require.Equal(t, zeroHashes[32-5], m.MerkleRoot(), "zero at first")
+		m.SetMemory(0xF004, 1)
+		require.NotEqual(t, zeroHashes[32-5], m.MerkleRoot(), "non-zero")
+		m.SetMemory(0xF004, 0)
+		require.Equal(t, zeroHashes[32-5], m.MerkleRoot(), "zero again")
+	})
+}
+
+func TestMemoryReadWrite(t *testing.T) {
+
+	t.Run("large random", func(t *testing.T) {
+		m := NewMemory()
+		data := make([]byte, 20_000)
+		_, err := rand.Read(data[:])
+		require.NoError(t, err)
+		require.NoError(t, m.SetMemoryRange(0, bytes.NewReader(data)))
+		for _, i := range []uint32{0, 4, 1000, 20_000 - 4} {
+			v := m.GetMemory(i)
+			expected := binary.BigEndian.Uint32(data[i : i+4])
+			require.Equalf(t, expected, v, "read at %d", i)
+		}
+	})
+
+	t.Run("repeat range", func(t *testing.T) {
+		m := NewMemory()
+		data := []byte(strings.Repeat("under the big bright yellow sun ", 40))
+		require.NoError(t, m.SetMemoryRange(0x1337, bytes.NewReader(data)))
+		res, err := io.ReadAll(m.ReadMemoryRange(0x1337-10, uint32(len(data)+20)))
+		require.NoError(t, err)
+		require.Equal(t, make([]byte, 10), res[:10], "empty start")
+		require.Equal(t, data, res[10:len(res)-10], "result")
+		require.Equal(t, make([]byte, 10), res[len(res)-10:], "empty end")
+	})
+
+	t.Run("read-write", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+		m.SetMemory(12, 0xAABB1CDD)
+		require.Equal(t, uint32(0xAABB1CDD), m.GetMemory(12))
+	})
+
+	t.Run("unaligned read", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		m.SetMemory(16, 0x11223344)
+		require.Panics(t, func() {
+			m.GetMemory(13)
+		})
+		require.Panics(t, func() {
+			m.GetMemory(14)
+		})
+		require.Panics(t, func() {
+			m.GetMemory(15)
+		})
+		require.Equal(t, uint32(0x11223344), m.GetMemory(16))
+		require.Equal(t, uint32(0), m.GetMemory(20))
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+	})
+
+	t.Run("unaligned write", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		require.Panics(t, func() {
+			m.SetMemory(13, 0x11223344)
+		})
+		require.Panics(t, func() {
+			m.SetMemory(14, 0x11223344)
+		})
+		require.Panics(t, func() {
+			m.SetMemory(15, 0x11223344)
+		})
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+	})
+}
+
+func TestMemoryJSON(t *testing.T) {
+	m := NewMemory()
+	m.SetMemory(8, 123)
+	dat, err := json.Marshal(m)
+	require.NoError(t, err)
+	var res Memory
+	require.NoError(t, json.Unmarshal(dat, &res))
+	require.Equal(t, uint32(123), res.GetMemory(8))
+}

cannon/mipsevm/metadata.go

+package mipsevm
+
+import (
+	"debug/elf"
+	"fmt"
+	"sort"
+)
+
+type Symbol struct {
+	Name  string `json:"name"`
+	Start uint32 `json:"start"`
+	Size  uint32 `json:"size"`
+}
+
+type Metadata struct {
+	Symbols []Symbol `json:"symbols"`
+}
+
+func MakeMetadata(elfProgram *elf.File) (*Metadata, error) {
+	syms, err := elfProgram.Symbols()
+	if err != nil {
+		return nil, fmt.Errorf("failed to load symbols table: %w", err)
+	}
+	// Make sure the table is sorted, Go outputs mostly sorted data, except some internal functions
+	sort.Slice(syms, func(i, j int) bool {
+		return syms[i].Value < syms[j].Value
+	})
+	out := &Metadata{Symbols: make([]Symbol, len(syms))}
+	for i, s := range syms {
+		out.Symbols[i] = Symbol{Name: s.Name, Start: uint32(s.Value), Size: uint32(s.Size)}
+	}
+	return out, nil
+}
+
+func (m *Metadata) LookupSymbol(addr uint32) string {
+	if len(m.Symbols) == 0 {
+		return "!unknown"
+	}
+	// find first symbol with higher start. Or n if no such symbol exists
+	i := sort.Search(len(m.Symbols), func(i int) bool {
+		return m.Symbols[i].Start > addr
+	})
+	if i == 0 {
+		return "!start"
+	}
+	out := &m.Symbols[i-1]
+	if out.Start+out.Size < addr { // addr may be pointing to a gap between symbols
+		return "!gap"
+	}
+	return out.Name
+}
+
+func (m *Metadata) SymbolMatcher(name string) func(addr uint32) bool {
+	for _, s := range m.Symbols {
+		if s.Name == name {
+			start := s.Start
+			end := s.Start + s.Size
+			return func(addr uint32) bool {
+				return addr >= start && addr < end
+			}
+		}
+	}
+	return func(addr uint32) bool {
+		return false
+	}
+}
+
+// HexU32 to lazy-format integer attributes for logging
+type HexU32 uint32
+
+func (v HexU32) String() string {
+	return fmt.Sprintf("%08x", uint32(v))
+}
+
+func (v HexU32) MarshalText() ([]byte, error) {
+	return []byte(v.String()), nil
+}

cannon/mipsevm/open_mips_tests/LICENSE

+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

cannon/mipsevm/open_mips_tests/README.md

+# OpenMIPS test vectors
+
+Tests from https://github.com/grantae/OpenMIPS/tree/d606b35e9d5260aef20de2a58660c8303a681e9c/software/test/macro/tests
+
+OpenMIPS is licensed LGPLv3 (as seen in the root of the repository), see [`LICENSE`](./LICENSE) file.
+Note that some build-system files from 2014/2015 in that repository by the same author are marked as BSD licensed,
+but the build-system is not used here.
+
+Requires https://github.com/sergev/LiteBSD/releases/download/tools/gcc-4.8.1-mips-macosx.tgz to build
+

cannon/mipsevm/open_mips_tests/maketests.py

+#!/usr/bin/env python3
+import os
+import sys
+import tempfile
+from capstone import *
+from elftools.elf.elffile import ELFFile
+md = Cs(CS_ARCH_MIPS, CS_MODE_32 + CS_MODE_BIG_ENDIAN)
+
+def maketest(d, out):
+  with tempfile.NamedTemporaryFile() as nf:
+    path = "/Users/kafka/fun/mips/mips-gcc-4.8.1/bin/"
+    print("building", d, "->", out)
+    # which mips is go
+    ret = os.system("%s/mips-elf-as -defsym big_endian=1 -march=mips32r2 -o %s %s" % (path, nf.name, d))
+    assert(ret == 0)
+    nf.seek(0)
+    elffile = ELFFile(nf)
+    #print(elffile)
+    for sec in elffile.iter_sections():
+      #print(sec, sec.name, sec.data())
+      if sec.name == ".test":
+        with open(out, "wb") as f:
+          # jump to 0xdead0000 when done
+          #data = b"\x24\x1f\xde\xad\x00\x1f\xfc\x00" + sec.data()
+          data = sec.data()
+          for dd in md.disasm(data, 0):
+            print(dd)
+          f.write(data)
+
+if __name__ == "__main__":
+  os.makedirs("/tmp/mips", exist_ok=True)
+  if len(sys.argv) > 2:
+    maketest(sys.argv[1], sys.argv[2])
+  else:
+    for d in os.listdir("test/"):
+      if not d.endswith(".asm"):
+        continue
+      maketest("test/"+d, "test/bin/"+(d.replace(".asm", ".bin")))
\ No newline at end of file

cannon/mipsevm/open_mips_tests/test/add.asm

+###############################################################################
+# File         : add.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'add' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    ori     $t1, $0, 0x3        # B = 0x3
+    add     $t2, $t0, $t1       # C = A + B = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addi.asm

+###############################################################################
+# File         : addi.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addi' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    addi    $t1, $t0, 5         # B = A + 5 = 2
+    addi    $t2, $t1, 0xfffe    # C = B + -2 = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addiu.asm

+###############################################################################
+# File         : addiu.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addiu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    addiu   $t1, $t0, 5         # B = A + 5 = 2
+    addiu   $t2, $t1, 0xfffe    # C = B + -2 = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addu.asm

+###############################################################################
+# File         : addu.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    ori     $t1, $0, 0x3        # B = 0x3
+    addu    $t2, $t0, $t1       # C = A + B = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/and.asm

+###############################################################################
+# File         : and.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'and' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    lui     $t1, 0xaaaa         # B = 0xaaaaaaaa
+    lui     $t2, 0x5555         # C = 0x55555555
+    ori     $t0, 0xbeef
+    ori     $t1, 0xaaaa
+    ori     $t2, 0x5555
+    and     $t3, $t0, $t1       # D = A & B = 0x8aaaaaaa
+    and     $t4, $t2, $t3       # E = B & D = 0
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/andi.asm

+###############################################################################
+# File         : andi.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'andi' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe    # A = 0xcafe
+    andi    $t1, $t0, 0xaaaa    # B = A & 0xaaaa = 0x8aaa
+    andi    $t2, $t1, 0x5555    # C = B & 0x5555 = 0
+    sltiu   $v0, $t2, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/beq.asm

+###############################################################################
+# File         : beq.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'beq' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe
+    ori     $t1, $0,  0xcafe
+    ori     $v0, $0,  0         # The test result starts as a failure
+    beq     $t0, $v0, $finish   # No branch
+    nop
+    beq     $t0, $t1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    beq     $0, $0, $finish     # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bgez.asm

+###############################################################################
+# File         : bgez.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bgez' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff
+    bgez    $t0, $finish        # No branch
+    nop
+    bgez    $s1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bgez    $0, $finish         # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bgtz.asm

+###############################################################################
+# File         : bgtz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bgtz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    lui     $t0, 0xffff
+    bgtz    $t0, $finish        # No branch
+    nop
+    bgtz    $s1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bgtz    $s1, $finish        # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/blez.asm

+###############################################################################
+# File         : blez.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'blez' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    blez    $s1, $finish        # No branch
+    lui     $t0, 0xffff
+    blez    $t0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    blez    $0, $finish         # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bltz.asm

+###############################################################################
+# File         : bltz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bltz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    bltz    $0, $finish         # No branch
+    nop
+    bltz    $s1, $finish        # No branch
+    lui     $t0, 0xffff
+    bltz    $t0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bltz    $t0, $finish        # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bne.asm

+###############################################################################
+# File         : bne.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bne' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe
+    ori     $t1, $0,  0xcafe
+    ori     $v0, $0,  0         # The test result starts as a failure
+    bne     $t0, $t1, $finish   # No branch
+    nop
+    bne     $t0, $v0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bne     $t0, $0, $finish    # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/clo.asm

+###############################################################################
+# File         : clo.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'clo' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t2, 0xffff         # 32
+    ori     $t2, 0xffff
+    lui     $t3, 0xffff         # 18
+    ori     $t3, 0xc000
+    lui     $t4, 0xf800         # 5
+    lui     $t5, 0xf000         # 4
+    lui     $t6, 0x7fff         # 0
+    ori     $t7, $0, 0          # 0
+    clo     $s2, $t2
+    clo     $s3, $t3
+    clo     $s4, $t4
+    clo     $s5, $t5
+    clo     $s6, $t6
+    clo     $s7, $t7
+    addiu   $s2, -32
+    addiu   $s3, -18
+    addiu   $s4, -5
+    addiu   $s5, -4
+    addiu   $s6, 0
+    addiu   $s7, 0
+    or      $v1, $s2, $s3
+    or      $v1, $v1, $s4
+    or      $v1, $v1, $s5
+    or      $v1, $v1, $s6
+    or      $v1, $v1, $s7
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/clz.asm

+###############################################################################
+# File         : clz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'clz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t2, 0xffff         # 0
+    ori     $t2, 0xffff
+    ori     $t3, $0, 0x0100     # 23
+    lui     $t4, 0x0700         # 5
+    lui     $t5, 0x0f00         # 4
+    lui     $t6, 0x7fff         # 1
+    ori     $t7, $0, 0          # 32
+    clz     $s2, $t2
+    clz     $s3, $t3
+    clz     $s4, $t4
+    clz     $s5, $t5
+    clz     $s6, $t6
+    clz     $s7, $t7
+    addiu   $s2, 0
+    addiu   $s3, -23
+    addiu   $s4, -5
+    addiu   $s5, -4
+    addiu   $s6, -1
+    addiu   $s7, -32
+    or      $v1, $s2, $s3
+    or      $v1, $v1, $s4
+    or      $v1, $v1, $s5
+    or      $v1, $v1, $s6
+    or      $v1, $v1, $s7
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test