Zephyr USB设备控制器驱动程序文档
原文链接：
USB设备控制器驱动程序
USB设备控制器驱动层实现低级别控制例程，直接处理硬件。所有设备控制器驱动程序都应实现include/zephyr/drivers/usb/usb_dc.h中描述的API。这允许在不更改上层的情况下集成新的USB设备控制器。使用此API无法在运行时支持多个控制器实例。
API 参考
usb_device_controller_api 组
USB设备控制器API。
Typedefs
// USB端点状态的回调函数签名
typedef void (*usb_dc_ep_callback)(uint8_t ep, enum usb_dc_ep_cb_status_code cb_status);
// 设备的回调函数签名
typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status, const uint8_t *param);
Enums（枚举）
/**
* 描述： USB驱动程序状态码。已注册设备状态回调报告的状态码。
*/
enum usb_dc_status_code {
/** 控制器报告USB错误 */
USB_DC_ERROR,
/** USB 复位 */
USB_DC_RESET,
/** USB连接建立，硬件枚举完成 */
USB_DC_CONNECTED,
/** USB配置完成 */
USB_DC_CONFIGURED,
/** USB连接丢失 */
USB_DC_DISCONNECTED,
/** USB连接被主机挂起 */
USB_DC_SUSPEND,
/** 主机恢复USB连接 */
USB_DC_RESUME,
/** 选择USB接口 */
USB_DC_INTERFACE,
/** 收到设置特征ENDPOINT_HALT。 */
USB_DC_SET_HALT,
/** 收到清除特征ENDPOINT_HALT。 */
USB_DC_CLEAR_HALT,
/** 帧开始接收 */
USB_DC_SOF,
/** USB连接初始状态 */
USB_DC_UNKNOWN
};
/**
* 描述： USB端点回调状态码。由注册端点回调报告的状态码。
*/
enum usb_dc_ep_cb_status_code {
/** 收到SETUP请求。 */
USB_DC_EP_SETUP,
/** 在此端点上进行了Out事务，数据可供读取。 */
USB_DC_EP_DATA_OUT,
/** 在此端点上完成了In事务。 */
USB_DC_EP_DATA_IN
};
/**
* 描述： USB端点传输类型。
*/
enum usb_dc_ep_transfer_type {
/** 控制类型端点*/
USB_DC_EP_CONTROL = 0,
/** 同步类型端点。 */
USB_DC_EP_ISOCHRONOUS,
/** 批量传输类型端点 */
USB_DC_EP_BULK,
/** 中断类型端点 */
USB_DC_EP_INTERRUPT
};
/**
* 描述： USB端点同步类型。
* 注意：仅对等时端点有效
*/
enum usb_dc_ep_synchronozation_type {
/** 无同步 */
USB_DC_EP_NO_SYNCHRONIZATION = (0U << 2U),
/** 异步 */
USB_DC_EP_ASYNCHRONOUS = (1U << 2U),
/** 自适应 */
USB_DC_EP_ADAPTIVE = (2U << 2U),
/** 同步 */
USB_DC_EP_SYNCHRONOUS = (3U << 2U)
};
函数
/**
* 描述： 连接USB连接设备。
功能为设备连接连接USB。成功后，USB锁相环被启用，USB设备现在能够在USB总线上传输和接收并产生中断。
*
* 参数：
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_attach(void);
/**
* 描述： 卸载USB设备。
命令功能，卸载USB设备。成功后，USB硬件锁相环被下电，USB通信被禁用。
*
* 参数：usb_descriptor —— USB描述符
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_detach(void);
/**
* 描述： 重置USB设备。
此函数将USB设备和固件返回到初始状态。注意:USB锁相环由usb_detach函数处理
*
* 参数：usb_descriptor —— USB描述符
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_reset(void);
/**
* 描述： 设置USB设备地址。
*
* 参数：usb_descriptor —— USB描述符
*
* 返回值： addr – [in] 设备地址
*/
int usb_dc_set_address(const uint8_t addr);
/**
* 描述： 设置USB设备控制器状态回调。
命令功能设置USB设备控制器状态回调。注册回调用于报告设备控制器状态的变化。状态码由usb_dc_status_code枚举描述。
*
* 参数：cb – [in] 回调函数
*
* 返回值：
*/
void usb_dc_set_status_callback(const usb_dc_status_callback cb)
/**
* 描述： 检查端点功能
函数检查端点的能力。Usb_dc_ep_cfg_data结构提供端点配置参数:端点地址、端点最大数据包大小和端点类型。驱动程序应该检查端点功能，如果端点配置是可能的，则返回0。
*
* 参数：cfg – [in] 端点配置
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data *const cfg);
/**
* 描述： 配置端点。
函数配置端点。Usb_dc_ep_cfg_data结构提供端点配置参数:端点地址、端点最大数据包大小和端点类型。
*
* 参数：cfg – [in] 端点配置
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data *const cfg)
/**
* 描述： 为所选端点设置停顿条件。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_set_stall(const uint8_t ep);
/**
* 描述： 清除所选端点的停顿条件。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_clear_stall(const uint8_t ep);
/**
* 描述： 检查所选端点是否已停止。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
* stopped - [out]端点停止状态
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled)
/**
* 描述： 停止选定的端点。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_halt(const uint8_t ep);
/**
* 描述： 启用所选端点。
函数启用所选端点。一旦成功，相应的端点将启用中断，并且该端点已准备好传输/接收数据。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_enable(const uint8_t ep);
/**
* 描述： 禁用所选端点。
函数禁用所选端点。一旦成功，相应端点的中断将被禁用，并且该端点不再能够传输/接收数据。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_disable(const uint8_t ep);
/**
* 描述： 刷新所选端点。
此函数将刷新选定端点的fifo。
*
* 参数：ep - [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_flush(const uint8_t ep);
/**
* 描述： 将数据写入指定的端点。
调用此函数将数据写入指定端点。当数据传输出去时，将调用提供的usb_ep_callback函数。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
* data – [in] 指向要写入数据的指针
* data_len – [in] 请求写入的数据的长度。对于一个长度为零的状态包，这个值可能为零。
* ret_bytes – [out] 预定传输的字节数。如果应用程序希望写入所有字节，则该值可能为NULL
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data, const uint32_t data_len, uint32_t *const ret_bytes);
/**
* 描述： 从指定端点读取数据。
在接收到该EP的OUT中断后，端点处理程序函数将调用该函数。应用程序只能通过提供的usb_ep_callback函数调用此函数。如果已经读取了端点FIFO中的所有数据，则该函数将清除端点NAK，以便从主机接收更多数据。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
* data – [in] 要写入的数据缓冲区的指针
* max_data_len - [in]读取的最大数据长度
* read_bytes - [out]读取的字节数。如果data为NULL且max_data_len为0，则应返回可读取的字节数。
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_read(const uint8_t ep, uint8_t *const data, const uint32_t max_data_len, uint32_t *const read_bytes);
/**
* 描述： 为指定端点设置回调函数。
函数设置回调函数，用于通知已接收的数据并可用于应用程序或在选定端点上完成传输，如果应用程序代码不需要回调，则为NULL。回调状态代码由usb_dc_ep_cb_status_code描述。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
* cb - [in] 回调函数
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb);
/**
* 描述： 从指定端点读取数据。
这类似于usb_dc_ep_read，不同之处在于，它不清除端点NAKs，因此消费者在完成数据处理之前不会被进一步的向上调用所困。调用方应该通过调用usb_dc_ep_read_continue()来重新激活ep。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
* data – [in] 要写入的数据缓冲区的指针
* max_data_len - [in]读取的最大数据长度
* read_bytes - [out]读取的字节数。如果data为NULL且max_data_len为0，则应返回可读取的字节数。
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes);
/**
* 描述： 继续从端点读取数据。
清除端点NAK并允许端点接受来自主机的更多数据。当使用者可以接受更多数据时，通常在usb_dc_ep_read_wait()之后调用。因此，这些调用一起充当流控制机制。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_ep_read_continue(uint8_t ep)
/**
* 描述： 获取端点最大数据包大小。
*
* 参数：ep – [in] 终端地址，与设备配置表中的终端地址对应
*
* 返回值： 端点最大包大小(mps)
*/
int usb_dc_ep_mps(uint8_t ep);
/**
* 描述： 启动主机唤醒过程。
函数唤醒主机，如果主机当前处于睡眠模式。
*
* 参数：
*
* 返回值： 成功时为0，失败时为负errno代码
*/
int usb_dc_wakeup_request(void);
结构体
/**
* 描述： USB端点配置。该结构包含端点的配置。
* 定义的位置：#include