ignis 0.0.1

data/lib/nvruby/jit/driver_api_bindings.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Ignis
+  module JIT
+    # CUDA Driver API FFI bindings for module and kernel management
+    # Provides low-level access to load compiled code and execute kernels
+    module DriverAPIBindings
+      extend FFI::Library
+
+      # CUDA Driver result codes
+      CUDA_SUCCESS = 0
+      CUDA_ERROR_INVALID_VALUE = 1
+      CUDA_ERROR_OUT_OF_MEMORY = 2
+      CUDA_ERROR_NOT_INITIALIZED = 3
+      CUDA_ERROR_DEINITIALIZED = 4
+      CUDA_ERROR_PROFILER_DISABLED = 5
+      CUDA_ERROR_NO_DEVICE = 100
+      CUDA_ERROR_INVALID_DEVICE = 101
+      CUDA_ERROR_INVALID_IMAGE = 200
+      CUDA_ERROR_INVALID_CONTEXT = 201
+      CUDA_ERROR_CONTEXT_ALREADY_CURRENT = 202
+      CUDA_ERROR_MAP_FAILED = 205
+      CUDA_ERROR_UNMAP_FAILED = 206
+      CUDA_ERROR_ARRAY_IS_MAPPED = 207
+      CUDA_ERROR_ALREADY_MAPPED = 208
+      CUDA_ERROR_NO_BINARY_FOR_GPU = 209
+      CUDA_ERROR_ALREADY_ACQUIRED = 210
+      CUDA_ERROR_NOT_MAPPED = 211
+      CUDA_ERROR_NOT_MAPPED_AS_ARRAY = 212
+      CUDA_ERROR_NOT_MAPPED_AS_POINTER = 213
+      CUDA_ERROR_ECC_UNCORRECTABLE = 214
+      CUDA_ERROR_UNSUPPORTED_LIMIT = 215
+      CUDA_ERROR_CONTEXT_ALREADY_IN_USE = 216
+      CUDA_ERROR_PEER_ACCESS_UNSUPPORTED = 217
+      CUDA_ERROR_INVALID_PTX = 218
+      CUDA_ERROR_INVALID_GRAPHICS_CONTEXT = 219
+      CUDA_ERROR_INVALID_SOURCE = 300
+      CUDA_ERROR_FILE_NOT_FOUND = 301
+      CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND = 302
+      CUDA_ERROR_SHARED_OBJECT_INIT_FAILED = 303
+      CUDA_ERROR_OPERATING_SYSTEM = 304
+      CUDA_ERROR_INVALID_HANDLE = 400
+      CUDA_ERROR_ILLEGAL_STATE = 401
+      CUDA_ERROR_NOT_FOUND = 500
+      CUDA_ERROR_NOT_READY = 600
+      CUDA_ERROR_ILLEGAL_ADDRESS = 700
+      CUDA_ERROR_LAUNCH_OUT_OF_RESOURCES = 701
+      CUDA_ERROR_LAUNCH_TIMEOUT = 702
+      CUDA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING = 703
+      CUDA_ERROR_PEER_ACCESS_ALREADY_ENABLED = 704
+      CUDA_ERROR_PEER_ACCESS_NOT_ENABLED = 705
+      CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE = 708
+      CUDA_ERROR_CONTEXT_IS_DESTROYED = 709
+      CUDA_ERROR_ASSERT = 710
+      CUDA_ERROR_TOO_MANY_PEERS = 711
+      CUDA_ERROR_HOST_MEMORY_ALREADY_REGISTERED = 712
+      CUDA_ERROR_HOST_MEMORY_NOT_REGISTERED = 713
+      CUDA_ERROR_HARDWARE_STACK_ERROR = 714
+      CUDA_ERROR_ILLEGAL_INSTRUCTION = 715
+      CUDA_ERROR_MISALIGNED_ADDRESS = 716
+      CUDA_ERROR_INVALID_ADDRESS_SPACE = 717
+      CUDA_ERROR_INVALID_PC = 718
+      CUDA_ERROR_LAUNCH_FAILED = 719
+      CUDA_ERROR_UNKNOWN = 999
+
+      # cuLaunchKernel extra parameter constants
+      CU_LAUNCH_PARAM_END = 0
+      CU_LAUNCH_PARAM_BUFFER_POINTER = 1
+      CU_LAUNCH_PARAM_BUFFER_SIZE = 2
+
+      # @return [Boolean] Whether bindings are loaded
+      @loaded = false
+
+      # @return [Boolean] Whether driver is initialized
+      @initialized = false
+
+      # @return [Mutex] Thread safety lock
+      @mutex = Mutex.new
+
+      class << self
+        # Ensure CUDA Driver API is loaded and initialized
+        # @return [void]
+        # @raise [LibraryNotFoundError] If CUDA driver cannot be loaded
+        def ensure_loaded!
+          @mutex.synchronize do
+            return if @loaded
+
+            load_cuda_driver!
+            attach_driver_functions!
+            initialize_driver!
+            @loaded = true
+            Ignis.logger.info("CUDA Driver API bindings initialized")
+          end
+        end
+
+        # Check if Driver API is loaded
+        # @return [Boolean]
+        def loaded?
+          @mutex.synchronize { @loaded }
+        end
+
+        # Load a module from CUBIN/PTX data
+        # @param data [String] CUBIN or PTX binary data
+        # @return [FFI::Pointer] Module handle (CUmodule)
+        # @raise [CudaDriverError] If module loading fails
+        def load_module_data(data)
+          ensure_loaded!
+
+          module_ptr = FFI::MemoryPointer.new(:pointer)
+          data_ptr = FFI::MemoryPointer.new(:char, data.bytesize)
+          data_ptr.put_bytes(0, data)
+
+          result = cuModuleLoadData(module_ptr, data_ptr)
+          check_result!(result, "cuModuleLoadData")
+
+          module_ptr.read_pointer
+        end
+
+        # Get a kernel function from a loaded module
+        # @param cuda_module [FFI::Pointer] Module handle
+        # @param function_name [String] Kernel function name
+        # @return [FFI::Pointer] Function handle (CUfunction)
+        # @raise [CudaDriverError] If function is not found
+        def get_module_function(cuda_module, function_name)
+          ensure_loaded!
+
+          func_ptr = FFI::MemoryPointer.new(:pointer)
+          name_ptr = FFI::MemoryPointer.from_string(function_name)
+
+          result = cuModuleGetFunction(func_ptr, cuda_module, name_ptr)
+          check_result!(result, "cuModuleGetFunction(#{function_name})")
+
+          func_ptr.read_pointer
+        end
+
+        # Launch a kernel function
+        # @param function [FFI::Pointer] Function handle (CUfunction)
+        # @param grid_dim [Array<Integer>] Grid dimensions [x, y, z]
+        # @param block_dim [Array<Integer>] Block dimensions [x, y, z]
+        # @param kernel_params [Array<FFI::Pointer>] Kernel parameter pointers
+        # @param shared_mem [Integer] Dynamic shared memory in bytes
+        # @param stream [FFI::Pointer, nil] CUDA stream (nil for default)
+        # @return [void]
+        # @raise [CudaDriverError] If kernel launch fails
+        def launch_kernel(function, grid_dim:, block_dim:, kernel_params:, shared_mem: 0, stream: nil)
+          ensure_loaded!
+
+          grid_x, grid_y, grid_z = normalize_dims(grid_dim)
+          block_x, block_y, block_z = normalize_dims(block_dim)
+
+          params_ptr = build_params_array(kernel_params)
+          stream_ptr = stream || FFI::Pointer::NULL
+
+          result = cuLaunchKernel(
+            function,
+            grid_x, grid_y, grid_z,
+            block_x, block_y, block_z,
+            shared_mem,
+            stream_ptr,
+            params_ptr,
+            nil
+          )
+
+          check_result!(result, "cuLaunchKernel")
+        end
+
+        # Unload a module
+        # @param cuda_module [FFI::Pointer] Module handle
+        # @return [void]
+        def unload_module(cuda_module)
+          return if cuda_module.nil? || cuda_module.null?
+
+          ensure_loaded!
+          cuModuleUnload(cuda_module)
+        end
+
+        # Get current CUDA context
+        # @return [FFI::Pointer] Context handle (CUcontext)
+        # @raise [CudaDriverError] If no context is current
+        def get_current_context
+          ensure_loaded!
+
+          ctx_ptr = FFI::MemoryPointer.new(:pointer)
+          result = cuCtxGetCurrent(ctx_ptr)
+          check_result!(result, "cuCtxGetCurrent")
+
+          ctx_ptr.read_pointer
+        end
+
+        # Set current CUDA context
+        # @param context [FFI::Pointer] Context handle
+        # @return [void]
+        # @raise [CudaDriverError] If context cannot be set
+        def set_current_context(context)
+          ensure_loaded!
+
+          result = cuCtxSetCurrent(context)
+          check_result!(result, "cuCtxSetCurrent")
+        end
+
+        # Get device compute capability
+        # @param device_id [Integer] Device index
+        # @return [Array<Integer>] [major, minor] compute capability
+        # @raise [CudaDriverError] If attribute cannot be retrieved
+        def get_device_compute_capability(device_id)
+          ensure_loaded!
+
+          device_ptr = FFI::MemoryPointer.new(:int)
+          result = cuDeviceGet(device_ptr, device_id)
+          check_result!(result, "cuDeviceGet")
+
+          device = device_ptr.read_int
+
+          major_ptr = FFI::MemoryPointer.new(:int)
+          minor_ptr = FFI::MemoryPointer.new(:int)
+
+          result = cuDeviceGetAttribute(major_ptr, 75, device) # CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR
+          check_result!(result, "cuDeviceGetAttribute(major)")
+
+          result = cuDeviceGetAttribute(minor_ptr, 76, device) # CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MINOR
+          check_result!(result, "cuDeviceGetAttribute(minor)")
+
+          [major_ptr.read_int, minor_ptr.read_int]
+        end
+
+        # Synchronize current context
+        # @return [void]
+        # @raise [CudaDriverError] If synchronization fails
+        def context_synchronize
+          ensure_loaded!
+
+          result = cuCtxSynchronize()
+          check_result!(result, "cuCtxSynchronize")
+        end
+
+        # Check CUDA Driver result and raise on error
+        # @param result [Integer] CUDA result code
+        # @param context [String] Context for error message
+        # @return [void]
+        # @raise [CudaDriverError] If result is not success
+        def check_result!(result, context)
+          return if result == CUDA_SUCCESS
+
+          raise CudaDriverError.new(result, context: context)
+        end
+
+        private
+
+        # Load CUDA driver library
+        # @return [void]
+        def load_cuda_driver!
+          begin
+            Ignis::CUDA::LibraryLoader.load_library(:cuda_driver)
+          rescue LibraryNotFoundError
+            ffi_lib "nvcuda"
+          end
+        end
+
+        # Initialize CUDA driver
+        # @return [void]
+        def initialize_driver!
+          return if @initialized
+
+          result = cuInit(0)
+          if result == CUDA_SUCCESS
+            @initialized = true
+          else
+            Ignis.logger.warn("cuInit returned #{result}, driver may already be initialized")
+            @initialized = true
+          end
+        end
+
+        # Attach all CUDA Driver FFI functions
+        # @return [void]
+        def attach_driver_functions!
+          begin
+            handle = Ignis::CUDA::LibraryLoader.load_library(:cuda_driver)
+            define_driver_function(handle, :cuInit, [:uint], :int)
+            define_driver_function(handle, :cuCtxGetCurrent, [:pointer], :int)
+            define_driver_function(handle, :cuCtxSetCurrent, [:pointer], :int)
+            define_driver_function(handle, :cuCtxSynchronize, [], :int)
+            define_driver_function(handle, :cuDeviceGet, [:pointer, :int], :int)
+            define_driver_function(handle, :cuDeviceGetAttribute, [:pointer, :int, :int], :int)
+            define_driver_function(handle, :cuModuleLoadData, [:pointer, :pointer], :int)
+            define_driver_function(handle, :cuModuleLoadDataEx, [:pointer, :pointer, :uint, :pointer, :pointer], :int)
+            define_driver_function(handle, :cuModuleGetFunction, [:pointer, :pointer, :pointer], :int)
+            define_driver_function(handle, :cuModuleUnload, [:pointer], :int)
+            define_driver_function(handle, :cuLaunchKernel, [
+              :pointer,     # CUfunction
+              :uint, :uint, :uint, # grid dims
+              :uint, :uint, :uint, # block dims
+              :uint,        # shared mem
+              :pointer,     # stream
+              :pointer,     # kernelParams
+              :pointer      # extra
+            ], :int)
+          rescue LibraryNotFoundError
+            attach_function :cuInit, [:uint], :int
+            attach_function :cuCtxGetCurrent, [:pointer], :int
+            attach_function :cuCtxSetCurrent, [:pointer], :int
+            attach_function :cuCtxSynchronize, [], :int
+            attach_function :cuDeviceGet, [:pointer, :int], :int
+            attach_function :cuDeviceGetAttribute, [:pointer, :int, :int], :int
+            attach_function :cuModuleLoadData, [:pointer, :pointer], :int
+            attach_function :cuModuleLoadDataEx, [:pointer, :pointer, :uint, :pointer, :pointer], :int
+            attach_function :cuModuleGetFunction, [:pointer, :pointer, :pointer], :int
+            attach_function :cuModuleUnload, [:pointer], :int
+            attach_function :cuLaunchKernel, [
+              :pointer, :uint, :uint, :uint, :uint, :uint, :uint,
+              :uint, :pointer, :pointer, :pointer
+            ], :int
+          end
+        end
+
+        # Define a Driver API function from the loaded library
+        # @param handle [FFI::DynamicLibrary] Library handle
+        # @param name [Symbol] Function name
+        # @param args [Array] Argument types
+        # @param ret [Symbol] Return type
+        # @return [void]
+        def define_driver_function(handle, name, args, ret)
+          # LibraryLoader returns a Fiddle::Handle; resolve the symbol address with
+          # Fiddle::Handle#[] and build an FFI::Function from it (Fiddle::Handle has
+          # no #find_function method).
+          func_ptr = begin
+            handle[name.to_s]
+          rescue Fiddle::DLError
+            nil
+          end
+          raise CudaDriverError.new(CUDA_ERROR_NOT_FOUND, context: "Function #{name} not found") unless func_ptr
+
+          func = FFI::Function.new(ret, args, FFI::Pointer.new(func_ptr))
+          define_singleton_method(name) { |*call_args| func.call(*call_args) }
+        end
+
+        # Normalize dimensions to [x, y, z]
+        # @param dims [Array<Integer>, Integer] Dimensions
+        # @return [Array<Integer>] [x, y, z] with defaults of 1
+        def normalize_dims(dims)
+          dims = [dims] if dims.is_a?(Integer)
+          dims = dims.dup
+          dims << 1 while dims.size < 3
+          dims[0..2]
+        end
+
+        # Build kernel params array from pointers
+        # @param params [Array<FFI::Pointer>] Parameter pointers
+        # @return [FFI::Pointer] Array of pointers for cuLaunchKernel
+        def build_params_array(params)
+          return nil if params.empty?
+
+          params_ptr = FFI::MemoryPointer.new(:pointer, params.size)
+          params.each_with_index do |param_ptr, i|
+            params_ptr.put_pointer(i * FFI::Pointer.size, param_ptr)
+          end
+          params_ptr
+        end
+      end
+    end
+  end
+end

data/lib/nvruby/jit/kernel.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Ignis
+  module JIT
+    # High-level kernel execution interface
+    # Provides easy-to-use launch configuration and argument marshaling
+    class Kernel
+      # @return [KernelModule] The underlying kernel module
+      attr_reader :kernel_module
+
+      # @return [Integer] Total number of times this kernel has been launched
+      attr_reader :launch_count
+
+      # @return [Float] Total time spent in kernel launches (seconds)
+      attr_reader :total_launch_time
+
+      # Create a new Kernel wrapper
+      # @param kernel_module [KernelModule] The loaded kernel module
+      def initialize(kernel_module)
+        @kernel_module = kernel_module
+        @launch_count = 0
+        @total_launch_time = 0.0
+        @mutex = Mutex.new
+      end
+
+      # Get the kernel function name
+      # @return [String]
+      def name
+        @kernel_module.kernel_name
+      end
+
+      # Get the device this kernel is loaded on
+      # @return [Integer]
+      def device_id
+        @kernel_module.device_id
+      end
+
+      # Launch the kernel with specified configuration
+      # @param grid [Array<Integer>, Integer] Grid dimensions (blocks)
+      # @param block [Array<Integer>, Integer] Block dimensions (threads)
+      # @param args [Array] Kernel arguments (NvArray, scalars, pointers)
+      # @param shared_mem [Integer] Dynamic shared memory in bytes
+      # @param stream [CUDA::Stream, nil] CUDA stream for async execution
+      # @return [self] Returns self for chaining
+      # @raise [CudaDriverError] If launch fails
+      # @raise [InvalidOperationError] If kernel module destroyed
+      def launch(grid:, block:, args: [], shared_mem: 0, stream: nil)
+        raise InvalidOperationError, "Kernel module has been destroyed" if @kernel_module.destroyed?
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        Ignis.set_device(device_id)
+        param_pointers = marshal_arguments(args)
+        stream_ptr = extract_stream_pointer(stream)
+
+        DriverAPIBindings.launch_kernel(
+          @kernel_module.function_handle,
+          grid_dim: normalize_dims(grid),
+          block_dim: normalize_dims(block),
+          kernel_params: param_pointers,
+          shared_mem: shared_mem,
+          stream: stream_ptr
+        )
+
+        @mutex.synchronize do
+          @launch_count += 1
+          @total_launch_time += Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        end
+
+        self
+      end
+
+      # Synchronous kernel launch with automatic device synchronization
+      # @param grid [Array<Integer>, Integer] Grid dimensions
+      # @param block [Array<Integer>, Integer] Block dimensions
+      # @param args [Array] Kernel arguments
+      # @param shared_mem [Integer] Dynamic shared memory
+      # @return [self]
+      def launch_sync(grid:, block:, args: [], shared_mem: 0)
+        launch(grid: grid, block: block, args: args, shared_mem: shared_mem, stream: nil)
+        Ignis.synchronize
+        self
+      end
+
+      # Calculate optimal grid size for a given element count
+      # @param total_elements [Integer] Total number of elements to process
+      # @param block_size [Integer] Desired block size (threads per block)
+      # @return [Array<Integer>] Grid dimensions
+      def self.calc_grid_size(total_elements, block_size: 256)
+        blocks = (total_elements + block_size - 1) / block_size
+        [blocks]
+      end
+
+      # Get execution statistics
+      # @return [Hash] Statistics including launch count and timing
+      def stats
+        @mutex.synchronize do
+          {
+            kernel_name: name,
+            device_id: device_id,
+            launch_count: @launch_count,
+            total_launch_time: @total_launch_time,
+            avg_launch_time: @launch_count.positive? ? @total_launch_time / @launch_count : 0.0
+          }
+        end
+      end
+
+      # Get a string representation
+      # @return [String]
+      def to_s
+        "#<Ignis::JIT::Kernel #{name} device=#{device_id} launches=#{@launch_count}>"
+      end
+
+      # Get detailed inspection
+      # @return [String]
+      def inspect
+        "#<Ignis::JIT::Kernel:0x#{object_id.to_s(16)} " \
+          "name=#{name.inspect} " \
+          "device=#{device_id} " \
+          "launches=#{@launch_count}>"
+      end
+
+      private
+
+      # Marshal Ruby arguments into FFI pointers for kernel params
+      # @param args [Array] Mixed array of NvArray, scalars, or pointers
+      # @return [Array<FFI::Pointer>] Array of parameter pointers
+      def marshal_arguments(args)
+        args.map { |arg| marshal_single_argument(arg) }
+      end
+
+      # Marshal a single argument to an FFI pointer
+      # @param arg [Object] NvArray, Numeric, or FFI::Pointer
+      # @return [FFI::Pointer]
+      def marshal_single_argument(arg)
+        case arg
+        when U64
+          marshal_u64(arg.value)
+        when FFI::Pointer
+          marshal_pointer(arg)
+        when Integer
+          marshal_integer(arg)
+        when Float
+          marshal_float(arg)
+        else
+          # Duck-typed GPU array: anything exposing the device-pointer API
+          # (Ignis::Shared::NvArray, or Ignis::NvArray from ignis-numerics).
+          if arg.respond_to?(:device_ffi_ptr)
+            marshal_nvarray(arg)
+          else
+            raise ArgumentError, "Unsupported kernel argument type: #{arg.class}"
+          end
+        end
+      end
+
+      # Wrapper forcing 64-bit (unsigned long long / size_t) marshalling of an
+      # integer kernel argument. The default Integer path is 32-bit (`int`); the
+      # kernel ABI is fixed by the parameter type, so a 64-bit parameter (e.g. an
+      # RNG seed) MUST be wrapped: kernel.launch(args: [..., U64.new(seed), n]).
+      U64 = Struct.new(:value)
+
+      # Marshal NvArray to device pointer
+      # @param arr [NvArray]
+      # @return [FFI::Pointer]
+      def marshal_nvarray(arr)
+        arr.to_device unless arr.on_device?
+        ptr = FFI::MemoryPointer.new(:pointer)
+        # device_ptr is a Fiddle::Pointer; the Driver API launch path is FFI, so
+        # use the FFI-wrapped device pointer.
+        ptr.write_pointer(arr.device_ffi_ptr)
+        ptr
+      end
+
+      # Marshal an existing pointer
+      # @param pointer [FFI::Pointer]
+      # @return [FFI::Pointer]
+      def marshal_pointer(pointer)
+        ptr = FFI::MemoryPointer.new(:pointer)
+        ptr.write_pointer(pointer)
+        ptr
+      end
+
+      # Marshal a 32-bit integer value (for `int` kernel params).
+      # @param value [Integer]
+      # @return [FFI::Pointer]
+      def marshal_integer(value)
+        unless value >= -(2**31) && value < 2**31
+          raise ArgumentError,
+                "Integer #{value} exceeds 32-bit kernel-arg range; wrap it in " \
+                "Ignis::JIT::Kernel::U64.new(x) for an unsigned long long parameter"
+        end
+        ptr = FFI::MemoryPointer.new(:int32)
+        ptr.write_int32(value)
+        ptr
+      end
+
+      # Marshal a 64-bit unsigned integer (for `unsigned long long` / `size_t` params).
+      # @param value [Integer]
+      # @return [FFI::Pointer]
+      def marshal_u64(value)
+        ptr = FFI::MemoryPointer.new(:uint64)
+        ptr.write_uint64(value)
+        ptr
+      end
+
+      # Marshal a float value
+      # @param value [Float]
+      # @return [FFI::Pointer]
+      def marshal_float(value)
+        ptr = FFI::MemoryPointer.new(:float)
+        ptr.write_float(value)
+        ptr
+      end
+
+      # Normalize dimensions to [x, y, z] format
+      # @param dims [Array<Integer>, Integer]
+      # @return [Array<Integer>]
+      def normalize_dims(dims)
+        dims = [dims] if dims.is_a?(Integer)
+        dims = dims.dup
+        dims << 1 while dims.size < 3
+        dims[0..2]
+      end
+
+      # Extract raw stream pointer
+      # @param stream [CUDA::Stream, FFI::Pointer, nil]
+      # @return [FFI::Pointer, nil]
+      def extract_stream_pointer(stream)
+        case stream
+        when nil
+          nil
+        when FFI::Pointer
+          stream
+        else
+          stream.respond_to?(:handle) ? stream.handle : nil
+        end
+      end
+    end
+  end
+end