1. 概述

1.1 介紹

libusb 是一個使用 C 編寫的庫，它提供 USB 設(shè)備的通用的訪問方法。APP 通過它，可以方便地訪問 USB 設(shè)備，無需編寫 USB 設(shè)備驅(qū)動程序。

可移植性：支持 Linux、macOS、Windows、Android、OpenBSD 等

用戶模式：APP 不需要特權(quán)模式、也不需要提升自己的權(quán)限即可訪問 USB 設(shè)備

支持所有 USB 協(xié)議：從 1.0 到 3.1 都支持

libusb 支持所有的傳輸類型(控制/批量/中斷/實時)，有兩類 API 接口：同步(Synchronous，簡單)，異步(Asynchronous，復(fù)雜但是更強大)。

它是輕量級的、線程安全的。還支持熱拔插。

1.2 用法

可以通過 libusb 訪問 USB 設(shè)備，不需要 USB 設(shè)備端的驅(qū)動程序，需要移除原來的驅(qū)動程序。然后就可以直接訪問 USB 控制器的驅(qū)動程序，使用 open/read/write/ioctl/close 這些接口來打開設(shè)備、收發(fā)數(shù)據(jù)、關(guān)閉設(shè)備。

libusb 封裝了更好用的函數(shù)，這些函數(shù)的使用可以分為 5 個步驟：

初始化

打開設(shè)備

移除原驅(qū)動/認(rèn)領(lǐng)接口

傳輸

關(guān)閉設(shè)備

2. API 接口

2.1 分類

libusb 的接口函數(shù)分為兩類：同步(Synchronous device I/O)、異步(Asynchronous device I/O)。

USB 數(shù)據(jù)傳輸分為兩個步驟，對于讀數(shù)據(jù)，先給設(shè)備發(fā)出數(shù)據(jù)的請求，一段時間后數(shù)據(jù)返回；對于寫數(shù)據(jù)，先發(fā)送數(shù)據(jù)給設(shè)備，一段時間后得到回應(yīng)。

同步接口的核心在于把上述兩個步驟放在一個函數(shù)里面。比如想去讀取一個 USB 鍵盤的數(shù)據(jù)，給鍵盤發(fā)出讀請求后，如果用戶一直沒有按下鍵盤，那么讀函數(shù)會一直等待。

異步接口的核心在于把上述兩個步驟分開：使用一個非阻塞的函數(shù)啟動傳輸，它會立刻返回；提供一個回調(diào)函數(shù)用來處理返回結(jié)果。

同步接口的示例代碼如下，在libusb_bulk_transfer函數(shù)內(nèi)部，如果沒有數(shù)據(jù)則會休眠：

unsignedchardata[4];
intactual_length;
intr=libusb_bulk_transfer(dev_handle,LIBUSB_ENDPOINT_IN,data,sizeof(data),&actual_length,0);
if(r==0&&actual_length==sizeof(data)){
//接收到的數(shù)據(jù)保存在data數(shù)組里
//解析這些數(shù)據(jù)就可以知道按鍵狀態(tài)
}else{
error();
}使用同步接口時，代碼比較簡單。但是無法實現(xiàn)"多 endpoint"的操作：上一個 endpoint 的傳輸在休眠，除非使用另一個線程，否則在同一個線程內(nèi)部在等待期間是無法操作另一個 endpoint 的。還有另一個缺點：無法取消傳輸。

異步接口是在 libusb-1.0 引入的新性能，接口更復(fù)雜，但是功能更強大。在異步接口函數(shù)里，它啟動傳輸、設(shè)置回調(diào)函數(shù)后就立刻返回。等"讀到數(shù)據(jù)"或是"得到回應(yīng)"后，回調(diào)函數(shù)被調(diào)用。發(fā)起數(shù)據(jù)傳輸?shù)木€程無需休眠等待結(jié)果，它支持"多endpoint"的操作，也支持取消傳輸。

2.2 初始化/反初始化

/**ingrouplibusb_lib
*初始化libusb，這個函數(shù)必須先于其他libusb的函數(shù)執(zhí)行
*
*如果傳入NULL，那么函數(shù)內(nèi)部會穿件一個默認(rèn)的context
*如果已經(jīng)創(chuàng)建過默認(rèn)的context，這個context會被重新使用(不會重新初始化它)
*
*參數(shù)：
*ctx:contextpointer的位置，也可以傳入NULL
*返回值
*0-成功
*負(fù)數(shù)-失敗
*/
intAPI_EXPORTEDlibusb_init(libusb_context**ctx);

初始化 libusb，參數(shù)是一個"a context pointer"的指針，如果這個參數(shù)為 NULL，則函數(shù)內(nèi)部會創(chuàng)建一個"default context"。所謂"libusb context"就是 libusb 上下文，就是一個結(jié)構(gòu)體，里面保存有各類信息，比如：libusb 的調(diào)試信息是否需要打印、各種互斥鎖、各類鏈表(用來記錄USB傳輸?shù)鹊?。

程序退出前，調(diào)用如下函數(shù)：

/**ingrouplibusb_lib
*發(fā)初始化libusb
*在關(guān)閉usb設(shè)備(libusb_close)后、退出程序前調(diào)用此函數(shù)
*
*參數(shù):
*ctx:context,傳入NULL表示defaultcontext
*/
voidAPI_EXPORTEDlibusb_exit(libusb_context*ctx);

2.3 獲取設(shè)備

可以使用libusb_get_device_list取出所有設(shè)備，函數(shù)接口如下：

/**@ingrouplibusb_dev
*返回一個list，list里含有當(dāng)前系統(tǒng)中所有的USB設(shè)備
*
*我們一般會在list里尋找需要訪問的設(shè)備，找到之后使用libusb_open函數(shù)打開它
*然后調(diào)用libusb_free_device_list釋放list
*
*這個函數(shù)的返回值表示list中有多少個設(shè)備
*list的最后一項是NULL
*
*參數(shù):
*ctx:context
*list:outputlocationforalistofdevices,最后必須調(diào)用libusb_free_device_list()來釋放它
*返回值:list中設(shè)備的個數(shù),或錯誤值
*/
ssize_tAPI_EXPORTEDlibusb_get_device_list(libusb_context*ctx,libusb_device***list);

調(diào)用此函數(shù)后，所有設(shè)備的信息存入 list，然后遍歷 list，找到想操作的設(shè)備。這個函數(shù)內(nèi)部會分配 list 的空間，所以用完后要釋放掉，使用以下函數(shù)釋放：

/**ingrouplibusb_dev
*前面使用libusb_get_device_list()獲得了設(shè)備list,
*使用完后要調(diào)用libusb_free_device_list()釋放這個list
*如果參數(shù)unref_devices為1,則list中每個設(shè)備的引用計數(shù)值減小1
*參數(shù):
*list:要釋放的設(shè)備list
*unref_devices:是否要將設(shè)備的引用計數(shù)減1
*/
voidAPI_EXPORTEDlibusb_free_device_list(libusb_device**list,intunref_devices);

2.4 打開/關(guān)閉設(shè)備

使用 libusb_get_device_list 得到設(shè)備列表后，可以選擇里面的某個設(shè)備，然后調(diào)用 libusb_open：

/**ingrouplibusb_dev
*打開一個設(shè)備并得到它的句柄,以后進行IO操作時都是使用句柄
*
*使用libusb_get_device()函數(shù)可以得到設(shè)備的list,
*從list里確定你要訪問的設(shè)備后, 使用libusb_open()去打開它。
* libusb_open()函數(shù)內(nèi)部會增加此設(shè)備的引用計數(shù), 使用完畢后要調(diào)用libusb_close()減小引用計數(shù)。
*
*參數(shù):
*dev:要打開的設(shè)備
*dev_handle:輸出參數(shù),用來保存句柄
*返回值:
*0-成功
*LIBUSB_ERROR_NO_MEM:缺少內(nèi)存
*LIBUSB_ERROR_ACCESS:權(quán)限不足
*LIBUSB_ERROR_NO_DEVICE:這個設(shè)備未連接
*其他錯誤:其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_open(libusb_device*dev,libusb_device_handle**dev_handle);

使用 libusb_open 函數(shù)打開 USB 設(shè)備后，可以得到一個句柄：libusb_device_handle。以后調(diào)用各種數(shù)據(jù)傳輸函數(shù)時，就是使用libusb_device_handle。

使用完畢后，調(diào)用 libusb_close 關(guān)閉設(shè)備，函數(shù)原型如下：

/**ingrouplibusb_dev
*關(guān)閉設(shè)備句柄,在程序退出之前應(yīng)該使用它去關(guān)閉已經(jīng)打開的句柄
*
*設(shè)備的引用計數(shù)在前面被libusb_open()函數(shù)增加了。
*在libusb_close()函數(shù)的內(nèi)部，它會減小設(shè)備的引用計數(shù)。
*
*參數(shù):dev_handle-句柄
*/
voidAPI_EXPORTEDlibusb_close(libusb_device_handle*dev_handle);

2.5 根據(jù) ID 打開設(shè)備

如果知道設(shè)備的 VID、PID，那么可以使用 libusb_open_device_with_vid_pid 來找到它、打開它。這個函數(shù)的內(nèi)部，先使用libusb_get_device_list列出所有設(shè)備，然后遍歷它們根據(jù) ID 選出設(shè)備，接著調(diào)用 libusb_open 打開它，最后調(diào)用 libusb_free_device_list 釋放設(shè)備。

libusb_open_device_with_vid_pid 函數(shù)原型如下：

/**ingrouplibusb_dev
*打開設(shè)備的常規(guī)做法是使用libusb_get_device_list()得到設(shè)備list，
*然后遍歷list，找到設(shè)備
*接著使用libusb_open()函數(shù)得到句柄
*
*如果知道USB設(shè)備的VID、PID，那么可以使用libusb_open_device_with_vid_pid()函數(shù)快速打開它，得到句柄。
*
*這個函數(shù)有一個缺點:如果系統(tǒng)中有多個ID相同的設(shè)備，你只能打開第1個設(shè)備
*
*參數(shù):
*ctx:context,或者傳入NULL以使用默認(rèn)的context
*vendor_id:廠家ID
*product_id:產(chǎn)品ID
*
*返回值:
*句柄-找到的第1個設(shè)備的句柄
*NULL-沒有找到設(shè)備
*/
DEFAULT_VISIBILITY
libusb_device_handle*LIBUSB_CALLlibusb_open_device_with_vid_pid(
libusb_context*ctx,uint16_tvendor_id,uint16_tproduct_id);

2.6 描述符相關(guān)函數(shù)

2.6.1 獲得設(shè)備描述符

/**ingrouplibusb_desc
*獲得設(shè)備描述符
*
*參數(shù):
*dev-哪個設(shè)備
*desc-輸出參數(shù),用來保存設(shè)備描述符
*
*返回值:
*0-成功,或其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_get_device_descriptor(libusb_device*dev,
structlibusb_device_descriptor*desc);

2.6.2 獲得/釋放配置描述符

/**ingrouplibusb_desc
*獲得指定的配置描述符
*
*參數(shù):
*dev-哪個設(shè)備
*config_index-哪個配置
*config-輸出參數(shù),用來保存配置描述符,使用完畢要調(diào)用libusb_free_config_descriptor()釋放掉
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-沒有這個配置
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_get_config_descriptor(libusb_device*dev,
uint8_tconfig_index,structlibusb_config_descriptor**config);

/**ingrouplibusb_desc
*Freeaconfigurationdescriptorobtainedfrom
*前面使用libusb_get_active_config_descriptor()或libusb_get_config_descriptor()獲得配置描述符，
*用完后調(diào)用libusb_free_config_descriptor()釋放掉
*/
voidAPI_EXPORTEDlibusb_free_config_descriptor(
structlibusb_config_descriptor*config);

2.7 detach/attach 驅(qū)動

2.7.1 兩種方法

使用 libusb 訪問 USB 設(shè)備時，需要先移除(detach)設(shè)備原來的驅(qū)動程序，然后認(rèn)領(lǐng)接口(claim interface)。有兩種辦法：

方法1：

//只是設(shè)置一個標(biāo)記位表示libusb_claim_interface
//使用libusb_claim_interface時會detach原來的驅(qū)動
libusb_set_auto_detach_kernel_driver(hdev,1);

//標(biāo)記這個interface已經(jīng)被使用認(rèn)領(lǐng)了
libusb_claim_interface(hdev,interface_number);

方法2：

//detach原來的驅(qū)動
libusb_detach_kernel_driver(hdev,interface_number);

//標(biāo)記這個interface已經(jīng)被使用認(rèn)領(lǐng)了
libusb_claim_interface(hdev,interface_number);

2.7.2 函數(shù)原型

函數(shù)libusb_detach_kernel_driver原型如下：

/**ingrouplibusb_dev
*給USB設(shè)備的接口(interface)移除驅(qū)動程序.Ifsuccessful,youwillthenbe
*移除原來的驅(qū)動后才能"claimtheinterface"、執(zhí)行IO操作
*
*實際上libusb會給這個接口安裝一個特殊的內(nèi)核驅(qū)動,
*所以本函數(shù)"移除驅(qū)動"是移除其他驅(qū)動，不是移除這個特殊的驅(qū)動。
*若干這個接口已經(jīng)安裝了這個特殊的驅(qū)動，本函數(shù)會返回LIBUSB_ERROR_NOT_FOUND.
*
*參數(shù):
*dev_handle-設(shè)備句柄
*interface_number-哪一個接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-這個接口沒有安裝其他驅(qū)動
*LIBUSB_ERROR_INVALID_PARAM-沒有這個接口
*LIBUSB_ERROR_NO_DEVICE-這個設(shè)備未連接
*LIBUSB_ERROR_NOT_SUPPORTED-系統(tǒng)不支持此操作,比如Windows
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_detach_kernel_driver(libusb_device_handle*dev_handle,intinterface_number);

函數(shù)libusb_claim_interface原型如下：

/**ingrouplibusb_dev
*libusb使用內(nèi)核里一個特殊的驅(qū)動程序，
*libusb_claim_interface()函數(shù)就是給某個usb接口安裝這個特殊的驅(qū)動程序，
*在使用libusb的函數(shù)執(zhí)行IO操作之前必須調(diào)用本函數(shù)。
*
*你可以給"已經(jīng)claim過的接口"再次調(diào)用本函數(shù)，它直接返回0。
*
*如果這個接口的auto_detach_kernel_driver被設(shè)置為1，
* libusb_claim_interface()函數(shù)會先移除其他驅(qū)動。
*
*本函數(shù)時純粹的邏輯操作：只是替換接口的驅(qū)動程序而已，不會導(dǎo)致USB硬件傳輸。
*
*參數(shù):
*dev_handle-句柄,表示USB設(shè)備
*interface_number-接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-沒有這個接口
*LIBUSB_ERROR_BUSY-其他APP或者驅(qū)動正在使用這個接口
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_claim_interface(libusb_device_handle*dev_handle,intinterface_number);

使用完 USB 設(shè)備后，在調(diào)用 libusb_close 之前，應(yīng)該libusb_release_interface釋放接口：

/**ingrouplibusb_dev
*前面使用libusb_claim_interface()給接口安裝了給libusb使用的特殊驅(qū)動程序,
*使用完畢后，在調(diào)用libusb_close()關(guān)閉句柄之前，
*可以調(diào)用libusb_release_interface()卸載特殊驅(qū)動程序
*如果設(shè)備的auto_detach_kernel_driver為1，還會重新安裝普通驅(qū)動程序
*
*這是一個阻塞函數(shù),它會給USB設(shè)備發(fā)送一個請求:SET_INTERFACEcontrol,
*用來把接口的狀態(tài)復(fù)位到第1個setting(thefirstalternatesetting)
*
*參數(shù):
*dev_handle-設(shè)備句柄
*interface_number-哪個接口
*
*返回值:
*0-成功
*LIBUSB_ERROR_NOT_FOUND-這個接口沒有被claim(沒有安裝特殊的驅(qū)動程序)
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_release_interface(libusb_device_handle*dev_handle,intinterface_number);

2.8 同步傳輸函數(shù)

2.8.1 控制傳輸

/**ingrouplibusb_syncio
*啟動控制傳輸
*
*傳輸方向在bmRequestType里
*wValue,wIndex和wLength是host-endian字節(jié)序
*
*參數(shù):
*dev_handle-設(shè)備句柄
*bmRequestType-setup數(shù)據(jù)包的bmRequestType域
*bRequest-setup數(shù)據(jù)包的bRequest域
*wValue-setup數(shù)據(jù)包的wValue域
*wIndex-setup數(shù)據(jù)包的wIndex域
*data-保存數(shù)據(jù)的buffer,可以是in、out數(shù)據(jù)
*wLength-setup數(shù)據(jù)包的wLength域
*timeout-超時時間(單位ms)，就是這個函數(shù)能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*正整數(shù)-成功傳輸?shù)臄?shù)據(jù)的長度
*LIBUSB_ERROR_TIMEOUT-超時
*LIBUSB_ERROR_PIPE-設(shè)備不支持該請求
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*LIBUSB_ERROR_BUSY-如果這個函數(shù)時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸?shù)淖止?jié)超過OS或硬件的支持
*theoperatingsystemand/orhardwarecansupport(see
efasynclimits)
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_control_transfer(libusb_device_handle*dev_handle,
uint8_tbmRequestType,uint8_tbRequest,uint16_twValue,uint16_twIndex,
unsignedchar*data,uint16_twLength,unsignedinttimeout);

2.8.2 批量傳輸

/**ingrouplibusb_syncio
*啟動批量傳輸
*傳輸方向在endpoint的"方向位"里表示
*
*對于批量讀，參數(shù)length表示"期望讀到的數(shù)據(jù)最大長度",實際讀到的長度保存在transferred參數(shù)里
*
*對于批量寫,transferred參數(shù)表示實際發(fā)送出去的數(shù)據(jù)長度
*
*發(fā)生超時錯誤時，也應(yīng)該檢查transferred參數(shù)。
*libusb會根據(jù)硬件的特點把數(shù)據(jù)拆分為一小段一小段地發(fā)送出去，
*這意味著發(fā)送滿某段數(shù)據(jù)后可能就發(fā)生超時錯誤，需要根據(jù)transferred參數(shù)判斷傳輸了多少數(shù)據(jù)。
*
*參數(shù):
*dev_handle-設(shè)備句柄
*endpoint-端點
*data-保存數(shù)據(jù)的buffer,可以是in、out數(shù)據(jù)
*length-對于批量寫，它表示要發(fā)送的數(shù)據(jù)長度;對于批量讀，它表示"要讀的數(shù)據(jù)的最大長度"
*transferred-輸出參數(shù)，表示實際傳輸?shù)臄?shù)據(jù)長度
*timeout-超時時間(單位ms)，就是這個函數(shù)能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*0-成功，根據(jù)transferred參數(shù)判斷傳輸了多少長度的數(shù)據(jù)
*LIBUSB_ERROR_TIMEOUT-超時,根據(jù)transferred參數(shù)判斷傳輸了多少長度的數(shù)據(jù)
*LIBUSB_ERROR_PIPE-端點錯誤，端點被掛起了
*LIBUSB_ERROR_OVERFLOW-溢出，設(shè)備提供的數(shù)據(jù)太多了
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*LIBUSB_ERROR_BUSY-如果這個函數(shù)時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸?shù)淖止?jié)超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_bulk_transfer(libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*data,intlength,
int*transferred,unsignedinttimeout);

2.8.3 中斷傳輸

/**ingrouplibusb_syncio
*啟動中斷傳輸
*傳輸方向在endpoint的"方向位"里表示
*
*對于中斷讀，參數(shù)length表示"期望讀到的數(shù)據(jù)最大長度",實際讀到的長度保存在transferred參數(shù)里
*
*對于中斷寫, transferred參數(shù)表示實際發(fā)送出去的數(shù)據(jù)長度，不一定能發(fā)送完全部數(shù)據(jù)。
*
*發(fā)生超時錯誤時，也應(yīng)該檢查transferred參數(shù)。
*libusb會根據(jù)硬件的特點把數(shù)據(jù)拆分為一小段一小段地發(fā)送出去，
*這意味著發(fā)送滿某段數(shù)據(jù)后可能就發(fā)生超時錯誤，需要根據(jù)transferred參數(shù)判斷傳輸了多少數(shù)據(jù)。
*
*參數(shù):
*dev_handle-設(shè)備句柄
*endpoint-端點
*data-保存數(shù)據(jù)的buffer,可以是in、out數(shù)據(jù)
*length-對于批量寫，它表示要發(fā)送的數(shù)據(jù)長度;對于批量讀，它表示"要讀的數(shù)據(jù)的最大長度"
*transferred-輸出參數(shù)，表示實際傳輸?shù)臄?shù)據(jù)長度
*timeout-超時時間(單位ms)，就是這個函數(shù)能等待的最大時間;0表示一直等待直到成功
*
*返回值:
*0-成功，根據(jù)transferred參數(shù)判斷傳輸了多少長度的數(shù)據(jù)
*LIBUSB_ERROR_TIMEOUT-超時,根據(jù)transferred參數(shù)判斷傳輸了多少長度的數(shù)據(jù)
*LIBUSB_ERROR_PIPE-端點錯誤，端點被掛起了
*LIBUSB_ERROR_OVERFLOW-溢出，設(shè)備提供的數(shù)據(jù)太多了
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*LIBUSB_ERROR_BUSY-如果這個函數(shù)時在事件處理上下文(eventhandlingcontext)里則返回這個錯誤
*LIBUSB_ERROR_INVALID_PARAM-傳輸?shù)淖止?jié)超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_interrupt_transfer(libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*data,intlength,
int*transferred,unsignedinttimeout);

2.9 異步傳輸函數(shù)

2.9.1 使用步驟

使用 libusb 的異步函數(shù)時，有如下步驟：

分配：分配一個libusb_transfer結(jié)構(gòu)體

填充：填充libusb_transfer結(jié)構(gòu)體，比如想訪問哪個 endpoint、數(shù)據(jù) buffer、長度等等

提交：提交libusb_transfer結(jié)構(gòu)體啟動傳輸

處理事件：檢查傳輸?shù)慕Y(jié)果，調(diào)用libusb_transfer結(jié)構(gòu)體的回調(diào)函數(shù)

釋放：釋放資源，比如釋放libusb_transfer結(jié)構(gòu)體

2.9.2 分配 transfer 結(jié)構(gòu)體

/**ingrouplibusb_asyncio
*分配一個libusb_transfer結(jié)構(gòu)體，
*如果iso_packets不為0，還會分配iso_packets個libusb_iso_packet_descriptor結(jié)構(gòu)體
*使用完畢后需要調(diào)用libusb_free_transfer()函數(shù)釋放掉
*
*對于控制傳輸、批量傳輸、中斷傳輸，iso_packets參數(shù)需要設(shè)置為0
*
*對于實時傳輸，需要指定iso_packets參數(shù)，
*這個函數(shù)會一起分配iso_packets個libusb_iso_packet_descriptor結(jié)構(gòu)體。
*這個函數(shù)返回的libusb_transfer結(jié)構(gòu)體并未初始化，
*你還需要初始化它的這些成員:
*libusb_transfer::num_iso_packets
*libusb_transfer::type
*
*你可以指定iso_packets參數(shù)，意圖給實時傳輸分配結(jié)構(gòu)體，
*但是你可以把這個結(jié)構(gòu)題用于其他類型的傳輸，
*在這種情況下，只要確保num_iso_packets為0就可以。
*
*參數(shù):
*iso_packets-分配多少個isochronouspacketdescriptorstoallocate
*
*返回值:
*返回一個libusb_transfer結(jié)構(gòu)體或NULL
*/
DEFAULT_VISIBILITY
structlibusb_transfer*LIBUSB_CALLlibusb_alloc_transfer(intiso_packets);

2.9.3 填充控制傳輸

/**ingrouplibusb_asyncio
*構(gòu)造控制傳輸結(jié)構(gòu)體
*
*如果你傳入buffer參數(shù)，那么buffer的前面8字節(jié)會被當(dāng)做"controlsetuppacket"來解析，
*buffer的最后2字節(jié)表示wLength，它也會被用來設(shè)置libusb_transfer::length
*所以，建議使用流程如下:
*1.分配buffer，這個buffer的前面8字節(jié)對應(yīng)"controlsetuppacket"，后面的空間可以用來保存其他數(shù)據(jù)
*2.設(shè)置"controlsetuppacket"，通過調(diào)用libusb_fill_control_setup()函數(shù)來設(shè)置
*3.如果是要把數(shù)據(jù)發(fā)送個設(shè)備，把要發(fā)送的數(shù)據(jù)放在buffer的后面(從buffer[8]開始放)
*4.調(diào)用libusb_fill_bulk_transfer
*5.提交傳輸:調(diào)用libusb_submit_transfer()
*
*也可以讓buffer參數(shù)為NULL，
*這種情況下libusb_transfer::length就不會被設(shè)置,
*需要手工去設(shè)置ibusb_transfer::buffer、ibusb_transfer::length
*
*參數(shù):
*transfer-要設(shè)置的libusb_transfer結(jié)構(gòu)體
*dev_handle-設(shè)備句柄
*buffer-數(shù)據(jù)buffer，如果不是NULL的話，它前面8直接會被當(dāng)做"controlsetuppacket"來處理，
*也會從buffer[6],buffer[7]把length提取出來，用來設(shè)置libusb_transfer::length
*這個buffer必須是2字節(jié)對齊
*callback-傳輸完成時的回調(diào)函數(shù)
*user_data-傳給回調(diào)函數(shù)的參數(shù)
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_control_transfer(
structlibusb_transfer*transfer,libusb_device_handle*dev_handle,
unsignedchar*buffer,libusb_transfer_cb_fncallback,void*user_data,
unsignedinttimeout);

2.9.4 填充批量傳輸

/**ingrouplibusb_asyncio
*構(gòu)造批量傳輸結(jié)構(gòu)體
*
*參數(shù):
*transfer-要設(shè)置的libusb_transfer結(jié)構(gòu)體
*dev_handle-設(shè)備句柄
*endpoint-端點
*buffer-數(shù)據(jù)buffer
*length-buffer的數(shù)據(jù)長度
*callback-傳輸完成時的回調(diào)函數(shù)
*user_data-傳給回調(diào)函數(shù)的參數(shù)
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_bulk_transfer(structlibusb_transfer*transfer,
libusb_device_handle*dev_handle,unsignedcharendpoint,
unsignedchar*buffer,intlength,libusb_transfer_cb_fncallback,
void*user_data,unsignedinttimeout);

2.9.5 填充中斷傳輸

/**ingrouplibusb_asyncio
*構(gòu)造中斷傳輸結(jié)構(gòu)體
*
*參數(shù):
*transfer-要設(shè)置的libusb_transfer結(jié)構(gòu)體
*dev_handle-設(shè)備句柄
*endpoint-端點
*buffer-數(shù)據(jù)buffer
*length-buffer的數(shù)據(jù)長度
*callback-傳輸完成時的回調(diào)函數(shù)
*user_data-傳給回調(diào)函數(shù)的參數(shù)
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_interrupt_transfer(
structlibusb_transfer*transfer,libusb_device_handle*dev_handle,
unsignedcharendpoint,unsignedchar*buffer,intlength,
libusb_transfer_cb_fncallback,void*user_data,unsignedinttimeout);

2.9.6 填充實時傳輸

/**ingrouplibusb_asyncio
*構(gòu)造實時傳輸結(jié)構(gòu)體
*
*參數(shù):
*transfer-要設(shè)置的libusb_transfer結(jié)構(gòu)體
*dev_handle-設(shè)備句柄
*endpoint-端點
*buffer-數(shù)據(jù)buffer
*length-buffer的數(shù)據(jù)長度
*num_iso_packets-實時傳輸包的個數(shù)
*callback-傳輸完成時的回調(diào)函數(shù)
*user_data-傳給回調(diào)函數(shù)的參數(shù)
*timeout-超時時間(單位:ms)
*/
staticinlinevoidlibusb_fill_iso_transfer(structlibusb_transfer*transfer,
libusb_device_handle*dev_handle,unsignedcharendpoint,
unsignedchar*buffer,intlength,intnum_iso_packets,
libusb_transfer_cb_fncallback,void*user_data,unsignedinttimeout);

2.9.7 提交傳輸

/**ingrouplibusb_asyncio
*提交傳輸Submit，這個函數(shù)會啟動傳輸，然后立刻返回
*
*參數(shù):
*transfer-要傳輸?shù)膌ibusb_transfer結(jié)構(gòu)體
*
*返回值:
*0-成功
*LIBUSB_ERROR_NO_DEVICE-設(shè)備未連接
*LIBUSB_ERROR_BUSY-這個傳輸已經(jīng)提交過了
*LIBUSB_ERROR_NOT_SUPPORTED-不支持這個傳輸
*LIBUSB_ERROR_INVALID_PARAM-傳輸?shù)淖止?jié)超過OS或硬件的支持
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_submit_transfer(structlibusb_transfer*transfer);

2.9.8 處理事件

有 4 個函數(shù)，其中 2 個沒有completed后綴的函數(shù)過時了：

/**ingrouplibusb_poll
*處理任何"pengding的事件"
*
*使用異步傳輸函數(shù)時，提交的tranfer結(jié)構(gòu)體后就返回了。
*可以使用本函數(shù)處理這些傳輸?shù)姆祷亟Y(jié)果。
*
*如果timeval參數(shù)為0，本函數(shù)會處理"當(dāng)前、已經(jīng)pending的事件"，然后馬上返回。
*
*如果timeval參數(shù)不為0，并且當(dāng)前沒有待處理的事件，本函數(shù)會阻塞以等待事件，直到超時。
*在等待過程中，如果事件發(fā)生了、或者得到了信號(signal)，那么這個函數(shù)會提前返回。
*
*completed參數(shù)用來避免競爭，如果它不為NULL:
*本函數(shù)獲得"eventhandlinglock"后，會判斷completed指向的數(shù)值，
*如果這個數(shù)值非0(表示別的線程已經(jīng)處理了、已經(jīng)completed了)，
*則本函數(shù)會立刻返回(既然都completed了，當(dāng)然無需再處理)
*
*參數(shù):
*ctx-context(如果傳入NULL則使用默認(rèn)context)
*tv-等待事件的最大時間，0表示不等待
*completed-指針，可以傳入NULL
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數(shù)無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_timeout_completed(libusb_context*ctx,
structtimeval*tv,int*completed);

/**ingrouplibusb_poll
*處理任何"pengding的事件"
*
*跟libusb_handle_events_timeout_completed()類似,
*就是調(diào)用"libusb_handle_events_timeout_completed(ctx,tv,NULL);"
*最后的completed參數(shù)為NULL。
*
*這個函數(shù)只是為了保持向后兼容，新的代碼建議使用libusb_handle_events_completed()或
*libusb_handle_events_timeout_completed()，
*這2個新函數(shù)可以處理競爭。
*
*參數(shù):
*ctx-context(如果傳入NULL則使用默認(rèn)context)
*tv-等待事件的最大時間，0表示不等待
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數(shù)無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_timeout(libusb_context*ctx,structtimeval*tv);

/**ingrouplibusb_poll
*處理任何"pengding的事件"，以阻塞方式處理(blockingmode)
*
*本函數(shù)的內(nèi)部實現(xiàn)就是調(diào)用:libusb_handle_events_timeout_completed(ctx,&tv,completed);
*超時時間設(shè)置為60秒
*
*參數(shù):
*ctx-context(如果傳入NULL則使用默認(rèn)context)
*completed-指針，可以傳入NULL
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數(shù)無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events_completed(libusb_context*ctx,int*completed);

/**ingrouplibusb_poll
*處理任何"pengding的事件"，以阻塞方式處理(blockingmode)
*
*本函數(shù)的內(nèi)部實現(xiàn)就是調(diào)用:libusb_handle_events_timeout_completed(ctx,&tv,NULL);
*超時時間設(shè)置為60秒
*
*這個函數(shù)只是為了保持向后兼容，新的代碼建議使用libusb_handle_events_completed()或
*libusb_handle_events_timeout_completed()，
*這2個新函數(shù)可以處理競爭。
*
*參數(shù):
*ctx-context(如果傳入NULL則使用默認(rèn)context)
*
*返回值:
*0-成功
*LIBUSB_ERROR_INVALID_PARAM-timeval參數(shù)無效
*其他LIBUSB_ERROR錯誤碼
*/
intAPI_EXPORTEDlibusb_handle_events(libusb_context*ctx);

2.9.9 釋放 transfer 結(jié)構(gòu)體

傳輸完畢，需要釋放 libusb_transfer 結(jié)構(gòu)體，如果要重復(fù)利用這個結(jié)構(gòu)體則無需釋放。

/**ingrouplibusb_asyncio
*釋放libusb_transfer結(jié)構(gòu)體
*前面使用libusb_alloc_transfer()分配的結(jié)構(gòu)體，要使用本函數(shù)來釋放。
*
*如果libusb_transfer::flags的LIBUSB_TRANSFER_FREE_BUFFER位非0，
*那么會使用free()函數(shù)釋放ibusb_transfer::buffer
*
*不能使用本函數(shù)釋放一個活動的傳輸結(jié)構(gòu)體(active,已經(jīng)提交尚未結(jié)束)
*
*/
voidAPI_EXPORTEDlibusb_free_transfer(structlibusb_transfer*transfer);

3. 使用示例

在 libusb 源碼的 examples 目錄下有示例程序，我們也有一些真實的案列。

3.1 dnw 工具

dnw 是 s3c2440 時代的工具，使用它可以從 PC 給開發(fā)板傳輸文件。它的核心源碼如下，使用同步接口進行數(shù)據(jù)傳輸：

/*openthedeviceusinglibusb*/
status=libusb_init(NULL);
if(status

	3.2 openocd

	openocd 是一個開源的 USB JTAG 調(diào)試軟件，它也是使用 libusb，涉及 USB 的操作代碼如下。

	3.2.1 找到設(shè)備
staticintcmsis_dap_usb_open(structcmsis_dap*dap,uint16_tvids[],uint16_tpids[],constchar*serial)
{
interr;
structlibusb_context*ctx;
structlibusb_device**device_list;

err=libusb_init(&ctx);
if(err){
LOG_ERROR("libusbinitializationfailed:%s",libusb_strerror(err));
returnERROR_FAIL;
}

intnum_devices=libusb_get_device_list(ctx,&device_list);
if(num_devices0){
err=libusb_get_string_descriptor_ascii(
dev_handle,dev_desc.iSerialNumber,
(uint8_t*)dev_serial,sizeof(dev_serial));

if(err0){
err=libusb_get_string_descriptor_ascii(
dev_handle,dev_desc.iProduct,
(uint8_t*)product_string,sizeof(product_string));
if(errbConfigurationValue;
conststructlibusb_interface_descriptor*intf_desc_candidate=NULL;
conststructlibusb_interface_descriptor*intf_desc_found=NULL;

for(intinterface=0;interfacebNumInterfaces;interface++){
conststructlibusb_interface_descriptor*intf_desc=&config_desc->interface[interface].altsetting[0];
intinterface_num=intf_desc->bInterfaceNumber;

/*Skipthisinterfaceifanotheronewasrequestedexplicitly*/
if(cmsis_dap_usb_interface!=-1&&cmsis_dap_usb_interface!=interface_num)
continue;

/*CMSIS-DAPv2specsays:
*
*CMSIS-DAPwithdefaultV2configurationusesWinUSBandisthereforefaster.
*OptionallysupportforstreamingSWOtraceisprovidedviaanadditionalUSBendpoint.
*
*TheWinUSBconfigurationrequirescustomclasssupportwiththeinterfacesetting
*ClassCode:0xFF(Vendorspecific)
*Subclass:0x00
*Protocolcode:0x00
*
*DependingontheconfigurationitusesthefollowingUSBendpointswhichshouldbeconfigured
*intheinterfacedescriptorinthisorder:
*-Endpoint1:BulkOut–usedforcommandsreceivedfromhostPC.
*-Endpoint2:BulkIn–usedforresponsessendtohostPC.
*-Endpoint3:BulkIn(optional)–usedforstreamingSWOtrace(ifenabledwithSWO_STREAM).
*/

/*Searchfor"CMSIS-DAP"intheinterfacestring*/
boolcmsis_dap_in_interface_str=false;
if(intf_desc->iInterface!=0){

charinterface_str[256]={0};

err=libusb_get_string_descriptor_ascii(
dev_handle,intf_desc->iInterface,
(uint8_t*)interface_str,sizeof(interface_str));
if(erriInterface,
dev_desc.idVendor,dev_desc.idProduct,
libusb_strerror(err));
}elseif(strstr(interface_str,"CMSIS-DAP")){
cmsis_dap_in_interface_str=true;
LOG_DEBUG("foundinterface%dstring'%s'",
interface_num,interface_str);
}
}

/*Bypassthefollowingcheckifthisinterfacewasexplicitlyrequested.*/
if(cmsis_dap_usb_interface==-1){
if(!cmsis_dap_in_product_str&&!cmsis_dap_in_interface_str)
continue;
}

/*checkendpoints*/
if(intf_desc->bNumEndpointsbNumEndpoints);
continue;
}

if((intf_desc->endpoint[0].bmAttributes&3)!=LIBUSB_TRANSFER_TYPE_BULK||
(intf_desc->endpoint[0].bEndpointAddress&0x80)!=LIBUSB_ENDPOINT_OUT){
LOG_DEBUG("skippinginterface%d,endpoint[0]isnotbulkout",
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("skippinginterface%d,endpoint[1]isnotbulkin",
interface_num);
continue;
}

/*WecanrelyontheinterfaceisreallyCMSIS-DAPif
*-we'veseenCMSIS-DAPintheinterfacestring
*-configaskedexplicitlyforaninterfacenumber
*-thedevicehasonlyoneinterface
*Thelatertwocasesshouldbehonoredonlyifweknow
*weareontherightdevice*/
boolintf_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){
/*Iftheinterfaceisreliablyidentified
*thenweneednotinsistonsettingUSBclass,subclassandprotocol
*exactlyasthespecificationrequires.
*AtleastKitProg3usesclass0contrarytothespecification*/
if(intf_identified_reliably){
LOG_WARNING("UsingCMSIS-DAPv2interface%dwithwrongclass%"PRId8
"subclass%"PRId8"orprotocol%"PRId8,
interface_num,
intf_desc->bInterfaceClass,
intf_desc->bInterfaceSubClass,
intf_desc->bInterfaceProtocol);
}else{
LOG_DEBUG("skippinginterface%d,class%"PRId8
"subclass%"PRId8"protocol%"PRId8,
interface_num,
intf_desc->bInterfaceClass,
intf_desc->bInterfaceSubClass,
intf_desc->bInterfaceProtocol);
continue;

}
}

if(intf_identified_reliably){
/*That'stheone!*/
intf_desc_found=intf_desc;
break;
}

if(!intf_desc_candidate&&device_identified_reliably){
/*ThisinterfacelookssuitableforCMSIS-DAP.Storethepointertoit
*andkeepsearchingforanotheronewithCMSIS-DAPininterfacestring*/
intf_desc_candidate=intf_desc;
}
}

if(!intf_desc_found){
/*WewerenotabletoidentifyreliablywhichinterfaceisCMSIS-DAP.
*Let'susethefirstsuitableifwefoundone*/
intf_desc_found=intf_desc_candidate;
}

if(!intf_desc_found){
libusb_free_config_descriptor(config_desc);
continue;
}

/*We'vechosenaninterface,connecttoit*/
intinterface_num=intf_desc_found->bInterfaceNumber;
intpacket_size=intf_desc_found->endpoint[0].wMaxPacketSize;
intep_out=intf_desc_found->endpoint[0].bEndpointAddress;
intep_in=intf_desc_found->endpoint[1].bEndpointAddress;

libusb_free_config_descriptor(config_desc);
libusb_free_device_list(device_list,true);

LOG_INFO("UsingCMSIS-DAPv2interfacewithVID:PID=0x%04x:0x%04x,serial=%s",
dev_desc.idVendor,dev_desc.idProduct,dev_serial);

intcurrent_config;
err=libusb_get_configuration(dev_handle,¤t_config);
if(err){
LOG_ERROR("couldnotfindcurrentconfiguration:%s",libusb_strerror(err));
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_FAIL;
}

if(config_num!=current_config){
err=libusb_set_configuration(dev_handle,config_num);
if(err){
LOG_ERROR("couldnotsetconfiguration:%s",libusb_strerror(err));
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_FAIL;
}
}

err=libusb_claim_interface(dev_handle,interface_num);
if(err)
LOG_WARNING("couldnotclaiminterface:%s",libusb_strerror(err));

dap->bdata=malloc(sizeof(structcmsis_dap_backend_data));
if(!dap->bdata){
LOG_ERROR("unabletoallocatememory");
libusb_release_interface(dev_handle,interface_num);
libusb_close(dev_handle);
libusb_exit(ctx);
returnERROR_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("unabletoallocatememory");
cmsis_dap_usb_close(dap);
returnERROR_FAIL;
}

dap->command=dap->packet_buffer;
dap->response=dap->packet_buffer;

returnERROR_OK;
}

libusb_close(dev_handle);
}

libusb_free_device_list(device_list,true);

libusb_exit(ctx);
returnERROR_FAIL;
}

	3.2.2 讀寫數(shù)據(jù)
staticintcmsis_dap_usb_read(structcmsis_dap*dap,inttimeout_ms)
{
inttransferred=0;
interr;

err=libusb_bulk_transfer(dap->bdata->dev_handle,dap->bdata->ep_in,
dap->packet_buffer,dap->packet_size,&transferred,timeout_ms);
if(err){
if(err==LIBUSB_ERROR_TIMEOUT){
returnERROR_TIMEOUT_REACHED;
}else{
LOG_ERROR("errorreadingdata:%s",libusb_strerror(err));
returnERROR_FAIL;
}
}

memset(&dap->packet_buffer[transferred],0,dap->packet_buffer_size-transferred);

returntransferred;
}

staticintcmsis_dap_usb_write(structcmsis_dap*dap,inttxlen,inttimeout_ms)
{
inttransferred=0;
interr;

/*skipthefirstbytethatisonlyusedbytheHIDbackend*/
err=libusb_bulk_transfer(dap->bdata->dev_handle,dap->bdata->ep_out,
dap->packet_buffer,txlen,&transferred,timeout_ms);
if(err){
if(err==LIBUSB_ERROR_TIMEOUT){
returnERROR_TIMEOUT_REACHED;
}else{
LOG_ERROR("errorwritingdata:%s",libusb_strerror(err));
returnERROR_FAIL;
}
}

returntransferred;
}

	編輯：黃飛