From 513772a534ff87a18fbcf81c18ef75ea2204ec69 Mon Sep 17 00:00:00 2001 From: sakimisu <1203593632@qq.com> Date: Thu, 13 Jul 2023 20:30:12 +0800 Subject: [PATCH] update doc --- docs/source/api/api_common.rst | 48 --------------------------- docs/source/api/api_host.rst | 13 ++++---- docs/source/api/api_port.rst | 8 ++--- docs/source/index.rst | 39 ++++++++++++++++------ docs/source/quick_start/img/keil.png | Bin 0 -> 31394 bytes docs/source/quick_start/stm32.rst | 2 ++ 6 files changed, 41 insertions(+), 69 deletions(-) delete mode 100644 docs/source/api/api_common.rst create mode 100644 docs/source/quick_start/img/keil.png 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 0000000000000000000000000000000000000000..f954ebc33638fda2607f676fc2d38042429ebe6d GIT binary patch literal 31394 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 z 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