cannon: Add godoc to ExecMipsCoreStepLogic (#12786)

* cannon: Add godoc to ExecMipsCoreStepLogic

* update MIPS64.sol

* update semver

cannon/mipsevm/exec/mips_instructions.go

@@ -33,7 +33,9 @@ func GetInstructionDetails(pc Word, memory *memory.Memory) (insn, opcode, fun ui
 	return insn, opcode, fun
 }
 
-func ExecMipsCoreStepLogic(cpu *mipsevm.CpuScalars, registers *[32]Word, memory *memory.Memory, insn, opcode, fun uint32, memTracker MemTracker, stackTracker StackTracker) (memUpdated bool, memAddr Word, err error) {
+// ExecMipsCoreStepLogic executes a MIPS instruction that isn't a syscall nor a RMW operation
+// If a store operation occurred, then it returns the effective address of the store memory location.
+func ExecMipsCoreStepLogic(cpu *mipsevm.CpuScalars, registers *[32]Word, memory *memory.Memory, insn, opcode, fun uint32, memTracker MemTracker, stackTracker StackTracker) (memUpdated bool, effMemAddr Word, err error) {
 	// j-type j/jal
 	if opcode == 2 || opcode == 3 {
 		linkReg := Word(0)
@@ -153,7 +155,7 @@ func ExecMipsCoreStepLogic(cpu *mipsevm.CpuScalars, registers *[32]Word, memory
 		memTracker.TrackMemAccess(storeAddr)
 		memory.SetWord(storeAddr, val)
 		memUpdated = true
-		memAddr = storeAddr
+		effMemAddr = storeAddr
 	}
 
 	// write back the value to destination register

cannon/mipsevm/multithreaded/mips.go

@@ -316,19 +316,19 @@ func (m *InstrumentedState) mipsStep() error {
 	}
 
 	// Exec the rest of the step logic
-	memUpdated, memAddr, err := exec.ExecMipsCoreStepLogic(m.state.getCpuRef(), m.state.GetRegistersRef(), m.state.Memory, insn, opcode, fun, m.memoryTracker, m.stackTracker)
+	memUpdated, effMemAddr, err := exec.ExecMipsCoreStepLogic(m.state.getCpuRef(), m.state.GetRegistersRef(), m.state.Memory, insn, opcode, fun, m.memoryTracker, m.stackTracker)
 	if err != nil {
 		return err
 	}
 	if memUpdated {
-		m.handleMemoryUpdate(memAddr)
+		m.handleMemoryUpdate(effMemAddr)
 	}
 
 	return nil
 }
 
-func (m *InstrumentedState) handleMemoryUpdate(memAddr Word) {
-	if memAddr == (arch.AddressMask & m.state.LLAddress) {
+func (m *InstrumentedState) handleMemoryUpdate(effMemAddr Word) {
+	if effMemAddr == (arch.AddressMask & m.state.LLAddress) {
 		// Reserved address was modified, clear the reservation
 		m.clearLLMemoryReservation()
 	}

packages/contracts-bedrock/semver-lock.json

@@ -148,8 +148,8 @@
     "sourceCodeHash": "0x9fa2d1297ad1e93b4d3c5c0fed08bedcd8f746807589f0fd3369e79347c6a027"
   },
   "src/cannon/MIPS64.sol": {
-    "initCodeHash": "0x5094e3f488de838cba1422b508a899444ee27905abc9c0b97961d4b8b7392289",
-    "sourceCodeHash": "0xdc2393d2073348218a9c6e169c2e7f687590e237773b8fde53fae9cf84395978"
+    "initCodeHash": "0xc615a8f321f3bfb29c9459705f3012e512c463ba9ba2e1bcb6f9349f2d911d10",
+    "sourceCodeHash": "0x8fd0f4167d80f48010ad1241a9f6fb93576887dcc1f97be6b05adaf0086a537b"
   },
   "src/cannon/PreimageOracle.sol": {
     "initCodeHash": "0x5d7e8ae64f802bd9d760e3d52c0a620bd02405dc2c8795818db9183792ffe81c",

packages/contracts-bedrock/src/cannon/MIPS64.sol

@@ -64,8 +64,8 @@ contract MIPS64 is ISemver {
     }
 
     /// @notice The semantic version of the MIPS64 contract.
-    /// @custom:semver 1.0.0-beta.2
-    string public constant version = "1.0.0-beta.2";
+    /// @custom:semver 1.0.0-beta.3
+    string public constant version = "1.0.0-beta.3";
 
     /// @notice The preimage oracle contract.
     IPreimageOracle internal immutable ORACLE;
@@ -272,20 +272,20 @@ contract MIPS64 is ISemver {
                 fun: fun
             });
             bool memUpdated;
-            uint64 memAddr;
-            (state.memRoot, memUpdated, memAddr) = ins.execMipsCoreStepLogic(coreStepArgs);
+            uint64 effMemAddr;
+            (state.memRoot, memUpdated, effMemAddr) = ins.execMipsCoreStepLogic(coreStepArgs);
             setStateCpuScalars(thread, cpu);
             updateCurrentThreadRoot();
             if (memUpdated) {
-                handleMemoryUpdate(state, memAddr);
+                handleMemoryUpdate(state, effMemAddr);
             }
 
             return outputState();
         }
     }
 
-    function handleMemoryUpdate(State memory _state, uint64 _memAddr) internal pure {
-        if (_memAddr == (arch.ADDRESS_MASK & _state.llAddress)) {
+    function handleMemoryUpdate(State memory _state, uint64 _effMemAddr) internal pure {
+        if (_effMemAddr == (arch.ADDRESS_MASK & _state.llAddress)) {
             // Reserved address was modified, clear the reservation
             clearLLMemoryReservation(_state);
         }

packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol

@@ -66,23 +66,23 @@ library MIPS64Instructions {
     /// @notice Execute core MIPS step logic.
     /// @return newMemRoot_ The updated merkle root of memory after any modifications, may be unchanged.
     /// @return memUpdated_ True if memory was modified.
-    /// @return memAddr_ Holds the memory address that was updated if memUpdated_ is true.
+    /// @return effMemAddr_ Holds the effective address that was updated if memUpdated_ is true.
     function execMipsCoreStepLogic(CoreStepLogicParams memory _args)
         internal
         pure
-        returns (bytes32 newMemRoot_, bool memUpdated_, uint64 memAddr_)
+        returns (bytes32 newMemRoot_, bool memUpdated_, uint64 effMemAddr_)
     {
         unchecked {
             newMemRoot_ = _args.memRoot;
             memUpdated_ = false;
-            memAddr_ = 0;
+            effMemAddr_ = 0;
 
             // j-type j/jal
             if (_args.opcode == 2 || _args.opcode == 3) {
                 // Take top 4 bits of the next PC (its 256 MB region), and concatenate with the 26-bit offset
                 uint64 target = (_args.cpu.nextPC & signExtend(0xF0000000, 32)) | uint64((_args.insn & 0x03FFFFFF) << 2);
                 handleJump(_args.cpu, _args.registers, _args.opcode == 2 ? 0 : REG_RA, target);
-                return (newMemRoot_, memUpdated_, memAddr_);
+                return (newMemRoot_, memUpdated_, effMemAddr_);
             }
 
             // register fetch
@@ -129,7 +129,7 @@ library MIPS64Instructions {
                     _rtReg: rtReg,
                     _rs: rs
                 });
-                return (newMemRoot_, memUpdated_, memAddr_);
+                return (newMemRoot_, memUpdated_, effMemAddr_);
             }
 
             uint64 storeAddr = U64_MASK;
@@ -162,18 +162,18 @@ library MIPS64Instructions {
                 if (_args.fun == 8 || _args.fun == 9) {
                     // jr/jalr
                     handleJump(_args.cpu, _args.registers, _args.fun == 8 ? 0 : rdReg, rs);
-                    return (newMemRoot_, memUpdated_, memAddr_);
+                    return (newMemRoot_, memUpdated_, effMemAddr_);
                 }
 
                 if (_args.fun == 0xa) {
                     // movz
                     handleRd(_args.cpu, _args.registers, rdReg, rs, rt == 0);
-                    return (newMemRoot_, memUpdated_, memAddr_);
+                    return (newMemRoot_, memUpdated_, effMemAddr_);
                 }
                 if (_args.fun == 0xb) {
                     // movn
                     handleRd(_args.cpu, _args.registers, rdReg, rs, rt != 0);
-                    return (newMemRoot_, memUpdated_, memAddr_);
+                    return (newMemRoot_, memUpdated_, effMemAddr_);
                 }
 
                 // lo and hi registers
@@ -187,7 +187,7 @@ library MIPS64Instructions {
                         _rt: rt,
                         _storeReg: rdReg
                     });
-                    return (newMemRoot_, memUpdated_, memAddr_);
+                    return (newMemRoot_, memUpdated_, effMemAddr_);
                 }
             }
 
@@ -195,13 +195,13 @@ library MIPS64Instructions {
             if (storeAddr != U64_MASK) {
                 newMemRoot_ = MIPS64Memory.writeMem(storeAddr, _args.memProofOffset, val);
                 memUpdated_ = true;
-                memAddr_ = storeAddr;
+                effMemAddr_ = storeAddr;
             }
 
             // write back the value to destination register
             handleRd(_args.cpu, _args.registers, rdReg, val, true);
 
-            return (newMemRoot_, memUpdated_, memAddr_);
+            return (newMemRoot_, memUpdated_, effMemAddr_);
         }
     }