docs: release v1.6.0

Signed-off-by: sakumisu <[email protected]>

Author: sakumisu

Kconfig.rttpkg

@@ -504,6 +504,8 @@ if PKG_USING_CHERRYUSB
 
         config PKG_USING_CHERRYUSB_LATEST_VERSION
             bool "latest"
+        config PKG_USING_CHERRYUSB_V010600
+            bool "v1.6.0"
         config PKG_USING_CHERRYUSB_V010503
             bool "v1.5.3.99"
         config PKG_USING_CHERRYUSB_V010502
@@ -523,6 +525,7 @@ if PKG_USING_CHERRYUSB
     config PKG_CHERRYUSB_VER
        string
        default "latest"    if PKG_USING_CHERRYUSB_LATEST_VERSION
+       default "v1.6.0"   if PKG_USING_CHERRYUSB_V010600
        default "v1.5.3.99"   if PKG_USING_CHERRYUSB_V010503
        default "v1.5.2"   if PKG_USING_CHERRYUSB_V010502
        default "v1.5.0"   if PKG_USING_CHERRYUSB_V010500

SConscript

@@ -280,7 +280,7 @@ if GetDepend(['PKG_CHERRYUSB_HOST']):
             LIBS = ['libxhci_a32_softfp_neon.a']
 
     if GetDepend(['PKG_CHERRYUSB_HOST_RP2040']):
-    	path += [cwd + '/port/rp2040']
+        path += [cwd + '/port/rp2040']
         src += Glob('port/rp2040/usb_hc_rp2040.c')
 
     if GetDepend(['PKG_CHERRYUSB_HOST_CDC_ACM']):

VERSION

@@ -1,5 +1,5 @@
 VERSION_MAJOR = 1
-VERSION_MINOR = 5
-PATCHLEVEL = 3
+VERSION_MINOR = 6
+PATCHLEVEL = 0
 VERSION_TWEAK = 0
 EXTRAVERSION = 0

common/usb_version.h

@@ -15,7 +15,7 @@
 #undef CHERRYUSB_VERSION_STR
 #endif
 
-#define CHERRYUSB_VERSION     0x010503
-#define CHERRYUSB_VERSION_STR "v1.5.3"
+#define CHERRYUSB_VERSION     0x010600
+#define CHERRYUSB_VERSION_STR "v1.6.0"
 
 #endif

docs/source/conf.py

@@ -6,8 +6,8 @@
 copyright = '2022 ~ 2025, sakumisu'
 author = 'sakumisu'
 
-release = '1.5.3'
-version = '1.5.3'
+release = '1.6.0'
+version = '1.6.0'
 
 # -- General configuration
 

docs/source/demo/usbh_serial.rst

@@ -87,15 +87,17 @@ Serial 框架当前支持 cdc acm, ftdi, cp210x, ch34x, pl2303，gsm 驱动。
 
     usbh_serial_close(serial);
 
-.. note:: 需要注意，例程中使用的是比较简单的先发送后读取的方式，因此发送的总长度不可以超过 CONFIG_USBHOST_SERIAL_RX_SIZE，正常使用 TX/RX 请分开进行。
+.. caution:: 需要注意，例程中使用的是比较简单的先发送后读取的方式，因此发送的总长度不可以超过 CONFIG_USBHOST_SERIAL_RX_SIZE，正常使用 TX/RX 请分开进行。
 
 用户需要考虑以下三种场景：
 
-- USB2TTL 设备 + 启用了波特率，这种情况下需要使用 `usbh_serial_write` 和 `usbh_serial_read` 进行收发数据， **并且 read 操作需要及时，防止 ringbuf 数据溢出而丢包**；
+- 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 设备请使用第一种场景**。
+- 纯 USB 设备 + 启动波特率，同 1，但是接收速率会打折扣（因为多了一层 ringbuf）。此时也不可以使用 `usbh_serial_cdc_write_async` 和 `usbh_serial_cdc_read_async`。 **如果是 GSM 设备请使用第一种场景**。
+
+.. note:: 简单来说就是，如果接收数据需要用到ringbuf转一层的，请使用第一种场景。
 
 .. code-block:: C
 

docs/source/index.rst

@@ -57,6 +57,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的
    quick_start/transplant
    quick_start/rtthread
    quick_start/q&a
+   quick_start/migration
    quick_start/share
    quick_start/opensource
 

docs/source/quick_start/migration.rst

@@ -0,0 +1,63 @@
+部分改动迁移指南
+========================
+
+
+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, &param_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);

docs/source/version.rst

@@ -162,4 +162,21 @@ v1.5.3
 - hpmicro、chipidea dcache 支持
 - idf host msc 支持
 - otg 框架重构，当前 port 仅支持 hpmicro
-- CI 编译功能，支持 hpmicro/espressif/bouffalolab
+- 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 速度设置

port/musb/README.md

@@ -9,6 +9,7 @@
 ### TI
 
 - MSP432E4x
+- TM4Cx
 
 ### Bekencorp