实用程序函数

本节介绍几个常规用途的函数。

设备配置工具

本节介绍与设备配置相关的函数。

获取接口编号

如果您使用的是多接口设备，usb_mid(7D) 驱动程序只会使其接口之一可用于调用驱动程序，此时您可能需要知道调用驱动程序所绑定到的接口的编号。使用 usb_get_if_number(9F) 函数执行以下任一任务：

• 返回调用驱动程序所绑定到的接口的编号。在这种情况下，usb_get_if_number(9F) 函数返回大于零的接口编号。

• 发现调用驱动程序管理整个多接口设备。驱动程序在设备级别绑定，因此 usb_mid 没有拆分设备。在这种情况下，usb_get_if_number(9F) 函数返回 USB_DEVICE_NODE 。

• 发现调用驱动程序通过管理设备在其当前配置中提供的唯一接口来管理整个设备。在这种情况下，usb_get_if_number(9F) 函数返回 USB_COMBINED_NODE。

管理整个设备

如果驱动程序管理整个复合设备，则可通过使用包含供应商 ID、产品 ID 和修订版 ID 的兼容名称将该驱动程序绑定到整个设备。绑定到整个复合设备的驱动程序必须像结点驱动程序一样管理该设备的所有接口。通常，不应将驱动程序绑定到整个复合设备。应改为使用一般的多接口驱动程序 usb_mid(7D)。

使用 usb_owns_device(9F) 函数可确定驱动程序是否拥有整个设备。设备可以是复合设备。如果驱动程序拥有整个设备，则 usb_owns_device(9F) 函数将返回 TRUE。

多配置设备

在任何特定时间，主机上只能使用 USB 设备的一种配置。大多数设备仅支持一种配置。但是，少数 USB 设备支持多种配置。

对于具有多种配置的任何设备，都是采用可使用某驱动程序的第一种配置。查找匹配项时，设备配置以数字顺序处理。如果未找到任何匹配的驱动程序，则设备将被设置采用第一种配置。在这种情况下，usb_mid 驱动程序将接管该设备，并将设备拆分为多个接口节点。使用 usb_get_cfg(9F) 函数可返回设备的当前配置。

您可以使用以下两种方法中的任何一种来请求采用其他配置。使用其中任何一种方法修改设备配置，均可确保 USBA 模块保持与设备同步。

• 使用 cfgadm_usb(1M) 命令。

• 从驱动程序调用 usb_set_cfg(9F) 函数。

  由于更改设备配置会影响整个设备，因此客户机驱动程序必须满足以下所有条件，才能成功调用 usb_set_cfg(9F) 函数：

  • 客户机驱动程序必须拥有整个设备。

  • 设备不能有子节点，因为其他驱动程序可能会通过这些子节点驱动该设备。

  • 必须关闭除缺省管道之外的所有管道。

  • 设备必须具有多种配置。

---

注意 - 不要通过手动执行 SET_CONFIGURATION USB 请求来更改设备配置。不支持使用 SET_CONFIGURATION 请求更改配置。

---

修改或获取替代设置

客户机驱动程序可以调用 usb_set_alt_if(9F) 函数以更改当前选定接口的选定替代设置。请确保关闭已明确打开的所有管道。切换替代设置时，usb_set_alt_if(9F) 函数将验证是否仅打开了缺省管道。确保在调用 usb_set_alt_if(9F) 之前已正确设置了设备。

更改替代设置可能会影响对驱动程序可用的端点以及特定于类和特定于供应商的描述符。有关端点和描述符的更多信息，请参见描述符树。

调用 usb_get_alt_if(9F) 函数可检索当前替代设置的编号。

其他实用程序函数

本节介绍在 USB 设备驱动程序中有用的其他函数。

检索字符串描述符

调用 usb_get_string_descr(9F) 函数可检索给定了索引的字符串描述符。一些配置、接口或设备描述符具有关联的字符串 ID。这样的描述符包含具有非零值的字符串索引字段。将字符串索引字段值传递给 usb_get_string_descr(9F) 可检索对应的字符串。

管道专用数据工具

每个管道都有一个空间指针，专供客户机驱动程序使用。使用 usb_pipe_set_private(9F) 函数可安装一个值。使用 usb_pipe_get_private(9F) 函数可检索该值。当管道可能需要将其自己的客户机定义状态传递到回调，以进行特定处理时，此工具在回调中很有用。

清除 USB 条件

使用 usb_clr_feature(9F) 函数可执行以下任务：

• 发出 USB CLEAR_FEATURE 请求以清除端点的停止条件。

• 清除设备的远程唤醒条件。

• 在设备级别、接口级别或端点级别清除特定于设备的条件。

获取设备、接口或端点状态

使用 usb_get_status(9F) 函数可发出 USB GET_STATUS 请求，以检索设备、接口或端点的状态。

• 设备状态。自备电源并启用远程唤醒。

• 接口状态。根据 USB 2.0 规范返回零。

• 端点状态。已停止端点。此状态指示运行延迟。必须清除停止状态才能重新运行设备。

  协议延迟指示发出了不支持的控制管道请求。在下一个控制传输开始时将会自动清除协议延迟。

获取设备的总线地址

使用 usb_get_addr(9F) 函数可获取设备的 USB 总线地址以用于调试目的。此地址映射到特定的 USB 端口。