在 Mac 上读取和写入 USB (HID) 中断端点

Question

我正在尝试与相当特定的 USB 设备进行通信，并为此开发 Windows 和 Mac 代码。

该设备是具有 HID 接口（3 类）的 USB 设备，具有两个端点，一个中断输入和一个中断输出。设备的本质是，只有当主机请求数据时，才会在输入端点上从设备发送数据：主机向其发送数据，设备在其输入中断端点上响应该数据。向设备获取数据（写入）要简单得多...

Windows 的代码相当简单：我得到设备的句柄，然后调用 ReadFile 或 WriteFile。显然，许多底层异步行为都被抽象出来了。它似乎工作正常。

但是，在 Mac 上，它有点粘。我尝试了很多事情，没有一个是完全成功的，但这里有两件看起来最有希望的事情......

1.) 尝试通过 IOUSBInterfaceInterface 访问设备（作为 USB），遍历端点以确定输入和输出端点，并（希望）使用 ReadPipe 和 WritePipe 进行通信。不幸的是，一旦我拥有它，我就无法打开界面，返回值 (kIOReturnExclusiveAccess) 指出某些东西已经让设备以独占方式打开。我曾尝试使用 IOUSBinterfaceInterface183，这样我就可以调用 USBInterfaceOpenSeize，但这会导致相同的返回错误值。

--- 2010 年 7 月 30 日更新 ---
显然，Apple IOUSBHIDDriver 早期与设备匹配，这可能是阻止打开 IOUSBInterfaceInterface 的原因。从一些挖掘看来，防止 IOUSBHIDDriver 匹配的常用方法是编写具有更高探测分数的无代码 kext（内核扩展）。这将尽早匹配，阻止 IOUSBHIDDriver 打开设备，并且理论上应该允许我打开接口并直接写入和读取端点。这没关系，但我更希望不必在用户机器上安装额外的东西。如果有人知道可靠的替代方案，我将不胜感激。

2.) 将设备作为 IOHIDDeviceInterface122（或更高版本）打开。为了阅读，我设置了一个异步端口、事件源和回调方法，以便在数据准备好时调用 - 当数据从输入中断端点上的设备发送时。但是，要写入设备需要的数据来初始化响应，我找不到方法。我难住了。 setReport 通常写入控制端点，另外我需要一个不期望任何直接响应、不阻塞的写入。

我在网上环顾四周并尝试了很多东西，但没有一个能让我成功。有什么建议吗？我不能使用很多 Apple HIDManager 代码，因为其中大部分是 10.5+，而且我的应用程序也必须在 10.4 上运行。

Answer 1

我现在有一个可用于 USB 设备的 Mac 驱动程序，它需要通过中断端点进行通信。这是我的做法：

最终，对我来说效果很好的方法是选项 1（如上所述）。如前所述，我在打开设备的 COM 样式 IOUSBInterfaceInterface 时遇到问题。随着时间的推移，很明显这是由于 HIDManager 捕获了设备。一旦它被捕获，我就无法从 HIDManager 中夺取对设备的控制权（甚至 USBInterfaceOpenSeize 调用或 USBDeviceOpenSeize 调用都不起作用）。

要控制设备，我需要在 HIDManager 之前抓取它。解决这个问题的方法是编写一个无代码的 kext（内核扩展）。 kext 本质上是一个位于 System/Library/Extensions 中的包，其中包含（通常）一个 plist（属性列表）和（偶尔）一个内核级驱动程序等。在我的情况下，我只想要 plist，它将向内核提供有关它匹配的设备的指令。如果数据给出的探测分数高于 HIDManager，那么我基本上可以捕获设备并使用用户空间驱动程序与之通信。

编写的kext plist，修改了一些具体项目的细节，如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>OSBundleLibraries</key>
    <dict>
        <key>com.apple.iokit.IOUSBFamily</key>
        <string>1.8</string>
        <key>com.apple.kernel.libkern</key>
        <string>6.0</string>
    </dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>English</string>
    <key>CFBundleGetInfoString</key>
    <string>Demi USB Device</string>
    <key>CFBundleIdentifier</key>
    <string>com.demiart.mydevice</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>Demi USB Device</string>
    <key>CFBundlePackageType</key>
    <string>KEXT</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>CFBundleVersion</key>
    <string>1.0.0</string>
    <key>IOKitPersonalities</key>
    <dict>
        <key>Device Driver</key>
        <dict>
            <key>CFBundleIdentifier</key>
            <string>com.apple.kernel.iokit</string>
            <key>IOClass</key>
            <string>IOService</string>
            <key>IOProviderClass</key>
            <string>IOUSBInterface</string>
            <key>idProduct</key>
            <integer>12345</integer>
            <key>idVendor</key>
            <integer>67890</integer>
            <key>bConfigurationValue</key>
            <integer>1</integer>
            <key>bInterfaceNumber</key>
            <integer>0</integer>
        </dict>
    </dict>
    <key>OSBundleRequired</key>
    <string>Local-Root</string>
</dict>
</plist>

idVendor 和 idProduct 值赋予 kext 特异性并充分提高其探测分数。

为了使用 kext，需要做以下事情（我的安装程序将为客户做这些事情）：

1. 将所有者更改为 root:wheel (sudo chown root:wheel DemiUSBDevice.kext)
2. 将 kext 复制到 Extensions (sudo cp DemiUSBDevice.kext /System/Library/Extensions)
3. 调用 kextload 实用程序加载 kext 以便立即使用而无需重新启动 (sudo kextload -vt /System/Library/Extensions/DemiUSBDevice.kext)
4. 触摸 Extensions 文件夹，以便下次重新启动时强制重建缓存 (sudo touch /System/Library/Extensions)

此时系统应该使用 kext 来阻止 HIDManager 捕获我的设备。现在，该怎么办？如何写入和读取？

以下是我的代码的一些简化的 sn-ps，减去任何错误处理，说明了解决方案。在能够对设备执行任何操作之前，应用程序需要知道设备何时连接（和分离）。请注意，这仅仅是为了说明的目的——一些变量是类级别的，一些是全局的，等等。下面是设置附加/分离事件的初始化代码：

#include <IOKit/IOKitLib.h>
#include <IOKit/IOCFPlugIn.h>
#include <IOKit/usb/IOUSBLib.h>
#include <mach/mach.h>

#define DEMI_VENDOR_ID 12345
#define DEMI_PRODUCT_ID 67890

void DemiUSBDriver::initialize(void)
{
    IOReturn                result;
    Int32                   vendor_id = DEMI_VENDOR_ID;
    Int32                   product_id = DEMI_PRODUCT_ID;
    mach_port_t             master_port;
    CFMutableDictionaryRef  matching_dict;
    IONotificationPortRef   notify_port;
    CFRunLoopSourceRef      run_loop_source;
    
    //create a master port
    result = IOMasterPort(bootstrap_port, &master_port);
    
    //set up a matching dictionary for the device
    matching_dict = IOServiceMatching(kIOUSBDeviceClassName);
    
    //add matching parameters
    CFDictionarySetValue(matching_dict, CFSTR(kUSBVendorID),
        CFNumberCreate(kCFAllocatorDefault, kCFNumberInt32Type, &vendor_id));
    CFDictionarySetValue(matching_dict, CFSTR(kUSBProductID),
        CFNumberCreate(kCFAllocatorDefault, kCFNumberInt32Type, &product_id));
      
    //create the notification port and event source
    notify_port = IONotificationPortCreate(master_port);
    run_loop_source = IONotificationPortGetRunLoopSource(notify_port);
    CFRunLoopAddSource(CFRunLoopGetCurrent(), run_loop_source, 
      kCFRunLoopDefaultMode);
    
    //add an additional reference for a secondary event 
    //  - each consumes a reference...
    matching_dict = (CFMutableDictionaryRef)CFRetain(matching_dict);
    
    //add a notification callback for detach event
    //NOTE: removed_iter is a io_iterator_t, declared elsewhere
    result = IOServiceAddMatchingNotification(notify_port, 
      kIOTerminatedNotification, matching_dict, device_detach_callback, 
      NULL, &removed_iter);
    
    //call the callback to 'arm' the notification
    device_detach_callback(NULL, removed_iter);
    
    //add a notification callback for attach event
    //NOTE: added_iter is a io_iterator_t, declared elsewhere
    result = IOServiceAddMatchingNotification(notify_port, 
      kIOFirstMatchNotification, matching_dict, device_attach_callback, 
      NULL, &g_added_iter);
    if (result)
    {
      throw Exception("Unable to add attach notification callback.");
    }
    
    //call the callback to 'arm' the notification
    device_attach_callback(NULL, added_iter);
    
    //'pump' the run loop to handle any previously added devices
    service();
}

在此初始化代码中有两种方法用作回调：device_detach_callback 和 device_attach_callback（均在静态方法中声明）。 device_detach_callback 很简单：

//implementation
void DemiUSBDevice::device_detach_callback(void* context, io_iterator_t iterator)
{
    IOReturn       result;
    io_service_t   obj;

    while ((obj = IOIteratorNext(iterator)))
    {
        //close all open resources associated with this service/device...
        
        //release the service
        result = IOObjectRelease(obj);
    }
}

device_attach_callback 是最神奇的地方。在我的代码中，我将其分解为多种方法，但在这里我将把它呈现为一个大的整体方法...：

void DemiUSBDevice::device_attach_callback(void * context, 
    io_iterator_t iterator)
{
    IOReturn                   result;
    io_service_t           usb_service;
    IOCFPlugInInterface**      plugin;   
    HRESULT                    hres;
    SInt32                     score;
    UInt16                     vendor; 
    UInt16                     product;
    IOUSBFindInterfaceRequest  request;
    io_iterator_t              intf_iterator;
    io_service_t               usb_interface;

    UInt8                      interface_endpoint_count = 0;
    UInt8                      pipe_ref = 0xff;
    
    UInt8                      direction;
    UInt8                      number;
    UInt8                      transfer_type;
    UInt16                     max_packet_size;
    UInt8                      interval;

    CFRunLoopSourceRef         m_event_source;
    CFRunLoopSourceRef         compl_event_source;
    
    IOUSBDeviceInterface245** dev = NULL;
    IOUSBInterfaceInterface245** intf = NULL;
    
    while ((usb_service = IOIteratorNext(iterator)))
    {
      //create the intermediate plugin
      result = IOCreatePlugInInterfaceForService(usb_service, 
        kIOUSBDeviceUserClientTypeID, kIOCFPlugInInterfaceID, &plugin, 
        &score);
      
      //get the device interface
      hres = (*plugin)->QueryInterface(plugin, 
        CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID245), (void**)&dev);
      
      //release the plugin - no further need for it
      IODestroyPlugInInterface(plugin);
      
      //double check ids for correctness
      result = (*dev)->GetDeviceVendor(dev, &vendor);
      result = (*dev)->GetDeviceProduct(dev, &product);
      if ((vendor != DEMI_VENDOR_ID) || (product != DEMI_PRODUCT_ID))
      {
        continue;
      }
      
      //set up interface find request
      request.bInterfaceClass     = kIOUSBFindInterfaceDontCare;
      request.bInterfaceSubClass  = kIOUSBFindInterfaceDontCare;
      request.bInterfaceProtocol  = kIOUSBFindInterfaceDontCare;
      request.bAlternateSetting   = kIOUSBFindInterfaceDontCare;
    
      result = (*dev)->CreateInterfaceIterator(dev, &request, &intf_iterator);
    
      while ((usb_interface = IOIteratorNext(intf_iterator)))
      {
        //create intermediate plugin
        result = IOCreatePlugInInterfaceForService(usb_interface, 
          kIOUSBInterfaceUserClientTypeID, kIOCFPlugInInterfaceID, &plugin, 
          &score);
      
        //release the usb interface - not needed
        result = IOObjectRelease(usb_interface);
      
        //get the general interface interface
        hres = (*plugin)->QueryInterface(plugin, CFUUIDGetUUIDBytes(
          kIOUSBInterfaceInterfaceID245), (void**)&intf);
      
        //release the plugin interface
        IODestroyPlugInInterface(plugin);
      
        //attempt to open the interface
        result = (*intf)->USBInterfaceOpen(intf);
      
        //check that the interrupt endpoints are available on this interface
        //calling 0xff invalid...
        m_input_pipe = 0xff;  //UInt8, pipe from device to Mac
        m_output_pipe = 0xff; //UInt8, pipe from Mac to device
    
        result = (*intf)->GetNumEndpoints(intf, &interface_endpoint_count);
        if (!result)
        {
          //check endpoints for direction, type, etc.
          //note that pipe_ref == 0 is the control endpoint (we don't want it)
          for (pipe_ref = 1; pipe_ref <= interface_endpoint_count; pipe_ref++)
          {
            result = (*intf)->GetPipeProperties(intf, pipe_ref, &direction,
              &number, &transfer_type, &max_packet_size, &interval);
            if (result)
            {
              break;
            }
        
            if (transfer_type == kUSBInterrupt)
            {
              if (direction == kUSBIn)
              {
                m_input_pipe = pipe_ref;
              }
              else if (direction == kUSBOut)
              {
                m_output_pipe = pipe_ref;
              }
            }
          }
        }

        //set up async completion notifications
        result = (*m_intf)->CreateInterfaceAsyncEventSource(m_intf, 
          &compl_event_source);
        CFRunLoopAddSource(CFRunLoopGetCurrent(), compl_event_source, 
          kCFRunLoopDefaultMode);
        
        break;
      }

      break;
    }
}

此时我们应该有中断端点的数量和设备的开放 IOUSBInterfaceInterface。可以通过调用类似的方法来完成数据的异步写入：

result = (intf)->WritePipeAsync(intf, m_output_pipe, 
          data, OUTPUT_DATA_BUF_SZ, device_write_completion, 
          NULL);

其中 data 是要写入的数据的 char 缓冲区，最后一个参数是要传递给回调的可选上下文对象，而 device_write_completion 是具有以下一般形式的静态方法：

void DemiUSBDevice::device_write_completion(void* context, 
    IOReturn result, void* arg0)
{
  //...
}

从中断端点读取类似：

result = (intf)->ReadPipeAsync(intf, m_input_pipe, 
          data, INPUT_DATA_BUF_SZ, device_read_completion, 
          NULL);

其中 device_read_completion 的格式如下：

void DemiUSBDevice::device_read_completion(void* context, 
    IOReturn result, void* arg0)
{
  //...
}

请注意，要接收这些回调，运行循环必须正在运行 (see this link for more information about the CFRunLoop)。实现此目的的一种方法是在调用异步读取或写入方法之后调用CFRunLoopRun()，此时主线程在运行循环运行时阻塞。处理完您的回调后，您可以调用CFRunLoopStop(CFRunLoopGetCurrent()) 来停止运行循环并将执行交给主线程。

另一种选择（我在我的代码中这样做）是将上下文对象（在以下代码示例中命名为“请求”）传递给 WritePipeAsync/ReadPipeAsync 方法 - 该对象包含一个布尔完成标志（在这个例子）。调用 read/write 方法后，不再调用CFRunLoopRun()，而是可以执行如下代码：

while (!(request->is_done))
{
  //run for 1/10 second to handle events
  Boolean returnAfterSourceHandled = false;
  CFTimeInterval seconds = 0.1;
  CFStringRef mode = kCFRunLoopDefaultMode;
  CFRunLoopRunInMode(mode, seconds, returnAfterSourceHandled);
}

这样做的好处是，如果您有其他线程使用运行循环，您不会在另一个线程停止运行循环时过早退出...

我希望这对人们有所帮助。我不得不从许多不完整的来源中提取来解决这个问题，这需要大量的工作才能正常运行......

Answer 2

在阅读了这个问题几次并考虑了一下之后，我想到了另一种模拟阻塞读取行为的解决方案，但使用 HID 管理器而不是替换它。

阻塞读取函数可以为设备注册一个输入回调，在当前运行循环中注册设备，然后通过调用 CFRunLoopRun() 来阻塞。然后，输入回调可以将报告复制到共享缓冲区并调用 CFRunLoopStop()，这会导致 CFRunLoopRun() 返回，从而解除对 read() 的阻塞。然后，read() 可以将报告返回给调用者。

我能想到的第一个问题是设备已经安排在运行循环中的情况。在读取功能中调度然后取消调度设备可能会产生不利影响。但这只有在应用程序尝试在同一设备上同时使用同步和异步调用时才会成为问题。

想到的第二件事是调用代码已经运行运行循环的情况（例如 Cocoa 和 Qt 应用程序）。但是，CFRunLoopStop() 的文档似乎表明对 CFRunLoopRun() 的嵌套调用得到了正确处理。所以，应该没问题。

这里有一些简化的代码。我刚刚在我的HID Library 中实现了类似的东西，它似乎可以工作，尽管我没有对它进行广泛的测试。

/* An IN report callback that stops its run loop when called. 
   This is purely for emulating blocking behavior in the read() method */
static void input_oneshot(void*           context,
                          IOReturn        result,
                          void*           deviceRef,
                          IOHIDReportType type,
                          uint32_t        reportID,
                          uint8_t*        report,
                          CFIndex         length)
{
    buffer_type *const buffer = static_cast<HID::buffer_type*>(context);

    /* If the report is valid, copy it into the caller's buffer
         The Report ID is prepended to the buffer so the caller can identify
         the report */
    if( buffer )
    {
        buffer->clear();    // Return an empty buffer on error
        if( !result && report && deviceRef )
        {
            buffer->reserve(length+1);
            buffer->push_back(reportID);
            buffer->insert(buffer->end(), report, report+length);
        }
    }

    CFRunLoopStop(CFRunLoopGetCurrent());
}

// Block while waiting for an IN interrupt report
bool read(buffer_type& buffer)
{
    uint8_t _bufferInput[_lengthInputBuffer];

    // Register a callback
    IOHIDDeviceRegisterInputReportCallback(deviceRef, _bufferInput, _lengthInputBuffer, input_oneshot, &buffer);

    // Schedule the device on the current run loop
    IOHIDDeviceScheduleWithRunLoop(deviceRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode);

    // Trap in the run loop until a report is received
    CFRunLoopRun();

    // The run loop has returned, so unschedule the device
    IOHIDDeviceUnscheduleFromRunLoop(deviceRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode);

    if( buffer.size() )
        return true;
    return false;
}

Answer 3

我遇到了同样的 kIOReturnExclusiveAccess。而不是与之抗争（构建kext等）。我找到了设备并使用了 POSIX api。

//My funcation was named differently, but I'm using this for continuity..
void DemiUSBDevice::device_attach_callback(void * context, 
    io_iterator_t iterator)
{
DeviceManager *deviceManager = (__bridge DADeviceManager *)context;
  io_registry_entry_t device;
  while ((device = IOIteratorNext(iterator))) {

    CFTypeRef prop;
    prop = IORegistryEntrySearchCFProperty(device,
                                           kIOServicePlane,
                                           CFSTR(kIODialinDeviceKey),
                                           kCFAllocatorDefault,
                                           kIORegistryIterateRecursively);
    if(prop){
      deviceManager->devPath = (__bridge NSString *)prop;
      [deviceManager performSelector:@selector(openDevice)];
    }
  }
}

一旦设置了 devPath，你就可以调用 open 和 read/write..

int dfd;
dfd = open([devPath UTF8String], O_RDWR | O_NOCTTY | O_NDELAY);
  if (dfd == -1) {
    //Could not open the port.
    NSLog(@"open_port: Unable to open %@", devPath);
    return;
  } else {
    fcntl(fd, F_SETFL, 0);
  }