From c377747e67de1ff61d123888f4e066312439db4e Mon Sep 17 00:00:00 2001 From: sakumisu <1203593632@qq.com> Date: Thu, 26 Sep 2024 21:54:46 +0800 Subject: [PATCH] docs: update rst --- docs/source/api/api_port.rst | 2 ++ docs/source/quick_start/start.rst | 16 ++++++++++------ docs/source/usb/usb_ext.rst | 17 ++++++++++------- 3 files changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst index b8cd5701..daed52e7 100644 --- a/docs/source/api/api_port.rst +++ b/docs/source/api/api_port.rst @@ -130,6 +130,8 @@ usbd_ep_start_read .. note:: 启动接收以后，以下两种情况，会进入传输完成中断：1、最后一包为短包（小于 EP MPS）；2、接收总长度等于 data_len +.. note:: 对于 bulk 传输，data_len 通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（MSC）; 主机手动发送 ZLP 或者短包（RNDIS） + host controller(hcd) ------------------------ diff --git a/docs/source/quick_start/start.rst b/docs/source/quick_start/start.rst index ba3cc786..a6f0ca6f 100644 --- a/docs/source/quick_start/start.rst +++ b/docs/source/quick_start/start.rst @@ -20,30 +20,34 @@ 第三步 --------- -非常好，到这步，说明你已经能熟练移植和跑通所有示例了，那么接下来，你应该学习什么呢？请直接跳到 **USB 枚举** 章节，了解下 USB 枚举过程，然后你会知道 USB 的两个概念， **请求** 和 **描述符**。群文件有各类设备枚举的抓包，可以下下来看看。 - +非常好，到这步，说明你已经能熟练移植和跑通所有示例了，那么接下来，你应该学习什么呢？ **事务**， **请求** 和 **描述符**（在 USB 的学习过程中，你只需要知道这三个，其余都不需要知道）。 第四步 ---------- -当你看了 **USB 枚举** 章节并且知道了一个概念， **描述符** 以后，这个时候，你就可以去简单看看什么是描述符，有哪些描述符，然后你需要记住， **设备、配置、接口、端点描述符的组成**，并背下来，其余的你都不需要知道，因为其他都是固定的，后续都是 CV 。 +首先我们需要知道 USB 事务包含 SETUP/IN/OUT，其实就是等价于发送命令，发送数据和接收数据，很简单。至于下面枚举中你在外面的网络中所听到的控制阶段，数据阶段，状态阶段，他不是事务，他只是用多个事务代表了一个阶段而已。 第五步 ---------- -然后呢，你可以再去看看请求结构体的组成，看看有哪些请求，简单了解即可，为什么呢？因为它不过就是 8 字节的数据格式，大家都会写一个 UART + 自定义协议，那么 USB 的请求也是一样的，只不过是规定好了而已。 +然后你再去看 **USB 枚举** 章节并且知道了一个概念： **描述符** ，这个时候，你就可以去简单看看什么是描述符，有哪些描述符，然后你需要记住， **设备、配置、接口、端点描述符的组成**，并背下来，其余的你都不需要知道，因为其他都是固定的，后续都是 CV 。群文件有各类设备枚举的抓包，可以下下来看看。 第六步 ---------- -这个时候，你该去熟悉下协议栈的一些 API 了，参考 API 手册章节，记住，都要看完哦 +然后呢，你可以再去看看什么是 **请求** ，请求结构体的组成，看看有哪些请求，简单了解即可，为什么呢？因为它不过就是 8 字节的数据格式，大家都会写一个 UART + 自定义协议，那么 USB 的请求也是一样的，只不过是规定好了而已。 第七步 ---------- -到这步呢，你肯定已经非常懂了，然后就可以开始你的一些小功能小项目了，在此期间呢，请查看 **USB 知识点拓展** 章节，因为有些东西，他比较重要，也是需要反复说明的。 +这个时候，你该去熟悉下协议栈的一些 API 了，参考 **API 手册** 章节。并且你需要知道中断完成的条件是什么，什么时候算接收完成，什么时候算发送完成，可以参考 **USB 知识点拓展** 章节。 第八步 ---------- +到这步呢，你肯定已经非常懂了，然后就可以开始你的一些小功能小项目了，在此期间呢，请循环查看 **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 48016a53..b403f476 100644 --- a/docs/source/usb/usb_ext.rst +++ b/docs/source/usb/usb_ext.rst @@ -19,14 +19,17 @@ USB 知识点拓展 什么是 ZLP ------------- -ZLP，顾名思义，零长度数据包，是 USB 设备在数据传输结束时，如果数据长度正好是最大包长度的整数倍，那么就会发送一个 ZLP 数据包，用来告诉主机数据传输结束。 -当我们发送或者接收的时候，如果没有相关的协议告诉我们接收或者发送的长度，这种情况下我们就需要 ZLP 功能。 +ZLP，顾名思义，零长度数据包，也就是数据长度为0 的短包。是 USB 设备在数据传输结束时，如果数据长度正好是最大包长度的整数倍，那么就需要发送一个 ZLP 数据包，用来告诉对方数据传输结束。 .. caution:: ZLP 功能仅限于 CONTROL 和 BULK 传输 -比如 cdc acm，本身是没有协议的，所以我们发送需要 ZLP，接收也需要 ZLP，但是又由于 PC 的 USB 主机驱动默认 **接收不开 ZLP**, 因此，我们 **接收的长度必须设置为 EP MPS**，通常为 64 或者 512， -而如果接收的数据不设置成 EP MPS ，就会带来数据接收不完成的问题，比如设置成 2048,如果主机发送的是 512/1024/1536，则 USB IP 不会进入完成状态，因为完成的条件是数据等于 2048 或者最后一个包是短包。 -再比如 MSC ，MSC 的逻辑是 CMD + DATA + STATUS 的流程，CMD 阶段包含了要接收或者发送的数据长度，所以不需要 ZLP 功能。 +什么时候算中断完成 +-------------------- -什么是帧与微帧 ----------------- +从机接收：接收的长度与设置的长度相等；接收的最后一个包为短包。 +从机发送：发送的长度与设置的长度相等，如果发送的长度是 EP MPS 的整数倍，需要再发送一个 ZLP（仅限 control 和 bulk 传输）。 + +主机接收：同从机接收 +主机发送：发送的长度与设置的长度相等 + +.. note:: 对于从机接收，并且是 bulk 传输，接收长度通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（例如 MSC）; 主机手动发送 ZLP 或者短包（例如 RNDIS） \ No newline at end of file