libusb 0.5.1 → 0.6.0

data/ext/libusb_recipe.rb

@@ -0,0 +1,29 @@
+require_relative '../lib/libusb/dependencies'
+require 'rubygems'
+# NOTE: Keep this version constraint in sync with libusb.gemspec
+gem "mini_portile2", LIBUSB::MINI_PORTILE_VERSION
+require "mini_portile2"
+
+class LibusbRecipe < MiniPortile
+  include LIBUSB
+  ROOT = File.expand_path('../..', __FILE__)
+
+  def initialize
+    super("libusb", LIBUSB_VERSION)
+    self.target = File.join(ROOT, "ports")
+    self.files = [url: LIBUSB_SOURCE_URI, sha1: LIBUSB_SOURCE_SHA1]
+    self.configure_options = []
+  end
+
+  def cook_and_activate
+    checkpoint = File.join(self.target, "#{self.name}-#{self.version}-#{self.host}.installed")
+    unless File.exist?(checkpoint)
+      self.cook
+      FileUtils.touch checkpoint
+    end
+    self.activate
+    self
+  end
+
+  public :files_hashs
+end

data/lib/libusb/call.rb

@@ -28,7 +28,7 @@ module LIBUSB
     prefix = FFI::Platform::LIBPREFIX.empty? ? 'lib' : FFI::Platform::LIBPREFIX
     bundled_dll = File.join(root_path, "lib/#{prefix}usb-1.0.#{ext}")
     bundled_dll_cygwin = File.join(root_path, "bin/#{prefix}usb-1.0.#{ext}")
-    ffi_lib(["#{prefix}usb-1.0", bundled_dll, bundled_dll_cygwin])
+    ffi_lib([bundled_dll, bundled_dll_cygwin, "#{prefix}usb-1.0"])
 
     ClassCodes = enum :libusb_class_code, [
       :CLASS_PER_INTERFACE, 0,
@@ -292,7 +292,7 @@ module LIBUSB
     try_attach_function 'libusb_get_ss_endpoint_companion_descriptor', [:pointer, :pointer, :pointer], :int
     try_attach_function 'libusb_free_ss_endpoint_companion_descriptor', [:pointer], :void
 
-    try_attach_function 'libusb_get_bos_descriptor', [:libusb_device_handle, :pointer], :int, :blocking=>true
+    try_attach_function 'libusb_get_bos_descriptor', [:libusb_device_handle, :pointer], :int, blocking: true
     try_attach_function 'libusb_free_bos_descriptor', [:pointer], :void
     try_attach_function 'libusb_get_usb_2_0_extension_descriptor', [:libusb_context, :pointer, :pointer], :int
     try_attach_function 'libusb_free_usb_2_0_extension_descriptor', [:pointer], :void
@@ -305,17 +305,19 @@ module LIBUSB
     attach_function 'libusb_close', [:pointer], :void
     attach_function 'libusb_get_device', [:libusb_device_handle], :pointer
 
-    attach_function 'libusb_set_configuration', [:libusb_device_handle, :int], :int, :blocking=>true
+    attach_function 'libusb_set_configuration', [:libusb_device_handle, :int], :int, blocking: true
     attach_function 'libusb_claim_interface', [:libusb_device_handle, :int], :int
-    attach_function 'libusb_release_interface', [:libusb_device_handle, :int], :int, :blocking=>true
+    attach_function 'libusb_release_interface', [:libusb_device_handle, :int], :int, blocking: true
 
     attach_function 'libusb_open_device_with_vid_pid', [:pointer, :int, :int], :pointer
 
-    attach_function 'libusb_set_interface_alt_setting', [:libusb_device_handle, :int, :int], :int, :blocking=>true
-    attach_function 'libusb_clear_halt', [:libusb_device_handle, :int], :int, :blocking=>true
-    attach_function 'libusb_reset_device', [:libusb_device_handle], :int, :blocking=>true
+    attach_function 'libusb_set_interface_alt_setting', [:libusb_device_handle, :int, :int], :int, blocking: true
+    attach_function 'libusb_clear_halt', [:libusb_device_handle, :int], :int, blocking: true
+    attach_function 'libusb_reset_device', [:libusb_device_handle], :int, blocking: true
     try_attach_function 'libusb_alloc_streams', [:libusb_device_handle, :uint32, :pointer, :int], :int
     try_attach_function 'libusb_free_streams', [:libusb_device_handle, :pointer, :int], :int
+    try_attach_function 'libusb_dev_mem_alloc', [:libusb_device_handle, :size_t], :pointer
+    try_attach_function 'libusb_dev_mem_free', [:libusb_device_handle, :pointer, :size_t], :int
 
     attach_function 'libusb_kernel_driver_active', [:libusb_device_handle, :int], :int
     attach_function 'libusb_detach_kernel_driver', [:libusb_device_handle, :int], :int
@@ -331,10 +333,11 @@ module LIBUSB
     try_attach_function 'libusb_transfer_set_stream_id', [:libusb_transfer, :uint32], :void
     try_attach_function 'libusb_transfer_get_stream_id', [:libusb_transfer], :uint32
 
-    attach_function 'libusb_handle_events', [:libusb_context], :int, :blocking=>true
-    try_attach_function 'libusb_handle_events_completed', [:libusb_context, :pointer], :int, :blocking=>true
-    attach_function 'libusb_handle_events_timeout', [:libusb_context, :pointer], :int, :blocking=>true
-    try_attach_function 'libusb_handle_events_timeout_completed', [:libusb_context, :pointer, :pointer], :int, :blocking=>true
+    attach_function 'libusb_handle_events', [:libusb_context], :int, blocking: true
+    try_attach_function 'libusb_handle_events_completed', [:libusb_context, :pointer], :int, blocking: true
+    attach_function 'libusb_handle_events_timeout', [:libusb_context, :pointer], :int, blocking: true
+    try_attach_function 'libusb_handle_events_timeout_completed', [:libusb_context, :pointer, :pointer], :int, blocking: true
+    try_attach_function 'libusb_interrupt_event_handler', [:libusb_context], :void
 
     callback :libusb_pollfd_added_cb, [:int, :short, :pointer], :void
     callback :libusb_pollfd_removed_cb, [:int, :pointer], :void

data/lib/libusb/compat.rb

@@ -130,7 +130,7 @@ module USB
   end
 
   def USB.each_device_by_class(devclass, subclass=nil, protocol=nil)
-    devs = default_context.devices :bClass=>devclass, :bSubClass=>subclass, :bProtocol=>protocol
+    devs = default_context.devices bClass: devclass, bSubClass: subclass, bProtocol: protocol
     devs.each do |dev|
       yield Device.new(dev)
     end
@@ -313,31 +313,31 @@ module USB
     def usb_control_msg(requesttype, request, value, index, bytes, timeout)
       if requesttype&LIBUSB::ENDPOINT_IN != 0
         # transfer direction in
-        res = @dev.control_transfer(:bmRequestType=>requesttype, :bRequest=>request,
-            :wValue=>value, :wIndex=>index, :dataIn=>bytes.bytesize, :timeout=>timeout)
+        res = @dev.control_transfer(bmRequestType: requesttype, bRequest: request,
+            wValue: value, wIndex: index, dataIn: bytes.bytesize, timeout: timeout)
         bytes[0, res.bytesize] = res
         res.bytesize
       else
         # transfer direction out
-        @dev.control_transfer(:bmRequestType=>requesttype, :bRequest=>request, :wValue=>value,
-            :wIndex=>index, :dataOut=>bytes, :timeout=>timeout)
+        @dev.control_transfer(bmRequestType: requesttype, bRequest: request, wValue: value,
+            wIndex: index, dataOut: bytes, timeout: timeout)
       end
     end
 
     def usb_bulk_write(endpoint, bytes, timeout)
-      @dev.bulk_transfer(:endpoint=>endpoint, :dataOut=>bytes, :timeout=>timeout)
+      @dev.bulk_transfer(endpoint: endpoint, dataOut: bytes, timeout: timeout)
     end
     def usb_bulk_read(endpoint, bytes, timeout)
-      res = @dev.bulk_transfer(:endpoint=>endpoint, :dataIn=>bytes.bytesize, :timeout=>timeout)
+      res = @dev.bulk_transfer(endpoint: endpoint, dataIn: bytes.bytesize, timeout: timeout)
       bytes[0, res.bytesize] = res
       res.bytesize
     end
 
     def usb_interrupt_write(endpoint, bytes, timeout)
-      @dev.interrupt_transfer(:endpoint=>endpoint, :dataOut=>bytes, :timeout=>timeout)
+      @dev.interrupt_transfer(endpoint: endpoint, dataOut: bytes, timeout: timeout)
     end
     def usb_interrupt_read(endpoint, bytes, timeout)
-      res = @dev.interrupt_transfer(:endpoint=>endpoint, :dataIn=>bytes.bytesize, :timeout=>timeout)
+      res = @dev.interrupt_transfer(endpoint: endpoint, dataIn: bytes.bytesize, timeout: timeout)
       bytes[0, res.bytesize] = res
       res.bytesize
     end

data/lib/libusb/context.rb

@@ -181,6 +181,8 @@ module LIBUSB
     # @param [Integer, nil] timeout  the maximum time (in millseconds) to block waiting for
     #                                events, or 0 for non-blocking mode
     # @param [Context::CompletionFlag, nil] completion_flag  CompletionFlag to check
+    #
+    # @see interrupt_event_handler
     def handle_events(timeout=nil, completion_flag=nil)
       if completion_flag && !completion_flag.is_a?(Context::CompletionFlag)
         raise ArgumentError, "completion_flag is not a CompletionFlag"
@@ -203,6 +205,19 @@ module LIBUSB
       LIBUSB.raise_error res, "in libusb_handle_events" if res<0
     end
 
+    if Call.respond_to?(:libusb_interrupt_event_handler)
+      # Interrupt any active thread that is handling events.
+      #
+      # This is mainly useful for interrupting a dedicated event handling thread when an application wishes to call {Context#exit}.
+      #
+      # Available since libusb-1.0.21.
+      #
+      # @see handle_events
+      def interrupt_event_handler
+        Call.libusb_interrupt_event_handler(@ctx)
+      end
+    end
+
     # Obtain a list of devices currently attached to the USB system, optionally matching certain criteria.
     #
     # @param [Hash] filter_hash  A number of criteria can be defined in key-value pairs.
@@ -218,7 +233,7 @@ module LIBUSB
     #
     # @example
     #   # Return all devices of vendor 0x0ab1 where idProduct is 3 or 4:
-    #   context.device :idVendor=>0x0ab1, :idProduct=>[0x0003, 0x0004]
+    #   context.device idVendor: 0x0ab1, idProduct: [0x0003, 0x0004]
     #
     # @return [Array<LIBUSB::Device>]
     def devices(filter_hash={})

data/lib/libusb/dependencies.rb

@@ -0,0 +1,7 @@
+module LIBUSB
+  LIBUSB_VERSION = ENV['LIBUSB_VERSION'] || '1.0.21'
+  LIBUSB_SOURCE_URI = "https://github.com/libusb/libusb/releases/download/v#{LIBUSB_VERSION}/libusb-#{LIBUSB_VERSION}.tar.bz2"
+  LIBUSB_SOURCE_SHA1 = '54d71841542eb1a6f0b0420878a4d5434efe8d28'
+
+  MINI_PORTILE_VERSION = '~> 2.1'
+end

data/lib/libusb/dev_handle.rb

@@ -41,6 +41,9 @@ module LIBUSB
     #
     # This is a non-blocking function; no requests are sent over the bus.
     def close
+      @bulk_transfer.free_buffer if @bulk_transfer
+      @interrupt_transfer.free_buffer if @interrupt_transfer
+      @control_transfer.free_buffer if @control_transfer
       Call.libusb_close(@pHandle)
     end
 
@@ -235,6 +238,13 @@ module LIBUSB
         LIBUSB.raise_error res, "in libusb_free_streams" unless res>=0
         nil
       end
+
+    else
+
+      def alloc_streams(num_streams, endpoints)
+        raise NotImplementedError, "libusb-1.0.19+ is required for bulk stream transfers"
+      end
+
     end
 
     # Determine if a kernel driver is active on an interface.
@@ -374,7 +384,7 @@ module LIBUSB
       raise ArgumentError, "invalid params #{args.inspect}" unless args.empty?
 
       # reuse transfer struct to speed up transfer
-      @bulk_transfer ||= BulkTransfer.new :dev_handle => self
+      @bulk_transfer ||= BulkTransfer.new dev_handle: self, allow_device_memory: true
       tr = @bulk_transfer
       tr.endpoint = endpoint
       tr.timeout = timeout
@@ -442,7 +452,7 @@ module LIBUSB
       raise ArgumentError, "invalid params #{args.inspect}" unless args.empty?
 
       # reuse transfer struct to speed up transfer
-      @interrupt_transfer ||= InterruptTransfer.new :dev_handle => self
+      @interrupt_transfer ||= InterruptTransfer.new dev_handle: self, allow_device_memory: true
       tr = @interrupt_transfer
       tr.endpoint = endpoint
       tr.timeout = timeout
@@ -502,7 +512,7 @@ module LIBUSB
       raise ArgumentError, "invalid params #{args.inspect}" unless args.empty?
 
       # reuse transfer struct to speed up transfer
-      @control_transfer ||= ControlTransfer.new :dev_handle => self
+      @control_transfer ||= ControlTransfer.new dev_handle: self, allow_device_memory: true
       tr = @control_transfer
       tr.timeout = timeout
       if dataIn

data/lib/libusb/eventmachine.rb

@@ -141,7 +141,7 @@ class DevHandle
   # Execute an eventmachine driven USB bulk transfer.
   #
   # @example
-  #   tr = devh.eventmachine_bulk_transfer( :endpoint => 0x02, :dataOut => "data" )
+  #   tr = devh.eventmachine_bulk_transfer( endpoint: 0x02, dataOut: "data" )
   #   tr.callback do |data|
   #     puts "sent: #{data.inspect}"
   #   end
@@ -159,9 +159,9 @@ class DevHandle
   #
   # @example
   #   tr = devh.eventmachine_control_transfer(
-  #     :bmRequestType=>ENDPOINT_IN|REQUEST_TYPE_CLASS|RECIPIENT_INTERFACE,
-  #     :bRequest=>0x01,
-  #     :wValue=>0, :wIndex=>0, :dataIn=>1 )
+  #     bmRequestType: ENDPOINT_IN|REQUEST_TYPE_CLASS|RECIPIENT_INTERFACE,
+  #     bRequest: 0x01,
+  #     wValue: 0, wIndex: 0, dataIn: 1 )
   #   tr.callback do |data|
   #     puts "recved: #{data.inspect}"
   #   end

data/lib/libusb/transfer.rb

@@ -25,10 +25,29 @@ module LIBUSB
   # Using {Transfer} derived classes directly, however, is needed for isochronous transfers and
   # allows a more advanced buffer management.
   class Transfer
+    class ZeroCopyMemory < FFI::Pointer
+      attr_reader :size
+
+      def initialize(dev_handle, ptr, size)
+        @dev_handle = dev_handle
+        @size = size
+        super(ptr)
+      end
+
+      def free(id=nil)
+        return unless @size
+#         puts format("libusb_dev_mem_free(%#x, %d)%s", address, @size, id ? " by GC" : '')
+        res = Call.libusb_dev_mem_free( @dev_handle.pHandle, self, @size )
+        LIBUSB.raise_error res, "in libusb_dev_mem_free" if res!=0
+        @size = nil
+      end
+    end
+
     def initialize(args={})
-      args.each{|k,v| send("#{k}=", v) }
       @buffer = nil
       @completion_flag = Context::CompletionFlag.new
+      @allow_device_memory = false
+      args.each{|k,v| send("#{k}=", v) }
     end
     private :initialize
 
@@ -52,11 +71,9 @@ module LIBUSB
     end
 
     # Set output data that should be sent.
+    # @see #allow_device_memory
     def buffer=(data)
-      if !@buffer || data.bytesize>@buffer.size
-        free_buffer
-        @buffer = FFI::MemoryPointer.new(data.bytesize, 1, false)
-      end
+      ensure_enough_buffer(data.bytesize)
       @buffer.put_bytes(0, data)
       @transfer[:buffer] = @buffer
       @transfer[:length] = data.bytesize
@@ -81,11 +98,9 @@ module LIBUSB
     #
     # @param [Fixnum]  len  Number of bytes to allocate
     # @param [String, nil] data  some data to initialize the buffer with
+    # @see #allow_device_memory
     def alloc_buffer(len, data=nil)
-      if !@buffer || len>@buffer.size
-        free_buffer
-        @buffer = FFI::MemoryPointer.new(len, 1, false)
-      end
+      ensure_enough_buffer(len)
       @buffer.put_bytes(0, data) if data
       @transfer[:buffer] = @buffer
       @transfer[:length] = len
@@ -96,6 +111,52 @@ module LIBUSB
       @transfer[:actual_length]
     end
 
+    # Try to use persistent device memory.
+    #
+    # If enabled, attempts to allocate a block of persistent DMA memory suitable for transfers against the given device.
+    # The memory is allocated by {#alloc_buffer} or {#buffer=}.
+    # If unsuccessful, ordinary user space memory will be used.
+    #
+    # Using this memory instead of regular memory means that the host controller can use DMA directly into the buffer to increase performance, and also that transfers can no longer fail due to kernel memory fragmentation.
+    #
+    # It requires libusb-1.0.21 and Linux-4.6 to be effective, but it can safely be enabled on other systems.
+    #
+    # Note that this type of memory is bound to the {#dev_handle=}.
+    # So even if the {DevHandle} is closed, the memory is still accessable and the device is locked.
+    # It is free'd by the garbage collector eventually, but in order to close the device deterministic, it is required to call {#free_buffer} on all {Transfer}s which use persistent device memory.
+    #
+    # @see #free_buffer
+    # @see #memory_type
+    attr_accessor :allow_device_memory
+
+    # @return +:device_memory+   - If persistent device memory is allocated.
+    # @return +:user_space+      - If user space memory is allocated.
+    # @return +nil+              - If no memory is allocated.
+    def memory_type
+      case @buffer
+        when ZeroCopyMemory then :device_memory
+        when FFI::MemoryPointer then :user_space
+        else nil
+      end
+    end
+
+    def ensure_enough_buffer(len)
+      if !@buffer || len>@buffer.size
+        free_buffer
+        # Try to use zero-copy-memory and fallback to FFI-memory if not available
+        if @allow_device_memory && @dev_handle && Call.respond_to?(:libusb_dev_mem_alloc)
+          ptr = Call.libusb_dev_mem_alloc( @dev_handle.pHandle, len )
+#           puts format("libusb_dev_mem_alloc(%d) => %#x", len, ptr.address)
+          unless ptr.null?
+            buffer = ZeroCopyMemory.new(@dev_handle, ptr, len)
+            ObjectSpace.define_finalizer(self, buffer.method(:free))
+          end
+        end
+        @buffer = buffer || FFI::MemoryPointer.new(len, 1, false)
+      end
+    end
+    private :ensure_enough_buffer
+
     # Retrieve the data actually transferred.
     #
     # @param [Fixnum] offset  optional offset of the retrieved data in the buffer.
@@ -228,7 +289,7 @@ module LIBUSB
 
       # Get a transfers bulk stream id.
       #
-      # Since version 1.0.19.
+      # Available since libusb-1.0.19.
       #
       # @return [Fixnum] the stream id for the transfer
       def stream_id

data/lib/libusb/version_gem.rb

@@ -15,5 +15,5 @@
 
 module LIBUSB
   # Library version of libusb for Ruby
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/libusb.gemspec

@@ -1,6 +1,7 @@
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
 require "libusb/version_gem"
+require "libusb/dependencies"
 
 Gem::Specification.new do |s|
   s.name        = "libusb"
@@ -10,19 +11,20 @@ Gem::Specification.new do |s|
   s.homepage    = "http://github.com/larskanis/libusb"
   s.summary     = %q{Access USB devices from Ruby via libusb-1.0}
   s.description = %q{LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices}
-  s.licenses    = ['LGPL-3']
+  s.licenses    = ['LGPL-3.0']
   s.rdoc_options = %w[--main README.md --charset=UTF-8]
 
-  s.rubyforge_project = "libusb"
-
   s.files         = `git ls-files`.split("\n")
+  s.files         << "ports/archives/libusb-#{LIBUSB::LIBUSB_VERSION}.tar.bz2"
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   s.extensions    = ['ext/extconf.rb']
 
-  s.add_runtime_dependency 'ffi', '>= 1.0'
+  s.required_ruby_version = Gem::Requirement.new(">= 1.9.3")
+  s.add_runtime_dependency 'ffi', '~> 1.0'
+  s.add_runtime_dependency 'mini_portile2', LIBUSB::MINI_PORTILE_VERSION
   s.add_development_dependency 'rake-compiler', '~> 0.9'
   s.add_development_dependency 'rake-compiler-dock', '~> 0.2'
-  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'bundler', '~> 1.0'
 end

data/test/test_libusb_bulk_stream_transfer.rb

@@ -44,7 +44,7 @@ class TestLibusbBulkStreamTransfer < Minitest::Test
   end
 
   def test_bulk_stream_transfer
-    tr = BulkStreamTransfer.new :dev_handle=>@dev, :stream_id=>123, :buffer=>' '*100
+    tr = BulkStreamTransfer.new dev_handle: @dev, stream_id: 123, buffer: ' '*100
     assert_equal 123, tr.stream_id, "stream_id should match"
   end
 end

data/test/test_libusb_descriptors.rb

@@ -161,11 +161,11 @@ class TestLibusbDescriptors < Minitest::Test
       end
     end
 
-    devs2 =  usb.devices( :bClass=>CLASS_MASS_STORAGE, :bSubClass=>0x01, :bProtocol=>0x50 )
-    devs2 += usb.devices( :bClass=>CLASS_MASS_STORAGE, :bSubClass=>0x06, :bProtocol=>0x50 )
+    devs2 =  usb.devices( bClass: CLASS_MASS_STORAGE, bSubClass: 0x01, bProtocol: 0x50 )
+    devs2 += usb.devices( bClass: CLASS_MASS_STORAGE, bSubClass: 0x06, bProtocol: 0x50 )
     assert_equal devs1.sort, devs2.sort, "devices and devices with filter should deliver the same device"
 
-    devs3 =  usb.devices( :bClass=>[CLASS_MASS_STORAGE], :bSubClass=>[0x01,0x06], :bProtocol=>[0x50] )
+    devs3 =  usb.devices( bClass: [CLASS_MASS_STORAGE], bSubClass: [0x01,0x06], bProtocol: [0x50] )
     assert_equal devs1.sort, devs3.sort, "devices and devices with array-filter should deliver the same device"
   end
 
@@ -179,7 +179,7 @@ class TestLibusbDescriptors < Minitest::Test
       end
     end
 
-    devs2 = usb.devices( :bClass=>CLASS_HUB )
+    devs2 = usb.devices( bClass: CLASS_HUB )
     assert_equal devs1.sort, devs2.sort, "devices and devices with filter should deliver the same device"
   end