diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst index 7821d424..b8cd5701 100644 --- a/docs/source/api/api_port.rst +++ b/docs/source/api/api_port.rst @@ -1,4 +1,4 @@ -Porting +主从驱动 ========================= .. note:: 请注意,v1.1 版本开始增加 busid 形参,其余保持不变,所以 API 说明不做更新 @@ -37,6 +37,7 @@ usbd_set_address int usbd_set_address(const uint8_t addr); +- **addr** 设备地址 - **return** 返回 0 表示正确,其他表示错误 usbd_ep_open @@ -46,8 +47,9 @@ usbd_ep_open .. code-block:: C - int usbd_ep_open(const struct usbd_endpoint_cfg *ep_cfg); + int usbd_ep_open(const struct usb_endpoint_descriptor *ep); +- **ep** 端点描述符 - **return** 返回 0 表示正确,其他表示错误 usbd_ep_close @@ -59,7 +61,7 @@ usbd_ep_close int usbd_ep_close(const uint8_t ep); -- **event** +- **ep** 端点地址 - **return** 返回 0 表示正确,其他表示错误 usbd_ep_set_stall @@ -126,7 +128,7 @@ usbd_ep_start_read - **data_len** 接收长度,原则上无限长,推荐 16K 字节以内,并且推荐是最大包长的整数倍 - **return** 返回 0 表示正确,其他表示错误 -.. note:: 启动接收以后,以下两种情况,会进入传输完成中断:1、最后一包为短包;2、接收总长度等于 data_len +.. note:: 启动接收以后,以下两种情况,会进入传输完成中断:1、最后一包为短包(小于 EP MPS);2、接收总长度等于 data_len host controller(hcd) ------------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 08458da6..8c9c9ea2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -53,6 +53,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 :maxdepth: 1 :caption: 快速上手 + quick_start/start quick_start/demo quick_start/transplant quick_start/rtthread diff --git a/docs/source/q&a.rst b/docs/source/q&a.rst index 52a63c27..357c8eeb 100644 --- a/docs/source/q&a.rst +++ b/docs/source/q&a.rst @@ -4,6 +4,8 @@ Q & A 移植提问模板 ---------------- +提问提交地址: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html + - 使用的板子,引脚,USB IP - USB 中断,时钟,引脚,寄存器地址是否正确,截图 - 是否能进 USB 中断 diff --git a/docs/source/quick_start/start.rst b/docs/source/quick_start/start.rst new file mode 100644 index 00000000..ba3cc786 --- /dev/null +++ b/docs/source/quick_start/start.rst @@ -0,0 +1,49 @@ +入门必看 +================== + +首先欢迎大家来到 usb 的世界,在这里你可以学习到 usb 各种知识以及 cherryusb 的移植使用进阶等等。但是呢,刚进来的你,一定很懵懂,因为 USB 很难(其实当你学会了 cherryusb以后,你会发现,USB 一点都不难), +那么这种情况下,你的学习路线,应该是怎么样呢?在这里,我推荐大家是按照我得学习路线来学习,这样对你的 USB 成长是最有帮助的,并且你也不会中途放弃。 + +首先,不允许上来就看概念,有句古诗说的好, **纸上得来终觉浅,绝知此事要躬行** ,光看纸面上的东西,你是学不到什么的,只有当自己实践了,你才能更深入的了解这些概念。那么作为初学者,你应该怎么做呢?请看以下步骤。 + + +第一步 +------------- + +你需要学过 C 语言,UART, DMA,这是基础,如果没学过,请去学习,不然你会很吃力。你会问 USB 跟 UART/DMA 有什么关系? 我只能说两个字, **等价** + +第二步 +------------- + +下载 demo 工程并跑通能运行, **建议学习慢的,使用 demo 同型号芯片**,学习快的,可以选择自己移植相关支持的型号的芯片。你连 demo 都跑不通,你学什么 USB,你说对不对? + +第三步 +--------- + +非常好,到这步,说明你已经能熟练移植和跑通所有示例了,那么接下来,你应该学习什么呢?请直接跳到 **USB 枚举** 章节,了解下 USB 枚举过程,然后你会知道 USB 的两个概念, **请求** 和 **描述符**。群文件有各类设备枚举的抓包,可以下下来看看。 + + +第四步 +---------- + +当你看了 **USB 枚举** 章节并且知道了一个概念, **描述符** 以后,这个时候,你就可以去简单看看什么是描述符,有哪些描述符,然后你需要记住, **设备、配置、接口、端点描述符的组成**,并背下来,其余的你都不需要知道,因为其他都是固定的,后续都是 CV 。 + +第五步 +---------- + +然后呢,你可以再去看看请求结构体的组成,看看有哪些请求,简单了解即可,为什么呢?因为它不过就是 8 字节的数据格式,大家都会写一个 UART + 自定义协议,那么 USB 的请求也是一样的,只不过是规定好了而已。 + +第六步 +---------- + +这个时候,你该去熟悉下协议栈的一些 API 了,参考 API 手册章节,记住,都要看完哦 + +第七步 +---------- + +到这步呢,你肯定已经非常懂了,然后就可以开始你的一些小功能小项目了,在此期间呢,请查看 **USB 知识点拓展** 章节,因为有些东西,他比较重要,也是需要反复说明的。 + +第八步 +---------- + +都到这步了,你应该不需要我了,这个时候,你可以去看看 USB 概念,看看 USB 的一些细节,看看 CherryUSB 的代码流程了。然后就是巩固巩固再巩固了。恭喜你,出师了!!! \ No newline at end of file diff --git a/docs/source/usb/usb_ext.rst b/docs/source/usb/usb_ext.rst index 5ba2d2f5..48016a53 100644 --- a/docs/source/usb/usb_ext.rst +++ b/docs/source/usb/usb_ext.rst @@ -11,6 +11,11 @@ USB 知识点拓展 对于软件分包来说,一次发送的长度即使是 16K, **内部也是通过软件分包的,在这种情况下,发送长度的多少不会对速度有任何提升**。 对于硬件分包来说,发送的长度会影响速度,因为硬件分包是通过 DMA 来进行的, **一次发送的长度越大,DMA 的效率就越高,速度也就越快**。(当然,其他协议栈虽然使用了 dma,但是部分代码实现还是按照一个包进行,等于没用,这也是速度低的一个原因) +什么是短包 +---------------- + +在上面我们讲了分包之后,短包就是分包的最后一个包(并且长度小于 EP MPS).比如发送 129 字节的数据,那么 USB 会按照 64 + 64 + 1 的形式传输,最后一个包是1个字节,这1个字节就是短包。 + 什么是 ZLP ------------- @@ -20,5 +25,8 @@ ZLP,顾名思义,零长度数据包,是 USB 设备在数据传输结束时 .. caution:: ZLP 功能仅限于 CONTROL 和 BULK 传输 比如 cdc acm,本身是没有协议的,所以我们发送需要 ZLP,接收也需要 ZLP,但是又由于 PC 的 USB 主机驱动默认 **接收不开 ZLP**, 因此,我们 **接收的长度必须设置为 EP MPS**,通常为 64 或者 512, -而如果接收的数据不设置成 EP MPS ,就会带来数据接收不完成的问题,比如设置成 2048,如果主机发送的是 512/1025/1536,则 USB IP 不会进入完成状态,因为完成的条件是数据等于 2048 或者最后一个包是短包。 -再比如 MSC ,MSC 的逻辑是 CMD + DATA + STATUS 的流程,CMD 阶段包含了要接收或者发送的数据长度,所以不需要 ZLP 功能。 \ No newline at end of file +而如果接收的数据不设置成 EP MPS ,就会带来数据接收不完成的问题,比如设置成 2048,如果主机发送的是 512/1024/1536,则 USB IP 不会进入完成状态,因为完成的条件是数据等于 2048 或者最后一个包是短包。 +再比如 MSC ,MSC 的逻辑是 CMD + DATA + STATUS 的流程,CMD 阶段包含了要接收或者发送的数据长度,所以不需要 ZLP 功能。 + +什么是帧与微帧 +----------------