diff --git a/docs/source/api/api_config.rst b/docs/source/api/api_config.rst new file mode 100644 index 00000000..d7754fd0 --- /dev/null +++ b/docs/source/api/api_config.rst @@ -0,0 +1,116 @@ +USB CONFIG 宏 +========================= + + +设备相关 CONFIG 宏 +--------------------- + +.. code-block:: C + + /* USB DEVICE Configuration */ + /* core */ + #ifndef CONFIG_USBDEV_REQUEST_BUFFER_LEN + #define CONFIG_USBDEV_REQUEST_BUFFER_LEN 256 + #endif + + #ifndef CONFIG_USBDEV_DESC_CHECK + #define CONFIG_USBDEV_DESC_CHECK 0 + #endif + + #ifndef CONFIG_USBDEV_TEST_MODE + #define CONFIG_USBDEV_TEST_MODE 0 + #endif + + /* msc class */ + #ifndef CONFIG_USBDEV_MSC_MANUFACTURER_STRING + #define CONFIG_USBDEV_MSC_MANUFACTURER_STRING "" + #endif + + #ifndef CONFIG_USBDEV_MSC_PRODUCT_STRING + #define CONFIG_USBDEV_MSC_PRODUCT_STRING "" + #endif + + #ifndef CONFIG_USBDEV_MSC_VERSION_STRING + #define CONFIG_USBDEV_MSC_VERSION_STRING "0.01" + #endif + + /* audio class */ + #ifndef CONFIG_USBDEV_AUDIO_VERSION + #define CONFIG_USBDEV_AUDIO_VERSION 0x0100 + #endif + + #ifndef CONFIG_USBDEV_AUDIO_MAX_CHANNEL + #define CONFIG_USBDEV_AUDIO_MAX_CHANNEL 2 + #endif + + +主机相关 CONFIG 宏 +--------------------- + +.. code-block:: C + + /* USB HOST Configuration */ + #ifndef CONFIG_USBHOST_RHPORTS + #define CONFIG_USBHOST_RHPORTS 1 + #endif + + #ifndef CONFIG_USBHOST_EHPORTS + #define CONFIG_USBHOST_EHPORTS 4 + #endif + + #ifndef CONFIG_USBHOST_PIPE_NUM + #define CONFIG_USBHOST_PIPE_NUM 10 + #endif + + #ifndef CONFIG_USBHOST_INTF_NUM + #define CONFIG_USBHOST_INTF_NUM 6 + #endif + + #ifndef CONFIG_USBHOST_EP_NUM + #define CONFIG_USBHOST_EP_NUM 4 + #endif + + #ifndef CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT + #define CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT 5000 + #endif + + #ifndef CONFIG_USBHOST_MSC_TIMEOUT + #define CONFIG_USBHOST_MSC_TIMEOUT 5000 + #endif + + #ifndef CONFIG_USBHOST_HPWORKQ_PRIO + #define CONFIG_USBHOST_HPWORKQ_PRIO 5 + #endif + #ifndef CONFIG_USBHOST_HPWORKQ_STACKSIZE + #define CONFIG_USBHOST_HPWORKQ_STACKSIZE 2048 + #endif + + #ifndef CONFIG_USBHOST_LPWORKQ_PRIO + #define CONFIG_USBHOST_LPWORKQ_PRIO 1 + #endif + #ifndef CONFIG_USBHOST_LPWORKQ_STACKSIZE + #define CONFIG_USBHOST_LPWORKQ_STACKSIZE 2048 + #endif + + #ifndef CONFIG_USBHOST_PSC_PRIO + #define CONFIG_USBHOST_PSC_PRIO 4 + #endif + #ifndef CONFIG_USBHOST_PSC_STACKSIZE + #define CONFIG_USBHOST_PSC_STACKSIZE 4096 + #endif + + #ifndef CONFIG_USBHOST_DEV_NAMELEN + #define CONFIG_USBHOST_DEV_NAMELEN 16 + #endif + + #define CONFIG_USBHOST_ASYNCH + //#define CONFIG_USBHOST_GET_STRING_DESC + + /* EHCI Configuration */ + #define CONFIG_USB_EHCI_HCCR_BASE (0x20072000) + #define CONFIG_USB_EHCI_HCOR_BASE (0x20072000 + 0x10) + #define CONFIG_USB_EHCI_QH_NUM (10) + #define CONFIG_USB_EHCI_QTD_NUM (10) + // #define CONFIG_USB_EHCI_INFO_ENABLE + #define CONFIG_USB_ECHI_HCOR_RESERVED_DISABLE + // #define CONFIG_USB_EHCI_CONFIGFLAG \ No newline at end of file diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst index ea243edc..42830f6c 100644 --- a/docs/source/api/api_device.rst +++ b/docs/source/api/api_device.rst @@ -260,8 +260,9 @@ usbd_cdc_acm_set_line_coding .. code-block:: C - void usbd_cdc_acm_set_line_coding(uint32_t baudrate, uint8_t databits, uint8_t parity, uint8_t stopbits); + void usbd_cdc_acm_set_line_coding(uint8_t intf, uint32_t baudrate, uint8_t databits, uint8_t parity, uint8_t stopbits); +- **intf** 控制接口号 - **baudrate** 波特率 - **databits** 数据位 - **parity** 校验位 @@ -274,8 +275,9 @@ usbd_cdc_acm_set_dtr .. code-block:: C - void usbd_cdc_acm_set_dtr(bool dtr); + void usbd_cdc_acm_set_dtr(uint8_t intf, bool dtr); +- **intf** 控制接口号 - **dtr** dtr 为1表示拉低电平，为0表示拉高电平 usbd_cdc_acm_set_rts @@ -285,8 +287,9 @@ usbd_cdc_acm_set_rts .. code-block:: C - void usbd_cdc_acm_set_rts(bool rts); + void usbd_cdc_acm_set_rts(uint8_t intf, bool rts); +- **intf** 控制接口号 - **rts** rts 为1表示拉低电平，为0表示拉高电平 CDC_ACM_DESCRIPTOR_INIT @@ -597,5 +600,8 @@ usbd_video_mjpeg_payload_fill DFU ----------------- -PORTING +PRINTER +----------------- + +MTP ----------------- \ No newline at end of file diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst index fdee2c18..92c42d00 100644 --- a/docs/source/api/api_host.rst +++ b/docs/source/api/api_host.rst @@ -1,6 +1,11 @@ 主机协议栈 ========================= +关于主机协议栈中结构体的命名、分类、成员组成，参考下面这两张图： + +.. figure:: img/api_host1.png +.. figure:: img/api_host2.png + CORE ----------------- @@ -94,7 +99,7 @@ hub 结构体 usbh_event_notify_handler """""""""""""""""""""""""""""""""""" -``usbh_event_notify_handler`` 是 USB 中断中的核心，用于处理不同的中断标志。包括复位、端点0 IN/OUT/SETUP、其他端点 IN/OUT 、SUSPEND、RESUME、SOF 中断等等。用于需要在 porting 接口中的 USB中断中调用该接口。 +``usbh_event_notify_handler`` 是 USB 中断中的核心，主要用于处理 **设备连接** 和 **设备断开** 中断，从而唤醒线程去执行枚举。 .. code-block:: C @@ -115,7 +120,7 @@ usbh_event_notify_handler usbh_initialize """""""""""""""""""""""""""""""""""" -``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：创建插拔检测用的信号量和枚举线程、高低工作队列、初始化 roothub端点0 配置，初始化 usb 主机控制器。 +``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：创建插拔检测用的信号量和枚举线程、高低工作队列、初始化 roothub 端点0 配置，初始化 usb 主机控制器。 .. code-block:: C @@ -151,11 +156,8 @@ HID MSC ----------------- -UAC +RNDIS ----------------- -UVC ------------------ - -PORTING +PRINTER ----------------- \ No newline at end of file diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst new file mode 100644 index 00000000..294b0eb2 --- /dev/null +++ b/docs/source/api/api_port.rst @@ -0,0 +1,328 @@ +Porting +========================= + +device controller(dcd) +------------------------- + +usb_dc_init +"""""""""""""""""""""""""""""""""""" + +``usb_dc_init`` 用于初始化 usb device controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。 + +.. code-block:: C + + int usb_dc_init(void); + +- **return** + +usb_dc_deinit +"""""""""""""""""""""""""""""""""""" + +``usb_dc_deinit`` 用于反初始化 usb device controller 寄存器。 **此函数不对用户开放**。 + +.. code-block:: C + + int usb_dc_deinit(void); + +- **return** + +usb_dc_attach +"""""""""""""""""""""""""""""""""""" + +``usb_dc_attach`` 使能上拉或者下拉电阻，从而能够让设备被主机枚举。 **此函数对用户开放**。 + +.. code-block:: C + + int usb_dc_attach(void); + +- **return** + +usb_dc_detach +"""""""""""""""""""""""""""""""""""" + +``usb_dc_detach``断开设备与主机的连接。 **此函数对用户开放**。 + +.. code-block:: C + + int usb_dc_detach(void); + +- **return** + +usbd_set_address +"""""""""""""""""""""""""""""""""""" + +``usbd_set_address`` 设置设备地址。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbd_set_address(const uint8_t addr); + +- **return** + +usbd_ep_open +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_open`` 设置端点的属性，开启对应端点的中断。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbd_ep_open(const struct usbd_endpoint_cfg *ep_cfg); + +- **return** + +usbd_ep_close +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_close`` 关闭端点。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbd_ep_close(const uint8_t ep); + +- **event** + +usbd_ep_set_stall +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_set_stall`` 将端点设置成 stall 状态并发送 stall 握手包。 **此函数对用户开放**。 + +.. code-block:: C + + int usbd_ep_set_stall(const uint8_t ep); + +- **ep** 端点地址 + +usbd_ep_clear_stall +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_clear_stall`` 清除端点的 stall 状态。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbd_ep_clear_stall(const uint8_t ep); + +- **ep** 端点地址 + +usbd_ep_is_stalled +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_is_stalled`` 读取当前端点的 stall 状态。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbd_ep_is_stalled(const uint8_t ep, uint8_t *stalled); + +- **ep** 端点地址 +- **return** 返回 1 表示 stalled，0 表示没有 stall + +usbd_ep_write +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_write`` 向某个端点发送数据， **如果该函数在中断中使用则是异步传输，否则是阻塞传输**。 **此函数对用户开放**。 + +.. code-block:: C + + int usbd_ep_write(const uint8_t ep, const uint8_t *data, uint32_t data_len, uint32_t *ret_bytes); + +- **ep** in 端点地址 +- **data** 要发送的数据缓冲区 +- **data_len** 发送长度，需要小于等于端点最大包长 +- **ret_bytes** 实际发送的长度，异步传输该参数无效。 **如果长度为 0，表示发送 0 长数据包（zero length packet）** +- **return** 返回 0 表示正确，其他表示错误 + +usbd_ep_read +"""""""""""""""""""""""""""""""""""" + +``usbd_ep_read`` 从某个端点接收数据， **该函数仅能在 usb out 中断中使用**。 **此函数对用户开放**。 + +.. code-block:: C + + int usbd_ep_read(const uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes); + +- **ep** out 端点地址 +- **data** 要接收的数据缓冲区 +- **data_len** 接收长度，需要小于等于端点最大包长，推荐直接设置成最大包长。 **如果长度为 0 表示启动下次接收** +- **ret_bytes** 实际接收的长度 +- **return** 返回 0 表示正确，其他表示错误 + +host controller(hcd) +------------------------ + +usb_hc_init +"""""""""""""""""""""""""""""""""""" + +``usb_hc_init`` 用于初始化 usb host controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。 + +.. code-block:: C + + int usb_hc_init(void); + +- **return** 返回 0 表示正确，其他表示错误 + +usbh_get_port_connect_status +"""""""""""""""""""""""""""""""""""" + +``usbh_get_port_connect_status`` 获取当前 hubport 连接状态。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_get_port_connect_status(const uint8_t port); + +- **port** 端口号 +- **return** 返回 1 表示连接，0 表示未连接 + +usbh_reset_port +"""""""""""""""""""""""""""""""""""" + +``usbh_reset_port`` 复位指定的 hubport **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_reset_port(const uint8_t port); + +- **port** 端口号 +- **return** 返回 0 表示正确，其他表示错误 + +usbh_get_port_speed +"""""""""""""""""""""""""""""""""""" + +``usbh_get_port_speed`` 获取当前 hubport 上连接的设备速度。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_get_port_speed(const uint8_t port); + +- **port** 端口号 +- **return** 返回 1 表示低速，2 表示全速，3 表示高速 + +usbh_ep0_reconfigure +"""""""""""""""""""""""""""""""""""" + +``usbh_ep0_reconfigure`` 重新设置端点 0 的属性。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_ep0_reconfigure(usbh_epinfo_t ep, uint8_t dev_addr, uint8_t ep_mps, uint8_t speed); + +- **ep** 端点信息 +- **dev_addr** 端点所在设备地址 +- **ep_mps** 端点最大包长 +- **speed** 端点所在设备的速度 +- **return** 返回 0 表示正确，其他表示错误 + +usbh_ep_alloc +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_alloc`` 为端点分配相关属性，初始化相关寄存器，并保存相关信息到 **ep** 句柄中。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_ep_alloc(usbh_epinfo_t *ep, const struct usbh_endpoint_cfg *ep_cfg); + +- **ep** 端点信息 +- **ep_cfg** 端点初始化需要的一些信息 +- **return** 返回 0 表示正确，其他表示错误 + +usbh_ep_free +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_free`` 释放端点的一些属性。 **此函数不对用户开放**。 + +.. code-block:: C + + int usbh_ep_free(usbh_epinfo_t ep); + +- **ep** 端点信息 +- **return** 返回 0 表示正确，其他表示错误 + +usbh_control_transfer +"""""""""""""""""""""""""""""""""""" + +``usbh_control_transfer`` 对端点 0 进行控制传输，并且 **此函数为阻塞式传输，默认超时时间 5s**。 **此函数对用户开放**。 + +.. code-block:: C + + int usbh_control_transfer(usbh_epinfo_t ep, struct usb_setup_packet *setup, uint8_t *buffer); + +- **ep** 端点信息 +- **setup** setup 包 +- **buffer** 要发送或者读取的数据缓冲区，为 NULL 表示没有数据要发送或者接收 +- **return** 返回 0 表示正确，其他表示错误 + +usbh_ep_bulk_transfer +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_bulk_transfer`` 对指定端点进行批量传输， **此函数为阻塞式传输**。 **此函数对用户开放**。 + +.. code-block:: C + + int usbh_ep_bulk_transfer(usbh_epinfo_t ep, uint8_t *buffer, uint32_t buflen, uint32_t timeout); + +- **ep** 端点信息 +- **buffer** 要发送或者读取的数据缓冲区 +- **buflen** 要发送或者接收的长度，最大不得高于 16K +- **timeout** 超时时间，单位 ms +- **return** 大于等于0 表示实际发送或者接收的长度，小于 0 表示错误 + +其中小于 0 的错误码如下： + +.. list-table:: + :widths: 30 30 + :header-rows: 1 + + * - ERROR CODE + - desc + * - ENODEV + - 设备未连接 + * - EBUSY + - 当前数据发送或者接收还未完成 + * - EAGAIN + - 主机一直收到 NAK 包 + * - ETIMEDOUT + - 数据发送或者接收超时 + * - EPERM + - 主机收到 STALL 包 + * - EIO + - 数据传输错误 + * - EPIPE + - 数据溢出 + * - ENXIO + - 设备断开，传输中止 + +usbh_ep_intr_transfer +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_intr_transfer`` 同上。 + +usbh_ep_bulk_async_transfer +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_bulk_async_transfer`` 对指定端点进行批量传输，传输完成将触发指定回调函数， **此函数为异步传输**。 **此函数对用户开放**。 + +.. code-block:: C + + int usbh_ep_bulk_async_transfer(usbh_epinfo_t ep, uint8_t *buffer, uint32_t buflen, usbh_asynch_callback_t callback, void *arg); + +- **ep** 端点信息 +- **buffer** 要发送或者读取的数据缓冲区 +- **buflen** 要发送或者接收的长度，最大不得高于 16K +- **callback** 传输完成回调函数， **该函数最终处于中断上下文** +- **arg** 用户自定义参数 +- **return** 为 0 表示配置正常，小于0 表示错误 + +usbh_ep_intr_async_transfer +"""""""""""""""""""""""""""""""""""" + +``usbh_ep_intr_async_transfer`` 同上。 + +usb_ep_cancel +"""""""""""""""""""""""""""""""""""" + +``usb_ep_cancel`` 中止当前端点传输， **此函数不对用户开放**。 + +.. code-block:: C + + int usb_ep_cancel(usbh_epinfo_t ep); + +- **ep** 端点信息 +- **return** 为 0 表示正确，小于0 表示错误 diff --git a/docs/source/api/img/api_host1.png b/docs/source/api/img/api_host1.png new file mode 100644 index 00000000..82932f50 Binary files /dev/null and b/docs/source/api/img/api_host1.png differ diff --git a/docs/source/api/img/api_host2.png b/docs/source/api/img/api_host2.png new file mode 100644 index 00000000..7f6d60b8 Binary files /dev/null and b/docs/source/api/img/api_host2.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index b259a58e..88cd66c7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 - 标准化的 porting 接口 - 设备协议栈的使用简化到类如 uart 、dma 的使用，主机协议栈的使用简化到文件的使用 - 协议栈实现代码简短，并且从上往下看完就能理清 usb 枚举过程和 class 加载机制 +- Api 少，并且分为三类：dcd/hcd api、注册 api、命令回调 api 其他相关链接： @@ -39,13 +40,16 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 usb/usb_desc usb/usb_request usb/usb_enum + .. toctree:: :maxdepth: 1 :caption: API 手册 api/api_device api/api_host + api/api_port api/api_common + api/api_config .. toctree:: :maxdepth: 1 diff --git a/docs/source/porting_usbip.rst b/docs/source/porting_usbip.rst index eeceed9f..f3af10db 100644 --- a/docs/source/porting_usbip.rst +++ b/docs/source/porting_usbip.rst @@ -7,7 +7,7 @@ USB IP 差别说明 FSDEV -------------------------- -这个 ip 不同厂家基本没有对标准的寄存器地址进行修改，所以，用户使用时，仅需要修改 `USBD_IRQHandler` 和 `USB_BASE` 即可。 +这个 ip 不同厂家基本都是基于标准的 usb 寄存器，所以，用户使用时，仅需要修改 `USBD_IRQHandler` 、 `USB_NUM_BIDIR_ENDPOINTS` 、 `USB_BASE` 即可。 MUSB -------------------------- diff --git a/docs/source/quick_start/other_chip.rst b/docs/source/quick_start/other_chip.rst index 66e14a28..a693cd82 100644 --- a/docs/source/quick_start/other_chip.rst +++ b/docs/source/quick_start/other_chip.rst @@ -1,7 +1,7 @@ 芯片通用移植指南 ========================= -本节主要介绍所有带 USB IP 的芯片，移植 CherryUSB 主从协议栈时的通用步骤和注意事项。在往下看之前，需要你准备好一个可以打印 helloworld 的基本工程，并且实现了 `printf` 、 `malloc`、 `free`。如果是主机，需要准备好可以打印 helloworld 的带 OS 的工程。 +本节主要介绍所有带 USB IP 的芯片，移植 CherryUSB 主从协议栈时的通用步骤和注意事项。在往下看之前，需要 **你准备好一个可以打印 helloworld 的基本工程** ，并且实现了 `printf` 、 `malloc`、 `free`。如果是主机，需要 **准备好可以打印 helloworld 的带 OS 的工程**。 USB Device 移植要点 ----------------------- @@ -15,7 +15,7 @@ USB Device 移植要点 - 编译使用。各个 class 如何使用，参考 demo 下的 template -.. note:: device 移植要点其实就三个，实现 `usb_dc_low_level_init` ，改 `USBD_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` 、 `USB_NUM_BIDIR_ENDPOINTS=x`，改 `usb_config.h` 中的内容 +.. note:: device 移植要点其实就三个，实现 `usb_dc_low_level_init` ;改 `USBD_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` 、 `USB_NUM_BIDIR_ENDPOINTS=x`;改 `usb_config.h` 中的内容 USB Host 移植要点 ----------------------- @@ -37,8 +37,8 @@ USB Host 移植要点 - 编译使用。各个 class 如何使用，参考 demo 下的 `usb_host.c` 文件 -.. note:: device 移植要点其实就三个，实现 `usb_hc_low_level_init` ，改 `USBH_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` ，改 `usb_config.h` 中的内容 +.. note:: device 移植要点其实就三个，实现 `usb_hc_low_level_init` ; 改 `USBH_IRQHandler=xxxx` 、`USB_BASE=0xxxxx` ; 改 `usb_config.h` 中的内容 .. note:: 使用 host 时，推荐添加除了 hub 以外的所有适配的 class 驱动，达到自动加载驱动的目的。当然，如果不用，那就不添加。 -.. caution:: 如果主从 ip 共用一个中断，推荐设置 `USBD_IRQHandler=USBD_IRQHandler` 、 `USBH_IRQHandler=USBH_IRQHandler` ，然后由真正的中断函数根据主从模式调用这两个函数。 \ No newline at end of file +.. caution:: 如果主从 ip 共用一个中断，设置 `USBD_IRQHandler=USBD_IRQHandler` 、 `USBH_IRQHandler=USBH_IRQHandler` ，然后由真正的中断函数根据主从模式调用这两个函数。 \ No newline at end of file diff --git a/docs/source/usb/usb_basic.rst b/docs/source/usb/usb_basic.rst index a4c391cb..e44ba115 100644 --- a/docs/source/usb/usb_basic.rst +++ b/docs/source/usb/usb_basic.rst @@ -2,6 +2,7 @@ USB 基本概念 =========================== 本文主要对 USB 官方手册 `usb2.0.pdf `_ 中提供的第五章、第七章、第八章、第九章进行讲解。 +如果是初学 usb 的同学，推荐先不要看本节，而是将示例 demo 能够跑通了，熟悉了使用，再来看。 简介 ---------