CyUsb3014应用笔记3 USB协议的各种描述符-FX3固件为例

1 概述

各种描述符的关系如下：

这些描述符格式大部分是固定的，前期开发 按照既定的参数设置即可，很少有需要改动的。

USB协议的各种描述符有如下这些类别

1 设备描述符 

2 配置描述符（比如：super / high / full speed 配置描述符）

3 BOS描述符

4 设备限定描述符

5 字符串描述符 （分别为：语言ID字符串 厂商设备字符串 产品字符串）

以下介绍CYUSB3014 FX3 demo中的涉及到的描述符

2.1 USB3.0设备描述符

用来描述设备的基本属性的，表示这个设备的最基本的一些属性

/* Standard device descriptor for USB 3.0 */
const uint8_t CyFxUSB30DeviceDscr[] __attribute__ ((aligned (32))) =
{
    0x12,                           /* Descriptor size  长度为18字节 */
    CY_U3P_USB_DEVICE_DESCR,        /* Device descriptor type  设备描述符固定值0x01 */
    0x00,0x03,                      /* USB 3.0 协议 */
    0x00,                           /* Device class 设备类0，代表通用功能*/
    0x00,                           /* Device sub-class 设备子类0，代表通用功能*/
    0x00,                           /* Device protocol 设备协议0，代表通用功能*/
    0x09,                           /* Maxpacket size for EP0 : 2^9最大包大小为 2^9 (512 bytes) */
    0xB4,0x04,                      /* Vendor ID */
    0xF1,0x00,                      /* Product ID */
    0x00,0x00,                      /* Device release number 设备发布版本号为 0*/
    0x01,                           /* Manufacture string index 制造商的字符串索引值是1 */
    0x02,                           /* Product string index 产品的字符串索引值是2*/
    0x00,                           /* Serial number string index 序列号字符串的索引值是0 */
    0x01                            /* Number of configurations支持的配置数为 1 */
};

这里的制造商字符串索引值，产品字符串索引值，序列号字符串索引值 是用于标志这些 字符串的值是第几个。

比如 注册程序中的 回应HOST的SETUP 包 代码中：

CyU3PUsbSetDesc(CY_U3P_USB_SET_STRING_DESCR, 1, (uint8_t *)CyFxUSBManufactureDscr);

CyU3PUsbSetDesc(CY_U3P_USB_SET_STRING_DESCR, 2, (uint8_t *)CyFxUSBProductDscr);

CyU3PUsbSetDesc(CY_U3P_USB_SET_STRING_DESCR, 0, (uint8_t *)CyFxUSBStringLangIDDscr);


extern CyU3PReturnStatus_t
CyU3PUsbSetDesc (
        CyU3PUSBSetDescType_t desc_type,        /**< Type of descriptor to register. */
        uint8_t desc_index,                     /**< Descriptor index: Used only for string descriptors. */
        uint8_t* desc                           /**< Pointer to buffer containing the descriptor. */
        );

2.2 USB2.0 设备描述符

/* Standard device descriptor for USB 2.0 */
const uint8_t CyFxUSB20DeviceDscr[] __attribute__ ((aligned (32))) =
{
    0x12,                           /* Descriptor size */
    CY_U3P_USB_DEVICE_DESCR,        /* Device descriptor type */
    0x10,0x02,                      /* USB 2.10 */
    0x00,                           /* Device class */
    0x00,                           /* Device sub-class */
    0x00,                           /* Device protocol */
    0x40,                           /* Maxpacket size for EP0 : 64 bytes */
    0xB4,0x04,                      /* Vendor ID */
    0xF1,0x00,                      /* Product ID */
    0x00,0x00,                      /* Device release number */
    0x01,                           /* Manufacture string index */
    0x02,                           /* Product string index */
    0x00,                           /* Serial number string index */
    0x01                            /* Number of configurations */
};

和上一个一样的，不一样的地方是这里USB2.0支持的0端点最大的包大小是64字节（0x40)，USB的协议代码也不一样

2.3 BOS描述符

用于描述设备支持的USB功能和特性。

BOS描述符是USB 3.0规范中引入的新描述符类型，用于提供设备的扩展功能信息，例如设备支持的USB版本、设备功能等。

/* Binary device object store descriptor */
const uint8_t CyFxUSBBOSDscr[] __attribute__ ((aligned (32))) =
{
    0x05,                           /* Descriptor size，固定长度5 */
    CY_U3P_BOS_DESCR,               /* Device descriptor type，BOS描述符类型，固定为0x0f */
    0x16,0x00,                      /* Length of this descriptor and all sub descriptors                 
                                      BOS描述符的总大小，以字节为单位*/
    0x02,                           /* Number of device capability descriptors BOS描述符中                    
                                     独立设备功能特性描述符的数量 */

 // 第一个设备能力描述符  指示设备支持的USB 2.0扩展功能，其中包括对低功耗模式（LPM）的支持。
    /* USB 2.0 extension */
    0x07,                           /* Descriptor size  7字节*/
    CY_U3P_DEVICE_CAPB_DESCR,       /* Device capability type descriptor ，固定为16 */
    CY_U3P_USB2_EXTN_CAPB_TYPE,     /* USB 2.0 extension capability type 0x02H,表示USB 2.0     
                                     EXTENSION */
    0x02,0x00,0x00,0x00,            /* bmAttributes ：Supported device level features: 
                                     LPM support 
                                    bmAttributes:
                                    BIT0:保留不用，值设为0。
                                    BIT1:LPM,此位值为1表示此设备支持链路电源管理协议。USB3.2                 
                                      增强型超高速设备应将该位设置为1。
                                    BIT[31:2]，保留不用，值设为0。
                                    如果不支持LPM 模式需要改这个4字节参数全是0
                                     */
 

//第二个设备能力描述符:SuperSpeed设备能力描述符，指示设备支持的USB 3.0 SuperSpeed功能，
//包括支持的速度（SS、HS和FS）、功能支持以及设备退出低功耗模式的延迟时间。  
    /* SuperSpeed device capability */
    0x0A,                           /* Descriptor size固定为10字节 */
    CY_U3P_DEVICE_CAPB_DESCR,       /* Device capability type descriptor 固定为16 */
    CY_U3P_SS_USB_CAPB_TYPE,        /* SuperSpeed device capability type 固定为03h 表示USB 
                                     3.0 SUPERSPEED_USB */
    0x00,                           /* bmAttributes ：Supported device level features  
                                    bmAttributes:1字节
                                    BIT0:保留不用，值设为0。
                                    BIT1:LPM,此位值为1表示此设备具有生成延迟容忍消息的能力                 
                                     (Latency Tolerance Messages)。
                                    BIT[7:2]，保留不用，值设为0。
                                    */
                                    
    0x0E,0x00,                      /* wSpeedsSupported：Speeds supported by the device : 
                                       SS, HS and FS 
                                    wSpeedsSupported:2字节
                                    BIT0置1，表示设备支持低速USB操作。
                                    BIT1置1，表示设备支持全速USB操作。
                                    BIT2置1，表示设备支持高速USB操作。
                                    BIT3置1，表示设备支持以GEN1速度运行。
                                    这个参数需要设置为0x0e    
                                    */
                                                                        
    0x03,                           /* bFunctionalitySupport：Functionality support 支持的                 
                                    所有功能对用户可用的最低速度。
                                    例如，如果设备支持其所有功能当以全速或更高速度连接时，它将     
                                    此值设置为1。*/
    0x00,                           /* U1 Device Exit latency ，LPM 模式中的U1状态设备退出 
                                    延迟。*/
    0x00,0x00                       /* U2 Device Exit latency ，LPM 模式中的U2状态设备退出 
                                    延迟。*/
};

2.4 设备限定描述符

设备限定描述符用在当一个设备能够工作在不同的速度下时，会获取设备限定描述符。同时支持全速与高速的设备，必须有一个Device Qualifier Descriptor。当设备转换速度的时候，设备描述符中的某些字段可能改变。Device Qualifier Descriptor描述符储存当前不适用的速度的字段数值

设备限定符描述符通常用于USB 2.0中，用于描述设备在USB 2.0速度模式下的能力，以便主机正确选择设备的速度。

/* Standard device qualifier descriptor */
const uint8_t CyFxUSBDeviceQualDscr[] __attribute__ ((aligned (32))) =
{
    0x0A,                           /* Descriptor size ，固定字节10个 */
    CY_U3P_USB_DEVQUAL_DESCR,       /* Device qualifier descriptor type，固定参数 */
    0x00,0x02,                      /* USB 2.0  ，USB2.0协议 */
    0x00,                           /* Device class 通用设备*/
    0x00,                           /* Device sub-class 通用设备 */
    0x00,                           /* Device protocol 通用设备 */
    0x40,                           /* Maxpacket size for EP0 : 64 bytes EP0 支持的最大包大 
                                    小是64字节 */
    0x01,                           /* Number of configurations，支持的配置数量为1  */
    0x00                            /* Reserved */
};

这个描述符用于在USB设备被主机检测到时发送给主机，以便主机能够根据设备在USB 2.0速度下的能力进行适当的配置和通信。

2.5 super speed 配置描述符

/* Standard super speed configuration descriptor */
const uint8_t CyFxUSBSSConfigDscr[] __attribute__ ((aligned (32))) =
{
    /* Configuration descriptor */
    0x09,                           /* Descriptor size 固定大小9字节*/
    CY_U3P_USB_CONFIG_DESCR,        /* Configuration descriptor type，类型，固定值0x02 */

    0x2C,0x00,                      /* Length of this descriptor and all sub descriptors 
                                    此配置返回的配置描述符.

                                     接口描述符以及 端点描述符的全部大小 */
    0x01,                           /* Number of interfaces 接口数量*/
    0x01,                           /* Configuration number 配置编号，一般有1个配置，就写编 
                                    号是1好了*/

    0x00,                           /* COnfiguration string index 配置的字符串索引值，描述这 
                                     个配置是什么名字的，0代表没有*/

    0x80,                           /* Config characteristics - Bus powered 表示总线供电*/
    0x32,                           /* Max power consumption of device (in 8mA unit) :最大 
                                     电流 400mA */

    /* Interface descriptor */
    0x09,                           /* Descriptor size 固定 */
    CY_U3P_USB_INTRFC_DESCR,        /* Interface Descriptor type 固定04h*/
    0x00,                           /* Interface number 接口数量*/
    0x00,                           /* Alternate setting number 备用接口 描述符标号 */
    0x02,                           /* Number of end points 端点 数量*/
    0xFF,                           /* Interface class  接口类别*/
    0x00,                           /* Interface sub class 接口子类别*/
    0x00,                           /* Interface protocol code 接口协议*/
    0x00,                           /* Interface descriptor string index 接口字符串索引，这 
                                     里00代表没有*/

    /* Endpoint descriptor for producer EP */
    0x07,                           /* Descriptor size 固定07*/
    CY_U3P_USB_ENDPNT_DESCR,        /* Endpoint descriptor type 固定05*/

    CY_FX_EP_PRODUCER,              /* bEndpointType：Endpoint address and description 
                                    USB设备的端点地址属性
                                    非同步传输的含义：
                                    Bit7：方向，对于控制端点可以忽略，1/0:IN/OUT．    
                                    Bit6-4：保留．     
                                    BIt3-0：端点号．
                                    比如这个参数的0x01意思是 EP 1 OUT；   如果是0x81意思是 
                                    EP 1 IN
                                    当为同步传输时的含义:
                                    bEndpointType的bit3-2：
                                    00：无同步
                                    01：异步
                                    10：适配
                                    11：同步
                                    BIT5:4
                                    00: 表示数据端点
                                    01：表示反馈端点Feedback endpoint
                                    10：表示隐式反馈数据端点 Implicit feedback Data 
                                   endpoint
                                    11:保留
                                     */
                                     
    CY_U3P_USB_EP_BULK,             /* Bulk endpoint type 端点属性．
                                     Bit7-2，同步传输定义．
                                     BIt1-0：00控制，01同步，02批量，03中断。*/
                                     
    0x00,0x04,                      /* Max packet size =1024bytes本端点的最大包大小。
                                      对于bulk为1024，对于同步传输，为0~1024或 1024。 */

    0x00,                           /* Servicing interval for data transfers : 0 for Bulk 
                                    轮训数据传送端点的时间间隔．对于批量传送和控制传送的端点忽 
                                      略。
                                    对于同步传送的端点，取值范围是1-16，对于中断传送的端点，范        
                                    围为1-255 */

    /* Super speed endpoint companion descriptor for producer EP 超高速端点补充描述符 */
    //接口中描述的每个端点后面都有一个超高速端点伙伴描述符 (SuperSpeed Endpoint Companion Descriptor)。
    //超高速端点伙伴描述符 (SuperSpeed Endpoint Companion Descriptor)总是在配置信息中，跟随在与其相关联的端点描述符 (Endpoint Descriptor)之后。它有5个字段，6个字节。

    0x06,                           /* Descriptor size 本描述符大小,固定0x06 */

    CY_U3P_SS_EP_COMPN_DESCR,       /* SS endpoint companion descriptor type 固定0x30 */
  
    BURST_LEN-1,                    /* bMaxBurst: Max number of packets in a burst 端点一            
                                      次突发可以发多少个包
                                     0: burst 1 packet at a time ,一般设置为16，控制端点这 
                                     个地方是0
                                    */

    0x00,                           /* bmAttributes Max streams for bulk EP = 0 (No 
                                     streams) ：见注释1*/
    0x00,0x00,                      /*wBytesPerInterval  Service interval for the EP : 见 
                                     注释2 */
    
// 下面这两个描述符是另外一个端点的 描述符，含义和上一个端点一样，数值不一样
      /* Endpoint descriptor for consumer EP */
    0x07,                           /* Descriptor size */
    CY_U3P_USB_ENDPNT_DESCR,        /* Endpoint descriptor type */
    CY_FX_EP_CONSUMER,              /* Endpoint address and description */
    CY_U3P_USB_EP_BULK,             /* Bulk endpoint type */
    0x00,0x04,                      /* Max packet size = 1024 bytes */
    0x00,                           /* Servicing interval for data transfers : 0 for Bulk 
                                        */

    /* Super speed endpoint companion descriptor for consumer EP */
    0x06,                           /* Descriptor size */
    CY_U3P_SS_EP_COMPN_DESCR,       /* SS endpoint companion descriptor type */
 
    BURST_LEN-1,                    /* Max no. of packets in a burst : 0: burst 1 packet 
                                      at a time */
    0x00,                           /* Max streams for bulk EP = 0 (No streams) */
    0x00,0x00                       /* Service interval for the EP : 0 for bulk */

  
};

注释1 bmAttributes端点的属性。

批量端点：bit[4:0]代表 MaxStreams。即 这个端点支持的流的最大数量。有效值是从 0 到 16，其中值为 0 表示端点没有定义流。对于值 1 至 16，所支持的流等于2^MaxStream。7:5 保留。这些位是保留，并应设置为零。

控制或中断端点：7:0 保留。这些位是保留，并应设置为零。

等时端点(isochronous endpoint)，用于确定服务间隔(service interval)中的最大数据包数。Bits 1…0为 Mult值，其余保留。如果Bits 7 字段的值为0，那么这个Mult（其实是与固件程序中的端点配置isoPck一致，值为isoPck-1）值和bMaxBurst值将一起确定这个端点支持的服务间隔(service interval)内的最大数据包（指的是1024最大负载）数量。最大数据包数 = (bMaxBurst + 1) x (Mult + 1)Mult值的有效值为0到2。如果bMaxBurst字段设置为零，则该字段应设置为零。因此，（同步传输）允许的最大数据包数 = (bMaxBurst + 1) x (Mult + 1) = (15 + 1) × (2 + 1) ＝ 48。当wMaxPacketSize = 1024时，吞吐量为每个服务间隔49152B，就是最大48KB。

  如果每个服务间隔(service interval)传输超过48 KB的SuperSpeedPlus端点使用规范(USB 3.1及以上)中超高速加等时端点伙伴描述符(SuperSpeedPlus Isochronous Endpoint Companion Descriptor)来指定每个服务间隔的最大数据包数。

  在USB3.0中，该字段不受Bits 7 字段的影响。因为Bits 7 字段保留，被设置为0。Bits 6…2保留，这些bits都要设置为0。Bits 7 即SSP ISO Companion(SuperSpeedPlus Isochronous Endpoint Companion)。这个字段用于确认是否使用超高速加等时端点伙伴描述符(SuperSpeedPlus Isochronous Endpoint Companion Descriptor)。如果这个字段被设置为1，那么超高速加等时端点伙伴描述符(SuperSpeedPlus Isochronous Endpoint Companion Descriptor)就应该跟随在该描述符之后出现，并且Bits 1…0的Mult字段无效。实际的Mult应该确定如下：dwBytesPerInterval/bMaxBurst/wMaxPacketSize向上取整到最近的整数值。该字段在USB 3.1中开始被定义，在USB 3.0协议中该字段保留，被设置为0。

注释2 wBytesPerInterval端点

在每个服务间隔(service interval (SI))中将要传输的总字节数。（实际配置0x00,0xB4 //45KB）该字段只对中断(interrupt)和等时(isochronous)端点有效。对于控制(control)和批量(bulk)端点，该字段未使用，被保留的，必须将其设置为零。

如果bmAttributes字段中SSP ISO Companion位的值设置为1（USB3.1），那么这个字段的值应被设置为1，并且这个端点的将要传输的总字节数，应该通过超高速加等时端点伙伴描述符(SuperSpeedPlus Isochronous Endpoint Companion Descriptor)来上报。

2.6 high speed 配置描述符

0x00,0x02, /* Max packet size = 512 bytes */

只有最大包大小不一样，其他都类似

2.7 full speed 配置描述符

0x40,0x00, /* Max packet size = 64 bytes */

只有最大包大小不一样，其他都类似

2.8 语言ID字符串描述符

字符串描述符支持多种语言，所以字符串描述符首先要指定语言ID，简体中文的ID值为0x0804，美式英语ID值为0x0409。

/* Standard language ID string descriptor */
const uint8_t CyFxUSBStringLangIDDscr[] __attribute__ ((aligned (32))) =
{
    0x04,                           /* Descriptor size */
    CY_U3P_USB_STRING_DESCR,        /* Device descriptor type */
    0x09,0x04                       /* Language ID supported */
};

2.9 厂商设备字符串描述符

描述厂商名字的

/* Standard manufacturer string descriptor */
const uint8_t CyFxUSBManufactureDscr[] __attribute__ ((aligned (32))) =
{
    0x10,                           /* Descriptor size */
    CY_U3P_USB_STRING_DESCR,        /* Device descriptor type */
    'C',0x00,
    'y',0x00,
    'p',0x00,
    'r',0x00,
    'e',0x00,
    's',0x00,
    's',0x00
    /*
    Unicode编码字符串．UNICODE采用两个字节字节表示一个字符，如果是英语字符的话，那就很简单了，
    直接在ASCII码前面补上一个为0x00的字节数据就组成UNICODE编码了，如果是其它语言的话，
    网上有很多的UNICODE编码转换工具，可以直接拿来使用就行了。
   
    */
};

2.10 产品字符串描述符

描述厂商具体产品名字的

/* Standard product string descriptor */
const uint8_t CyFxUSBProductDscr[] __attribute__ ((aligned (32))) =
{
    0x08,                           /* Descriptor size */
    CY_U3P_USB_STRING_DESCR,        /* Device descriptor type */
    'F',0x00,
    'X',0x00,
    '3',0x00
     /*
    Unicode编码字符串．UNICODE采用两个字节字节表示一个字符，如果是英语字符的话，那就很简单了，
    直接在ASCII码前面补上一个为0x00的字节数据就组成UNICODE编码了，如果是其它语言的话，
    网上有很多的UNICODE编码转换工具，可以直接拿来使用就行了。
   
    */

2 一些特别说明

这里有些容易混淆的概念

2.1 端点的大小

描述符有中有很多描述端点大小的字节，他们代表的含义不一样

USB3.0 设备描述符中 的是 USB3.0的控制端点0的 最大字节数是512字节

USB2.0 设备描述符中 的是 USB2.0的控制端点0的 最大字节数大小是64字节

而配置描述符中的端点描述符 中 描述的是 本接口中的端点（非控制端点0）的最大字节数，super speed 是1024

2.2 Super / high/ full SPEED

Super Speed:理论速率5Gbps,对应之前的USB3.0

High Speed：理论速度是480Mbps，对应之前的USB2.0；

Full Speed：理论速度是12Mbps，也就是过去的USB1.1；