mipsevm: update readme, expose PatchVM function

mipsevm/README

-Running MIPS processor on chain
-
-Instruction set used by minigeth, 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']
-
- There's three ways to run the embedded MIPS engine, see "run_<type>":
- * unicorn -- fastest, uses none of the solidity
- * evm -- uses MIPS.sol, but stubs MIPSMemory.sol to SLOAD/SSTORE and doesn't compute the merkle trie
- * chain -- uses MIPS.sol + MIPSMemory.sol, slowest, will actually run on chain like this

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 `PatchVM` for Go programs.
+3. Load the state into a MIPS-32 configured unicorn instance, using `NewUnicorn`, `LoadUnicorn`
+4. Implement the `PreimageOracle` interface
+5. Instrument the emulator with the state, and pre-image oracle, using `NewUnicornState`
+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 `Oracle.sol`, using the above witness data.

mipsevm/evm_test.go

@@ -128,7 +128,7 @@ func TestHelloEVM(t *testing.T) {
 	state, err := LoadELF(elfProgram)
 	require.NoError(t, err, "load ELF into state")
 
-	err = patchVM(elfProgram, state)
+	err = PatchVM(elfProgram, state)
 	require.NoError(t, err, "apply Go runtime patches")
 
 	mu, err := NewUnicorn()
@@ -199,7 +199,7 @@ func TestClaimEVM(t *testing.T) {
 	state, err := LoadELF(elfProgram)
 	require.NoError(t, err, "load ELF into state")
 
-	err = patchVM(elfProgram, state)
+	err = PatchVM(elfProgram, state)
 	require.NoError(t, err, "apply Go runtime patches")
 
 	mu, err := NewUnicorn()

mipsevm/patch.go

@@ -51,7 +51,7 @@ func LoadELF(f *elf.File) (*State, error) {
 	return s, nil
 }
 
-func patchVM(f *elf.File, st *State) error {
+func PatchVM(f *elf.File, st *State) error {
 	symbols, err := f.Symbols()
 	if err != nil {
 		return fmt.Errorf("failed to read symbols data, cannot patch program: %w", err)

mipsevm/state_test.go

@@ -92,7 +92,7 @@ func TestHello(t *testing.T) {
 	state, err := LoadELF(elfProgram)
 	require.NoError(t, err, "load ELF into state")
 
-	err = patchVM(elfProgram, state)
+	err = PatchVM(elfProgram, state)
 	require.NoError(t, err, "apply Go runtime patches")
 
 	mu, err := NewUnicorn()
@@ -194,7 +194,7 @@ func TestClaim(t *testing.T) {
 	state, err := LoadELF(elfProgram)
 	require.NoError(t, err, "load ELF into state")
 
-	err = patchVM(elfProgram, state)
+	err = PatchVM(elfProgram, state)
 	require.NoError(t, err, "apply Go runtime patches")
 
 	mu, err := NewUnicorn()