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 <usb_device.h>
 */
struct usb_dc_ep_cfg_data {
	/** 设备端点号，注意输入端点与输出端点的配置
	 *       IN  EP = 0x80 | \<endpoint number\>
	 *       OUT EP = 0x00 | \<endpoint number\>
	 */
	 
	uint8_t ep_addr;
	/** 端点最大包大小 */
	uint16_t ep_mps;
	
	/** 端点传输类型。可能是批量，中断，控制或同步 */
	enum usb_dc_ep_transfer_type ep_type;
};