Add documentation in InstructionSupport.swift

Author: kateinoigakukun

Sources/WasmKit/CMakeLists.txt

@@ -10,7 +10,6 @@ add_wasmkit_library(WasmKit
   Component/ComponentTypes.swift
   Execution/Instructions/Reference.swift
   Execution/Instructions/Control.swift
-  Execution/Instructions/Expression.swift
   Execution/Instructions/Instruction.swift
   Execution/Instructions/Parametric.swift
   Execution/Instructions/Table.swift

Sources/WasmKit/Execution/Function.swift

@@ -202,6 +202,30 @@ struct WasmFunctionEntity {
 
 typealias InternalUncompiledCode = EntityHandle<Code>
 
+/// A compiled instruction sequence.
+struct InstructionSequence: Equatable {
+    let instructions: UnsafeMutableBufferPointer<CodeSlot>
+    /// The maximum height of the value stack during execution of this function.
+    /// This height does not count the locals.
+    let maxStackHeight: Int
+
+    let constants: UnsafeBufferPointer<UntypedValue>
+
+    init(instructions: UnsafeMutableBufferPointer<CodeSlot>, maxStackHeight: Int, constants: UnsafeBufferPointer<UntypedValue>) {
+        self.instructions = instructions
+        self.maxStackHeight = maxStackHeight
+        self.constants = constants
+    }
+
+    var baseAddress: UnsafeMutablePointer<CodeSlot> {
+        self.instructions.baseAddress!
+    }
+
+    static func == (lhs: InstructionSequence, rhs: InstructionSequence) -> Bool {
+        lhs.instructions.baseAddress == rhs.instructions.baseAddress
+    }
+}
+
 enum CodeBody {
     case uncompiled(InternalUncompiledCode)
     case compiled(InstructionSequence)

Sources/WasmKit/Execution/Instructions/Expression.swift

@@ -44,92 +44,35 @@ struct LLVReg: Equatable, ShiftedVReg {
     }
 }
 
-extension RawUnsignedInteger {
-    init(_ slot: CodeSlot, shiftWidth: Int) {
-        let mask = CodeSlot(Self.max)
-        let bitPattern = (slot >> shiftWidth) & mask
-        self = Self(bitPattern)
-    }
-
-    func bits(shiftWidth: Int) -> CodeSlot {
-        CodeSlot(self) << shiftWidth
-    }
-}
-
-extension RawSignedInteger {
-    init(_ slot: CodeSlot, shiftWidth: Int) {
-        self.init(bitPattern: Unsigned(slot, shiftWidth: shiftWidth))
-    }
-
-    func bits(shiftWidth: Int) -> CodeSlot {
-        Unsigned(bitPattern: self).bits(shiftWidth: shiftWidth)
-    }
-}
-
-extension UntypedValue {
-    init(_ slot: CodeSlot, shiftWidth: Int) {
-        self.init(storage: slot)
-    }
-
-    func bits(shiftWidth: Int) -> CodeSlot { storage }
-}
+// MARK: - Immediate load/emit support
 
+/// A protocol that represents an immediate associated with an instruction.
 protocol InstructionImmediate {
+    /// Loads an immediate from the instruction sequence.
+    ///
+    /// - Parameter pc: The program counter to read from.
+    /// - Returns: The loaded immediate.
     static func load(from pc: inout Pc) -> Self
+
+    /// Emits the layout of the immediate to be emitted.
+    ///
+    /// - Parameter emitSlot: The closure to schedule a slot emission.
+    ///             This closure receives a builder closure that builds the slot.
+    ///
+    /// - Note: This method is intended to work at meta-level to allow
+    ///         knowing the size of slots without actual immediate values.
     static func emit(to emitSlot: @escaping ((Self) -> CodeSlot) -> Void)
 }
 
 extension InstructionImmediate {
+    /// Emits the immediate value
+    ///
+    /// - Parameter emitSlot: The closure to emit a slot.
     func emit(to emitSlot: @escaping (CodeSlot) -> Void) {
         Self.emit { buildCodeSlot in
             emitSlot(buildCodeSlot(self))
         }
     }
-    static func emit<Parent>(to emitParent: @escaping ((Parent) -> CodeSlot) -> Void, _ child: KeyPath<Parent, Self>) {
-        Self.emit { emitChild in
-            emitParent { emitChild($0[keyPath: child]) }
-        }
-    }
-}
-
-extension InstructionImmediate {
-    static func load(from pc: inout Pc) -> Self {
-        pc.read()
-    }
-    static func emit(to emitSlot: ((Self) -> CodeSlot) -> Void) {
-        assert(MemoryLayout<Self>.size == 8)
-        emitSlot { unsafeBitCast($0, to: CodeSlot.self) }
-    }
-}
-
-extension VReg: InstructionImmediate {
-    static func load(from pc: inout Pc) -> Self {
-        VReg(bitPattern: UInt16(pc.read(UInt64.self)))
-    }
-    static func emit(to emitSlot: @escaping ((Self) -> CodeSlot) -> Void) {
-        emitSlot { CodeSlot(UInt16(bitPattern: $0)) }
-    }
-
-    typealias Slot2 = (VReg, VReg, pad: UInt32)
-    static func load2(from pc: inout Pc) -> (Self, Self) {
-        let (x, y, _) = pc.read(Slot2.self)
-        return (x, y)
-    }
-    static func emit2(to emitSlot: @escaping ((Self, Self) -> CodeSlot) -> Void) {
-        emitSlot { x, y in
-            let slot: Slot2 = (x, y, 0)
-            return unsafeBitCast(slot, to: CodeSlot.self)
-        }
-    }
-}
-
-extension LLVReg: InstructionImmediate {
-    static func load(from pc: inout Pc) -> Self {
-        Self(storage: Int64(bitPattern: pc.read()))
-    }
-    static func emit(to emitSlot: ((Self) -> CodeSlot) -> Void) {
-        emitSlot { UInt64(bitPattern: $0.value) }
-    }
 }
 
 extension UInt32: InstructionImmediate {
@@ -150,6 +93,8 @@ extension Int32: InstructionImmediate {
     }
 }
 
+// MARK: - Immediate type extensions
+
 extension Instruction.RefNullOperand {
     init(result: VReg, type: ReferenceType) {
         self.init(result: result, rawType: type.rawValue)
@@ -210,9 +155,64 @@ extension Instruction {
     typealias OnExitOperand = FunctionIndex
 }
 
+extension RawUnsignedInteger {
+    init(_ slot: CodeSlot, shiftWidth: Int) {
+        let mask = CodeSlot(Self.max)
+        let bitPattern = (slot >> shiftWidth) & mask
+        self = Self(bitPattern)
+    }
+
+    func bits(shiftWidth: Int) -> CodeSlot {
+        CodeSlot(self) << shiftWidth
+    }
+}
+
+extension RawSignedInteger {
+    init(_ slot: CodeSlot, shiftWidth: Int) {
+        self.init(bitPattern: Unsigned(slot, shiftWidth: shiftWidth))
+    }
+
+    func bits(shiftWidth: Int) -> CodeSlot {
+        Unsigned(bitPattern: self).bits(shiftWidth: shiftWidth)
+    }
+}
+
+extension UntypedValue {
+    init(_ slot: CodeSlot, shiftWidth: Int) {
+        self.init(storage: slot)
+    }
+
+    func bits(shiftWidth: Int) -> CodeSlot { storage }
+}
+
 /// The type of an opcode identifier.
 typealias OpcodeID = UInt64
 
+// MARK: - Instruction printing support
+
+extension InstructionSequence {
+    func write<Target>(to target: inout Target, context: inout InstructionPrintingContext) where Target : TextOutputStream {
+        var hexOffsetWidth = String(instructions.count - 1, radix: 16).count
+        hexOffsetWidth = (hexOffsetWidth + 1) & ~1
+
+        guard let cursorStart = instructions.baseAddress else { return }
+        let cursorEnd = cursorStart.advanced(by: instructions.count)
+
+        var cursor = cursorStart
+        while cursor < cursorEnd {
+            let index = cursor - cursorStart
+            var hexOffset = String(index, radix: 16)
+            while hexOffset.count < hexOffsetWidth {
+                hexOffset = "0" + hexOffset
+            }
+            target.write("0x\(hexOffset): ")
+            let instruction = Instruction.load(from: &cursor)
+            context.print(instruction: instruction, to: &target)
+            target.write("\n")
+        }
+    }
+}
+
 struct InstructionPrintingContext {
     let shouldColor: Bool
     let function: Function