diff --git a/docs/source/demo/img/otg.png b/docs/source/demo/img/otg.png new file mode 100644 index 00000000..9605176a Binary files /dev/null and b/docs/source/demo/img/otg.png differ diff --git a/docs/source/demo/usb_otg.rst b/docs/source/demo/usb_otg.rst new file mode 100644 index 00000000..78692cc0 --- /dev/null +++ b/docs/source/demo/usb_otg.rst @@ -0,0 +1,15 @@ +OTG 功能的使用 +========================= + +如果需要使用 OTG 功能，首先使用的芯片需要支持 ID 检测功能，然后使能 ``CONFIG_USB_OTG_ENABLE`` 宏，将之前的例程中 ``usbh_initialize`` 或者 ``usbh_initialize`` +替换成 ``usbotg_initialize`` 即可。 + +ID 检测电路根据不同的 USB 接口类型有所不同，常见的有 micro-USB 和 USB-C 两种接口类型。 + +- 如果是 micro-USB 接口，则将 ID 线连接到芯片的 ID 引脚，并使能 ID 功能即可。 +- 如果是 USB-C 接口，由于没有 ID 引脚，则需要借助 CC 电路转换成 ID 然后连接到芯片的 ID 引脚，常见电路图如下所示（DNP 表示不焊接）： + +.. figure:: img/otg.png + + +.. note:: 除 ID 引脚以外，还需要增加 VBUS 输出开关控制，当工作在 host 时，开启 VBUS 供电，当工作在 device 时，关闭 VBUS 供电。 \ No newline at end of file diff --git a/docs/source/demo/usbd_audiov1.rst b/docs/source/demo/usbd_audiov1.rst index 9d2e3051..794ac8f6 100644 --- a/docs/source/demo/usbd_audiov1.rst +++ b/docs/source/demo/usbd_audiov1.rst @@ -1,5 +1,7 @@ usbd_audiov1 =============== -.. note:: 在使用windows 时，当修改描述符任意参数时，必须同步修改字符串描述符，并且卸载驱动，否则windows会认为设备未更改，继续使用旧的驱动，导致无法识别设备。Linux 不受此限制。 +在使用 UAC1.0 时，需要注意以下几点： +- 在使用windows 时，当修改描述符任意参数时，必须同步修改字符串描述符，并且卸载驱动，否则windows会认为设备未更改，继续使用旧的驱动，导致无法识别设备。Linux 不受此限制。 +- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息，无需第一步 \ No newline at end of file diff --git a/docs/source/demo/usbd_audiov2.rst b/docs/source/demo/usbd_audiov2.rst index 816532c9..0390f17d 100644 --- a/docs/source/demo/usbd_audiov2.rst +++ b/docs/source/demo/usbd_audiov2.rst @@ -1,6 +1,9 @@ usbd_audiov2 =============== -.. note:: 在使用windows 时，当修改描述符任意参数时，必须同步修改字符串描述符，并且卸载驱动，否则windows会认为设备未更改，继续使用旧的驱动，导致无法识别设备。Linux 不受此限制。 +在使用 UAC2.0 时，需要注意以下几点： -.. note:: windows 10 uac2.0 功能不完善，请使用 windows 11 测试uac2.0 功能。Linux 不受此限制。 \ No newline at end of file +- 在使用windows 时，当修改描述符任意参数时，必须同步修改字符串描述符，并且卸载驱动，否则windows会认为设备未更改，继续使用旧的驱动，导致无法识别设备。Linux 不受此限制。 +- QQ 群文件中下载 RemoveGhostDev64.exe 可以自动删除所有 USB 注册的驱动信息，无需第一步 +- windows 10 uac2.0 功能不完善，请使用 windows 11 测试uac2.0 功能。Linux 不受此限制 +- windows 中设置的采样率表范围在多通道时（通道数大于2）计算有误，比如设置 8K~96K，那么实际是大于等于8K 小于96K，而非小于等于96K。Linux 不受此限制 diff --git a/docs/source/index.rst b/docs/source/index.rst index 90c3b8aa..8cdb78cd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,10 +44,9 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 **其他相关链接** -- **CherryUSB 大纲** https://www.bilibili.com/video/BV1st4y1H7K2 -- **CherryUSB 从机协议栈视频教程** https://www.bilibili.com/video/BV1Ef4y1t73d -- **CherryUSB 腾讯会议** https://www.bilibili.com/video/BV16x421y7mM -- **github** https://github.com/sakumisu/CherryUSB +- **视频教程**： https://www.bilibili.com/cheese/play/ss707687201 +- **github** ： https://github.com/sakumisu/CherryUSB +- **CherryUSB原理性分析和应用实践-汉斯期刊**： https://www.hanspub.org/journal/paperinformation?paperid=126903 .. toctree:: :maxdepth: 1 @@ -57,10 +56,9 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 quick_start/demo quick_start/transplant quick_start/rtthread - quick_start/esp - q&a - opensource - share + quick_start/q&a + quick_start/share + quick_start/opensource .. toctree:: :maxdepth: 1 @@ -116,6 +114,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 demo/usbh_wifi demo/usbd_vendor demo/usbh_vendor + demo/usb_otg .. toctree:: :maxdepth: 1 diff --git a/docs/source/quick_start/demo.rst b/docs/source/quick_start/demo.rst index 9c5e6569..926e318e 100644 --- a/docs/source/quick_start/demo.rst +++ b/docs/source/quick_start/demo.rst @@ -29,6 +29,21 @@ - esp32p4：一个 USB2.0 内置全速 PHY 芯片，一个 USB2.0 内置高速 PHY 芯片，支持主从机。 - 默认 demo 采用组件库安装的形式，在 https://components.espressif.com/ 中搜索 cherryusb 即可 +ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发环境。 + +- ctrl + shift + p 选择 ESP-IDF 欢迎界面，然后选择 Component mananger + +.. figure:: img/esp1.png + +- 找到 cherryusb 并安装 + +.. figure:: img/esp2.png + +- 打开 menuconfig，并打开 cherryusb 的配置，根据实际情况选择主机或者从机模式 + +.. figure:: img/esp3.png +.. figure:: img/esp4.png + 基于飞腾派系列芯片（官方 SDK 支持） ----------------------------------- diff --git a/docs/source/quick_start/esp.rst b/docs/source/quick_start/esp.rst deleted file mode 100644 index 29639e05..00000000 --- a/docs/source/quick_start/esp.rst +++ /dev/null @@ -1,17 +0,0 @@ -基于 ESP-Registry 开发指南 -=========================== - -ESP-Registry 可以参考官方文档，推荐使用 vscode + esp-idf 的开发环境。 - -- ctrl + shift + p 选择 ESP-IDF 欢迎界面，然后选择 Component mananger - -.. figure:: img/esp1.png - -- 找到 cherryusb 并安装 - -.. figure:: img/esp2.png - -- 打开 menuconfig，并打开 cherryusb 的配置，根据实际情况选择主机或者从机模式 - -.. figure:: img/esp3.png -.. figure:: img/esp4.png \ No newline at end of file diff --git a/docs/source/quick_start/img/question1.png b/docs/source/quick_start/img/question1.png new file mode 100644 index 00000000..a852e6aa Binary files /dev/null and b/docs/source/quick_start/img/question1.png differ diff --git a/docs/source/quick_start/img/question2.png b/docs/source/quick_start/img/question2.png new file mode 100644 index 00000000..e00b3bfa Binary files /dev/null and b/docs/source/quick_start/img/question2.png differ diff --git a/docs/source/opensource.rst b/docs/source/quick_start/opensource.rst similarity index 100% rename from docs/source/opensource.rst rename to docs/source/quick_start/opensource.rst diff --git a/docs/source/q&a.rst b/docs/source/quick_start/q&a.rst similarity index 71% rename from docs/source/q&a.rst rename to docs/source/quick_start/q&a.rst index 59b9dc7d..dfdbac85 100644 --- a/docs/source/q&a.rst +++ b/docs/source/quick_start/q&a.rst @@ -46,16 +46,52 @@ GD IP 采用 DWC2，但是读取的硬件参数都是 0（我也不懂为什么 USB_OTG_INEP(i)->DIEPCTL = (USB_OTG_DIEPCTL_EPDIS | USB_OTG_DIEPCTL_SNAK); USB_OTG_OUTEP(i)->DOEPCTL = (USB_OTG_DOEPCTL_EPDIS | USB_OTG_DOEPCTL_SNAK); +除此之外可能存在其他未知 BUG，请自行测试。 + +开启 USB_LOG_DBG 后无法枚举 +---------------------------------------------------------------- + +有且仅有商业性 IP 开启后可以枚举，其余 IP 禁止开启，否则无法枚举。懂得都懂。 + +USB3 CV测试用哪个版本 +------------------------------ + +1.4.3 版本及以上 + +Ep addr XXX fifo overflow +------------------------------ + +.. figure:: img/question1.png + +该错误表示该端点默认设置的 fifo 空间不够用，需要增大 fifo 空间，通常见于 DWC2/MUSB IP。FIFO 设置参考相关的 glue 文件。 + Ep addr XXX overflow ------------------------------ -该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用。并且默认 demo 不做双向功能，考虑到不是所有的 IP 都支持，因此默认是 81 02 这样的而不是 81 01， -如果支持，自行修改。某些 IP 双向端点可能会占用相同的硬件信息，不一定能同时使用，自行检查。 +.. figure:: img/question2.png + +该错误表示该 IP 硬件上没有这么多端点, 请更换 IP or 减少端点使用。 +当然也可以修改为双向端点，考虑到不是所有的 IP 都支持双向端点，因此默认 demo 不做双向功能，举例默认是 81 02 这样的而不是 81 01，如果支持，自行修改。某些 IP 双向端点可能会占用相同的硬件信息，不一定能同时使用，自行检查。 This dwc2 version does not support dma mode, so stop working ---------------------------------------------------------------- -该 DWC2 版本不支持 dma 模式，禁止使用。 +该 DWC2 版本不支持 dma 模式，禁止使用。不使用 DMA 模式会频繁触发 NAK 中断（大概几十us一次），CPU 占用率过高。 + +OTG 有哪些芯片支持 +------------------------------ + +当前主线仅 HPM 芯片支持 OTG 功能，通过 ID 引脚自动切换主从模式，其他芯片请使用手动切换模式 OR 自行实现添加 ID 识别的驱动。 + +PC 识别的 COM 口如何更改名称 +---------------------------------------------------------------- + +这是微软对 CDC ACM 的驱动问题，无法修改，如需修改，请联系微软并缴纳费用+编写驱动后即可更改。 + +connect 和 disconnect event 不触发 +---------------------------------------------------------------- + +当前仅 hpm 芯片支持 connect 和 disconnect 事件，其他芯片请使用 USB 检测 vbus 电路。DWC2 IP 支持，但是由于需要占用引脚，并且大多是log 口，然后不同使能的配置也不一样，因此不做支持。 __has_include 报错 ------------------------------------------------------------------ @@ -78,6 +114,7 @@ Failed to enable port USB_ERR_NAK 说明 ---------------------------------------------------------------- + USB_ERR_NAK 只存在于 DWC2 buffer dma 模式，DWC2 在 buffer dma模式下对于中断传输不支持硬件处理 NAK 中断，因此需要软件处理，导致 NAK 中断非常多，建议搭配定时器使用。 DWC2 scatter/gather dma 模式下全部由硬件处理，但是不支持 split 传输。总结， **半斤 IP**。 @@ -85,14 +122,3 @@ USB host 连接 USB 网卡问题 ---------------------------------------------------------------- 表现为能识别网卡并且分配到 IP 地址，但是无法 ping 通，这是因为网卡自身需要开启自动拨号，通常需要使用 AT 口设置。具体为 EC20/ML307 等模块。 - -PC 识别的 COM 口如何更改名称 ----------------------------------------------------------------- - -这是微软对 CDC ACM 的驱动问题，无法修改，如需修改，请联系微软并缴纳费用即可更改。 - -connect 和 disconnect event 不触发 ----------------------------------------------------------------- - -当前仅 hpm 芯片支持 connect 和 disconnect 事件，其他芯片请使用 USB 检测 vbus 电路。DWC2 IP 支持，但是由于需要占用引脚，并且大多是log 口， -然后不同使能的配置也不一样，因此不做支持。 \ No newline at end of file diff --git a/docs/source/share.rst b/docs/source/quick_start/share.rst similarity index 100% rename from docs/source/share.rst rename to docs/source/quick_start/share.rst diff --git a/docs/source/usb/usb_ext.rst b/docs/source/usb/usb_ext.rst index fa81f728..86b87a53 100644 --- a/docs/source/usb/usb_ext.rst +++ b/docs/source/usb/usb_ext.rst @@ -29,9 +29,11 @@ ZLP，顾名思义，零长度数据包，也就是数据长度为0 的短包。 -------------------- 从机接收：接收的长度与设置的长度相等；接收的最后一个包为短包。 -从机发送：发送的长度与设置的长度相等，如果发送的长度是 EP MPS 的整数倍，需要再发送一个 ZLP（仅限 control 和 bulk 传输）。 +从机发送：发送的长度与设置的长度相等，如果发送的长度是 EP MPS 的整数倍， **通常** 需要再发送一个 ZLP（仅限 control 和 bulk 传输）。 + +.. note:: 对于从机接收，并且是 bulk 传输，接收长度通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（例如 MSC）; 主机手动发送 ZLP 或者短包（例如 RNDIS） + +.. note:: 对于从机发送，并且是 bulk 传输，发送长度没有限制，但是如果是 EP MPS 整数倍，通常需要发送 ZLP。自定义协议则不需要发送 ZLP，例如 MSC。 主机接收：同从机接收 主机发送：发送的长度与设置的长度相等 - -.. note:: 对于从机接收，并且是 bulk 传输，接收长度通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（例如 MSC）; 主机手动发送 ZLP 或者短包（例如 RNDIS） \ No newline at end of file