![]() |
CMSIS-Driver
版本 2.6.0
中间件和应用程序代码的外设接口
|
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 函数:
| struct ARM_DRIVER_USBD |
USB 设备驱动程序的访问结构体。
USB 设备驱动程序的功能可以通过函数指针访问。有关概述信息,请参阅通用驱动程序功能。
USBD 的每个实例都提供了这样的访问结构体。该实例由访问结构体的符号名称中的后缀指示,例如:
中间件中的配置设置允许将中间件连接到特定的驱动程序实例 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 |
| struct ARM_USBD_STATE |
| ARM_USBD_SignalDeviceEvent_t |
| ARM_USBD_SignalEndpointEvent_t |
| ARM_DRIVER_VERSION ARM_USBD_GetVersion | ( | void | ) |
获取驱动版本。
函数 ARM_USBD_GetVersion 返回 ARM_DRIVER_VERSION 中驱动程序实现的版本信息
示例:
| ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities | ( | void | ) |
获取驱动程序功能。
函数 ARM_USBD_GetCapabilities 返回有关此驱动程序实现中功能的信息。结构体 ARM_USBD_CAPABILITIES 的数据字段对各种功能进行编码,例如,如果硬件可以使用 ARM_USBD_SignalDeviceEvent 回调函数创建信号事件。
示例:
| 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 | ) |
| int32_t ARM_USBD_PowerControl | ( | ARM_POWER_STATE | state | ) |
控制 USB 设备接口电源。
| [in] | state | 电源状态 |
功能 ARM_USBD_PowerControl 操作 USB 设备接口的电源模式。
参数 state 设置操作并可具有以下值:
有关更多信息,请参阅函数调用序列。
| int32_t ARM_USBD_DeviceConnect | ( | void | ) |
| int32_t ARM_USBD_DeviceDisconnect | ( | void | ) |
| ARM_USBD_STATE ARM_USBD_DeviceGetState | ( | void | ) |
| int32_t ARM_USBD_DeviceRemoteWakeup | ( | void | ) |
| int32_t ARM_USBD_DeviceSetAddress | ( | uint8_t | 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 | 端点地址
|
| [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 | 端点地址
|
函数 ARM_USBD_EndpointUnconfigure 取消配置指定的端点。
参数 ep_addr 指定端点地址。
| int32_t ARM_USBD_EndpointStall | ( | uint8_t | ep_addr, |
| bool | stall | ||
| ) |
为 USB 端点设置/清除停顿。
| [in] | ep_addr | 端点地址
|
| [in] | stall | 操作
|
函数 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 | 端点地址
|
| [out] | data | 指向数据读取或写入数据的缓冲区 |
| [in] | num | 传输的数据字节数 |
函数 ARM_USBD_EndpointTransfer 读取或写入数据到 USB 端点。
参数 ep_addr 指定端点地址。
参数 data 是要读取数据或写入数据的缓冲区。
参数 num 是要传输的字节数(必须是读取传输的端点最大数据包大小的倍数)。
该功能是非阻塞的,只要驱动程序在指定的端点上开始操作,就会立即返回。在操作期间,不允许在同一端点再次调用该函数。此外,数据缓冲区必须保持分配状态,并且数据内容不得修改。
端点地址中的方向指定传输的类型:
当接收到所请求的数据字节数时或接收到短包或 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 | 端点地址
|
函数 ARM_USBD_EndpointTransferGetResult 返回由 ARM_USBD_EndpointTransfer 启动的成功传输的数据字节数。
参数 ep_addr 指定端点地址。
| int32_t ARM_USBD_EndpointTransferAbort | ( | uint8_t | ep_addr | ) |
终止当前的 USB 端点传输。
| [in] | ep_addr | 端点地址
|
函数 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] | event | USBD 设备事件 |
函数 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 | 端点地址
|
| [in] | event | USBD 端点事件 |
函数 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 端点发送数据时发生。 |