libusb 0.4.1 → 0.5.0

data/lib/libusb/constants.rb

@@ -26,6 +26,10 @@ module LIBUSB
   Call::IsoSyncTypes.to_h.each{|k,v| const_set(k,v) }
   Call::Speeds.to_h.each{|k,v| const_set(k,v) }
   Call::Capabilities.to_h.each{|k,v| const_set(k,v) }
+  Call::SupportedSpeeds.to_h.each{|k,v| const_set(k,v) }
+  Call::Usb20ExtensionAttributes.to_h.each{|k,v| const_set(k,v) }
+  Call::SsUsbDeviceCapabilityAttributes.to_h.each{|k,v| const_set(k,v) }
+  Call::BosTypes.to_h.each{|k,v| const_set(k,v) }
   Call::HotplugEvents.to_h.each{|k,v| const_set(k,v) }
   Call::HotplugFlags.to_h.each{|k,v| const_set(k,v) }
 

data/lib/libusb/dev_handle.rb

@@ -189,6 +189,54 @@ module LIBUSB
       LIBUSB.raise_error res, "in libusb_reset_device" if res!=0
     end
 
+    if Call.respond_to?(:libusb_alloc_streams)
+
+      # @method alloc_streams
+      #
+      # Allocate up to num_streams usb bulk streams on the specified endpoints. This
+      # function takes an array of endpoints rather then a single endpoint because
+      # some protocols require that endpoints are setup with similar stream ids.
+      # All endpoints passed in must belong to the same interface.
+      #
+      # Note this function may return less streams then requested. Also note that the
+      # same number of streams are allocated for each endpoint in the endpoint array.
+      #
+      # Stream id 0 is reserved, and should not be used to communicate with devices.
+      # If {alloc_streams} returns with a value of N, you may use stream ids
+      # 1 to N.
+      #
+      # Available since libusb-1.0.19.
+      #
+      # @param [Fixnum] num_streams  number of streams to try to allocate
+      # @param [Array<Fixnum>, Array<Endpoint>] endpoints  array of endpoints to allocate streams on
+      # @return [Fixnum] number of streams allocated
+      # @see #free_streams
+      # @see BulkStreamTransfer
+      def alloc_streams(num_streams, endpoints)
+        pEndpoints = endpoints_as_ffi_bytes(endpoints)
+        res = Call.libusb_alloc_streams(@pHandle, num_streams, pEndpoints, endpoints.length)
+        LIBUSB.raise_error res, "in libusb_alloc_streams" unless res>=0
+        res
+      end
+
+      # @method free_streams
+      #
+      # Free usb bulk streams allocated with {alloc_streams}
+      #
+      # Note streams are automatically free-ed when releasing an interface.
+      #
+      # Available since libusb-1.0.19.
+      #
+      # @param [Array<Fixnum>, Array<Endpoint>] endpoints  array of endpoints to free streams on
+      # @see #alloc_streams
+      def free_streams(endpoints)
+        pEndpoints = endpoints_as_ffi_bytes(endpoints)
+        res = Call.libusb_free_streams(@pHandle, pEndpoints, endpoints.length)
+        LIBUSB.raise_error res, "in libusb_free_streams" unless res>=0
+        nil
+      end
+    end
+
     # Determine if a kernel driver is active on an interface.
     #
     # If a kernel driver is active, you cannot claim the interface,
@@ -253,6 +301,26 @@ module LIBUSB
       end
     end
 
+    # @private
+    if Call.respond_to?(:libusb_get_bos_descriptor)
+
+      # @method bos
+      # Get a Binary Object Store (BOS) descriptor.
+      #
+      # This is a BLOCKING function, which will send requests to the device.
+      #
+      # Since libusb version 1.0.16.
+      #
+      # @return [Bos]
+      def bos
+        ctx = device.context.instance_variable_get(:@ctx)
+        pp_desc = FFI::MemoryPointer.new :pointer
+        res = Call.libusb_get_bos_descriptor(@pHandle, pp_desc)
+        LIBUSB.raise_error res, "in libusb_get_bos_descriptor" if res!=0
+        Bos.new(ctx, pp_desc.read_pointer)
+      end
+    end
+
     # Perform a USB bulk transfer.
     #
     # When called without a block, the transfer is done synchronously - so all events are handled
@@ -473,5 +541,14 @@ module LIBUSB
         res
       end
     end
+
+    def endpoints_as_ffi_bytes(endpoints)
+      pEndpoints = FFI::MemoryPointer.new :char, endpoints.length
+      endpoints.each_with_index do |ep, epi|
+        ep = ep.bEndpointAddress if ep.respond_to? :bEndpointAddress
+        pEndpoints.put_uchar(epi, ep)
+      end
+      pEndpoints
+    end
   end
 end

data/lib/libusb/endpoint.rb

@@ -170,5 +170,25 @@ module LIBUSB
       t = bEndpointAddress<=>o.bEndpointAddress if t==0
       t
     end
+
+    if Call.respond_to?(:libusb_get_ss_endpoint_companion_descriptor)
+
+      # @method ss_companion
+      # Get the endpoints superspeed endpoint companion descriptor (if any).
+      #
+      # Since libusb version 1.0.16.
+      #
+      # @return [SsCompanion]
+      def ss_companion
+        ep_comp = FFI::MemoryPointer.new :pointer
+        res = Call.libusb_get_ss_endpoint_companion_descriptor(
+          device.context.instance_variable_get(:@ctx),
+          pointer,
+          ep_comp
+        )
+        LIBUSB.raise_error res, "in libusb_get_ss_endpoint_companion_descriptor" if res!=0
+        SsCompanion.new ep_comp.read_pointer
+      end
+    end
   end
 end

data/lib/libusb/ss_companion.rb

@@ -0,0 +1,69 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby 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 Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'libusb/call'
+
+module LIBUSB
+  # A structure representing the superspeed endpoint companion descriptor.
+  #
+  # This descriptor is documented in section 9.6.7 of the USB 3.0 specification. All multiple-byte fields are represented in host-endian format.
+  class SsCompanion < FFI::ManagedStruct
+    layout :bLength, :uint8,
+        :bDescriptorType, :uint8,
+        :bMaxBurst, :uint8,
+        :bmAttributes, :uint8,
+        :wBytesPerInterval, :uint16
+
+    # Size of this descriptor (in bytes)
+    def bLength
+      self[:bLength]
+    end
+
+    # Descriptor type.
+    #
+    # Will have value LIBUSB::DT_SS_ENDPOINT_COMPANION in this context.
+    def bDescriptorType
+      self[:bDescriptorType]
+    end
+
+    # The maximum number of packets the endpoint can send or recieve as part of a burst.
+    def bMaxBurst
+      self[:bMaxBurst]
+    end
+
+    # In bulk EP: bits 4:0 represents the maximum number of streams the EP supports.
+    #
+    # In isochronous EP: bits 1:0 represents the Mult - a zero based value that determines the maximum number of packets within a service interval
+    def bmAttributes
+      self[:bmAttributes]
+    end
+
+    # The total number of bytes this EP will transfer every service interval.
+    #
+    # valid only for periodic EPs.
+    def wBytesPerInterval
+      self[:wBytesPerInterval]
+    end
+
+    def inspect
+      "\#<#{self.class} burst: #{bMaxBurst} attrs: #{bmAttributes}>"
+    end
+
+    # @private
+    def self.release(ptr)
+      Call.libusb_free_ss_endpoint_companion_descriptor(ptr)
+    end
+  end
+end

data/lib/libusb/transfer.rb

@@ -203,6 +203,40 @@ module LIBUSB
     end
   end
 
+  if Call.respond_to?(:libusb_transfer_get_stream_id)
+
+    # Transfer class for USB bulk transfers using USB-3.0 streams.
+    #
+    # @see DevHandle#alloc_streams
+    #
+    # Available since libusb-1.0.19.
+    class BulkStreamTransfer < Transfer
+      def initialize(args={})
+        @transfer = Call::Transfer.new Call.libusb_alloc_transfer(0)
+        @transfer[:type] = TRANSFER_TYPE_BULK_STREAM
+        @transfer[:timeout] = 1000
+        super
+      end
+
+      # Set a transfers bulk stream id.
+      #
+      # @param [Fixnum] stream_id  the stream id to set
+      def stream_id=(v)
+        Call.libusb_transfer_set_stream_id(@transfer, v)
+        v
+      end
+
+      # Get a transfers bulk stream id.
+      #
+      # Since version 1.0.19.
+      #
+      # @return [Fixnum] the stream id for the transfer
+      def stream_id
+        Call.libusb_transfer_get_stream_id(@transfer)
+      end
+    end
+  end
+
   class ControlTransfer < Transfer
     def initialize(args={})
       @transfer = Call::Transfer.new Call.libusb_alloc_transfer(0)

data/lib/libusb/version_gem.rb

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

data/libusb.gemspec

@@ -10,6 +10,7 @@ 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.rdoc_options = %w[--main README.md --charset=UTF-8]
 
   s.rubyforge_project = "libusb"

data/test/test_libusb_bos.rb

@@ -0,0 +1,118 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby 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 Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require "minitest/autorun"
+require "libusb"
+
+class TestLibusbBos < Minitest::Test
+  include LIBUSB
+
+  attr_accessor :usb
+
+  def setup
+    @usb = Context.new
+    @usb.debug = 0
+  end
+
+  def test_bos
+    did_bos = false
+    did_cap = false
+    usb.devices.each do |dev|
+      # devices with USB version >= 0x201 could support bos
+      # devices with USB version >= 0x210 must support bos
+      if dev.bcdUSB >= 0x210
+        dev.open do |devh|
+          bos = devh.bos
+          did_bos = true
+
+          assert_equal 5, bos.bLength
+          assert_equal 0x0f, bos.bDescriptorType
+          assert_operator 5, :<=, bos.wTotalLength
+          assert_operator 0, :<=, bos.bNumDeviceCaps
+
+          caps = bos.device_capabilities
+          assert_equal bos.bNumDeviceCaps, caps.length
+          cap_types = bos.device_capability_types
+          assert_equal bos.bNumDeviceCaps, cap_types.length
+
+          cap_types.each do |cap_type|
+            assert_operator [
+                :BT_WIRELESS_USB_DEVICE_CAPABILITY,
+                :BT_USB_2_0_EXTENSION,
+                :BT_SS_USB_DEVICE_CAPABILITY,
+                :BT_CONTAINER_ID,
+              ], :include?, cap_type
+          end
+
+
+          caps.each do |cap|
+            did_cap = true
+
+            assert_operator 4, :<=, cap.bLength
+            assert_equal LIBUSB::DT_DEVICE_CAPABILITY, cap.bDescriptorType
+            assert_kind_of String, cap.dev_capability_data, "should provide binary capability data"
+            assert_kind_of String, cap.inspect, "should respond to inspect"
+            assert_operator 1, :<=, cap.dev_capability_data.length, "dev_capability_data should be at least one byte"
+
+            case cap
+              when Bos::DeviceCapability
+                assert_kind_of Integer, cap.bDevCapabilityType
+
+              when Bos::Usb20Extension
+                assert_equal 2, cap.bDevCapabilityType
+                assert_operator 0, :<=, cap.bmAttributes
+                assert_operator [true, false], :include?, cap.bm_lpm_support?
+
+              when Bos::SsUsbDeviceCapability
+                assert_equal 3, cap.bDevCapabilityType
+                assert_operator 0, :<=, cap.bmAttributes
+                assert_operator [true, false], :include?, cap.bm_ltm_support?
+                assert_operator 0, :<=, cap.wSpeedSupported
+                assert_kind_of Array, cap.supported_speeds
+                assert_operator 0, :<=, cap.bFunctionalitySupport
+                assert_operator 0, :<=, cap.bU1DevExitLat
+                assert_operator 0, :<=, cap.bU2DevExitLat
+
+              when Bos::ContainerId
+                assert_equal 4, cap.bDevCapabilityType
+                assert_operator 0, :<=, cap.bReserved
+                assert_operator 16, :==, cap.container_id.bytesize, "container_id should be 16 bytes long"
+
+              else
+                refute true, "invalid device capability class"
+            end
+          end
+        end
+      end
+    end
+    skip "no device with BOS available" unless did_bos
+    skip "no device with BOS capability available" unless did_cap
+  end
+
+  def test_no_bos
+    did_failing_bos = false
+
+    # devices with USB version < 0x201 shouldn't support bos
+    if dev=usb.devices.find{|dev| dev.bcdUSB < 0x201 }
+      dev.open do |devh|
+        assert_raises LIBUSB::ERROR_PIPE do
+          devh.bos
+        end
+        did_failing_bos = true
+      end
+    end
+    skip "no device without BOS available" unless did_failing_bos
+  end
+end

data/test/test_libusb_bulk_stream_transfer.rb

@@ -0,0 +1,50 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby 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 Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require "minitest/autorun"
+require "libusb"
+
+class TestLibusbBulkStreamTransfer < Minitest::Test
+  include LIBUSB
+
+  def setup
+    c = Context.new
+    begin
+      @dev = c.devices.first.open
+    rescue LIBUSB::ERROR_ACCESS
+      @dev = nil
+      skip "error opening device"
+    end
+  end
+
+  def teardown
+    @dev.close if @dev
+  end
+
+  def test_alloc_streams
+    assert_raises(ERROR_NOT_SUPPORTED, "TODO: test with a OS that supports bulk streams and against a real device") do
+      nr_allocated = @dev.alloc_streams( 2, @dev.device.endpoints )
+    end
+
+    assert_raises(ERROR_NOT_SUPPORTED) do
+      @dev.free_streams( [0x01,0x82] )
+    end
+  end
+
+  def test_bulk_stream_transfer
+    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

@@ -113,6 +113,35 @@ class TestLibusbDescriptors < Minitest::Test
     end
   end
 
+  def test_ss_companion
+    did_cc_companion = false
+    did_failing_cc_companion = false
+
+    usb.devices.each do |dev|
+      dev.endpoints.each do |ep|
+        if dev.device_speed == :SPEED_SUPER
+          ss = ep.ss_companion
+          assert_match(/SsCompanion/, ss.inspect, "SsCompanion#inspect should work")
+
+          assert_kind_of Integer, ss.bLength
+          assert_equal LIBUSB::DT_SS_ENDPOINT_COMPANION, ss.bDescriptorType
+          assert_kind_of Integer, ss.bMaxBurst
+          assert_kind_of Integer, ss.bmAttributes
+          assert_kind_of Integer, ss.wBytesPerInterval
+          did_cc_companion = true
+        elsif !did_failing_cc_companion
+          assert_raises ERROR_NOT_FOUND do
+            ep.ss_companion
+          end
+          did_failing_cc_companion = true
+        end
+      end
+    end
+
+    skip "no device with cc_companion available" unless did_cc_companion
+    skip "no device without cc_companion available" unless did_failing_cc_companion
+  end
+
   def test_constants
     assert_equal 7, CLASS_PRINTER, "Printer class id should be defined"
     assert_equal 48, ISO_USAGE_TYPE_MASK, "iso usage type should be defined"