13.5. 无 urb 的 USB 传送

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 函数.