CMSIS-Driver  版本 2.6.0
中间件和应用程序代码的外设接口
 全部 数据结构 文件 函数 变量 类型定义 枚举 枚举   页面
USB 设备接口

USB 设备外设的驱动程序 API(Driver_USBD.h) 更多...

内容

 USBD 设备事件
 USB 设备驱动程序生成通过函数 ARM_USBD_SignalDeviceEvent 通知的设备回调事件。
 
 USBD 端点事件
 USB 设备驱动程序生成通过函数 ARM_USBD_SignalEndpointEvent 通知的端点回调事件。
 

数据结构

struct  ARM_DRIVER_USBD
 USB 设备驱动程序的访问结构。更多...
 
struct  ARM_USBD_CAPABILITIES
 USB 设备驱动程序功能。更多...
 
struct  ARM_USBD_STATE
 USB 设备状态。更多...
 

类型定义

typedef void(* ARM_USBD_SignalDeviceEvent_t )(uint32_t event)
 指向 ARM_USBD_SignalDeviceEvent 的指针:发出 USB 设备事件信号。更多...
 
typedef void(* ARM_USBD_SignalEndpointEvent_t )(uint8_t ep_addr, uint32_t event)
 指向 ARM_USBD_SignalEndpointEvent 的指针:发出 USB 端点事件信号。更多...
 

函数

ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
 获取驱动版本。更多...
 
ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
 获取驱动程序功能。更多...
 
int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 初始化 USB 设备接口。更多...
 
int32_t ARM_USBD_Uninitialize (void)
 取消初始化 USB 设备接口。更多...
 
int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
 控制 USB 设备接口电源。更多...
 
int32_t ARM_USBD_DeviceConnect (void)
 连接 USB 设备。更多...
 
int32_t ARM_USBD_DeviceDisconnect (void)
 断开 USB 设备。更多...
 
ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
 获取当前的 USB 设备状态。更多...
 
int32_t ARM_USBD_DeviceRemoteWakeup (void)
 触发 USB 远程唤醒。更多...
 
int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
 设置 USB 设备地址。更多...
 
int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 读取通过控制端点接收到的设置数据包。更多...
 
int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
 配置 USB 端点。更多...
 
int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 取消配置 USB 端点。更多...
 
int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 为 USB 端点设置/清除停顿。更多...
 
int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 从 USB 端点读取数据或将数据写入 USB 端点。更多...
 
uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 获取 USB 端点传输的结果。更多...
 
int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 终止当前的 USB 端点传输。更多...
 
uint16_t ARM_USBD_GetFrameNumber (void)
 获取当前的 USB 帧号。更多...
 
void ARM_USBD_SignalDeviceEvent (uint32_t event)
 信号 USB 设备事件。更多...
 
void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event)
 信号 USB 端点事件。 更多...
 

描述

USB 设备外设的驱动程序 API(Driver_USBD.h)

USB 设备 API

头文件 Driver_USBD.h 定义了中间件组件使用的 USB 设备驱动程序接口的 API。驱动程序实现本身是设备系列包的典型部分,它在结构 ARM_DRIVER_USBD 中将函数指针作为接口的入口点。该结构可以在每个接口中多次使用,以控制多个 USBD 接口。

头文件 Driver_USBD.h 还定义了可以分类为设备事件回调端点事件回调的回调例程。回调由驱动程序在发生适当事件的中断环境中调用,以发出设备相关事件(USBD 设备事件)和端点相关事件(USBD 端点事件)的信号。

USB 设备功能调用序列

要使用 USBD 驱动程序,请按以下顺序调用 API 函数:

msc_inline_mscgraph_2

数据结构文档

struct ARM_DRIVER_USBD

USB 设备驱动程序的访问结构体。

USB 设备驱动程序的功能可以通过函数指针访问。有关概述信息,请参阅通用驱动程序功能

USBD 的每个实例都提供了这样的访问结构体。该实例由访问结构体的符号名称中的后缀指示,例如:

  • Driver_USBD0 是第一个实例(编号 0)的访问结构体的名称。
  • Driver_USBD1 是第二个实例(编号 1)的访问结构体的名称。

中间件中的配置设置允许将中间件连接到特定的驱动程序实例 Driver_USBDn。缺省值是 0,它将中间件连接到驱动程序的第一个实例。

注意
结构体必须保持不变。

数据字段

ARM_DRIVER_VERSION(* GetVersion )(void)
 指向 ARM_USBD_GetVersion 的指针:获取驱动程序版本。更多...
 
ARM_USBD_CAPABILITIES(* GetCapabilities )(void)
 指向 ARM_USBD_GetCapabilities 的指针:获取驱动程序功能。更多...
 
int32_t(* Initialize )(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 指向 ARM_USBD_Initialize 的指针:初始化 USB 设备接口。更多...
 
int32_t(* Uninitialize )(void)
 指向 ARM_USBD_Uninitialize 的指针:取消初始化 USB 设备接口。更多...
 
int32_t(* PowerControl )(ARM_POWER_STATE state)
 指向 ARM_USBD_PowerControl 的指针:控制 USB 设备接口电源。更多...
 
int32_t(* DeviceConnect )(void)
 指向 ARM_USBD_DeviceConnect 的指针:连接 USB 设备。更多...
 
int32_t(* DeviceDisconnect )(void)
 指向 ARM_USBD_DeviceDisconnect 的指针:断开 USB 设备。更多...
 
ARM_USBD_STATE(* DeviceGetState )(void)
 指向 ARM_USBD_DeviceGetState 的指针:获取当前的 USB 设备状态。更多...
 
int32_t(* DeviceRemoteWakeup )(void)
 指向 ARM_USBD_DeviceRemoteWakeup 的指针:触发 USB 远程唤醒。更多...
 
int32_t(* DeviceSetAddress )(uint8_t dev_addr)
 指向 ARM_USBD_DeviceSetAddress 的指针:设置 USB 设备地址。更多...
 
int32_t(* ReadSetupPacket )(uint8_t *setup)
 指向 ARM_USBD_ReadSetupPacket 的指针:读取通过控制端点接收到的设置数据包。更多...
 
int32_t(* EndpointConfigure )(uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
 指向 ARM_USBD_EndpointConfigure 的指针:配置 USB 端点。更多...
 
int32_t(* EndpointUnconfigure )(uint8_t ep_addr)
 指向 ARM_USBD_EndpointUnconfigure 的指针:取消配置 USB 端点。更多...
 
int32_t(* EndpointStall )(uint8_t ep_addr, bool stall)
 指向 ARM_USBD_EndpointStall 的指针:设置/清除 USB 端点的停顿。更多...
 
int32_t(* EndpointTransfer )(uint8_t ep_addr, uint8_t *data, uint32_t num)
 指向 ARM_USBD_EndpointTransfer 的指针:从 USB 端点读取数据或将数据写入 USB 端点。更多...
 
uint32_t(* EndpointTransferGetResult )(uint8_t ep_addr)
 指向 ARM_USBD_EndpointTransferGetResult 的指针:获取 USB 端点传输的结果。更多...
 
int32_t(* EndpointTransferAbort )(uint8_t ep_addr)
 指向 ARM_USBD_EndpointTransferAbort 的指针:终止当前的 USB 端点传输。更多...
 
uint16_t(* GetFrameNumber )(void)
 指向 ARM_USBD_GetFrameNumber 的指针:获取当前的 USB 帧号。更多...
 

现场文档

ARM_DRIVER_VERSION(* GetVersion)(void)

指向 ARM_USBD_GetVersion 的指针:获取驱动程序版本。

ARM_USBD_CAPABILITIES(* GetCapabilities)(void)

指向 ARM_USBD_GetCapabilities 的指针:获取驱动程序功能。

int32_t(* Initialize)(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)

指向 ARM_USBD_Initialize 的指针:初始化 USB 设备接口。

int32_t(* Uninitialize)(void)

指向 ARM_USBD_Uninitialize 的指针:取消初始化 USB 设备接口。

int32_t(* PowerControl)(ARM_POWER_STATE state)

指向 ARM_USBD_PowerControl 的指针:控制 USB 设备接口电源。

int32_t(* DeviceConnect)(void)

指向 ARM_USBD_DeviceConnect 的指针:连接 USB 设备。

int32_t(* DeviceDisconnect)(void)

指向 ARM_USBD_DeviceDisconnect 的指针:断开 USB 设备。

ARM_USBD_STATE(* DeviceGetState)(void)

指向 ARM_USBD_DeviceGetState 的指针:获取当前的 USB 设备状态。

int32_t(* DeviceRemoteWakeup)(void)

指向 ARM_USBD_DeviceRemoteWakeup 的指针:触发 USB 远程唤醒。

int32_t(* DeviceSetAddress)(uint8_t dev_addr)

指向 ARM_USBD_DeviceSetAddress 的指针:设置 USB 设备地址。

int32_t(* ReadSetupPacket)(uint8_t *setup)

指向 ARM_USBD_ReadSetupPacket 的指针:读取通过控制端点接收到的设置数据包。

int32_t(* EndpointConfigure)(uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)

指向 ARM_USBD_EndpointConfigure 的指针:配置 USB 端点。

int32_t(* EndpointUnconfigure)(uint8_t ep_addr)

指向 ARM_USBD_EndpointUnconfigure 的指针:取消配置 USB 端点。

int32_t(* EndpointStall)(uint8_t ep_addr, bool stall)

指向 ARM_USBD_EndpointStall 的指针:设置/清除 USB 端点的停顿。

int32_t(* EndpointTransfer)(uint8_t ep_addr, uint8_t *data, uint32_t num)

指向 ARM_USBD_EndpointTransfer 的指针:从 USB 端点读取数据或将数据写入 USB 端点。

uint32_t(* EndpointTransferGetResult)(uint8_t ep_addr)

指向 ARM_USBD_EndpointTransferGetResult 的指针:获取 USB 端点传输的结果。

int32_t(* EndpointTransferAbort)(uint8_t ep_addr)

指向 ARM_USBD_EndpointTransferAbort 的指针:终止当前的 USB 端点传输。

uint16_t(* GetFrameNumber)(void)

指向 ARM_USBD_GetFrameNumber 的指针:获取当前的 USB 帧号。

struct ARM_USBD_CAPABILITIES

USB 设备驱动程序功能。

USB 设备驱动程序可以用不同的功能来实现。此结构体的数据字段对由此驱动程序实现的功能进行编码。

返回者:

注意
结构体必须保持不变。
数据字段
uint32_t vbus_detection: 1 VBUS 检测。
uint32_t event_vbus_on: 1 信号 VBUS 开启事件。
uint32_t event_vbus_off: 1 信号 VBUS 关闭事件。
uint32_t reserved: 29 保留(必须为零)
struct ARM_USBD_STATE

USB 设备状态。

该结构体存储有关 USB 设备状态的信息。数据字段对建立的速度进行编码,无论设备是否通电并处于活动状态。

返回者:

数据字段
uint32_t vbus: 1 USB 设备 VBUS 标志。
uint32_t speed: 2 USB 设备速度设置(ARM_USB_SPEED_xxx)
uint32_t active: 1 USB 设备活动标志。
uint32_t reserved: 28

类型定义文档

ARM_USBD_SignalDeviceEvent_t

指向 ARM_USBD_SignalDeviceEvent 的指针:发出 USB 设备事件信号。

为回调函数 ARM_USBD_SignalDeviceEvent 提供类型定义。

参数用于:

ARM_USBD_SignalEndpointEvent_t

指向 ARM_USBD_SignalEndpointEvent 的指针:发出 USB 端点事件信号。

为回调函数 ARM_USBD_SignalEndpointEvent 提供类型定义。

参数用于:

函数文档

ARM_DRIVER_VERSION ARM_USBD_GetVersion ( void  )

获取驱动版本。

返回
ARM_DRIVER_VERSION

函数 ARM_USBD_GetVersion 返回 ARM_DRIVER_VERSION 中驱动程序实现的版本信息

  • API 版本是用于实现此驱动程序的 CMSIS-Driver 规范的版本。
  • 驱动程序版本是实际驱动程序实现的源代码版本。

示例:

extern ARM_DRIVER_USBD Driver_USBD0;
ARM_DRIVER_USBD *drv_info;
void setup_usbd (void) {
drv_info = &Driver_USBD0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities ( void  )

获取驱动程序功能。

返回
ARM_USBD_CAPABILITIES

函数 ARM_USBD_GetCapabilities 返回有关此驱动程序实现中功能的信息。结构体 ARM_USBD_CAPABILITIES 的数据字段对各种功能进行编码,例如,如果硬件可以使用 ARM_USBD_SignalDeviceEvent 回调函数创建信号事件。

示例:

extern ARM_DRIVER_USBD Driver_USBD0;
ARM_DRIVER_USBD *drv_info;
void read_capabilities (void) {
ARM_USBD_CAPABILITIES drv_capabilities;
drv_info = &Driver_USBD0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
int32_t ARM_USBD_Initialize ( ARM_USBD_SignalDeviceEvent_t  cb_device_event,
ARM_USBD_SignalEndpointEvent_t  cb_endpoint_event 
)

初始化 USB 设备接口。

参数
[in]cb_device_event指向 ARM_USBD_SignalDeviceEvent 的指针
[in]cb_endpoint_event指向 ARM_USBD_SignalEndpointEvent 的指针
返回
状态错误代码

函数 ARM_USBD_Initialize 初始化 USB 设备接口。当中间件组件开始操作时调用它。

该功能执行以下操作:

参数 cb_device_event 是一个指向 ARM_USBD_SignalDeviceEvent 回调函数的指针; 当不需要设备回调信号时使用 NULL 指针。
参数 cb_endpoint_event 是一个指向 ARM_USBD_SignalEndpointEvent 回调函数的指针。

示例:

int32_t ARM_USBD_Uninitialize ( void  )

取消初始化 USB 设备接口。

返回
状态错误代码

ARM_USBD_Uninitialize 函数取消初始化 USBD 接口的资源。

当中间件组件停止操作并释放接口使用的软件资源时调用它。

int32_t ARM_USBD_PowerControl ( ARM_POWER_STATE  state)

控制 USB 设备接口电源。

参数
[in]state电源状态
返回
状态错误代码

功能 ARM_USBD_PowerControl 操作 USB 设备接口的电源模式。

参数 state 设置操作并可具有以下值:

  • ARM_POWER_FULL : 用于数据传输的设置外设,启用中断(NVIC)和可选的 DMA。可以多次调用。如果外设已经处于此模式,则该功能不执行任何操作,并返回 ARM_DRIVER_OK
  • ARM_POWER_LOW : 可能会使用省电功能。未实现时返回 ARM_DRIVER_ERROR_UNSUPPORTED
  • ARM_POWER_OFF : 终止任何未决数据传输,禁用外设,禁用相关中断和 DMA。

有关更多信息,请参阅函数调用序列

int32_t ARM_USBD_DeviceConnect ( void  )

连接 USB 设备。

参数
状态错误代码

功能 ARM_USBD_DeviceConnect 发信号给设备连接的主机。

int32_t ARM_USBD_DeviceDisconnect ( void  )

断开 USB 设备。

返回
状态错误代码

函数 ARM_USBD_DeviceDisconnect 向主机发送信号,表明设备已断开连接。

ARM_USBD_STATE ARM_USBD_DeviceGetState ( void  )

获取当前的 USB 设备状态。

返回
设备状态 ARM_USBD_STATE

检索当前的 USB 设备状态。

int32_t ARM_USBD_DeviceRemoteWakeup ( void  )

触发 USB 远程唤醒。

返回
状态错误代码

ARM_USBD_DeviceRemoteWakeup 函数向主机发送远程唤醒信号。

int32_t ARM_USBD_DeviceSetAddress ( uint8_t  dev_addr)

设置 USB 设备地址。

参数
[in]dev_addr设备地址
返回
状态错误代码

为设备分配一个地址。

int32_t ARM_USBD_ReadSetupPacket ( uint8_t *  setup)

读取通过控制端点接收到的设置数据包。

参数
[out]setup指向设置数据包的缓冲区的指针
返回
状态错误代码

函数 ARM_USBD_ReadSetupPacket 读取通过由 ARM_USBD_EVENT_SETUP 事件指示的控制端点(端点 0)接收的最后一个 SETUP 数据包(8 个字节)。

参见:

int32_t ARM_USBD_EndpointConfigure ( uint8_t  ep_addr,
uint8_t  ep_type,
uint16_t  ep_max_packet_size 
)

配置 USB 端点。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
[in]ep_type端点类型(ARM_USB_ENDPOINT_xxx)
[in]ep_max_packet_size端点最大数据包大小
返回
状态错误代码

函数 ARM_USBD_EndpointConfigure 配置传输的端点。

int32_t ARM_USBD_EndpointUnconfigure ( uint8_t  ep_addr)

取消配置 USB 端点。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
返回
状态错误代码

函数 ARM_USBD_EndpointUnconfigure 取消配置指定的端点。

参数 ep_addr 指定端点地址。

int32_t ARM_USBD_EndpointStall ( uint8_t  ep_addr,
bool  stall 
)

为 USB 端点设置/清除停顿。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
[in]stall操作
  • false 清除
  • true 设置
返回
状态错误代码

函数 ARM_USBD_EndpointStall 设置或清除指定端点的停顿条件。

参数 ep_addr 指定端点地址。
参数 stall 是一个布尔参数。

int32_t ARM_USBD_EndpointTransfer ( uint8_t  ep_addr,
uint8_t *  data,
uint32_t  num 
)

从 USB 端点读取数据或将数据写入 USB 端点。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
[out]data指向数据读取或写入数据的缓冲区
[in]num传输的数据字节数
返回
状态错误代码

函数 ARM_USBD_EndpointTransfer 读取或写入数据到 USB 端点。

参数 ep_addr 指定端点地址。
参数 data 是要读取数据或写入数据的缓冲区。
参数 num 是要传输的字节数(必须是读取传输的端点最大数据包大小的倍数)。

该功能是非阻塞的,只要驱动程序在指定的端点上开始操作,就会立即返回。在操作期间,不允许在同一端点再次调用该函数。此外,数据缓冲区必须保持分配状态,并且数据内容不得修改。

端点地址中的方向指定传输的类型:

  • OUT 端点的端点读取(方向 = 0)
  • IN 端点的端点写入(方向 = 1)

当接收到所请求的数据字节数时或接收到短包或 ZLP(零长度包)时,端点读取完成。操作完成由 ARM_USBD_EVENT_OUT 事件指示。通过调用 ARM_USBD_EndpointTransferGetResult 可以检索成功接收的数据字节数。

当发送请求的数据字节数时,端点写入完成。操作完成由 ARM_USBD_EVENT_IN 事件指示。通过调用 ARM_USBD_EndpointTransferGetResult 可以检索成功发送的数据字节数。

通过调用 ARM_USBD_EndpointTransferAbort 可以中止传输操作。

uint32_t ARM_USBD_EndpointTransferGetResult ( uint8_t  ep_addr)

获取 USB 端点传输的结果。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
返回
成功传输的数据字节数

函数 ARM_USBD_EndpointTransferGetResult 返回由 ARM_USBD_EndpointTransfer 启动的成功传输的数据字节数。

参数 ep_addr 指定端点地址。

int32_t ARM_USBD_EndpointTransferAbort ( uint8_t  ep_addr)

终止当前的 USB 端点传输。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
返回
状态错误代码

函数 ARM_USBD_EndpointTransferAbort 将传输中止到由 ARM_USBD_EndpointTransfer 启动的端点。

参数 ep_addr 指定端点地址。

uint16_t ARM_USBD_GetFrameNumber ( void  )

获取当前的 USB 帧号。

返回
帧号

检索最后一帧开始(SOF)数据包的顺序 11 位帧号。

void ARM_USBD_SignalDeviceEvent ( uint32_t  event)

信号 USB 设备事件。

参数
[in]eventUSBD 设备事件
返回
没有

函数 ARM_USBD_SignalDeviceEvent 是由函数 ARM_USBD_Initialize 注册的回调函数。

参数 event 表示在驱动程序操作期间发生的一个或多个事件。每个事件都在一个单独的位中编码,因此可以在同一个呼叫中发出多个事件的信号。

并非每个事件都必须由驱动程序生成。这取决于存储在结构体 ARM_USBD_CAPABILITIES 的数据字段中的已实现的功能,可以使用功能 ARM_USBD_GetCapabilities 检索功能。

可以生成以下事件:

事件描述支持时 ARM_USBD_CAPABILITIES
ARM_USBD_EVENT_VBUS_ON 0 当检测到有效的 VBUS 电压时发生。数据字段 event_vbus_on = 1
ARM_USBD_EVENT_VBUS_OFF 1 当 VBUS 电压关闭时发生。数据字段 event_vbus_off = 1
ARM_USBD_EVENT_RESET 2 当检测到 USB 重置时发生。始终支持
ARM_USBD_EVENT_HIGH_SPEED 3 当 USB 设备切换到高速时发生。始终支持
ARM_USBD_EVENT_SUSPEND 4 在检测到 USB 暂停时发生。始终支持
ARM_USBD_EVENT_RESUME 5 在检测到 USB 恢复时发生。始终支持
void ARM_USBD_SignalEndpointEvent ( uint8_t  ep_addr,
uint32_t  event 
)

信号 USB 端点事件。

参数
[in]ep_addr端点地址
  • ep_addr.0..3: 地址
  • ep_addr.7: 方向
[in]eventUSBD 端点事件
返回
没有

函数 ARM_USBD_SignalEndpointEvent 是由函数 ARM_USBD_Initialize 注册的回调函数。

参数 ep_addr 指定端点。
参数 event 表示在驱动程序操作过程中发生的一个或多个事件。每个事件都在一个单独的位中编码,因此可以在同一个呼叫中发出多个事件的信号。

可以生成以下事件:

事件描述
ARM_USBD_EVENT_SETUP 0 在通过控制端点接收到 SETUP 数据包时发生。
ARM_USBD_EVENT_OUT 1 当通过 OUT 端点收到数据时发生。
ARM_USBD_EVENT_IN 2 在通过 IN 端点发送数据时发生。