13.5. 無 urb 的 USB 傳送 · Linux 設備驅動 (第三版)

## 13.5.?無 urb 的 USB 傳送有時一個 USB 驅動必須經過所有的步驟創建一個 struct urb, 初始化它, 再等待 urb 完成函數運行, 只是要發送或者接受一些簡單的 USB 數據. 有 2 個函數用來提供一個簡單的接口. ### 13.5.1.?usb_bulk_msg 接口 usb_bulk_msg 創建一個 USB 塊 urb 并且發送它到特定的設備, 接著在返回到調用者之前等待完成. 它定義為: ~~~ int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe, void *data, int len, int *actual_length, int timeout); ~~~ 這個函數的參數是: struct usb_device *usb_dev 發送塊消息去的 USB 設備的指針 unsigned int pipe 這個塊消息要發送到的 USB 設備的特定端點. 這個值被創建, 使用一個對 usb_sndbulkpipe 或者usb_rcvbulkpipe 的調用. void *data 如果這是一個 OUT 端點, 指向要發送到設備的數據的指針. 如果是一個 IN 端點, 這是一個在被從設備讀出后數據應當被放置的地方的指針. int len 被 data 參數指向的緩沖的長度 int *actual_length 指向函數放置真實字節數的指針, 這些字節要么被發送到設備要么從設備中獲取, 根據端點方向. int timeout 時間量, 以嘀噠計, 應當在超時前等待的. 如果這個值是 0, 函數永遠等待消息完成. 如果函數成功, 返回值是 0; 否則, 一個負錯誤值被返回. 這錯誤號匹配之前在"urb結構"一節中描述的錯誤號. 如果成功, actual_length 參數包含被傳送或從消息中獲取的字節數. 下面是一個使用這個函數調用的例子: ~~~ /* do a blocking bulk read to get data from the device */ retval = usb_bulk_msg(dev->udev, usb_rcvbulkpipe(dev->udev, dev->bulk_in_endpointAddr), dev->bulk_in_buffer, min(dev->bulk_in_size, count), &count, HZ*10); /* if the read was successful, copy the data to user space */ if (!retval) { if (copy_to_user(buffer, dev->bulk_in_buffer, count)) retval = -EFAULT; else retval = count; } ~~~ 這個例子展示了一個簡單的從一個 IN 端點的塊讀. 如果讀取成功, 數據接著被拷貝到用戶空間. 這個典型地是在 USB 驅動的讀函數中完成. usb_bulk_msg 函數不能被從中斷上下文調用, 或者持有一個自旋鎖. 還有, 這個函數不能被任何其他函數取消, 因此當使用它時小心; 確認你的驅動的去連接知道足夠多來等待調用結束, 在允許它自己被從內存中卸載之前. ### 13.5.2.?usb_control_msg 接口 usb_control_msg 函數就像 usb_bulk_msg 函數, 除了它允許一個驅動發送和結束 USB 控制信息: int usb_control_msg(struct usb_device *dev, unsigned int pipe, __u8 request, __u8 requesttype, __u16 value, __u16 index, void *data, __u16 size, int timeout); 這個函數的參數幾乎和 usb_bulk_msg 的相同, 有幾個這樣的不同: struct usb_device *dev 指向發送控制消息去的 USB 設備的指針. unsigned int pipe 控制消息要發送到的 USB 設備的特定端點. 這個值在 usb_sndctrlpipe 或者 usb_rcvctrlpipe 函數中被創建. __u8 request 這個控制消息的 USB 請求值. __u8 requesttype 這個控制消息的 USB 請求類型. __u16 value 這個控制消息的 USB 消息值. __u16 index 這個控制消息的 USB 消息索引值. void *data 如果是一個 OUT 端點, 是一個指向要發送到設備的數據的指針. 如果是一個 IN 端點, 是一個在被從設備讀取后數據被放置的地方的指針. __u16 size 被 data 參數指向的緩沖的大小. int timeout 時間量, 以嘀噠計, 應當在超時前等待的. 如果這個值是 0, 這個函數將等待消息結束. 如果函數是成功的, 它返回被傳送到或從這個設備的字節數. 如果它不成功, 它返回一個負錯誤碼. 參數 request, requesttype, value, 和 index 都直接映射到 USB 規范給一個 USB 控制消息如何被定義. 對于更多的關于這些參數的有效值的信息和它們如何被使用, 見 USB 規范的第 9 章. 象 usb_bulk_msg 函數, 函數 usb_control_msg 不能被從中斷上下文或者持有自旋鎖中被調用. 還有, 這個函數不能被任何其他函數取消, 所以當使用它時要小心; 確認你的驅動的 disconnect 函數了解足夠多, 在允許它自己被從內存卸載之前完成等待調用. ### 13.5.3.?使用 USB 數據函數 USB 核心中的幾個幫忙函數可用來從所有的 USB 設備中存取標準信息. 這些函數不能從中斷上下文或者持有自旋鎖時調用. 函數 usb_get_descriptor 獲取指定的 USB 描述符從特定的設備. 這個函數被定義為: ~~~ int usb_get_descriptor(struct usb_device *dev, unsigned char type, unsigned char index, void *buf, int size); ~~~ 這個函數可被一個 USB 驅動用來從 struct usb_device 結構中, 獲取任何還沒有在 struct usb_device 和 struct usb_interface 結構中出現的設備描述符, 例如聲音描述符或者其他類的特定消息. 這個函數的參數是: struct usb_device *usb_dev 指向應當從中獲取描述符的 USB 設備的指針 unsigned char type 描述符類型. 這個類型在 USB 規范中描述, 并且是下列類型之一: USB_DT_DEVICEUSB_DT_CONFIGUSB_DT_STRINGUSB_DT_INTERFACEUSB_DT_ENDPOINTUSB_DT_DEVICE_QUALIFIERUSB_DT_OTHER_SPEED_CONFIGUSB_DT_INTERFACE_POWERUSB_DT_OTGUSB_DT_DEBUGUSB_DT_INTERFACE_ASSOCIATIONUSB_DT_CS_DEVICEUSB_DT_CS_CONFIGUSB_DT_CS_STRINGUSB_DT_CS_INTERFACEUSB_DT_CS_ENDPOINT unsigned char index 應當從設備獲取的描述符的數目. void *buf 你拷貝描述符到的緩沖的指針. int size 由 buf 變量指向的內存的大小. 如果這個函數成功, 它返回從設備讀取的字節數, 否則, 它返回由它所調用的底層函數 usb_control_msg 所返回的一個負錯誤值. usb_get_descripter 調用的一項最普遍的用法是從 USB 設備獲取一個字符串. 因為這個是非常普遍, 有一個幫忙函數稱為 usb_get_string: ~~~ int usb_get_string(struct usb_device *dev, unsigned short langid, unsigned char index, void *buf, int size); ~~~ 如果成功, 這個函數返回設備收到的給這個字符串的字節數. 否則, 它返回一個由這個函數調用的底層函數 usb_control_msg 返回的負錯誤值. 如果這個函數成功, 它返回一個以 UTF-16LE 格式編碼的字符串(Unicode, 16位每字符, 小端字節序)在 buf 參數指向的緩沖中. 因為這個格式不是非常有用, 有另一個函數, 稱為 usb_string, 它返回一個從一個 USB 設備讀來的字符串, 并且已經轉換為一個 ISO 8859-1 格式字符串. 這個字符集是一個 8 位的 UICODE 的子集, 并且是最普遍的英文和其他西歐字符串格式. 因為這是 USB 設備的字符串的典型格式, 建議 usb_string 函數來替代 usb_get_string 函數.