From eaefb8ed21ed23f732e8b608ed7948e6b71ab0d8 Mon Sep 17 00:00:00 2001 From: sakumisu <1203593632@qq.com> Date: Fri, 30 Jan 2026 22:10:34 +0800 Subject: docs: update docs and add english version Signed-off-by: sakumisu <1203593632@qq.com> --- docs/source/api/api_config.rst | 163 --------- docs/source/api/api_device.rst | 502 ---------------------------- docs/source/api/api_host.rst | 317 ------------------ docs/source/api/api_port.rst | 266 --------------- docs/source/api/img/api_device1.png | Bin 296936 -> 0 bytes docs/source/api/img/api_host1.png | Bin 43480 -> 0 bytes docs/source/api/img/api_host2.png | Bin 46429 -> 0 bytes docs/source/class/class_audio.rst | 4 - docs/source/class/class_cdc.rst | 4 - docs/source/class/class_hid.rst | 4 - docs/source/class/class_msc.rst | 4 - docs/source/class/class_video.rst | 4 - docs/source/class/winusb.rst | 2 - docs/source/conf.py | 37 -- docs/source/demo/img/cherryadb.png | Bin 42508 -> 0 bytes docs/source/demo/img/otg.png | Bin 477332 -> 0 bytes docs/source/demo/img/rtt_adb_shell1.png | Bin 67618 -> 0 bytes docs/source/demo/img/rtt_adb_shell2.png | Bin 508959 -> 0 bytes docs/source/demo/img/usbh_serial.png | Bin 3906892 -> 0 bytes docs/source/demo/usb_otg.rst | 15 - docs/source/demo/usbd_adb.rst | 28 -- docs/source/demo/usbd_audiov1.rst | 7 - docs/source/demo/usbd_audiov2.rst | 9 - docs/source/demo/usbd_cdc_acm.rst | 104 ------ docs/source/demo/usbd_ecm.rst | 2 - docs/source/demo/usbd_hid.rst | 4 - docs/source/demo/usbd_msc.rst | 39 --- docs/source/demo/usbd_rndis.rst | 2 - docs/source/demo/usbd_vendor.rst | 44 --- docs/source/demo/usbd_video.rst | 83 ----- docs/source/demo/usbd_webusb.rst | 21 -- docs/source/demo/usbd_winusb.rst | 55 --- docs/source/demo/usbh_bluetooth.rst | 2 - docs/source/demo/usbh_hid.rst | 55 --- docs/source/demo/usbh_msc.rst | 56 ---- docs/source/demo/usbh_net.rst | 156 --------- docs/source/demo/usbh_serial.rst | 196 ----------- docs/source/demo/usbh_vendor.rst | 127 ------- docs/source/demo/usbh_wifi.rst | 2 - docs/source/index.rst | 157 --------- docs/source/quick_start/demo.rst | 224 ------------- docs/source/quick_start/img/env0.png | Bin 17041 -> 0 bytes docs/source/quick_start/img/env1.png | Bin 42859 -> 0 bytes docs/source/quick_start/img/env2.png | Bin 66915 -> 0 bytes docs/source/quick_start/img/esp1.png | Bin 28939 -> 0 bytes docs/source/quick_start/img/esp2.png | Bin 72318 -> 0 bytes docs/source/quick_start/img/esp3.png | Bin 29745 -> 0 bytes docs/source/quick_start/img/esp4.png | Bin 52878 -> 0 bytes docs/source/quick_start/img/question1.png | Bin 12295 -> 0 bytes docs/source/quick_start/img/question2.png | Bin 40757 -> 0 bytes docs/source/quick_start/img/stm32_1.png | Bin 28974 -> 0 bytes docs/source/quick_start/img/stm32_10.png | Bin 8929 -> 0 bytes docs/source/quick_start/img/stm32_11.png | Bin 19428 -> 0 bytes docs/source/quick_start/img/stm32_12.png | Bin 80088 -> 0 bytes docs/source/quick_start/img/stm32_13.png | Bin 42394 -> 0 bytes docs/source/quick_start/img/stm32_14.png | Bin 32694 -> 0 bytes docs/source/quick_start/img/stm32_15.png | Bin 63453 -> 0 bytes docs/source/quick_start/img/stm32_16.png | Bin 19056 -> 0 bytes docs/source/quick_start/img/stm32_18.png | Bin 36595 -> 0 bytes docs/source/quick_start/img/stm32_19.png | Bin 44186 -> 0 bytes docs/source/quick_start/img/stm32_2.png | Bin 46511 -> 0 bytes docs/source/quick_start/img/stm32_3_1.png | Bin 36249 -> 0 bytes docs/source/quick_start/img/stm32_3_2.png | Bin 49701 -> 0 bytes docs/source/quick_start/img/stm32_4_1.png | Bin 27734 -> 0 bytes docs/source/quick_start/img/stm32_4_2.png | Bin 74975 -> 0 bytes docs/source/quick_start/img/stm32_5.png | Bin 23833 -> 0 bytes docs/source/quick_start/img/stm32_6.png | Bin 21999 -> 0 bytes docs/source/quick_start/img/stm32_7.png | Bin 8848 -> 0 bytes docs/source/quick_start/img/stm32_8.png | Bin 17224 -> 0 bytes docs/source/quick_start/migration.rst | 63 ---- docs/source/quick_start/opensource.rst | 62 ---- docs/source/quick_start/q&a.rst | 137 -------- docs/source/quick_start/rtthread.rst | 62 ---- docs/source/quick_start/share.rst | 27 -- docs/source/quick_start/start.rst | 53 --- docs/source/quick_start/transplant.rst | 137 -------- docs/source/show/img/usbdev_msc.png | Bin 41061 -> 0 bytes docs/source/show/img/usbdev_rndis_linux.png | Bin 186610 -> 0 bytes docs/source/show/img/usbdev_rndis_lwip.png | Bin 61847 -> 0 bytes docs/source/show/img/usbdev_rndis_lwip2.png | Bin 418408 -> 0 bytes docs/source/show/img/usbdev_rndis_wifi.png | Bin 1000959 -> 0 bytes docs/source/show/img/usbdev_rndis_wifi2.png | Bin 295386 -> 0 bytes docs/source/show/img/usbdev_rndis_win.png | Bin 862579 -> 0 bytes docs/source/show/img/usbdev_uvc_mjpeg.png | Bin 4399953 -> 0 bytes docs/source/show/img/usbdev_uvc_yuv.png | Bin 4219553 -> 0 bytes docs/source/show/img/usbhost_ax88772_1.png | Bin 65228 -> 0 bytes docs/source/show/img/usbhost_ax88772_2.png | Bin 53080 -> 0 bytes docs/source/show/img/usbhost_hub.png | Bin 103531 -> 0 bytes docs/source/show/img/usbhost_hub2.png | Bin 11107 -> 0 bytes docs/source/show/img/usbhost_msc.png | Bin 13051 -> 0 bytes docs/source/show/img/usbhost_msc_xhci.png | Bin 40182 -> 0 bytes docs/source/show/img/usbhost_rndis.png | Bin 552961 -> 0 bytes docs/source/show/img/usbhost_uvc.gif | Bin 8564084 -> 0 bytes docs/source/show/img/usbhost_wifi.png | Bin 101688 -> 0 bytes docs/source/show/index.rst | 103 ------ docs/source/support/img/dwc2_hostuac.png | Bin 168135 -> 0 bytes docs/source/support/img/dwc2_hostuvc1.png | Bin 322035 -> 0 bytes docs/source/support/img/dwc2_hostuvc2.png | Bin 334772 -> 0 bytes docs/source/support/img/dwc2_hostuvc3.png | Bin 326837 -> 0 bytes docs/source/support/img/ehci_hostuvc1.png | Bin 232158 -> 0 bytes docs/source/support/img/ehci_hostuvc2.png | Bin 223817 -> 0 bytes docs/source/support/img/mtpdev.png | Bin 361577 -> 0 bytes docs/source/support/img/ohci.png | Bin 37670 -> 0 bytes docs/source/support/img/rndisrx.png | Bin 131796 -> 0 bytes docs/source/support/img/rndistx.png | Bin 147014 -> 0 bytes docs/source/support/img/tmcdev1.png | Bin 578670 -> 0 bytes docs/source/support/img/tmcdev2.png | Bin 218648 -> 0 bytes docs/source/support/img/usbhost_uvc.gif | Bin 8564084 -> 0 bytes docs/source/support/index.rst | 43 --- docs/source/tools/img/chrytool1.png | Bin 22400 -> 0 bytes docs/source/tools/img/chrytool2.png | Bin 42418 -> 0 bytes docs/source/tools/img/chrytool3.png | Bin 21838 -> 0 bytes docs/source/tools/img/chrytool4.png | Bin 28145 -> 0 bytes docs/source/tools/img/chrytool5.png | Bin 75465 -> 0 bytes docs/source/tools/img/chrytool6.png | Bin 31559 -> 0 bytes docs/source/tools/img/chrytool7.png | Bin 35601 -> 0 bytes docs/source/tools/index.rst | 50 --- docs/source/usb/img/1.png | Bin 107074 -> 0 bytes docs/source/usb/img/10.png | Bin 72135 -> 0 bytes docs/source/usb/img/11.png | Bin 10007 -> 0 bytes docs/source/usb/img/12.png | Bin 2125 -> 0 bytes docs/source/usb/img/13.png | Bin 2235 -> 0 bytes docs/source/usb/img/14.png | Bin 13349 -> 0 bytes docs/source/usb/img/15.png | Bin 36258 -> 0 bytes docs/source/usb/img/16.png | Bin 37965 -> 0 bytes docs/source/usb/img/17.png | Bin 47541 -> 0 bytes docs/source/usb/img/18.png | Bin 4845 -> 0 bytes docs/source/usb/img/19.png | Bin 7013 -> 0 bytes docs/source/usb/img/2.png | Bin 79045 -> 0 bytes docs/source/usb/img/20.png | Bin 74655 -> 0 bytes docs/source/usb/img/21.png | Bin 7284 -> 0 bytes docs/source/usb/img/22.png | Bin 6361 -> 0 bytes docs/source/usb/img/23.png | Bin 66450 -> 0 bytes docs/source/usb/img/24.png | Bin 19100 -> 0 bytes docs/source/usb/img/25.png | Bin 9216 -> 0 bytes docs/source/usb/img/26.png | Bin 15984 -> 0 bytes docs/source/usb/img/27.png | Bin 7785 -> 0 bytes docs/source/usb/img/28.png | Bin 6461 -> 0 bytes docs/source/usb/img/29.png | Bin 8557 -> 0 bytes docs/source/usb/img/3.png | Bin 124692 -> 0 bytes docs/source/usb/img/30.png | Bin 3724 -> 0 bytes docs/source/usb/img/4.png | Bin 168663 -> 0 bytes docs/source/usb/img/5.png | Bin 55539 -> 0 bytes docs/source/usb/img/6.png | Bin 36583 -> 0 bytes docs/source/usb/img/7.png | Bin 17216 -> 0 bytes docs/source/usb/img/8.png | Bin 72615 -> 0 bytes docs/source/usb/img/9.png | Bin 114230 -> 0 bytes docs/source/usb/img/overview1.png | Bin 92546 -> 0 bytes docs/source/usb/img/overview2.png | Bin 27578 -> 0 bytes docs/source/usb/img/usb_enum.png | Bin 175530 -> 0 bytes docs/source/usb/img/usb_request.png | Bin 81361 -> 0 bytes docs/source/usb/img/usbstruct.png | Bin 44620 -> 0 bytes docs/source/usb/usb2.0_basic.rst | 296 ---------------- docs/source/usb/usb3.0_basic.rst | 33 -- docs/source/usb/usb_desc.rst | 37 -- docs/source/usb/usb_enum.rst | 22 -- docs/source/usb/usb_ext.rst | 39 --- docs/source/usb/usb_request.rst | 6 - docs/source/usbdev.svg | 4 - docs/source/usbhost.svg | 9 - docs/source/usbip/cdns2.rst | 2 - docs/source/usbip/cdns3.rst | 2 - docs/source/usbip/chipidea.rst | 2 - docs/source/usbip/dwc2.rst | 2 - docs/source/usbip/dwc3.rst | 2 - docs/source/usbip/ehci.rst | 2 - docs/source/usbip/fotg210.rst | 2 - docs/source/usbip/musb.rst | 2 - docs/source/usbip/ohci.rst | 2 - docs/source/usbip/xhci.rst | 2 - docs/source/version.rst | 182 ---------- 171 files changed, 4080 deletions(-) delete mode 100644 docs/source/api/api_config.rst delete mode 100644 docs/source/api/api_device.rst delete mode 100644 docs/source/api/api_host.rst delete mode 100644 docs/source/api/api_port.rst delete mode 100644 docs/source/api/img/api_device1.png delete mode 100644 docs/source/api/img/api_host1.png delete mode 100644 docs/source/api/img/api_host2.png delete mode 100644 docs/source/class/class_audio.rst delete mode 100644 docs/source/class/class_cdc.rst delete mode 100644 docs/source/class/class_hid.rst delete mode 100644 docs/source/class/class_msc.rst delete mode 100644 docs/source/class/class_video.rst delete mode 100644 docs/source/class/winusb.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/demo/img/cherryadb.png delete mode 100644 docs/source/demo/img/otg.png delete mode 100644 docs/source/demo/img/rtt_adb_shell1.png delete mode 100644 docs/source/demo/img/rtt_adb_shell2.png delete mode 100644 docs/source/demo/img/usbh_serial.png delete mode 100644 docs/source/demo/usb_otg.rst delete mode 100644 docs/source/demo/usbd_adb.rst delete mode 100644 docs/source/demo/usbd_audiov1.rst delete mode 100644 docs/source/demo/usbd_audiov2.rst delete mode 100644 docs/source/demo/usbd_cdc_acm.rst delete mode 100644 docs/source/demo/usbd_ecm.rst delete mode 100644 docs/source/demo/usbd_hid.rst delete mode 100644 docs/source/demo/usbd_msc.rst delete mode 100644 docs/source/demo/usbd_rndis.rst delete mode 100644 docs/source/demo/usbd_vendor.rst delete mode 100644 docs/source/demo/usbd_video.rst delete mode 100644 docs/source/demo/usbd_webusb.rst delete mode 100644 docs/source/demo/usbd_winusb.rst delete mode 100644 docs/source/demo/usbh_bluetooth.rst delete mode 100644 docs/source/demo/usbh_hid.rst delete mode 100644 docs/source/demo/usbh_msc.rst delete mode 100644 docs/source/demo/usbh_net.rst delete mode 100644 docs/source/demo/usbh_serial.rst delete mode 100644 docs/source/demo/usbh_vendor.rst delete mode 100644 docs/source/demo/usbh_wifi.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/quick_start/demo.rst delete mode 100644 docs/source/quick_start/img/env0.png delete mode 100644 docs/source/quick_start/img/env1.png delete mode 100644 docs/source/quick_start/img/env2.png delete mode 100644 docs/source/quick_start/img/esp1.png delete mode 100644 docs/source/quick_start/img/esp2.png delete mode 100644 docs/source/quick_start/img/esp3.png delete mode 100644 docs/source/quick_start/img/esp4.png delete mode 100644 docs/source/quick_start/img/question1.png delete mode 100644 docs/source/quick_start/img/question2.png delete mode 100644 docs/source/quick_start/img/stm32_1.png delete mode 100644 docs/source/quick_start/img/stm32_10.png delete mode 100644 docs/source/quick_start/img/stm32_11.png delete mode 100644 docs/source/quick_start/img/stm32_12.png delete mode 100644 docs/source/quick_start/img/stm32_13.png delete mode 100644 docs/source/quick_start/img/stm32_14.png delete mode 100644 docs/source/quick_start/img/stm32_15.png delete mode 100644 docs/source/quick_start/img/stm32_16.png delete mode 100644 docs/source/quick_start/img/stm32_18.png delete mode 100644 docs/source/quick_start/img/stm32_19.png delete mode 100644 docs/source/quick_start/img/stm32_2.png delete mode 100644 docs/source/quick_start/img/stm32_3_1.png delete mode 100644 docs/source/quick_start/img/stm32_3_2.png delete mode 100644 docs/source/quick_start/img/stm32_4_1.png delete mode 100644 docs/source/quick_start/img/stm32_4_2.png delete mode 100644 docs/source/quick_start/img/stm32_5.png delete mode 100644 docs/source/quick_start/img/stm32_6.png delete mode 100644 docs/source/quick_start/img/stm32_7.png delete mode 100644 docs/source/quick_start/img/stm32_8.png delete mode 100644 docs/source/quick_start/migration.rst delete mode 100644 docs/source/quick_start/opensource.rst delete mode 100644 docs/source/quick_start/q&a.rst delete mode 100644 docs/source/quick_start/rtthread.rst delete mode 100644 docs/source/quick_start/share.rst delete mode 100644 docs/source/quick_start/start.rst delete mode 100644 docs/source/quick_start/transplant.rst delete mode 100644 docs/source/show/img/usbdev_msc.png delete mode 100644 docs/source/show/img/usbdev_rndis_linux.png delete mode 100644 docs/source/show/img/usbdev_rndis_lwip.png delete mode 100644 docs/source/show/img/usbdev_rndis_lwip2.png delete mode 100644 docs/source/show/img/usbdev_rndis_wifi.png delete mode 100644 docs/source/show/img/usbdev_rndis_wifi2.png delete mode 100644 docs/source/show/img/usbdev_rndis_win.png delete mode 100644 docs/source/show/img/usbdev_uvc_mjpeg.png delete mode 100644 docs/source/show/img/usbdev_uvc_yuv.png delete mode 100644 docs/source/show/img/usbhost_ax88772_1.png delete mode 100644 docs/source/show/img/usbhost_ax88772_2.png delete mode 100644 docs/source/show/img/usbhost_hub.png delete mode 100644 docs/source/show/img/usbhost_hub2.png delete mode 100644 docs/source/show/img/usbhost_msc.png delete mode 100644 docs/source/show/img/usbhost_msc_xhci.png delete mode 100644 docs/source/show/img/usbhost_rndis.png delete mode 100644 docs/source/show/img/usbhost_uvc.gif delete mode 100644 docs/source/show/img/usbhost_wifi.png delete mode 100644 docs/source/show/index.rst delete mode 100644 docs/source/support/img/dwc2_hostuac.png delete mode 100644 docs/source/support/img/dwc2_hostuvc1.png delete mode 100644 docs/source/support/img/dwc2_hostuvc2.png delete mode 100644 docs/source/support/img/dwc2_hostuvc3.png delete mode 100644 docs/source/support/img/ehci_hostuvc1.png delete mode 100644 docs/source/support/img/ehci_hostuvc2.png delete mode 100644 docs/source/support/img/mtpdev.png delete mode 100644 docs/source/support/img/ohci.png delete mode 100644 docs/source/support/img/rndisrx.png delete mode 100644 docs/source/support/img/rndistx.png delete mode 100644 docs/source/support/img/tmcdev1.png delete mode 100644 docs/source/support/img/tmcdev2.png delete mode 100644 docs/source/support/img/usbhost_uvc.gif delete mode 100644 docs/source/support/index.rst delete mode 100644 docs/source/tools/img/chrytool1.png delete mode 100644 docs/source/tools/img/chrytool2.png delete mode 100644 docs/source/tools/img/chrytool3.png delete mode 100644 docs/source/tools/img/chrytool4.png delete mode 100644 docs/source/tools/img/chrytool5.png delete mode 100644 docs/source/tools/img/chrytool6.png delete mode 100644 docs/source/tools/img/chrytool7.png delete mode 100644 docs/source/tools/index.rst delete mode 100644 docs/source/usb/img/1.png delete mode 100644 docs/source/usb/img/10.png delete mode 100644 docs/source/usb/img/11.png delete mode 100644 docs/source/usb/img/12.png delete mode 100644 docs/source/usb/img/13.png delete mode 100644 docs/source/usb/img/14.png delete mode 100644 docs/source/usb/img/15.png delete mode 100644 docs/source/usb/img/16.png delete mode 100644 docs/source/usb/img/17.png delete mode 100644 docs/source/usb/img/18.png delete mode 100644 docs/source/usb/img/19.png delete mode 100644 docs/source/usb/img/2.png delete mode 100644 docs/source/usb/img/20.png delete mode 100644 docs/source/usb/img/21.png delete mode 100644 docs/source/usb/img/22.png delete mode 100644 docs/source/usb/img/23.png delete mode 100644 docs/source/usb/img/24.png delete mode 100644 docs/source/usb/img/25.png delete mode 100644 docs/source/usb/img/26.png delete mode 100644 docs/source/usb/img/27.png delete mode 100644 docs/source/usb/img/28.png delete mode 100644 docs/source/usb/img/29.png delete mode 100644 docs/source/usb/img/3.png delete mode 100644 docs/source/usb/img/30.png delete mode 100644 docs/source/usb/img/4.png delete mode 100644 docs/source/usb/img/5.png delete mode 100644 docs/source/usb/img/6.png delete mode 100644 docs/source/usb/img/7.png delete mode 100644 docs/source/usb/img/8.png delete mode 100644 docs/source/usb/img/9.png delete mode 100644 docs/source/usb/img/overview1.png delete mode 100644 docs/source/usb/img/overview2.png delete mode 100644 docs/source/usb/img/usb_enum.png delete mode 100644 docs/source/usb/img/usb_request.png delete mode 100644 docs/source/usb/img/usbstruct.png delete mode 100644 docs/source/usb/usb2.0_basic.rst delete mode 100644 docs/source/usb/usb3.0_basic.rst delete mode 100644 docs/source/usb/usb_desc.rst delete mode 100644 docs/source/usb/usb_enum.rst delete mode 100644 docs/source/usb/usb_ext.rst delete mode 100644 docs/source/usb/usb_request.rst delete mode 100644 docs/source/usbdev.svg delete mode 100644 docs/source/usbhost.svg delete mode 100644 docs/source/usbip/cdns2.rst delete mode 100644 docs/source/usbip/cdns3.rst delete mode 100644 docs/source/usbip/chipidea.rst delete mode 100644 docs/source/usbip/dwc2.rst delete mode 100644 docs/source/usbip/dwc3.rst delete mode 100644 docs/source/usbip/ehci.rst delete mode 100644 docs/source/usbip/fotg210.rst delete mode 100644 docs/source/usbip/musb.rst delete mode 100644 docs/source/usbip/ohci.rst delete mode 100644 docs/source/usbip/xhci.rst delete mode 100644 docs/source/version.rst (limited to 'docs/source') diff --git a/docs/source/api/api_config.rst b/docs/source/api/api_config.rst deleted file mode 100644 index c1fe8603..00000000 --- a/docs/source/api/api_config.rst +++ /dev/null @@ -1,163 +0,0 @@ -USB CONFIG 说明 -========================= - -通用 CONFIG ---------------------- - -CONFIG_USB_PRINTF -^^^^^^^^^^^^^^^^^^^^ - -USB log 功能，默认重定向到 printf，需要注意，USB log 会在中断中使用，因此重定向的 api 不允许阻塞。举例，如果使用的是 rt-thread，请更换成 rt-kprintf - -CONFIG_USB_DBG_LEVEL -^^^^^^^^^^^^^^^^^^^^^^ - -控制 log 的打印级别 - -CONFIG_USB_PRINTF_COLOR_ENABLE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -控制 log 颜色打印，默认开启 - -CONFIG_USB_DCACHE_ENABLE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -不使用 nocache ram 时，开启此宏以保证数据一致性。 **使用 EHCI 时，内部依旧需要使用 nocache ram**。 - -CONFIG_USB_ALIGN_SIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -USB buffer 的对齐大小，默认是 4。IP 在 dma 模式下可能对输入的 buffer有对齐要求，一般是4，如果是其他对齐方式，请修改此值。 - -USB_NOCACHE_RAM_SECTION -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -如果芯片没有 cache 功能，此宏无效。如果有，则 USB 的输入输出 buffer 必须放在 nocache ram 中，保证数据一致性。 - -设备协议栈 CONFIG ---------------------- - -CONFIG_USBDEV_REQUEST_BUFFER_LEN -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -控制传输接收和发送的 buffer 最大长度，默认是 512。 - -CONFIG_USBDEV_SETUP_LOG_PRINT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -使能或者关闭 setup 包的 dump 信息，默认关闭。 - -CONFIG_USBDEV_DESC_CHECK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -暂时没有实现 - -CONFIG_USBDEV_TEST_MODE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -使能或者关闭 usb test mode - -CONFIG_USBDEV_MSC_MAX_BUFSIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -msc 缓存的最大长度，缓存越大，USB 的速度越高，因为介质一般多个 block 读写速度比单个 block 高很多，比如 sd 卡。 -默认 512 ，如果是 flash 需要改成 4K, 缓存的大小需要是介质的一个 block size 的整数倍。 - -CONFIG_USBDEV_MSC_MANUFACTURER_STRING -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CONFIG_USBDEV_MSC_PRODUCT_STRING -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CONFIG_USBDEV_MSC_VERSION_STRING -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CONFIG_USBDEV_MSC_POLLING -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -将 usbd_msc_sector_read 和 usbd_msc_sector_write 操作放在 while1 中运行，裸机下使用。 - -CONFIG_USBDEV_MSC_THREAD -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -使能或者关闭 msc 线程，默认关闭。usbd_msc_sector_read 和 usbd_msc_sector_write 默认是在中断中执行，所以如果开启了 os 建议开启此宏，那么， -usbd_msc_sector_read 和 usbd_msc_sector_write 就会在线程中执行。 - -CONFIG_USBDEV_MSC_PRIO -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -MSC 读写线程的优先级，默认是 4，数值越小，优先级越高 - -CONFIG_USBDEV_MSC_STACKSIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -MSC 读写线程的堆栈大小，默认 2K 字节 - -CONFIG_USBDEV_RNDIS_RESP_BUFFER_SIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -rndis 控制传输最大接收和发送的长度，根据 RNDIS options list 决定最小长度，默认要大于等于 156 - -CONFIG_USBDEV_RNDIS_ETH_MAX_FRAME_SIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -rndis 以太网帧的最大长度，默认 1580 - -CONFIG_USBDEV_RNDIS_VENDOR_ID -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CONFIG_USBDEV_RNDIS_VENDOR_DESC -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CONFIG_USBDEV_RNDIS_USING_LWIP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -rndis 与 lwip 接口的对接 - -主机协议栈 CONFIG ---------------------- - -以下参数决定了支持的最大外部hub数量，接口数，每个接口的端点数和 altsetting 数量，更改此值会影响 ram 的大小，建议根据实际情况更改。 - -.. code-block:: C - - #define CONFIG_USBHOST_MAX_RHPORTS 1 - #define CONFIG_USBHOST_MAX_EXTHUBS 1 - #define CONFIG_USBHOST_MAX_EHPORTS 4 - #define CONFIG_USBHOST_MAX_INTERFACES 6 - #define CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 1 - #define CONFIG_USBHOST_MAX_ENDPOINTS 4 - -以下参数决定了支持的 class 数目，更改此值会影响 ram 的大小，建议根据实际情况更改。 - -.. code-block:: C - - #define CONFIG_USBHOST_MAX_SERIAL_CLASS 4 - #define CONFIG_USBHOST_MAX_HID_CLASS 4 - #define CONFIG_USBHOST_MAX_MSC_CLASS 2 - #define CONFIG_USBHOST_MAX_AUDIO_CLASS 1 - #define CONFIG_USBHOST_MAX_VIDEO_CLASS 1 - -CONFIG_USBHOST_PSC_PRIO -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -主机插拔线程的优先级，默认是 0，数值越小，优先级越高 - -CONFIG_USBHOST_PSC_STACKSIZE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -主机插拔线程的堆栈大小，默认 2K 字节 - -CONFIG_USBHOST_REQUEST_BUFFER_LEN -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -控制传输能够接收或者发送的最大长度 - -CONFIG_USBHOST_CONTROL_TRANSFER_TIMEOUT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -控制传输发送或者接收的超时时间，默认 500 ms - -CONFIG_USBHOST_MSC_TIMEOUT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -MSC 读写传输的超时时间，默认 5s \ No newline at end of file diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst deleted file mode 100644 index bc8cb100..00000000 --- a/docs/source/api/api_device.rst +++ /dev/null @@ -1,502 +0,0 @@ -设备协议栈 -========================= - -设备协议栈主要负责枚举和驱动加载，枚举这边就不说了，驱动加载，也就是接口驱动加载，主要是依靠 `usbd_add_interface` 函数，用于记录传入的接口驱动并保存到接口数组表，当主机进行类请求时就可以查找接口表进行访问了。 -在调用 `usbd_desc_register` 以后需要进行接口注册和端点注册，口诀如下： - -- 有多少个接口就调用多少次 `usbd_add_interface`，参数填相关 `xxx_init_intf`, 如果没有支持的，手动创建一个 intf 填入 -- 有多少个端点就调用多少次 `usbd_add_endpoint`，当中断完成时，会调用到注册的端点回调中。 - -参考下面这张图： - -.. figure:: img/api_device1.png - -CORE ------------------ - -端点结构体 -"""""""""""""""""""""""""""""""""""" - -端点结构体主要用于注册不同端点地址的中断完成回调函数。 - -.. code-block:: C - - struct usbd_endpoint { - uint8_t ep_addr; - usbd_endpoint_callback ep_cb; - }; - -- **ep_addr** 端点地址（带方向） -- **ep_cb** 端点完成中断回调函数。 - -.. note:: 总结一句话：in 回调函数等价于 dma 发送完成中断回调函数；out 回调函数等价于 dma 接收完成中断回调函数 - -接口结构体 -"""""""""""""""""""""""""""""""""""" - -接口结构体主要用于注册不同类设备除了标准设备请求外的其他请求，包括类设备请求、厂商设备请求和自定义设备请求。以及协议栈中的相关通知回调函数。 - -.. code-block:: C - - struct usbd_interface { - usbd_request_handler class_interface_handler; - usbd_request_handler class_endpoint_handler; - usbd_request_handler vendor_handler; - usbd_notify_handler notify_handler; - const uint8_t *hid_report_descriptor; - uint32_t hid_report_descriptor_len; - uint8_t intf_num; - }; - -- **class_interface_handler** class setup 请求回调函数,接收者为接口 -- **class_endpoint_handler** class setup 请求回调函数,接收者为端点 -- **vendor_handler** vendor setup 请求回调函数 -- **notify_handler** 中断标志、协议栈相关状态回调函数 -- **hid_report_descriptor** hid 报告描述符 -- **hid_report_descriptor_len** hid 报告描述符长度 -- **intf_num** 当前接口偏移 - -usbd_desc_register -"""""""""""""""""""""""""""""""""""" - -``usbd_desc_register`` 用来注册 USB 描述符，描述符种类包括：设备描述符、配置描述符（包含配置描述符、接口描述符、class 类描述符、端点描述符）、字符串描述符、设备限定描述符，其他速度描述符， -bos描述符，winusb 描述符。 - -.. code-block:: C - - // 开启 CONFIG_USBDEV_ADVANCE_DESC - void usbd_desc_register(uint8_t busid, const struct usb_descriptor *desc); - - // 关闭 CONFIG_USBDEV_ADVANCE_DESC - void usbd_desc_register(uint8_t busid, const uint8_t *desc); - void usbd_msosv1_desc_register(uint8_t busid, struct usb_msosv1_descriptor *desc); - void usbd_msosv2_desc_register(uint8_t busid, struct usb_msosv2_descriptor *desc); - void usbd_bos_desc_register(uint8_t busid, struct usb_bos_descriptor *desc); - void usbd_webusb_desc_register(uint8_t busid, struct usb_webusb_descriptor *desc); - -- **desc** 描述符的句柄 - -.. note:: 当前默认开启 CONFIG_USBDEV_ADVANCE_DESC，如果需要使用旧版本 API 请关闭该宏，从 v1.6.0 开始只有开启了 CONFIG_USBDEV_ADVANCE_DESC 的 API - -usbd_add_interface -"""""""""""""""""""""""""""""""""""" - -``usbd_add_interface`` 添加一个接口驱动。 **添加顺序必须按照描述符中接口顺序**。 - -.. code-block:: C - - void usbd_add_interface(uint8_t busid, struct usbd_interface *intf); - -- **busid** USB 总线 id -- **intf** 接口驱动句柄，通常从不同 class 的 `xxx_init_intf` 函数获取 - -usbd_add_endpoint -"""""""""""""""""""""""""""""""""""" - -``usbd_add_endpoint`` 添加一个端点中断完成回调函数。 - -.. code-block:: C - - void usbd_add_endpoint(uint8_t busid, struct usbd_endpoint *ep); - -- **busid** USB 总线 id -- **ep** 端点句柄 - -usbd_initialize -"""""""""""""""""""""""""""""""""""" - -``usbd_initialize`` 用来初始化 usb device 寄存器配置、usb 时钟、中断等，需要注意，此函数必须在注册描述符 API 最后。 **如果使用 os，必须放在线程中执行**。 - -.. code-block:: C - - int usbd_initialize(uint8_t busid, uintptr_t reg_base, usbd_event_handler_t event_handler); - -- **busid** USB 总线 id -- **reg_base** USB 设备寄存器基地址 -- **event_handler** 协议栈中断或者状态回调函数，event 事件 -- **return** 返回 0 表示成功，其他值表示失败 - -event 事件包括： - -.. code-block:: C - - USBD_EVENT_ERROR, /** USB error reported by the controller */ - USBD_EVENT_RESET, /** USB reset */ - USBD_EVENT_SOF, /** Start of Frame received */ - USBD_EVENT_CONNECTED, /** USB connected*/ - USBD_EVENT_DISCONNECTED, /** USB disconnected */ - USBD_EVENT_SUSPEND, /** USB connection suspended by the HOST */ - USBD_EVENT_RESUME, /** USB connection resumed by the HOST */ - - /* USB DEVICE STATUS */ - USBD_EVENT_CONFIGURED, /** USB configuration done */ - USBD_EVENT_SET_INTERFACE, /** USB interface selected */ - USBD_EVENT_SET_REMOTE_WAKEUP, /** USB set remote wakeup */ - USBD_EVENT_CLR_REMOTE_WAKEUP, /** USB clear remote wakeup */ - USBD_EVENT_INIT, /** USB init done when call usbd_initialize */ - USBD_EVENT_DEINIT, /** USB deinit done when call usbd_deinitialize */ - USBD_EVENT_UNKNOWN - -.. note:: 大部分 IP USBD_EVENT_CONNECTED 和 USBD_EVENT_DISCONNECTED 事件都不支持，当前仅 HPM 芯片支持，其余芯片自行设计vbus检测电路替代 - -usbd_deinitialize -"""""""""""""""""""""""""""""""""""" - -``usbd_deinitialize`` 用来反初始化 usb device，关闭 usb 设备时钟、中断等。 - -.. code-block:: C - - int usbd_deinitialize(uint8_t busid); - -- **busid** USB 总线 id -- **return** 返回 0 表示成功，其他值表示失败 - -CDC ACM ------------------ - -usbd_cdc_acm_init_intf -"""""""""""""""""""""""""""""""""""" - -``usbd_cdc_acm_init_intf`` 用来初始化 USB CDC ACM 类接口，并实现该接口相关的函数。 - -- ``cdc_acm_class_interface_request_handler`` 用来处理 USB CDC ACM 类 Setup 请求。 -- ``cdc_notify_handler`` 用来处理 USB CDC 其他中断回调函数。 - -.. code-block:: C - - struct usbd_interface *usbd_cdc_acm_init_intf(uint8_t busid, struct usbd_interface *intf); - -- **busid** USB 总线 id -- **return** 接口句柄 - -usbd_cdc_acm_set_line_coding -"""""""""""""""""""""""""""""""""""" - -``usbd_cdc_acm_set_line_coding`` 用来对串口进行配置，如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。 - -.. code-block:: C - - void usbd_cdc_acm_set_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding); - -- **busid** USB 总线 id -- **intf** 控制接口号 -- **line_coding** 串口配置 - -usbd_cdc_acm_get_line_coding -"""""""""""""""""""""""""""""""""""" - -``usbd_cdc_acm_get_line_coding`` 用来获取串口进行配置，如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。 - -.. code-block:: C - - void usbd_cdc_acm_get_line_coding(uint8_t busid, uint8_t intf, struct cdc_line_coding *line_coding); - -- **busid** USB 总线 id -- **intf** 控制接口号 -- **line_coding** 串口配置 - -usbd_cdc_acm_set_dtr -"""""""""""""""""""""""""""""""""""" - -``usbd_cdc_acm_set_dtr`` 用来控制串口 DTR 。如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。 - -.. code-block:: C - - void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr); - -- **busid** USB 总线 id -- **intf** 控制接口号 -- **dtr** dtr 为1表示拉低电平，为0表示拉高电平 - -usbd_cdc_acm_set_rts -"""""""""""""""""""""""""""""""""""" - -``usbd_cdc_acm_set_rts`` 用来控制串口 RTS 。如果仅使用 USB 而不用 串口，该接口不用用户实现，使用默认。 - -.. code-block:: C - - void usbd_cdc_acm_set_rts(uint8_t busid, uint8_t intf, bool rts); - -- **busid** USB 总线 id -- **intf** 控制接口号 -- **rts** rts 为1表示拉低电平，为0表示拉高电平 - -CDC_ACM_DESCRIPTOR_INIT -"""""""""""""""""""""""""""""""""""" - -``CDC_ACM_DESCRIPTOR_INIT`` 配置了默认的 cdc acm 需要的描述符以及参数，方便用户使用。总长度为 `CDC_ACM_DESCRIPTOR_LEN` 。 - -.. code-block:: C - - CDC_ACM_DESCRIPTOR_INIT(bFirstInterface, int_ep, out_ep, in_ep, str_idx); - -- **bFirstInterface** 表示该 cdc acm 第一个接口所在所有接口的偏移 -- **int_ep** 表示中断端点地址（带方向） -- **out_ep** 表示 bulk out 端点地址（带方向） -- **in_ep** 表示 bulk in 端点地址（带方向） -- **str_idx** 控制接口对应的字符串 id - -HID ------------------ - -usbd_hid_init_intf -"""""""""""""""""""""""""""""""""""" - -``usbd_hid_init_intf`` 用来初始化 USB HID 类接口，并实现该接口相关的函数： - -- ``hid_class_interface_request_handler`` 用来处理 USB HID 类的 Setup 请求。 -- ``hid_notify_handler`` 用来处理 USB HID 其他中断回调函数。 - -.. code-block:: C - - struct usbd_interface *usbd_hid_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t *desc, uint32_t desc_len); - -- **busid** USB 总线 id -- **desc** 报告描述符 -- **desc_len** 报告描述符长度 - -MSC ------------------ - -usbd_msc_init_intf -"""""""""""""""""""""""""""""""""""" -``usbd_msc_init_intf`` 用来初始化 MSC 类接口，并实现该接口相关函数，并且注册端点回调函数。（因为 msc bot 协议是固定的，所以不需要用于实现，因此端点回调函数自然不需要用户实现）。 - -- ``msc_storage_class_interface_request_handler`` 用于处理 USB MSC Setup 中断请求。 -- ``msc_storage_notify_handler`` 用于实现 USB MSC 其他中断回调函数。 - -- ``mass_storage_bulk_out`` 用于处理 USB MSC 端点 out 中断。 -- ``mass_storage_bulk_in`` 用于处理 USB MSC 端点 in 中断。 - -.. code-block:: C - - struct usbd_interface *usbd_msc_init_intf(uint8_t busid, struct usbd_interface *intf, const uint8_t out_ep, const uint8_t in_ep); - -- **busid** USB 总线 id -- **out_ep** out 端点地址 -- **in_ep** in 端点地址 - -usbd_msc_get_cap -"""""""""""""""""""""""""""""""""""" - -``usbd_msc_get_cap`` 用来获取存储器的 lun、扇区个数和每个扇区大小。用户必须实现该函数。 - -.. code-block:: C - - void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint16_t *block_size); - -- **busid** USB 总线 id -- **lun** 存储逻辑单元，暂时无用，默认支持一个 -- **block_num** 存储扇区个数 -- **block_size** 存储扇区大小 - -usbd_msc_sector_read -"""""""""""""""""""""""""""""""""""" - -``usbd_msc_sector_read`` 用来对存储器某个扇区开始的地址进行数据读取。用户必须实现该函数。 - -.. code-block:: C - - int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length); - -- **busid** USB 总线 id -- **lun** 存储逻辑单元，暂时无用，默认支持一个 -- **sector** 扇区偏移 -- **buffer** 存储读取的数据的指针 -- **length** 读取长度 - - -usbd_msc_sector_write -"""""""""""""""""""""""""""""""""""" - -``usbd_msc_sector_write`` 用来对存储器某个扇区开始写入数据。用户必须实现该函数。 - -.. code-block:: C - - int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length); - -- **busid** USB 总线 id -- **lun** 存储逻辑单元，暂时无用，默认支持一个 -- **sector** 扇区偏移 -- **buffer** 写入数据指针 -- **length** 写入长度 - -UAC ------------------ - -usbd_audio_init_intf -"""""""""""""""""""""""""""""""""""" -``usbd_audio_init_intf`` 用来初始化 USB Audio 类接口，并实现该接口相关的函数： - -- ``audio_class_interface_request_handler`` 用于处理 USB Audio Setup 接口接收者中断请求。 -- ``audio_class_endpoint_request_handler`` 用于处理 USB Audio Setup 端点接收者中断请求。 -- ``audio_notify_handler`` 用于实现 USB Audio 其他中断回调函数。 - -.. code-block:: C - - struct usbd_interface *usbd_audio_init_intf(uint8_t busid, struct usbd_interface *intf, - uint16_t uac_version, - struct audio_entity_info *table, - uint8_t num); - -- **busid** USB 总线 id -- **intf** 接口句柄 -- **uac_version** 音频类版本，UAC1.0 或 UAC2.0 -- **table** 音频实体信息表 -- **num** 音频实体信息表长度 - -usbd_audio_open -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_open`` 用来开启音频数据传输。主机发送开启命令的回调函数。 - -.. code-block:: C - - void usbd_audio_open(uint8_t intf); - -- **intf** 开启的接口号 - -usbd_audio_close -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_close`` 用来关闭音频数据传输。主机发送关闭命令的回调函数。 - -.. code-block:: C - - void usbd_audio_close(uint8_t intf); - -- **intf** 关闭的接口号 - -usbd_audio_set_mute -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_set_mute`` 用来设置静音。 - -.. code-block:: C - - void usbd_audio_set_mute(uint8_t busid, uint8_t ep, uint8_t ch, bool mute); - -- **busid** USB 总线 id -- **ep** 要设置静音的端点 -- **ch** 要设置静音的通道 -- **mute** 为1 表示静音，0相反 - -usbd_audio_set_volume -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_set_volume`` 用来设置音量。 - -.. code-block:: C - - void usbd_audio_set_volume(uint8_t busid, uint8_t ep, uint8_t ch, int volume_db); - -- **busid** USB 总线 id -- **ep** 要设置音量的端点 -- **ch** 要设置音量的通道 -- **volume_db** 要设置音量的分贝，单位 -100dB ~ 0dB - -usbd_audio_set_sampling_freq -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_set_sampling_freq`` 用来设置设备上音频模块的采样率 - -.. code-block:: C - - void usbd_audio_set_sampling_freq(uint8_t busid, uint8_t ep, uint32_t sampling_freq); - -- **ep** 要设置采样率的端点 -- **sampling_freq** 要设置的采样率 - -usbd_audio_get_sampling_freq_table -"""""""""""""""""""""""""""""""""""" - -``usbd_audio_get_sampling_freq_table`` 用来获取支持的采样率列表，如果函数没有实现，则使用默认采样率列表。 UAC2 only。 - -.. code-block:: C - - void usbd_audio_get_sampling_freq_table(uint8_t busid, uint8_t ep, uint8_t **sampling_freq_table); - -- **ep** 要获取采样率的端点 -- **sampling_freq_table** 采样率列表地址，格式参考默认采样率列表 - -UVC ------------------ - -usbd_video_init_intf -"""""""""""""""""""""""""""""""""""" -``usbd_video_init_intf`` 用来初始化 USB Video 类接口，并实现该接口相关的函数： - -- ``video_class_interface_request_handler`` 用于处理 USB Video Setup 中断请求。 -- ``video_notify_handler`` 用于实现 USB Video 其他中断回调函数。 - -.. code-block:: C - - struct usbd_interface *usbd_video_init_intf(uint8_t busid, struct usbd_interface *intf, - uint32_t dwFrameInterval, - uint32_t dwMaxVideoFrameSize, - uint32_t dwMaxPayloadTransferSize); -- **busid** USB 总线 id -- **intf** 接口句柄 -- **dwFrameInterval** 视频帧间隔，单位 100ns -- **dwMaxVideoFrameSize** 最大视频帧大小 -- **dwMaxPayloadTransferSize** 最大负载传输大小 - -usbd_video_open -"""""""""""""""""""""""""""""""""""" - -``usbd_video_open`` 用来开启视频数据传输。 - -.. code-block:: C - - void usbd_video_open(uint8_t intf); - -- **intf** 开启的接口号 - -usbd_video_close -"""""""""""""""""""""""""""""""""""" - -``usbd_video_close`` 用来关闭视频数据传输。 - -.. code-block:: C - - void usbd_video_open(uint8_t intf); - -- **intf** 关闭的接口号 - -usbd_video_stream_start_write -"""""""""""""""""""""""""""""""""""" - -``usbd_video_stream_start_write`` 用来启动一帧视频数据流发送。需要搭配 `usbd_video_stream_split_transfer` 使用。 - -.. code-block:: C - - int usbd_video_stream_start_write(uint8_t busid, uint8_t ep, uint8_t *ep_buf, uint8_t *stream_buf, uint32_t stream_len, bool do_copy); - -- **busid** USB 总线 id -- **ep** 视频数据端点地址 -- **ep_buf** 视频数据端点传输缓冲区 -- **stream_buf** 一帧视频数据源缓冲区 -- **stream_len** 一帧视频数据源缓冲区大小 -- **do_copy** 是否需要将 stream_buf 数据复制到 ep_buf 中，当前仅当 stream_buf 在 nocache 区域并且未开启 DCACHE_ENABLE 时该参数才为 false - -usbd_video_stream_split_transfer -"""""""""""""""""""""""""""""""""""" - -``usbd_video_stream_split_transfer`` 用来分割视频数据流发送。需要搭配 `usbd_video_stream_start_write` 使用。 - -.. code-block:: C - - int usbd_video_stream_split_transfer(uint8_t busid, uint8_t ep); - -- **busid** USB 总线 id -- **ep** 视频数据端点地址 -- **return** 返回 true 表示一帧数据发送完成，false 表示数据未发送完成 - -RNDIS ------------------ - -CDC ECM ------------------ - -MTP ------------------ diff --git a/docs/source/api/api_host.rst b/docs/source/api/api_host.rst deleted file mode 100644 index 46d1e428..00000000 --- a/docs/source/api/api_host.rst +++ /dev/null @@ -1,317 +0,0 @@ -主机协议栈 -========================= - -关于主机协议栈中结构体的命名、分类、成员组成，参考下面这两张图： - -.. figure:: img/api_host1.png -.. figure:: img/api_host2.png - -CORE ------------------ - -CLASS 驱动信息结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_class_info { - uint8_t match_flags; /* Used for product specific matches; range is inclusive */ - uint8_t bInterfaceClass; /* Base device class code */ - uint8_t bInterfaceSubClass; /* Sub-class, depends on base class. Eg. */ - uint8_t bInterfaceProtocol; /* Protocol, depends on base class. Eg. */ - const uint16_t (*id_table)[2]; /* List of Vendor/Product ID pairs */ - const struct usbh_class_driver *class_driver; - }; - -端点结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_endpoint { - struct usb_endpoint_descriptor ep_desc; - }; - -接口备用结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_interface_altsetting { - struct usb_interface_descriptor intf_desc; - struct usbh_endpoint ep[CONFIG_USBHOST_MAX_ENDPOINTS]; - }; - -接口结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_interface { - char devname[CONFIG_USBHOST_DEV_NAMELEN]; - struct usbh_class_driver *class_driver; - void *priv; - struct usbh_interface_altsetting altsetting[CONFIG_USBHOST_MAX_INTF_ALTSETTINGS]; - uint8_t altsetting_num; - }; - -配置结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_configuration { - struct usb_configuration_descriptor config_desc; - struct usbh_interface intf[CONFIG_USBHOST_MAX_INTERFACES]; - }; - -hubport 结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_hubport { - bool connected; /* True: device connected; false: disconnected */ - uint8_t port; /* Hub port index */ - uint8_t dev_addr; /* device address */ - uint8_t speed; /* device speed */ - uint8_t depth; /* distance from root hub */ - uint8_t route; /* route string */ - uint8_t slot_id; /* slot id */ - struct usb_device_descriptor device_desc; - struct usbh_configuration config; - const char *iManufacturer; - const char *iProduct; - const char *iSerialNumber; - uint8_t *raw_config_desc; - struct usb_setup_packet *setup; - struct usbh_hub *parent; - struct usbh_hub *self; /* if this hubport is a hub */ - struct usbh_bus *bus; - struct usb_endpoint_descriptor ep0; - struct usbh_urb ep0_urb; - usb_osal_mutex_t mutex; - }; - -hub 结构体 -"""""""""""""""""""""""""""""""""""" - -.. code-block:: C - - struct usbh_hub { - bool connected; - bool is_roothub; - uint8_t index; - uint8_t hub_addr; - uint8_t speed; - uint8_t nports; - uint8_t powerdelay; - uint8_t tt_think; - bool ismtt; - struct usb_hub_descriptor hub_desc; /* USB 2.0 only */ - struct usb_hub_ss_descriptor hub_ss_desc; /* USB 3.0 only */ - struct usbh_hubport child[CONFIG_USBHOST_MAX_EHPORTS]; - struct usbh_hubport *parent; - struct usbh_bus *bus; - struct usb_endpoint_descriptor *intin; - struct usbh_urb intin_urb; - uint8_t *int_buffer; - struct usb_osal_timer *int_timer; - }; - -usbh_initialize -"""""""""""""""""""""""""""""""""""" - -``usbh_initialize`` 用来初始化 usb 主机协议栈，包括：初始化 usb 主机控制器，创建 roothub 设备，创建 hub 检测线程。 - -.. code-block:: C - - int usbh_initialize(uint8_t busid, uint32_t reg_base, usbh_event_handler_t event_handler); - -- **busid** bus id，从 0开始，不能超过 `CONFIG_USBHOST_MAX_BUS` -- **reg_base** hcd 寄存器基地址 -- **event_handler** host 事件回调函数，可以为NULL -- **return** 0 表示正常其他表示错误 - -usbh_find_class_instance -"""""""""""""""""""""""""""""""""""" - -``usbh_find_class_instance`` 根据注册的 class 名称查找对应的 class 结构体句柄。 - -.. code-block:: C - - void *usbh_find_class_instance(const char *devname); - -- **devname** class 名称 -- **return** class 结构体句柄 - -lsusb -"""""""""""""""""""""""""""""""""""" - -``lsusb`` 用来查看和操作 hub 上的设备信息。需要借助 shell 插件使用。 - -.. code-block:: C - - int lsusb(int argc, char **argv); - -SERIAL ------------------ - -usbh_serial_open -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_open`` 根据路径打开一个串口设备。 - -.. code-block:: C - - struct usbh_serial *usbh_serial_open(const char *devname, uint32_t open_flags); - -- **devname** 串口路径 -- **open_flags** 打开标志，参考 `USBH_SERIAL_OFLAG_*` 定义 -- **return** serial 结构体句柄 - -usbh_serial_close -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_close`` 关闭串口设备。 - -.. code-block:: C - - void usbh_serial_close(struct usbh_serial *serial); - -- **serial** serial 结构体句柄 - -usbh_serial_control -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_control`` 对串口进行配置。 - -.. code-block:: C - - int usbh_serial_control(struct usbh_serial *serial, int cmd, void *arg); - -- **serial** serial 结构体句柄 -- **cmd** 控制命令，参考 `USBH_SERIAL_CMD_*` 定义 -- **arg** 控制参数指针 -- **return** 0 表示正常其他表示错误 - -usbh_serial_write -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_write`` 向串口写数据。 - -.. code-block:: C - - int usbh_serial_write(struct usbh_serial *serial, const void *buffer, uint32_t buflen); - -- **serial** serial 结构体句柄 -- **buffer** 数据缓冲区指针 -- **buflen** 要写入的数据长度 -- **return** 实际写入的数据长度或者错误码 - -.. note:: 如果没有开启 CONFIG_USB_DCACHE_ENABLE，则 buffer 需要是 nocache区域，否则需要是对齐到 CONFIG_USB_ALIGN_SIZE 的区域。 - -usbh_serial_read -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_read`` 从串口读数据。 **如果没有设置波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf **。 - -.. code-block:: C - - int usbh_serial_read(struct usbh_serial *serial, void *buffer, uint32_t buflen); - -- **serial** serial 结构体句柄 -- **buffer** 数据缓冲区指针 -- **buflen** 要读取的最大数据长度 -- **return** 实际读取的数据长度或者错误码 - -.. note:: 由于内部使用了 ringbuffer，对于用户的 buffer 属性没有限制。 - -usbh_serial_cdc_write_async -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_cdc_write_async`` 异步从串口读数据。 **如果设置了波特率，不允许使用该 API**。 - -.. code-block:: C - - int usbh_serial_cdc_write_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg); - -- **serial** serial 结构体句柄 -- **buffer** 数据缓冲区指针 -- **buflen** 要发送的数据长度 -- **complete** 读数据完成回调函数 -- **arg** 回调函数参数 -- **return** 0 表示正常其他表示错误 - -.. note:: 如果没有开启 CONFIG_USB_DCACHE_ENABLE，则 buffer 需要是 nocache区域，否则需要是对齐到 CONFIG_USB_ALIGN_SIZE 的区域。 - -usbh_serial_cdc_read_async -"""""""""""""""""""""""""""""""""""" - -``usbh_serial_cdc_read_async`` 异步从串口读数据。 **如果设置了波特率，不允许使用该 API，设置波特率后，内部会开启 rx 接收并将数据写入 ringbuf **。 - -.. code-block:: C - - int usbh_serial_cdc_read_async(struct usbh_serial *serial, uint8_t *buffer, uint32_t buflen, usbh_complete_callback_t complete, void *arg); - -- **serial** serial 结构体句柄 -- **buffer** 数据缓冲区指针 -- **buflen** 要读取的最大数据长度，一次最高 16K。并且需要是 wMaxPacketSize 的整数倍 -- **complete** 读数据完成回调函数 -- **arg** 回调函数参数 -- **return** 0 表示正常其他表示错误 - -.. note:: 如果没有开启 CONFIG_USB_DCACHE_ENABLE，则 buffer 需要是 nocache区域，否则需要是对齐到 CONFIG_USB_ALIGN_SIZE 的区域。 - -HID ------------------ - -MSC ------------------ - -usbh_msc_scsi_init -"""""""""""""""""""""""""""""""""""" - -``usbh_msc_scsi_init`` 初始化 msc scsi 设备。获取 MSC 状态和容量信息。 - -.. code-block:: C - - int usbh_msc_scsi_init(struct usbh_msc *msc_class); - -- **msc_class** msc 结构体句柄 -- **return** 0 表示正常其他表示错误 - -usbh_msc_scsi_write10 -"""""""""""""""""""""""""""""""""""" - -``usbh_msc_scsi_write10`` 向 msc 设备写数据。 - -.. code-block:: C - - int usbh_msc_scsi_write10(struct usbh_msc *msc_class, uint32_t start_sector, const uint8_t *buffer, uint32_t nsectors); - -- **msc_class** msc 结构体句柄 -- **start_sector** 起始扇区 -- **buffer** 数据缓冲区指针 -- **nsectors** 要写入的扇区数 -- **return** 返回 0 表示正常其他表示错误 - -usbh_msc_scsi_read10 -"""""""""""""""""""""""""""""""""""" - -``usbh_msc_scsi_read10`` 从 msc 设备读数据。 - -.. code-block:: C - - int usbh_msc_scsi_read10(struct usbh_msc *msc_class, uint32_t start_sector, uint8_t *buffer, uint32_t nsectors); - -- **msc_class** msc 结构体句柄 -- **start_sector** 起始扇区 -- **buffer** 数据缓冲区指针 -- **nsectors** 要读取的扇区数 -- **return** 返回 0 表示正常其他表示错误 - -NETWORK ------------------ - -已对接 lwIP 协议栈或者其他网络协议栈，使用 socket API 即可。 \ No newline at end of file diff --git a/docs/source/api/api_port.rst b/docs/source/api/api_port.rst deleted file mode 100644 index c214daa7..00000000 --- a/docs/source/api/api_port.rst +++ /dev/null @@ -1,266 +0,0 @@ -主从驱动 -========================= - -.. note:: 请注意，v1.1 版本开始增加 busid 形参，其余保持不变，所以 API 说明不做更新 - -device controller(dcd) -------------------------- - -usb_dc_init -"""""""""""""""""""""""""""""""""""" - -``usb_dc_init`` 用于初始化 usb device controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。 - -.. code-block:: C - - int usb_dc_init(void); - -- **return** 返回 0 表示正确，其他表示错误 - -usb_dc_deinit -"""""""""""""""""""""""""""""""""""" - -``usb_dc_deinit`` 用于反初始化 usb device controller 寄存器。 **此函数不对用户开放**。 - -.. code-block:: C - - int usb_dc_deinit(void); - -- **return** 返回 0 表示正确，其他表示错误 - -usbd_set_address -"""""""""""""""""""""""""""""""""""" - -``usbd_set_address`` 设置设备地址。 **此函数不对用户开放**。 - -.. code-block:: C - - int usbd_set_address(const uint8_t addr); - -- **addr** 设备地址 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_open -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_open`` 设置端点的属性，开启对应端点的中断。 **此函数不对用户开放**。 - -.. code-block:: C - - int usbd_ep_open(const struct usb_endpoint_descriptor *ep); - -- **ep** 端点描述符 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_close -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_close`` 关闭端点。 **此函数不对用户开放**。 - -.. code-block:: C - - int usbd_ep_close(const uint8_t ep); - -- **ep** 端点地址 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_set_stall -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_set_stall`` 将端点设置成 stall 状态并发送 stall 握手包。 **此函数对用户开放**。 - -.. code-block:: C - - int usbd_ep_set_stall(const uint8_t ep); - -- **ep** 端点地址 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_clear_stall -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_clear_stall`` 清除端点的 stall 状态。 **此函数不对用户开放**。 - -.. code-block:: C - - int usbd_ep_clear_stall(const uint8_t ep); - -- **ep** 端点地址 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_is_stalled -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_is_stalled`` 读取当前端点的 stall 状态。 **此函数不对用户开放**。 - -.. code-block:: C - - int usbd_ep_is_stalled(const uint8_t ep, uint8_t *stalled); - -- **ep** 端点地址 -- **return** 返回 1 表示 stalled，0 表示没有 stall - -usbd_ep_start_write -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_start_write`` 启动端点发送，发送完成以后，会调用注册的 in 端点传输完成中断回调函数。该函数为异步发送。 **此函数对用户开放**。 - -.. code-block:: C - - int usbd_ep_start_write(const uint8_t ep, const uint8_t *data, uint32_t data_len); - -- **ep** in 端点地址 -- **data** 发送数据缓冲区 -- **data_len** 发送长度，原则上无限长，推荐 16K 字节以内 -- **return** 返回 0 表示正确，其他表示错误 - -usbd_ep_start_read -"""""""""""""""""""""""""""""""""""" - -``usbd_ep_start_read`` 启动端点接收，接收完成以后，会调用注册的 out 端点传输完成中断回调函数。该函数为异步接收。 **此函数对用户开放**。 - -.. code-block:: C - - int usbd_ep_start_read(const uint8_t ep, uint8_t *data, uint32_t data_len); - -- **ep** out 端点地址 -- **data** 接收数据缓冲区 -- **data_len** 接收长度，原则上无限长，推荐 16K 字节以内，并且推荐是最大包长的整数倍 -- **return** 返回 0 表示正确，其他表示错误 - -.. note:: 启动接收以后，以下两种情况，会进入传输完成中断：1、最后一包为短包（小于 EP MPS）；2、接收总长度等于 data_len - -.. note:: 对于 bulk 传输，data_len 通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（MSC）; 主机手动发送 ZLP 或者短包（RNDIS） - -host controller(hcd) ------------------------- - -usb_hc_init -"""""""""""""""""""""""""""""""""""" - -``usb_hc_init`` 用于初始化 usb host controller 寄存器，设置 usb 引脚、时钟、中断等等。 **此函数不对用户开放**。 - -.. code-block:: C - - int usb_hc_init(void); - -- **return** 返回 0 表示正确，其他表示错误 - -usb_hc_deinit -"""""""""""""""""""""""""""""""""""" - -``usb_hc_deinit`` 用于反初始化 usb host controller 寄存器。 **此函数不对用户开放**。 - -.. code-block:: C - - int usb_hc_deinit(void); - -- **return** 返回 0 表示正确，其他表示错误 - -usbh_roothub_control -"""""""""""""""""""""""""""""""""""" - -``usbh_roothub_control`` 用来对 roothub 发起请求， **此函数不对用户开放**。 - -.. code-block:: C - - int usbh_roothub_control(struct usb_setup_packet *setup, uint8_t *buf); - -- **setup** 请求 -- **buf** 接收缓冲区 -- **return** 返回 0 表示正确，其他表示错误 - -usbh_submit_urb -"""""""""""""""""""""""""""""""""""" - -``usbh_submit_urb`` 对某个地址上的端点进行数据请求。 **此函数对用户开放**。 - -.. code-block:: C - - int usbh_submit_urb(struct usbh_urb *urb); - -- **urb** usb 请求块 -- **return** 返回 0 表示正确，其他表示错误 - -其中， `urb` 结构体信息如下： - -.. code-block:: C - - struct usbh_urb { - usb_slist_t list; - void *hcpriv; - struct usbh_hubport *hport; - struct usb_endpoint_descriptor *ep; - uint8_t data_toggle; - uint8_t interval; - struct usb_setup_packet *setup; - uint8_t *transfer_buffer; - uint32_t transfer_buffer_length; - int transfer_flags; - uint32_t actual_length; - uint32_t timeout; - int errorcode; - uint32_t num_of_iso_packets; - uint32_t start_frame; - usbh_complete_callback_t complete; - void *arg; - #if defined(__ICCARM__) || defined(__ICCRISCV__) || defined(__ICCRX__) - struct usbh_iso_frame_packet *iso_packet; - #else - struct usbh_iso_frame_packet iso_packet[0]; - #endif - }; - -- **hcpriv** 主机控制器驱动私有成员 -- **hport** 当前 urb 使用的 hport -- **ep** 当前 urb 使用的 ep -- **data_toggle** 当前 data toggle -- **interval** urb 传输间隔，单位 us，如果 interval 大于 1000us，则需要使用软件定时器来维护 -- **setup** setup 请求缓冲区，端点0使用 -- **transfer_buffer** 传输的数据缓冲区 -- **transfer_buffer_length** 传输长度 -- **transfer_flags** 传输时携带的 flag -- **actual_length** 实际传输长度 -- **timeout** 传输超时时间，为 0 该函数则为非阻塞，可在中断中使用 -- **errorcode** 错误码 -- **num_of_iso_packets** iso 帧或者微帧个数 -- **complete** 传输完成回调函数 -- **arg** 传输完成时携带的参数 -- **iso_packet** iso 数据包 - -.. note:: timeout 如何没有特别对时间的要求，必须设置成 0xffffffff，原则上不允许超时，如果超时了，一般不能再继续工作 - -`errorcode` 可以返回以下值： - -.. code-block:: C - - #define USB_ERR_NOMEM 1 - #define USB_ERR_INVAL 2 - #define USB_ERR_NODEV 3 - #define USB_ERR_NOTCONN 4 - #define USB_ERR_NOTSUPP 5 - #define USB_ERR_BUSY 6 - #define USB_ERR_RANGE 7 - #define USB_ERR_STALL 8 - #define USB_ERR_BABBLE 9 - #define USB_ERR_NAK 10 - #define USB_ERR_DT 11 - #define USB_ERR_IO 12 - #define USB_ERR_SHUTDOWN 13 - #define USB_ERR_TIMEOUT 14 - -其中 `iso_packet` 结构体信息如下： - -.. code-block:: C - - struct usbh_iso_frame_packet { - uint8_t *transfer_buffer; - uint32_t transfer_buffer_length; - uint32_t actual_length; - int errorcode; - }; - -- **transfer_buffer** 传输的数据缓冲区 -- **transfer_buffer_length** 传输长度 -- **actual_length** 实际传输长度 -- **errorcode** 错误码 \ No newline at end of file diff --git a/docs/source/api/img/api_device1.png b/docs/source/api/img/api_device1.png deleted file mode 100644 index ba218b65..00000000 Binary files a/docs/source/api/img/api_device1.png and /dev/null differ diff --git a/docs/source/api/img/api_host1.png b/docs/source/api/img/api_host1.png deleted file mode 100644 index 82932f50..00000000 Binary files a/docs/source/api/img/api_host1.png and /dev/null differ diff --git a/docs/source/api/img/api_host2.png b/docs/source/api/img/api_host2.png deleted file mode 100644 index 7f6d60b8..00000000 Binary files a/docs/source/api/img/api_host2.png and /dev/null differ diff --git a/docs/source/class/class_audio.rst b/docs/source/class/class_audio.rst deleted file mode 100644 index d1a9e207..00000000 --- a/docs/source/class/class_audio.rst +++ /dev/null @@ -1,4 +0,0 @@ -UAC -========================= - -参考官方 audio 相关 pdf \ No newline at end of file diff --git a/docs/source/class/class_cdc.rst b/docs/source/class/class_cdc.rst deleted file mode 100644 index d3ed560f..00000000 --- a/docs/source/class/class_cdc.rst +++ /dev/null @@ -1,4 +0,0 @@ -CDC -========================= - -参考官方 cdc 相关 pdf \ No newline at end of file diff --git a/docs/source/class/class_hid.rst b/docs/source/class/class_hid.rst deleted file mode 100644 index 0f9ef13d..00000000 --- a/docs/source/class/class_hid.rst +++ /dev/null @@ -1,4 +0,0 @@ -HID -========================= - -参考官方 hid 相关 pdf \ No newline at end of file diff --git a/docs/source/class/class_msc.rst b/docs/source/class/class_msc.rst deleted file mode 100644 index c01a359c..00000000 --- a/docs/source/class/class_msc.rst +++ /dev/null @@ -1,4 +0,0 @@ -MSC -========================= - -参考官方 msc 相关 pdf \ No newline at end of file diff --git a/docs/source/class/class_video.rst b/docs/source/class/class_video.rst deleted file mode 100644 index cabe5173..00000000 --- a/docs/source/class/class_video.rst +++ /dev/null @@ -1,4 +0,0 @@ -UVC -========================= - -参考官方 video 相关 pdf \ No newline at end of file diff --git a/docs/source/class/winusb.rst b/docs/source/class/winusb.rst deleted file mode 100644 index 8c74d3b7..00000000 --- a/docs/source/class/winusb.rst +++ /dev/null @@ -1,2 +0,0 @@ -WINUSB -========================= diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 6174f623..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,37 +0,0 @@ -# Configuration file for the Sphinx documentation builder. - -# -- Project information - -project = 'CherryUSB' -copyright = '2022 ~ 2025, sakumisu' -author = 'sakumisu' - -release = '1.6.0' -version = '1.6.0' - -# -- General configuration - -extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'recommonmark', - 'sphinx_markdown_tables' -] - -intersphinx_mapping = { -# 'python': ('https://docs.python.org/3/', None), -# 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), -} -intersphinx_disabled_domains = ['std'] - -templates_path = ['_templates'] - -# -- Options for HTML output - -html_theme = 'sphinx_rtd_theme' - -# -- Options for EPUB output -epub_show_urls = 'footnote' diff --git a/docs/source/demo/img/cherryadb.png b/docs/source/demo/img/cherryadb.png deleted file mode 100644 index 512586b9..00000000 Binary files a/docs/source/demo/img/cherryadb.png and /dev/null differ diff --git a/docs/source/demo/img/otg.png b/docs/source/demo/img/otg.png deleted file mode 100644 index 9605176a..00000000 Binary files a/docs/source/demo/img/otg.png and /dev/null differ diff --git a/docs/source/demo/img/rtt_adb_shell1.png b/docs/source/demo/img/rtt_adb_shell1.png deleted file mode 100644 index df4964a2..00000000 Binary files a/docs/source/demo/img/rtt_adb_shell1.png and /dev/null differ diff --git a/docs/source/demo/img/rtt_adb_shell2.png b/docs/source/demo/img/rtt_adb_shell2.png deleted file mode 100644 index 88d99a6a..00000000 Binary files a/docs/source/demo/img/rtt_adb_shell2.png and /dev/null differ diff --git a/docs/source/demo/img/usbh_serial.png b/docs/source/demo/img/usbh_serial.png deleted file mode 100644 index da929c4a..00000000 Binary files a/docs/source/demo/img/usbh_serial.png and /dev/null differ diff --git a/docs/source/demo/usb_otg.rst b/docs/source/demo/usb_otg.rst deleted file mode 100644 index 78692cc0..00000000 --- a/docs/source/demo/usb_otg.rst +++ /dev/null @@ -1,15 +0,0 @@ -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_adb.rst b/docs/source/demo/usbd_adb.rst deleted file mode 100644 index 92a3043e..00000000 --- a/docs/source/demo/usbd_adb.rst +++ /dev/null @@ -1,28 +0,0 @@ -usbd_adb -=============== - -本节主要介绍如何使用 adb device。支持 **cherrysh** 和 rt-thread **msh**，只需要在 main 中添加以下初始化即可。 - -.. code-block:: C - - cherryadb_init(0, xxxxx); - -如果使用 rt-thread，还需要在 menuconfig 中使能 adb device。 - -.. figure:: img/rtt_adb_shell1.png - -进入 adb --------------- - -- 使用 **cherrysh** 时枚举完成以后自动进入 adb 模式 -- 使用 **msh** 需要在 **msh** 中输入 ``adb_enter`` 进入 adb 模式 - -退出 adb --------------- - -- 使用 **cherrysh** 时输入 ``exit`` 退出 adb 模式 -- 使用 **msh** 需要在 **msh** 中输入 ``adb_exit`` 退出 adb 模式 - -.. figure:: img/cherryadb.png - -.. figure:: img/rtt_adb_shell2.png diff --git a/docs/source/demo/usbd_audiov1.rst b/docs/source/demo/usbd_audiov1.rst deleted file mode 100644 index 794ac8f6..00000000 --- a/docs/source/demo/usbd_audiov1.rst +++ /dev/null @@ -1,7 +0,0 @@ -usbd_audiov1 -=============== - -在使用 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 deleted file mode 100644 index 0390f17d..00000000 --- a/docs/source/demo/usbd_audiov2.rst +++ /dev/null @@ -1,9 +0,0 @@ -usbd_audiov2 -=============== - -在使用 UAC2.0 时，需要注意以下几点： - -- 在使用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/demo/usbd_cdc_acm.rst b/docs/source/demo/usbd_cdc_acm.rst deleted file mode 100644 index be330b4c..00000000 --- a/docs/source/demo/usbd_cdc_acm.rst +++ /dev/null @@ -1,104 +0,0 @@ -usbd_cdc_acm -=============== - -本 demo 主要用于演示 cdc acm 功能，包含收发测试，DTR 控制，ZLP 测试，性能测试。 - -- 开辟读写 buffer，用于收发数据，并且buffer需要用 nocache 修饰，这里我们读写都是用 2048字节，是为了后面的 ZLP 测试和性能测试使用。 - -.. code-block:: C - - USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t read_buffer[2048]; /* 2048 is only for test speed , please use CDC_MAX_MPS for common*/ - USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t write_buffer[2048]; - - -- 在协议栈事件回调中，我们需要在枚举完成后启动第一次传输，并清除相关 flag，可以在 reset 事件中清除，也可以在 configured 事件中清除。 - -.. code-block:: C - - static void usbd_event_handler(uint8_t busid, uint8_t event) - { - switch (event) { - case USBD_EVENT_RESET: - break; - case USBD_EVENT_CONNECTED: - break; - case USBD_EVENT_DISCONNECTED: - break; - case USBD_EVENT_RESUME: - break; - case USBD_EVENT_SUSPEND: - break; - case USBD_EVENT_CONFIGURED: - ep_tx_busy_flag = false; - /* setup first out ep read transfer */ - usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048); - break; - case USBD_EVENT_SET_REMOTE_WAKEUP: - break; - case USBD_EVENT_CLR_REMOTE_WAKEUP: - break; - - default: - break; - } - } - -- 在接收完成中断中继续发起接收；在发送完成中断中判断是否需要发送 ZLP。 - -.. code-block:: C - - void usbd_cdc_acm_bulk_out(uint8_t busid, uint8_t ep, uint32_t nbytes) - { - USB_LOG_RAW("actual out len:%d\r\n", nbytes); - // for (int i = 0; i < 100; i++) { - // printf("%02x ", read_buffer[i]); - // } - // printf("\r\n"); - /* setup next out ep read transfer */ - usbd_ep_start_read(busid, CDC_OUT_EP, read_buffer, 2048); - } - - void usbd_cdc_acm_bulk_in(uint8_t busid, uint8_t ep, uint32_t nbytes) - { - USB_LOG_RAW("actual in len:%d\r\n", nbytes); - - if ((nbytes % usbd_get_ep_mps(busid, ep)) == 0 && nbytes) { - /* send zlp */ - usbd_ep_start_write(busid, CDC_IN_EP, NULL, 0); - } else { - ep_tx_busy_flag = false; - } - } - -- 以下是为了测试 DTR 功能并控制 USB 发送，DTR 和 RTS 只用于搭配 UART 使用，如果是纯 USB，没什么用，这里仅做测试。DTR 开关使用任意串口上位机并勾选 DTR。 - -.. code-block:: C - - void usbd_cdc_acm_set_dtr(uint8_t busid, uint8_t intf, bool dtr) - { - if (dtr) { - dtr_enable = 1; - } else { - dtr_enable = 0; - } - } - -- 在主函数中一直调用发送即可 - -.. code-block:: C - - void cdc_acm_data_send_with_dtr_test(uint8_t busid) - { - if (dtr_enable) { - ep_tx_busy_flag = true; - usbd_ep_start_write(busid, CDC_IN_EP, write_buffer, 2048); - while (ep_tx_busy_flag) { - } - } - } - -- 上述我们需要注意，长度设置为 2048 是为了测试 ZLP 功能，通常实际使用时，接收长度应该使用 CDC_MAX_MPS 。具体原因参考 :ref:`usb_ext` -- 如果需要做性能测试，使用 tools/test_srcipts/test_cdc_speed.py 进行测试,并在测试之前删除 `usbd_cdc_acm_bulk_out` 和 `usbd_cdc_acm_bulk_in` 中的打印，否则会影响测试结果。 - - -此外，对于 CDC ACM 搭配 OS 的情况，通常我们 read 使用异步并将数据存储到 ringbuffer 中，write 使用同步搭配 sem 使用。 \ No newline at end of file diff --git a/docs/source/demo/usbd_ecm.rst b/docs/source/demo/usbd_ecm.rst deleted file mode 100644 index c4c64ab5..00000000 --- a/docs/source/demo/usbd_ecm.rst +++ /dev/null @@ -1,2 +0,0 @@ -usbd_cdc_ecm -=============== diff --git a/docs/source/demo/usbd_hid.rst b/docs/source/demo/usbd_hid.rst deleted file mode 100644 index 68b6b285..00000000 --- a/docs/source/demo/usbd_hid.rst +++ /dev/null @@ -1,4 +0,0 @@ -usbd_hid -=============== - -HID 功能比较简单，因此不作赘述，需要注意，使用 hid custom 例程时，需要搭配 `tools/test_srcipts/test_hid_inout.py` 使用。 \ No newline at end of file diff --git a/docs/source/demo/usbd_msc.rst b/docs/source/demo/usbd_msc.rst deleted file mode 100644 index ff59aada..00000000 --- a/docs/source/demo/usbd_msc.rst +++ /dev/null @@ -1,39 +0,0 @@ -usbd_msc -=============== - -本节主要演示 USB 模拟 U 盘功能。默认使用RAM 作为存储介质模拟 U 盘。 - -- 实现 U 盘的读写和获取容量接口，注意，容量 block_num 为虚拟的，实际没有这么多 block，读写的数据超过 BLOCK_COUNT 会丢弃。 - -block_size 一般为 512/2048/4096。 - -.. code-block:: C - - void usbd_msc_get_cap(uint8_t busid, uint8_t lun, uint32_t *block_num, uint32_t *block_size) - { - *block_num = 1000; //Pretend having so many buffer,not has actually. - *block_size = BLOCK_SIZE; - } - int usbd_msc_sector_read(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length) - { - if (sector < BLOCK_COUNT) - memcpy(buffer, mass_block[sector].BlockSpace, length); - return 0; - } - - int usbd_msc_sector_write(uint8_t busid, uint8_t lun, uint32_t sector, uint8_t *buffer, uint32_t length) - { - if (sector < BLOCK_COUNT) - memcpy(mass_block[sector].BlockSpace, buffer, length); - return 0; - } - -- 默认上述 API 在中断中执行，如果需要在非中断中执行，可以选择如下： - -1，裸机下开启 `CONFIG_USBDEV_MSC_POLLING` 并在 while1 中调用 `usbd_msc_polling`，则读写函数在 while1 中执行。 - -2, OS 下开启 `CONFIG_USBDEV_MSC_THREAD`，则读写函数在线程中执行。 - -- 修改 `CONFIG_USBDEV_MSC_BUFSIZE` 会影响 U 盘的读写速度，必须是 block_size 的整数倍，当然，也会增加 RAM 的占用。 - -- 如果 RAM 例程可以用，但是介质更换成 SD 或者 FLASH 后不可用，则一定是介质驱动问题。 \ No newline at end of file diff --git a/docs/source/demo/usbd_rndis.rst b/docs/source/demo/usbd_rndis.rst deleted file mode 100644 index 40fba402..00000000 --- a/docs/source/demo/usbd_rndis.rst +++ /dev/null @@ -1,2 +0,0 @@ -usbd_rndis -=============== diff --git a/docs/source/demo/usbd_vendor.rst b/docs/source/demo/usbd_vendor.rst deleted file mode 100644 index b38631b1..00000000 --- a/docs/source/demo/usbd_vendor.rst +++ /dev/null @@ -1,44 +0,0 @@ -vendor device 驱动编写 -=========================== - -本节主要介绍如何编写一个 vendor device 驱动。 - -- 首先复制一份 class/template/usbd_xxx.c 文件 -- 实现以下三个回调函数，通常来说，vendor 驱动只需要实现 vendor_handler - -.. code-block:: C - - intf->class_interface_handler = xxx_class_interface_request_handler; - intf->class_endpoint_handler = NULL; - intf->vendor_handler = NULL; - intf->notify_handler = xxx_notify_handler; - -- 举例如下 - -case1 演示对于主机 IN 数据的处理，将数据拷贝到 *data 中，并指定*len 的长度。协议栈会自动发送给主机，不需要用户手动调用发送 API。 - -case2 演示对于主机 OUT 数据的处理，当执行到此函数时，说明数据都已经接收完成，可以直接读取 *data 中的数据，长度为 *len。 - -.. code-block:: C - - static int xxx_vendor_request_handler(uint8_t busid, struct usb_setup_packet *setup, uint8_t **data, uint32_t *len) - { - USB_LOG_WRN("XXX Class request: " - "bRequest 0x%02x\r\n", - setup->bRequest); - - switch (setup->bRequest) { - case 1: - memcpy(*data, xxx, sizeof(xxx)); - *len = sizeof(xxx); - case 2: - hexdump(*data, *len); - default: - USB_LOG_WRN("Unhandled XXX Class bRequest 0x%02x\r\n", setup->bRequest); - return -1; - } - - return 0; - } - -- 最后使用形如 usbd_add_interface(busid, usbd_xxx_init_intf(&intf)) 注册接口 \ No newline at end of file diff --git a/docs/source/demo/usbd_video.rst b/docs/source/demo/usbd_video.rst deleted file mode 100644 index e215abde..00000000 --- a/docs/source/demo/usbd_video.rst +++ /dev/null @@ -1,83 +0,0 @@ -usbd_video -=============== - -本节主要演示 USB UAC 功能，支持 YUYV, MJPEG, H264 格式。为了方便演示，都采用的静态图。 - -demo 包含 **video_static_yuyv_template**, **video_static_mjpeg_template**, **video_static_h264_template**, 仅描述符和图片数据不同。 - -- 在高速模式下，默认最大是1024字节，但是如果芯片支持 additional transcations，可以配置为最高 2048字节或者3072字节，这样可以提高传输效率。 - -.. code-block:: C - - #ifdef CONFIG_USB_HS - #define MAX_PAYLOAD_SIZE 1024 // for high speed with one transcations every one micro frame - #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11)) - - // #define MAX_PAYLOAD_SIZE 2048 // for high speed with two transcations every one micro frame - // #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 2)) | (0x01 << 11)) - - // #define MAX_PAYLOAD_SIZE 3072 // for high speed with three transcations every one micro frame - // #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 3)) | (0x02 << 11)) - - #else - #define MAX_PAYLOAD_SIZE 1020 - #define VIDEO_PACKET_SIZE (unsigned int)(((MAX_PAYLOAD_SIZE / 1)) | (0x00 << 11)) - #endif - -- 通常只需要修改 WIDTH 和 HEIGHT - -.. code-block:: C - - #define WIDTH (unsigned int)(640) - #define HEIGHT (unsigned int)(480) - - #define CAM_FPS (30) - #define INTERVAL (unsigned long)(10000000 / CAM_FPS) - #define MIN_BIT_RATE (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS) //16 bit - #define MAX_BIT_RATE (unsigned long)(WIDTH * HEIGHT * 16 * CAM_FPS) - #define MAX_FRAME_SIZE (unsigned long)(WIDTH * HEIGHT * 2) - -- USB 端点配置，默认 interval 为 1，也就是全速模式下 1ms，高速模式下 125us。同步类型使用异步模式。 - -.. code-block:: C - - /* 1.2.2.2 Standard VideoStream Isochronous Video Data Endpoint Descriptor */ - USB_ENDPOINT_DESCRIPTOR_INIT(VIDEO_IN_EP, 0x05, VIDEO_PACKET_SIZE, 0x01), - - -- 使用 `usbd_video_stream_start_write` 传输数据, 最后 **do_copy** 选项表示是否将数据 copy 到 packet_buffer, -如果不选择 copy， 则会直接在原图像数据中填充头部信息，并直接发送，达到 zero copy 功能。 - -- 因为提供的是静态数据，不能被修改，因此需要重新给一个 frame_buffer 用于图像传输，在实际对接 camera 场景中是动态数据，直接使用 camera 的数据缓冲区即可。 - - -.. code-block:: C - - void usbd_video_iso_callback(uint8_t busid, uint8_t ep, uint32_t nbytes) - { - if (usbd_video_stream_split_transfer(busid, ep)) { - /* one frame has done */ - iso_tx_busy = false; - } - } - - USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t packet_buffer[MAX_PAYLOAD_SIZE]; - USB_NOCACHE_RAM_SECTION USB_MEM_ALIGNX uint8_t frame_buffer[32 * 1024]; - - void video_test(uint8_t busid) - { - memset(packet_buffer, 0, sizeof(packet_buffer)); - - while (1) { - if (tx_flag) { - iso_tx_busy = true; - memcpy(frame_buffer, cherryusb_mjpeg, sizeof(cherryusb_mjpeg)); // cherryusb_mjpeg is a static MJPEG frame buffer, so we need copy it to frame_buffer - usbd_video_stream_start_write(busid, VIDEO_IN_EP, packet_buffer, (uint8_t *)frame_buffer, sizeof(cherryusb_mjpeg), false); - while (iso_tx_busy) { - if (tx_flag == 0) { - break; - } - } - } - } - } \ No newline at end of file diff --git a/docs/source/demo/usbd_webusb.rst b/docs/source/demo/usbd_webusb.rst deleted file mode 100644 index 0df9bef6..00000000 --- a/docs/source/demo/usbd_webusb.rst +++ /dev/null @@ -1,21 +0,0 @@ -usbd_webusb -=============== - -本 demo 主要演示 webusb 功能，webusb 主要用于弹出网页并对 USB 设备进行访问。示例使用 webusb_hid_template.c。 - -- 在注册描述符时注册 BOS, MSOSV2, WEBUSB 描述符即可。 - -.. code-block:: C - - usbd_bos_desc_register(busid, &bos_desc); - usbd_msosv2_desc_register(busid, &msosv2_desc); - usbd_webusb_desc_register(busid, &webusb_url_desc); - -- 增加一个接口描述符用于 webusb - -.. code-block:: C - - USB_INTERFACE_DESCRIPTOR_INIT(USBD_WEBUSB_INTF_NUM, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00) - -- 其余使用 hid 描述符，不再赘述 -- 枚举完成后，电脑右下角会弹出网页信息，点击即可打开网页 \ No newline at end of file diff --git a/docs/source/demo/usbd_winusb.rst b/docs/source/demo/usbd_winusb.rst deleted file mode 100644 index 0a6d4de9..00000000 --- a/docs/source/demo/usbd_winusb.rst +++ /dev/null @@ -1,55 +0,0 @@ -usbd_winusb -=============== - -本节主要介绍 winusb 驱动。winusb 是 windows 为了让用户友好的访问 USB 自定义类设备提供的一套通用驱动，其实本质就是 CDC ACM，只不过没有设置波特率的命令。 -WINUSB 版本根据 USB 版本分为 V1/V2 版本，V2 版本需要包含 BOS 描述符，V1 版本不需要。 **V2 版本需要在设备描述符中设置为 USB2.1 的版本号**。 - -.. note:: 更换 winusb 描述符任意配置可能会枚举成功但是无法识别设备，需要删除 计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\usbflags 下所有注册表项，重新插拔设备后生效。 - -- V1 版本注册描述符 - -.. code-block:: C - - const struct usb_descriptor winusbv1_descriptor = { - .device_descriptor_callback = device_descriptor_callback, - .config_descriptor_callback = config_descriptor_callback, - .device_quality_descriptor_callback = device_quality_descriptor_callback, - .string_descriptor_callback = string_descriptor_callback, - .msosv1_descriptor = &msosv1_desc - }; - - OR - - usbd_msosv1_desc_register(busid, &msosv1_desc); - -- V2 版本注册描述符 - -.. code-block:: C - - const struct usb_descriptor winusbv2_descriptor = { - .device_descriptor_callback = device_descriptor_callback, - .config_descriptor_callback = config_descriptor_callback, - .device_quality_descriptor_callback = device_quality_descriptor_callback, - .string_descriptor_callback = string_descriptor_callback, - .msosv2_descriptor = &msosv2_desc, - .bos_descriptor = &bos_desc, - }; - - OR - - usbd_bos_desc_register(busid, &bos_desc); - usbd_msosv2_desc_register(busid, &msosv2_desc); - - -- 接口描述符注册 - -.. code-block:: C - - /* Interface 0 */ - USB_INTERFACE_DESCRIPTOR_INIT(0x00, 0x00, 0x02, 0xFF, 0x00, 0x00, 0x02), - /* Endpoint OUT 2 */ - USB_ENDPOINT_DESCRIPTOR_INIT(WINUSB_OUT_EP, USB_ENDPOINT_TYPE_BULK, WINUSB_EP_MPS, 0x00), - /* Endpoint IN 1 */ - USB_ENDPOINT_DESCRIPTOR_INIT(WINUSB_IN_EP, USB_ENDPOINT_TYPE_BULK, WINUSB_EP_MPS, 0x00), - -- 读写操作与 CDC ACM 相同，不再赘述 \ No newline at end of file diff --git a/docs/source/demo/usbh_bluetooth.rst b/docs/source/demo/usbh_bluetooth.rst deleted file mode 100644 index a93844ea..00000000 --- a/docs/source/demo/usbh_bluetooth.rst +++ /dev/null @@ -1,2 +0,0 @@ -usbh_bluetooth -=============== diff --git a/docs/source/demo/usbh_hid.rst b/docs/source/demo/usbh_hid.rst deleted file mode 100644 index 6d519319..00000000 --- a/docs/source/demo/usbh_hid.rst +++ /dev/null @@ -1,55 +0,0 @@ -usbh_hid -=============== - -本节主要介绍 HID 类的使用。 - -- HID 枚举完成回调中创建一次性线程 - -.. code-block:: C - - - void usbh_hid_run(struct usbh_hid *hid_class) - { - usb_osal_thread_create("usbh_hid", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_hid_thread, hid_class); - } - - void usbh_hid_stop(struct usbh_hid *hid_class) - { - } - - -- 这里我们使用 usbh_submit_urb 的异步操作，在中断中处理数据并继续接收下一次数据。 - -.. code-block:: C - - static void usbh_hid_thread(void *argument) - { - int ret; - struct usbh_hid *hid_class = (struct usbh_hid *)argument; - ; - - /* test with only one buffer, if you have more hid class, modify by yourself */ - - /* Suggest you to use timer for int transfer and use ep interval */ - usbh_int_urb_fill(&hid_class->intin_urb, hid_class->hport, hid_class->intin, hid_buffer, hid_class->intin->wMaxPacketSize, 0, usbh_hid_callback, hid_class); - ret = usbh_submit_urb(&hid_class->intin_urb); - if (ret < 0) { - goto delete; - } - // clang-format off - delete: - usb_osal_thread_delete(NULL); - // clang-format on - } - -- 当然，也可以不使用异步操作，而是使用 timeout 的同步操作。 -- HID 使用的是中断传输，因此正常来说，我们需要根据 **bInterval** 来设置定时器，定时触发中断传输，demo 这里没有使用，如果对时间有精确要求，可以选择使用定时器来触发异步发送。 -- 以 hub 通信为例，采用的是一次性定时器，也可以使用周期性定时器。 - -.. code-block:: C - - hub->int_timer = usb_osal_timer_create("hubint_tim", USBH_GET_URB_INTERVAL(hub->intin->bInterval, hport->speed) / 1000, hub_int_timeout, hub, 0); - -.. note:: - - 这里的 `USBH_GET_URB_INTERVAL` 是一个宏定义，用于根据 binterval 计算 URB 的传输间隔时间, 单位是 us，而定时器最低是 ms ，因此需要除以 1000。对于小于等于 1ms 的不需要使用定时器。 \ No newline at end of file diff --git a/docs/source/demo/usbh_msc.rst b/docs/source/demo/usbh_msc.rst deleted file mode 100644 index 83956cc2..00000000 --- a/docs/source/demo/usbh_msc.rst +++ /dev/null @@ -1,56 +0,0 @@ -usbh_msc -=============== - -本节主要介绍主机 MSC 使用。借助 FATFS 实现读写功能。 - -- 在 msc 枚举完成的回调中注册一个线程，用于读写操作。 - -.. code-block:: C - - void usbh_msc_run(struct usbh_msc *msc_class) - { - usb_osal_thread_create("usbh_msc", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_msc_thread, msc_class); - } - - void usbh_msc_stop(struct usbh_msc *msc_class) - { - } - - -- 不使用 fatfs，则直接使用 usbh_msc_scsi_read10 或者 usbh_msc_scsi_write10 函数进行读写操作。 -- 如果使用 fatfs，则需要在 usbh_msc_thread 中调用 fatfs 的接口进行读写操作。msc读写适配fatfs 参考 `platform/fatfs/usbh_fatfs.c` - -.. code-block:: C - - static void usbh_msc_thread(void *argument) - { - int ret; - struct usbh_msc *msc_class = (struct usbh_msc *)argument; - - /* test with only one buffer, if you have more msc class, modify by yourself */ - #if 1 - /* get the partition table */ - ret = usbh_msc_scsi_read10(msc_class, 0, partition_table, 1); - if (ret < 0) { - USB_LOG_RAW("scsi_read10 error,ret:%d\r\n", ret); - goto delete; - } - for (uint32_t i = 0; i < 512; i++) { - if (i % 16 == 0) { - USB_LOG_RAW("\r\n"); - } - USB_LOG_RAW("%02x ", partition_table[i]); - } - USB_LOG_RAW("\r\n"); - #endif - - #if TEST_USBH_MSC_FATFS - usb_msc_fatfs_test(); - #endif - // clang-format off - delete: - usb_osal_thread_delete(NULL); - // clang-format on - } - -- 最后处理完成或者失败后，删除线程。 \ No newline at end of file diff --git a/docs/source/demo/usbh_net.rst b/docs/source/demo/usbh_net.rst deleted file mode 100644 index 8757991e..00000000 --- a/docs/source/demo/usbh_net.rst +++ /dev/null @@ -1,156 +0,0 @@ -usbh_net -=============== - -本节主要介绍 USB 网卡的使用，当前已经支持和测试以下 USB 网卡: - -- 4G 网卡：EC20(ECM/RNDIS)、手机（RNDIS）、SIMCOM7600(RNDIS)、ML307R(RNDIS)、AIR780(RNDIS) - -.. caution:: 请注意，部分 4G 网卡默认不带自动拨号功能，请更换固件或者使用 AT 配置成自动拨号，否则无法获取 IP。 - -- USB 以太网卡：ASIX AX88772，REALTEK RTL8152 -- USB WIFI 网卡： 博流 BL616（RNDIS/ECM） - -USB 网卡相关的宏和文件 ------------------------- - -网卡相关的宏如下，主要用于根据不同的网络组件注册网卡驱动： - -.. code-block:: C - - // #define CONFIG_USBHOST_PLATFORM_CDC_ECM - // #define CONFIG_USBHOST_PLATFORM_CDC_RNDIS - // #define CONFIG_USBHOST_PLATFORM_CDC_NCM - // #define CONFIG_USBHOST_PLATFORM_ASIX - // #define CONFIG_USBHOST_PLATFORM_RTL8152 - -.. note:: 如果使用了 Kconfig 系统，上述宏自定生成，其他平台请手动定义。 - -USB 网卡传输层面已经对接好了相关网络组件，列举如下： - -- 自定义 OS + LWIP 请使用 **platform/lwip/usbh_lwip.c**，需要自行包含该文件，并使能上述相关的宏。并在初始化 USB 之前调用 `tcpip_init(NULL, NULL)` -- RT-THREAD + LWIP 请使用 **platform/rtthread/usbh_lwip.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件，勾选 rt-thread lwip以后自动调用 `tcpip_init(NULL, NULL)` -- ESP-IDF + LWIP 请使用 **platform/freertos/usbh_net.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件，并且在初始化 USB 之前调用 `esp_netif_init()` + `esp_event_loop_create_default()` -- NUTTX + NUTTX 网络组件 请使用 **platform/nuttx/usbh_net.c**，在 Kconfig 中使能对应的网卡驱动后自动勾选该文件，勾选网络组件以后自动调用 - -.. note:: 如果是自行添加代码，别忘了添加 USB 网卡驱动相关的源文件，例如 **class/usbh_cdc_ecm.c**。所以我们推荐搭配对应平台使用哦，省去自己添加文件的麻烦 - -USB 网卡对接过程 -------------------- - -下面举例对接 LWIP 的对接过程。 - -- 在 USB 网卡枚举完成以后，会 **自动** 调用 `usbh_xxx_run` 函数，此时注册 netif 驱动，并且开启 DHCP 客户端和获取 IP 的定时器。 - -.. code-block:: C - - void usbh_cdc_ecm_run(struct usbh_cdc_ecm *cdc_ecm_class) - { - struct netif *netif = &g_cdc_ecm_netif; - - netif->hwaddr_len = 6; - memcpy(netif->hwaddr, cdc_ecm_class->mac, 6); - - IP4_ADDR(&g_ipaddr, 0, 0, 0, 0); - IP4_ADDR(&g_netmask, 0, 0, 0, 0); - IP4_ADDR(&g_gateway, 0, 0, 0, 0); - - netif = netif_add(netif, &g_ipaddr, &g_netmask, &g_gateway, NULL, usbh_cdc_ecm_if_init, tcpip_input); - netif_set_default(netif); - while (!netif_is_up(netif)) { - } - - dhcp_handle = usb_osal_timer_create("dhcp", 200, dhcp_timeout, netif, true); - if (dhcp_handle == NULL) { - USB_LOG_ERR("timer creation failed! \r\n"); - while (1) { - } - } - - usb_osal_thread_create("usbh_cdc_ecm_rx", 2048, CONFIG_USBHOST_PSC_PRIO + 1, usbh_cdc_ecm_rx_thread, NULL); - #if LWIP_DHCP - dhcp_start(netif); - usb_osal_timer_start(dhcp_handle); - #endif - } - -- `usbh_lwip_eth_output_common` 用于将发送 pbuf 组装成 USB 网卡数据包 -- `usbh_lwip_eth_input_common` 用于将 USB 网卡数据组装成 pbuf -- 实际网卡发送和接收处理 - -.. code-block:: C - - static err_t usbh_cdc_ecm_linkoutput(struct netif *netif, struct pbuf *p) - { - int ret; - (void)netif; - - usbh_lwip_eth_output_common(p, usbh_cdc_ecm_get_eth_txbuf()); - ret = usbh_cdc_ecm_eth_output(p->tot_len); - if (ret < 0) { - return ERR_BUF; - } else { - return ERR_OK; - } - } - - void usbh_cdc_ecm_eth_input(uint8_t *buf, uint32_t buflen) - { - usbh_lwip_eth_input_common(&g_cdc_ecm_netif, buf, buflen); - } - -- USB 网卡 拔出以后会 **自动** 调用 `usbh_xxx_stop` 函数，此时需要停止 DHCP 客户端，删除定时器，并且移除 netif。 - -.. code-block:: C - - void usbh_cdc_ecm_stop(struct usbh_cdc_ecm *cdc_ecm_class) - { - struct netif *netif = &g_cdc_ecm_netif; - (void)cdc_ecm_class; - - #if LWIP_DHCP - dhcp_stop(netif); - dhcp_cleanup(netif); - usb_osal_timer_delete(dhcp_handle); - #endif - netif_set_down(netif); - netif_remove(netif); - } - -- 因为 USB 网卡内部已经对接了LWIP，因此用户可以直接使用 LWIP 的 API，无需关心 USB 的实现。 - -USB 网卡 LWIP 配置宏相关注意事项 ------------------------------------- - -**LWIP_TCPIP_CORE_LOCKING_INPUT** 用于不使用 lwip 内置的 tcpip 线程，而使用 USB 自己的接收处理线程。 - -**LWIP_TCPIP_CORE_LOCKING** 在现在 lwip 版本中默认是打开的，也推荐必须打开。 - -**PBUF_POOL_BUFSIZE** 推荐大于1600，搭配 LWIP_TCPIP_CORE_LOCKING_INPUT 使用，因为我们提供了使用 zero mempy 的方式，使用静态 pbuf，而不是把数据 copy 到 pbuf 中。 - -**TCPIP_THREAD_STACKSIZE** 推荐大于 1K，防止栈溢出。 - -.. code-block:: C - - #if LWIP_TCPIP_CORE_LOCKING_INPUT != 1 - #warning suggest you to set LWIP_TCPIP_CORE_LOCKING_INPUT to 1, usb handles eth input with own thread - #endif - - #if LWIP_TCPIP_CORE_LOCKING != 1 - #error must set LWIP_TCPIP_CORE_LOCKING to 1 - #endif - - #if PBUF_POOL_BUFSIZE < 1600 - #error PBUF_POOL_BUFSIZE must be larger than 1600 - #endif - - #if TCPIP_THREAD_STACKSIZE < 1024 - #error TCPIP_THREAD_STACKSIZE must be >= 1024 - #endif - - -总结 --------------- - -.. note:: 通过以上内容，我们可以看到 CherryUSB 对 USB 网卡的支持是非常完善的，用户只需要使能对应的宏或者勾选，就可以实现 USB 网卡的自动识别和驱动注册，无需手动初始化网卡相关配置，用户只需关注应用层，极大地方便了用户的使用。 - -具体移植文章可以参考开发者的一些笔记 https://club.rt-thread.org/ask/article/5cf3e9e0b2d95800.html \ No newline at end of file diff --git a/docs/source/demo/usbh_serial.rst b/docs/source/demo/usbh_serial.rst deleted file mode 100644 index 619545c6..00000000 --- a/docs/source/demo/usbh_serial.rst +++ /dev/null @@ -1,196 +0,0 @@ -usbh_serial -=============== - -Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。 - -.. figure:: img/usbh_serial.png - -当前支持两种使用方式，一种是使用源生 CherryUSB usbhost serial API 进行操作，另一种是基于平台封装的 API 操作，比如 rt-thread device API，nuttx posix API。 - -下面演示的是使用 CherryUSB usbhost serial API 进行串口回环测试，并且使用阻塞发送，异步读取的方式： - -.. code-block:: C - - struct usbh_serial *serial; - - serial = usbh_serial_open("/dev/ttyACM0", USBH_SERIAL_O_RDWR | USBH_SERIAL_O_NONBLOCK); - if (serial == NULL) { - serial = usbh_serial_open("/dev/ttyUSB0", USBH_SERIAL_O_RDWR | USBH_SERIAL_O_NONBLOCK); - if (serial == NULL) { - USB_LOG_RAW("no serial device found\r\n"); - goto delete; - } - } - - struct usbh_serial_termios termios; - - memset(&termios, 0, sizeof(termios)); - termios.baudrate = 115200; - termios.stopbits = 0; - termios.parity = 0; - termios.databits = 8; - termios.rtscts = false; - termios.rx_timeout = 0; - ret = usbh_serial_control(serial, USBH_SERIAL_CMD_SET_ATTR, &termios); - if (ret < 0) { - USB_LOG_RAW("set serial attr error, ret:%d\r\n", ret); - goto delete_with_close; - } - - serial_tx_bytes = 0; - while (1) { - ret = usbh_serial_write(serial, serial_tx_buffer, sizeof(serial_tx_buffer)); - if (ret < 0) { - USB_LOG_RAW("serial write error, ret:%d\r\n", ret); - goto delete_with_close; - } else { - serial_tx_bytes += ret; - - if (serial_tx_bytes == SERIAL_TEST_LEN) { - USB_LOG_RAW("send over\r\n"); - break; - } - } - } - - volatile uint32_t wait_timeout = 0; - serial_rx_bytes = 0; - while (1) { - ret = usbh_serial_read(serial, &serial_rx_data[serial_rx_bytes], SERIAL_TEST_LEN - serial_rx_bytes); - if (ret < 0) { - USB_LOG_RAW("serial read error, ret:%d\r\n", ret); - goto delete_with_close; - } else { - serial_rx_bytes += ret; - - if (serial_rx_bytes == SERIAL_TEST_LEN) { - USB_LOG_RAW("receive over\r\n"); - for (uint32_t i = 0; i < SERIAL_TEST_LEN; i++) { - if (serial_rx_data[i] != 0xa5) { - USB_LOG_RAW("serial loopback data error at index %d, data: 0x%02x\r\n", (unsigned int)i, serial_rx_data[i]); - goto delete_with_close; - } - } - serial_test_success = true; - break; - } - } - wait_timeout++; - - if (wait_timeout > 500) { // 5s - USB_LOG_RAW("serial read timeout\r\n"); - goto delete_with_close; - } - - usb_osal_msleep(10); - } - - usbh_serial_close(serial); - -.. caution:: 需要注意，例程中使用的是比较简单的先发送后读取的方式，因此发送的总长度不可以超过 CONFIG_USBHOST_SERIAL_RX_SIZE，正常使用 TX/RX 请分开进行。 - -用户需要考虑以下三种场景： - -- USB2TTL 设备 + 启用了波特率（USB2TTL设备必须启用波特率），这种情况下需要使用 `usbh_serial_write` 和 `usbh_serial_read` 进行收发数据， **并且 read 操作需要及时，防止 ringbuf 数据溢出而丢包**。不可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async` - -- 纯 USB 设备 + 未启动波特率，这种情况下可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async` 进行异步收发数据。阻塞则可以用 `usbh_serial_write` ，不可以使用 `usbh_serial_read`。 - -- 纯 USB 设备 + 启动波特率，同 1，但是接收速率会打折扣（因为多了一层 ringbuf）。此时也不可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async`。 **如果是 GSM 设备请使用第一种场景**。 - -.. note:: 简单来说就是，如果接收数据需要用到ringbuf转一层的，请使用第一种场景。 - -.. code-block:: C - - [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected - [I/usbh_core] New device found,idVendor:10c4,idProduct:ea60,bcdDevice:0100 - [I/usbh_core] The device has 1 bNumConfigurations - [I/usbh_core] The device has 1 interfaces - [I/usbh_core] Enumeration success, start loading class driver - [I/usbh_core] Loading cp210x class driver on interface 0 - [I/usbh_cp210x] chip partnum: 0x02 - [I/usbh_cp210x] ulAmountInInQueue: 0, ulAmountInOutQueue: 0 - [I/usbh_serial] Ep=81 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Ep=01 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (cp210x) - start serial loopback test, len: 1024 - send over - receive over - serial loopback test success - [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (cp210x) - [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected - [I/usbh_hub] New high-speed device on Bus 0, Hub 1, Port 1 connected - [I/usbh_core] New device found,idVendor:0403,idProduct:6010,bcdDevice:0700 - [I/usbh_core] The device has 1 bNumConfigurations - [I/usbh_core] The device has 2 interfaces - [I/usbh_core] Enumeration success, start loading class driver - [I/usbh_core] Loading ftdi class driver on interface 0 - [I/usbh_ftdi] chip name: FT2232H - [I/usbh_serial] Ep=81 Attr=02 Mps=512 Interval=00 Mult=00 - [I/usbh_serial] Ep=02 Attr=02 Mps=512 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (ftdi) - [I/usbh_core] Loading ftdi class driver on interface 1 - [I/usbh_ftdi] chip name: FT2232H - [I/usbh_serial] Ep=83 Attr=02 Mps=512 Interval=00 Mult=00 - [I/usbh_serial] Ep=04 Attr=02 Mps=512 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyUSB1 (ftdi) - start serial loopback test, len: 1024 - send over - receive over - serial loopback test success - [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (ftdi) - [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB1 (ftdi) - [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected - [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected - [I/usbh_core] New device found,idVendor:067b,idProduct:2303,bcdDevice:0300 - [I/usbh_core] The device has 1 bNumConfigurations - [I/usbh_core] The device has 1 interfaces - [I/usbh_core] Enumeration success, start loading class driver - [I/usbh_core] Loading pl2303 class driver on interface 0 - [I/usbh_pl2303] Ep=81 Attr=03 Mps=10 Interval=01 Mult=00 - [I/usbh_pl2303] chip type: PL2303HX - [I/usbh_serial] Ep=02 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Ep=83 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (pl2303) - start serial loopback test, len: 1024 - send over - receive over - serial loopback test success - [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (pl2303) - [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected - [W/usbh_hub] Failed to enable port 1 - [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected - [I/usbh_core] New device found,idVendor:1a86,idProduct:7523,bcdDevice:0264 - [I/usbh_core] The device has 1 bNumConfigurations - [I/usbh_core] The device has 1 interfaces - [I/usbh_core] Enumeration success, start loading class driver - [I/usbh_core] Loading ch34x class driver on interface 0 - [I/usbh_ch43x] Ep=81 Attr=03 Mps=8 Interval=01 Mult=00 - [I/usbh_ch43x] chip version: 0x31 - [I/usbh_serial] Ep=82 Attr=02 Mps=32 Interval=00 Mult=00 - [I/usbh_serial] Ep=02 Attr=02 Mps=32 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyUSB0 (ch34x) - start serial loopback test, len: 1024 - send over - receive over - serial loopback test success - [I/usbh_serial] Unregister Serial Class: /dev/ttyUSB0 (ch34x) - [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected - [I/usbh_hub] New full-speed device on Bus 0, Hub 1, Port 1 connected - [I/usbh_core] New device found,idVendor:42bf,idProduct:b210,bcdDevice:0217 - [I/usbh_core] The device has 1 bNumConfigurations - [I/usbh_core] The device has 3 interfaces - [I/usbh_core] Enumeration success, start loading class driver - [E/usbh_core] Do not support Class:0xff, Subclass:0x01, Protocl:0x00 on interface 0 - [I/usbh_core] Loading cdc_acm class driver on interface 1 - [I/usbh_cdc_acm] Ep=85 Attr=03 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Ep=04 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Ep=83 Attr=02 Mps=64 Interval=00 Mult=00 - [I/usbh_serial] Register Serial Class: /dev/ttyACM0 (cdc_acm) - [I/usbh_core] Loading cdc_data class driver on interface 2 - start serial loopback test, len: 1024 - send over - receive over - serial loopback test success - [I/usbh_serial] Unregister Serial Class: /dev/ttyACM0 (cdc_acm) - [I/usbh_core] Device on Bus 0, Hub 1, Port 1 disconnected - diff --git a/docs/source/demo/usbh_vendor.rst b/docs/source/demo/usbh_vendor.rst deleted file mode 100644 index b86bda60..00000000 --- a/docs/source/demo/usbh_vendor.rst +++ /dev/null @@ -1,127 +0,0 @@ -vendor host 驱动编写 -=========================== - -本节主要介绍如何编写一个 vendor host 驱动。 - -- 首先复制一份 class/template/usbh_xxx.c 文件 - -- 定义 class 驱动并使用 CLASS_INFO_DEFINE 前缀，这样，枚举完成后，协议栈自动通过 usbd_class_find_driver 来查找对应的驱动。 - -.. code-block:: C - - static const struct usbh_class_driver xxx_class_driver = { - .driver_name = "xxx", - .connect = usbh_xxx_connect, - .disconnect = usbh_xxx_disconnect - }; - - CLASS_INFO_DEFINE const struct usbh_class_info xxx_class_info = { - .match_flags = USB_CLASS_MATCH_INTF_CLASS | USB_CLASS_MATCH_INTF_SUBCLASS | USB_CLASS_MATCH_INTF_PROTOCOL, - .bInterfaceClass = 0, - .bInterfaceSubClass = 0, - .bInterfaceProtocol = 0, - .id_table = NULL, - .class_driver = &xxx_class_driver - }; - - -- 实现 connect 和 disconnect 函数, 在 connect 函数中，需要分配一个 xxx_class 结构体，在 disconnect 函数中释放 urb 和 xxx_class。 - -.. code-block:: C - - struct usbh_xxx { - struct usbh_hubport *hport; - struct usb_endpoint_descriptor *xxxin; - struct usb_endpoint_descriptor *xxxout; - struct usbh_urb xxxin_urb; - struct usbh_urb xxxout_urb; - - uint8_t intf; /* interface number */ - uint8_t minor; - - void *user_data; - }; - - static int usbh_xxx_connect(struct usbh_hubport *hport, uint8_t intf) - { - struct usb_endpoint_descriptor *ep_desc; - int ret; - - struct usbh_xxx *xxx_class = usbh_xxx_class_alloc(); - if (xxx_class == NULL) { - USB_LOG_ERR("Fail to alloc xxx_class\r\n"); - return -USB_ERR_NOMEM; - } - - return ret; - } - - - static int usbh_xxx_disconnect(struct usbh_hubport *hport, uint8_t intf) - { - int ret = 0; - - struct usbh_xxx *xxx_class = (struct usbh_xxx *)hport->config.intf[intf].priv; - - if (xxx_class) { - if (xxx_class->xxxin) { - usbh_kill_urb(&xxx_class->xxxin_urb); - } - - if (xxx_class->xxxout) { - usbh_kill_urb(&xxx_class->xxxout_urb); - } - - if (hport->config.intf[intf].devname[0] != '\0') { - USB_LOG_INFO("Unregister xxx Class:%s\r\n", hport->config.intf[intf].devname); - usbh_xxx_stop(xxx_class); - } - - usbh_xxx_class_free(xxx_class); - } - - return ret; - } - -- 初始化端点 - -.. code-block:: C - - for (uint8_t i = 0; i < hport->config.intf[intf].altsetting[0].intf_desc.bNumEndpoints; i++) { - ep_desc = &hport->config.intf[intf].altsetting[0].ep[i].ep_desc; - if (ep_desc->bEndpointAddress & 0x80) { - USBH_EP_INIT(xxx_class->intin, ep_desc); - } else { - USBH_EP_INIT(xxx_class->intout, ep_desc); - } - } - -- 最后设计收发 API，根据实际情况设计成同步 or 异步。 - -.. code-block:: C - - int usbh_xxx_in_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout) - { - int ret; - struct usbh_urb *urb = &xxx_class->xxxin_urb; - - usbh_xxx_urb_fill(urb, xxx_class->hport, xxx_class->xxxin, buffer, buflen, timeout, NULL, NULL); - ret = usbh_submit_urb(urb); - if (ret == 0) { - ret = urb->actual_length; - } - return ret; - } - - int usbh_xxx_out_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout) - { - int ret; - struct usbh_urb *urb = &xxx_class->xxxout_urb; - - usbh_xxx_urb_fill(urb, xxx_class->hport, xxx_class->xxxout, buffer, buflen, timeout, NULL, NULL); - ret = usbh_submit_urb(urb); - if (ret == 0) { - ret = urb->actual_length; - } - return ret; - } \ No newline at end of file diff --git a/docs/source/demo/usbh_wifi.rst b/docs/source/demo/usbh_wifi.rst deleted file mode 100644 index be148c7d..00000000 --- a/docs/source/demo/usbh_wifi.rst +++ /dev/null @@ -1,2 +0,0 @@ -usbh_wifi -=============== diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 831de0a1..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. CherryUSB 使用指南 documentation master file, created by - sphinx-quickstart on Thu Nov 21 10:50:33 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -CherryUSB 使用指南 -====================================================== - -CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 USB 主从协议栈。同时 CherryUSB 具有以下优点： - -**易于学习 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 - -**其他相关链接** - -- **视频教程**： 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 - :caption: 快速上手 - - quick_start/start - quick_start/demo - quick_start/transplant - quick_start/rtthread - quick_start/q&a - quick_start/migration - quick_start/share - quick_start/opensource - -.. toctree:: - :maxdepth: 1 - :caption: USB 基本知识点 - - usb/usb2.0_basic - usb/usb3.0_basic - usb/usb_desc - usb/usb_request - usb/usb_enum - usb/usb_ext - -.. toctree:: - :maxdepth: 1 - :caption: API 手册 - - api/api_device - api/api_host - api/api_port - api/api_config - -.. toctree:: - :maxdepth: 1 - :caption: Class 指南 - - class/class_cdc - class/class_hid - class/class_msc - class/class_audio - class/class_video - class/winusb - -.. toctree:: - :maxdepth: 1 - :caption: 例程说明 - - demo/usbd_cdc_acm - demo/usbd_hid - demo/usbd_msc - demo/usbd_rndis - demo/usbd_ecm - demo/usbd_audiov1 - demo/usbd_audiov2 - demo/usbd_video - demo/usbd_winusb - demo/usbd_webusb - demo/usbd_adb - demo/usbh_serial - demo/usbh_hid - demo/usbh_msc - demo/usbh_net - demo/usbh_bluetooth - demo/usbh_wifi - demo/usbd_vendor - demo/usbh_vendor - demo/usb_otg - -.. toctree:: - :maxdepth: 1 - :caption: USBIP 介绍 - - usbip/ohci - usbip/ehci - usbip/xhci - usbip/chipidea - usbip/dwc2 - usbip/musb - usbip/fotg210 - usbip/cdns2 - usbip/cdns3 - usbip/dwc3 - -.. toctree:: - :maxdepth: 1 - :caption: 工具使用 - - tools/index - -.. toctree:: - :maxdepth: 1 - :caption: 版本说明 - - version - -.. toctree:: - :maxdepth: 1 - :caption: 性能展示 - - show/index - -.. toctree:: - :maxdepth: 1 - :caption: 商业支持 - - support/index \ No newline at end of file diff --git a/docs/source/quick_start/demo.rst b/docs/source/quick_start/demo.rst deleted file mode 100644 index e51a2e3e..00000000 --- a/docs/source/quick_start/demo.rst +++ /dev/null @@ -1,224 +0,0 @@ -基于现有 demo 快速验证 -========================= - -在学习 USB 或者是学习 CherryUSB 代码之前，我们需要先基于现有的 demo 进行快速验证，为什么？是为了提升对 USB 的兴趣，能有信心进行下一步的动作，如果 demo 都跑不起来，或者自己摸索写代码，或者先看 USB 基本概念，结果看到最后， -发现一点都看不懂，概念好多，根本记不住，从而丧失对 USB 的兴趣。因此，先跑 demo 非常重要。下面我将给大家罗列目前支持的 demo 仓库。 - -基于 bouffalolab 系列芯片（官方 SDK 支持） ------------------------------------------- - -仓库参考：https://github.com/CherryUSB/cherryusb_bouffalolab - -- BL616/BL808：USB2.0 内置 HS phy 芯片，支持主从机。device 支持 5 个端点（包括端点0），不支持双向同时使用。 -- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 - -基于 HPMicro 系列芯片（官方 SDK 支持） ------------------------------------------------------ - -仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro - -- HPM 系列: USB2.0 内置 HS phy 芯片，支持主从机。device 支持 8/16 端点（包括端点0），并且可以同时使用双向，不同芯片个数有差异。 -- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。 - -基于 esp32s2/s3/p4 系列芯片（官方 SDK 即将支持） -------------------------------------------------- - -仓库参考：https://github.com/CherryUSB/cherryusb_esp32 - -- esp32s2/s3：USB2.0 内置全速 PHY 芯片，支持主从机，device 支持 7 个端点（包括端点0），并且可以同时使用双向。 -- 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 支持） ------------------------------------ - -仓库参考：https://gitee.com/phytium_embedded/phytium-free-rtos-sdk - -- 飞腾派支持两个 USB3.0 主机（采用 XHCI）， 两个 USB2.0 主从机 -- USB 的相关应用位于 `example/peripheral/usb` ，根据官方环境搭建完成后，即可编译使用。 - -基于 Essemi 系列芯片（官方 SDK 支持） ------------------------------------------ - -仓库参考：https://github.com/CherryUSB/cherryusb_es32 - -- 支持全速和高速主从机。device 支持 6 个端点（包括端点0），并且可以同时使用双向。 - -基于 Artinchip 系列芯片（官方 SDK 支持） ------------------------------------------------ - -仓库参考：https://gitee.com/artinchip/luban-lite - -- 支持全速和高速主从机，主机采用 EHCI + OHCI。device 支持 8 个端点（包括端点0），并且可以同时使用双向。 - -基于 canmv-k230 芯片（官方 SDK 支持） ---------------------------------------------- - -仓库参考：https://github.com/CherryUSB/k230_sdk - -- K230: 两个 USB2.0 内置 HS PHY 芯片，支持主从机。device 支持 16 个端点（包括端点0），并且可以同时使用双向。 - -基于 NXP MCX系列芯片 ---------------------------- - -仓库参考：https://github.com/CherryUSB/cherryusb_mcx 或者 https://github.com/RT-Thread/rt-thread/tree/master/bsp/nxp/mcx - -- 支持全速 IP 和高速 IP， 高速 IP 支持主机和从机。device 支持 8 个端点（包括端点0），并且可以同时使用双向。 - -基于 RP2040/RP2035 芯片（官方 SDK 即将支持） --------------------------------------------- - -仓库参考： https://github.com/CherryUSB/pico-examples 和 https://github.com/CherryUSB/pico-sdk - -基于 ST 系列芯片 ---------------------------- - -仓库参考：https://github.com/CherryUSB/cherryusb_stm32 - -默认提供以下 demo 工程： - -- F103 使用 fsdev ip -- F429 主从使用 USB1, 引脚 pb14/pb15, 默认从机没有开启 DMA 模式 -- H7 设备使用 USB0, 引脚 pa11/pa12，没有开 DMA 模式。主机使用 USB1 ,引脚 pb14/pb15，并且需要做 nocache 处理 - -demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。 - -.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。 - -涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有： - -- usb ip 区别：F1使用 fsdev，F4/H7使用 dwc2 -- dwc2 ip 区别： USB0 (引脚是 PA11/PA12) 和 USB1 (引脚是 PB14/PB15), 其中 USB1 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能 -- F4 无 cache，H7 有 cache - -如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下 - -.. code-block:: C - - cpu_mpu_config(0, MPU_Normal_NonCache, 0x24070000, MPU_REGION_SIZE_64KB); - -对应 keil 中的 sct 脚本修改： - -.. code-block:: C - - LR_IROM1 0x08000000 0x00200000 { ; load region size_region - ER_IROM1 0x08000000 0x00200000 { ; load address = execution address - *.o (RESET, +First) - *(InRoot$$Sections) - .ANY (+RO) - .ANY (+XO) - } - RW_IRAM2 0x24000000 0x00070000 { ; RW data - .ANY (+RW +ZI) - } - USB_NOCACHERAM 0x24070000 0x00010000 { ; RW data - *(.noncacheable) - } - } - -USB Device 移植要点 -^^^^^^^^^^^^^^^^^^^^^^ - -- 使用 **stm32cubemx** 创建工程，配置基本的 RCC、UART (作为log使用) - -.. figure:: img/stm32_1.png -.. figure:: img/stm32_2.png - -- 如果使用 fsdev ip，勾选 **USB** 。如果使用 dwc2 ip，勾选 **USB_OTG_FS** 或者勾选 **USB_OTG_HS**。开启 USB 中断，其他配置对我们没用，代码中不会使用任何 st 的 usb 库。 - -.. figure:: img/stm32_3_1.png -.. figure:: img/stm32_3_2.png - -- 配置 usb clock 为 48M - -.. figure:: img/stm32_4_1.png -.. figure:: img/stm32_4_2.png - -- 选择好工程，这里我们选择 keil，设置好 stack 和 heap，如果使用 msc 可以推荐设置大点，然后点击 **Generate Code**。 - -.. figure:: img/stm32_5.png - -- 添加 CherryUSB 必须要的源码（ **usbd_core.c** 、 **dwc2/usb_dc_dwc2.c** 或者是 **fsdev/usb_dc_fsdev.c** ）,以及想要使用的 class 驱动，可以将对应的 class template 添加方便测试。 - -.. figure:: img/stm32_6.png - -- 头文件该加的加 - -.. figure:: img/stm32_7.png - -- 复制一份 **cherryusb_config_template.h**，放到 `Core/Inc` 目录下，并命名为 `usb_config.h` - -.. figure:: img/stm32_8.png - -- 如果使用 fsdev ip，（V1.5.0 开始需要增加 **fsdev/usb_glue_st.c**） 在 `usb_config.h` 中实现以下宏,具体数值不同芯片不一样： - -.. code-block:: C - - #define CONFIG_USBDEV_FSDEV_PMA_ACCESS 2 - -- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 - -.. figure:: img/stm32_10.png -.. figure:: img/stm32_11.png - -.. note :: 以下两个步骤从 V1.5.0 开始不再需要，**fsdev/usb_glue_st.c**, **dwc2/usb_glue_st.c** 文件中已经实现 - -- 拷贝 **xxx_msp.c** 中的 **HAL_PCD_MspInit** 函数中的内容到 **usb_dc_low_level_init** 函数中，屏蔽 st 生成的 usb 初始化 - -.. figure:: img/stm32_12.png -.. figure:: img/stm32_14.png - -- 在中断函数中调用 `USBD_IRQHandler`，并传入 `busid` - -.. figure:: img/stm32_13.png - -- 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 - -- 调用 template 的内容初始化，并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBDEV_MAX_BUS` - -.. figure:: img/stm32_15.png - -USB Host 移植要点 -^^^^^^^^^^^^^^^^^^^^^^ - -前面 6 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port (引脚是 PB14/PB15)，所以 fs port (引脚是 PA11/PA12)不做支持（没有 dma 你玩什么主机）。 - -- 添加 CherryUSB 必须要的源码（ **usbh_core.c** 、 **usbh_hub.c** 、 **usb_hc_dwc2.c** 、 **usb_glue_st.c** 以及 **osal** 目录下的适配层文件）,以及想要使用的 class 驱动，并且可以将对应的 **usb host.c** 添加方便测试。 - -.. figure:: img/stm32_16.png - -- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。 - -.. figure:: img/stm32_10.png -.. figure:: img/stm32_11.png - -- 复制一份 **cherryusb_config_template.h**，放到 `Core/Inc` 目录下，并命名为 `usb_config.h` - -.. note :: 以下两个步骤从 V1.5.0 开始不再需要，**fsdev/usb_glue_st.c**, **dwc2/usb_glue_st.c** 文件中已经实现 - -- 拷贝 **xxx_msp.c** 中的 `HAL_HCD_MspInit` 函数中的内容到 `usb_hc_low_level_init` 函数中，屏蔽 st 生成的 usb 初始化 -- 在中断函数中调用 `USBH_IRQHandler`，并传入 `busid` - -.. figure:: img/stm32_19.png - -- 链接脚本修改参考 :ref:`usbh_link_script` 章节 -- 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 -- 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base` 还有 `event_handler` 可缺省为NULL， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` -- 启动线程 - -.. figure:: img/stm32_18.png diff --git a/docs/source/quick_start/img/env0.png b/docs/source/quick_start/img/env0.png deleted file mode 100644 index c0a8b03f..00000000 Binary files a/docs/source/quick_start/img/env0.png and /dev/null differ diff --git a/docs/source/quick_start/img/env1.png b/docs/source/quick_start/img/env1.png deleted file mode 100644 index 2a68e052..00000000 Binary files a/docs/source/quick_start/img/env1.png and /dev/null differ diff --git a/docs/source/quick_start/img/env2.png b/docs/source/quick_start/img/env2.png deleted file mode 100644 index ee37101a..00000000 Binary files a/docs/source/quick_start/img/env2.png and /dev/null differ diff --git a/docs/source/quick_start/img/esp1.png b/docs/source/quick_start/img/esp1.png deleted file mode 100644 index 1f059e71..00000000 Binary files a/docs/source/quick_start/img/esp1.png and /dev/null differ diff --git a/docs/source/quick_start/img/esp2.png b/docs/source/quick_start/img/esp2.png deleted file mode 100644 index fd20e9ce..00000000 Binary files a/docs/source/quick_start/img/esp2.png and /dev/null differ diff --git a/docs/source/quick_start/img/esp3.png b/docs/source/quick_start/img/esp3.png deleted file mode 100644 index 82a7162f..00000000 Binary files a/docs/source/quick_start/img/esp3.png and /dev/null differ diff --git a/docs/source/quick_start/img/esp4.png b/docs/source/quick_start/img/esp4.png deleted file mode 100644 index ffb2882a..00000000 Binary files a/docs/source/quick_start/img/esp4.png and /dev/null differ diff --git a/docs/source/quick_start/img/question1.png b/docs/source/quick_start/img/question1.png deleted file mode 100644 index a852e6aa..00000000 Binary files a/docs/source/quick_start/img/question1.png and /dev/null differ diff --git a/docs/source/quick_start/img/question2.png b/docs/source/quick_start/img/question2.png deleted file mode 100644 index e00b3bfa..00000000 Binary files a/docs/source/quick_start/img/question2.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_1.png b/docs/source/quick_start/img/stm32_1.png deleted file mode 100644 index b91044a5..00000000 Binary files a/docs/source/quick_start/img/stm32_1.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_10.png b/docs/source/quick_start/img/stm32_10.png deleted file mode 100644 index d55b38e7..00000000 Binary files a/docs/source/quick_start/img/stm32_10.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_11.png b/docs/source/quick_start/img/stm32_11.png deleted file mode 100644 index 3ad5b074..00000000 Binary files a/docs/source/quick_start/img/stm32_11.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_12.png b/docs/source/quick_start/img/stm32_12.png deleted file mode 100644 index 84aaffe8..00000000 Binary files a/docs/source/quick_start/img/stm32_12.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_13.png b/docs/source/quick_start/img/stm32_13.png deleted file mode 100644 index f12fad75..00000000 Binary files a/docs/source/quick_start/img/stm32_13.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_14.png b/docs/source/quick_start/img/stm32_14.png deleted file mode 100644 index e5aa5b19..00000000 Binary files a/docs/source/quick_start/img/stm32_14.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_15.png b/docs/source/quick_start/img/stm32_15.png deleted file mode 100644 index 7c293287..00000000 Binary files a/docs/source/quick_start/img/stm32_15.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_16.png b/docs/source/quick_start/img/stm32_16.png deleted file mode 100644 index 70f2e63c..00000000 Binary files a/docs/source/quick_start/img/stm32_16.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_18.png b/docs/source/quick_start/img/stm32_18.png deleted file mode 100644 index 456df189..00000000 Binary files a/docs/source/quick_start/img/stm32_18.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_19.png b/docs/source/quick_start/img/stm32_19.png deleted file mode 100644 index a796dc75..00000000 Binary files a/docs/source/quick_start/img/stm32_19.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_2.png b/docs/source/quick_start/img/stm32_2.png deleted file mode 100644 index 671b1b82..00000000 Binary files a/docs/source/quick_start/img/stm32_2.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_3_1.png b/docs/source/quick_start/img/stm32_3_1.png deleted file mode 100644 index 9e42196d..00000000 Binary files a/docs/source/quick_start/img/stm32_3_1.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_3_2.png b/docs/source/quick_start/img/stm32_3_2.png deleted file mode 100644 index 492d6739..00000000 Binary files a/docs/source/quick_start/img/stm32_3_2.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_4_1.png b/docs/source/quick_start/img/stm32_4_1.png deleted file mode 100644 index e81437bc..00000000 Binary files a/docs/source/quick_start/img/stm32_4_1.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_4_2.png b/docs/source/quick_start/img/stm32_4_2.png deleted file mode 100644 index dd90f5b8..00000000 Binary files a/docs/source/quick_start/img/stm32_4_2.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_5.png b/docs/source/quick_start/img/stm32_5.png deleted file mode 100644 index 5bec9878..00000000 Binary files a/docs/source/quick_start/img/stm32_5.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_6.png b/docs/source/quick_start/img/stm32_6.png deleted file mode 100644 index f0ad9a0b..00000000 Binary files a/docs/source/quick_start/img/stm32_6.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_7.png b/docs/source/quick_start/img/stm32_7.png deleted file mode 100644 index 8aef0bfa..00000000 Binary files a/docs/source/quick_start/img/stm32_7.png and /dev/null differ diff --git a/docs/source/quick_start/img/stm32_8.png b/docs/source/quick_start/img/stm32_8.png deleted file mode 100644 index 08d2e724..00000000 Binary files a/docs/source/quick_start/img/stm32_8.png and /dev/null differ diff --git a/docs/source/quick_start/migration.rst b/docs/source/quick_start/migration.rst deleted file mode 100644 index 10f2ef7e..00000000 --- a/docs/source/quick_start/migration.rst +++ /dev/null @@ -1,63 +0,0 @@ -部分改动迁移指南 -======================== - - -usbh_initialize ------------------- - -usbh_initialize 从 v1.6.0 开始新增 event_handler 参数，通常不需要使用，可以传入 NULL。 - -dwc2 glue st ----------------- - -dwc2 从 v1.5.0 开始 glue 文件内置底层初始化，比如 `usb_dc_low_level_init`，底层依赖 `HAL_PCD_MspInit` 和 `HAL_HCD_MspInit`，必须使用 stm32cubemx 生成。第三方平台不保证有这些函数实现，自行检查。 - - -dwc2 glue ----------------- - -dwc2 从 v1.5.1 开始新增 `struct dwc2_user_params`，用于实现多 dwc2 port 不同配置。并替代 `usbd_get_dwc2_gccfg_conf` 和 `usbh_get_dwc2_hccfg_conf` 函数， -并增加 `dwc2_get_user_params` 函数实现，举例如下： - -.. code-block:: C - - #ifndef CONFIG_USB_DWC2_CUSTOM_PARAM - void dwc2_get_user_params(uint32_t reg_base, struct dwc2_user_params *params) - { - memcpy(params, ¶m_common, sizeof(struct dwc2_user_params)); - #ifdef CONFIG_USB_DWC2_CUSTOM_FIFO - struct usb_dwc2_user_fifo_config s_dwc2_fifo_config; - - dwc2_get_user_fifo_config(reg_base, &s_dwc2_fifo_config); - - params->device_rx_fifo_size = s_dwc2_fifo_config.device_rx_fifo_size; - for (uint8_t i = 0; i < MAX_EPS_CHANNELS; i++) { - params->device_tx_fifo_size[i] = s_dwc2_fifo_config.device_tx_fifo_size[i]; - } - #endif - } - #endif - -host serial ----------------- - -从 v1.6.0 开始，主机增加 host serial 框架，用于统一所有类串口设备。以下 API 需要使用新 serial API 替换： - -.. code-block:: C - - int usbh_xxx_set_line_coding(struct usbh_xxx *xxx_class, struct cdc_line_coding *line_coding); - int usbh_xxx_get_line_coding(struct usbh_xxx *xxx_class, struct cdc_line_coding *line_coding); - int usbh_xxx_set_line_state(struct usbh_xxx *xxx_class, bool dtr, bool rts); - - int usbh_xxx_bulk_in_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout); - int usbh_xxx_bulk_out_transfer(struct usbh_xxx *xxx_class, uint8_t *buffer, uint32_t buflen, uint32_t timeout); - -替换为： - -.. code-block:: C - - struct usbh_serial *usbh_serial_open(const char *devname, uint32_t open_flags); - int usbh_serial_close(struct usbh_serial *serial); - int usbh_serial_control(struct usbh_serial *serial, int cmd, void *arg); - int usbh_serial_write(struct usbh_serial *serial, const void *buffer, uint32_t buflen); - int usbh_serial_read(struct usbh_serial *serial, void *buffer, uint32_t buflen); diff --git a/docs/source/quick_start/opensource.rst b/docs/source/quick_start/opensource.rst deleted file mode 100644 index 7990538e..00000000 --- a/docs/source/quick_start/opensource.rst +++ /dev/null @@ -1,62 +0,0 @@ -官方开源项目分享 -==================== - -除了基本的厂家 SDK 支持以外，我们还对一些火热的开源项目进行了支持，以便于开发者更好的使用这些项目。下面列举适配的 demo 工程链接，具体适配层参考 https://github.com/cherry-embedded/CherryUSB/tree/master/platform 。 - -DAPLINK --------------- - -适配链接：https://github.com/cherry-embedded/CherryDAP - -Blackmagic --------------- - -适配链接：https://github.com/zhangjiance/bmp-hpm-port - -RT-Thread --------------- - -适配链接：https://github.com/RT-Thread/rt-thread - -NUTTX/VELA --------------- - -适配链接：https://github.com/CherryUSB/cherryusb_nuttx - -Zephyr --------------- - -适配链接：https://github.com/hpmicro/zephyr_sdk_glue - -Cangaroo --------------- - -Cangaroo is an open source can bus analyzer software. We provide four-channel CANFD analyzer based on hpmicro hpm5361 - -适配上位机链接：https://github.com/RCSN/cangaroo_hpmicro_canfd_analyzer -适配下位机链接：https://github.com/RCSN/hpm_sdk_extra/tree/main/demos/cangaroo_hpmicro - -LVGL --------------- - -适配链接：https://github.com/cherry-embedded/CherryUSB/tree/master/platform/lvgl - -QMK --------------- - -QMK is an open-source keyboard firmware for Atmel AVR and Arm USB families. - -适配链接：待开放 - -Klipper --------------- - -Klipper is a 3d-printer firmware. - -适配链接：待开放 - - -MAKCU/KMBOX --------------- - -懂的都懂，不开放 \ No newline at end of file diff --git a/docs/source/quick_start/q&a.rst b/docs/source/quick_start/q&a.rst deleted file mode 100644 index 391b7037..00000000 --- a/docs/source/quick_start/q&a.rst +++ /dev/null @@ -1,137 +0,0 @@ -Q & A -============================== - -移植提问模板 ----------------- - -请在下列途径提交问题： -- RT-Thread 官方论坛: https://club.rt-thread.org/ask/tag/5f5f851966917b14.html -- Github issue: https://github.com/cherry-embedded/CherryUSB/issues/new/choose - -提问中请包含以下信息： - -- 使用的版本 -- 使用的板子，引脚，USB IP -- 是否配置 USB 中断，USB 时钟，USB 引脚，USB phy 配置，以及 USB 寄存器地址是否正确，截图 -- 是否能进 USB 中断 -- 芯片是否带有 cache功能，是否做了 no cache 处理，截图 -- USB 电路是否画正确，是否使用杜邦线连接，是否直连，如果正常，请说明正常原因 -- 如果能进中断，配置 **#define CONFIG_USB_DBG_LEVEL USB_DBG_LOG** 并提供 log，仅限商业 IP, 其余 IP 禁止开启 log，否则无法枚举 -- 是否流片并销售 - -其余问题提问模板 ------------------- - -具体说明现象，复现方式，使用我提供的 demo 再测试，以及提供完整 log - -CherryUSB 性能能到多少 ----------------------------------------------------------------- - -参考 :ref:`performace_show` - -ST IP 命名问题 ------------------- - -ST 命名为 USB_OTG_FS, USB_OTG_HS，并不是说明本身是高速或者全速，只是代表可以支持到高速，但是本身都是全速，需要外挂高速phy。因此，提问禁止说这两个词，请使用 USB0(PA11/PA12),USB1(PB14/PB15) 代替。其余国产厂家同理。 - -GD IP 问题 ------------------- - -GD IP 采用 DWC2，但是读取的硬件参数都是 0（我也不懂为什么不给人知道），因此需要用户自行知道硬件信息，从 1.5.0 开始由于需要读取硬件信息，因此无法直接使用。 - -其次 GD 复位以后无法使用 EPDIS 功能关闭端点，需要用户删除 reset 中断中的以下代码： - -.. code-block:: C - - 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 ------------------------------- - -.. 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 模式，禁止使用。不使用 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 报错 ------------------------------------------------------------------- -如果报错，需要编译器支持 c99 语法，如果是 keil，请用 ac6 编译器 - -CONFIG_USB_HS 何时使用 ----------------------------------------------------------------- - -当你的芯片硬件支持高速，并想初始化成高速模式时开启，相关 IP 会根据该宏配置内部或者外部 高速 PHY。 - -Failed to enable port ----------------------------------------------------------------- - -供电不足或者硬件 USB 电路问题 - -移植 usb host 出现 urb 返回 -12/-14 ----------------------------------------------------------------- - -检查 phy 配置，cache 配置（如果有），电源供电（建议自供电） - -USB_ERR_NAK 说明 ----------------------------------------------------------------- - -USB_ERR_NAK 只存在于 DWC2 buffer dma/slave 模式(我们不使用 slave 模式)，DWC2 在 buffer dma模式下对于中断传输不支持硬件处理 NAK 中断，因此需要软件处理，导致 NAK 中断非常多，建议搭配定时器使用。 -DWC2 scatter/gather dma 模式下全部由硬件处理，但是不支持 split 传输。总结， **食之无味，弃之可惜**。 - -USB host 连接 USB 网卡问题 ----------------------------------------------------------------- - -表现为能识别网卡并且分配到 IP 地址，但是无法 ping 通，这是因为网卡自身需要开启自动拨号，通常需要使用 AT 口设置。具体为 EC20/ML307 等模块。 - - -什么时候需要开启 CONFIG_USB_DCACHE_ENABLE -------------------------------------------------- - -当芯片带有 cache 功能，并且没有使用 no cache ram 时需要开启此宏以保证数据一致性。 **使用 EHCI 时，内部依旧需要使用 nocache ram**。通常，对于第三方平台或者组件，没有使用 no cache ram 宏修饰，都是使用全局变量或者 malloc 等 -操作，这部分 RAM 通常是走 cache 的，因此需要开启此宏。建议第三方平台使用时，必须开启。 - -哪些 IP 对数据有对齐要求 -------------------------------------------------- - -- 在未开启 CONFIG_USB_DCACHE_ENABLE 时，仅 DWC2/WCH/AIC IP 需要 4字节对齐，其余 1字节对齐即可。 -- 在开启 CONFIG_USB_DCACHE_ENABLE 时，所有 IP 都需要对齐到 CONFIG_USB_ALIGN_SIZE 字节 \ No newline at end of file diff --git a/docs/source/quick_start/rtthread.rst b/docs/source/quick_start/rtthread.rst deleted file mode 100644 index 132015d9..00000000 --- a/docs/source/quick_start/rtthread.rst +++ /dev/null @@ -1,62 +0,0 @@ -基于 RT-Thread 软件包开发指南 -=============================== - -.. note:: CherryUSB 已经加入 RT-Thread 主线，可以选择使用主线版本，配置方式相同。 - -本节主要介绍使用 RT-Thread 提供的软件包管理器来配置工程，以 env 作为演示。本节操作不同芯片都一样，后续不再重复讲解。打开 env 以后使用 menuconfig 进入包管理器，并在如图所示路径中选择 CherryUSB。 - -.. figure:: img/env0.png - -从机配置 --------------------------- - -* 选择 Enable usb device mode 并敲回车进入。 -* 首先第一个配置是配置 USB 的速度，分为 **FS、HS**，表示使用全速还是高速功能。高速功能要求内置高速 PHY 或者外接 PHY -* 其次第二个配置则是选择 USB device ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme。 -* 选择你想使用的 class -* 选择是否使用 demo 模板 - -.. figure:: img/env1.png - -* 最后退出保存即可。 -* 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径,并修改以下内容： - -.. code-block:: C - - #include "rtthread.h" - - #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__) - -* USB IP 相关的 config 需要用户自己根据芯片实际情况修改 -* 在代码中实现 `usb_dc_low_level_init` 函数 -* 在 USB 中断函数中调用 `USBD_IRQHandler`，并传入 `busid` -* 调用 `usbd_initialize` 并填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBDEV_MAX_BUS` -* 使用 `scons --target=mdk5` 或者 `scons` 进行编译，如果是mdk，需要使用 AC6 编译器 -* 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 - -主机配置 --------------------------- - -* 选择 Enable usb host mode 并敲回车进入 -* 选择 USB host ip，不清楚自己芯片是哪个 ip 的可以参考 **port** 目录下对应的 readme -* 根据需要勾选 class 驱动 -* 选择是否开启模板 demo，推荐不用 - -.. figure:: img/env2.png - -* 最后退出保存即可。 -* 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径,并实现以下内容： - -.. code-block:: C - - #include "rtthread.h" - - #define CONFIG_USB_PRINTF(...) rt_kprintf(__VA_ARGS__) - -* USB IP 相关的 config 需要用户自己根据芯片实际情况修改 -* 在代码中实现 `usb_hc_low_level_init` 函数 -* 在 USB 中断函数中调用 `USBH_IRQHandler`，并传入 `busid` -* 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base` 还有 `event_handler` 可缺省为NULL， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` -* 使用 `scons --target=mdk5` 或者 `scons` 进行编译，如果是mdk，需要使用 AC6 编译器 -* 链接脚本修改参考 :ref:`usbh_link_script` 章节 -* 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 diff --git a/docs/source/quick_start/share.rst b/docs/source/quick_start/share.rst deleted file mode 100644 index a57a8e1e..00000000 --- a/docs/source/quick_start/share.rst +++ /dev/null @@ -1,27 +0,0 @@ -开发者经验/开源项目分享 -======================== - -- `RT-Thread-CherryUSB - RT-Thread `_ - -- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb？ `_ - -- `RT-Thread-CherryUSB移植笔记(一)：APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread `_ - -- `华大HC32F460XXX移植cherryusb协议栈，实现USB CDC ACM_cherryusb移植教程-CSDN博客 `_ - -- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 `_ - -- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ - -- `模仿stm32标准库风格写的库文件（f1c100s/f1c200s)，且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) `_ - -- `printalyzer-timer: F-Stop enlarging timer and print exposure meter `_ - -- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA `_ - -- `Cherryuf2 `_ - -- `PicoPiFi: Driverless RNDIS USB WIFI Dongle `_ - -- `phobia: Phobia Motor Controller `_ - diff --git a/docs/source/quick_start/start.rst b/docs/source/quick_start/start.rst deleted file mode 100644 index c6223b61..00000000 --- a/docs/source/quick_start/start.rst +++ /dev/null @@ -1,53 +0,0 @@ -入门必看 -================== - -首先欢迎大家来到 usb 的世界，在这里你可以学习到 usb 各种知识以及 cherryusb 的移植使用进阶等等。但是呢，刚进来的你，一定很懵懂，因为 USB 很难（其实当你学会了 cherryusb以后，你会发现，USB 一点都不难）， -那么这种情况下，你的学习路线，应该是怎么样呢？在这里，我推荐大家是按照我得学习路线来学习，这样对你的 USB 成长是最有帮助的，并且你也不会中途放弃。 - -首先，不允许上来就看概念，有句古诗说的好， **纸上得来终觉浅，绝知此事要躬行** ，光看纸面上的东西，你是学不到什么的，只有当自己实践了，你才能更深入的了解这些概念。那么作为初学者，你应该怎么做呢？请看以下步骤。 - - -第一步 -------------- - -你需要学过 C 语言，UART, DMA，这是基础，如果没学过，请去学习，不然你会很吃力。你会问 USB 跟 UART/DMA 有什么关系？ 我只能说两个字， **等价** - -第二步 -------------- - -下载 demo 工程并跑通能运行， **建议学习慢的，使用 demo 同型号芯片**，学习快的，可以选择自己移植相关支持的型号的芯片。你连 demo 都跑不通，你学什么 USB，你说对不对？ - -第三步 ---------- - -非常好，到这步，说明你已经能熟练移植和跑通所有示例了，那么接下来，你应该学习什么呢？ **事务**， **请求** 和 **描述符** （在 USB 的学习过程中，你只需要知道这三个，其余都不需要知道）。 - -第四步 ----------- - -首先我们需要知道 USB 事务包含 SETUP/IN/OUT，其实就是等价于发送命令，发送数据和接收数据，很简单。至于下面枚举中你在外面的网络中所听到的控制阶段，数据阶段，状态阶段，他不是事务，他只是用多个事务代表了一个阶段而已。 - -第五步 ----------- - -然后你再去看 **USB 枚举** 章节并且知道了一个概念： **描述符** ，这个时候，你就可以去简单看看什么是描述符，有哪些描述符，然后你需要记住， **设备、配置、接口、端点描述符的组成**，并背下来，其余的你都不需要知道，因为其他都是固定的，后续都是 CV 。群文件有各类设备枚举的抓包，可以下下来看看。 - -第六步 ----------- - -然后呢，你可以再去看看什么是 **请求** ，请求结构体的组成，看看有哪些请求，简单了解即可，为什么呢？因为它不过就是 8 字节的数据格式，大家都会写一个 UART + 自定义协议，那么 USB 的请求也是一样的，只不过是规定好了而已。 - -第七步 ----------- - -这个时候，你该去熟悉下协议栈的一些 API 了，参考 **API 手册** 章节。并且你需要知道中断完成的条件是什么，什么时候算接收完成，什么时候算发送完成，可以参考 **USB 知识点拓展** 章节。 - -第八步 ----------- - -到这步呢，你肯定已经非常懂了，然后就可以开始你的一些小功能小项目了，在此期间呢，请循环查看 **USB 知识点拓展** 章节，直到你真的理解了，因为这些内容是非常重要的，会影响我们代码的执行结果。 - -第九步 ----------- - -都到这步了，你应该不需要我了，这个时候，你可以去看看 USB 概念，看看 USB 的一些细节，看看 CherryUSB 的代码流程了。然后就是巩固巩固再巩固了。恭喜你，出师了！！！ diff --git a/docs/source/quick_start/transplant.rst b/docs/source/quick_start/transplant.rst deleted file mode 100644 index 710497d4..00000000 --- a/docs/source/quick_start/transplant.rst +++ /dev/null @@ -1,137 +0,0 @@ -芯片通用移植指南 -========================= - -本节主要介绍所有带 USB IP 的芯片，移植 CherryUSB 主从协议栈时的通用步骤和注意事项。在移植之前，需要 **你准备好一个可以打印 helloworld 的基本工程** ，默认打印使用 `printf`, 如果是主机模式， **则需要准备好可以正常执行 os 调度的基本工程**。 - -USB Device 移植要点 ------------------------ - -- 拷贝 CherryUSB 源码到工程目录下，并按需添加源文件和头文件路径，头文件路径建议全部添加。其中 `usbd_core.c` 和 `usb_dc_xxx.c` 为必须添加项。而 `usb_dc_xxx.c` 是芯片所对应的 USB IP dcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 -- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径 -- 实现 `usb_dc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 -- 在中断函数中调用 `USBD_IRQHandler`，并传入 `busid`, 如果你的 SDK 中中断入口已经存在 `USBD_IRQHandler` ，请更改 USB 协议栈中的名称 -- 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 -- 注册描述符并调用 `usbd_initialize`，填入 `busid` 和 USB IP 的 `reg base`， `busid` 从 0 开始，不能超过 `CONFIG_USBDEV_MAX_BUS`，可以直接使用 demo 下的 template - -USB Host 移植要点 ------------------------ - -- 拷贝 CherryUSB 源码到工程目录下，并按需添加源文件和头文件路径，头文件路径建议全部添加。其中 `usbh_core.c` 、 `usb_hc_xxx.c` 以及 **osal** 目录下源文件（根据不同的 os 选择对应的源文件）为必须添加项。而 `usb_hc_xxx.c` 是芯片所对应的 USB IP hcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 -- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径 -- 实现 `usb_hc_low_level_init` 函数（该函数主要负责 USB 时钟、引脚、中断的初始化）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 -- 调用 `usbh_initialize` 并填入 `busid` 和 USB IP 的 `reg base` 还有 `event_handler` 可缺省为NULL， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` -- 在中断函数中调用 `USBH_IRQHandler`，并传入 `busid`, 如果你的 SDK 中中断入口已经存在 `USBH_IRQHandler` ，请更改 USB 协议栈中的名称 -- 链接脚本修改参考 :ref:`usbh_link_script` 章节 -- 如果芯片带 cache，cache 修改参考 :ref:`usb_cache` 章节 -- 调用 `usbh_initialize` ，填入 `busid` 和 USB IP 的 `reg base` 还有 `event_handler` 可缺省为NULL， `busid` 从 0 开始，不能超过 `CONFIG_USBHOST_MAX_BUS` 。基础的 cdc + hid + msc 参考 `usb_host.c` 文件，其余参考 **platform** 目录下适配 - -.. _usbh_link_script: - -主机链接脚本修改 ------------------------ - -在使用主机时，如果没有修改链接脚本，会报 `__usbh_class_info_start__` 和 `__usbh_class_info_end__` 未定义的错误。因为主机协议栈需要在链接脚本中添加一个 section 来存储 class 信息。 - -- 如果使用的是 KEIL 无需修改 - -- 如果使用的是 GCC ，需要在链接脚本中添加如下代码（需要放在 flash 位置，建议放最后）： - -.. code-block:: C - - // 在 ld 文件中添加如下代码 - . = ALIGN(4); - __usbh_class_info_start__ = .; - KEEP(*(.usbh_class_info)) - __usbh_class_info_end__ = .; - -GCC 举例如下： - -.. code-block:: C - - /* The program code and other data into "FLASH" Rom type memory */ - .text : - { - . = ALIGN(4); - *(.text) /* .text sections (code) */ - *(.text*) /* .text* sections (code) */ - *(.glue_7) /* glue arm to thumb code */ - *(.glue_7t) /* glue thumb to arm code */ - *(.eh_frame) - - KEEP (*(.init)) - KEEP (*(.fini)) - . = ALIGN(4); - __usbh_class_info_start__ = .; - KEEP(*(.usbh_class_info)) - __usbh_class_info_end__ = .; - . = ALIGN(4); - _etext = .; /* define a global symbols at end of code */ - } > FLASH - -- Segger Embedded Studio 举例如下： - -.. code-block:: C - - define block cherryusb_usbh_class_info { section .usbh_class_info }; - - define exported symbol __usbh_class_info_start__ = start of block cherryusb_usbh_class_info; - define exported symbol __usbh_class_info_end__ = end of block cherryusb_usbh_class_info + 1; - - place in AXI_SRAM { block cherryusb_usbh_class_info }; - keep { section .usbh_class_info}; - - -.. _usb_cache: - -cache 配置修改 -------------------------------- - -对于带 cache 的芯片，协议栈以及 port 中不会对 cache 区域的 ram 进行 clean 或者 invalid，所以需要使用一块非 cache 区域的 ram 来维护。 -`USB_NOCACHE_RAM_SECTION` 宏表示将变量指定到非 cache ram上，默认 `USB_NOCACHE_RAM_SECTION` 定义为 `__attribute__((section(".noncacheable")))`。 -因此，用户需要在对应的链接脚本中添加 no cache ram 的 section，并且 section 段包含 `.noncacheable`。 - -.. note:: 需要注意，光修改链接脚本中的 nocache section 是不够的，还需要配置该 section 中的 ram 是真的 nocache，一般需要配置 mpu 属性（arm 的参考 stm32h7 demo）。 - -GCC: - -.. code-block:: C - - MEMORY - { - RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 256K - 64K - RAM_nocache (xrw) : ORIGIN = 0x20030000, LENGTH = 64K - FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 512K - } - - ._nocache_ram : - { - . = ALIGN(4); - *(.noncacheable) - } >RAM_nocache - - -SCT: - -.. code-block:: C - - LR_IROM1 0x08000000 0x00200000 { ; load region size_region - ER_IROM1 0x08000000 0x00200000 { ; load address = execution address - *.o (RESET, +First) - *(InRoot$$Sections) - .ANY (+RO) - .ANY (+XO) - } - RW_IRAM2 0x24000000 0x00070000 { ; RW data - .ANY (+RW +ZI) - } - USB_NOCACHERAM 0x24070000 0x00010000 { ; RW data - *(.noncacheable) - } - } - -ICF: - -.. code-block:: C - - define region NONCACHEABLE_RAM = [from 0x1140000 size 256K]; - place in NONCACHEABLE_RAM { section .noncacheable, section .noncacheable.init, section .noncacheable.bss }; // Noncacheable diff --git a/docs/source/show/img/usbdev_msc.png b/docs/source/show/img/usbdev_msc.png deleted file mode 100644 index 30f22383..00000000 Binary files a/docs/source/show/img/usbdev_msc.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_linux.png b/docs/source/show/img/usbdev_rndis_linux.png deleted file mode 100644 index 94b97312..00000000 Binary files a/docs/source/show/img/usbdev_rndis_linux.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_lwip.png b/docs/source/show/img/usbdev_rndis_lwip.png deleted file mode 100644 index f4cfd0b3..00000000 Binary files a/docs/source/show/img/usbdev_rndis_lwip.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_lwip2.png b/docs/source/show/img/usbdev_rndis_lwip2.png deleted file mode 100644 index 3fde91f9..00000000 Binary files a/docs/source/show/img/usbdev_rndis_lwip2.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_wifi.png b/docs/source/show/img/usbdev_rndis_wifi.png deleted file mode 100644 index d6817876..00000000 Binary files a/docs/source/show/img/usbdev_rndis_wifi.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_wifi2.png b/docs/source/show/img/usbdev_rndis_wifi2.png deleted file mode 100644 index dba9f3dd..00000000 Binary files a/docs/source/show/img/usbdev_rndis_wifi2.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_rndis_win.png b/docs/source/show/img/usbdev_rndis_win.png deleted file mode 100644 index 5293023a..00000000 Binary files a/docs/source/show/img/usbdev_rndis_win.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_uvc_mjpeg.png b/docs/source/show/img/usbdev_uvc_mjpeg.png deleted file mode 100644 index a2321c15..00000000 Binary files a/docs/source/show/img/usbdev_uvc_mjpeg.png and /dev/null differ diff --git a/docs/source/show/img/usbdev_uvc_yuv.png b/docs/source/show/img/usbdev_uvc_yuv.png deleted file mode 100644 index a630cd67..00000000 Binary files a/docs/source/show/img/usbdev_uvc_yuv.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_ax88772_1.png b/docs/source/show/img/usbhost_ax88772_1.png deleted file mode 100644 index a267b292..00000000 Binary files a/docs/source/show/img/usbhost_ax88772_1.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_ax88772_2.png b/docs/source/show/img/usbhost_ax88772_2.png deleted file mode 100644 index fc6e96fc..00000000 Binary files a/docs/source/show/img/usbhost_ax88772_2.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_hub.png b/docs/source/show/img/usbhost_hub.png deleted file mode 100644 index 011468c7..00000000 Binary files a/docs/source/show/img/usbhost_hub.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_hub2.png b/docs/source/show/img/usbhost_hub2.png deleted file mode 100644 index 00c09d6f..00000000 Binary files a/docs/source/show/img/usbhost_hub2.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_msc.png b/docs/source/show/img/usbhost_msc.png deleted file mode 100644 index ec546a8d..00000000 Binary files a/docs/source/show/img/usbhost_msc.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_msc_xhci.png b/docs/source/show/img/usbhost_msc_xhci.png deleted file mode 100644 index 084250f2..00000000 Binary files a/docs/source/show/img/usbhost_msc_xhci.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_rndis.png b/docs/source/show/img/usbhost_rndis.png deleted file mode 100644 index 12ab1a4e..00000000 Binary files a/docs/source/show/img/usbhost_rndis.png and /dev/null differ diff --git a/docs/source/show/img/usbhost_uvc.gif b/docs/source/show/img/usbhost_uvc.gif deleted file mode 100644 index c4df04e0..00000000 Binary files a/docs/source/show/img/usbhost_uvc.gif and /dev/null differ diff --git a/docs/source/show/img/usbhost_wifi.png b/docs/source/show/img/usbhost_wifi.png deleted file mode 100644 index e57fd85b..00000000 Binary files a/docs/source/show/img/usbhost_wifi.png and /dev/null differ diff --git a/docs/source/show/index.rst b/docs/source/show/index.rst deleted file mode 100644 index c5d3f708..00000000 --- a/docs/source/show/index.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. _performace_show: - -性能展示 -============================== - -以下演示了 CherryUSB 在不同应用中的性能表现。主要演示高速模式，全速看不出什么性能差异。 - -CDC ACM 通信 ----------------- - -可以达到硬件极限性能，当然需要硬件理论支持到这速度，CherryUSB 就支持到这速度,举例如下： - -- HPM 系列(从机可以到 42MB/S, 主机 44MB/S, 已经达到硬件极限) -- BL 系列（从机 32MB/S, 主机 25MB/S, 已经达到硬件极限） -- STM32F4 全速（从机 900KB/S, 主机 1.12MB/S, 已经达到硬件极限） - -从机测速demo: cdc_acm_template.c 并且关闭 log，脚本使用 `tools/test_srcipts/test_cdc_speed.py` -主机测速demo: usb_host.c 中 TEST_USBH_CDC_SPEED=1 - -USB Device MSC ------------------ - -演示 USB Device MSC 使用 SDXC3.0 + EMMC 测试。 - -.. figure:: img/usbdev_msc.png - -USB Device RNDIS ------------------------ - -.. note:: 默认 rndis 仅支持单包，因此下面速度为最低速度。多包支持需要联系作者。 - -演示 USB Device RNDIS 局域网下搭配 lwip 的速度。 - -作为 client - -.. figure:: img/usbdev_rndis_lwip.png - -作为 server - -.. figure:: img/usbdev_rndis_lwip2.png - -演示 USB Device RNDIS + WIFI 透传测试。 - -.. figure:: img/usbdev_rndis_wifi.png -.. figure:: img/usbdev_rndis_wifi2.png - -演示 USB Device RNDIS + 百兆以太网透传测试。 - -.. figure:: img/usbdev_rndis_win.png -.. figure:: img/usbdev_rndis_linux.png - -USB Device UVC ------------------------ - -演示 USB Device UVC + 摄像头传输 YUYV/MJPEG 640 * 480 图像。FPS 30。 - -.. figure:: img/usbdev_uvc_mjpeg.png -.. figure:: img/usbdev_uvc_yuv.png - -USB Host HUB ------------------------ - -多级 hub 支持，演示 1托 7 HUB - -.. figure:: img/usbhost_hub.png -.. figure:: img/usbhost_hub2.png - -USB Host MSC ------------------------ - -演示 USB Host MSC 在 USB2.0 和 USB3.0 下的速度，U盘推荐使用固态测试。 - -.. figure:: img/usbhost_msc.png -.. figure:: img/usbhost_msc_xhci.png - -USB Host UVC ------------------------ - -演示 USB Host UVC 驱动 648 * 480 YUV 摄像头。FPS 30。 - -.. figure:: img/usbhost_uvc.gif - -USB Host ASIX 网卡 ------------------------ - -演示 USB Host 驱动 AX88772 USB 以太网模块。 - -.. figure:: img/usbhost_ax88772_1.png -.. figure:: img/usbhost_ax88772_2.png - -USB Host RNDIS 网卡 ------------------------ - -演示 USB Host 驱动手机，手机开启 USB 共享网络即可使用 RNDIS 。 - -.. figure:: img/usbhost_rndis.png - -USB Host WIFI ------------------------ - -演示 USB Host 驱动 BL616 USB WIFI。 - -.. figure:: img/usbhost_wifi.png diff --git a/docs/source/support/img/dwc2_hostuac.png b/docs/source/support/img/dwc2_hostuac.png deleted file mode 100644 index 6050f531..00000000 Binary files a/docs/source/support/img/dwc2_hostuac.png and /dev/null differ diff --git a/docs/source/support/img/dwc2_hostuvc1.png b/docs/source/support/img/dwc2_hostuvc1.png deleted file mode 100644 index 70b4dd1a..00000000 Binary files a/docs/source/support/img/dwc2_hostuvc1.png and /dev/null differ diff --git a/docs/source/support/img/dwc2_hostuvc2.png b/docs/source/support/img/dwc2_hostuvc2.png deleted file mode 100644 index 8885e90e..00000000 Binary files a/docs/source/support/img/dwc2_hostuvc2.png and /dev/null differ diff --git a/docs/source/support/img/dwc2_hostuvc3.png b/docs/source/support/img/dwc2_hostuvc3.png deleted file mode 100644 index fb3e1eef..00000000 Binary files a/docs/source/support/img/dwc2_hostuvc3.png and /dev/null differ diff --git a/docs/source/support/img/ehci_hostuvc1.png b/docs/source/support/img/ehci_hostuvc1.png deleted file mode 100644 index 2bd6590a..00000000 Binary files a/docs/source/support/img/ehci_hostuvc1.png and /dev/null differ diff --git a/docs/source/support/img/ehci_hostuvc2.png b/docs/source/support/img/ehci_hostuvc2.png deleted file mode 100644 index f44fa68c..00000000 Binary files a/docs/source/support/img/ehci_hostuvc2.png and /dev/null differ diff --git a/docs/source/support/img/mtpdev.png b/docs/source/support/img/mtpdev.png deleted file mode 100644 index 513b8ac9..00000000 Binary files a/docs/source/support/img/mtpdev.png and /dev/null differ diff --git a/docs/source/support/img/ohci.png b/docs/source/support/img/ohci.png deleted file mode 100644 index 171f77be..00000000 Binary files a/docs/source/support/img/ohci.png and /dev/null differ diff --git a/docs/source/support/img/rndisrx.png b/docs/source/support/img/rndisrx.png deleted file mode 100644 index ce1133ed..00000000 Binary files a/docs/source/support/img/rndisrx.png and /dev/null differ diff --git a/docs/source/support/img/rndistx.png b/docs/source/support/img/rndistx.png deleted file mode 100644 index 69e45db8..00000000 Binary files a/docs/source/support/img/rndistx.png and /dev/null differ diff --git a/docs/source/support/img/tmcdev1.png b/docs/source/support/img/tmcdev1.png deleted file mode 100644 index 1eaf7155..00000000 Binary files a/docs/source/support/img/tmcdev1.png and /dev/null differ diff --git a/docs/source/support/img/tmcdev2.png b/docs/source/support/img/tmcdev2.png deleted file mode 100644 index 97c8297b..00000000 Binary files a/docs/source/support/img/tmcdev2.png and /dev/null differ diff --git a/docs/source/support/img/usbhost_uvc.gif b/docs/source/support/img/usbhost_uvc.gif deleted file mode 100644 index c4df04e0..00000000 Binary files a/docs/source/support/img/usbhost_uvc.gif and /dev/null differ diff --git a/docs/source/support/index.rst b/docs/source/support/index.rst deleted file mode 100644 index e30c4bb0..00000000 --- a/docs/source/support/index.rst +++ /dev/null @@ -1,43 +0,0 @@ -商业支持 -============================== - -以下内容为商业收费类，如需支持，请邮件到 1203593632@qq.com。 - -- OHCI 驱动 - -.. figure:: img/ohci.png - -- EHCI IP 中 ISO 驱动和 UAC/UVC 框架，搭配主机 UVC & UAC 类（这部分是开源的）使用。iso 支持一个微帧 1/2/3 包，支持 MJPEG 和 YUV 摄像头 - -.. figure:: img/ehci_hostuvc1.png -.. figure:: img/ehci_hostuvc2.png - -演示 USB Host UVC 驱动 648 * 480 YUV 摄像头。FPS 30。 - -.. figure:: img/usbhost_uvc.gif - -- DWC2 IP 中 ISO 驱动和 UAC/UVC 框架，搭配主机 UVC & UAC 类（这部分是开源的）使用。iso 支持一个微帧 1/2/3 包，支持 MJPEG 和 YUV 摄像头 - -.. figure:: img/dwc2_hostuvc1.png -.. figure:: img/dwc2_hostuvc2.png -.. figure:: img/dwc2_hostuvc3.png -.. figure:: img/dwc2_hostuac.png - -- MUSB IP 中 ISO 驱动和 UAC/UVC 框架，搭配主机 UVC & UAC 类（这部分是开源的）使用。MUSB 需要为 mentor 公司制定的标准 IP - -- 从机 MTP 类驱动, 支持多文件和多文件夹，支持 MCU 端增删文件并与 PC 同步 - -.. figure:: img/mtpdev.png - -- 从机 TMC 类驱动 - -.. figure:: img/tmcdev1.png -.. figure:: img/tmcdev2.png - -- USB 网卡类高性能版本优化,包含 CDC-NCM, CDC-RNDIS, 私有类驱动（支持多包发送和接收），下面举例 RNDIS - -.. figure:: img/rndistx.png -.. figure:: img/rndisrx.png - -- 定制化 class 驱动或者 IP 驱动适配 -- 技术支持相关 \ No newline at end of file diff --git a/docs/source/tools/img/chrytool1.png b/docs/source/tools/img/chrytool1.png deleted file mode 100644 index 8717316a..00000000 Binary files a/docs/source/tools/img/chrytool1.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool2.png b/docs/source/tools/img/chrytool2.png deleted file mode 100644 index a0eb4192..00000000 Binary files a/docs/source/tools/img/chrytool2.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool3.png b/docs/source/tools/img/chrytool3.png deleted file mode 100644 index 52a3556b..00000000 Binary files a/docs/source/tools/img/chrytool3.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool4.png b/docs/source/tools/img/chrytool4.png deleted file mode 100644 index 8ad68400..00000000 Binary files a/docs/source/tools/img/chrytool4.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool5.png b/docs/source/tools/img/chrytool5.png deleted file mode 100644 index 17849324..00000000 Binary files a/docs/source/tools/img/chrytool5.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool6.png b/docs/source/tools/img/chrytool6.png deleted file mode 100644 index 931ccad8..00000000 Binary files a/docs/source/tools/img/chrytool6.png and /dev/null differ diff --git a/docs/source/tools/img/chrytool7.png b/docs/source/tools/img/chrytool7.png deleted file mode 100644 index 283a7fc9..00000000 Binary files a/docs/source/tools/img/chrytool7.png and /dev/null differ diff --git a/docs/source/tools/index.rst b/docs/source/tools/index.rst deleted file mode 100644 index 0ebfb31d..00000000 --- a/docs/source/tools/index.rst +++ /dev/null @@ -1,50 +0,0 @@ -chryusb_configurator --------------------------- - -`chryusb_configurator `_ 主要服务在使用设备协议栈时，生成描述符数组，从而调用 `usbd_desc_register` 进行注册。 - -- 首先我们从 github 下载 chryusb_configurator.exe，然后一路安装就可以了。然后双击打开，点击 `工程`，并点击 `新建工程` - -.. figure:: img/chrytool1.png - -- 新建完成以后，会生成默认的描述符配置，包含 **设备描述符**、 **配置描述符**、 **字符串描述符**,并且 **字符串描述符** 默认支持三个 - -.. figure:: img/chrytool2.png - -- 然后我们可以根据需要修改相关描述符的信息，比如 **设备描述符** 中的 vid、pid，class 参数， **配置描述符** 中的 **Power** 等等 - -- 然后是 class 的添加，需要点击 `文件`，并点击 `新建文件` - -.. figure:: img/chrytool3.png - -- 然后右侧提供了一些 class 的描述符模板，选择一个进行初始化 - -.. figure:: img/chrytool4.png - -- 如果是多个 class ，则上述两步重复操作就可以了 - -- 然后我们根据需要修改相关端点的参数，比如方向、地址、size、interval - -.. figure:: img/chrytool5.png - -- 最后点击 `文件` 并保存文件,后缀为 `.chry` -- 切换到工程文件，后缀是 `.chrybase`, 然后点击 `添加分组配置` 导入刚刚配置好的 class 文件 - -.. figure:: img/chrytool6.png - -- 点击 `工程` 并点击 `保存工程` -- 点击 `编译`，生成描述符数组 - -.. figure:: img/chrytool7.png - -- 复制编译后的文件到自己的工程中使用即可 - - -力科 USB Protocol Suite --------------------------- - -Wireshark --------------------------- - -Audacity --------------------------- diff --git a/docs/source/usb/img/1.png b/docs/source/usb/img/1.png deleted file mode 100644 index e85ddf7a..00000000 Binary files a/docs/source/usb/img/1.png and /dev/null differ diff --git a/docs/source/usb/img/10.png b/docs/source/usb/img/10.png deleted file mode 100644 index bb57645e..00000000 Binary files a/docs/source/usb/img/10.png and /dev/null differ diff --git a/docs/source/usb/img/11.png b/docs/source/usb/img/11.png deleted file mode 100644 index 11056e33..00000000 Binary files a/docs/source/usb/img/11.png and /dev/null differ diff --git a/docs/source/usb/img/12.png b/docs/source/usb/img/12.png deleted file mode 100644 index 4149d81e..00000000 Binary files a/docs/source/usb/img/12.png and /dev/null differ diff --git a/docs/source/usb/img/13.png b/docs/source/usb/img/13.png deleted file mode 100644 index 29a544b2..00000000 Binary files a/docs/source/usb/img/13.png and /dev/null differ diff --git a/docs/source/usb/img/14.png b/docs/source/usb/img/14.png deleted file mode 100644 index 8ca094a4..00000000 Binary files a/docs/source/usb/img/14.png and /dev/null differ diff --git a/docs/source/usb/img/15.png b/docs/source/usb/img/15.png deleted file mode 100644 index eba7b89b..00000000 Binary files a/docs/source/usb/img/15.png and /dev/null differ diff --git a/docs/source/usb/img/16.png b/docs/source/usb/img/16.png deleted file mode 100644 index 259336ca..00000000 Binary files a/docs/source/usb/img/16.png and /dev/null differ diff --git a/docs/source/usb/img/17.png b/docs/source/usb/img/17.png deleted file mode 100644 index c42de390..00000000 Binary files a/docs/source/usb/img/17.png and /dev/null differ diff --git a/docs/source/usb/img/18.png b/docs/source/usb/img/18.png deleted file mode 100644 index f08b6354..00000000 Binary files a/docs/source/usb/img/18.png and /dev/null differ diff --git a/docs/source/usb/img/19.png b/docs/source/usb/img/19.png deleted file mode 100644 index 2e6eb9ce..00000000 Binary files a/docs/source/usb/img/19.png and /dev/null differ diff --git a/docs/source/usb/img/2.png b/docs/source/usb/img/2.png deleted file mode 100644 index 5b4f5f20..00000000 Binary files a/docs/source/usb/img/2.png and /dev/null differ diff --git a/docs/source/usb/img/20.png b/docs/source/usb/img/20.png deleted file mode 100644 index a44898a8..00000000 Binary files a/docs/source/usb/img/20.png and /dev/null differ diff --git a/docs/source/usb/img/21.png b/docs/source/usb/img/21.png deleted file mode 100644 index 7aa81e95..00000000 Binary files a/docs/source/usb/img/21.png and /dev/null differ diff --git a/docs/source/usb/img/22.png b/docs/source/usb/img/22.png deleted file mode 100644 index 370d39f9..00000000 Binary files a/docs/source/usb/img/22.png and /dev/null differ diff --git a/docs/source/usb/img/23.png b/docs/source/usb/img/23.png deleted file mode 100644 index e08db16e..00000000 Binary files a/docs/source/usb/img/23.png and /dev/null differ diff --git a/docs/source/usb/img/24.png b/docs/source/usb/img/24.png deleted file mode 100644 index fec98d49..00000000 Binary files a/docs/source/usb/img/24.png and /dev/null differ diff --git a/docs/source/usb/img/25.png b/docs/source/usb/img/25.png deleted file mode 100644 index 9bcaf151..00000000 Binary files a/docs/source/usb/img/25.png and /dev/null differ diff --git a/docs/source/usb/img/26.png b/docs/source/usb/img/26.png deleted file mode 100644 index d439b7c4..00000000 Binary files a/docs/source/usb/img/26.png and /dev/null differ diff --git a/docs/source/usb/img/27.png b/docs/source/usb/img/27.png deleted file mode 100644 index 1047da1b..00000000 Binary files a/docs/source/usb/img/27.png and /dev/null differ diff --git a/docs/source/usb/img/28.png b/docs/source/usb/img/28.png deleted file mode 100644 index 95b760c5..00000000 Binary files a/docs/source/usb/img/28.png and /dev/null differ diff --git a/docs/source/usb/img/29.png b/docs/source/usb/img/29.png deleted file mode 100644 index 09538d16..00000000 Binary files a/docs/source/usb/img/29.png and /dev/null differ diff --git a/docs/source/usb/img/3.png b/docs/source/usb/img/3.png deleted file mode 100644 index b8ef0823..00000000 Binary files a/docs/source/usb/img/3.png and /dev/null differ diff --git a/docs/source/usb/img/30.png b/docs/source/usb/img/30.png deleted file mode 100644 index d3014f95..00000000 Binary files a/docs/source/usb/img/30.png and /dev/null differ diff --git a/docs/source/usb/img/4.png b/docs/source/usb/img/4.png deleted file mode 100644 index f80c5366..00000000 Binary files a/docs/source/usb/img/4.png and /dev/null differ diff --git a/docs/source/usb/img/5.png b/docs/source/usb/img/5.png deleted file mode 100644 index ec6a4ba2..00000000 Binary files a/docs/source/usb/img/5.png and /dev/null differ diff --git a/docs/source/usb/img/6.png b/docs/source/usb/img/6.png deleted file mode 100644 index 2d280398..00000000 Binary files a/docs/source/usb/img/6.png and /dev/null differ diff --git a/docs/source/usb/img/7.png b/docs/source/usb/img/7.png deleted file mode 100644 index e7562f11..00000000 Binary files a/docs/source/usb/img/7.png and /dev/null differ diff --git a/docs/source/usb/img/8.png b/docs/source/usb/img/8.png deleted file mode 100644 index a4ac6ad4..00000000 Binary files a/docs/source/usb/img/8.png and /dev/null differ diff --git a/docs/source/usb/img/9.png b/docs/source/usb/img/9.png deleted file mode 100644 index a8b5b2a3..00000000 Binary files a/docs/source/usb/img/9.png and /dev/null differ diff --git a/docs/source/usb/img/overview1.png b/docs/source/usb/img/overview1.png deleted file mode 100644 index fbaf5a19..00000000 Binary files a/docs/source/usb/img/overview1.png and /dev/null differ diff --git a/docs/source/usb/img/overview2.png b/docs/source/usb/img/overview2.png deleted file mode 100644 index c8b3b779..00000000 Binary files a/docs/source/usb/img/overview2.png and /dev/null differ diff --git a/docs/source/usb/img/usb_enum.png b/docs/source/usb/img/usb_enum.png deleted file mode 100644 index 01c67c15..00000000 Binary files a/docs/source/usb/img/usb_enum.png and /dev/null differ diff --git a/docs/source/usb/img/usb_request.png b/docs/source/usb/img/usb_request.png deleted file mode 100644 index bb9f2637..00000000 Binary files a/docs/source/usb/img/usb_request.png and /dev/null differ diff --git a/docs/source/usb/img/usbstruct.png b/docs/source/usb/img/usbstruct.png deleted file mode 100644 index bd062ca3..00000000 Binary files a/docs/source/usb/img/usbstruct.png and /dev/null differ diff --git a/docs/source/usb/usb2.0_basic.rst b/docs/source/usb/usb2.0_basic.rst deleted file mode 100644 index 1c2b599e..00000000 --- a/docs/source/usb/usb2.0_basic.rst +++ /dev/null @@ -1,296 +0,0 @@ -USB 基本概念(2.0 为主) -=========================== - -本文主要对 USB 官方手册 `usb2.0.pdf `_ 中提供的第五章、第七章、第八章、第九章进行讲解。 -如果是初学 usb 的同学，推荐先不要看本节，而是将示例 demo 能够跑通了，熟悉了使用，再来看。 - -简介 ---------- - -USB 是什么？干什么用的？有什么优点?这些大家可以百度，我就不提了。主要先说 USB 的接口和速度根据不同的 USB 版本的分类，如图所示： - -.. figure:: img/overview1.png - -其次是 USB 需要满足的电平标准，有了电平标准后，下面说的信号状态就可以进行分类了。USB2.0 和 USB3.0 支持的电压范围和最大电流如下： - -.. figure:: img/overview2.png - -USB 信号状态 ------------------ - -首先我们需要了解的是 USB 的电气特性中的 Signaling Level，也就是信号状态。USB 主要是靠 D+ 和 D- 来实现不同的信号状态，然后进行通信。官方手册 7.1.7 中列举出了低速、全速和高速时的信号状态对应的 D+ 和 D- 需要满足的要求。 - -.. figure:: img/1.png -.. figure:: img/2.png -.. figure:: img/3.png - -- **差分 0 和差分 1**： 这两个状态用于通过 USB 进行的通用数据通信。当 D+线为高电平、 D-线为低电平时，该状态为差分 1。当 D+线为低电平、 D-线为高电平时，该状态为差分 0。 -- **J 状态和 K 状态**： 除了差分信号外， USB 规范还定义了其他两个差分状态： J 状态和 K 状态。它们的定义由设备速度决定。在全速和高速设备上， J 状态为差分 1 而 K 状态是差分 0。在低速设备上，该情况则相反。 -- **单端 0（ SE0）**： 在 D+和 D-均为低电平时所发生的状态。该状态表示一个复位、断连或数据包的结束。 -- **单端 1（ SE1）**： 在 D+和 D-均为高电平时发生的状态。不会故意生成该状态，并且不能在 USB 设计中出现。 -- **闲置**： 必须在发送一个数据包的前后发生的状态。如果一个数据线为低电平，而另一个数据线为高电平，则表示闲置状态。高电平和低电平的定义由设备的速度决定。在全速设备上，闲置状态是指 D+为高电平、 D-为低电平。在低速设备上，该情况则相反。 -- **恢复**： 用于使设备从挂起状态唤醒。通过发送一个 K 状态实现该操作。 -- **数据包的开始（ SOP）**： 当 D+和 D-线从闲置状态转换到 K 状态时，将在开始低速或全速数据包前发生。 -- **数据包的结束（ EOP）**： 在低速或全速数据包结束时发生。当 SE0 状态持续两位时间（后面的内容将介绍位时间）以及 J 状态持续 1 位时间时，将发生 EOP。 -- **复位**： 在 SE0 状态持续 10 ms 时发生。在 SE0 至少持续 2.5 ms 后，该设备会复位，并开始进入复位状态。 -- **保持活动（ Keep Alive）**： 在低速设备中使用的信号。低速设备缺少了一个帧起始数据包（用于防止挂起状态）。每次经过 1 ms，它们都会使用一个 EOP 来防止设备进入挂起状态。 - -.. note::这里需要注意的一点就是， J K状态和差分0/1，对于低速来说，和全速/高速是相反的。 - -下面我们通过一个波形，来区分这些信号状态： - -.. figure:: img/4.png - -- 第一个红框，可以看出是一个数据包的开始，并且假设这是一个全速设备，那么D+ 为高，D- 为低，是一个闲置状态。 -- 第二个红框，D+为低，D- 为高，说明是一个 K 状态，由 闲置转 K 状态说明他是一个 SOP。 -- 第三个红框开始表示数据，表示 JKJKJKJKJK。 -- 第四个红框表示 SE0 ,因为D+和 D-均为低电平。 -- 第五个红框，而 SE0 持续了一段时间后，变成了 D+高，D- 低，说明他是一个 J 状态，从 SE0 切换成 J 状态，说明他是一个 EOP。 - -USB 速度识别 ---------------------- - -USB 的速度是如何判定的？ 这个见手册 7.1.5.1。USB 的速度检测主要是靠 D+ 和 D-线上拉 1.5K决定，如果 D+上拉1.5k，则该设备为全速设备，如果 D-上拉1.5k，则为低速设备。而高速设备初始是以一个全速设备的身份出现，和全速设备一样，D+线上有一个1.5k的上拉电阻。USB2.0的hub把它当作一个全速设备，之后，hub 和设备通过一系列握手信号确认双方的身份，最终判定该设备为高速设备。 - -.. figure:: img/5.png - -USB 连接与断开检测 ---------------------- - -那么 当我们的设备插上 USB 主机时，主机是如何知道有设备插入或者拔出呢？手册 7.1.7.3 给出了答案，如图所示： - -.. figure:: img/6.png -.. figure:: img/7.png - -首先是连接检测，主机检测到某一个数据线电平拉高保持了一段时间，就认为有设备连接上来了。低速设备连接时，主机会检测到D-线被拉高，全速/高速设备连接时，主机会检测到D+线被拉高。 -而断开检测，则是主机端D+、D-数据线上的下拉电阻起作用，断开后使得二者都在低电平；当低电平持续 TDDIS 时间就会被主机认为是断开状态。上图中，TDDIS在2到2.5us之间。 - -USB 电源 ---------------------- - -作为 USB 电源时， USB 设备可被划分为两种设备类型：总线供电和自供电。 - -- 总线供电是 USB 设计的一个优势。由于设备通过总线供电，因此不需要使用笨重的内部或外部电源，它仍能够维持自身操作。总线可由主机或集线器供电。使用某个总线供电的设备时，用户将设备配置为某种状态前必须考虑其功耗。 -- 自供电设备通过使用外部电源（如直流电源适配器或电池）为自己供电。自供电设备在进行设计的过程中需要考虑到一些注意事项。 USB 规范要求自供电设备一直监控自己的 VBUS 线。 VBUS 不存在的时间内，设备必须断开提供给 D+/D-线上的上拉电阻的电源，从而防止向主机或集线器供电。 否则，会导致 USB 合规性测试发生失败。但是自供电集线器能够从总线获得最多 100 mA 的电流。 - -USB 设备状态 ---------------------- - -在 USB 插上主机的那一刻， USB 设备本身的设备状态是会变化的。而这个设备状态，后面如果学习到枚举过程，可以知道，其实这段变化描述的就是枚举过程。这部分见手册 9.1.1。 - -.. figure:: img/9.png - -- 连接状态： 当将某个设备插入到主机/集线器，但主机/集线器不给 VBUS 线供电时，会出现这种状态。它通常在集线器检测到一个过流事件时出现。虽然仍连接着设备，但主机移除了供给它的电源。 -- 供电： 某个设备被连接到 USB 上并得到供电，但仍未接收到一个复位请求。 -- 默认： 某个设备被连接到 USB 上、得到供电，并且由主机进行了复位。这时，设备没有任何设备地址。 设备会响应地址 0。 -- 地址： 某个设备被连接到 USB、得到供电、被复位，并且有一个唯一的地址。但是设备仍未得到配置。 -- 配置： 设备已经连接到 USB、得到供电、被复位、具有唯一的地址、得到配置，但尚未进入挂起状态。此时，总线供电设备能够消耗超过 100 mA 的电流。 -- 挂起： 如上面所述，设备已经建立好了连接，并且得到配置，但在 3 ms 时间内不会进行任意总线操作。 - -翻译成中文图就是： - -.. figure:: img/10.png - -USB 编码与位填充 ---------------------- - -首先，USB 的数据是串行发送的，就像 UART、I2C、SPI 等等，连续的01 信号只通过一根数据线发送给接受者。但是因为发送者和接收者运行的频率不一样，信号的同步就是个问题，比如，接受者接收到了一个持续一段时间的低电平，无法得知这究竟是代表了 5 个 0 还是 1000 个 0。一个解决办法，就是在传输数据信号的同时，附加一个时钟信号，用来同步两端的传输，接受者在时钟信号的辅助下对数据信号采样，就可以正确解析出发送的数据了，比如 I2C 就是这样做的，SDA 来传输数据，SCL 来传输同步时钟： - -.. figure:: img/11.png - -虽然这样解决了问题，但是却需要附加一根时钟信号线来传输时钟。因为USB没有时钟信号，有没有不需要附加的时钟信号，也能保持两端的同步呢？ -有的，这就是 RZ 编码（Return-to-zero Code），也叫做归零编码。 - -RZ 编码（Return-to-zero Code） -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -RZ 编码（Return-to-zero Code），也叫做归零编码。在 RZ 编码中，正电平代表逻辑 1，负电平代表逻辑 0，并且，每传输完一位数据，信号返回到零电平，也就是说，信号线上会出现 3 种电平：正电平、负电平、零电平。 - -.. figure:: img/12.png - -从图上就可以看出来，因为每位传输之后都要归零，所以接受者只要在信号归零后采样即可，这样就不在需要单独的时钟信号。实际上， RZ 编码就是相当于把时钟信号用归零编码在了数据之内。这样的信号也叫做自同步（self-clocking）信号。 -这样虽然省了时钟数据线，但是还是有缺点的，因为在 RZ 编码中，大部分的数据带宽，都用来传输“归零”而浪费掉了。 - -NRZ 编码（Non-return-to-zero Code） -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -去掉这个归零步骤，NRZ 编码（Non-return-to-zero Code）就出现了，和 RZ 的区别就是 NRZ 是不需要归零的。 - -.. figure:: img/13.png - -NRZI 编码（Non-Return-to-Zero Inverted Code） -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -NRZI 编码（Non-Return-to-Zero Inverted Code）和 NRZ 的区别就是 NRZI 用信号的翻转代表一个逻辑，信号保持不变代表另外一个逻辑。这个见手册 7.1.8。 - -.. figure:: img/14.png - -如图所示，可以得出一个简单的记忆方式：遇到 0 的边沿电平就翻转，遇到 1 的边沿则不变。 - -位填充（bit-stuffing） -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -但是，这样还是会有一个问题，就是虽然接受者可以主动和发送者的频率匹配，但是两者之间总会有误差。假如数据信号是 1000 个逻辑 1，经过 USB 的 NRZI 编码之后，就是很长一段没有变化的电平，在这种情况下，即使接受者的频率和发送者相差千分之一，就会造成把数据采样成 1001 个或者 999 个 1了。 -USB 对这个问题的解决办法，就是强制插 0，也就是（位填充）bit-stuffing，如果要传输的数据中有 6个连续的 1，发送前就会在第 6 个 1 后面强制插入一个 0，让发送的信号强制出现翻转，从而强制接受者进行频率调整。 -接受者只要删除 6 个连续 1 之后的 0，就可以恢复原始的数据了。这部分见手册 7.1.9。 - -.. figure:: img/15.png -.. figure:: img/16.png -.. figure:: img/17.png - -在数据被NRZI编码之前，在数据流中每六个连续的1之后插入一个0，以强制NRZI数据流中的过渡，这使接收器逻辑至少每七位有一次数据转换，以保证数据和时钟的锁定。比特填充是从同步模式开始启用。结束同步模式的数据 "一 "被算作是序列中的第一个 "一"。序列中的第一个。除了高速EOP期间，发射器的位填充总是被强制执行。如果需要按照 -位填充规则的要求，零位将被插入，即使它是数据包结束（EOP）信号前的最后一位。接收器必须对NRZI数据进行解码，识别填充位，并将其丢弃。 - -.. caution:: 以下内容可以用一张图概括，了解即可，没有必要死记硬背 - -.. figure:: img/usbstruct.png - -USB 字段(域) ---------------------- - -USB 字段构成了 USB 通信中最基本也是最小的单元，后面的包、事务，最根本都是由字段构成，而字段又是由比特构成。字段部分见手册 8.1。 - -.. note:: USB 的比特先行模式是按照 LSB 先行原则。 - -同步字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -在 USB 系统中，主机和设备不是共享一个时钟，这使得接收方没办法准确知道发送方什么时候发送数据，尽管能检测到SOP，但是远远不够，所有这个时候就需要同步字段，使得接收方和发送方收发过程中保持同步，所以任何一个包都要以同步字段开始。同步字段0x01，经过编码以后就是01010100B。 - -.. figure:: img/18.png - -包标识符字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -PID 由一个四位数据包类型字段和一个四位校验字段组成，占用 8 个bit，如图所示。 PID指示数据包的类型，并通过推断，数据包的格式和应用于数据包的错误检测类型包。 PID的四位校验字段是通过执行分组类型字段的一个补码来生成，从而确保PID的可靠解码，以便正确解释分组的其余部分，如果四个PID校验位不是它们各自的分组标识符位的补码，则存在PID错误。 - -.. figure:: img/19.png - -既然是 4个比特，说明了 PID 类型可以分为16种，从16种中，又细分成4类：令牌 PID,数据 PID，握手 PID 和特殊 PID。 - -.. figure:: img/20.png - -地址字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -地址字段又分为设备地址字段和端点地址字段，其中设备地址字段占用 7 个bit，除去0 地址，主机可以分配的地址有 127个。 - -.. figure:: img/21.png - -端点地址字段占用 4个 bit，总共可以提供 16 个端点。 - -.. figure:: img/22.png - -帧号字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -帧号字段占用 11 个bit，主机每发出一个帧，帧号都会加1，如图所示。而高速设备中，帧中又包含微帧，1帧=8微帧，微帧则是加0.1。关于帧和微帧的概念，后续补充。 - -.. figure:: img/23.png - -数据字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -根据传输类型不同，数据字段中的数据长度也是不定的，从 0-1024不等。 - -.. figure:: img/24.png - -CRC 字段 -^^^^^^^^^^^^^^^^^^^^^^^^ - -循环冗余校验（CRC）用于保护令牌和数据包中的所有非PID字段。PID不包含在包含CRC的分组的CRC校验中。 在执行比特填充之前，在发送器中的各个字段上生成所有CRC。 类似地，在去除填充位之后，在接收器中对CRC进行解码。令牌和数据包CRC为所有单比特和双比特错误提供100％的覆盖。 CRC失败被认为表示一个或多个受保护字段已损坏并导致接收器忽略这些字段，并且在大多数情况下，忽略整个数据包。 - -.. figure:: img/24.png - -- 令牌CRC - -为令牌提供五位CRC字段，并覆盖IN，SETUP和OUT令牌的ADDR和ENDP字段或SOF令牌的时间戳字段。 PING和SPLIT特殊令牌还包括一个五位CRC字段。 - -生成多项式为： G（X）= X^5 + X^2 + 1 -表示该多项式的二进制位模式是00101B。 如果接收到所有令牌位而没有错误，则接收器处的五位校验和将为01100B。 - -- 数据CRC - -数据CRC是应用于数据分组的数据字段的16位多项式。 - -生成多项式是：G（X）= X^16 + X^15 + X^2 + 1 -表示该多项式的二进制位模式是1000000000000101B。 如果没有错误地接收到所有数据和CRC位，则16位校验和将为1000000000001101B。 - -USB 包 ---------------------- - -包由字段组成，根据 PID 类型，包分为四大类：令牌包、数据包、握手包、特殊包。此节内容见官方 8.4.1。 - -.. figure:: img/25.png - -算上 SOP,则如图，组成一个完整的包。 - -.. figure:: img/26.png - -令牌包 -^^^^^^^^^^^^^^^^^^^^^^^^ - -令牌包分为：SETUP、IN、OUT、SOF，其中 SETUP、IN、OUT的字段组成一样，如图： - -.. figure:: img/27.png - -- PID 字段：定义了数据传输方向为USB主机到USB设备。 -- ADDR 字段：指明了USB设备地址。 -- ENDP 字段：指明了接收数据的端点号。 -- CRC 字段：用于ADDR字段和ENDP字段进行循环冗余校验。 - -SOF 包的字段组成，如图： - -.. figure:: img/28.png - -- PID 字段：定义了数据传输方向为USB主机到USB设备。 -- 帧号 字段：指明了USB传输的帧号，其11位。 -- CRC 字段：用于ADDR字段和ENDP字段进行循环冗余校验。 - -数据包 -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. figure:: img/29.png - -- PID 字段：用于指明不同的数据包类型。支持 4 种数据包，分别为： DATAO 、 DATA1 、DATA2 和MDATA。 -- 数据 字段：其中包含了传输的数据。其数据的大小根据数据传输类吧和川户需要而定。根据 USB 协议的规定，对于低速 USB 数据传输， 最大长度为8字节对于全速SB 数据传输，其最大长度为 1023 字节；对于高速 USB 数据传输，数据最大长度为 1024 。 -- CRC 字段：这里使用 16 位的循环冗余校验来对数据字段进行保护。 - -握手包 -^^^^^^^^^^^^^^^^^^^^^^^^ - -握手包由8位的PID构成，用于数据传输的末位报告本次数据传输的状成。握手包之后使是整个事务处理的结束信号EOP. - -.. figure:: img/30.png - -特殊包 -^^^^^^^^^^^^^^^^^^^^^^^^ - -USB 事务 ---------------------- - -USB 常用事务共有三种：SETUP、IN、OUT，除了控制传输使用三个事务，其他传输都使用两个事务。特殊事务则是不携带数据的事务。 - -SETUP 事务 -^^^^^^^^^^^^^^^^^^^^^^^^ - -IN 事务 -^^^^^^^^^^^^^^^^^^^^^^^^ - -OUT 事务 -^^^^^^^^^^^^^^^^^^^^^^^^ - -特殊事务 -^^^^^^^^^^^^^^^^^^^^^^^^ - -USB 传输 ---------------------- - -控制传输 -^^^^^^^^^^^^^^^^^^^^^^^^ - -批量传输 -^^^^^^^^^^^^^^^^^^^^^^^^ - -中断传输 -^^^^^^^^^^^^^^^^^^^^^^^^ - -同步传输 -^^^^^^^^^^^^^^^^^^^^^^^^ \ No newline at end of file diff --git a/docs/source/usb/usb3.0_basic.rst b/docs/source/usb/usb3.0_basic.rst deleted file mode 100644 index 1dbbd815..00000000 --- a/docs/source/usb/usb3.0_basic.rst +++ /dev/null @@ -1,33 +0,0 @@ -USB 基本概念(3.0 为主) -=========================== - - -简介 ------------- - - - -与 USB 2.0 相同和不同点 --------------------------- - - -Link Layer --------------------- - -LCW -^^^^^^^^^^ - -Protocol Layer --------------------- - -LMP -^^^^^^^^^^^^^^^^^^^^^^^^ - -TP -^^^^^^^^^^^^^^^^^^^^^^^^ - -DP -^^^^^^^^^^^^^^^^^^^^^^^^ - -ITP -^^^^^^^^^^^^^^^^^^^^^^^^ \ No newline at end of file diff --git a/docs/source/usb/usb_desc.rst b/docs/source/usb/usb_desc.rst deleted file mode 100644 index f0bcc7fe..00000000 --- a/docs/source/usb/usb_desc.rst +++ /dev/null @@ -1,37 +0,0 @@ -USB 描述符 -=========================== - -本节参考官方 usb2.0 pdf 9.5 节即可。 - -设备描述符 ---------------------- - -配置描述符 ---------------------- - -接口描述符 ---------------------- - -端点描述符 ---------------------- - -字符串描述符 ---------------------- - -接口关联描述符 ---------------------- - -设备限定描述符 ---------------------- - -其他速度描述符 ---------------------- - -BOS 描述符 ---------------------- - -超高速端点伴随描述符 ---------------------- - -增加型超高速同步端点伴随描述符 -------------------------------- diff --git a/docs/source/usb/usb_enum.rst b/docs/source/usb/usb_enum.rst deleted file mode 100644 index 1434424f..00000000 --- a/docs/source/usb/usb_enum.rst +++ /dev/null @@ -1,22 +0,0 @@ -USB 枚举 -=========================== - -当我们了解了 usb 设备请求以后，就可以来学习下 USB 设备的整个枚举过程了，看看是如何枚举出一个串口、鼠标、u盘等设备了。枚举过程中主机会发送设备请求来获取相关信息（也就是描述符），具体发送哪些，参考下图。 - -.. figure:: img/usb_enum.png - -- 首先设备接上 USB 线，然后插上电脑 -- 设备插上以后上电，处于供电状态 -- 主机通过 D+/D- 识别到设备插入 -- 对设备进行复位 -- 主机发送 **获取设备描述符请求** -- 可选的复位操作 -- 主机发送 **设置设备地址请求** -- 主机发送 **获取配置描述符请求**，可能会获取多次，无所谓 -- 主机发送 **获取字符串描述符请求**，正常会获取3个字符串，如果后面的描述符中指定了字符串，则继续获取指定的字符串 -- 主机发送 **获取设备限定描述符请求**，用来获取在设备工作在其他速度上的请求，如果设备只能工作在全速模式，则必须回复 stall，并且协议栈中一定会打印该请求告诉你此命令设备不支持。 -- 主机发送 **设置配置请求**，对设备的端点进行配置，通常是根据端点描述符中的配置进行设置。 -- 到此标准的设备请求结束 -- 主机根据接口描述符加载对应支持的 class 驱动，如果主机不支持，则会提示该设备找不到驱动 -- 加载完成以后，开始执行该 class 相关的请求 -- 最终进行 class 的数据流传输 \ No newline at end of file diff --git a/docs/source/usb/usb_ext.rst b/docs/source/usb/usb_ext.rst deleted file mode 100644 index 86b87a53..00000000 --- a/docs/source/usb/usb_ext.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _usb_ext: - -USB 知识点拓展 -=========================== - -什么是分包 -------------- - -由于 USB 协议中规定了每个包的最大长度，所以当我们发送的数据长度超过了最大包长度时，就需要分包发送，这就是分包。比如 ep mps 为 64，数据长度为 129，则 USB 会按照 64 + 64 + 1 的形式传输。 -而对于 USB IP 来说，分包分为软件分包和硬件分包，软件分包就是用户代码自行分包，这种 ip 一般都使用 FIFO 来进行，因为 FIFO 深度是有限的；第二种 -则是使用硬件分包，这种 USB IP 一般带 DMA 或者描述符 DMA 功能，那么这种 IP 的效率无疑是最高的，cherryusb 中充分利用了这点，使得 USB 速度能够达到最高。 - -对于软件分包来说，一次发送的长度即使是 16K， **内部也是通过软件分包的，在这种情况下，发送长度的多少不会对速度有任何提升**。 -对于硬件分包来说，发送的长度会影响速度，因为硬件分包是通过 DMA 来进行的， **一次发送的长度越大，DMA 的效率就越高，速度也就越快**。（当然，其他协议栈虽然使用了 dma，但是部分代码实现还是按照一个包进行，等于没用，这也是速度低的一个原因） - -什么是短包 ----------------- - -在上面我们讲了分包之后，短包就是分包的最后一个包（并且长度小于 EP MPS）.比如发送 129 字节的数据，那么 USB 会按照 64 + 64 + 1 的形式传输，最后一个包是1个字节，这1个字节就是短包。 - -什么是 ZLP -------------- - -ZLP，顾名思义，零长度数据包，也就是数据长度为0 的短包。是 USB 设备在数据传输结束时，如果数据长度正好是最大包长度的整数倍，那么就需要发送一个 ZLP 数据包，用来告诉对方数据传输结束。 - -.. caution:: ZLP 功能仅限于 CONTROL 和 BULK 传输 - -什么时候算中断完成 --------------------- - -从机接收：接收的长度与设置的长度相等；接收的最后一个包为短包。 -从机发送：发送的长度与设置的长度相等，如果发送的长度是 EP MPS 的整数倍， **通常** 需要再发送一个 ZLP（仅限 control 和 bulk 传输）。 - -.. note:: 对于从机接收，并且是 bulk 传输，接收长度通常设计为 EP MPS，以下三种情况可以修改为多个 EP MPS: 固定长度；自定义协议并携带长度（例如 MSC）; 主机手动发送 ZLP 或者短包（例如 RNDIS） - -.. note:: 对于从机发送，并且是 bulk 传输，发送长度没有限制，但是如果是 EP MPS 整数倍，通常需要发送 ZLP。自定义协议则不需要发送 ZLP，例如 MSC。 - -主机接收：同从机接收 -主机发送：发送的长度与设置的长度相等 diff --git a/docs/source/usb/usb_request.rst b/docs/source/usb/usb_request.rst deleted file mode 100644 index 8e42565d..00000000 --- a/docs/source/usb/usb_request.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB 设备请求 -=========================== - -本节参考官方 usb2.0 pdf 9.3、9.4 节即可。 - -.. figure:: img/usb_request.png diff --git a/docs/source/usbdev.svg b/docs/source/usbdev.svg deleted file mode 100644 index 8f787289..00000000 --- a/docs/source/usbdev.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
usbd_desc_register
usbd_add_interface
usbd_add_endpoint
    struct usbd_tx_rx_msg tx_msg[16];
    struct usbd_tx_rx_msg rx_msg[16];
struct usbd_interface *intf[16];
usbd_initialize
USBD_IRQHandler
usbd_event_reset_handler
usbd_event_ep0_setup_complete_handler
usbd_event_ep_in_complete_handler
usbd_event_ep_out_complete_handler
usbd_setup_request_handler
tx_msg[ep & 0x7f].cb
rx_msg[ep & 0x7f].cb
usbd_event_ep0_in_complete_handler
tx_msg[ep & 0x7f].cb (ep != 0)
usbd_event_ep0_out_complete_handler
rx_msg[ep & 0x7f].cb (ep != 0)
usbd_standard_request_handler
usbd_class_request_handler
usbd_vendor_request_handler
 \ No newline at end of file diff --git a/docs/source/usbhost.svg b/docs/source/usbhost.svg deleted file mode 100644 index b7d537b5..00000000 --- a/docs/source/usbhost.svg +++ /dev/null @@ -1,9 +0,0 @@ -
usbh_initialize
usbh_initialize
usbh_hub_initialize
usbh_hub_initialize
usbh_roothub_register
usbh_roothub_register
create usbh_hub_thread
create usbh_hub_thread
usb_hc_init
usb_hc_init
usbh_roothub_thread_wakeup
usbh_roothub_thread_wakeup -
hub_int_complete_callback
hub_int_complete_callback -
wakeup
wakeup
wakeup
wakeup
usbh_enumerate
usbh_enumerate -
search all ports
search all ports
usbh_hub_events
usbh_hub_events -
CLASS_CONNECT
CLASS_CONNECT -
search all interface drivers
search all interface drivers
usbh_find_class_driver
usbh_find_class_driver -
if hub class？
if hub class？
usbh_int_urb_fill


usbh_submit_urb
usbh_int_urb_fill...
Class Register
Class Register -
USBH_IRQHandler
USBH_IRQHandler -Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/source/usbip/cdns2.rst b/docs/source/usbip/cdns2.rst deleted file mode 100644 index 88afc8d2..00000000 --- a/docs/source/usbip/cdns2.rst +++ /dev/null @@ -1,2 +0,0 @@ -CDNS2 -=============== diff --git a/docs/source/usbip/cdns3.rst b/docs/source/usbip/cdns3.rst deleted file mode 100644 index c2132d1a..00000000 --- a/docs/source/usbip/cdns3.rst +++ /dev/null @@ -1,2 +0,0 @@ -CDNS3 -=============== diff --git a/docs/source/usbip/chipidea.rst b/docs/source/usbip/chipidea.rst deleted file mode 100644 index 57c46ec0..00000000 --- a/docs/source/usbip/chipidea.rst +++ /dev/null @@ -1,2 +0,0 @@ -CHIPIDEA -================= \ No newline at end of file diff --git a/docs/source/usbip/dwc2.rst b/docs/source/usbip/dwc2.rst deleted file mode 100644 index 6c5a8c08..00000000 --- a/docs/source/usbip/dwc2.rst +++ /dev/null @@ -1,2 +0,0 @@ -DWC2 -================= \ No newline at end of file diff --git a/docs/source/usbip/dwc3.rst b/docs/source/usbip/dwc3.rst deleted file mode 100644 index 746bbee6..00000000 --- a/docs/source/usbip/dwc3.rst +++ /dev/null @@ -1,2 +0,0 @@ -DWC3 -=============== diff --git a/docs/source/usbip/ehci.rst b/docs/source/usbip/ehci.rst deleted file mode 100644 index 637bbe69..00000000 --- a/docs/source/usbip/ehci.rst +++ /dev/null @@ -1,2 +0,0 @@ -EHCI -================= \ No newline at end of file diff --git a/docs/source/usbip/fotg210.rst b/docs/source/usbip/fotg210.rst deleted file mode 100644 index f6e566a8..00000000 --- a/docs/source/usbip/fotg210.rst +++ /dev/null @@ -1,2 +0,0 @@ -FOTG210 -=============== diff --git a/docs/source/usbip/musb.rst b/docs/source/usbip/musb.rst deleted file mode 100644 index 597876c0..00000000 --- a/docs/source/usbip/musb.rst +++ /dev/null @@ -1,2 +0,0 @@ -MUSB -================= \ No newline at end of file diff --git a/docs/source/usbip/ohci.rst b/docs/source/usbip/ohci.rst deleted file mode 100644 index 8467233b..00000000 --- a/docs/source/usbip/ohci.rst +++ /dev/null @@ -1,2 +0,0 @@ -OHCI -================= \ No newline at end of file diff --git a/docs/source/usbip/xhci.rst b/docs/source/usbip/xhci.rst deleted file mode 100644 index 0c16c2e2..00000000 --- a/docs/source/usbip/xhci.rst +++ /dev/null @@ -1,2 +0,0 @@ -XHCI -================= \ No newline at end of file diff --git a/docs/source/version.rst b/docs/source/version.rst deleted file mode 100644 index 5c6e23e7..00000000 --- a/docs/source/version.rst +++ /dev/null @@ -1,182 +0,0 @@ -版本说明 -============================== - -如果没有特别情况，请使用最新版本。下面只列举比较重要的更新，详细更新说明请参考 https://github.com/cherry-embedded/CherryUSB/releases。 - -<= v0.10.2 初代版本 ----------------------- - -- **用于定基本的主从机框架，仅支持单 USB IP**。 -- **host 驱动每个 ep 占用一个 硬件 pipe，不支持动态使用硬件 pipe**。 -- 相关 porting 需要使用此版本，后续不再支持（比如 ch32，rp2040），以及旧版本pusb2 和 xhci（新版本不再提供源码）。 - -v1.0.0 过度版本 ----------------------- - -- **host 支持动态使用硬件 pipe，不再固定** - -v1.1.0 过度版本 ----------------------- - -- **主从机支持多 USB IP 且要相同 IP** -- **host 增加 bluetooth, ch340, ftdi, cp210x, asix 驱动** -- device msc 支持多 lun，并且 CONFIG_USBDEV_MSC_BLOCK_SIZE 修改为 CONFIG_USBDEV_MSC_MAX_BUFSIZE - -v1.2.0 ----------------------- - -- **host 增加 rtl8152，cdc ncm 驱动** -- host 增加 timer 去控制中断传输（hub修改为 timer 控制） -- porting 增加 esp，aic 主机驱动 -- **优化 DWC2 优化代码方便阅读，并增加一些 FIFO 配置宏给用户（因为 dwc2 fifo 大小有限，以及配置方式很多，所以导出给用户配置，方便合理控制性能）** -- 优化 ehci 驱动（qtd不再使用动态申请，绑定 qh），方便代码运行的更快 - -v1.3.0 ----------------------- - -- **device 支持多种速度描述符自动选择功能（开启 CONFIG_USBDEV_ADVANCE_DESC）** -- device core 代码统一 ep0 buffer 的使用，用于美化代码 -- host 增加 pl2303 驱动；采用 id table 来支持多个 vid，pid；增加 user_data 给用户使用 -- host 网络 class 驱动增加 tx、rx buffer 的宏，增加 LWIP_TCPIP_CORE_LOCKING_INPUT 的使用，以便实现数据的零拷贝 -- porting 导入 bouffalo，aic，stm32f723 device驱动 -- **porting 中主机部分 urb->timeout 清0 的处理有点问题（大数据量传输时会出现 no pipe alloc 异常，主要原因是刚启动传输就完成了，还没判断 timeout就被修改为0了，没有进入 take sem 流程），此版本已修复** -- ehci enable iaad in usbh_kill_urb，read ehci hcor offset from hccr caplength，enable ohci for ehci -- 适配 nuttx os - -v1.3.1 ----------------------- - -- bugfix（audio，video，cdc ecm 相关宏，结构体，api） -- **host hub 枚举线程删除，使用 psc 线程，枚举方式更改为队列模式，取消同时枚举多个设备的功能** -- host 扫描驱动信息和 instance 采用递归模式，删除链表扫描 -- host 网络 class 驱动优化，支持接收 16K 以上的数据（cdc ecm 不支持），采用高级 memcpy api -- **device 协议栈中打印删除（中断中不再做打印）** -- porting 中 musb fifo配置修改为从 fifo table 获取（此代码参考 linux），适配 es32，sunxi，beken - -v1.4.0 ----------------------- - -- **device 开始支持 remote wakeup 功能, hid request(0x21)，完善 GET STATUS 请求（此版本开始可以通过 USB3CV 测试）** -- device 增加 UF2, ADB, WEBUSB 功能； msc 增加裸机的读写 polling 功能，将读写放在 while1中执行； usbd_cdc 改名为 usbd_cdc_acm -- host 增加 usbwifi(bl616), xbox驱动； **重构 USB3.0 枚举逻辑** -- **host 中 cdc_acm,hid,msc,serial 传输共享 buffer，如果存在多个相同的设备会有问题，修改为单独的 buffer** -- **porting 重构 XHCI/PUSB2 驱动，不开源**；ehci 和 ohci 文件改名；增加 remote wakeup api -- esp 组件库支持 -- **chipidea 从机驱动支持，nxp mcx 系列主从支持** -- threadx os 支持 - -v1.4.1 ----------------------- - -- **修复device 模式下使用多个 altsetting 时重复关闭端点问题，改成 altsetting 为0时关闭** -- **重构主机 audio 解析描述符** -- **增加 kinetis usbip** -- 主机下 usbh_msc_get_maxlun 请求部分 U 盘不支持，不做错误返回 -- 主机下 usbh_hid_get_report_descriptor 导出给用户调用 -- 静态代码检查 -- github action 功能 - -v1.4.2 ----------------------- - -- device 实现 USB_REQUEST_GET_INTERFACE 请求 -- **device video 传输重构，增加双缓冲功能** -- device ecm 重构，保持和 rndis 类似 API -- device 和 host audio 音量配置功能重构 -- host 增加 AOA 驱动 -- 兼容 C++ 相关修改 -- fsdev 不支持 ISO 和 DWC2 高速 hub 不支持全速低速检查 -- **通用 OHCI 代码更新** - -v1.4.3 ----------------------- - -- **device ep0 处理增加线程模式** -- device audio feedback 宏和demo -- device rndis 增加透传功能（无LWIP） -- **host msc 将 scsi 初始化从枚举线程中移出，在mount阶段调用，并增加了testunity 多次尝试，兼容一部分 U 盘** -- rp2040 主从支持 -- **nuttx fs，serial，net 组件支持** -- dwc2、ehci、ohci 主机 dcache功能支持（v1.5.0 完善） -- t113、MCXA156、CH585 、 **stm32h7r 支持** -- 修复 v1.4.1 中 altsetting 为0时应该关闭所有端点的问题 - -v1.5.0 ----------------------- - -- **协议栈内部全局 buffer 需要使用 USB_ALIGN_UP 对齐, 用于开启 dcache 并且不使能 nocache 时使用** -- **完善 ehci/ohci dcache 模式下的处理**， add CONFIG_USB_EHCI_DESC_DCACHE_ENABLE for qh&qtd&itd, add CONFIG_USB_OHCI_DESC_DCACHE_ENABLE for ed&td -- **平台代码更新，平台相关转移到 platform，增加 lvgl 键鼠支持，blackmagic 支持，filex 支持, zephyr disk支持，esp-idf netif支持** -- **device sof callback 支持** -- **dwc2 、fsdev st 下实现底层 API 和中断，直接调用 HAL_PCD_MSP 和 HAL_HCD_MSP，不需要用户复制粘贴** -- **DWC2 实现 SPLIT 功能，高速模式下支持外部高速 hub 对接 FS/LS 设备** -- liteos-m, zephyr os 支持 -- device msc 裸机读写采用变量模式，而不是ringbuffer -- ehci qtd 使用 qtd alloc & free，节省内存，目前是 qh 携带 qtd -- rndis/ECM device， msc demo 更新，支持 rt-thread 下免修改 -- **memcpy 全部使用 usb_memcpy 替换，arm 库存在非对其访问问题** -- **重构 device mtp 驱动（收费使用）** -- **device tmc 驱动（收费使用）** -- **重构device video 传输，直接在图像数据中填充 uvc header，达到zero memcpy** -- **增加 usb_osal_thread_schedule_other api，用于在释放 class 资源之前，先释放所有 class 线程，避免释放 class 资源以后线程还在使用该 class 资源** -- **dwc2 device 增加 dcache 功能，可用于 cortex-M7/ESP32P4** -- **bouffalo/hpm/esp/st/nxp dcache api 支持** -- ch32 device iso 更新，IP 目录重新分类 -- cmake，scons，kconfig 更新 -- 使用 USB_ASSERT_MSG 对部分代码检查，全面性 warning 修复 -- N32H4/MM32F5 device 支持 -- 默认使能 CONFIG_USBDEV_ADVANCE_DESC - -v1.5.1 ----------------------- - -- 支持 rt-thread 下使用 adb shell，host serial/device cdc_acm 对接 rtdevice 框架 -- **dwc2 增加多个 usbport 不同参数的配置功能，比如一个全速一个高速，fifo配置和phy配置不同** -- **ehci 在控制传输中如果没有 nodata 阶段会导致 data qtd 未释放，导致内存泄漏** -- **dwc2 读取 setup 使用 usbd_get_next_ep0_state 去判断，避免 setup 和 ep0 out 使用在 USB_OTG_DOEPINT_XFRC 状态下冲突** -- sifli usb device 初步支持 - -v1.5.2 ----------------------- - -- 对 1.5.1 下 rt-thread 组件的一些 bugfix -- idf timer osal 替换为 esp timer，freertos timer会有启动失败的可能性；xTaskCreate 使用 xTaskCreatePinnedToCore 替换，方便多核使用 -- 主机枚举中，删除描述符溢出相关的 ASSERT 操作，改成返回错误。获取字符串描述符改成支持才获取。2 ms 延时改成 10ms，因为一些 os 使用的是 100hz，会造成延时失效 -- **dwc2 ep mult 支持，split 传输代码优化，对 split 相关的 cache 处理修改** -- **dwc2 halt 中不能清除 USB_OTG_HCCHAR_EPDIR，reset port 中使用超时机制，防止在枚举时由于拔出而造成死等** -- 更新 DWC2 中 at32，stm32，kendryte，espressif glue 代码 -- musb 对于标准的 IP 结构采用独立 EP 控制寄存器组，不使用 EPIDX 寄存器去控制 -- 删除所有 CONFIG_USBDEV_EP_NUM & CONFIG_USBHOST_PIPE_NUM，不再使用，因为 IP 本身会携带这些信息，或者厂家 SDK 提供了对应的宏 -- CONFIG_USBHOST_MAX_INTF_ALTSETTINGS 默认使用 2 减少内存，只有 UVC 和UAC 使用（商业收费），所以不需要开很大 -- urb interval 从 u8 改 u32，最大支持 2^15 * 125us - -v1.5.3 ----------------------- - -- 增加 mongoose demo -- **从机支持自定义 ep0 mps，仅支持商业性 IP** -- 主机增加 UVC bulk支持， **接口号匹配驱动功能**， **主机分配地址功能改成循环自增模式** ，重构 lsusb 命令 -- 主机控制传输增加 retry 机制，部分 device 通信不稳定，retry 次数参考 linux -- **主机 rndis 驱动增加非标 02/02/ff 接口驱动匹配** -- musb IP 关闭 multipoint feature 支持 -- hpmicro、chipidea dcache 支持 -- idf host msc 支持 -- otg 框架重构，当前 port 仅支持 hpmicro -- CI 编译功能，支持 hpmicro/espressif/bouffalolab - -v1.5.3.99 ----------------------- - -bugfix for v1.5.3 - - -v1.6.0 ----------------------- - -- **host 增加 serial 框架，统一所有类串口驱动** -- **host hid 增加报告描述符解析功能** -- usbh_initialize 增加 event callback，用于通知用户主机事件变化，通常不需要使用，设置为 NULL 即可 -- 支持 gamepad device -- 增加 ti xmc，infineon edge e8x port 支持 -- dwc2 增加 usbd_dwc2_get_system_clock 替换 SystemCoreClock；删除 __UNALIGNED_UINT32_READ 和 __UNALIGNED_UINT32_WRITE 宏；读取 setup 个数设置为 1个；第一次读取 setup 移动到 USB_OTG_GINTSTS_ENUMDNE 中断中 -- dwc2/ehci 增加 roothub 速度设置 \ No newline at end of file -- cgit v1.3.1