VMGen: Minor documentation improvements

Author: kateinoigakukun

Sources/WasmKit/Execution/DispatchInstruction.swift

@@ -1,7 +1,14 @@
 //// Automatically generated by Utilities/Sources/VMGen.swift
 //// DO NOT EDIT DIRECTLY
 
+// Include the C inline code to codegen together with the Swift code.
+import _CWasmKit.InlineCode
+
+// MARK: - Token Threaded Code
 extension Execution {
+
+    /// Execute an instruction identified by the opcode.
+    /// Note: This function is only used when using token threading model.
     @inline(__always)
     mutating func doExecute(_ opcode: OpcodeID, sp: inout Sp, pc: inout Pc, md: inout Md, ms: inout Ms) throws -> CodeSlot {
         switch opcode {
@@ -207,6 +214,7 @@ extension Execution {
     }
 }
 
+// MARK: - Direct Threaded Code
 extension Execution {
     @_silgen_name("wasmkit_execute_copyStack") @inline(__always)
     mutating func execute_copyStack(sp: UnsafeMutablePointer<Sp>, pc: UnsafeMutablePointer<Pc>, md: UnsafeMutablePointer<Md>, ms: UnsafeMutablePointer<Ms>) -> CodeSlot {
@@ -1763,14 +1771,12 @@ extension Execution {
     }
 }
 
-
-import _CWasmKit.InlineCode
-
 extension Instruction {
-    var handler: UInt64 {
+    /// The tail-calling execution handler for the instruction.
+    var handler: UInt {
         return withUnsafePointer(to: wasmkit_tc_exec_handlers) {
             let count = MemoryLayout.size(ofValue: wasmkit_tc_exec_handlers) / MemoryLayout<wasmkit_tc_exec>.size
-            return $0.withMemoryRebound(to: UInt64.self, capacity: count) {
+            return $0.withMemoryRebound(to: UInt.self, capacity: count) {
                 $0[Int(self.opcodeID)]
             }
         }

Sources/WasmKit/Execution/Execution.swift

@@ -234,12 +234,9 @@ func executeWasm(
         }
 
         try withUnsafeTemporaryAllocation(of: CodeSlot.self, capacity: 2) { rootISeq in
-            switch runtime.value.configuration.threadingModel {
-            case .direct:
-                rootISeq[0] = Instruction.endOfExecution.handler
-            case .token:
-                rootISeq[0] = UInt64(Instruction.endOfExecution.opcodeID)
-            }
+            rootISeq[0] = Instruction.endOfExecution.headSlot(
+                threadingModel: runtime.value.configuration.threadingModel
+            )
             try stack.execute(
                 sp: sp,
                 pc: rootISeq.baseAddress!,

Sources/WasmKit/Execution/Instructions/Control.swift

@@ -100,16 +100,11 @@ extension Execution {
     mutating func compilingCall(sp: inout Sp, pc: Pc, immediate: Instruction.CallOperand) throws -> (Pc, CodeSlot) {
         var pc = pc
         // NOTE: `CompilingCallOperand` consumes 2 slots, discriminator is at -3
-        let discriminatorPc = pc.advanced(by: -3)
+        let headSlotPc = pc.advanced(by: -3)
         let callee = immediate.callee
         try callee.ensureCompiled(runtime: runtime)
         let replaced = Instruction.internalCall(immediate)
-        switch runtime.value.configuration.threadingModel {
-        case .direct:
-            discriminatorPc.pointee = replaced.handler
-        case .token:
-            discriminatorPc.pointee = UInt64(replaced.opcodeID)
-        }
+        headSlotPc.pointee = replaced.headSlot(threadingModel: runtime.value.configuration.threadingModel)
         try _internalCall(sp: &sp, pc: &pc, callee: callee, internalCallOperand: immediate)
         return pc.next()
     }

Sources/WasmKit/Execution/Instructions/InstructionSupport.swift

@@ -188,6 +188,17 @@ extension UntypedValue {
 /// The type of an opcode identifier.
 typealias OpcodeID = UInt64
 
+extension Instruction {
+    func headSlot(threadingModel: RuntimeConfiguration.ThreadingModel) -> CodeSlot {
+        switch threadingModel {
+        case .direct:
+            return CodeSlot(handler)
+        case .token:
+            return opcodeID
+        }
+    }
+}
+
 // MARK: - Instruction printing support
 
 extension InstructionSequence {

Sources/WasmKit/Translator.swift

@@ -585,13 +585,7 @@ struct InstructionTranslator<Context: TranslatorContext>: InstructionVisitor {
 
         private mutating func assign(at index: Int, _ instruction: Instruction) {
             trace("assign: \(instruction)")
-            let headSlot: CodeSlot
-            switch runtimeConfiguration.threadingModel {
-            case .direct:
-                headSlot = instruction.handler
-            case .token:
-                headSlot = UInt64(instruction.opcodeID)
-            }
+            let headSlot = instruction.headSlot(threadingModel: runtimeConfiguration.threadingModel)
             trace("        [\(index)] = 0x\(String(headSlot, radix: 16))")
             self.instructions[index] = headSlot
             if let immediate = instruction.rawImmediate {
@@ -636,12 +630,7 @@ struct InstructionTranslator<Context: TranslatorContext>: InstructionVisitor {
         mutating func emit(_ instruction: Instruction, resultRelink: ResultRelink? = nil) {
             self.lastEmission = LastEmission(position: insertingPC, resultRelink: resultRelink)
             trace("emitInstruction: \(instruction)")
-            switch runtimeConfiguration.threadingModel {
-            case .direct:
-                emitSlot(instruction.handler)
-            case .token:
-                emitSlot(UInt64(instruction.opcodeID))
-            }
+            emitSlot(instruction.headSlot(threadingModel: runtimeConfiguration.threadingModel))
             if let immediate = instruction.rawImmediate {
                 var slots: [CodeSlot] = []
                 immediate.emit(to: { slots.append($0) })

Utilities/Sources/VMGen.swift

@@ -34,6 +34,9 @@ enum VMGen {
             + ExecutionParameter.allCases.map { ($0.label, $0.type, true) }
         var output = """
             extension Execution {
+
+                /// Execute an instruction identified by the opcode.
+                /// Note: This function is only used when using token threading model.
                 @inline(__always)
                 mutating func doExecute(_ \(doExecuteParams.map { "\($0.label): \($0.isInout ? "inout " : "")\($0.type)" }.joined(separator: ", "))) throws -> CodeSlot {
                     switch opcode {
@@ -427,19 +430,30 @@ enum VMGen {
         let generatedFiles = [
             GeneratedFile(
                 projectSources + ["WasmKit", "Execution", "DispatchInstruction.swift"],
-                header + generateDispatcher(instructions: instructions)
-                + "\n\n"
-                + generateDirectThreadedCode(instructions: instructions, inlineImpls: inlineImpls)
+                header
                 + """
+                // Include the C inline code to codegen together with the Swift code.
+                import _CWasmKit.InlineCode
 
+                // MARK: - Token Threaded Code
 
-                import _CWasmKit.InlineCode
+                """
+                + generateDispatcher(instructions: instructions)
+                + """
+
+
+                // MARK: - Direct Threaded Code
+
+                """
+                + generateDirectThreadedCode(instructions: instructions, inlineImpls: inlineImpls)
+                + """
 
                 extension Instruction {
-                    var handler: UInt64 {
+                    /// The tail-calling execution handler for the instruction.
+                    var handler: UInt {
                         return withUnsafePointer(to: wasmkit_tc_exec_handlers) {
                             let count = MemoryLayout.size(ofValue: wasmkit_tc_exec_handlers) / MemoryLayout<wasmkit_tc_exec>.size
-                            return $0.withMemoryRebound(to: UInt64.self, capacity: count) {
+                            return $0.withMemoryRebound(to: UInt.self, capacity: count) {
                                 $0[Int(self.opcodeID)]
                             }
                         }