diff options
Diffstat (limited to 'docs/source/quick_start')
36 files changed, 0 insertions, 765 deletions
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 Binary files differdeleted file mode 100644 index c0a8b03f..00000000 --- a/docs/source/quick_start/img/env0.png +++ /dev/null diff --git a/docs/source/quick_start/img/env1.png b/docs/source/quick_start/img/env1.png Binary files differdeleted file mode 100644 index 2a68e052..00000000 --- a/docs/source/quick_start/img/env1.png +++ /dev/null diff --git a/docs/source/quick_start/img/env2.png b/docs/source/quick_start/img/env2.png Binary files differdeleted file mode 100644 index ee37101a..00000000 --- a/docs/source/quick_start/img/env2.png +++ /dev/null diff --git a/docs/source/quick_start/img/esp1.png b/docs/source/quick_start/img/esp1.png Binary files differdeleted file mode 100644 index 1f059e71..00000000 --- a/docs/source/quick_start/img/esp1.png +++ /dev/null diff --git a/docs/source/quick_start/img/esp2.png b/docs/source/quick_start/img/esp2.png Binary files differdeleted file mode 100644 index fd20e9ce..00000000 --- a/docs/source/quick_start/img/esp2.png +++ /dev/null diff --git a/docs/source/quick_start/img/esp3.png b/docs/source/quick_start/img/esp3.png Binary files differdeleted file mode 100644 index 82a7162f..00000000 --- a/docs/source/quick_start/img/esp3.png +++ /dev/null diff --git a/docs/source/quick_start/img/esp4.png b/docs/source/quick_start/img/esp4.png Binary files differdeleted file mode 100644 index ffb2882a..00000000 --- a/docs/source/quick_start/img/esp4.png +++ /dev/null diff --git a/docs/source/quick_start/img/question1.png b/docs/source/quick_start/img/question1.png Binary files differdeleted file mode 100644 index a852e6aa..00000000 --- a/docs/source/quick_start/img/question1.png +++ /dev/null diff --git a/docs/source/quick_start/img/question2.png b/docs/source/quick_start/img/question2.png Binary files differdeleted file mode 100644 index e00b3bfa..00000000 --- a/docs/source/quick_start/img/question2.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_1.png b/docs/source/quick_start/img/stm32_1.png Binary files differdeleted file mode 100644 index b91044a5..00000000 --- a/docs/source/quick_start/img/stm32_1.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_10.png b/docs/source/quick_start/img/stm32_10.png Binary files differdeleted file mode 100644 index d55b38e7..00000000 --- a/docs/source/quick_start/img/stm32_10.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_11.png b/docs/source/quick_start/img/stm32_11.png Binary files differdeleted file mode 100644 index 3ad5b074..00000000 --- a/docs/source/quick_start/img/stm32_11.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_12.png b/docs/source/quick_start/img/stm32_12.png Binary files differdeleted file mode 100644 index 84aaffe8..00000000 --- a/docs/source/quick_start/img/stm32_12.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_13.png b/docs/source/quick_start/img/stm32_13.png Binary files differdeleted file mode 100644 index f12fad75..00000000 --- a/docs/source/quick_start/img/stm32_13.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_14.png b/docs/source/quick_start/img/stm32_14.png Binary files differdeleted file mode 100644 index e5aa5b19..00000000 --- a/docs/source/quick_start/img/stm32_14.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_15.png b/docs/source/quick_start/img/stm32_15.png Binary files differdeleted file mode 100644 index 7c293287..00000000 --- a/docs/source/quick_start/img/stm32_15.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_16.png b/docs/source/quick_start/img/stm32_16.png Binary files differdeleted file mode 100644 index 70f2e63c..00000000 --- a/docs/source/quick_start/img/stm32_16.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_18.png b/docs/source/quick_start/img/stm32_18.png Binary files differdeleted file mode 100644 index 456df189..00000000 --- a/docs/source/quick_start/img/stm32_18.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_19.png b/docs/source/quick_start/img/stm32_19.png Binary files differdeleted file mode 100644 index a796dc75..00000000 --- a/docs/source/quick_start/img/stm32_19.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_2.png b/docs/source/quick_start/img/stm32_2.png Binary files differdeleted file mode 100644 index 671b1b82..00000000 --- a/docs/source/quick_start/img/stm32_2.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_3_1.png b/docs/source/quick_start/img/stm32_3_1.png Binary files differdeleted file mode 100644 index 9e42196d..00000000 --- a/docs/source/quick_start/img/stm32_3_1.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_3_2.png b/docs/source/quick_start/img/stm32_3_2.png Binary files differdeleted file mode 100644 index 492d6739..00000000 --- a/docs/source/quick_start/img/stm32_3_2.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_4_1.png b/docs/source/quick_start/img/stm32_4_1.png Binary files differdeleted file mode 100644 index e81437bc..00000000 --- a/docs/source/quick_start/img/stm32_4_1.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_4_2.png b/docs/source/quick_start/img/stm32_4_2.png Binary files differdeleted file mode 100644 index dd90f5b8..00000000 --- a/docs/source/quick_start/img/stm32_4_2.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_5.png b/docs/source/quick_start/img/stm32_5.png Binary files differdeleted file mode 100644 index 5bec9878..00000000 --- a/docs/source/quick_start/img/stm32_5.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_6.png b/docs/source/quick_start/img/stm32_6.png Binary files differdeleted file mode 100644 index f0ad9a0b..00000000 --- a/docs/source/quick_start/img/stm32_6.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_7.png b/docs/source/quick_start/img/stm32_7.png Binary files differdeleted file mode 100644 index 8aef0bfa..00000000 --- a/docs/source/quick_start/img/stm32_7.png +++ /dev/null diff --git a/docs/source/quick_start/img/stm32_8.png b/docs/source/quick_start/img/stm32_8.png Binary files differdeleted file mode 100644 index 08d2e724..00000000 --- a/docs/source/quick_start/img/stm32_8.png +++ /dev/null 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 <https://club.rt-thread.org/ask/tag/5f5f851966917b14.html?type=article>`_ - -- `[HPM-DIY]hpm6750 USB开源协议栈性能对比-cherryusb or tinyusb？ <https://bbs.eeworld.com.cn/thread-1212755-1-1.html>`_ - -- `RT-Thread-CherryUSB移植笔记(一)：APM32F407VGT6 DWC2移植 Port.A Full-Speed + Por.B High-SpeedRT-Thread问答社区 - RT-Thread <https://club.rt-thread.org/ask/article/3e893614c58da7aa.html>`_ - -- `华大HC32F460XXX移植cherryusb协议栈，实现USB CDC ACM_cherryusb移植教程-CSDN博客 <https://blog.csdn.net/u011404840/article/details/142180703>`_ - -- `rt-thread使用cherryusb实现虚拟串口-CSDN博客 <https://blog.csdn.net/weixin_45919462/article/details/143872583>`_ - -- `F1C100S+rtt+CherryUSB的USB HOST成功读到U盘 / 全志 SOC / WhyCan Forum(哇酷开发者社区) <https://whycan.com/t_10289.html>`_ - -- `模仿stm32标准库风格写的库文件（f1c100s/f1c200s)，且已移植了rt-thread、lvgl、fatfs、cherryusb / 全志 SOC / WhyCan Forum(哇酷开发者社区) <https://whycan.com/t_10475.html>`_ - -- `printalyzer-timer: F-Stop enlarging timer and print exposure meter <https://github.com/dektronics/printalyzer-timer>`_ - -- `MiSTeryNano: Atari STE MiSTery core for the Tang Nano 20k FPGA <https://github.com/harbaum/MiSTeryNano>`_ - -- `Cherryuf2 <https://github.com/zhaqian12/Cherryuf2>`_ - -- `PicoPiFi: Driverless RNDIS USB WIFI Dongle <https://github.com/sidd-kishan/PicoPiFi>`_ - -- `phobia: Phobia Motor Controller <https://github.com/rombrew/phobia>`_ - 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 |
