usbredir-0.7内容详解（一）

      在spice源码中难免会遇到usb重定向的问题，现在最新的usb重定向的版本是：usb重定向协议0.7版本（USB redirection protocol version 0.7），可以点击：usbredir-0.7.tar.bz2, 或者网站http://www.spice-space.org/page/UsbRedir下载就可以了。

　下完解压后里面有个协议说明文档usb-redirection-protocol.txt，主要介绍了版本信息和协议方面的东西，看懂了这个整个协议就差不多了。其他版本的极少就不看了，直接０0.7版本了：

版本0.7                 2014.5.19发行

-usb_redir_ep_info_header扩展了max_streams字段，如果两边都有usb_redir_cap_bulk_streams，它将只会被发送/接收。

-改变了了bulk_stream 包的定义，允许在一对多点上分配/释放流，理论上讲是协议上的变化，但是目前未知还没哪一个去使用它，这一点可以安全的使用。

USB 重定向协议  版本0.7

-----------------------------------------------------------

在本文档中这个协议是为一个单独的usb设备建立usb传输隧道（通道），注意：不是整个hub，而是单个的usb设备。

最有意义的应用是将一个client / viewer  "a"上所连接的usb设备，连接到寄宿在主机"b"上的虚拟机 "v"内，并且可以在这个虚拟机 "v" 上显示，就像直接在虚拟机上链接的一样。

这个协议是一个可靠的双向传输协议，例如tcp 套接字socket，在协议中所有的整型都会通过这个管道的有序字节被发送，所有的结构体都被被打包发送（no padding）。

定义：

usb-device:usb-device的usb传输将会建立隧道。

usb-guest:连接usb-device和使用，就像直接连接和使用它一样，例如一个虚拟机运行的是guset os 通过网络连接了一个usb-device，就像usb-device是这个虚拟机的一部分。

usb-host:使一个usb-device可以被usb-guest使用。例如通过网络连接到一个机器上的usb光驱，在另一台上的虚拟设备上呈现。

基本包结构/通信

------------------------------------------------------------

在usb-guest和usb-host之间所交换的每一个包都开始于一个连表头usb_redir_header,后面识根据特定的可选类型的可选数据。

                   
//下面是<span style="font-family: Arial, Helvetica, sans-serif;">usb_redir_header，每个都如下所示 </span>

struct usb_redir_header {
     uint32_t type; 
     uint32_t length;
     uint32_t id;   
 }                  
//或者两边（<span style="font-size:18px;">usb-guest和</span><span style="font-size:18px;">usb-host</span>）都含有<span style="font-family: Arial, Helvetica, sans-serif;">usb_redir_cap_64bits_ids 则如下所示</span>          
struct usb_redir_header {
     uint32_t type;                                 
     uint32_t length;
     uint64_t id;   
 }      

/******************************************************

type：包的类型来，自与枚举

<pre name="code" class="cpp">length：可选类型的header + 可选类型的data，可以为0

id：当usb-guest发送包时就会产生一个唯一的id，usb-host将会使用同样的id来回应这个包，允许usb-guest根据初始的re     quest来匹配回应

************************************************************/

有两个类型的包：

1) control packets       //控制包                                                                                          
2) data packets           //数据包

control packets在usb-host,同时被操作，并且发送request到 host os后，就会“等待”回应，usb-host将会停止进程知道等到回应的包。然而对于数据包data packets，usb-host通过提交包含请求的data packets到host os，让usb-host知道有一个来自usb-device的回应。

注意：control packets 应当仅仅发送到usb-host上，当没有数据包在设备/接口/终点影响的控制包的等待时，所有挂起的数据包将会被丢弃。

包的类型列表        
----------------           
                           
control packets://控制包           
 usb_redir_hello            
 usb_redir_device_connect   
 usb_redir_device_disconnect
 usb_redir_reset            
 usb_redir_interface_info   
 usb_redir_ep_info          
 usb_redir_set_configuration
 usb_redir_get_configuration
 usb_redir_configuration_status
 usb_redir_set_alt_setting  
 usb_redir_get_alt_setting  
 usb_redir_alt_setting_status
 usb_redir_start_iso_stream 
 usb_redir_stop_iso_stream  
 usb_redir_iso_stream_status                                                                                                        
 usb_redir_start_interrupt_receiving
 usb_redir_stop_interrupt_receiving
 usb_redir_interrupt_receiving_status
 usb_redir_alloc_bulk_streams 
 usb_redir_free_bulk_streams
 usb_redir_bulk_streams_status
 usb_redir_cancel_data_packet 
 usb_redir_filter_reject    
 usb_redir_filter_filter    
 usb_redir_device_disconnect_ack   
 usb_redir_start_bulk_receiving    
 usb_redir_stop_bulk_receiving
 usb_redir_bulk_receiving_status   
data packets://数据包              
 usb_redir_control_packet   
 usb_redir_bulk_packet      
 usb_redir_iso_packet       
 usb_redir_interrupt_packet 
 usb_redir_buffered_bulk_packet                           

每一个usb-host都包含一个状态字段，如下所示

enum {        
    usb_redir_success, 
    usb_redir_cancelled,    /* 传输被取消 */
    usb_redir_inval,        /* Invalid packet type / length / ep, etc. */
    usb_redir_ioerror,      /* IO error 输入输出错误 */
    usb_redir_stall,        /* Stalled 停滞 */
    usb_redir_timeout,      /* Request timed out 请求超时*/
    usb_redir_babble,       /* The device has "babbled" 设备泄露 */
};<span style="font-size: 18px; font-family: Arial, Helvetica, sans-serif;">/*注意在未来的版本有可能会添加状态码到新的 error 情况下，因此位置的状态值将会为译为一个错误*/</span>

usb_redir_hello
----------------------------------

//usb_redir_header.type:    usb_redir_hello
//usb_redir_header.length:  <see description>
//usb_redir_header.id:      0 (always as this is an unsolicited packet)
                           
struct usb_redir_hello_header {
    char     version[64];  
    uint32_t capabilities[0];
}

<span style="font-size: 18.1818180084229px;">/*一旦连接建立的时候这个类型的包将会被两边发送，它是强制被发送的第一个包，他包含</span> ：

<pre name="code" class="cpp" style="font-size: 18.1818180084229px;">version：从0开始的开源版本字符串，用作log，不被解析

capabilities:用于发布的可变长度数组，会在下面的枚举定义

*/    

enum {                 
    /* Supports USB 3 bulk streams 支持usb 3 块流*/
    usb_redir_cap_bulk_streams, 
    /* The device_connect packet has the device_version_bcd field设备链接的bcd字段 */
    usb_redir_cap_connect_device_version,
    /* Supports usb_redir_filter_reject and usb_redir_filter_filter pkts */
    usb_redir_cap_filter, 
    /* Supports the usb_redir_device_disconnect_ack packet */
    usb_redir_cap_device_disconnect_ack,
    /* The ep_info packet has the max_packet_size field */
    usb_redir_cap_ep_info_max_packet_size,
    /* Supports 64 bits ids in usb_redir_header */
    usb_redir_cap_64bits_ids,
    /* Supports 32 bits length in usb_redir_bulk_packet_header */
    usb_redir_cap_32bits_bulk_length,
    /* Supports bulk receiving / buffered bulk input */
    usb_redir_cap_bulk_receiving,
};    

usb_redir_device_connect

------------------------

//usb_redir_header.type:    usb_redir_device_connect
//usb_redir_header.length:  sizeof(usb_redir_device_connect_header)
//usb_redir_header.id:      0 (always as this is an unsolicited packet)
                           
enum {//usb重定向的速度：低速，全速，高速，超速                     
    usb_redir_speed_low,   
    usb_redir_speed_full,  
    usb_redir_speed_high,  
    usb_redir_speed_super, 
    usb_redir_speed_unknown = 255
}                          
                           
struct usb_redir_device_connect_header {
    uint8_t speed;//由上面的枚举获得         
    uint8_t device_class;  //设备类
    uint8_t device_subclass;//子类
    uint8_t device_protocol; //协议
    uint16_t vendor_id;    //供应商id
    uint16_t product_id;   //产品id
    uint16_t device_version_bcd;//版本bcd
}  //这个包只被usb-host发送，当设备可用的时候。注意：usb-host可能会重新利用存在连接对于一个新的/新挂载的设备上，这种情况下会在一个usb_redir_device_disconnect消息被发送通知usb-guest一个新的可用设备后重新被发送。注意：在发送usb_redir_device_connect_info 之前首先通过usb_redir_interface_info发送usb_redir_ep_info.    

usb_redir_device_disconnect

-------------------------------------------

//usb_redir_header.type:    usb_redir_device_disconnect
//usb_redir_header.length:  0
//usb_redir_header.id:      0 (always as this is an unsolicited packet)

//这个包被usb-host发送来告知设备已经断开（卸载），注意：在一些平台上usb-host也许不会自动发现断开直到usb包被发送到设备。

usb_redir_reset

-----------------------------------

//usb_redir_header.type:    usb_redir_reset
//usb_redir_header.length:  0

//这个包会被usb-guest发送来触发一个usb设备的重置。注意：在reset之后当有东西出错时usb-host可能无法重连，如果发生这样的情况usb_redir_device_disconnect将会呗usb-host发送