libusb的用法和使用步骤
1. 概述
1.1 介绍
libusb 是一个使用 c 编写的库，它提供 usb 设备的通用的访问方法。app 通过它，可以方便地访问 usb 设备，无需编写 usb 设备驱动程序。
可移植性：支持 linux、macos、windows、android、openbsd 等
用户模式：app 不需要特权模式、也不需要提升自己的权限即可访问 usb 设备
支持所有 usb 协议：从 1.0 到 3.1 都支持
libusb 支持所有的传输类型(控制/批量/中断/实时)，有两类 api 接口：同步(synchronous，简单)，异步(asynchronous，复杂但是更强大)。
它是轻量级的、线程安全的。还支持热拔插。
1.2 用法
可以通过 libusb 访问 usb 设备，不需要 usb 设备端的驱动程序，需要移除原来的驱动程序。然后就可以直接访问 usb 控制器的驱动程序，使用 open/read/write/ioctl/close 这些接口来打开设备、收发数据、关闭设备。
libusb 封装了更好用的函数，这些函数的使用可以分为 5 个步骤：
初始化
打开设备
移除原驱动/认领接口
传输
关闭设备
2. api 接口
2.1 分类
libusb 的接口函数分为两类：同步(synchronous device i/o)、异步(asynchronous device i/o)。
usb 数据传输分为两个步骤，对于读数据，先给设备发出数据的请求，一段时间后数据返回；对于写数据，先发送数据给设备，一段时间后得到回应。
同步接口的核心在于把上述两个步骤放在一个函数里面。比如想去读取一个 usb 键盘的数据，给键盘发出读请求后，如果用户一直没有按下键盘，那么读函数会一直等待。
异步接口的核心在于把上述两个步骤分开：使用一个非阻塞的函数启动传输，它会立刻返回；提供一个回调函数用来处理返回结果。
同步接口的示例代码如下，在libusb_bulk_transfer函数内部，如果没有数据则会休眠：
unsigned char data[4];int actual_length;int r = libusb_bulk_transfer(dev_handle, libusb_endpoint_in, data, sizeof(data), &actual_length, 0);if (r == 0 && actual_length == sizeof(data)) { // 接收到的数据保存在data数组里 // 解析这些数据就可以知道按键状态} else { error();}使用同步接口时，代码比较简单。但是无法实现多 endpoint的操作：上一个 endpoint 的传输在休眠，除非使用另一个线程，否则在同一个线程内部在等待期间是无法操作另一个 endpoint 的。还有另一个缺点：无法取消传输。 异步接口是在 libusb-1.0 引入的新性能，接口更复杂，但是功能更强大。在异步接口函数里，它启动传输、设置回调函数后就立刻返回。等读到数据或是得到回应后，回调函数被调用。发起数据传输的线程无需休眠等待结果，它支持多endpoint的操作，也支持取消传输。
2.2 初始化/反初始化
/** ingroup libusb_lib * 初始化libusb，这个函数必须先于其他libusb的函数执行 * * 如果传入null，那么函数内部会穿件一个默认的context * 如果已经创建过默认的context，这个context会被重新使用(不会重新初始化它) * * 参数： * ctx : context pointer的位置，也可以传入null * 返回值 * 0 - 成功 * 负数 - 失败 */int api_exported libusb_init(libusb_context **ctx); 初始化 libusb，参数是一个a context pointer的指针，如果这个参数为 null，则函数内部会创建一个default context。所谓libusb context就是 libusb 上下文，就是一个结构体，里面保存有各类信息，比如：libusb 的调试信息是否需要打印、各种互斥锁、各类链表(用来记录usb传输等等)。
程序退出前，调用如下函数：
/** ingroup libusb_lib * 发初始化libusb * 在关闭usb设备(libusb_close)后、退出程序前调用此函数 * * 参数: * ctx : context, 传入null表示default context */void api_exported libusb_exit(libusb_context *ctx); 2.3 获取设备
可以使用libusb_get_device_list取出所有设备，函数接口如下：
/** @ingroup libusb_dev * 返回一个list，list里含有当前系统中所有的usb设备 * * 我们一般会在list里寻找需要访问的设备，找到之后使用libusb_open函数打开它 * 然后调用libusb_free_device_list释放list * * 这个函数的返回值表示list中有多少个设备 * list的最后一项是null * * 参数: * ctx : context * list : output location for a list of devices, 最后必须调用libusb_free_device_list()来释放它 * 返回值: list中设备的个数, 或错误值 */ssize_t api_exported libusb_get_device_list(libusb_context *ctx,libusb_device ***list); 调用此函数后，所有设备的信息存入 list，然后遍历 list，找到想操作的设备。这个函数内部会分配 list 的空间，所以用完后要释放掉，使用以下函数释放：
/** ingroup libusb_dev * 前面使用libusb_get_device_list()获得了设备list, * 使用完后要调用libusb_free_device_list()释放这个list * 如果参数unref_devices为1, 则list中每个设备的引用计数值减小1 * 参数: * list : 要释放的设备list * unref_devices : 是否要将设备的引用计数减1 */void api_exported libusb_free_device_list(libusb_device **list,int unref_devices); 2.4 打开/关闭设备
使用 libusb_get_device_list 得到设备列表后，可以选择里面的某个设备，然后调用 libusb_open：
/** ingroup libusb_dev * 打开一个设备并得到它的句柄, 以后进行io操作时都是使用句柄 * * 使用libusb_get_device()函数可以得到设备的list, * 从list里确定你要访问的设备后, 使用libusb_open()去打开它。 * libusb_open()函数内部会增加此设备的引用计数, 使用完毕后要调用libusb_close()减小引用计数。 * * 参数: * dev : 要打开的设备 * dev_handle : 输出参数, 用来保存句柄 * 返回值: * 0 - 成功 * libusb_error_no_mem : 缺少内存 * libusb_error_access : 权限不足 * libusb_error_no_device : 这个设备未连接 * 其他错误 : 其他libusb_error错误码 */int api_exported libusb_open(libusb_device *dev,libusb_device_handle **dev_handle); 使用 libusb_open 函数打开 usb 设备后，可以得到一个句柄：libusb_device_handle。以后调用各种数据传输函数时，就是使用libusb_device_handle。
使用完毕后，调用 libusb_close 关闭设备，函数原型如下：
/** ingroup libusb_dev * 关闭设备句柄, 在程序退出之前应该使用它去关闭已经打开的句柄 * * 设备的引用计数在前面被libusb_open()函数增加了。 * 在libusb_close()函数的内部，它会减小设备的引用计数。 * * 参数: dev_handle - 句柄 */void api_exported libusb_close(libusb_device_handle *dev_handle); 2.5 根据 id 打开设备
如果知道设备的 vid、pid，那么可以使用 libusb_open_device_with_vid_pid 来找到它、打开它。这个函数的内部，先使用libusb_get_device_list列出所有设备，然后遍历它们根据 id 选出设备，接着调用 libusb_open 打开它，最后调用 libusb_free_device_list 释放设备。
libusb_open_device_with_vid_pid 函数原型如下：
/** ingroup libusb_dev * 打开设备的常规做法是使用libusb_get_device_list()得到设备list， * 然后遍历list，找到设备 * 接着使用libusb_open()函数得到句柄 * * 如果知道usb设备的vid、pid，那么可以使用libusb_open_device_with_vid_pid()函数快速打开它，得到句柄。 * * 这个函数有一个缺点: 如果系统中有多个id相同的设备，你只能打开第1个设备 * * 参数: * ctx : context, 或者传入null以使用默认的context * vendor_id : 厂家id * product_id : 产品id * * 返回值: * 句柄 - 找到的第1个设备的句柄 * null - 没有找到设备 */default_visibilitylibusb_device_handle * libusb_call libusb_open_device_with_vid_pid( libusb_context *ctx, uint16_t vendor_id, uint16_t product_id); 2.6 描述符相关函数
2.6.1 获得设备描述符
/** ingroup libusb_desc * 获得设备描述符 * * 参数: * dev - 哪个设备 * desc - 输出参数, 用来保存设备描述符 * * 返回值: * 0 - 成功, 或其他libusb_error错误码 */int api_exported libusb_get_device_descriptor(libusb_device *dev, struct libusb_device_descriptor *desc); 2.6.2 获得/释放配置描述符
/** ingroup libusb_desc * 获得指定的配置描述符 * * 参数: * dev - 哪个设备 * config_index - 哪个配置 * config - 输出参数, 用来保存配置描述符, 使用完毕要调用libusb_free_config_descriptor()释放掉 * * 返回值: * 0 - 成功 * libusb_error_not_found - 没有这个配置 * 其他libusb_error错误码 */int api_exported libusb_get_config_descriptor(libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config);/** ingroup libusb_desc * free a configuration descriptor obtained from * 前面使用libusb_get_active_config_descriptor()或libusb_get_config_descriptor()获得配置描述符， * 用完后调用libusb_free_config_descriptor()释放掉 */void api_exported libusb_free_config_descriptor( struct libusb_config_descriptor *config); 2.7 detach/attach 驱动
2.7.1 两种方法
使用 libusb 访问 usb 设备时，需要先移除(detach)设备原来的驱动程序，然后认领接口(claim interface)。有两种办法：
方法1：
// 只是设置一个标记位表示libusb_claim_interface// 使用libusb_claim_interface时会detach原来的驱动libusb_set_auto_detach_kernel_driver(hdev, 1); // 标记这个interface已经被使用认领了libusb_claim_interface(hdev, interface_number); 方法2：
// detach原来的驱动libusb_detach_kernel_driver(hdev, interface_number);// 标记这个interface已经被使用认领了libusb_claim_interface(hdev, interface_number); 2.7.2 函数原型
函数libusb_detach_kernel_driver原型如下：
/** ingroup libusb_dev * 给usb设备的接口(interface)移除驱动程序. if successful, you will then be * 移除原来的驱动后才能claim the interface、执行io操作 * * 实际上libusb会给这个接口安装一个特殊的内核驱动, * 所以本函数移除驱动是移除其他驱动，不是移除这个特殊的驱动。 * 若干这个接口已经安装了这个特殊的驱动，本函数会返回libusb_error_not_found. * * 参数: * dev_handle - 设备句柄 * interface_number - 哪一个接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 这个接口没有安装其他驱动 * libusb_error_invalid_param - 没有这个接口 * libusb_error_no_device - 这个设备未连接 * libusb_error_not_supported - 系统不支持此操作, 比如windows * 其他libusb_error错误码 */int api_exported libusb_detach_kernel_driver(libusb_device_handle *dev_handle,int interface_number); 函数libusb_claim_interface原型如下：
/** ingroup libusb_dev * libusb使用内核里一个特殊的驱动程序， * libusb_claim_interface()函数就是给某个usb接口安装这个特殊的驱动程序， * 在使用libusb的函数执行io操作之前必须调用本函数。 * * 你可以给已经claim过的接口再次调用本函数，它直接返回0。 * * 如果这个接口的auto_detach_kernel_driver被设置为1， * libusb_claim_interface()函数会先移除其他驱动。 * * 本函数时纯粹的逻辑操作：只是替换接口的驱动程序而已，不会导致usb硬件传输。 * * 参数: * dev_handle - 句柄, 表示usb设备 * interface_number - 接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 没有这个接口 * libusb_error_busy - 其他app或者驱动正在使用这个接口 * libusb_error_no_device - 设备未连接 * 其他libusb_error错误码 */int api_exported libusb_claim_interface(libusb_device_handle *dev_handle,int interface_number); 使用完 usb 设备后，在调用 libusb_close 之前，应该libusb_release_interface释放接口：
/** ingroup libusb_dev * 前面使用libusb_claim_interface()给接口安装了给libusb使用的特殊驱动程序, * 使用完毕后，在调用libusb_close()关闭句柄之前， * 可以调用libusb_release_interface()卸载特殊驱动程序 * 如果设备的auto_detach_kernel_driver为1，还会重新安装普通驱动程序 * * 这是一个阻塞函数, 它会给usb设备发送一个请求: set_interface control, * 用来把接口的状态复位到第1个setting(the first alternate setting) * * 参数: * dev_handle - 设备句柄 * interface_number - 哪个接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 这个接口没有被claim(没有安装特殊的驱动程序) * libusb_error_no_device - 设备未连接 * 其他libusb_error错误码 */int api_exported libusb_release_interface(libusb_device_handle *dev_handle,int interface_number); 2.8 同步传输函数
2.8.1 控制传输
/** ingroup libusb_syncio * 启动控制传输 * * 传输方向在bmrequesttype里 * wvalue,windex和wlength是host-endian字节序 * * 参数: * dev_handle - 设备句柄 * bmrequesttype - setup数据包的bmrequesttype域 * brequest - setup数据包的brequest域 * wvalue - setup数据包的wvalue域 * windex - setup数据包的windex域 * data - 保存数据的buffer, 可以是in、out数据 * wlength - setup数据包的wlength域 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 正整数 - 成功传输的数据的长度 * libusb_error_timeout - 超时 * libusb_error_pipe - 设备不支持该请求 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * the operating system and/or hardware can support (see ef asynclimits) * 其他libusb_error错误码 */int api_exported libusb_control_transfer(libusb_device_handle *dev_handle, uint8_t bmrequesttype, uint8_t brequest, uint16_t wvalue, uint16_t windex, unsigned char *data, uint16_t wlength, unsigned int timeout); 2.8.2 批量传输
/** ingroup libusb_syncio * 启动批量传输 * 传输方向在endpoint的方向位里表示 * * 对于批量读，参数length表示期望读到的数据最大长度, 实际读到的长度保存在transferred参数里 * * 对于批量写, transferred参数表示实际发送出去的数据长度 * * 发生超时错误时，也应该检查transferred参数。 * libusb会根据硬件的特点把数据拆分为一小段一小段地发送出去， * 这意味着发送满某段数据后可能就发生超时错误，需要根据transferred参数判断传输了多少数据。 * * 参数: * dev_handle - 设备句柄 * endpoint - 端点 * data - 保存数据的buffer, 可以是in、out数据 * length - 对于批量写，它表示要发送的数据长度; 对于批量读，它表示要读的数据的最大长度 * transferred - 输出参数，表示实际传输的数据长度 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 0 - 成功，根据transferred参数判断传输了多少长度的数据 * libusb_error_timeout - 超时, 根据transferred参数判断传输了多少长度的数据 * libusb_error_pipe - 端点错误，端点被挂起了 * libusb_error_overflow - 溢出，设备提供的数据太多了 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_bulk_transfer(libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); 2.8.3 中断传输
/** ingroup libusb_syncio * 启动中断传输 * 传输方向在endpoint的方向位里表示 * * 对于中断读，参数length表示期望读到的数据最大长度, 实际读到的长度保存在transferred参数里 * * 对于中断写, transferred参数表示实际发送出去的数据长度，不一定能发送完全部数据。 * * 发生超时错误时，也应该检查transferred参数。 * libusb会根据硬件的特点把数据拆分为一小段一小段地发送出去， * 这意味着发送满某段数据后可能就发生超时错误，需要根据transferred参数判断传输了多少数据。 * * 参数: * dev_handle - 设备句柄 * endpoint - 端点 * data - 保存数据的buffer, 可以是in、out数据 * length - 对于批量写，它表示要发送的数据长度; 对于批量读，它表示要读的数据的最大长度 * transferred - 输出参数，表示实际传输的数据长度 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 0 - 成功，根据transferred参数判断传输了多少长度的数据 * libusb_error_timeout - 超时, 根据transferred参数判断传输了多少长度的数据 * libusb_error_pipe - 端点错误，端点被挂起了 * libusb_error_overflow - 溢出，设备提供的数据太多了 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_interrupt_transfer(libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); 2.9 异步传输函数
2.9.1 使用步骤
使用 libusb 的异步函数时，有如下步骤：
分配：分配一个libusb_transfer结构体
填充：填充libusb_transfer结构体，比如想访问哪个 endpoint、数据 buffer、长度等等
提交：提交libusb_transfer结构体启动传输
处理事件：检查传输的结果，调用libusb_transfer结构体的回调函数
释放：释放资源，比如释放libusb_transfer结构体
2.9.2 分配 transfer 结构体
/** ingroup libusb_asyncio * 分配一个libusb_transfer结构体， * 如果iso_packets不为0，还会分配iso_packets个libusb_iso_packet_descriptor结构体 * 使用完毕后需要调用libusb_free_transfer()函数释放掉 * * 对于控制传输、批量传输、中断传输，iso_packets参数需要设置为0 * * 对于实时传输，需要指定iso_packets参数， * 这个函数会一起分配iso_packets个libusb_iso_packet_descriptor结构体。 * 这个函数返回的libusb_transfer结构体并未初始化， * 你还需要初始化它的这些成员: * libusb_transfer::num_iso_packets * libusb_transfer::type * * 你可以指定iso_packets参数，意图给实时传输分配结构体， * 但是你可以把这个结构题用于其他类型的传输， * 在这种情况下，只要确保num_iso_packets为0就可以。 * * 参数: * iso_packets - 分配多少个isochronous packet descriptors to allocate * * 返回值: * 返回一个libusb_transfer结构体或null */default_visibilitystruct libusb_transfer * libusb_call libusb_alloc_transfer(int iso_packets); 2.9.3 填充控制传输
/** ingroup libusb_asyncio * 构造控制传输结构体 * * 如果你传入buffer参数，那么buffer的前面8字节会被当做control setup packet来解析， * buffer的最后2字节表示wlength，它也会被用来设置libusb_transfer::length * 所以，建议使用流程如下: * 1. 分配buffer，这个buffer的前面8字节对应control setup packet，后面的空间可以用来保存其他数据 * 2. 设置control setup packet，通过调用libusb_fill_control_setup()函数来设置 * 3. 如果是要把数据发送个设备，把要发送的数据放在buffer的后面(从buffer[8]开始放) * 4. 调用libusb_fill_bulk_transfer * 5. 提交传输: 调用libusb_submit_transfer() * * 也可以让buffer参数为null， * 这种情况下libusb_transfer::length就不会被设置, * 需要手工去设置ibusb_transfer::buffer、ibusb_transfer::length * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * buffer - 数据buffer，如果不是null的话，它前面8直接会被当做control setup packet来处理， * 也会从buffer[6], buffer[7]把length提取出来，用来设置libusb_transfer::length * 这个buffer必须是2字节对齐 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_control_transfer( struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.4 填充批量传输
/** ingroup libusb_asyncio * 构造批量传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.5 填充中断传输
/** ingroup libusb_asyncio * 构造中断传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_interrupt_transfer( struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.6 填充实时传输
/** ingroup libusb_asyncio * 构造实时传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * num_iso_packets - 实时传输包的个数 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, int num_iso_packets, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.7 提交传输
/** ingroup libusb_asyncio * 提交传输submit，这个函数会启动传输，然后立刻返回 * * 参数: * transfer - 要传输的libusb_transfer结构体 * * 返回值: * 0 - 成功 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 这个传输已经提交过了 * libusb_error_not_supported - 不支持这个传输 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_submit_transfer(struct libusb_transfer *transfer); 2.9.8 处理事件
有 4 个函数，其中 2 个没有completed后缀的函数过时了：
/** ingroup libusb_poll * 处理任何pengding的事件 * * 使用异步传输函数时，提交的tranfer结构体后就返回了。 * 可以使用本函数处理这些传输的返回结果。 * * 如果timeval参数为0，本函数会处理当前、已经pending的事件，然后马上返回。 * * 如果timeval参数不为0，并且当前没有待处理的事件，本函数会阻塞以等待事件，直到超时。 * 在等待过程中，如果事件发生了、或者得到了信号(signal)，那么这个函数会提前返回。 * * completed参数用来避免竞争，如果它不为null: * 本函数获得event handling lock后，会判断completed指向的数值， * 如果这个数值非0(表示别的线程已经处理了、已经completed了)， * 则本函数会立刻返回(既然都completed了，当然无需再处理) * * 参数: * ctx - context(如果传入null则使用默认context) * tv - 等待事件的最大时间，0表示不等待 * completed - 指针，可以传入null * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_timeout_completed(libusb_context *ctx, struct timeval *tv, int *completed);/** ingroup libusb_poll * 处理任何pengding的事件 * * 跟libusb_handle_events_timeout_completed()类似, * 就是调用libusb_handle_events_timeout_completed(ctx, tv, null); * 最后的completed参数为null。 * * 这个函数只是为了保持向后兼容，新的代码建议使用libusb_handle_events_completed()或 * libusb_handle_events_timeout_completed()， * 这2个新函数可以处理竞争。 * * 参数: * ctx - context(如果传入null则使用默认context) * tv - 等待事件的最大时间，0表示不等待 * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_timeout(libusb_context *ctx,struct timeval *tv);/** ingroup libusb_poll * 处理任何pengding的事件，以阻塞方式处理(blocking mode) * * 本函数的内部实现就是调用: libusb_handle_events_timeout_completed(ctx, &tv, completed); * 超时时间设置为60秒 * * 参数: * ctx - context(如果传入null则使用默认context) * completed - 指针，可以传入null * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_completed(libusb_context *ctx,int *completed);/** ingroup libusb_poll * 处理任何pengding的事件，以阻塞方式处理(blocking mode) * * 本函数的内部实现就是调用: libusb_handle_events_timeout_completed(ctx, &tv, null); * 超时时间设置为60秒 * * 这个函数只是为了保持向后兼容，新的代码建议使用libusb_handle_events_completed()或 * libusb_handle_events_timeout_completed()， * 这2个新函数可以处理竞争。 * * 参数: * ctx - context(如果传入null则使用默认context) * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events(libusb_context *ctx); 2.9.9 释放 transfer 结构体
传输完毕，需要释放 libusb_transfer 结构体，如果要重复利用这个结构体则无需释放。
/** ingroup libusb_asyncio * 释放libusb_transfer结构体 * 前面使用libusb_alloc_transfer()分配的结构体，要使用本函数来释放。 * * 如果libusb_transfer::flags的libusb_transfer_free_buffer位非0， * 那么会使用free()函数释放ibusb_transfer::buffer * * 不能使用本函数释放一个活动的传输结构体(active, 已经提交尚未结束) * */void api_exported libusb_free_transfer(struct libusb_transfer *transfer); 3. 使用示例
在 libusb 源码的 examples 目录下有示例程序，我们也有一些真实的案列。
3.1 dnw 工具
dnw 是 s3c2440 时代的工具，使用它可以从 pc 给开发板传输文件。它的核心源码如下，使用同步接口进行数据传输：
/* open the device using libusb */ status = libusb_init(null); if (status < 0) { printf(libusb_init() failed: %s, libusb_error_name(status)); return -1; } hdev = libusb_open_device_with_vid_pid(null, (uint16_t)dnw_device_idvendor, (uint16_t)dnw_device_idproduct); if (hdev == null) { printf(libusb_open() failed); goto err3; } /* we need to claim the first interface */ libusb_set_auto_detach_kernel_driver(hdev, 1); status = libusb_claim_interface(hdev, 0); if (status != libusb_success) { libusb_close(hdev); printf(libusb_claim_interface failed: %s, libusb_error_name(status)); goto err2; } ret = libusb_bulk_transfer(hdev, 0x03, buf, num_write, &transferred, 3000); 3.2 openocd
openocd 是一个开源的 usb jtag 调试软件，它也是使用 libusb，涉及 usb 的操作代码如下。
3.2.1 找到设备
static int cmsis_dap_usb_open(struct cmsis_dap *dap, uint16_t vids[], uint16_t pids[], const char *serial){ int err; struct libusb_context *ctx; struct libusb_device **device_list; err = libusb_init(&ctx); if (err) { log_error(libusb initialization failed: %s, libusb_strerror(err)); return error_fail; } int num_devices = libusb_get_device_list(ctx, &device_list); if (num_devices < 0) { log_error(could not enumerate usb devices: %s, libusb_strerror(num_devices)); libusb_exit(ctx); return error_fail; } for (int i = 0; i 0) { err = libusb_get_string_descriptor_ascii( dev_handle, dev_desc.iserialnumber, (uint8_t *)dev_serial, sizeof(dev_serial)); if (err 0) { err = libusb_get_string_descriptor_ascii( dev_handle, dev_desc.iproduct, (uint8_t *)product_string, sizeof(product_string)); if (err interface[interface].altsetting[0]; int interface_num = intf_desc->binterfacenumber; /* skip this interface if another one was requested explicitly */ if (cmsis_dap_usb_interface != -1 && cmsis_dap_usb_interface != interface_num) continue; /* cmsis-dap v2 spec says: * * cmsis-dap with default v2 configuration uses winusb and is therefore faster. * optionally support for streaming swo trace is provided via an additional usb endpoint. * * the winusb configuration requires custom class support with the interface setting * class code: 0xff (vendor specific) * subclass: 0x00 * protocol code: 0x00 * * depending on the configuration it uses the following usb endpoints which should be configured * in the interface descriptor in this order: * - endpoint 1: bulk out – used for commands received from host pc. * - endpoint 2: bulk in – used for responses send to host pc. * - endpoint 3: bulk in (optional) – used for streaming swo trace (if enabled with swo_stream). */ /* search for cmsis-dap in the interface string */ bool cmsis_dap_in_interface_str = false; if (intf_desc->iinterface != 0) { char interface_str[256] = {0}; err = libusb_get_string_descriptor_ascii( dev_handle, intf_desc->iinterface, (uint8_t *)interface_str, sizeof(interface_str)); if (err iinterface, dev_desc.idvendor, dev_desc.idproduct, libusb_strerror(err)); } else if (strstr(interface_str, cmsis-dap)) { cmsis_dap_in_interface_str = true; log_debug(found interface %d string '%s', interface_num, interface_str); } } /* bypass the following check if this interface was explicitly requested. */ if (cmsis_dap_usb_interface == -1) { if (!cmsis_dap_in_product_str && !cmsis_dap_in_interface_str) continue; } /* check endpoints */ if (intf_desc->bnumendpoints bnumendpoints); continue; } if ((intf_desc->endpoint[0].bmattributes & 3) != libusb_transfer_type_bulk || (intf_desc->endpoint[0].bendpointaddress & 0x80) != libusb_endpoint_out) { log_debug(skipping interface %d, endpoint[0] is not bulk out, interface_num); continue; } if ((intf_desc->endpoint[1].bmattributes & 3) != libusb_transfer_type_bulk || (intf_desc->endpoint[1].bendpointaddress & 0x80) != libusb_endpoint_in) { log_debug(skipping interface %d, endpoint[1] is not bulk in, interface_num); continue; } /* we can rely on the interface is really cmsis-dap if * - we've seen cmsis-dap in the interface string * - config asked explicitly for an interface number * - the device has only one interface * the later two cases should be honored only if we know * we are on the right device */ bool intf_identified_reliably = cmsis_dap_in_interface_str || (device_identified_reliably && (cmsis_dap_usb_interface != -1 || config_desc->bnuminterfaces == 1)); if (intf_desc->binterfaceclass != libusb_class_vendor_spec || intf_desc->binterfacesubclass != 0 || intf_desc->binterfaceprotocol != 0) { /* if the interface is reliably identified * then we need not insist on setting usb class, subclass and protocol * exactly as the specification requires. * at least kitprog3 uses class 0 contrary to the specification */ if (intf_identified_reliably) { log_warning(using cmsis-dapv2 interface %d with wrong class % prid8 subclass % prid8 or protocol % prid8, interface_num, intf_desc->binterfaceclass, intf_desc->binterfacesubclass, intf_desc->binterfaceprotocol); } else { log_debug(skipping interface %d, class % prid8 subclass % prid8 protocol % prid8, interface_num, intf_desc->binterfaceclass, intf_desc->binterfacesubclass, intf_desc->binterfaceprotocol); continue; } } if (intf_identified_reliably) { /* that's the one! */ intf_desc_found = intf_desc; break; } if (!intf_desc_candidate && device_identified_reliably) { /* this interface looks suitable for cmsis-dap. store the pointer to it * and keep searching for another one with cmsis-dap in interface string */ intf_desc_candidate = intf_desc; } } if (!intf_desc_found) { /* we were not able to identify reliably which interface is cmsis-dap. * let's use the first suitable if we found one */ intf_desc_found = intf_desc_candidate; } if (!intf_desc_found) { libusb_free_config_descriptor(config_desc); continue; } /* we've chosen an interface, connect to it */ int interface_num = intf_desc_found->binterfacenumber; int packet_size = intf_desc_found->endpoint[0].wmaxpacketsize; int ep_out = intf_desc_found->endpoint[0].bendpointaddress; int ep_in = intf_desc_found->endpoint[1].bendpointaddress; libusb_free_config_descriptor(config_desc); libusb_free_device_list(device_list, true); log_info(using cmsis-dapv2 interface with vid:pid=0x%04x:0x%04x, serial=%s, dev_desc.idvendor, dev_desc.idproduct, dev_serial); int current_config; err = libusb_get_configuration(dev_handle, ¤t_config); if (err) { log_error(could not find current configuration: %s, libusb_strerror(err)); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } if (config_num != current_config) { err = libusb_set_configuration(dev_handle, config_num); if (err) { log_error(could not set configuration: %s, libusb_strerror(err)); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } } err = libusb_claim_interface(dev_handle, interface_num); if (err) log_warning(could not claim interface: %s, libusb_strerror(err)); dap->bdata = malloc(sizeof(struct cmsis_dap_backend_data)); if (!dap->bdata) { log_error(unable to allocate memory); libusb_release_interface(dev_handle, interface_num); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } dap->packet_size = packet_size; dap->packet_buffer_size = packet_size; dap->bdata->usb_ctx = ctx; dap->bdata->dev_handle = dev_handle; dap->bdata->ep_out = ep_out; dap->bdata->ep_in = ep_in; dap->bdata->interface = interface_num; dap->packet_buffer = malloc(dap->packet_buffer_size); if (!dap->packet_buffer) { log_error(unable to allocate memory); cmsis_dap_usb_close(dap); return error_fail; } dap->command = dap->packet_buffer; dap->response = dap->packet_buffer; return error_ok; } libusb_close(dev_handle); } libusb_free_device_list(device_list, true); libusb_exit(ctx); return error_fail;} 3.2.2 读写数据
OpenHarmony竞赛训练营（第一期）决赛入围名单公示
RF-35TACONICmaterial的性能及应用简介
详谈RFID的市场应用及发展前景
新能源汽车规划明年3月出台
华为将于12月21日发布智慧屏S系列新品：搭载鸿蒙OS系统
libusb的用法和使用步骤
Verilog HDL中定义的26个有关门级的关键字中常用的有哪些？
腾讯首次攻破超声波屏下指纹识别技术
频谱分析仪68169B_40G维修无法开机案例
Redmi K20 PRO首发体验Android Q系统
压敏电阻构成的LED驱动电路
征信机构不得过度采集信用信息
74hc138能锁存吗 74hc138功能详解
MF52型热敏电阻
比特币的“去中心化”是否彻底？什么是BGP劫持呢？
如何利用Silent Switcher 2稳压器来满足汽车制造商的EMI要求
览邦WACH MAX-A90智能手表，经典设计焕发现代魅力，硬核性能，集运动健康娱乐于一表
耳机放大器中的噪音抑制详解
英伟达「黄氏定律」让未来的AI算力每年能够提升一倍
清问一下PE和GND到底该怎么联呢？
1.1 介绍
libusb 是一个使用 c 编写的库，它提供 usb 设备的通用的访问方法。app 通过它，可以方便地访问 usb 设备，无需编写 usb 设备驱动程序。
可移植性：支持 linux、macos、windows、android、openbsd 等
用户模式：app 不需要特权模式、也不需要提升自己的权限即可访问 usb 设备
支持所有 usb 协议：从 1.0 到 3.1 都支持
libusb 支持所有的传输类型(控制/批量/中断/实时)，有两类 api 接口：同步(synchronous，简单)，异步(asynchronous，复杂但是更强大)。
它是轻量级的、线程安全的。还支持热拔插。
1.2 用法
可以通过 libusb 访问 usb 设备，不需要 usb 设备端的驱动程序，需要移除原来的驱动程序。然后就可以直接访问 usb 控制器的驱动程序，使用 open/read/write/ioctl/close 这些接口来打开设备、收发数据、关闭设备。
libusb 封装了更好用的函数，这些函数的使用可以分为 5 个步骤：
初始化
打开设备
移除原驱动/认领接口
传输
关闭设备
2. api 接口
2.1 分类
libusb 的接口函数分为两类：同步(synchronous device i/o)、异步(asynchronous device i/o)。
usb 数据传输分为两个步骤，对于读数据，先给设备发出数据的请求，一段时间后数据返回；对于写数据，先发送数据给设备，一段时间后得到回应。
同步接口的核心在于把上述两个步骤放在一个函数里面。比如想去读取一个 usb 键盘的数据，给键盘发出读请求后，如果用户一直没有按下键盘，那么读函数会一直等待。
异步接口的核心在于把上述两个步骤分开：使用一个非阻塞的函数启动传输，它会立刻返回；提供一个回调函数用来处理返回结果。
同步接口的示例代码如下，在libusb_bulk_transfer函数内部，如果没有数据则会休眠：
unsigned char data[4];int actual_length;int r = libusb_bulk_transfer(dev_handle, libusb_endpoint_in, data, sizeof(data), &actual_length, 0);if (r == 0 && actual_length == sizeof(data)) { // 接收到的数据保存在data数组里 // 解析这些数据就可以知道按键状态} else { error();}使用同步接口时，代码比较简单。但是无法实现多 endpoint的操作：上一个 endpoint 的传输在休眠，除非使用另一个线程，否则在同一个线程内部在等待期间是无法操作另一个 endpoint 的。还有另一个缺点：无法取消传输。 异步接口是在 libusb-1.0 引入的新性能，接口更复杂，但是功能更强大。在异步接口函数里，它启动传输、设置回调函数后就立刻返回。等读到数据或是得到回应后，回调函数被调用。发起数据传输的线程无需休眠等待结果，它支持多endpoint的操作，也支持取消传输。
2.2 初始化/反初始化
/** ingroup libusb_lib * 初始化libusb，这个函数必须先于其他libusb的函数执行 * * 如果传入null，那么函数内部会穿件一个默认的context * 如果已经创建过默认的context，这个context会被重新使用(不会重新初始化它) * * 参数： * ctx : context pointer的位置，也可以传入null * 返回值 * 0 - 成功 * 负数 - 失败 */int api_exported libusb_init(libusb_context **ctx); 初始化 libusb，参数是一个a context pointer的指针，如果这个参数为 null，则函数内部会创建一个default context。所谓libusb context就是 libusb 上下文，就是一个结构体，里面保存有各类信息，比如：libusb 的调试信息是否需要打印、各种互斥锁、各类链表(用来记录usb传输等等)。
程序退出前，调用如下函数：
/** ingroup libusb_lib * 发初始化libusb * 在关闭usb设备(libusb_close)后、退出程序前调用此函数 * * 参数: * ctx : context, 传入null表示default context */void api_exported libusb_exit(libusb_context *ctx); 2.3 获取设备
可以使用libusb_get_device_list取出所有设备，函数接口如下：
/** @ingroup libusb_dev * 返回一个list，list里含有当前系统中所有的usb设备 * * 我们一般会在list里寻找需要访问的设备，找到之后使用libusb_open函数打开它 * 然后调用libusb_free_device_list释放list * * 这个函数的返回值表示list中有多少个设备 * list的最后一项是null * * 参数: * ctx : context * list : output location for a list of devices, 最后必须调用libusb_free_device_list()来释放它 * 返回值: list中设备的个数, 或错误值 */ssize_t api_exported libusb_get_device_list(libusb_context *ctx,libusb_device ***list); 调用此函数后，所有设备的信息存入 list，然后遍历 list，找到想操作的设备。这个函数内部会分配 list 的空间，所以用完后要释放掉，使用以下函数释放：
/** ingroup libusb_dev * 前面使用libusb_get_device_list()获得了设备list, * 使用完后要调用libusb_free_device_list()释放这个list * 如果参数unref_devices为1, 则list中每个设备的引用计数值减小1 * 参数: * list : 要释放的设备list * unref_devices : 是否要将设备的引用计数减1 */void api_exported libusb_free_device_list(libusb_device **list,int unref_devices); 2.4 打开/关闭设备
使用 libusb_get_device_list 得到设备列表后，可以选择里面的某个设备，然后调用 libusb_open：
/** ingroup libusb_dev * 打开一个设备并得到它的句柄, 以后进行io操作时都是使用句柄 * * 使用libusb_get_device()函数可以得到设备的list, * 从list里确定你要访问的设备后, 使用libusb_open()去打开它。 * libusb_open()函数内部会增加此设备的引用计数, 使用完毕后要调用libusb_close()减小引用计数。 * * 参数: * dev : 要打开的设备 * dev_handle : 输出参数, 用来保存句柄 * 返回值: * 0 - 成功 * libusb_error_no_mem : 缺少内存 * libusb_error_access : 权限不足 * libusb_error_no_device : 这个设备未连接 * 其他错误 : 其他libusb_error错误码 */int api_exported libusb_open(libusb_device *dev,libusb_device_handle **dev_handle); 使用 libusb_open 函数打开 usb 设备后，可以得到一个句柄：libusb_device_handle。以后调用各种数据传输函数时，就是使用libusb_device_handle。
使用完毕后，调用 libusb_close 关闭设备，函数原型如下：
/** ingroup libusb_dev * 关闭设备句柄, 在程序退出之前应该使用它去关闭已经打开的句柄 * * 设备的引用计数在前面被libusb_open()函数增加了。 * 在libusb_close()函数的内部，它会减小设备的引用计数。 * * 参数: dev_handle - 句柄 */void api_exported libusb_close(libusb_device_handle *dev_handle); 2.5 根据 id 打开设备
如果知道设备的 vid、pid，那么可以使用 libusb_open_device_with_vid_pid 来找到它、打开它。这个函数的内部，先使用libusb_get_device_list列出所有设备，然后遍历它们根据 id 选出设备，接着调用 libusb_open 打开它，最后调用 libusb_free_device_list 释放设备。
libusb_open_device_with_vid_pid 函数原型如下：
/** ingroup libusb_dev * 打开设备的常规做法是使用libusb_get_device_list()得到设备list， * 然后遍历list，找到设备 * 接着使用libusb_open()函数得到句柄 * * 如果知道usb设备的vid、pid，那么可以使用libusb_open_device_with_vid_pid()函数快速打开它，得到句柄。 * * 这个函数有一个缺点: 如果系统中有多个id相同的设备，你只能打开第1个设备 * * 参数: * ctx : context, 或者传入null以使用默认的context * vendor_id : 厂家id * product_id : 产品id * * 返回值: * 句柄 - 找到的第1个设备的句柄 * null - 没有找到设备 */default_visibilitylibusb_device_handle * libusb_call libusb_open_device_with_vid_pid( libusb_context *ctx, uint16_t vendor_id, uint16_t product_id); 2.6 描述符相关函数
2.6.1 获得设备描述符
/** ingroup libusb_desc * 获得设备描述符 * * 参数: * dev - 哪个设备 * desc - 输出参数, 用来保存设备描述符 * * 返回值: * 0 - 成功, 或其他libusb_error错误码 */int api_exported libusb_get_device_descriptor(libusb_device *dev, struct libusb_device_descriptor *desc); 2.6.2 获得/释放配置描述符
/** ingroup libusb_desc * 获得指定的配置描述符 * * 参数: * dev - 哪个设备 * config_index - 哪个配置 * config - 输出参数, 用来保存配置描述符, 使用完毕要调用libusb_free_config_descriptor()释放掉 * * 返回值: * 0 - 成功 * libusb_error_not_found - 没有这个配置 * 其他libusb_error错误码 */int api_exported libusb_get_config_descriptor(libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config);/** ingroup libusb_desc * free a configuration descriptor obtained from * 前面使用libusb_get_active_config_descriptor()或libusb_get_config_descriptor()获得配置描述符， * 用完后调用libusb_free_config_descriptor()释放掉 */void api_exported libusb_free_config_descriptor( struct libusb_config_descriptor *config); 2.7 detach/attach 驱动
2.7.1 两种方法
使用 libusb 访问 usb 设备时，需要先移除(detach)设备原来的驱动程序，然后认领接口(claim interface)。有两种办法：
方法1：
// 只是设置一个标记位表示libusb_claim_interface// 使用libusb_claim_interface时会detach原来的驱动libusb_set_auto_detach_kernel_driver(hdev, 1); // 标记这个interface已经被使用认领了libusb_claim_interface(hdev, interface_number); 方法2：
// detach原来的驱动libusb_detach_kernel_driver(hdev, interface_number);// 标记这个interface已经被使用认领了libusb_claim_interface(hdev, interface_number); 2.7.2 函数原型
函数libusb_detach_kernel_driver原型如下：
/** ingroup libusb_dev * 给usb设备的接口(interface)移除驱动程序. if successful, you will then be * 移除原来的驱动后才能claim the interface、执行io操作 * * 实际上libusb会给这个接口安装一个特殊的内核驱动, * 所以本函数移除驱动是移除其他驱动，不是移除这个特殊的驱动。 * 若干这个接口已经安装了这个特殊的驱动，本函数会返回libusb_error_not_found. * * 参数: * dev_handle - 设备句柄 * interface_number - 哪一个接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 这个接口没有安装其他驱动 * libusb_error_invalid_param - 没有这个接口 * libusb_error_no_device - 这个设备未连接 * libusb_error_not_supported - 系统不支持此操作, 比如windows * 其他libusb_error错误码 */int api_exported libusb_detach_kernel_driver(libusb_device_handle *dev_handle,int interface_number); 函数libusb_claim_interface原型如下：
/** ingroup libusb_dev * libusb使用内核里一个特殊的驱动程序， * libusb_claim_interface()函数就是给某个usb接口安装这个特殊的驱动程序， * 在使用libusb的函数执行io操作之前必须调用本函数。 * * 你可以给已经claim过的接口再次调用本函数，它直接返回0。 * * 如果这个接口的auto_detach_kernel_driver被设置为1， * libusb_claim_interface()函数会先移除其他驱动。 * * 本函数时纯粹的逻辑操作：只是替换接口的驱动程序而已，不会导致usb硬件传输。 * * 参数: * dev_handle - 句柄, 表示usb设备 * interface_number - 接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 没有这个接口 * libusb_error_busy - 其他app或者驱动正在使用这个接口 * libusb_error_no_device - 设备未连接 * 其他libusb_error错误码 */int api_exported libusb_claim_interface(libusb_device_handle *dev_handle,int interface_number); 使用完 usb 设备后，在调用 libusb_close 之前，应该libusb_release_interface释放接口：
/** ingroup libusb_dev * 前面使用libusb_claim_interface()给接口安装了给libusb使用的特殊驱动程序, * 使用完毕后，在调用libusb_close()关闭句柄之前， * 可以调用libusb_release_interface()卸载特殊驱动程序 * 如果设备的auto_detach_kernel_driver为1，还会重新安装普通驱动程序 * * 这是一个阻塞函数, 它会给usb设备发送一个请求: set_interface control, * 用来把接口的状态复位到第1个setting(the first alternate setting) * * 参数: * dev_handle - 设备句柄 * interface_number - 哪个接口 * * 返回值: * 0 - 成功 * libusb_error_not_found - 这个接口没有被claim(没有安装特殊的驱动程序) * libusb_error_no_device - 设备未连接 * 其他libusb_error错误码 */int api_exported libusb_release_interface(libusb_device_handle *dev_handle,int interface_number); 2.8 同步传输函数
2.8.1 控制传输
/** ingroup libusb_syncio * 启动控制传输 * * 传输方向在bmrequesttype里 * wvalue,windex和wlength是host-endian字节序 * * 参数: * dev_handle - 设备句柄 * bmrequesttype - setup数据包的bmrequesttype域 * brequest - setup数据包的brequest域 * wvalue - setup数据包的wvalue域 * windex - setup数据包的windex域 * data - 保存数据的buffer, 可以是in、out数据 * wlength - setup数据包的wlength域 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 正整数 - 成功传输的数据的长度 * libusb_error_timeout - 超时 * libusb_error_pipe - 设备不支持该请求 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * the operating system and/or hardware can support (see ef asynclimits) * 其他libusb_error错误码 */int api_exported libusb_control_transfer(libusb_device_handle *dev_handle, uint8_t bmrequesttype, uint8_t brequest, uint16_t wvalue, uint16_t windex, unsigned char *data, uint16_t wlength, unsigned int timeout); 2.8.2 批量传输
/** ingroup libusb_syncio * 启动批量传输 * 传输方向在endpoint的方向位里表示 * * 对于批量读，参数length表示期望读到的数据最大长度, 实际读到的长度保存在transferred参数里 * * 对于批量写, transferred参数表示实际发送出去的数据长度 * * 发生超时错误时，也应该检查transferred参数。 * libusb会根据硬件的特点把数据拆分为一小段一小段地发送出去， * 这意味着发送满某段数据后可能就发生超时错误，需要根据transferred参数判断传输了多少数据。 * * 参数: * dev_handle - 设备句柄 * endpoint - 端点 * data - 保存数据的buffer, 可以是in、out数据 * length - 对于批量写，它表示要发送的数据长度; 对于批量读，它表示要读的数据的最大长度 * transferred - 输出参数，表示实际传输的数据长度 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 0 - 成功，根据transferred参数判断传输了多少长度的数据 * libusb_error_timeout - 超时, 根据transferred参数判断传输了多少长度的数据 * libusb_error_pipe - 端点错误，端点被挂起了 * libusb_error_overflow - 溢出，设备提供的数据太多了 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_bulk_transfer(libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); 2.8.3 中断传输
/** ingroup libusb_syncio * 启动中断传输 * 传输方向在endpoint的方向位里表示 * * 对于中断读，参数length表示期望读到的数据最大长度, 实际读到的长度保存在transferred参数里 * * 对于中断写, transferred参数表示实际发送出去的数据长度，不一定能发送完全部数据。 * * 发生超时错误时，也应该检查transferred参数。 * libusb会根据硬件的特点把数据拆分为一小段一小段地发送出去， * 这意味着发送满某段数据后可能就发生超时错误，需要根据transferred参数判断传输了多少数据。 * * 参数: * dev_handle - 设备句柄 * endpoint - 端点 * data - 保存数据的buffer, 可以是in、out数据 * length - 对于批量写，它表示要发送的数据长度; 对于批量读，它表示要读的数据的最大长度 * transferred - 输出参数，表示实际传输的数据长度 * timeout - 超时时间(单位ms)，就是这个函数能等待的最大时间; 0表示一直等待直到成功 * * 返回值: * 0 - 成功，根据transferred参数判断传输了多少长度的数据 * libusb_error_timeout - 超时, 根据transferred参数判断传输了多少长度的数据 * libusb_error_pipe - 端点错误，端点被挂起了 * libusb_error_overflow - 溢出，设备提供的数据太多了 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 如果这个函数时在事件处理上下文(event handling context)里则返回这个错误 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_interrupt_transfer(libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout); 2.9 异步传输函数
2.9.1 使用步骤
使用 libusb 的异步函数时，有如下步骤：
分配：分配一个libusb_transfer结构体
填充：填充libusb_transfer结构体，比如想访问哪个 endpoint、数据 buffer、长度等等
提交：提交libusb_transfer结构体启动传输
处理事件：检查传输的结果，调用libusb_transfer结构体的回调函数
释放：释放资源，比如释放libusb_transfer结构体
2.9.2 分配 transfer 结构体
/** ingroup libusb_asyncio * 分配一个libusb_transfer结构体， * 如果iso_packets不为0，还会分配iso_packets个libusb_iso_packet_descriptor结构体 * 使用完毕后需要调用libusb_free_transfer()函数释放掉 * * 对于控制传输、批量传输、中断传输，iso_packets参数需要设置为0 * * 对于实时传输，需要指定iso_packets参数， * 这个函数会一起分配iso_packets个libusb_iso_packet_descriptor结构体。 * 这个函数返回的libusb_transfer结构体并未初始化， * 你还需要初始化它的这些成员: * libusb_transfer::num_iso_packets * libusb_transfer::type * * 你可以指定iso_packets参数，意图给实时传输分配结构体， * 但是你可以把这个结构题用于其他类型的传输， * 在这种情况下，只要确保num_iso_packets为0就可以。 * * 参数: * iso_packets - 分配多少个isochronous packet descriptors to allocate * * 返回值: * 返回一个libusb_transfer结构体或null */default_visibilitystruct libusb_transfer * libusb_call libusb_alloc_transfer(int iso_packets); 2.9.3 填充控制传输
/** ingroup libusb_asyncio * 构造控制传输结构体 * * 如果你传入buffer参数，那么buffer的前面8字节会被当做control setup packet来解析， * buffer的最后2字节表示wlength，它也会被用来设置libusb_transfer::length * 所以，建议使用流程如下: * 1. 分配buffer，这个buffer的前面8字节对应control setup packet，后面的空间可以用来保存其他数据 * 2. 设置control setup packet，通过调用libusb_fill_control_setup()函数来设置 * 3. 如果是要把数据发送个设备，把要发送的数据放在buffer的后面(从buffer[8]开始放) * 4. 调用libusb_fill_bulk_transfer * 5. 提交传输: 调用libusb_submit_transfer() * * 也可以让buffer参数为null， * 这种情况下libusb_transfer::length就不会被设置, * 需要手工去设置ibusb_transfer::buffer、ibusb_transfer::length * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * buffer - 数据buffer，如果不是null的话，它前面8直接会被当做control setup packet来处理， * 也会从buffer[6], buffer[7]把length提取出来，用来设置libusb_transfer::length * 这个buffer必须是2字节对齐 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_control_transfer( struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.4 填充批量传输
/** ingroup libusb_asyncio * 构造批量传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.5 填充中断传输
/** ingroup libusb_asyncio * 构造中断传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_interrupt_transfer( struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.6 填充实时传输
/** ingroup libusb_asyncio * 构造实时传输结构体 * * 参数: * transfer - 要设置的libusb_transfer结构体 * dev_handle - 设备句柄 * endpoint - 端点 * buffer - 数据buffer * length - buffer的数据长度 * num_iso_packets - 实时传输包的个数 * callback - 传输完成时的回调函数 * user_data - 传给回调函数的参数 * timeout - 超时时间(单位: ms) */static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, int num_iso_packets, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout); 2.9.7 提交传输
/** ingroup libusb_asyncio * 提交传输submit，这个函数会启动传输，然后立刻返回 * * 参数: * transfer - 要传输的libusb_transfer结构体 * * 返回值: * 0 - 成功 * libusb_error_no_device - 设备未连接 * libusb_error_busy - 这个传输已经提交过了 * libusb_error_not_supported - 不支持这个传输 * libusb_error_invalid_param - 传输的字节超过os或硬件的支持 * 其他libusb_error错误码 */int api_exported libusb_submit_transfer(struct libusb_transfer *transfer); 2.9.8 处理事件
有 4 个函数，其中 2 个没有completed后缀的函数过时了：
/** ingroup libusb_poll * 处理任何pengding的事件 * * 使用异步传输函数时，提交的tranfer结构体后就返回了。 * 可以使用本函数处理这些传输的返回结果。 * * 如果timeval参数为0，本函数会处理当前、已经pending的事件，然后马上返回。 * * 如果timeval参数不为0，并且当前没有待处理的事件，本函数会阻塞以等待事件，直到超时。 * 在等待过程中，如果事件发生了、或者得到了信号(signal)，那么这个函数会提前返回。 * * completed参数用来避免竞争，如果它不为null: * 本函数获得event handling lock后，会判断completed指向的数值， * 如果这个数值非0(表示别的线程已经处理了、已经completed了)， * 则本函数会立刻返回(既然都completed了，当然无需再处理) * * 参数: * ctx - context(如果传入null则使用默认context) * tv - 等待事件的最大时间，0表示不等待 * completed - 指针，可以传入null * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_timeout_completed(libusb_context *ctx, struct timeval *tv, int *completed);/** ingroup libusb_poll * 处理任何pengding的事件 * * 跟libusb_handle_events_timeout_completed()类似, * 就是调用libusb_handle_events_timeout_completed(ctx, tv, null); * 最后的completed参数为null。 * * 这个函数只是为了保持向后兼容，新的代码建议使用libusb_handle_events_completed()或 * libusb_handle_events_timeout_completed()， * 这2个新函数可以处理竞争。 * * 参数: * ctx - context(如果传入null则使用默认context) * tv - 等待事件的最大时间，0表示不等待 * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_timeout(libusb_context *ctx,struct timeval *tv);/** ingroup libusb_poll * 处理任何pengding的事件，以阻塞方式处理(blocking mode) * * 本函数的内部实现就是调用: libusb_handle_events_timeout_completed(ctx, &tv, completed); * 超时时间设置为60秒 * * 参数: * ctx - context(如果传入null则使用默认context) * completed - 指针，可以传入null * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events_completed(libusb_context *ctx,int *completed);/** ingroup libusb_poll * 处理任何pengding的事件，以阻塞方式处理(blocking mode) * * 本函数的内部实现就是调用: libusb_handle_events_timeout_completed(ctx, &tv, null); * 超时时间设置为60秒 * * 这个函数只是为了保持向后兼容，新的代码建议使用libusb_handle_events_completed()或 * libusb_handle_events_timeout_completed()， * 这2个新函数可以处理竞争。 * * 参数: * ctx - context(如果传入null则使用默认context) * * 返回值: * 0 - 成功 * libusb_error_invalid_param - timeval参数无效 * 其他libusb_error错误码 */int api_exported libusb_handle_events(libusb_context *ctx); 2.9.9 释放 transfer 结构体
传输完毕，需要释放 libusb_transfer 结构体，如果要重复利用这个结构体则无需释放。
/** ingroup libusb_asyncio * 释放libusb_transfer结构体 * 前面使用libusb_alloc_transfer()分配的结构体，要使用本函数来释放。 * * 如果libusb_transfer::flags的libusb_transfer_free_buffer位非0， * 那么会使用free()函数释放ibusb_transfer::buffer * * 不能使用本函数释放一个活动的传输结构体(active, 已经提交尚未结束) * */void api_exported libusb_free_transfer(struct libusb_transfer *transfer); 3. 使用示例
在 libusb 源码的 examples 目录下有示例程序，我们也有一些真实的案列。
3.1 dnw 工具
dnw 是 s3c2440 时代的工具，使用它可以从 pc 给开发板传输文件。它的核心源码如下，使用同步接口进行数据传输：
/* open the device using libusb */ status = libusb_init(null); if (status < 0) { printf(libusb_init() failed: %s, libusb_error_name(status)); return -1; } hdev = libusb_open_device_with_vid_pid(null, (uint16_t)dnw_device_idvendor, (uint16_t)dnw_device_idproduct); if (hdev == null) { printf(libusb_open() failed); goto err3; } /* we need to claim the first interface */ libusb_set_auto_detach_kernel_driver(hdev, 1); status = libusb_claim_interface(hdev, 0); if (status != libusb_success) { libusb_close(hdev); printf(libusb_claim_interface failed: %s, libusb_error_name(status)); goto err2; } ret = libusb_bulk_transfer(hdev, 0x03, buf, num_write, &transferred, 3000); 3.2 openocd
openocd 是一个开源的 usb jtag 调试软件，它也是使用 libusb，涉及 usb 的操作代码如下。
3.2.1 找到设备
static int cmsis_dap_usb_open(struct cmsis_dap *dap, uint16_t vids[], uint16_t pids[], const char *serial){ int err; struct libusb_context *ctx; struct libusb_device **device_list; err = libusb_init(&ctx); if (err) { log_error(libusb initialization failed: %s, libusb_strerror(err)); return error_fail; } int num_devices = libusb_get_device_list(ctx, &device_list); if (num_devices < 0) { log_error(could not enumerate usb devices: %s, libusb_strerror(num_devices)); libusb_exit(ctx); return error_fail; } for (int i = 0; i 0) { err = libusb_get_string_descriptor_ascii( dev_handle, dev_desc.iserialnumber, (uint8_t *)dev_serial, sizeof(dev_serial)); if (err 0) { err = libusb_get_string_descriptor_ascii( dev_handle, dev_desc.iproduct, (uint8_t *)product_string, sizeof(product_string)); if (err interface[interface].altsetting[0]; int interface_num = intf_desc->binterfacenumber; /* skip this interface if another one was requested explicitly */ if (cmsis_dap_usb_interface != -1 && cmsis_dap_usb_interface != interface_num) continue; /* cmsis-dap v2 spec says: * * cmsis-dap with default v2 configuration uses winusb and is therefore faster. * optionally support for streaming swo trace is provided via an additional usb endpoint. * * the winusb configuration requires custom class support with the interface setting * class code: 0xff (vendor specific) * subclass: 0x00 * protocol code: 0x00 * * depending on the configuration it uses the following usb endpoints which should be configured * in the interface descriptor in this order: * - endpoint 1: bulk out – used for commands received from host pc. * - endpoint 2: bulk in – used for responses send to host pc. * - endpoint 3: bulk in (optional) – used for streaming swo trace (if enabled with swo_stream). */ /* search for cmsis-dap in the interface string */ bool cmsis_dap_in_interface_str = false; if (intf_desc->iinterface != 0) { char interface_str[256] = {0}; err = libusb_get_string_descriptor_ascii( dev_handle, intf_desc->iinterface, (uint8_t *)interface_str, sizeof(interface_str)); if (err iinterface, dev_desc.idvendor, dev_desc.idproduct, libusb_strerror(err)); } else if (strstr(interface_str, cmsis-dap)) { cmsis_dap_in_interface_str = true; log_debug(found interface %d string '%s', interface_num, interface_str); } } /* bypass the following check if this interface was explicitly requested. */ if (cmsis_dap_usb_interface == -1) { if (!cmsis_dap_in_product_str && !cmsis_dap_in_interface_str) continue; } /* check endpoints */ if (intf_desc->bnumendpoints bnumendpoints); continue; } if ((intf_desc->endpoint[0].bmattributes & 3) != libusb_transfer_type_bulk || (intf_desc->endpoint[0].bendpointaddress & 0x80) != libusb_endpoint_out) { log_debug(skipping interface %d, endpoint[0] is not bulk out, interface_num); continue; } if ((intf_desc->endpoint[1].bmattributes & 3) != libusb_transfer_type_bulk || (intf_desc->endpoint[1].bendpointaddress & 0x80) != libusb_endpoint_in) { log_debug(skipping interface %d, endpoint[1] is not bulk in, interface_num); continue; } /* we can rely on the interface is really cmsis-dap if * - we've seen cmsis-dap in the interface string * - config asked explicitly for an interface number * - the device has only one interface * the later two cases should be honored only if we know * we are on the right device */ bool intf_identified_reliably = cmsis_dap_in_interface_str || (device_identified_reliably && (cmsis_dap_usb_interface != -1 || config_desc->bnuminterfaces == 1)); if (intf_desc->binterfaceclass != libusb_class_vendor_spec || intf_desc->binterfacesubclass != 0 || intf_desc->binterfaceprotocol != 0) { /* if the interface is reliably identified * then we need not insist on setting usb class, subclass and protocol * exactly as the specification requires. * at least kitprog3 uses class 0 contrary to the specification */ if (intf_identified_reliably) { log_warning(using cmsis-dapv2 interface %d with wrong class % prid8 subclass % prid8 or protocol % prid8, interface_num, intf_desc->binterfaceclass, intf_desc->binterfacesubclass, intf_desc->binterfaceprotocol); } else { log_debug(skipping interface %d, class % prid8 subclass % prid8 protocol % prid8, interface_num, intf_desc->binterfaceclass, intf_desc->binterfacesubclass, intf_desc->binterfaceprotocol); continue; } } if (intf_identified_reliably) { /* that's the one! */ intf_desc_found = intf_desc; break; } if (!intf_desc_candidate && device_identified_reliably) { /* this interface looks suitable for cmsis-dap. store the pointer to it * and keep searching for another one with cmsis-dap in interface string */ intf_desc_candidate = intf_desc; } } if (!intf_desc_found) { /* we were not able to identify reliably which interface is cmsis-dap. * let's use the first suitable if we found one */ intf_desc_found = intf_desc_candidate; } if (!intf_desc_found) { libusb_free_config_descriptor(config_desc); continue; } /* we've chosen an interface, connect to it */ int interface_num = intf_desc_found->binterfacenumber; int packet_size = intf_desc_found->endpoint[0].wmaxpacketsize; int ep_out = intf_desc_found->endpoint[0].bendpointaddress; int ep_in = intf_desc_found->endpoint[1].bendpointaddress; libusb_free_config_descriptor(config_desc); libusb_free_device_list(device_list, true); log_info(using cmsis-dapv2 interface with vid:pid=0x%04x:0x%04x, serial=%s, dev_desc.idvendor, dev_desc.idproduct, dev_serial); int current_config; err = libusb_get_configuration(dev_handle, ¤t_config); if (err) { log_error(could not find current configuration: %s, libusb_strerror(err)); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } if (config_num != current_config) { err = libusb_set_configuration(dev_handle, config_num); if (err) { log_error(could not set configuration: %s, libusb_strerror(err)); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } } err = libusb_claim_interface(dev_handle, interface_num); if (err) log_warning(could not claim interface: %s, libusb_strerror(err)); dap->bdata = malloc(sizeof(struct cmsis_dap_backend_data)); if (!dap->bdata) { log_error(unable to allocate memory); libusb_release_interface(dev_handle, interface_num); libusb_close(dev_handle); libusb_exit(ctx); return error_fail; } dap->packet_size = packet_size; dap->packet_buffer_size = packet_size; dap->bdata->usb_ctx = ctx; dap->bdata->dev_handle = dev_handle; dap->bdata->ep_out = ep_out; dap->bdata->ep_in = ep_in; dap->bdata->interface = interface_num; dap->packet_buffer = malloc(dap->packet_buffer_size); if (!dap->packet_buffer) { log_error(unable to allocate memory); cmsis_dap_usb_close(dap); return error_fail; } dap->command = dap->packet_buffer; dap->response = dap->packet_buffer; return error_ok; } libusb_close(dev_handle); } libusb_free_device_list(device_list, true); libusb_exit(ctx); return error_fail;} 3.2.2 读写数据
OpenHarmony竞赛训练营（第一期）决赛入围名单公示
RF-35TACONICmaterial的性能及应用简介
详谈RFID的市场应用及发展前景
新能源汽车规划明年3月出台
华为将于12月21日发布智慧屏S系列新品：搭载鸿蒙OS系统
libusb的用法和使用步骤
Verilog HDL中定义的26个有关门级的关键字中常用的有哪些？
腾讯首次攻破超声波屏下指纹识别技术
频谱分析仪68169B_40G维修无法开机案例
Redmi K20 PRO首发体验Android Q系统
压敏电阻构成的LED驱动电路
征信机构不得过度采集信用信息
74hc138能锁存吗 74hc138功能详解
MF52型热敏电阻
比特币的“去中心化”是否彻底？什么是BGP劫持呢？
如何利用Silent Switcher 2稳压器来满足汽车制造商的EMI要求
览邦WACH MAX-A90智能手表，经典设计焕发现代魅力，硬核性能，集运动健康娱乐于一表
耳机放大器中的噪音抑制详解
英伟达「黄氏定律」让未来的AI算力每年能够提升一倍
清问一下PE和GND到底该怎么联呢？