diff --git a/docs/source/api/api_common.rst b/docs/source/api/api_common.rst deleted file mode 100644 index 3c4653d9..00000000 --- a/docs/source/api/api_common.rst +++ /dev/null @@ -1,48 +0,0 @@ -其他 -========================= - -usb_malloc -"""""""""""""""""""""""""""""""""""" - -``usb_malloc`` 用来申请内存。 - -.. code-block:: C - - void *usb_malloc(size_t size); - -- **size** 要申请的内存大小 -- **return** 申请的内存地址 - -usb_free -"""""""""""""""""""""""""""""""""""" - -``usb_free`` 用来释放申请的内存。 - -.. code-block:: C - - void usb_free(void *ptr); - -- **ptr** 要释放的内存地址 - -usb_iomalloc -"""""""""""""""""""""""""""""""""""" - -``usb_iomalloc`` 用来申请内存,并按照 `CONFIG_DCACHE_LINE_SIZE` 对齐,一般使用到 dcache 和 dma 需要对齐操作的时候使用。 - -.. code-block:: C - - void *usb_iomalloc(size_t size); - -- **size** 要申请的内存大小 -- **return** 申请的内存地址 - -usb_iofree -"""""""""""""""""""""""""""""""""""" - -``usb_iofree`` 用来释放申请的内存。 - -.. code-block:: C - - void usb_iofree(void *ptr); - -- **ptr** 要释放的内存地址 diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst index 979aaa8e..56af923b 100644 --- a/docs/source/api/api_host.rst +++ b/docs/source/api/api_host.rst @@ -82,11 +82,13 @@ hubport 结构体 const char *iManufacturer; const char *iProduct; const char *iSerialNumber; - #if 0 - uint8_t* raw_config_desc; - #endif - USB_MEM_ALIGNX struct usb_setup_packet setup; + uint8_t *raw_config_desc; + struct usb_setup_packet *setup; struct usbh_hub *parent; + #ifdef CONFIG_USBHOST_XHCI + uint32_t protocol; /* port protocol, for xhci, some ports are USB2.0, others are USB3.0 */ + #endif + usb_osal_thread_t thread; }; hub 结构体 @@ -101,12 +103,11 @@ hub 结构体 uint8_t index; uint8_t hub_addr; usbh_pipe_t intin; - USB_MEM_ALIGNX uint8_t int_buffer[1]; + uint8_t *int_buffer; struct usbh_urb intin_urb; struct usb_hub_descriptor hub_desc; struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS]; struct usbh_hubport *parent; - usb_slist_t hub_event_list; }; usbh_initialize diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst index 95be593d..528809d5 100644 --- a/docs/source/api/api_port.rst +++ b/docs/source/api/api_port.rst @@ -153,19 +153,19 @@ usbh_roothub_control - **buf** 接收缓冲区 - **return** 返回 0 表示正确,其他表示错误 -usbh_ep0_pipe_reconfigure +usbh_ep_pipe_reconfigure """""""""""""""""""""""""""""""""""" -``usbh_ep0_pipe_reconfigure`` 重新设置端点 0 的 pipe 属性。 **此函数不对用户开放**。 +``usbh_ep_pipe_reconfigure`` 重新设置端点 0 的 pipe 属性。 **此函数不对用户开放**。 .. code-block:: C - int usbh_ep0_pipe_reconfigure(usbh_pipe_t pipe, uint8_t dev_addr, uint8_t ep_mps, uint8_t speed); + int usbh_ep_pipe_reconfigure(usbh_pipe_t pipe, uint8_t dev_addr, uint8_t ep_mps, uint8_t mult); - **pipe** pipe 句柄 - **dev_addr** 端点所在设备地址 - **ep_mps** 端点最大包长 -- **speed** 端点所在设备的速度 +- **mult** 端点一次传输个数 - **return** 返回 0 表示正确,其他表示错误 usbh_pipe_alloc diff --git a/docs/source/index.rst b/docs/source/index.rst index 0bbb9fe8..faa3dac6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,23 +8,41 @@ CherryUSB 使用指南 CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 USB 主从协议栈。同时 CherryUSB 具有以下优点: -- 代码精简,并且内存占用极小,而且还可进一步的裁剪 -- 全面的 class 驱动,并且主从 class 驱动全部模板化,方便用户增加新的 class 驱动以及学习的时候查找规律 -- 可供用户使用的 API 非常少,并且分类清晰。从机:初始化 + 注册、命令回调类、数据收发类;主机:初始化 + 查找类、数据收发类 -- 树状化编程,代码层层递进,方便用户理清函数调用关系、枚举和 class 驱动加载过程 -- 标准化的 porting 接口,相同 ip 无需重写驱动,并且 porting 驱动也进行了模板化,方便用户新增 porting。 -- 主从收发接口的使用等价于 uart tx/rx dma 的使用,长度也没有限制 -- 能够达到 USB 硬件理论带宽 +**易于学习 USB** -从机协议栈整体执行流程: +为了方便用户学习 USB 基本知识、枚举、驱动加载、IP 驱动,因此,编写的代码具备以下优点: + +- 代码精简,逻辑简单,无复杂 C 语言语法 +- 树状化编程,代码层层递进 +- Class 驱动和 porting 驱动模板化、精简化 +- API 分类清晰(从机:初始化、注册类、命令回调类、数据收发类;主机:初始化、查找类、数据收发类) + +**易于使用 USB** + +为了方便用户使用 USB 接口,考虑到用户学习过 uart 和 dma,因此,设计的数据收发类接口具备以下优点: + +- 等价于使用 uart tx dma/uart rx dma +- 收发长度没有限制,用户不需要关心 USB 分包过程(porting 驱动做分包过程) + +**易于发挥 USB 性能** + +考虑到 USB 性能问题,尽量达到 USB 硬件理论带宽,因此,设计的数据收发类接口具备以下优点: + +- Porting 驱动直接对接寄存器,无抽象层封装 +- Memory zero copy +- IP 如果带 DMA 则使用 DMA 模式(DMA 带硬件分包功能) +- 长度无限制,方便对接硬件 DMA 并且发挥 DMA 的优势 +- 分包功能在中断中处理 + +**从机协议栈整体执行流程** .. figure:: usbdev.svg -主机协议栈整体执行流程: +**主机协议栈整体执行流程** .. figure:: usbhost.svg -其他相关链接: +**其他相关链接** - **CherryUSB 大纲** https://www.bilibili.com/video/BV1st4y1H7K2 - **从机协议栈视频教程** https://www.bilibili.com/video/BV1Ef4y1t73d @@ -59,7 +77,6 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 api/api_device api/api_host api/api_port - api/api_common api/api_config .. toctree:: diff --git a/docs/source/quick_start/img/keil.png b/docs/source/quick_start/img/keil.png new file mode 100644 index 00000000..f954ebc3 Binary files /dev/null and b/docs/source/quick_start/img/keil.png differ diff --git a/docs/source/quick_start/stm32.rst b/docs/source/quick_start/stm32.rst index 906a1374..5f1b80c3 100644 --- a/docs/source/quick_start/stm32.rst +++ b/docs/source/quick_start/stm32.rst @@ -36,6 +36,8 @@ .. caution :: 如果使用 STM32F7 或者 STM32H7, 请在 CFLAG 中添加 STM32F7 或者 STM32H7 宏定义,否则无法枚举 +.. figure:: img/keil.png + 工程样例试用 -----------------------