sgc-ruby-cuda 0.1.0

data/README.rdoc

@@ -0,0 +1,106 @@
+== Welcome to SGC-Ruby-CUDA
+
+SGC-Ruby-CUDA implements Ruby bindings to Nvidia CUDA SDK. It provides easy
+access to CUDA-enabled GPU from a Ruby program.
+
+SGC-Ruby-CUDA is incomplete in many ways. Currently, it supports only some
+crucial CUDA Driver and Runtime API functions. We hope to expand the coverage
+as much as possible.
+
+SGC-Ruby-CUDA is tested on 64bit Fedora 14. We are looking forward to support
+Mac OSX. We have not tested it against 32bit Linux OS and Windows. We certainly
+wish to improve the code base to support multiple platforms in the future.
+We also welcome CUDA users to test it against their working environments.
+
+Current development will focus on supporting CUDA Toolkit 4.0.
+
+Check out {file:doc/features.rdoc} for the supported CUDA features.
+Also see {file:doc/devel.rdoc} for the latest development plan.
+
+
+Fedora and the Infinity design logo are trademarks of Red Hat, Inc.
+
+Linux is a registered trademark of Linus Torvalds.
+
+NVIDIA, the NVIDIA logo, CUDA, GeForce, Quadro, and Tesla are trademarks or
+registered trademarks of NVIDIA Corporation in the U.S. and other countries.
+
+Windows is a registered trademark of Microsoft Corporation in the United States
+and other countries.
+
+
+== Design philosophy
+
+The Ruby bindings, Ruby CUDA API, which deal directly with Nvidia CUDA SDK C/C++
+bindings retain the CUDA Driver and Runtime API in a systematic way whenever
+possible. This facilitates developers familiar with CUDA C who should be able to
+use SGC-Ruby-CUDA with minimum effort. At times, we may design the API to be
+more Ruby-like and let go unnecessary API structure in modern programming
+language.
+
+We use Ruby-FFI as a bridge to call the CUDA C API. Ruby classes and methods to
+are built on top. The use of Ruby-FFI would ease the support of multiple Ruby
+interpretors.
+
+
+== Prerequisites
+
+* Ruby         (Tested with Ruby 1.9.2)
+* Ruby-FFI     (Tested with Ruby-FFI 1.0.7)
+* CUDA Toolkit (Tested with CUDA Toolkit 4.0)
+* C++ compiler (Tested with GCC 4.6.0 but requires simple patch to CUDA Toolkit)
+* Yard         (Tested with Yard 0.6.7, required for generating documentations)
+
+
+== How to get SGC-Ruby-CUDA
+
+The SGC-Ruby-CUDA git repository can be found in the following:
+
+    http://github.com/xman/sgc-ruby-cuda
+    git://rubyforge.org/rubycuda.git
+
+The master branch can be checked out with the following command:
+
+    git clone git://github.com/xman/sgc-ruby-cuda.git sgc-ruby-cuda
+    git clone git://rubyforge.org/rubycuda.git sgc-ruby-cuda
+
+The devel* branches may be checked out for a peep on the latest development.
+However, they are highly volatile and _rebase_ may be applied for cleaner
+commits. The devel* branches serve as grace period before commits move into
+mainstream or master branches which are considered stable commits. This would
+minimize unnecessary fixing commits.
+
+
+== Getting started
+
+    # Setup the environment. Assuming the CUDA Toolkit is installed in
+    # the default path /usr/local/cuda.
+
+    # For 64bit Linux:
+    export CPATH="/usr/local/cuda/include"
+    export LIBRARY_PATH="/usr/local/cuda/lib64"
+    export LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH"
+    export PATH="/usr/local/cuda/bin:$PATH"
+
+    gem install ffi
+    cd sgc-ruby-cuda
+    rake test
+    # Check out the test cases in test/ on how to use Ruby CUDA API.
+
+    gem install yard
+    cd sgc-ruby-cuda
+    rake yard
+    # Check out the generated documentations in html/index.html with a browser.
+
+
+== License
+
+SGC-Ruby-CUDA is released under the GNU GPLv3. See the file COPYING.
+
+
+== The Author
+
+All kinds of feedbacks and bug reports are welcomed. Here is the author's email
+address:
+
+    shinyee@speedgocomputing.com

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/clean'
+require 'yard'
+
+load 'version.rb'
+
+CUDA_PATH         = "lib/cuda"
+CUDA_DRIVER_PATH  = "#{CUDA_PATH}/driver"
+CUDA_RUNTIME_PATH = "#{CUDA_PATH}/runtime"
+DOC_PATH          = "doc"
+HTML_OUTPUT_PATH  = "html"
+
+
+task :default => []
+
+desc 'Build everything.'
+task :all => [:package, :yard]
+
+
+spec = Gem::Specification.new do |s|
+    s.platform    = Gem::Platform::RUBY
+    s.name        = 'sgc-ruby-cuda'
+    s.version     = SGC_RUBY_CUDA_VERSION
+    s.summary     = 'Ruby bindings for using Nvidia CUDA.'
+    s.description = 'SGC-Ruby-CUDA implements Ruby bindings to Nvidia CUDA SDK. It provides easy access to CUDA-enabled GPU from a Ruby program.'
+
+    s.required_ruby_version     = '>= 1.9.2'
+
+    s.author            = 'Chung Shin Yee'
+    s.email             = 'shinyee@speedgocomputing.com'
+    s.homepage          = 'https://rubyforge.org/projects/rubycuda'
+    s.rubyforge_project = 'rubycuda'
+
+    s.require_path = 'lib'
+
+    s.files  = FileList['lib/**/*.rb', "#{DOC_PATH}/**/*.rdoc"].to_a
+    s.files += ['Rakefile', 'version.rb', 'README.rdoc', 'COPYING']
+    s.files += ['.yardopts']
+    s.test_files = FileList['test/{**/*.rb,vadd.cu,bad.ptx}'].to_a
+
+    s.add_dependency 'ffi', '>= 1.0.7'
+    s.add_dependency 'yard', '>= 0.6.7'
+
+    s.requirements << 'CUDA Toolkit 4.0'
+    s.requirements << 'C++ compiler'
+    s.requirements << 'CUDA-enabled GPU'
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar_gz  = true
+end
+
+
+desc 'Generate SGC Ruby CUDA documentation with YARD.'
+task :yard
+YARD::Rake::YardocTask.new do |t|
+    t.files = FileList['lib/**/*.rb'].to_a
+    t.options += ['-o', "#{HTML_OUTPUT_PATH}"]
+end
+
+
+desc 'Run SGC Ruby CUDA test cases.'
+task :test
+Rake::TestTask.new do |t|
+    t.libs << 'lib'
+
+    t.test_files = FileList['test/**/test_*.rb'].to_a
+    t.verbose    = true
+end
+
+
+CLEAN.include ['pkg', "#{HTML_OUTPUT_PATH}"]
+CLEAN.include ['**/*.o', '**/*.so']
+CLEAN.include ['test/vadd.ptx']

data/doc/devel.rdoc

@@ -0,0 +1,77 @@
+= Development Plan
+SGC-Ruby-CUDA development plan provides an outline of features, issues, etc.
+that will be tackled in order. There is currently no strict timeline on when
+these features or issues will be covered. We hope at least we are progressing
+consistently and catching up the development of Nvidia CUDA SDK.
+
+
+== Creating Ruby bindings for using CUDA Driver API on Linux Platform
+
+=== On-going
+* Include Ruby bindings for the use of CUDA compiler to compile a .cu file to
+  generate a .ptx file.
+* Supporting CUDA Toolkit 4.0.
+
+=== Todo
+* Port some CUDA samples to SGC-Ruby-CUDA with benchmark.
+* Develop sample programs.
+
+
+== Creating Ruby bindings for using CUDA Driver API on Mac Platform
+
+=== On-going
+
+=== Todo
+
+
+== Towards robust development of Ruby CUDA Driver API
+
+=== On-going
+
+=== Todo
+* Update the memory abstraction or parameter passing.
+  * To allow one to specify a paramater as a float or double, int or long, etc.
+  * To provide memory buffers for more data types?
+
+
+== Creating Ruby bindings for using CUDA Runtime API on Linux Platform
+
+=== On-going
+* Supporting CUDA Toolkit 4.0.
+
+=== Todo
+* Develop sample programs.
+
+
+== Creating Ruby bindings for using CUDA Runtime API on Mac Platform
+
+=== On-going
+
+=== Todo
+
+
+== Towards portable platform - supporting Linux, Mac, Windows
+
+=== Todo
+* Support portable compilations.
+* Support portable paths?
+* Configurable tools? compiler commands, flags, etc.
+* Release SGC-Ruby-CUDA gems for multiple platforms.
+
+
+== Development of generic kernel programs
+
+=== Todo
+* Identify interesting sample kernel programs bundled with CUDA Toolkit, pycuda,
+  ruby-opencl, etc.
+* Identify open source kernels available on the web.
+* Adopt or develop kernel programs.
+* Develop tests and benchmark programs for the kernels.
+* Optimizing the kernel performance.
+
+
+== Development of benchmarking suite
+
+=== Todo
+* Identify existing benchmarking suites for GPU.
+* Porting existing CUDA kernels and benchmark programs to SGC-Ruby-CUDA.

data/doc/features.rdoc

@@ -0,0 +1,55 @@
+== Supported CUDA 4.0 Driver API Modules
+
+    * Fully supported (excluding deprecated functions).
+    + Partially supported.
+    - Not supported.
+
+    Feature                         Supported?
+    ------------------------------------------
+    Version Management                  *
+    Device Management                   *
+    Context Management                  *
+    Module Management                   +
+    Memory Management                   +
+    Unified Addressing                  -
+    Peer Context Memory Access          -
+    Execution Control                   +
+    Stream Management                   *
+    Event Management                    *
+    Texture Reference Management        -
+    Surface Reference Management        -
+    Graphics Interoperability           -
+    OpenGL Interoperability             -
+    Direct3D 9 Interoperability         -
+    Direct3D 10 Interoperability        -
+    Direct3D 11 Interoperability        -
+    VDPAU Interoperability              -
+
+
+== Supported CUDA 4.0 Runtime API Modules
+
+    * Fully supported (excluding deprecated functions).
+    + Partially supported.
+    - Not supported.
+
+    Feature                         Supported?
+    ------------------------------------------
+    Version Management                  *
+    Error Handling                      *
+    Device Management                   +
+    Thread Management                   *
+    Memory Management                   +
+    Unified Addressing                  -
+    Peer Device Memory Access           -
+    Execution Control                   +
+    Stream Management                   *
+    Event Management                    *
+    Texture Reference Management        -
+    Surface Reference Management        -
+    C++ API Routines                    -
+    Graphics Interoperability           -
+    OpenGL Interoperability             -
+    Direct3D 9 Interoperability         -
+    Direct3D 10 Interoperability        -
+    Direct3D 11 Interoperability        -
+    VDPAU Interoperability              -

data/lib/cuda/driver/context.rb

@@ -0,0 +1,236 @@
+#
+# Copyright (c) 2011 Chung Shin Yee
+#
+#       shinyee@speedgocomputing.com
+#       http://www.speedgocomputing.com
+#       http://github.com/xman/sgc-ruby-cuda
+#       http://rubyforge.org/projects/rubycuda
+#
+# This file is part of SGC-Ruby-CUDA.
+#
+# SGC-Ruby-CUDA is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# SGC-Ruby-CUDA is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with SGC-Ruby-CUDA.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'cuda/driver/ffi-cu'
+require 'cuda/driver/cu'
+require 'cuda/driver/error'
+require 'helpers/flags'
+
+
+module SGC
+module CU
+
+class CUContext
+
+    # Create a new CUDA context with _flags_ (CUContextFlags) and _device_ (CUDevice),
+    # then associate it with the calling thread, and return the context.
+    #
+    # @overload create(device)
+    # @overload create(flags, device)
+    # @param [Integer, CUContextFlags, Array<Integer, CUContextFlags>] flags
+    #   The list of flags to use for the CUDA context creation.
+    #   Setting _flags_ to 0 or ommitting _flags_ uses SCHED_AUTO.
+    # @param [CUDevice] device The device to create the CUDA context with.
+    # @return [CUContext] A CUDA context created with _flags_ and _device_.
+    #
+    # @example Create CUDA context with different flags.
+    #     dev = CUDevice.get(0)
+    #     CUContext.create(dev)                 #=> ctx
+    #     CUContext.create(0, dev)              #=> ctx
+    #     CUContext.create(:SCHED_SPIN, dev)    #=> ctx
+    #     CUContext.create([:SCHED_SPIN, :BLOCKING_SYNC], dev)    #=> ctx
+    def self.create(arg1, arg2 = nil)
+        if arg2 != nil
+            flags, dev = arg1, arg2
+            flags = CUContextFlags.value(flags)
+        else
+            flags = 0
+            dev = arg1
+        end
+
+        p = FFI::MemoryPointer.new(:CUContext)
+        status = API::cuCtxCreate(p, flags, dev.to_api)
+        Pvt::handle_error(status, "Failed to create CUDA context: flags = #{flags}.")
+        new(p)
+    end
+
+
+    # Destroy this CUDA context.
+    def destroy
+        status = API::cuCtxDestroy(self.to_api)
+        Pvt::handle_error(status, "Failed to destroy CUDA context.")
+        nil
+    end
+
+
+    # @deprecated
+    #
+    # Increment the reference count on this CUDA context.
+    # @overload attach
+    # @overload attach(flags)
+    # @param [Integer] flags Currently _flags_ must be set to zero.
+    # @return [CUContext] This CUDA context.
+    def attach(flags = 0)
+        status = API::cuCtxAttach(@pcontext, flags)
+        Pvt::handle_error(status, "Failed to attach CUDA context: flags = #{flags}.")
+        self
+    end
+
+
+    # @deprecated
+    #
+    # Decrement the reference count on this CUDA context.
+    def detach
+        status = API::cuCtxDetach(self.to_api)
+        Pvt::handle_error(status, "Failed to detach CUDA context.")
+        nil
+    end
+
+
+    # @return [CUContext] The CUDA context bound to the calling CPU thread.
+    def self.current
+        p = FFI::MemoryPointer.new(:CUContext)
+        status = API::cuCtxGetCurrent(p)
+        Pvt::handle_error(status, "Failed to get the current CUDA context.")
+        new(p)
+    end
+
+
+    # Set the current CUDA context to _context_.
+    # @param [CUContext] The CUDA context to set as the current CUDA context.
+    def self.current=(context)
+        status = API::cuCtxSetCurrent(context.to_api)
+        Pvt::handle_error(status, "Failed to set the current CUDA context.")
+    end
+
+
+    # Push this CUDA context onto the CUDA context stack, which becomes currently active CUDA context.
+    # @return [CUContext] This CUDA context.
+    def push_current
+        status = API::cuCtxPushCurrent(self.to_api)
+        Pvt::handle_error(status, "Failed to push this CUDA context.")
+        self
+    end
+
+
+    # @return [Integer] The API version used to create this CUDA context.
+    def api_version
+        p = FFI::MemoryPointer.new(:uint)
+        status = API::cuCtxGetApiVersion(self.to_api, p)
+        Pvt::handle_error(status, "Failed to get the API version of this CUDA context.")
+        p.get_uint(0)
+    end
+
+
+    # @return [Integer] The API version used to create the current CUDA context.
+    def self.api_version
+        p = FFI::MemoryPointer.new(:uint)
+        status = API::cuCtxGetApiVersion(nil, p)
+        Pvt::handle_error(status, "Failed to get the API version of the current CUDA context.")
+        p.get_uint(0)
+    end
+
+
+    # @return [CUDevice] The device associated to the current CUDA context.
+    def self.device
+        p = FFI::MemoryPointer.new(:CUDevice)
+        status = API::cuCtxGetDevice(p)
+        Pvt::handle_error(status, "Failed to get the current CUDA context's device.")
+        CUDevice.send(:new, p)
+    end
+
+
+    # @param [CULimit] lim The particular limit attribute to query.
+    # @return [Integer] The limit _lim_ (CULimit) of the current CUDA context.
+    #
+    # @example Get the stack size limit.
+    #     CUContext.limit(:STACK_SIZE)    #=> 8192
+    def self.limit(lim)
+        p = FFI::MemoryPointer.new(:size_t)
+        status = API::cuCtxGetLimit(p, lim)
+        Pvt::handle_error(status, "Failed to get the current CUDA context limit: limit = #{lim}")
+        API::read_size_t(p)
+    end
+
+
+    # Set the limit _lim_ (CULimit) of the current CUDA context to _value_.
+    # @param [CULimit] lim The particular limit attribute to set.
+    # @param [Integer] value The value to set the limit to.
+    #
+    # @example Set the stack size limit.
+    #     CUContext.limit = [:STACK_SIZE, 8192]    #=> [:STACK_SIZE, 8192]
+    #     CUContext.limit = :STACK_SIZE, 8192      #=> [:STACK_SIZE, 8192]
+    def self.limit=(*lim_val_pair)
+        lim, val = lim_val_pair.flatten
+        lim != nil && val != nil or raise ArgumentError, "Invalid limit and value pair given: limit = #{lim}, value = #{val}."
+        status = API::cuCtxSetLimit(lim, val)
+        Pvt::handle_error(status, "Failed to set the current CUDA context limit: limit = #{lim}, value = #{val}")
+    end
+
+
+    # @return [CUFunctionCache] The cache config of the current CUDA context.
+    #
+    # @example Get the cache config.
+    #     CUContext.cache_config    #=> :PREFER_NONE
+    def self.cache_config
+        p = FFI::MemoryPointer.new(:enum)
+        status = API::cuCtxGetCacheConfig(p)
+        Pvt::handle_error(status, "Failed to get the current CUDA context cache config.")
+        CUFunctionCache[API::read_enum(p)]
+    end
+
+
+    # Set the cache to _conf_ (CUFunctionCache) for the current CUDA context.
+    #
+    # @example Set the cache config to prefer shared.
+    #     CUContext.cache_config = :PREFER_SHARED    #=> :PREFER_SHARED
+    def self.cache_config=(conf)
+        status = API::cuCtxSetCacheConfig(conf)
+        Pvt::handle_error(status, "Failed to set the current CUDA context cache config: config = #{conf}")
+    end
+
+
+    # Pop the current CUDA context from the CUDA context stack, which becomes inactive.
+    def self.pop_current
+        p = FFI::MemoryPointer.new(:CUContext)
+        status = API::cuCtxPopCurrent(p)
+        Pvt::handle_error(status, "Failed to pop current context.")
+        new(p)
+    end
+
+
+    # Block until all the tasks of the current CUDA context complete.
+    def self.synchronize
+        status = API::cuCtxSynchronize
+        Pvt::handle_error(status, "Failed to synchronize the current context.")
+        nil
+    end
+
+
+    # @private
+    def initialize(ptr)
+        @pcontext = ptr
+    end
+    private_class_method(:new)
+
+
+    # @private
+    def to_api
+        API::read_cucontext(@pcontext)
+    end
+
+end
+
+end # module
+end # module