libusb 0.7.0-x64-mingw-ucrt

data/README.md

@@ -0,0 +1,184 @@
+<!-- -*- coding: utf-8 -*- -->
+
+[![Build Status](https://travis-ci.com/larskanis/libusb.svg?branch=master)](https://travis-ci.com/larskanis/libusb)
+[![Build status](https://ci.appveyor.com/api/projects/status/mdfnfdwu4mil42o3/branch/master?svg=true)](https://ci.appveyor.com/project/larskanis/libusb/branch/master)
+
+Access USB devices from Ruby
+============================
+
+LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices.
+
+* [libusb](http://libusb.info) is a library that gives full access to devices connected via the USB bus. No special kernel driver is thus necessary for accessing USB devices.
+* This Ruby binding supports the API version 1.0 of [libusb](http://libusb.info). Note that the old "legacy" version 0.1.x of libusb uses a completely different API that is covered by the ruby extension [ruby-usb](http://www.a-k-r.org/ruby-usb/) .
+
+
+LIBUSB for Ruby is covered by the GNU Lesser General Public License version 3.
+
+Features
+--------
+
+* Access to descriptors of devices, configurations, interfaces, settings and endpoints
+* Synchronous and asynchronous communication for bulk, control, interrupt and isochronous transfers
+* Support for USB-3.0 descriptors and bulk streams
+* Compatibility layer for [ruby-usb](http://www.a-k-r.org/ruby-usb/) (API based on libusb-0.1). See {::USB} for description.
+
+Synopsis
+--------
+```ruby
+require "libusb"
+
+usb = LIBUSB::Context.new
+device = usb.devices(idVendor: 0x04b4, idProduct: 0x8613).first
+device.open_interface(0) do |handle|
+  handle.control_transfer(bmRequestType: 0x40, bRequest: 0xa0, wValue: 0xe600, wIndex: 0x0000, dataOut: 1.chr)
+end
+```
+{LIBUSB::Context#devices} is used to get all or only particular devices.
+After {LIBUSB::Device#open_interface opening and claiming} the {LIBUSB::Device} the resulting {LIBUSB::DevHandle} can be
+used to communicate with the connected USB device
+by {LIBUSB::DevHandle#control_transfer}, {LIBUSB::DevHandle#bulk_transfer},
+{LIBUSB::DevHandle#interrupt_transfer} or by using the {LIBUSB::Transfer} classes.
+
+A {LIBUSB::Device} can also be used to retrieve information about it,
+by using the device descriptor attributes.
+A {LIBUSB::Device} could have several configurations. You can then decide of which
+configuration to enable. You can only enable one configuration at a time.
+
+Each {LIBUSB::Configuration} has one or more interfaces. These can be seen as functional group
+performing a single feature of the device.
+
+Each {LIBUSB::Interface} has at least one {LIBUSB::Setting}. The first setting is always default.
+An alternate setting can be used independent on each interface.
+
+Each {LIBUSB::Setting} specifies it's own set of communication endpoints.
+Each {LIBUSB::Endpoint} specifies the type of transfer, direction, polling interval and
+maximum packet size.
+
+See [the documentation](http://rubydoc.info/gems/libusb/frames) for a full API description.
+
+Prerequisites
+-------------
+
+* Linux, MacOS or Windows system with Ruby MRI 2.x/3.x, JRuby or recent version of Rubinius
+* Optionally: [libusb](http://libusb.info) C-library version 1.0.8 or any newer version.
+  The system libusb library can be installed like so:
+  * Debian or Ubuntu:
+
+      ```
+      $ sudo apt-get install libusb-1.0-0
+      ```
+  * MacOS: install with homebrew:
+
+      ```
+      $ brew install libusb
+      ```
+    or macports:
+
+      ```
+      $ port install libusb
+      ```
+  * Windows: libusb.gem already comes with a precompiled `libusb.dll`, but you need to install a device driver (see [below](#usage-on-windows))
+
+Install
+-------
+
+    $ gem install libusb
+
+While ```gem install``` the system is checked for a usable libusb library installation.
+If none could be found, a bundled libusb version is built and used, instead.
+
+Latest code can be used in this way:
+
+    $ git clone git://github.com/larskanis/libusb.git
+    $ bundle
+    $ rake install_gem
+
+Troubleshooting
+------------------------
+In order to implement a driver for a USB device, it's essential to have a look at the packets that are send to and received back from the USB device. [Wireshark](https://www.wireshark.org) has builtin capabilities to sniff USB traffic. On Linux you possibly need to load the usbmon kernel module before start:
+```
+    sudo modprobe usbmon
+```
+On Windows it's possible to sniff USB, if the USB kernel driver was installed by the Wireshark setup.
+
+![Wireshark](wireshark-usb-sniffer.png?raw=true "Wireshark sniffing USB packets")
+
+Device hotplug support
+----------------------
+
+Support for device hotplugging can be used, if ```LIBUSB.has_capability?(:CAP_HAS_HOTPLUG)``` returns ```true```.
+This requires libusb-1.0.16 or newer on Linux or MacOS. Windows support is [still on the way](https://github.com/libusbx/libusbx/issues/9).
+
+A hotplug event handler can be registered with {LIBUSB::Context#on_hotplug_event}.
+You then need to call {LIBUSB::Context#handle_events} in order to receive any events.
+This can be done as blocking calls (possibly in it's own thread) or by using {LIBUSB::Context#pollfds} to
+detect any events to handle.
+
+
+Usage on Windows
+----------------
+
+In contrast to Linux, any access to an USB device by LIBUSB on Windows requires a proper driver
+installed in the system. Fortunately creating such a driver is quite easy with
+[Zadig](http://zadig.akeo.ie/). Select the interesting USB device,
+choose WinUSB driver and press "Install Driver". That's it. You may take the generated output directory
+with it's INI-file and use it for driver installations on other 32 or 64 bit Windows
+systems.
+
+
+Binary gems for Windows and Linux
+---------------------------
+
+The Libusb gem is provided as source gem and as binary gems for Windows and Linux operating systems on [rubygems.org](https://rubygems.org/gems/libusb).
+The binary version is usually preferred, but the source version of the gem can be enforced by:
+
+    $ gem install libusb --platform ruby
+
+Libusb gem can be cross built for Windows and Linux, using the [rake-compiler-dock](https://github.com/larskanis/rake-compiler-dock) .
+Just run:
+
+    $ rake gem:native
+
+If everything works, there are several platform specific gem files (like `libusb-VERSION-x64-mingw32.gem`) in the pkg
+directory.
+
+EventMachine integration
+------------------------
+
+Libusb for Ruby comes with an experimental integration to [EventMachine](http://rubyeventmachine.com/).
+That API is currently proof of concept - see {LIBUSB::Context#eventmachine_register}.
+If you're experienced with EventMachine, please leave a comment.
+
+
+Testing LIBUSB gem
+------------------
+
+Libusb for Ruby has a bundled test suite which verifies proper working of many functions of the library.
+Only a small subset of these tests are executed on Github Actions due to the missing USB functions in the CI environments.
+They just verify that the libusb library can be installed and called and that very basic functions are working.
+
+To run the tests against real devices the following procedure should be done:
+
+```sh
+$ # Connect a USB mass strorage device. It is used read-only.
+$ sudo chown $USER /dev/bus/usb/*/*
+$ rake test
+```
+
+While the tests are running a second arbitrary USB device is requested to be connected and shortly after disconnected again.
+There are only 5 seconds timeout for connecting and disconnecting, so that the device should have be ready.
+Some USB mass storage devices are not compatible to the tests, so that it's best to try out different models to find some that doesn't fail.
+
+
+Resources
+---------
+
+* Project's home page: http://github.com/larskanis/libusb
+* API documentation: http://rubydoc.info/gems/libusb/frames
+* Mailinglist: http://rubyforge.org/mailman/listinfo/libusb-hackers
+* Overall introduction to USB: http://www.usbmadesimple.co.uk
+
+Todo
+----
+
+* stabilize EventMachine interface

data/Rakefile

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# -*- ruby -*-
+
+require 'bundler/gem_helper'
+require 'rubygems/package_task'
+require 'pathname'
+require 'uri'
+require 'ostruct'
+require 'rake/clean'
+require_relative 'lib/libusb/libusb_recipe'
+require_relative 'lib/libusb/gem_helper'
+
+CLOBBER.include 'pkg'
+CLEAN.include 'ports'
+CLEAN.include 'tmp'
+CLEAN.include 'ext/tmp'
+CLEAN.include 'lib/*.a'
+CLEAN.include 'lib/*.so*'
+CLEAN.include 'lib/*.dll*'
+
+task :build do
+  require_relative 'lib/libusb/libusb_recipe'
+  recipe = LIBUSB::LibusbRecipe.new
+  recipe.download
+end
+
+task :gem => :build
+task :compile do
+  sh "ruby -C ext extconf.rb --disable-system-libusb"
+  sh "make -C ext install RUBYARCHDIR=../lib"
+end
+
+task :gemfile_libusb_gem do
+  gf = File.read("Gemfile")
+  gf.gsub!(/^(gemspec)$/, "# \\1")
+  gf << "\ngem 'libusb'\n"
+  File.write("Gemfile_libusb_gem", gf)
+  puts "Gemfile_libusb_gem written"
+end
+
+task :test do
+  sh "ruby -w -W2 -I.:lib -e \"#{Dir["test/test_*.rb"].map{|f| "require '#{f}';"}.join}\" -- -v"
+end
+task :default => :test
+
+ci_tests = %w[test_libusb.rb test_libusb_structs.rb]
+task :ci do
+  sh "ruby -w -W2 -I. -e \"#{ci_tests.map{|f| "require 'test/#{f}';"}.join}\" -- -v"
+end
+
+CrossLibraries = [
+  ['x86-mingw32', 'i686-w64-mingw32', 'bin/libusb-1.0.dll'],
+  ['x64-mingw32', 'x86_64-w64-mingw32', 'bin/libusb-1.0.dll'],
+  ['x64-mingw-ucrt', 'x86_64-w64-mingw32', 'bin/libusb-1.0.dll'],
+  ['x86-linux', 'i686-linux-gnu', 'lib/libusb-1.0.so'],
+  ['x86_64-linux', 'x86_64-linux-gnu', 'lib/libusb-1.0.so'],
+].map do |ruby_platform, host_platform, libusb_dll|
+  LIBUSB::CrossLibrary.new ruby_platform, host_platform, libusb_dll
+end
+
+LIBUSB::GemHelper.install_tasks
+Bundler::GemHelper.instance.cross_platforms = CrossLibraries.map(&:ruby_platform)
+
+CrossLibraries.map(&:ruby_platform).each do |platform|
+  desc "Build windows and linux fat binary gems"
+  multitask 'gem:native' => "gem:native:#{platform}"
+
+  task "gem:native:#{platform}" do
+    require 'rake_compiler_dock'
+    sh "bundle package"
+    RakeCompilerDock.sh <<-EOT, platform: platform
+      bundle --local &&
+      #{ "sudo yum install -y libudev-devel &&" if platform=~/linux/ }
+      bundle exec rake --trace cross:#{platform} gem "MAKE=make V=1 -j`nproc`" || cat tmp/*/ports/libusb/*/*.log
+    EOT
+  end
+end
+
+# vim: syntax=ruby

data/lib/libusb/bos.rb

@@ -0,0 +1,362 @@
+# 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::Struct
+
+    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.unpack1("H*")}>"
+      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::Struct
+      include GenericMethods
+      include ContextReference
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bmAttributes, :uint32
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_usb_2_0_extension_descriptor)
+      end
+
+      # 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
+    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::Struct
+      include GenericMethods
+      include ContextReference
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bmAttributes, :uint8,
+          :wSpeedSupported, :uint16,
+          :bFunctionalitySupport, :uint8,
+          :bU1DevExitLat, :uint8,
+          :bU2DevExitLat, :uint16
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_ss_usb_device_capability_descriptor)
+      end
+
+      # 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
+    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::Struct
+      include GenericMethods
+      include ContextReference
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          :bDevCapabilityType, :uint8,
+          :bReserved, :uint8,
+          :ContainerID, [:uint8, 16]
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_container_id_descriptor)
+      end
+
+      # 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.unpack1("H*")}>"
+      end
+    end
+
+
+    # A structure representing a Platform descriptor.
+    # This descriptor is documented in section 9.6.2.4 of the USB 3.2 specification.
+    class PlatformDescriptor < FFI::Struct
+      include GenericMethods
+      include ContextReference
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          # Capability type. Will have value
+          # libusb_capability_type::LIBUSB_BT_PLATFORM_DESCRIPTOR
+          # LIBUSB_BT_CONTAINER_ID in this context.
+          :bDevCapabilityType, :uint8,
+          # Reserved field
+          :bReserved, :uint8,
+          # 128 bit UUID
+          :PlatformCapabilityUUID, [:uint8, 16],
+          # Capability data (bLength - 20)
+          :CapabilityData, [:uint8, 0]
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_platform_descriptor)
+      end
+
+      # Reserved field
+      def bReserved
+        self[:bReserved]
+      end
+
+      # @return [String] 128 bit UUID
+      def platformCapabilityUUID
+        self[:PlatformCapabilityUUID].to_ptr.read_bytes(16)
+      end
+
+      # This is a variable-length field containing data associated with the platform specific capability.
+      # This field may be zero bytes in length.
+      # @return [String]
+      def capabilityData
+        self[:CapabilityData].to_ptr.read_bytes(bLength - 20)
+      end
+
+      def inspect
+        "\#<#{self.class} #{platformCapabilityUUID.unpack1("H*")} (#{capabilityData.unpack1("H*")})>"
+      end
+    end
+
+    include ContextReference
+
+    def initialize(ctx, *args)
+      @ctx = ctx
+      super(*args)
+
+      register_context(ctx, :libusb_free_bos_descriptor)
+    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(@ctx, 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(@ctx, 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(@ctx, pp_ext.read_pointer) if res==0
+          when LIBUSB::BT_PLATFORM_DESCRIPTOR
+            res = Call.libusb_get_platform_descriptor(@ctx, cap.pointer, pp_ext)
+            cap = PlatformDescriptor.new(@ctx, 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
+  end
+end