summaryrefslogtreecommitdiff
path: root/docs/source/api
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/api')
-rw-r--r--docs/source/api/api_config.rst9
-rw-r--r--docs/source/api/api_device.rst239
-rw-r--r--docs/source/api/api_host.rst46
3 files changed, 181 insertions, 113 deletions
diff --git a/docs/source/api/api_config.rst b/docs/source/api/api_config.rst
index 6b2ed8eb..c1fe8603 100644
--- a/docs/source/api/api_config.rst
+++ b/docs/source/api/api_config.rst
@@ -19,6 +19,11 @@ CONFIG_USB_PRINTF_COLOR_ENABLE
控制 log 颜色打印，默认开启
+CONFIG_USB_DCACHE_ENABLE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+不使用 nocache ram 时，开启此宏以保证数据一致性。 **使用 EHCI 时，内部依旧需要使用 nocache ram**。
+
CONFIG_USB_ALIGN_SIZE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -126,7 +131,7 @@ rndis 与 lwip 接口的对接
.. code-block:: C
- #define CONFIG_USBHOST_MAX_CDC_ACM_CLASS 4
+ #define CONFIG_USBHOST_MAX_SERIAL_CLASS 4
#define CONFIG_USBHOST_MAX_HID_CLASS 4
#define CONFIG_USBHOST_MAX_MSC_CLASS 2
#define CONFIG_USBHOST_MAX_AUDIO_CLASS 1
@@ -150,7 +155,7 @@ CONFIG_USBHOST_REQUEST_BUFFER_LEN
CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-控制传输发送或者接收的超时时间，默认 1s
+控制传输发送或者接收的超时时间，默认 500 ms
CONFIG_USBHOST_MSC_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst
index 29c2b438..5c55d64b 100644
--- a/docs/source/api/api_device.rst
+++ b/docs/source/api/api_device.rst
@@ -14,8 +14,6 @@
CORE
-----------------
-.. note:: 请注意，v1.1 版本开始增加 busid 形参，其余保持不变，所以 API 说明不做更新
-
端点结构体
""""""""""""""""""""""""""""""""""""
@@ -28,7 +26,6 @@ CORE
usbd_endpoint_callback ep_cb;
};
-- **list** 端点的链表节点
- **ep_addr** 端点地址（带方向）
- **ep_cb** 端点完成中断回调函数。
@@ -58,94 +55,101 @@ CORE
- **hid_report_descriptor** hid 报告描述符
- **hid_report_descriptor_len** hid 报告描述符长度
- **intf_num** 当前接口偏移
-- **ep_list** 端点的链表节点
usbd_desc_register
""""""""""""""""""""""""""""""""""""
-``usbd_desc_register`` 用来注册 USB 描述符，描述符种类包括：设备描述符、配置描述符（包含配置描述符、接口描述符、class 类描述符、端点描述符）、字符串描述符、设备限定描述符。
+``usbd_desc_register`` 用来注册 USB 描述符，描述符种类包括：设备描述符、配置描述符（包含配置描述符、接口描述符、class 类描述符、端点描述符）、字符串描述符、设备限定描述符，其他速度描述符，
+bos描述符，winusb 描述符。
.. code-block:: C
- void usbd_desc_register(const uint8_t *desc);
+ // 开启 CONFIG_USBDEV_ADVANCE_DESC
+ void usbd_desc_register(uint8_t busid, const struct usb_descriptor *desc);
-- **desc** 描述符的句柄
+ // 关闭 CONFIG_USBDEV_ADVANCE_DESC
+ void usbd_desc_register(uint8_t busid, const uint8_t *desc);
+ void usbd_msosv1_desc_register(uint8_t busid, struct usb_msosv1_descriptor *desc);
+ void usbd_msosv2_desc_register(uint8_t busid, struct usb_msosv2_descriptor *desc);
+ void usbd_bos_desc_register(uint8_t busid, struct usb_bos_descriptor *desc);
+ void usbd_webusb_desc_register(uint8_t busid, struct usb_webusb_descriptor *desc);
-.. note:: 当前 API 仅支持一种速度，如果需要更高级的速度切换功能，请开启 CONFIG_USBDEV_ADVANCE_DESC，并且包含了下面所有描述符注册功能
+- **desc** 描述符的句柄
+.. note:: 当前默认开启 CONFIG_USBDEV_ADVANCE_DESC，如果需要使用旧版本 API 请关闭该宏
-usbd_msosv1_desc_register
+usbd_add_interface
""""""""""""""""""""""""""""""""""""
-``usbd_msosv1_desc_register`` 用来注册一个 WINUSB 1.0 描述符。
+``usbd_add_interface`` 添加一个接口驱动。 **添加顺序必须按照描述符中接口顺序**。
.. code-block:: C
- void usbd_msosv1_desc_register(struct usb_msosv1_descriptor *desc);
+ void usbd_add_interface(uint8_t busid, struct usbd_interface *intf);
-- **desc** 描述符句柄
+- **busid** USB 总线 id
+- **intf** 接口驱动句柄，通常从不同 class 的 `xxx_init_intf` 函数获取
-usbd_msosv2_desc_register
+usbd_add_endpoint
""""""""""""""""""""""""""""""""""""
-``usbd_msosv2_desc_register`` 用来注册一个 WINUSB 2.0 描述符。
+``usbd_add_endpoint`` 添加一个端点中断完成回调函数。
.. code-block:: C
- void usbd_msosv2_desc_register(struct usb_msosv2_descriptor *desc);
+ void usbd_add_endpoint(uint8_t busid, struct usbd_endpoint *ep);
-- **desc** 描述符句柄
+- **busid** USB 总线 id
+- **ep** 端点句柄
-usbd_bos_desc_register
+usbd_initialize
""""""""""""""""""""""""""""""""""""
-``usbd_bos_desc_register`` 用来注册一个 BOS 描述符， USB 2.1 版本以上必须注册。
+``usbd_initialize`` 用来初始化 usb device 寄存器配置、usb 时钟、中断等，需要注意，此函数必须在注册描述符 API 最后。 **如果使用 os，必须放在线程中执行**。
.. code-block:: C
- void usbd_bos_desc_register(struct usb_bos_descriptor *desc);
-
-- **desc** 描述符句柄
+ int usbd_initialize(uint8_t busid, uintptr_t reg_base, usbd_event_handler_t event_handler);
-usbd_add_interface
-""""""""""""""""""""""""""""""""""""
+- **busid** USB 总线 id
+- **reg_base** USB 设备寄存器基地址
+- **event_handler** 协议栈中断或者状态回调函数，event 事件
+- **return** 返回 0 表示成功，其他值表示失败
-``usbd_add_interface`` 添加一个接口驱动。 **添加顺序必须按照描述符顺序**。
+event 事件包括：
.. code-block:: C
- void usbd_add_interface(struct usbd_interface *intf);
-
-- **intf** 接口驱动句柄，通常从不同 class 的 `xxx_init_intf` 函数获取
-
-usbd_add_endpoint
-""""""""""""""""""""""""""""""""""""
+ USBD_EVENT_ERROR, /** USB error reported by the controller */
+ USBD_EVENT_RESET, /** USB reset */
+ USBD_EVENT_SOF, /** Start of Frame received */
+ USBD_EVENT_CONNECTED, /** USB connected*/
+ USBD_EVENT_DISCONNECTED, /** USB disconnected */
+ USBD_EVENT_SUSPEND, /** USB connection suspended by the HOST */
+ USBD_EVENT_RESUME, /** USB connection resumed by the HOST */
-``usbd_add_endpoint`` 添加一个端点中断完成回调函数。
-
-.. code-block:: C
+ /* USB DEVICE STATUS */
+ USBD_EVENT_CONFIGURED, /** USB configuration done */
+ USBD_EVENT_SET_INTERFACE, /** USB interface selected */
+ USBD_EVENT_SET_REMOTE_WAKEUP, /** USB set remote wakeup */
+ USBD_EVENT_CLR_REMOTE_WAKEUP, /** USB clear remote wakeup */
+ USBD_EVENT_INIT, /** USB init done when call usbd_initialize */
+ USBD_EVENT_DEINIT, /** USB deinit done when call usbd_deinitialize */
+ USBD_EVENT_UNKNOWN
- void usbd_add_endpoint(struct usbd_endpoint *ep);;
+.. note:: 大部分 IP USBD_EVENT_CONNECTED 和 USBD_EVENT_DISCONNECTED 都支持，当前仅 HPM 芯片支持
-- **ep** 端点句柄
-
-usbd_initialize
+usbd_deinitialize
""""""""""""""""""""""""""""""""""""
-``usbd_initialize`` 用来初始化 usb device 寄存器配置、usb 时钟、中断等，需要注意，此函数必须在所有列出的 API 最后。 **如果使用 os，必须放在线程中执行**。
+``usbd_deinitialize`` 用来反初始化 usb device，关闭 usb 设备时钟、中断等。
.. code-block:: C
- int usbd_initialize(void);
-
-usbd_event_handler
-""""""""""""""""""""""""""""""""""""
-
-``usbd_event_handler`` 是协议栈中中断或者协议栈一些状态的回调函数。大部分 IP 仅支持 USBD_EVENT_RESET 和 USBD_EVENT_CONFIGURED
+ int usbd_deinitialize(uint8_t busid);
-.. code-block:: C
-
- void usbd_event_handler(uint8_t event);
+- **busid** USB 总线 id
+- **return** 返回 0 表示成功，其他值表示失败
CDC ACM
-----------------
@@ -160,8 +164,9 @@ usbd_cdc_acm_init_intf
.. code-block:: C
- struct usbd_interface *usbd_cdc_acm_init_intf(struct usbd_interface *intf);
+ struct usbd_interface *usbd_cdc_acm_init_intf(uint8_t busid, struct usbd_interface *intf);
+- **busid** USB 总线 id
- **return** 接口句柄
usbd_cdc_acm_set_line_coding
@@ -171,8 +176,9 @@ usbd_cdc_acm_set_line_coding
.. code-block:: C
- void usbd_cdc_acm_set_line_coding(uint8_t intf, struct cdc_line_coding *line_coding);
+ void usbd_cdc_acm_set_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding);
+- **busid** USB 总线 id
- **intf** 控制接口号
- **line_coding** 串口配置
@@ -183,8 +189,9 @@ usbd_cdc_acm_get_line_coding
.. code-block:: C
- void usbd_cdc_acm_get_line_coding(uint8_t intf, struct cdc_line_coding *line_coding);
+ void usbd_cdc_acm_get_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding);
+- **busid** USB 总线 id
- **intf** 控制接口号
- **line_coding** 串口配置
@@ -195,8 +202,9 @@ usbd_cdc_acm_set_dtr
.. code-block:: C
- void usbd_cdc_acm_set_dtr(uint8_t intf, bool dtr);
+ void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr);
+- **busid** USB 总线 id
- **intf** 控制接口号
- **dtr** dtr 为1表示拉低电平，为0表示拉高电平
@@ -207,8 +215,9 @@ usbd_cdc_acm_set_rts
.. code-block:: C
- void usbd_cdc_acm_set_rts(uint8_t intf, bool rts);
+ void usbd_cdc_acm_set_rts(uint8_t busid, uint8_t intf, bool rts);
+- **busid** USB 总线 id
- **intf** 控制接口号
- **rts** rts 为1表示拉低电平，为0表示拉高电平
@@ -240,8 +249,9 @@ usbd_hid_init_intf
.. code-block:: C
- struct usbd_interface *usbd_hid_init_intf(struct usbd_interface *intf, const uint8_t *desc, uint32_t desc_len);
+ struct usbd_interface *usbd_hid_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t *desc, uint32_t desc_len);
+- **busid** USB 总线 id
- **desc** 报告描述符
- **desc_len** 报告描述符长度
@@ -260,8 +270,9 @@ usbd_msc_init_intf
.. code-block:: C
- struct usbd_interface *usbd_msc_init_intf(struct usbd_interface *intf, const uint8_t out_ep, const uint8_t in_ep);
+ struct usbd_interface *usbd_msc_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t out_ep, const uint8_t in_ep);
+- **busid** USB 总线 id
- **out_ep** out 端点地址
- **in_ep** in 端点地址
@@ -272,8 +283,9 @@ usbd_msc_get_cap
.. code-block:: C
- void usbd_msc_get_cap(uint8_t lun, uint32_t *block_num, uint16_t *block_size);
+ void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint16_t *block_size);
+- **busid** USB 总线 id
- **lun** 存储逻辑单元，暂时无用，默认支持一个
- **block_num** 存储扇区个数
- **block_size** 存储扇区大小
@@ -285,8 +297,10 @@ usbd_msc_sector_read
.. code-block:: C
- int usbd_msc_sector_read(uint32_t sector, uint8_t *buffer, uint32_t length);
+ int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length);
+- **busid** USB 总线 id
+- **lun** 存储逻辑单元，暂时无用，默认支持一个
- **sector** 扇区偏移
- **buffer** 存储读取的数据的指针
- **length** 读取长度
@@ -299,8 +313,10 @@ usbd_msc_sector_write
.. code-block:: C
- int usbd_msc_sector_write(uint32_t sector, uint8_t *buffer, uint32_t length);
+ int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length);
+- **busid** USB 总线 id
+- **lun** 存储逻辑单元，暂时无用，默认支持一个
- **sector** 扇区偏移
- **buffer** 写入数据指针
- **length** 写入长度
@@ -318,15 +334,21 @@ usbd_audio_init_intf
.. code-block:: C
- struct usbd_interface *usbd_audio_init_intf(struct usbd_interface *intf);
+ struct usbd_interface *usbd_audio_init_intf(uint8_t busid, struct usbd_interface *intf,
+ uint16_t uac_version,
+ struct audio_entity_info *table,
+ uint8_t num);
-- **class** 类的句柄
+- **busid** USB 总线 id
- **intf** 接口句柄
+- **uac_version** 音频类版本，UAC1.0 或 UAC2.0
+- **table** 音频实体信息表
+- **num** 音频实体信息表长度
usbd_audio_open
""""""""""""""""""""""""""""""""""""
-``usbd_audio_open`` 用来开启音频数据传输。
+``usbd_audio_open`` 用来开启音频数据传输。主机发送开启命令的回调函数。
.. code-block:: C
@@ -337,7 +359,7 @@ usbd_audio_open
usbd_audio_close
""""""""""""""""""""""""""""""""""""
-``usbd_audio_close`` 用来关闭音频数据传输。
+``usbd_audio_close`` 用来关闭音频数据传输。主机发送关闭命令的回调函数。
.. code-block:: C
@@ -345,18 +367,6 @@ usbd_audio_close
- **intf** 关闭的接口号
-usbd_audio_add_entity
-""""""""""""""""""""""""""""""""""""
-
-``usbd_audio_add_entity`` 用来添加 unit 相关控制，例如 feature unit、clock source。
-
-.. code-block:: C
-
- void usbd_audio_add_entity(uint8_t entity_id, uint16_t bDescriptorSubtype);
-
-- **entity_id** 要添加的 unit id
-- **bDescriptorSubtype** entity_id 的描述符子类型
-
usbd_audio_set_mute
""""""""""""""""""""""""""""""""""""
@@ -364,10 +374,12 @@ usbd_audio_set_mute
.. code-block:: C
- void usbd_audio_set_mute(uint8_t ch, uint8_t enable);
+ void usbd_audio_set_mute(uint8_t busid, uint8_t ep, uint8_t ch, bool mute);
+- **busid** USB 总线 id
+- **ep** 要设置静音的端点
- **ch** 要设置静音的通道
-- **enable** 为1 表示静音，0相反
+- **mute** 为1 表示静音，0相反
usbd_audio_set_volume
""""""""""""""""""""""""""""""""""""
@@ -376,10 +388,12 @@ usbd_audio_set_volume
.. code-block:: C
- void usbd_audio_set_volume(uint8_t ch, float dB);
+ void usbd_audio_set_volume(uint8_t busid, uint8_t ep, uint8_t ch, int volume_db);
+- **busid** USB 总线 id
+- **ep** 要设置音量的端点
- **ch** 要设置音量的通道
-- **dB** 要设置音量的分贝，其中 UAC1.0范围从 -127 ~ +127dB，UAC2.0 从 0 ~ 256dB
+- **volume_db** 要设置音量的分贝，单位 -100dB ~ 0dB
usbd_audio_set_sampling_freq
""""""""""""""""""""""""""""""""""""
@@ -388,34 +402,23 @@ usbd_audio_set_sampling_freq
.. code-block:: C
- void usbd_audio_set_sampling_freq(uint8_t ep_ch, uint32_t sampling_freq);
+ void usbd_audio_set_sampling_freq(uint8_t busid, uint8_t ep, uint32_t sampling_freq);
-- **ch** 要设置采样率的端点或者通道，UAC1.0为端点，UAC2.0 为通道
-- **dB** 要设置的采样率
+- **ep** 要设置采样率的端点
+- **sampling_freq** 要设置的采样率
usbd_audio_get_sampling_freq_table
""""""""""""""""""""""""""""""""""""
-``usbd_audio_get_sampling_freq_table`` 用来获取支持的采样率列表，如果函数没有实现，则使用默认采样率列表。
+``usbd_audio_get_sampling_freq_table`` 用来获取支持的采样率列表，如果函数没有实现，则使用默认采样率列表。 UAC2 only。
.. code-block:: C
- void usbd_audio_get_sampling_freq_table(uint8_t **sampling_freq_table);
+ void usbd_audio_get_sampling_freq_table(uint8_t busid, uint8_t ep, uint8_t **sampling_freq_table);
+- **ep** 要获取采样率的端点
- **sampling_freq_table** 采样率列表地址，格式参考默认采样率列表
-usbd_audio_set_pitch
-""""""""""""""""""""""""""""""""""""
-
-``usbd_audio_set_pitch`` 用来设置音频音调，仅 UAC1.0 有这功能。
-
-.. code-block:: C
-
- void usbd_audio_set_pitch(uint8_t ep, bool enable);
-
-- **ep** 要设置音调的端点
-- **enable** 开启或关闭音调
-
UVC
-----------------
@@ -428,13 +431,15 @@ usbd_video_init_intf
.. code-block:: C
- struct usbd_interface *usbd_video_init_intf(struct usbd_interface *intf,
- uint32_t dwFrameInterval,
- uint32_t dwMaxVideoFrameSize,
- uint32_t dwMaxPayloadTransferSize);
-
-- **class** 类的句柄
+ struct usbd_interface *usbd_video_init_intf(uint8_t busid, struct usbd_interface *intf,
+ uint32_t dwFrameInterval,
+ uint32_t dwMaxVideoFrameSize,
+ uint32_t dwMaxPayloadTransferSize);
+- **busid** USB 总线 id
- **intf** 接口句柄
+- **dwFrameInterval** 视频帧间隔，单位 100ns
+- **dwMaxVideoFrameSize** 最大视频帧大小
+- **dwMaxPayloadTransferSize** 最大负载传输大小
usbd_video_open
""""""""""""""""""""""""""""""""""""
@@ -458,25 +463,39 @@ usbd_video_close
- **intf** 关闭的接口号
-usbd_video_payload_fill
+usbd_video_stream_start_write
+""""""""""""""""""""""""""""""""""""
+
+``usbd_video_stream_start_write`` 用来启动一帧视频数据流发送。需要搭配 `usbd_video_stream_split_transfer` 使用。
+
+.. code-block:: C
+
+ int usbd_video_stream_start_write(uint8_t busid, uint8_t ep, uint8_t *ep_buf, uint8_t *stream_buf, uint32_t stream_len, bool do_copy);
+
+- **busid** USB 总线 id
+- **ep** 视频数据端点地址
+- **ep_buf** 视频数据端点传输缓冲区
+- **stream_buf** 一帧视频数据源缓冲区
+- **stream_len** 一帧视频数据源缓冲区大小
+- **do_copy** 是否需要将 stream_buf 数据复制到 ep_buf 中，当前仅当 stream_buf 在 nocache 区域并且未开启 DCACHE_ENABLE 时该参数才为 false
+
+usbd_video_stream_split_transfer
""""""""""""""""""""""""""""""""""""
-``usbd_video_payload_fill`` 用来填充 mjpeg 到新的 buffer中，其中会对 mjpeg 数据按帧进行切分，切分大小由 ``dwMaxPayloadTransferSize`` 控制，并添加头部信息，当前头部字节数为 2。头部信息见 ``struct video_mjpeg_payload_header``
+``usbd_video_stream_split_transfer`` 用来分割视频数据流发送。需要搭配 `usbd_video_stream_start_write` 使用。
.. code-block:: C
- uint32_t usbd_video_payload_fill(uint8_t *input, uint32_t input_len, uint8_t *output, uint32_t *out_len);
+ int usbd_video_stream_split_transfer(uint8_t busid, uint8_t ep);
-- **input** mjpeg 格式的数据包，从 FFD8~FFD9结束
-- **input_len** mjpeg数据包大小
-- **output** 输出缓冲区
-- **out_len** 输出实际要发送的长度大小
-- **return** 返回 usb 按照 ``dwMaxPayloadTransferSize`` 大小要发多少帧
+- **busid** USB 总线 id
+- **ep** 视频数据端点地址
+- **return** 返回 true 表示一帧数据发送完成，false 表示数据未发送完成
-DFU
+RNDIS
-----------------
-PRINTER
+CDC ECM
-----------------
MTP
diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst
index e369aa3a..5faa9cde 100644
--- a/docs/source/api/api_host.rst
+++ b/docs/source/api/api_host.rst
@@ -264,5 +264,49 @@ HID
MSC
-----------------
+usbh_msc_scsi_init
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_init`` 初始化 msc scsi 设备。获取 MSC 状态和容量信息。
+
+.. code-block:: C
+
+ int usbh_msc_scsi_init(struct usbh_msc *msc_class);
+
+- **msc_class** msc 结构体句柄
+- **return** 0 表示正常其他表示错误
+
+usbh_msc_scsi_write10
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_write10`` 向 msc 设备写数据。
+
+.. code-block:: C
+
+ int usbh_msc_scsi_write10(struct usbh_msc *msc_class, uint32_t start_sector, const uint8_t *buffer, uint32_t nsectors);
+
+- **msc_class** msc 结构体句柄
+- **start_sector** 起始扇区
+- **buffer** 数据缓冲区指针
+- **nsectors** 要写入的扇区数
+- **return** 返回 0 表示正常其他表示错误
+
+usbh_msc_scsi_read10
+""""""""""""""""""""""""""""""""""""
+
+``usbh_msc_scsi_read10`` 从 msc 设备读数据。
+
+.. code-block:: C
+
+ int usbh_msc_scsi_read10(struct usbh_msc *msc_class, uint32_t start_sector, uint8_t *buffer, uint32_t nsectors);
+
+- **msc_class** msc 结构体句柄
+- **start_sector** 起始扇区
+- **buffer** 数据缓冲区指针
+- **nsectors** 要读取的扇区数
+- **return** 返回 0 表示正常其他表示错误
+
NETWORK
------------------ \ No newline at end of file
+-----------------
+
+已对接 lwIP 协议栈或者其他网络协议栈，使用 socket API 即可。 \ No newline at end of file
generated by cgit v1.3.1 (git 2.54.0) at 2026-08-16 19:24:43 +0000