docs: release v1.6.0v1.6.0

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

5 files changed, 89 insertions, 6 deletions

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6269e54d..6174f623 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -6,8 +6,8 @@ project = 'CherryUSB'
 copyright = '2022 ~ 2025, sakumisu'
 author = 'sakumisu'
 
-release = '1.5.3'
-version = '1.5.3'
+release = '1.6.0'
+version = '1.6.0'
 
 # -- General configuration
 
diff --git a/docs/source/demo/usbh_serial.rst b/docs/source/demo/usbh_serial.rst
index 3e06561a..619545c6 100644
--- a/docs/source/demo/usbh_serial.rst
+++ b/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
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8cdb78cd..831de0a1 100644
--- a/docs/source/index.rst
+++ b/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
 
diff --git a/docs/source/quick_start/migration.rst b/docs/source/quick_start/migration.rst
new file mode 100644
index 00000000..10f2ef7e
--- /dev/null
+++ b/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);
diff --git a/docs/source/version.rst b/docs/source/version.rst
index 6de257e9..5c6e23e7 100644
--- a/docs/source/version.rst
+++ b/docs/source/version.rst
@@ -162,4 +162,21 @@ v1.5.3
 - hpmicro、chipidea dcache 支持
 - idf host msc 支持
 - otg 框架重构，当前 port 仅支持 hpmicro
-- CI 编译功能，支持 hpmicro/espressif/bouffalolab
\ No newline at end of file
+- 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