我想翻译USB编程指南，谁有意合作？

edwardhayes

luoyong兄到结束的时候，麻烦你整理一下，成为一个html。

luoyong

好的

luoyong

USB的数据传输
这一节主要讲述关于USB数据传输所需要的变量、宏定义和函数。

结构变量和宏定义
USB子系统使用USB请求块(URB)来传输数据，在这个结构变量中包含了USB数据传输的所有设置参数。USB的传输采用异步方式，在传输完毕后通过一个停止函数来结束所有传送。
typedef struct
{
    unsighed int offset;                         //数据的缓冲区地址
    unsighed int length;                        //预计的数据长度
    unsighed int actual_length;            //处理结束后得到的实际数据长度
    unsighed int status;                         //处理结束后的状态
}iso_packet_descriptor_t,*piso_packet_descriptor_t;
struct urb;
typedef struct urb
{
                  spinlock_t lock;
                  void *hcpriv;                                   //USB控制器所要使用的数据(可以不必考虑)
                  struct list_head urb_list;                 //所有urb的列表(可以不必考虑)
   >C0        struct urb* next;                              //下一个urb
   >CM      struct usb_device *dev;                   //相关的USB设备
   >CM         unsighed int pipe;                            //有关数据管道的信息
   <C         int status;                                         //返回的状态标志
   TC0         unsighed int transfer_flags;                                           //USB_DISABLE_SPD|USB_ISO_ASAP|USB_URB_EARLY_COMPLE
  >CM          void *transfer_buffer;                    //所要使用的数据缓冲区
  >CM          int transfer_buffer_length;             //数据缓冲的长度
  <C          int actual_length;                            //实际的数据缓冲长度
                 int bandwidth;                                 //带宽
  <X--          unsighed char *setup_packet;         //配置时使用的数据(只在控制流中使用)
  T-XX          int start_frame;                               //开始侦(只在异步和中断方式中使用)
  >--X          int number_of_packets;                  //所要传送的数据包(只在异步传输中使用)
  >-X-          int interval;                                     //选择时间间隔(只在中断方式中使用)
  <--X          int error_count;                               //出现错误的次数(只在异步方式中使用)
  >XXX          int timeout;                                     //超时等待时间

  >C0          void *context;                                 //相关信息
  >C0          usb_complete_t complete;              //指向相关信息的指针

  >--X          iso_packet_descriptor_t iso_frame_desc[0];//可选的iso描述符
}urb_t,*purb_t;
如上面的例子，一个URB包含了数据传送方式的描述参数(用C标出)。符号>代表输入参数，M表示的是URB中必须包括的参数，0表示可选(可省略)的，符号<代表返回值，标有T的为临时参数，标有X的参数表示被相关传输类型所使用。

    URB看起来繁杂但功能齐备，虽然有些宏定义能够帮助我们进行快速设置但是许多重要的参数仍然需要手动改动。

dev ：一个指向probe函数中usb_device的指针。
pipe：用来指定结束符和配置信息，这里提供了一些自动生成pipe值的宏定义
           pipe=usb_sndctrlpipe(dev,endpoint)
           pipe=usb_rcvctrlpipe(dev,endpoint)
           创建一个向上(rcv)或向下(snd)控制流的管道。dev通常是一个指向usb_device结构的指针，endpoint通常设为0。
           
            pipe=usb_sndbulkpipe(dev,endpoint)
            pipe=usb_rcvbulkpipe(dev,endpoint)
            创建一个向上(rcv)或向下(snd)的海量传输流的管道。endpoint的值一般是1和15之间。
            pipe=usb_sndintpipe(dev,endpoint)
            pipe=usb_rcvintpipe(dev,endpoint)
            创建一个向上(rcv)或向下(snd)的中断流的管道。endpoint的值一般在1和15之间。
            pipe=usb_sndisopipe(dev,endpoint)
            pipe=usb_rcvisopipe(dev,endpoint)
            创建一个向上(rcv)或向下(snd)异步传输流的管道。endpoint值一般在1和15之间。

transfer_buffer:一个指向数据缓冲区的指针，这个缓冲区应该是一个不分页的连续物理内存块

transfer_buffer_length:数据缓冲区长度。这个值必须小于或者等于数据包的长度，最大的数据包长度可以从结束描述符的wMaxPacketSize变量中得到。如果endpoint值为零那么就没有可用的描述符，这时就可以从usb_device中的maxpacketsize中得到这个值。
在海量传输中如果传输量大于wMaxPacketSize就会被自动分成若干小块进行传输。

complete:

shhky

参考
   ·出错代码
        ○USB提交请求模块(usb_submit_urb)的出错代码       
        ○USB请求模块(URB)出错代码
        ○USB核心函数的出错代码

·USB提交请求模块(usb_submit_urb)的出错代码

·非USB指定
        0                USB请求模块提交成功
        -ENOMEM                内部结构分配内存失败

·USB指定
        -ENODEV                指定的USB设备或总线不存在
        -ENXIO                USB请求块已经在请求队列
        -EINVAL
                        a) 指定的传输方式无效（或不支持）
                        b) 无效的中断间隔(0n256)
                        c) 一个以上的中断包
        -EAGAIN
                        a) 指定的ISO帧过早开始
                        b) （使用 ISO-ASAP）预期等待队列过长请重试
        －EFBIG                请求的ISO帧过多 （当前地uhci900）
        -EPIPE                指定的管道句柄已经停止使用
        -EMSGSIZE        端点消息大小为0, 执行接口/预备设定

·USB请求模块(URB)出错代码
   ·下列错误由urb->status或iso_frame_desc[n].status返回：
        0                传输成功完成
        -ENOENT                unlink_urb取消URB
        -EINPROGRESS        URB未完成，尚无结果（准确的说，到目前没有错误）
        -EPROTO
                        a) Bitstuff错误
                        b) 未知的USB错误
        -EILSEQ                CRC校验不符
        -EPIPE
                        a) 检测到干扰
                        b) 端点停止
        -ENOST                缓冲区错误
        -ETIMEDOUT        传输超时，NAK
        -ENODEV                USB设备未连接
        -EREMOTEIO        侦测到小包
        -EXDEV ISO        传输只完成部分，具体信息请查看单个数据帧的状态
        -EINVAL ISO        ISO疯啦，如果你看到这个错误，关机回家吧。

·USB核心函数的出错代码

·usb_register():
        -EINVAL                在注册新驱动时出现错误

·usb_terminate_bulk():
        -ENODEV                URB 已移除

·usb_get_*/usb_set_*():
        所有的USB错误（提交/状态）都可能发生。


参考书目

1 http://www.usb.org, Universal Serial Bus Implementers Forum

2 http://www.linux-usb.org, Linux USB Developer and Support information.

3 http://usb.cs.tum.edu, Linux USB Developer Pages

4 Universal Serial Bus Specification Compaq, Intel, Microsoft, NEC, Revision 1.1, September

23, 1998

5 Universal Serial Bus Common Class Specification Systemsoft Corporation, Intel Corporation,

Revision 1.0 December 16, 1997

6 Device Class Definition for Human Interface Devices (HID) Firmware Specification, Version

1.1, Universal Serial Bus (USB),July 4, 1999

7 Intel Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1, March 1996

8 Linux Device Drivers, 1st Edition, Alessandro Rubini, February 1998

9 http://selva.dit.upm.es/jmseyas/linux/kernel/hackers-docs.html, Index of Documentation for

People Interested in Writing and/or Understanding the Linux Kernel, Juan-Mariano de Goyeneche

shhky

索引
actual_length
        传输数据结构 & | 传输数据结构 &
bulk transfers
        数据流类型
bus powered
        USB设备与传输
communication speed
        USB设备与传输
compatibility wrappers
        兼容性包装
complete
        传输数据结构 &
configuration descriptor
        标准描述
context
        传输数据结构 &
control transfers
        数据流类型
dev
        传输数据结构 &
device classes
        设备类型
device descriptor
        标准描述符
disconnect function
        框架入口
downstream
        数据流类型
driver framework
        USB设备驱动
endpoint descriptor
        标准描述符
entry points
        框架入口
enumeration
        枚举和设备描述符
Error Codes
        出错代码
error_count
        传输数据结构 &
FILL_BULK_URB
        URB 宏
FILL_BULK_URB_TO
        URB 宏
FILL_CONTROL_URB
        URB 宏
FILL_CONTROL_URB_TO
        URB 宏
FILL_INT_URB
        URB 宏
framework
        USB设备驱动
full speed
        USB设备与传输
HID
        人机交互接口设备(HID)
Host Controller
        宿主控制器
hub
        集线器
human interface devices
        人机交互接口设备(HID)
interface descriptor
        标准描述符
interrupt transfers
        数据流类型
interval
        传输数据结构 &
iso_frame_desc
        传输数据结构 &
isochronous transfers
        数据流类型
linux USB subsystem
        Linux USB子系统
low speed
        USB设备与传输
macros
        URB 宏
next
        传输数据结构 &
number_of_packets
        传输数据结构 &
OHCI
        宿主控制器
pipe
        传输数据结构 &
probe function
        框架入口
self powered
        USB设备与传输
setup_packet
        传输数据结构 &
specification
        通用串行总线
start_frame
        传输数据结构 & | 传输数据结构 &
status
        传输数据结构 &
string descriptors
        标准描述符
struct usb_config_descriptor
        描述符数据结构
struct usb_device
        描述符数据结构
struct usb_endpoint_descriptor
        描述符数据结构
struct usb_interface
        描述符数据结构
struct usb_interface_descriptor
        描述符数据结构
timeout
        传输数据结构 &
transfer_buffer
        传输数据结构 &
transfer_buffer_length
        传输数据结构 &
transfer_flags
        传输数据结构 &
UHCI
        宿主控制器
Universal Serial Bus
        通用串行总线
upstream
        数据流类型
USB
        通用串行总线
USB core
        Linux USB子系统
USB subsystem
        Linux USB子系统
usb_alloc_urb
        URB 函数
USB_ASYNC_UNLINK
        传输数据结构 &
usb_bulk_msg
        兼容性包装（Compatibility Wrappers ）
usb_clear_halt
        标准设备请求
usb_control_msg
        兼容性包装（Compatibility Wrappers ）
usb_deregister
        框架函数
USB_DISABLE_SPD
        传输数据结构 &
usb_driver_claim_interface
        框架函数
usb_driver_release_interface
        框架函数
usb_free_urb
        URB 函数
usb_get_descriptor
        标准设备请求
usb_get_device_descriptor
        标准设备请求
usb_get_protocol
        标准设备请求
usb_get_report
        标准设备请求
usb_get_status
        标准设备请求
usb_get_string
        标准设备请求
usb_interface_claimed
        框架函数
USB_ISO_ASAP
        传输数据结构 &
USB_NO_FSBR
        传输数据结构 &
USB_QUEUE_BULK
        传输数据结构 &
usb_rcvbulkpipe
        传输数据结构 &
usb_rcvctrlpipe
        传输数据结构 &
usb_rcvintpipe
        传输数据结构 &
usb_rcvisopipe
        传输数据结构 &
usb_register
        框架函数
usb_set_configuration
        标准设备请求
usb_set_idle
        标准设备请求
usb_set_interface
        标准设备请求
usb_set_protocol
        标准设备请求
usb_sndbulkpipe
        传输数据结构 &
usb_sndctrlpipe
        传输数据结构 &
usb_sndintpipe
        传输数据结构 &
usb_sndisopipe
        传输数据结构 &
usb_string
        标准设备请求
usb_submit_urb
        URB 函数
USB_TIMEOUT_KILLED
        传输数据结构 &
usb_unlink_urb
        URB 函数
virtual root hub
        集线器

shhky

关于这篇文档
Linux USB设备驱动编程指南
本文是由 LaTeX2HTML translator 生成的（版本 99.1 release——1999年3月发布）。

版权所有 1993, 1994, 1995, 1996, Nikos Drakos, 英国利兹大学(University of Leeds),基于计算机的学习组(Computer Based Learning Unit).
版权所有 1997, 1998, 1999, Ross Moore, 澳大利亚悉尼Macquarie大学,数学系(Mathematics Department).

生成文档所使用的命令行参数为：
latex2html -local_icons -rootdir usbdoc -up_url http://usb.cs.tum.edu -up_title USB Developer Pages usbdoc.tex

本文的转换是有Detlef Fliegl于2001年1月8日完成的。

本文的中文文档由edwardhayes(通用串型总线), luoyong(Linux的USB子系统), shhky(附录部分) 于2004年3月4日完成第一稿。

luoyong

对不起二位了，这篇文章我选错了，这文章是由一篇德文文章翻译过来的，有许多语句不通的地方，中间的代码部分的讲解条理很乱，总之这篇文章不怎么好
二位的文章我已经存档了，争取单独成文，有机会到资料站上发布出去，实在抱歉了，耽误大家时间了
不过将错就错，我还是会把我的那部分翻译出来的

luoyong

complete:一个指向当操作结束后调用的函数的指针。

context:一个指向与发送请求相关的context结构
例子：一个传送操作结束后调用的函数
void complete(struct urb *purb)
{
    struct device_context *s=purb->context;
    /*唤醒请求源*/
    wake_up(&s->wait);
}

transfer_flags：修改这个变量可以改变数据传送方式，可以取的值如下
USB_DISABLE_SPD
使用这个标志代表忽略小数据包，小数据包是指到结束点时没有上传足够的数据，没有到达数据包的容量。
USB_NO_FSBR
USB_ISO_ASAP
当使用同步传输时这个标志告诉USB控制器立即开始传输。
USB_ASYNC_UNLINK
当取消一个URB时，你可以用同步和异步两种方式来结束，使用这个标志代表异步。
USB_TIMEOUT_KILLED
当需要使用超时停止的话使用这个标志，停止后URB状态符会给出超时的原因。
USB_QUEUE_BULK
允许你使用海量传输队列，通常情况下每次只能进行一组海量传输。

next：你可以使用next指针将多个URB连接成一个请求链，这就允许你向USB Core传送一连串的请求，你可以使用一个空指针(NULL)来结束这个链。

status：这个变量表示数据传送的状态。当请求成功传送后的返回值是-EINPROGRESS，成功结束后返回0，在3.1节中列出了所有的错误的表示值。

actual_length：当传输结束后这个变量会表示出传送字节的实际数目。

剩下的参数值对对应的传输方式有效
海量传输相关：无对应参数
控制传输：
setup_packet  控制传输由2到3个阶段组成，第一个阶段是向下传输控制数据的数据包，这个变量就指向那个包含控制信息的缓冲区，这个缓冲区必须是一个不分页的连续物理内存块。(通常使用void *kmalloc(size_t,GFP_KERNEL);)
中断传输：
start_frame
这个变量表示了第一个数据块。
interval
这个变量表示出以毫秒位单位的时间间隔，值应该在1和255之间。将这个值设为0表示立即中断。你可以在中断传输的结束描述结构中找到bInterval,这个就是中断的间隔。

darkstar_w

Edward,这些东西怎有没有组织和打包？

edwardhayes

我已经请luoyong兄做这个工作了，不知道他是不是有事情耽搁了。
最近我这边老是停电，什么事情都不能做，火死了……
每天都是白白浪费掉7、8个钟头。