update st rst

38 files changed, 121 insertions, 83 deletions

diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst
index 42830f6c..fff16d48 100644
--- a/docs/source/api/api_device.rst
+++ b/docs/source/api/api_device.rst
@@ -406,7 +406,7 @@ usbd_msc_sector_read
 
 - **sector** 扇区偏移
 - **buffer** 存储读取的数据的指针
-- **length** 读取长度
+- **length** 读取长度，当前为1个扇区的大小
 
 
 usbd_msc_sector_write
@@ -420,7 +420,7 @@ usbd_msc_sector_write
 
 - **sector** 扇区偏移
 - **buffer** 写入数据指针
-- **length** 写入长度
+- **length** 写入长度，当前为1个扇区的大小
 
 UAC
 -----------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 95cb33e0..b78b5a44 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,8 +27,8 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的
    :caption: 快速上手
 
    quick_start/bl702
-   quick_start/stm32f429
-   quick_start/es32f369
+   quick_start/stm32
+   quick_start/es32
    quick_start/rt-thread/rtthread
    quick_start/other_chip
 
diff --git a/docs/source/quick_start/es32f369.rst b/docs/source/quick_start/es32.rst
index f0e0e7a7..f0e0e7a7 100644
--- a/docs/source/quick_start/es32f369.rst
+++ b/docs/source/quick_start/es32.rst
diff --git a/docs/source/quick_start/img/stm32_1.png b/docs/source/quick_start/img/stm32_1.png
new file mode 100644
index 00000000..b91044a5
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_1.png
diff --git a/docs/source/quick_start/img/stm32f429_9.png b/docs/source/quick_start/img/stm32_10.png
index d55b38e7..d55b38e7 100644
--- a/docs/source/quick_start/img/stm32f429_9.png
+++ b/docs/source/quick_start/img/stm32_10.png
diff --git a/docs/source/quick_start/img/stm32f429_11.png b/docs/source/quick_start/img/stm32_11.png
index 3ad5b074..3ad5b074 100644
--- a/docs/source/quick_start/img/stm32f429_11.png
+++ b/docs/source/quick_start/img/stm32_11.png
diff --git a/docs/source/quick_start/img/stm32_12.png b/docs/source/quick_start/img/stm32_12.png
new file mode 100644
index 00000000..84aaffe8
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_12.png
diff --git a/docs/source/quick_start/img/stm32f429_14.png b/docs/source/quick_start/img/stm32_13.png
index d350a776..d350a776 100644
--- a/docs/source/quick_start/img/stm32f429_14.png
+++ b/docs/source/quick_start/img/stm32_13.png
diff --git a/docs/source/quick_start/img/stm32f429_15.png b/docs/source/quick_start/img/stm32_14.png
index e5aa5b19..e5aa5b19 100644
--- a/docs/source/quick_start/img/stm32f429_15.png
+++ b/docs/source/quick_start/img/stm32_14.png
diff --git a/docs/source/quick_start/img/stm32_15.png b/docs/source/quick_start/img/stm32_15.png
new file mode 100644
index 00000000..037bfbdf
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_15.png
diff --git a/docs/source/quick_start/img/stm32_16.png b/docs/source/quick_start/img/stm32_16.png
new file mode 100644
index 00000000..4573f911
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_16.png
diff --git a/docs/source/quick_start/img/stm32_17.png b/docs/source/quick_start/img/stm32_17.png
new file mode 100644
index 00000000..04ff0010
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_17.png
diff --git a/docs/source/quick_start/img/stm32_17_1.png b/docs/source/quick_start/img/stm32_17_1.png
new file mode 100644
index 00000000..1144cbda
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_17_1.png
diff --git a/docs/source/quick_start/img/stm32_17_2.png b/docs/source/quick_start/img/stm32_17_2.png
new file mode 100644
index 00000000..605458e0
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_17_2.png
diff --git a/docs/source/quick_start/img/stm32_17_3.png b/docs/source/quick_start/img/stm32_17_3.png
new file mode 100644
index 00000000..219e9f78
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_17_3.png
diff --git a/docs/source/quick_start/img/stm32_17_4.png b/docs/source/quick_start/img/stm32_17_4.png
new file mode 100644
index 00000000..c9d03c74
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_17_4.png
diff --git a/docs/source/quick_start/img/stm32f429_17.png b/docs/source/quick_start/img/stm32_18.png
index b779f7f7..b779f7f7 100644
--- a/docs/source/quick_start/img/stm32f429_17.png
+++ b/docs/source/quick_start/img/stm32_18.png
diff --git a/docs/source/quick_start/img/stm32_19.png b/docs/source/quick_start/img/stm32_19.png
new file mode 100644
index 00000000..e6508aa8
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_19.png
diff --git a/docs/source/quick_start/img/stm32_2.png b/docs/source/quick_start/img/stm32_2.png
new file mode 100644
index 00000000..671b1b82
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_2.png
diff --git a/docs/source/quick_start/img/stm32f429_18.png b/docs/source/quick_start/img/stm32_20.png
index 977bda82..977bda82 100644
--- a/docs/source/quick_start/img/stm32f429_18.png
+++ b/docs/source/quick_start/img/stm32_20.png
diff --git a/docs/source/quick_start/img/stm32f429_3.png b/docs/source/quick_start/img/stm32_3.png
index 492d6739..492d6739 100644
--- a/docs/source/quick_start/img/stm32f429_3.png
+++ b/docs/source/quick_start/img/stm32_3.png
diff --git a/docs/source/quick_start/img/stm32_3_1.png b/docs/source/quick_start/img/stm32_3_1.png
new file mode 100644
index 00000000..9e42196d
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_3_1.png
diff --git a/docs/source/quick_start/img/stm32f429_4.png b/docs/source/quick_start/img/stm32_4.png
index dd90f5b8..dd90f5b8 100644
--- a/docs/source/quick_start/img/stm32f429_4.png
+++ b/docs/source/quick_start/img/stm32_4.png
diff --git a/docs/source/quick_start/img/stm32_4_1.png b/docs/source/quick_start/img/stm32_4_1.png
new file mode 100644
index 00000000..e81437bc
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_4_1.png
diff --git a/docs/source/quick_start/img/stm32f429_5.png b/docs/source/quick_start/img/stm32_5.png
index 5bec9878..5bec9878 100644
--- a/docs/source/quick_start/img/stm32f429_5.png
+++ b/docs/source/quick_start/img/stm32_5.png
diff --git a/docs/source/quick_start/img/stm32_6.png b/docs/source/quick_start/img/stm32_6.png
new file mode 100644
index 00000000..f0ad9a0b
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_6.png
diff --git a/docs/source/quick_start/img/stm32f429_7.png b/docs/source/quick_start/img/stm32_7.png
index 8aef0bfa..8aef0bfa 100644
--- a/docs/source/quick_start/img/stm32f429_7.png
+++ b/docs/source/quick_start/img/stm32_7.png
diff --git a/docs/source/quick_start/img/stm32f429_8.png b/docs/source/quick_start/img/stm32_8.png
index 08d2e724..08d2e724 100644
--- a/docs/source/quick_start/img/stm32f429_8.png
+++ b/docs/source/quick_start/img/stm32_8.png
diff --git a/docs/source/quick_start/img/stm32_9.png b/docs/source/quick_start/img/stm32_9.png
new file mode 100644
index 00000000..57971d26
--- /dev/null
+++ b/docs/source/quick_start/img/stm32_9.png
diff --git a/docs/source/quick_start/img/stm32f429_1.png b/docs/source/quick_start/img/stm32f429_1.png
deleted file mode 100644
index 7c7152d3..00000000
--- a/docs/source/quick_start/img/stm32f429_1.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_10.png b/docs/source/quick_start/img/stm32f429_10.png
deleted file mode 100644
index d02dcc95..00000000
--- a/docs/source/quick_start/img/stm32f429_10.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_12.png b/docs/source/quick_start/img/stm32f429_12.png
deleted file mode 100644
index ab5b92e6..00000000
--- a/docs/source/quick_start/img/stm32f429_12.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_13.png b/docs/source/quick_start/img/stm32f429_13.png
deleted file mode 100644
index 598a9578..00000000
--- a/docs/source/quick_start/img/stm32f429_13.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_16.png b/docs/source/quick_start/img/stm32f429_16.png
deleted file mode 100644
index 6bd9a684..00000000
--- a/docs/source/quick_start/img/stm32f429_16.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_2.png b/docs/source/quick_start/img/stm32f429_2.png
deleted file mode 100644
index a6c32050..00000000
--- a/docs/source/quick_start/img/stm32f429_2.png
+++ /dev/null
diff --git a/docs/source/quick_start/img/stm32f429_6.png b/docs/source/quick_start/img/stm32f429_6.png
deleted file mode 100644
index a7346c93..00000000
--- a/docs/source/quick_start/img/stm32f429_6.png
+++ /dev/null
diff --git a/docs/source/quick_start/stm32.rst b/docs/source/quick_start/stm32.rst
new file mode 100644
index 00000000..c471448e
--- /dev/null
+++ b/docs/source/quick_start/stm32.rst
@@ -0,0 +1,117 @@
+基于 STM32F1/F4/H7 开发指南
+=============================
+
+本节是基于 STM32 三个系列芯片的使用，涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有：
+
+- usb ip 区别：F1使用 fsdev，F4/H7使用 dwc2
+- dwc2 ip 区别： fs port 和 hs port(带 dma 和不带 dma 功能)
+- F4 与 H7 cache 区别、USB BASE 区别
+
+
+工程样例试用
+-----------------------
+
+默认提供以下 demo 工程：
+
+- F103 使用 fsdev ip
+- F429 主从使用 hs port
+- H7 设备使用 fs port，主机使用 hs port，并且主机带 cache 支持
+
+
+默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。
+
+.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。
+
+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.png
+
+- 配置 usb clock 为 48M
+
+.. figure:: img/stm32_4_1.png
+.. figure:: img/stm32_4.png
+
+- 选择好工程，这里我们选择 keil，设置好 stack 和 heap，如果使用 msc 可以推荐设置大点，然后点击 **Generate Code**。
+
+.. figure:: img/stm32_5.png
+
+- 添加 CherryUSB 必须要的源码（ **usbd_core.c** 、 **usb_dc_dwc2.c** 或者是 **usb_dc_fsdev.c**  ）,以及想要使用的 class 驱动，可以将对应的 class template 添加方便测试。
+
+.. figure:: img/stm32_6.png
+
+- 头文件该加的加
+
+.. figure:: img/stm32_7.png
+
+- 复制一份 **usb_config.h**，这里放到 `Core/Inc` 目录下
+
+.. figure:: img/stm32_8.png
+
+- 如果使用 dwc2 ip，编译选项中需要添加 `CONFIG_USB_DWC2_PORT=xxx`，使用 PA11/PA12 则 **xxx=FS_PORT**，使用 PB14/PB15 则 **xxx=HS_PORT**
+
+.. figure:: img/stm32_9.png
+
+- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。
+.. figure:: img/stm32_10.png
+.. figure:: img/stm32_11.png
+
+- 拷贝 **xxx_msp.c** 中的 **HAL_PCD_MspInit** 函数中的内容到 **usb_dc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化
+
+.. figure:: img/stm32_12.png
+.. figure:: img/stm32_13.png
+.. figure:: img/stm32_14.png
+
+- 调用 template 的内容初始化，就可以使用了
+
+.. figure:: img/stm32_15.png
+
+USB Host 移植要点
+-----------------------
+
+前面 7 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port，所以 fs port 不做支持（没有 dma 你玩什么主机）。
+
+- 添加 CherryUSB 必须要的源码（ **usbh_core.c** 、 **usb_hc_dwc2.c** 、以及 **osal** 目录下的适配层文件）,以及想要使用的 class 驱动（推荐添加除了 hub 之外的所有的 class），可以将对应的 usb host template 添加方便测试。
+
+.. figure:: img/stm32_16.png
+
+- 编译选项中需要添加 `CONFIG_USBHOST_HIGH_WORKQ`,作用是在线程中复位 port。
+
+.. figure:: img/stm32_17.png
+
+- 如果使用的是 F7/H7 这种带 cache功能的，由于 dma 原因，所以需要刷 cache，编译选项中需要添加 `CONFIG_USB_DCACHE_ENABLE`,并实现刷 cache的两个函数。当然，可以不开 dcahe功能，就不需要添加编译选项。
+并且需要搭配 MPU 使用，如果是新手，对 cache不了解，推荐关闭 cache功能。默认 cache 使用 Write Back 属性。
+
+.. figure:: img/stm32_17_1.png
+.. figure:: img/stm32_17_2.png
+.. figure:: img/stm32_17_3.png
+
+.. note:: STM32 usb dma 访问的 ram 只能在 0x24000000 开始的地址，所以，推荐关闭 0x20000000开始的地址。
+
+.. figure:: img/stm32_17_4.png
+
+- 编译器推荐使用 **AC6**。勾选 **Microlib**，并实现 **printf** ，方便后续查看 log。
+.. figure:: img/stm32_10.png
+.. figure:: img/stm32_11.png
+
+- 拷贝 **xxx_msp.c** 中的 **HAL_HCD_MspInit** 函数中的内容到 **usb_hc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化
+
+.. figure:: img/stm32_12.png
+.. figure:: img/stm32_13.png
+.. figure:: img/stm32_19.png
+
+- 调用 **usbh_initialize** 以及 os 需要的启动线程的函数即可使用
+
+.. figure:: img/stm32_18.png
+
+- 如果使用 **msc**，并且带文件系统，需要自行添加文件系统文件了，对应的 porting 编写参考 **fatfs_usbh.c** 文件。
+
+.. figure:: img/stm32_20.png
\ No newline at end of file
diff --git a/docs/source/quick_start/stm32f429.rst b/docs/source/quick_start/stm32f429.rst
deleted file mode 100644
index fcb331c0..00000000
--- a/docs/source/quick_start/stm32f429.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-基于 STM32F429 开发指南
-=========================
-
-本节是基于 stm32f429 开发板的使用，仓库中已经默认有主从机的 demo ，其余 stm32 系列，基本类似，所以后续不再赘述。
-
-.. note:: stm32的 porting 使用寄存器编写，所以 st 的 usb 库没有一丁点用，想删就删。（ps 主机还没用寄存器，所以删不了）
-
-工程样例试用
------------------------
-
-默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32f429igt6.ioc** 文件，双击打开，点击 **Generate Code** 即可。
-
-
-USB Device 移植要点
------------------------
-
-- 使用 **stm32cubemx** 创建工程，配置基本的 RCC、UART (作为log使用)
-
-.. figure:: img/stm32f429_1.png
-.. figure:: img/stm32f429_2.png
-
-- 如果使用 PA11 和 PA12，勾选 **USB_OTG_FS**，否则勾选  **USB_OTG_HS**，并按下面进行配置，我们只需要开启中断和 gpio 配置，其他配置对我们没用。
-
-.. figure:: img/stm32f429_3.png
-
-- 配置 usb clock 为 48M
-
-.. figure:: img/stm32f429_4.png
-
-- 选择好工程，这里我们选择 keil，设置好 stack 和 heap，如果使用 msc 可以推荐设置大点，然后点击 **Generate Code**。
-
-.. figure:: img/stm32f429_5.png
-
-- 添加 CherryUSB 必须要的源码（ **usbd_core.c** 、 **usb_dc_synopsys.c** ）,以及想要使用的 class 驱动，可以将对应的 class template 添加方便测试。
-
-.. figure:: img/stm32f429_6.png
-
-- 头文件该加的加
-
-.. figure:: img/stm32f429_7.png
-
-- 复制一份 **usb_config.h**，这里放到 `Core/Inc` 目录下
-
-.. figure:: img/stm32f429_8.png
-
-- 如果使用 PB14 和 PB15，并且仅使用 FS 模式，编译选项中添加 `CONFIG_USB_HS_IN_FULL`，剩下的按照下图配置，编译器推荐使用 **AC6**。打开 **Microlib**，后续 **printf** 使用
-
-.. figure:: img/stm32f429_9.png
-.. figure:: img/stm32f429_10.png
-
-- 实现 printf，如果关闭 usb 的log，可以不实现
-
-.. figure:: img/stm32f429_11.png
-
-- 拷贝 **xxx_msp.c** 中的 **HAL_PCD_MspInit** 函数中的内容到 **usb_dc_low_level_init** 函数中，屏蔽 st 生成的 usb 中断函数和 usb 初始化
-
-.. figure:: img/stm32f429_12.png
-.. figure:: img/stm32f429_13.png
-.. figure:: img/stm32f429_14.png
-.. figure:: img/stm32f429_15.png
-
-- 主函数屏蔽 **stm32cubemx** 生成的中断函数和 usb 初始化，然后调用 template 的内容初始化，就可以使用了
-
-USB Host 移植要点
------------------------
-
-前面 9 步与 Device 一样，目前 Host 暂时用的 st 的 hal 库，后面有时间了再整理成寄存器的并进行优化。
-
-- 添加 CherryUSB 必须要的源码（ **usbh_core.c** 、 **usb_hc_synopsys.c** 、以及 **osal** 目录下的适配层文件）,以及想要使用的 class 驱动（推荐添加除了 hub 之外的所有的 class），可以将对应的 usb host template 添加方便测试。
-
-.. figure:: img/stm32f429_16.png
-
-- 主函数屏蔽 st 的 usb 初始化，屏蔽 st 生成的 usb 中断函数，然后调用 **usbh_initialize** 以及 os 需要的启动线程的函数即可使用
-
-.. figure:: img/stm32f429_17.png
-
-- 如果使用 **msc**，并且带文件系统，需要自行添加文件系统文件了，对应的 porting 编写参考 **fatfs_usbh.c** 文件。
-
-.. figure:: img/stm32f429_18.png
\ No newline at end of file