Add more detailed documentation to the resizeFrameHeader instruction

Author: kateinoigakukun

Sources/WasmKit/Execution/Execution.swift

@@ -538,17 +538,15 @@ extension Execution {
     func tailInvoke(
         function: InternalFunction,
         callerInstance: InternalInstance?,
-        spAddend: VReg,
         sp: Sp, pc: Pc, md: inout Md, ms: inout Ms
     ) throws -> (Pc, Sp) {
         if function.isWasm {
             return try tailInvokeWasmFunction(
                 function: function.wasm, callerInstance: callerInstance,
-                spAddend: spAddend,
                 sp: sp, md: &md, ms: &ms
             )
         } else {
-            try invokeHostFunction(function: function.host, sp: sp, spAddend: spAddend)
+            try invokeHostFunction(function: function.host, sp: sp, spAddend: 0)
             return (pc, sp)
         }
     }
@@ -561,21 +559,19 @@ extension Execution {
     private func tailInvokeWasmFunction(
         function: EntityHandle<WasmFunctionEntity>,
         callerInstance: InternalInstance?,
-        spAddend: VReg,
         sp: Sp, md: inout Md, ms: inout Ms
     ) throws -> (Pc, Sp) {
         let iseq = try function.ensureCompiled(store: store)
-        let newSp = sp.advanced(by: Int(spAddend))
-        try checkStackBoundary(newSp.advanced(by: iseq.maxStackHeight))
-        newSp.currentFunction = function
+        try checkStackBoundary(sp.advanced(by: iseq.maxStackHeight))
+        sp.currentFunction = function
 
-        initializeConstSlots(sp: newSp, iseq: iseq, numberOfNonParameterLocals: function.numberOfNonParameterLocals)
+        initializeConstSlots(sp: sp, iseq: iseq, numberOfNonParameterLocals: function.numberOfNonParameterLocals)
 
         Execution.CurrentMemory.mayUpdateCurrentInstance(
             instance: function.instance,
             from: callerInstance, md: &md, ms: &ms
         )
-        return (iseq.baseAddress, newSp)
+        return (iseq.baseAddress, sp)
     }
 
     /// Executes the given WebAssembly function.

Sources/WasmKit/Execution/Instructions/Control.swift

@@ -151,13 +151,12 @@ extension Execution {
         )
         return pc.next()
     }
-    
+
     mutating func returnCall(sp: inout Sp, pc: Pc, md: inout Md, ms: inout Ms, immediate: Instruction.ReturnCallOperand) throws -> (Pc, CodeSlot) {
         var pc = pc
         (pc, sp) = try tailInvoke(
             function: immediate.callee,
             callerInstance: currentInstance(sp: sp),
-            spAddend: 0,
             sp: sp, pc: pc, md: &md, ms: &ms
         )
         return pc.next()
@@ -172,13 +171,38 @@ extension Execution {
         (pc, sp) = try tailInvoke(
             function: function,
             callerInstance: callerInstance,
-            spAddend: 0,
             sp: sp, pc: pc, md: &md, ms: &ms
         )
         return pc.next()
     }
 
     mutating func resizeFrameHeader(sp: inout Sp, immediate: Instruction.ResizeFrameHeaderOperand) throws {
+        // The params/results space are resized by `delta` slots and the rest of the
+        // frame is copied to the new location. See the following diagram for the
+        // layout of the frame before and after the resize operation:
+        //
+        //
+        //              |--------BEFORE-------|   |--------AFTER--------|
+        //              |  Params  | Results  |   |  Params  | Results  |
+        //              |  ...     |   ...    |   |  ...     |   ...    |
+        // Old Header ->|---------------------|\  |  ...     |   ...    |              -+
+        //              |         Sp          | \ |  ...     |   ...    |               | delta
+        //              |---------------------|  \|---------------------|<- New Header -+  -+
+        //              |         Pc          |   |         Sp          |                   |
+        //              |---------------------|   |---------------------|                   |
+        //              |     Current Func    | C |         Pc          |                   |
+        //     Old Sp ->|---------------------| O |---------------------|                   |
+        //              |       Locals        | P |     Current Func    |                   |
+        //              |        ...          | Y |---------------------|<- New Sp          |
+        //              |---------------------|   |       Locals        |                   | sizeToCopy
+        //              |        Consts       |   |        ...          |                   |
+        //              |        ...          |   |---------------------|                   |
+        //              |---------------------|   |        Consts       |                   |
+        //              |     Value Stack     |   |        ...          |                   |
+        //              |        ...          |   |---------------------|                   |
+        //              |---------------------|\  |     Value Stack     |                   |
+        //                                      \ |        ...          |                   |
+        //                                       \|---------------------|                  -+
         let newSp = sp.advanced(by: Int(immediate.delta))
         try checkStackBoundary(newSp)
         let oldFrameHeader = sp.advanced(by: -FrameHeaderLayout.numberOfSavingSlots)

Sources/WasmKit/Execution/Instructions/Instruction.swift

@@ -25,7 +25,8 @@ enum Instruction: Equatable {
     case internalCall(Instruction.CallOperand)
     /// WebAssembly Core Instruction `call_indirect`
     case callIndirect(Instruction.CallIndirectOperand)
-    /// Resize the frame header
+    /// Resize the frame header by increasing param/result slots and copying `sizeToCopy`
+    /// slots placed after the header
     case resizeFrameHeader(Instruction.ResizeFrameHeaderOperand)
     /// WebAssembly Core Instruction `return_call`
     case returnCall(Instruction.ReturnCallOperand)

Sources/WasmKit/Translator.swift

@@ -190,7 +190,7 @@ private struct MetaProgramCounter {
 /// )
 /// ```
 ///
-/// Then the stack frame layout looks like: 
+/// Then the stack frame layout looks like:
 ///
 /// ```
 /// | Offset                             | Description          |

Utilities/Sources/VMSpec/Instruction.swift

@@ -543,7 +543,10 @@ extension VMGen {
                 $0.field(name: "index", type: .VReg)
                 $0.field(name: "spAddend", type: .VReg)
             },
-            Instruction(name: "resizeFrameHeader", documentation: "Resize the frame header",
+            Instruction(name: "resizeFrameHeader", documentation: """
+                        Resize the frame header by increasing param/result slots and copying `sizeToCopy`
+                        slots placed after the header
+                        """,
                         mayThrow: true, mayUpdateFrame: true) {
                 $0.field(name: "delta", type: .VReg)
                 $0.field(name: "sizeToCopy", type: .VReg)