2019年07月31日 | STM32之三标准外设版USB驱动库详解（架构+文件+函数+使用说明

写在前面

目前，ST的USB驱动有两套，一套是早期的独立版USB驱动，官方培训文档中称为Legacy library；一套为针对其Cube 系列的驱动，根据芯片不同可能有区别，具体见对应芯片的Cube驱动包，官方培训文档中称为Cube library。 本文使用的为Legacy library USB 驱动。更详细的各驱动库版本，请参考博文STM32 之 USB IP（USB模块） 详解。

本文多出自于ST的官方文档 及 2016~2017的培训文档，读者也可以直接去ST官网查阅相关文档。

稍有涉及USB 2.0 规范的内容，关于USB规范去官网或自行Google。也可以参考：

USB之USB2.0 规范详解 第一部分

USB之USB2.0 规范详解 第二部分

关于驱动

  STM32 MCU有两种带USB功能的IP

针对不同的芯片有不同的独立版本驱动（主要是芯片不同，USB的是有区别的）。目前有如下几个：

STSW-STM32046： 主要是针对STM32F105/7, STM32F2 and STM32F4 USB on-the-go Host and device library，对应的说明文档为UM1021。下载地址为https://www.st.com/content/st_com/en/products/embedded-software/mcus-embedded-software/stm32-embedded-software/stm32-standard-peripheral-library-expansion/stsw-stm32046.html，该版本的驱动最新版本为2.2.0。下文就是以该驱动为例。

STSW-STM32121： 主要是针对STM32F10x, STM32L1xx and STM32F3xx USB full speed device library，对应的说明文档为UM0424。

下载地址为https://www.st.com/content/st_com/en/products/embedded-software/mcus-embedded-software/stm32-embedded-software/stm32-standard-peripheral-library-expansion/stsw-stm32121.html，该版本的驱动最新版本为4.0.1。

STSW-STM32092： 主要是针对STM32F0x2xx USB FS device library，对应的说明为UM1717。下载地址为https://www.st.com/content/st_com/en/products/embedded-software/mcus-embedded-software/stm32-embedded-software/stm32-standard-peripheral-library-expansion/stsw-stm32092.html，该版本驱动的最新版本为1.0.0。这里需要注意，该驱动是针对STM32F0x2xx的，但是可以非常方便的移植到STM32F0xx系列得MCU中，需要注意的是，需要根据具体芯片的时钟，修改驱动的usb_conf.h和usb_bsp.c。关于具体的移植可参考网友的该文章USB库STM32F0x2移植到STM32F070笔记

以下文章主要介绍STSW-STM32046。关于STM32 的USB IP，更详细的请参考博文STM32 之 USB IP（USB模块） 详解

驱动结构

  目前，独立版USB驱动并不是支持所有的STM3的芯片，且ST已经不再维护独立版的USB库（被Cube系列取代），具体见驱动源码即可。驱动源码的结构还是比较简单的，主要包含驱动库源码、使用示例、其他实用程序、发行说明文档四大部分。驱动目录结构如下图所示：

  重点在Libraries目录中。其中的USB OTG是USB Device和USB Host 的基础。在实际使用，USB OTG是USB Device和USB Host 的底层驱动。（在一开始学习时，还以为每部分都可以独立使用！！）。

  此外，从上图可看到这个USB库里还带了标准外设库源码。主要是因为之前还没有HAL库。而且ST在Cube系列中，重新实现了所有源码（包括USB驱动）即：HAL库。但是需要说明的是，以上USB库不仅仅可以和标准外设库连用，还可以和HAL库连用。

  本文主要说明USB驱动，同目录下的标准库驱动（其他博文中有详细说明）不再多说。其他部分在实际移植过程中可作为参考，例如各种示例程序等，也不详细介绍。USB驱动的整个驱动库的架构如下图：

USB OTG core

  USB OTG core，即：STM32芯片内嵌的USB OTG 控制器。 STM32F105/07xx器件内嵌了一个USB OTG FS内核，而STM32F2xx和STM32F4xx器件内嵌了一个USB OTG FS内核和一个HS内核。 见下图：

比较如下：

  USB芯片也分为Controller部分和PHY部分。Controller部分主要实现USB的协议和控制。内部逻辑主要有MAC层、CSR层和FIFO控制层，还有其他低功耗管理之类层次。MAC实现按USB协议进行数据包打包和解包，并把数据按照UTMI总线格式发送给PHY（USB3.0为PIPE）。CSR层进行寄存器控制，软件对USB芯片的控制就是通过CSR寄存器，这部分和CPU进行交互访问，主要作为Slave通过AXI或者AHB进行交互。FIFO控制层主要是和DDR进行数据交互，控制USB从DDR搬运数据的通道，主要作为Master通过AXI/AHB进行交互。PHY部分功能主要实现并转串的功能，把UTMI或者PIPE口的并行数据转换成串行数据，再通过差分数据线输出到芯片外部。

  一般来说，如果usb phy封装在芯片内，基本采用UTMI+的接口。不封装到芯片内的一般采用ULPI接口，这样可以降低pin的数量。

  关于STM32芯片内嵌的OTG FS控制器、OTG HS控制器、OTG FS PHY具体见芯片手册。

某网友的 usb 的phy 协议发展历程

USB OTG full speed core

  OTG_FS 是一款双角色设备(DRD) 控制器，同时支持从机功能和主机功能，完全符合USB 2.0 规范的On-The-Go 补充标准。此外，该控制器也可配置为“仅主机”模式或“仅从机”模式，完全符合USB 2.0 规范。在主机模式下，OTG_FS 支持全速（FS，12 Mb/s）和低速（LS，1.5 Mb/s）收发器，而从机模式下则仅支持全速（FS，12 Mb/s）收发器。OTG_FS 同时支持HNP 和SRP。主机模式下需要的唯一外部设备是提供VBUS的电荷泵。其硬件框图如下

  OTG_FS支持HNP（主机协商协议）和SRP（会话请求协议）。 唯一需要的外部设备是Host模式下VBUS电源的电荷泵。

OTG_FS 接口的通用特性如下：

经USB-IF 认证，符合通用串行总线规范第2.0 版

模块内嵌的PHY 还完全支持定义在标准规范OTG 补充第1.3 版中的OTG 协议

支持A-B 器件识别（ID 线）

支持主机协商协议(HNP) 和会话请求协议(SRP)

允许主机关闭VBUS以在OTG 应用中节省电池电量

支持通过内部比较器对VBUS电平采取监控

支持主机到从机的角色动态切换

可通过软件配置为以下角色：

具有SRP 功能的USB FS 从机（B 器件）

具有SRP 功能的USB FS/LS 主机（A 器件）

USB On-The-Go 全速双角色设备

支持FS SOF 和LS Keep-alive 令牌

SOF 脉冲可通过PAD 输出

SOF 脉冲从内部连接到定时器2 (TIM2)

可配置的帧周期

可配置的帧结束中断

具有省电功能，例如在USB 挂起期间停止系统、关闭数字模块时钟、对PHY 和DFIFO电源加以管理

具有采用高级FIFO 控制的1.25 KB 专用RAM

可将RAM 空间划分为不同FIFO，以便灵活有效地使用RAM

每个FIFO 可存储多个数据包

动态分配存储区

FIFO 大小可配置为非2 的幂次方值，以便连续使用存储单元

一帧之内可以无需要应用程序干预，以达到最大USB 带宽

OTG_FS 接口在主机模式下具有以下主要特性和要求：

通过外部电荷泵生成VBUS电压。

多达8 个主机通道（管道）：每个通道都可以动态实现重新配置，可支持任何类型的USB 传输。

内置硬件调度器可：

在周期性硬件队列中存储多达8 个中断加同步传输请求

在非周期性硬件队列中存储多达8 个控制加批量传输请求

管理一个共享RX FIFO、一个周期性TX FIFO 和一个非周期性TX FIFO，以有效使用USB 数据RAM。

OTG_FS 接口在从机模式下具有以下特性：

1 个双向控制端点0

3 个IN 端点(EP)，可配置为支持批量传输、中断传输或同步传输

3 个OUT 端点，可配置为支持批量传输、中断传输或同步传输

管理一个共享Rx FIFO 和一个Tx-OUT FIFO，以高效使用USB 数据RAM

管理多达4 个专用Tx-IN FIFO（分别用于每个使能的IN EP），降低应用程序负荷

支持软断开功能。

关于该部分的详细说明，参见芯片的参考手册第34节：USB on-the-go full-speed (OTG_FS)

USB OTG high speed core

  OTG_HS 是一个双角色设备(DRD) 控制器，同时支持从机和主机功能，并且完全符合USB 2.0 规范的On-The-Go 补充标准。此外，该控制器也可配置为仅主机或仅从机控制器，完全符合USB 2.0 规范。在主机模式中，OTG_HS 支持高速（HS，480 Mbits/s）、全速（FS、12 Mbits/s）和低速（LS，1.5 Mbits/s）传输，而在从机模式中，仅支持高速（HS，480 Mbits/s）和全速（FS、12 Mbits/s）传输。OTG_HS 还支持HNP 和SRP。OTG 模式下需要的唯一外部设备是提供VBUS 的电荷泵。

USB DMA 不支持内部Flash寻址

OTG_HS支持HNP（主机协商协议）和SRP（会话请求协议）。 所需的唯一外部设备是OTG模式下VBUS电源的电荷泵。

OTG_HS 接口的通用特性如下：

经USB-IF 认证，符合通用串行总线规范2.0 版本

支持3 个PHY 接口

片上全速PHY

连接外部全速PHY 的I2 C 接口

连接外部高速PHY 的ULPI 接口

支持主机协商协议(HNP) 和会话请求协议(SRP)

在OTG 应用中允许主机关闭VBUS以节省功耗，而不需要外部组件

允许使用内部比较器来监视VBUS电平

支持主机和从机之间的动态角色切换

可通过软件配置为以下角色：

支持SRP 的USB HS/FS 从机（B 器件）

支持SRP 的USB HS/FS/LS 主机（A 器件）

USB OTG FS 双角色设备

支持HS/FS SOF 以及低速(LS)“Keep-alive”令牌并具有如下功能：

SOF 脉冲引脚输出功能

SOF 脉冲与定时器2 (TIM2) 的内部连接

可配置的帧周期

可配置的帧结束中断

模块内嵌DMA，并可软件配置AHB 的突发传输类型

具备省电功能，例如在USB 挂起期间停止系统时钟，关闭数字模块内部时钟域、PHY 和DFIFO 电源管理

具有包含高级FIFO 管理的专用4K 字节数据RAM：

可以将存储区配置为不同FIFO，以便灵活高效地使用RAM

每个FIFO 可包含多个数据包

动态地进行存储器分配

FIFO 大小可配置为2 的幂以外的值，以便连续使用存储区

一帧之内可以无需要应用程序干预，以达到最大USB 带宽

主机模式下的OTG_HS 接口特征如下：

需要外部电荷泵来生成VBUS

具有多达12 个主机通道（管道），每个通道可动态地进行重新配置，可支持任何类型的USB 传输

内置硬件调度器：

在周期性硬件队列中存储多达8 个中断加同步传输请求

在非周期性硬件队列中存储多达8 个控制加批量传输请求

管理一个共享RX FIFO、一个周期性TX FIFO 和一个非周期性TX FIFO，以有效使用USB 数据RAM

在主机模式下具备对SOF 帧周期进行动态调校的功能

OTG_HS 接口在从机模式下具有以下特性：

具有1 个双向控制端点0

具有5 个IN 端点(EP)，可配置为支持批量、中断或同步传输

具有5 个OUT 端点，可配置为支持批量、中断或同步传输

管理一个共享Rx FIFO 和一个Tx-OUT FIFO，可高效使用USB 数据RAM

管理多达6 个专用Tx-IN FIFO（每个IN 配置的EP 使用一个）以降低应用程序负载

具备软断开功能

关于该部分的详细说明，参见芯片的参考手册第35节：USB on-the-go high-speed (OTG_HS)

USB OTG low level driver files

  USB OTG驱动源码目录结构及代码架构如下图所示：

模块 文件 说明

Common usb_core.c/h 该文件包含硬件抽象层和USB通信操作

Common usb_conf_template.h 该文件包含主机、设备和OTG模式的核心配置参数：发送FIFO大小，接收FIFO大小，核心模式和选定功能等。*用户需要根据自己的需求，使用这个文件对USB OTG low level driver进行合理的配置。这个文件应该被复制到应用程序文件夹并根据应用程序的需要进行修改。

Common usb_bsp_template.c 该文件包含了USB使用的低级核心配置（中断、GPIO等）。用户需要使用这个文件配置USB使用的硬件资源。这个文件应该被复制到应用程序文件夹并根据应用程序的需要进行修改。

Host usb_hcd.c/h 该文件包含USB_HOST_Library访问核心时使用的Host接口层。

Host usb_hcd_int.c/h 该文件包含Host模式所使用的中断子程序。

Device usb_dcd.c/h 该文件包含USB_HOST_DEvice用于访问核心时使用的的Device接口层。

Device usb_dcd_int.c/h 该文件包含Device模式的中断子程序。

OTG usb_otg.c/h 该文件包含SRP和HNP协议的实现以及有关于OTG模式的中断。

USB OTG low level driver 配置

  USB OTG low level driver 配置是通过一个名为usb_conf.h的配置文件进行配置的。在实际的移植过程中，可以复制源码中的usb_conf_template.h然后更名为usb_conf.h，然后编辑修改即可。具体可配置的项目见下表：

定义 描述

USB_OTG_FS_CORE 使能内核的全速模式

USB_OTG_HS_CORE 使能内核的高速模式

RX_FIFO_FS_SIZE 设置全速模式下接收的FIFO的大小

RX_FIFO_HS_SIZE 设置高速模式下接收的FIFO的大小

TXn_FIFO_FS_SIZE 设置全速模式下指定设备端点的发送FIFO的大小，n 为设备的端点号使用的索引值

TXn_FIFO_HS_SIZE 设置高速模式下指定设备端点的发送FIFO的大小，n 为设备的端点号使用的索引值

TXH_NP_FS_FIFOSIZ 设置全速模式下，作为USB Host时，非周期性发送的FIFO的大小

TXH_NP_HS_FIFOSIZ 设置高速模式下，作为USB Host时，非周期性发送的FIFO的大小

TXH_P_FS_FIFOSIZ 设置全速模式下，作为USB Host时，周期性发送的FIFO的大小

TXH_P_HS_FIFOSIZ 设置高速模式下，作为USB Host时，周期性发送的FIFO的大小

USB_OTG_ULPI_PHY_ENABLED 为高速模式使能ULPI接口的PHY。通常为外接的PHY芯片

USB_OTG_EMBEDDED_PHY_ENABLED 为高速模式芯片内嵌的FS PHY。一般STM32系列芯片内嵌了一个PHY芯片。芯片不同其PHY的对于全速和高速的支持情况也不同

USB_OTG_HS_LOW_PWR_MGMT_SUPPORT 使能高速模式下的低功耗管理功能

USB_OTG_FS_LOW_PWR_MGMT_SUPPORT 使能全速模式下的低功耗管理功能

USB_OTG_HS_INTERNAL_DMA_ENABLED 使能高速模式下的DMA特性

USB_OTG_HS_DEDICATED_EP1_ENABLED 使能高速模式下，作为USB Device时，专用的端点1的特性

USB OTG low level driver 使用

  在USB OTG low level driver的使用中，配置选项均在usb_conf.h中。除此之外，对于某些变量的定义也有如下需要注意的事项。

The Rx and Tx FIFOs size and start address are set inside this function to use one more endpoints in addition to the control Endpoint (0). The user can change the FIFO settings by modifying the default values and changing the FIFO depth for each Tx FIFO in the usb_conf.h file.

Low level driver structures

该部分使用一个结构体USB_OTG_CORE_HANDLE来定义需要使用的变量、状态和缓冲区等。这个结构体也是用户在使用时需要重点关注的第一个结构体。具体如下：

typedef struct USB_OTG_handle

{

  USB_OTG_CORE_CFGS    cfg;

  USB_OTG_CORE_REGS    regs;

#ifdef USE_DEVICE_MODE

  DCD_DEV     dev;

#endif

#ifdef USE_HOST_MODE

  HCD_DEV     host;

#endif

#ifdef USE_OTG_MODE

  OTG_DEV     otg;

#endif

}

USB_OTG_CORE_HANDLE , *PUSB_OTG_CORE_HANDLE;

同时在使用DMA时，需要注意：

目前，DMA仅在高速模式下使用。

在使用DMA时，必须要保证所有需要处理DMA 收发Buf的结构体必须是四字节对齐的。所以，USB_OTG_handle(其封装了所有内部Buffer和变量)必须要四字节对齐。具体可使用如下代码：

#ifdef USB_OTG_HS_INTERNAL_DMA_ENABLED

  #if defined ( __ICCARM__ ) /*!< IAR Compiler */

    #pragma data_alignment=4   

  #endif

#endif /* USB_OTG_HS_INTERNAL_DMA_ENABLED */

__ALIGN_BEGIN USB_OTG_CORE_HANDLE USB_OTG_Core __ALIGN_END;

__ALIGN_BEGIN和__ALIGN_END为特殊的编译器宏值，具体见usb_conf_template.h的定义。

USB OTG low level driver中的Host层

  该部分主要是指usb_hcd.c/h和usb_hcd_int.c/h两个文件。在初始化主机驱动程序（HCD）之后，低级驱动程序为数据和URB状态监视保存多个结构和缓冲区。 主机通道结构保存在主机驱动程序中，并通过主机号索引从上层访问。USB Host 的定义结构：

typedef struct _HCD

{

  uint8_t                  Rx_Buffer [MAX_DATA_LENGTH];  /* 此缓冲区保存IN数据包，并可以从全局主机核心结构直接访问，如下所示：pdev-> host.Rx_Buffer。*/

  __IO uint32_t            ConnSts; /* 连接状态。 它可以直接或通过使用HCD_IsDeviceConnected（）函数进行访问。 */

  __IO uint32_t            PortEnabled;  /* */

  __IO uint32_t            ErrCnt[USB_OTG_MAX_TX_FIFOS];  /* 在一次传输过程中保存通道上的错误数量。 */

  __IO uint32_t            XferCnt[USB_OTG_MAX_TX_FIFOS]; /* 保存已在Rx_Buffer中接收和可用的IN数据的数量。 它可以直接访问或使用GetXferCnt（）函数访问。*/

  __IO HC_STATUS           HC_Status[USB_OTG_MAX_TX_FIFOS];  /* 由驱动程序内部使用。 可被上层访问。它保存一个通道上的当前传输的状态 */

  __IO URB_STATE           URB_State[USB_OTG_MAX_TX_FIFOS]; /* 该变量保持主机通道上的传输状态。*/

  USB_OTG_HC               hc [USB_OTG_MAX_TX_FIFOS]; 

  uint16_t                 channel [USB_OTG_MAX_TX_FIFOS]; /* 这个变量管理主机通道状态（使用或空闲）。 */

}

HCD_DEV , *USB_OTG_USBH_PDEV;

usb_hcd_int.c/h文件中使用如下结构来处理USB中断

typedef struct _USBH_HCD_INT

{

  uint8_t (* SOF) (USB_OTG_CORE_HANDLE *pdev);

  uint8_t (* DevConnected) (USB_OTG_CORE_HANDLE *pdev);

  uint8_t (* DevDisconnected) (USB_OTG_CORE_HANDLE *pdev);

  uint8_t (* DevPortEnabled) (USB_OTG_CORE_HANDLE *pdev);  

  uint8_t (* DevPortDisabled) (USB_OTG_CORE_HANDLE *pdev); 

}USBH_HCD_INT_cb_TypeDef;

extern USBH_HCD_INT_cb_TypeDef *USBH_HCD_INT_fops;