libusb 0.4.1 → 0.5.0

data/lib/libusb.rb

@@ -25,7 +25,9 @@ module LIBUSB
   autoload :Endpoint, 'libusb/endpoint'
   autoload :Interface, 'libusb/interface'
   autoload :Setting, 'libusb/setting'
-  %w[ Transfer BulkTransfer ControlTransfer InterruptTransfer IsoPacket IsochronousTransfer ].each do |klass|
+  autoload :SsCompanion, 'libusb/ss_companion'
+  autoload :Bos, 'libusb/bos'
+  %w[ Transfer BulkTransfer BulkStreamTransfer ControlTransfer InterruptTransfer IsoPacket IsochronousTransfer ].each do |klass|
     autoload klass, 'libusb/transfer'
   end
 

data/lib/libusb/bos.rb

@@ -0,0 +1,306 @@
+# 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 Binary Device Object Store (BOS) descriptor.
+  # This descriptor is documented in section 9.6.2 of the USB 3.0 specification.
+  # All multiple-byte fields are represented in host-endian format.
+  class Bos < FFI::ManagedStruct
+
+    module GenericMethods
+      # @return [Integer]  Size of this descriptor (in bytes)
+      def bLength
+        self[:bLength]
+      end
+
+      # @return [Integer]  Descriptor type. Will have value LIBUSB::DT_DEVICE_CAPABILITY
+      # in this context.
+      def bDescriptorType
+        self[:bDescriptorType]
+      end
+
+      # @return [Integer] Device Capability type
+      def bDevCapabilityType
+        self[:bDevCapabilityType]
+      end
+
+      def inspect
+        "\#<#{self.class} cap: #{bDevCapabilityType} data: #{dev_capability_data.unpack("H*")[0]}>"
+      end
+
+      # @return [String]  Device Capability data (bLength - 3 bytes)
+      def dev_capability_data
+        pointer.read_bytes(bLength - 3)
+      end
+    end
+
+    # A generic representation of a BOS Device Capability descriptor.
+    class DeviceCapability < FFI::Struct
+      include GenericMethods
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8
+
+      def initialize( bos, *args)
+        # Avoid that the bos struct is GC'ed before this instance
+        @bos = bos
+        super(*args)
+      end
+    end
+
+    # A structure representing the USB 2.0 Extension descriptor
+    # This descriptor is documented in section 9.6.2.1 of the USB 3.0 specification.
+    # All multiple-byte fields are represented in host-endian format.
+    class Usb20Extension < FFI::ManagedStruct
+      include GenericMethods
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bmAttributes, :uint32
+
+      # Bitmap encoding of supported device level features.
+      # A value of one in a bit location indicates a feature is
+      # supported; a value of zero indicates it is not supported.
+      # @see Call::Usb20ExtensionAttributes
+      def bmAttributes
+        self[:bmAttributes]
+      end
+
+      # @return [Boolean] Supports Link Power Management (LPM)
+      def bm_lpm_support?
+        (bmAttributes & BM_LPM_SUPPORT) != 0
+      end
+
+      def inspect
+        attrs = Call::Usb20ExtensionAttributes.to_h.map do |k, v|
+          (bmAttributes & v) ? k.to_s : nil
+        end
+        "\#<#{self.class} #{attrs.compact.join(",")}>"
+      end
+
+      # @private
+      def self.release(ptr)
+        Call.libusb_free_usb_2_0_extension_descriptor(ptr)
+      end
+    end
+
+    # A structure representing the SuperSpeed USB Device Capability descriptor
+    # This descriptor is documented in section 9.6.2.2 of the USB 3.0 specification.
+    # All multiple-byte fields are represented in host-endian format.
+    class SsUsbDeviceCapability < FFI::ManagedStruct
+      include GenericMethods
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bmAttributes, :uint32,
+          :wSpeedSupported, :uint16,
+          :bFunctionalitySupport, :uint8,
+          :bU1DevExitLat, :uint8,
+          :bU2DevExitLat, :uint16
+
+      # Bitmap encoding of supported device level features.
+      # A value of one in a bit location indicates a feature is
+      # supported; a value of zero indicates it is not supported.
+      #
+      # @return [Integer]
+      # @see Call::SsUsbDeviceCapabilityAttributes
+      def bmAttributes
+        self[:bmAttributes]
+      end
+
+      # @return [Boolean] Supports Latency Tolerance Messages (LTM)
+      def bm_ltm_support?
+        (bmAttributes & BM_LTM_SUPPORT) != 0
+      end
+
+      def inspect
+        attrs = Call::SsUsbDeviceCapabilityAttributes.to_h.map do |k,v|
+          (bmAttributes & v) != 0 ? k.to_s : nil
+        end
+        "\#<#{self.class} #{attrs.compact.join(",")} #{supported_speeds.join(",")}>"
+      end
+
+      # Bitmap encoding of the speed supported by this device when
+      # operating in SuperSpeed mode.
+      #
+      # @return [Integer]
+      # @see Call::SupportedSpeeds
+      def wSpeedSupported
+        self[:wSpeedSupported]
+      end
+
+      # @return [Array<Symbol>]  speeds supported by this device when
+      #     operating in SuperSpeed mode {Call::SupportedSpeeds}
+      def supported_speeds
+        speeds = Call::SupportedSpeeds.to_h.map do |k,v|
+          (wSpeedSupported & v) != 0 ? k : nil
+        end
+        speeds.compact
+      end
+
+      # The lowest speed at which all the functionality supported
+      # by the device is available to the user. For example if the
+      # device supports all its functionality when connected at
+      # full speed and above then it sets this value to 1.
+      #
+      # 0 - low speed
+      # 1 - full speed
+      # 2 - high speed
+      # 3 - super speed
+      # @return [Integer]
+      def bFunctionalitySupport
+        self[:bFunctionalitySupport]
+      end
+
+      # @return [Integer]  U1 Device Exit Latency.
+      def bU1DevExitLat
+        self[:bU1DevExitLat]
+      end
+
+      # @return [Integer]  U2 Device Exit Latency.
+      def bU2DevExitLat
+        self[:bU2DevExitLat]
+      end
+
+      # @private
+      def self.release(ptr)
+        Call.libusb_free_ss_usb_device_capability_descriptor(ptr)
+      end
+    end
+
+    # A structure representing the Container ID descriptor.
+    # This descriptor is documented in section 9.6.2.3 of the USB 3.0 specification.
+    # All multiple-byte fields, except UUIDs, are represented in host-endian format.
+    class ContainerId < FFI::ManagedStruct
+      include GenericMethods
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bReserved, :uint8,
+          :ContainerID, [:uint8, 16]
+
+      # Reserved field
+      def bReserved
+        self[:bReserved]
+      end
+
+      # @return [String] 128 bit UUID
+      def container_id
+        self[:ContainerID].to_ptr.read_bytes(16)
+      end
+
+      def inspect
+        "\#<#{self.class} #{container_id.unpack("H*")[0]}>"
+      end
+
+      # @private
+      def self.release(ptr)
+        Call.libusb_free_container_id_descriptor(ptr)
+      end
+    end
+
+    def initialize( ctx, *args)
+      @ctx = ctx
+      super(*args)
+    end
+
+    layout :bLength, :uint8,
+        :bDescriptorType, :uint8,
+        :wTotalLength, :uint16,
+        :bNumDeviceCaps, :uint8,
+        :dev_capability, [:pointer, 0]
+
+    # @return [Integer]  Size of this descriptor (in bytes)
+    def bLength
+      self[:bLength]
+    end
+
+    # @return [Integer]  Descriptor type. Will have value LIBUSB::DT_BOS LIBUSB_DT_BOS
+    # in this context.
+    def bDescriptorType
+      self[:bDescriptorType]
+    end
+
+    # @return [Integer]  Length of this descriptor and all of its sub descriptors
+    def wTotalLength
+      self[:wTotalLength]
+    end
+
+    # @return [Integer]  The number of separate device capability descriptors in
+    # the BOS
+    def bNumDeviceCaps
+      self[:bNumDeviceCaps]
+    end
+
+    # bNumDeviceCap Device Capability Descriptors
+    #
+    # @return [Array<Bos::DeviceCapability, Bos::Usb20Extension, Bos::SsUsbDeviceCapability, Bos::ContainerId>]
+    def device_capabilities
+      pp_ext = FFI::MemoryPointer.new :pointer
+      caps = []
+      # Capabilities are appended to the bos header
+      ptr = pointer + offset_of(:dev_capability)
+      bNumDeviceCaps.times do
+        cap = DeviceCapability.new self, ptr.read_pointer
+        case cap.bDevCapabilityType
+          when LIBUSB::BT_WIRELESS_USB_DEVICE_CAPABILITY
+            # no struct defined in libusb -> use generic DeviceCapability
+          when LIBUSB::BT_USB_2_0_EXTENSION
+            res = Call.libusb_get_usb_2_0_extension_descriptor(@ctx, cap.pointer, pp_ext)
+            cap = Usb20Extension.new(pp_ext.read_pointer) if res==0
+          when LIBUSB::BT_SS_USB_DEVICE_CAPABILITY
+            res = Call.libusb_get_ss_usb_device_capability_descriptor(@ctx, cap.pointer, pp_ext)
+            cap = SsUsbDeviceCapability.new(pp_ext.read_pointer) if res==0
+          when LIBUSB::BT_CONTAINER_ID
+            res = Call.libusb_get_container_id_descriptor(@ctx, cap.pointer, pp_ext)
+            cap = ContainerId.new(pp_ext.read_pointer) if res==0
+          else
+            # unknown capability -> use generic DeviceCapability
+        end
+        ptr += FFI.type_size(:pointer)
+        caps << cap
+      end
+      caps
+    end
+
+    # @return [Array<Symbol>]  Types of Capabilities
+    #
+    # @see Call::BosTypes
+    def device_capability_types
+      # Capabilities are appended to the bos header
+      ptr = pointer + offset_of(:dev_capability)
+      bNumDeviceCaps.times.map do
+        cap = DeviceCapability.new self, ptr.read_pointer
+        ptr += FFI.type_size(:pointer)
+        Call::BosTypes.find cap.bDevCapabilityType
+      end
+    end
+
+    def inspect
+      "\#<#{self.class} #{device_capability_types.join(", ")}>"
+    end
+
+    # @private
+    def self.release(ptr)
+      Call.libusb_free_bos_descriptor(ptr)
+    end
+  end
+end

data/lib/libusb/call.rb

@@ -81,11 +81,18 @@ module LIBUSB
       :TRANSFER_ADD_ZERO_PACKET, 1 << 3,
     ]
 
+    # Values for {Endpoint#transfer_type}.
     TransferTypes = enum :libusb_transfer_type, [
+      # Control endpoint
       :TRANSFER_TYPE_CONTROL, 0,
+      # Isochronous endpoint
       :TRANSFER_TYPE_ISOCHRONOUS, 1,
+      # Bulk endpoint
       :TRANSFER_TYPE_BULK, 2,
+      # Interrupt endpoint
       :TRANSFER_TYPE_INTERRUPT, 3,
+      # Stream endpoint
+      :TRANSFER_TYPE_BULK_STREAM, 4,
     ]
 
     StandardRequests = enum :libusb_standard_request, [
@@ -108,15 +115,32 @@ module LIBUSB
     ]
 
     DescriptorTypes = enum :libusb_descriptor_type, [
+      # Device descriptor. See {Device}
       :DT_DEVICE, 0x01,
+      # Configuration descriptor. See {Configuration}
       :DT_CONFIG, 0x02,
+      # String descriptor
       :DT_STRING, 0x03,
+      # Interface descriptor. See {Interface}
       :DT_INTERFACE, 0x04,
+      # Endpoint descriptor. See {Endpoint}
       :DT_ENDPOINT, 0x05,
+      # BOS descriptor
+      :DT_BOS, 0x0f,
+      # Device Capability descriptor
+      :DT_DEVICE_CAPABILITY, 0x10,
+      # HID descriptor
       :DT_HID, 0x21,
+      # HID report descriptor
       :DT_REPORT, 0x22,
+      # Physical descriptor
       :DT_PHYSICAL, 0x23,
+      # Hub descriptor
       :DT_HUB, 0x29,
+      # SuperSpeed Hub descriptor
+      :DT_SUPERSPEED_HUB, 0x2a,
+      # SuperSpeed Endpoint Companion descriptor
+      :DT_SS_ENDPOINT_COMPANION, 0x30,
     ]
 
     RequestTypes = enum :libusb_request_type, [
@@ -148,6 +172,19 @@ module LIBUSB
       :SPEED_SUPER, 4,
     ]
 
+    # Supported speeds (wSpeedSupported) bitfield. Indicates what
+    # speeds the device supports.
+    SupportedSpeeds = enum :libusb_supported_speed, [
+      # Low speed operation supported (1.5MBit/s).
+      :LOW_SPEED_OPERATION, 1,
+      # Full speed operation supported (12MBit/s).
+      :FULL_SPEED_OPERATION, 2,
+      # High speed operation supported (480MBit/s).
+      :HIGH_SPEED_OPERATION, 4,
+      # Superspeed operation supported (5000MBit/s).
+      :SUPER_SPEED_OPERATION, 8,
+    ]
+
     Capabilities = enum :libusb_capability, [
       :CAP_HAS_CAPABILITY, 0x0000,
       # Hotplug support is available on this platform.
@@ -162,6 +199,36 @@ module LIBUSB
       :CAP_SUPPORTS_DETACH_KERNEL_DRIVER, 0x0101,
     ]
 
+    # Masks for the bits of the
+    # {Bos::Usb20Extension#bmAttributes} field
+    # of the USB 2.0 Extension descriptor.
+    Usb20ExtensionAttributes = enum :libusb_usb_2_0_extension_attributes, [
+      # Supports Link Power Management (LPM)
+      :BM_LPM_SUPPORT, 2,
+    ]
+
+    # Masks for the bits of the
+    # {Bos::SsUsbDeviceCapability#bmAttributes} field
+    # field of the SuperSpeed USB Device Capability descriptor.
+    SsUsbDeviceCapabilityAttributes = enum :libusb_ss_usb_device_capability_attributes, [
+      # Supports Latency Tolerance Messages (LTM)
+      :BM_LTM_SUPPORT, 2,
+    ]
+
+    # USB capability types
+    #
+    # @see Bos::DeviceCapability
+    BosTypes = enum :libusb_bos_type, [
+      # Wireless USB device capability
+      :BT_WIRELESS_USB_DEVICE_CAPABILITY, 1,
+      # USB 2.0 extensions
+      :BT_USB_2_0_EXTENSION, 2,
+      # SuperSpeed USB device capability
+      :BT_SS_USB_DEVICE_CAPABILITY, 3,
+      # Container ID type
+      :BT_CONTAINER_ID, 4,
+    ]
+
     # Since libusb version 1.0.16.
     #
     # Hotplug events
@@ -186,6 +253,7 @@ module LIBUSB
     typedef :pointer, :libusb_context
     typedef :pointer, :libusb_device
     typedef :pointer, :libusb_device_handle
+    typedef :pointer, :libusb_transfer
     typedef :int, :libusb_hotplug_callback_handle
 
     def self.try_attach_function(method, *args)
@@ -221,6 +289,18 @@ module LIBUSB
     attach_function 'libusb_get_max_packet_size', [:pointer, :uint8], :int
     attach_function 'libusb_get_max_iso_packet_size', [:pointer, :uint8], :int
 
+    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_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
+    try_attach_function 'libusb_get_ss_usb_device_capability_descriptor', [:libusb_context, :pointer, :pointer], :int
+    try_attach_function 'libusb_free_ss_usb_device_capability_descriptor', [:pointer], :void
+    try_attach_function 'libusb_get_container_id_descriptor', [:libusb_context, :pointer, :pointer], :int
+    try_attach_function 'libusb_free_container_id_descriptor', [:pointer], :void
+
     attach_function 'libusb_open', [:pointer, :pointer], :int
     attach_function 'libusb_close', [:pointer], :void
     attach_function 'libusb_get_device', [:libusb_device_handle], :pointer
@@ -234,6 +314,8 @@ module LIBUSB
     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
 
     attach_function 'libusb_kernel_driver_active', [:libusb_device_handle, :int], :int
     attach_function 'libusb_detach_kernel_driver', [:libusb_device_handle, :int], :int
@@ -246,6 +328,8 @@ module LIBUSB
     attach_function 'libusb_submit_transfer', [:pointer], :int
     attach_function 'libusb_cancel_transfer', [:pointer], :int
     attach_function 'libusb_free_transfer', [:pointer], :void
+    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