Merge branch 'refactor/esp_driver_sdspi' into 'master'

refactor(sdspi): place sdspi driver into a new component See merge request espressif/esp-idf!27225
2023-11-20 19:24:10 +08:00
parent 3334ec54fa b8aba80172
commit 712e7756f5
21 changed files with 107 additions and 29 deletions
--- a/components/driver/CMakeLists.txt
+++ b/components/driver/CMakeLists.txt
@@ -16,7 +16,6 @@ set(includes "include"
             "parlio/include"
             "rmt/include"
             "sdio_slave/include"
-             "sdspi/include"
             "sigma_delta/include"
             "temperature_sensor/include"
             "touch_sensor/include"
@@ -113,14 +112,6 @@ if(CONFIG_SOC_SDM_SUPPORTED)
                     "deprecated/sigma_delta_legacy.c")
 endif()

-# SDSPI related source files
-if(CONFIG_SOC_GPSPI_SUPPORTED)
-    list(APPEND srcs "sdspi/sdspi_crc.c"
-                     "sdspi/sdspi_host.c"
-                     "sdspi/sdspi_transaction.c")
-endif()
-
-
 # Temperature Sensor related source files
 if(CONFIG_SOC_TEMP_SENSOR_SUPPORTED)
    list(APPEND srcs "temperature_sensor/temperature_sensor.c"
@@ -173,7 +164,7 @@ else()
                           # for backward compatibility, the driver component needs to
                           # have a public dependency on other "esp_driver_foo" components
                                    esp_driver_gpio esp_driver_pcnt esp_driver_gptimer esp_driver_spi esp_driver_mcpwm
-                                    esp_driver_sdmmc esp_driver_ana_cmpr esp_driver_i2s
+                                    esp_driver_sdmmc esp_driver_sdspi esp_driver_ana_cmpr esp_driver_i2s
                           LDFRAGMENTS ${ldfragments}
                          )
 endif()
--- a/components/esp_driver_sdmmc/README.md
+++ b/components/esp_driver_sdmmc/README.md
@@ -0,0 +1,19 @@
+# SDMMC Host Driver
+
+SD Host side related components are:
+- `sdmmc`
+- `esp_driver_sdmmc` (current component)
+- `esp_driver_sdspi`
+
+For relationship and dependency among these components, see [SD Host Side Related Component Architecture](../sdmmc/README.md).
+
+`esp_driver_sdmmc` components holds SDMMC Host driver for ESP SDMMC peripheral, this driver provides APIs to help you:
+- do SD transactions (under SD mode) via ESP SDMMC peripheral.
+- tune ESP SDMMC hardware configurations, such as clock frequency, bus width, etc.
+- ...
+
+You can
+- use this driver to implement `sdmmc` protocol interfaces
+- directly use `esp_driver_sdmmc` APIs
+
+to communicate with SD slave devices under SD mode.
--- a/components/esp_driver_sdspi/CMakeLists.txt
+++ b/components/esp_driver_sdspi/CMakeLists.txt
@@ -0,0 +1,15 @@
+set(srcs)
+
+set(public_include "include")
+
+if(CONFIG_SOC_GPSPI_SUPPORTED)
+    list(APPEND srcs "src/sdspi_crc.c"
+                     "src/sdspi_host.c"
+                     "src/sdspi_transaction.c")
+endif()
+
+idf_component_register(SRCS ${srcs}
+                       INCLUDE_DIRS ${public_include}
+                       REQUIRES sdmmc esp_driver_spi esp_driver_gpio
+                       PRIV_REQUIRES esp_timer
+                      )
--- a/components/esp_driver_sdspi/README.md
+++ b/components/esp_driver_sdspi/README.md
@@ -0,0 +1,19 @@
+# SDSPI Host Driver
+
+SD Host side related components are:
+- `sdmmc`
+- `esp_driver_sdmmc`
+- `esp_driver_sdspi` (current component)
+
+For relationship and dependency among these components, see [SD Host Side Related Component Architecture](../sdmmc/README.md).
+
+`esp_driver_sdspi` components is a driver based on ESP GPSPI master driver to help you:
+- do SD transactions (under SDSPI mode) via ESP GPSPI peripheral.
+- tune ESP GPSPI hardware configurations, such as clock frequency, bus width, etc.
+- ...
+
+You can
+- use this driver to implement `sdmmc` protocol interfaces
+- directly use `esp_driver_sdspi` APIs
+
+to communicate with SD slave devices under SDSPI mode.
--- a/components/esp_driver_sdspi/include/driver/sdspi_host.h
+++ b/components/esp_driver_sdspi/include/driver/sdspi_host.h
@@ -9,7 +9,7 @@
 #include <stdint.h>
 #include <stddef.h>
 #include "esp_err.h"
-#include "driver/sdmmc_types.h"
+#include "sd_protocol_types.h"
 #include "driver/gpio.h"
 #include "driver/spi_master.h"

--- a/components/esp_driver_sdspi/src/sdspi_crc.c
+++ b/components/esp_driver_sdspi/src/sdspi_crc.c
--- a/components/esp_driver_sdspi/src/sdspi_crc.h
+++ b/components/esp_driver_sdspi/src/sdspi_crc.h
--- a/components/esp_driver_sdspi/src/sdspi_host.c
+++ b/components/esp_driver_sdspi/src/sdspi_host.c
@@ -13,7 +13,7 @@
 #include "esp_log.h"
 #include "esp_heap_caps.h"
 #include "driver/gpio.h"
-#include "driver/sdmmc_defs.h"
+#include "sd_protocol_defs.h"
 #include "driver/sdspi_host.h"
 #include "sdspi_private.h"
 #include "sdspi_crc.h"
--- a/components/esp_driver_sdspi/src/sdspi_private.h
+++ b/components/esp_driver_sdspi/src/sdspi_private.h
--- a/components/esp_driver_sdspi/src/sdspi_transaction.c
+++ b/components/esp_driver_sdspi/src/sdspi_transaction.c
@@ -8,9 +8,8 @@
 #include "esp_err.h"
 #include "esp_log.h"
 #include "sys/lock.h"
-#include "driver/sdmmc_types.h"
-#include "driver/sdmmc_defs.h"
-#include "driver/sdmmc_types.h"
+#include "sd_protocol_defs.h"
+#include "sd_protocol_types.h"
 #include "sdspi_private.h"
 #include "sdspi_crc.h"

--- a/components/fatfs/CMakeLists.txt
+++ b/components/fatfs/CMakeLists.txt
@@ -22,7 +22,7 @@ else()

    list(APPEND include_dirs "vfs")

-    list(APPEND requires "sdmmc" "driver") # `driver` will be replaced with `esp_driver_sdspi`
+    list(APPEND requires "sdmmc" "esp_driver_sdmmc" "esp_driver_sdspi")

    list(APPEND priv_requires "vfs" "esp_driver_gpio")
 endif()
--- a/components/sdmmc/README.md
+++ b/components/sdmmc/README.md
@@ -0,0 +1,35 @@
+# SDMMC Protocol Layer Driver
+
+## SD Host Side Related Component Architecture
+
+### Architecture Graph
+
+                            ┌─────────────────────────────────────────────┐
+                            │                                             │
+                            │  SD Protocol Layer Driver: components/sdmmc │
+                            │                                             │
+                            └──────────▲────────────────────▲─────────────┘
+                                       │                    │
+                                       │                    │
+                            Implements │                    │ Implements
+                                       │                    │
+    ┌──────────────────────────────────┴─────┐         ┌────┴───────────────────────────────────┐
+    │                                        │         │                                        │
+    │Host Driver: components/esp_driver_sdmmc│         │Host Driver: components/esp_driver_sdspi│
+    │                                        │         │                                        │
+    └────────────────────────────────────────┘         └────────────────────────────────────────┘
+
+### Components
+
+- `sdmmc`: SD protocol layer driver, it provides SD protocol related definitions and interfaces. With corresponding implementation drivers, `sdmmc` APIs can help you:
+  - send commands to slave devices
+  - send and receive data
+  - handle error conditions within the bus
+- `esp_driver_sdmmc`: SDMMC Host driver for ESP SDMMC hardware, it implements the `sdmmc` protocol interfaces.
+- `esp_driver_sdspi`: SDSPI Host driver for ESP GPSPI hardware, it implements the `sdmmc` protocol interfaces.
+
+### Dependency
+
+- `esp_driver_sdmmc` is in driver layer (G2), it relies on `sdmmc`
+- `esp_driver_sdspi` is in driver layer (G2), it relies on `sdmmc`
+- `sdmmc` does not and should not rely on `esp_driver_sdmmc` or `esp_driver_sdspi`. Though `sdmmc` is independent, it still stays in G2.
--- a/components/vfs/test_apps/main/CMakeLists.txt
+++ b/components/vfs/test_apps/main/CMakeLists.txt
@@ -7,6 +7,6 @@ set(src "test_app_main.c" "test_vfs_access.c"

 idf_component_register(SRCS ${src}
                       PRIV_INCLUDE_DIRS .
-                       PRIV_REQUIRES test_utils vfs fatfs spiffs unity lwip wear_levelling cmock
+                       PRIV_REQUIRES test_utils vfs fatfs spiffs unity lwip wear_levelling cmock driver
                       WHOLE_ARCHIVE
                       )
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -93,7 +93,7 @@ INPUT = \
    $(PROJECT_PATH)/components/esp_driver_sdmmc/include/driver/sdmmc_default_configs.h \
    $(PROJECT_PATH)/components/esp_driver_sdmmc/include/driver/sdmmc_host.h \
    $(PROJECT_PATH)/components/esp_driver_sdmmc/include/driver/sdmmc_types.h \
-    $(PROJECT_PATH)/components/driver/sdspi/include/driver/sdspi_host.h \
+    $(PROJECT_PATH)/components/esp_driver_sdspi/include/driver/sdspi_host.h \
    $(PROJECT_PATH)/components/esp_driver_spi/include/driver/spi_common.h \
    $(PROJECT_PATH)/components/esp_driver_spi/include/driver/spi_master.h \
    $(PROJECT_PATH)/components/esp_driver_spi/include/driver/spi_slave_hd.h \
--- a/docs/en/api-reference/storage/sdmmc.rst
+++ b/docs/en/api-reference/storage/sdmmc.rst
@@ -8,7 +8,7 @@ Overview

 The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol level driver built on top of SDMMC and SD SPI host drivers.

-SDMMC and SD SPI host drivers (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h` and :component_file:`driver/sdspi/include/driver/sdspi_host.h`) provide API functions for:
+SDMMC and SD SPI host drivers (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h` and :component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`) provide API functions for:

 - Sending commands to slave devices
 - Sending and receiving data
--- a/docs/zh_CN/api-reference/storage/sdmmc.rst
+++ b/docs/zh_CN/api-reference/storage/sdmmc.rst
@@ -8,7 +8,7 @@ SD/SDIO/MMC 驱动程序

 SD/SDIO/MMC 驱动是一种基于 SDMMC 和 SD SPI 主机驱动的协议级驱动程序，目前已支持 SD 存储器、SDIO 卡和 eMMC 芯片。

-SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h` 和 :component_file:`driver/sdspi/include/driver/sdspi_host.h`）为以下功能提供 API：
+SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h` 和 :component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`）为以下功能提供 API：

 - 发送命令至从设备
 - 接收和发送数据
--- a/examples/storage/.build-test-rules.yml
+++ b/examples/storage/.build-test-rules.yml
@@ -10,11 +10,11 @@ examples/storage/custom_flash_driver:

 examples/storage/emmc:
  depends_components:
-    - sdmmc
-    - driver # `driver` will be replaced with `esp_driver_sdspi`
    - fatfs
    - vfs
+    - sdmmc
    - esp_driver_sdmmc
+    - esp_driver_sdspi
  enable:
    - if: IDF_TARGET == "esp32s3"
      reason: only support on esp32s3
@@ -134,7 +134,7 @@ examples/storage/sd_card/sdspi:
  depends_components:
    - vfs
    - sdmmc
-    - driver # To be updated to `esp_driver_sdspi`
+    - esp_driver_sdspi
  disable:
    - if: SOC_GPSPI_SUPPORTED != 1
  disable_test:
--- a/tools/test_apps/.build-test-rules.yml
+++ b/tools/test_apps/.build-test-rules.yml
@@ -99,7 +99,7 @@ tools/test_apps/storage/sdmmc_console:
  depends_components:
    - sdmmc
    - esp_driver_sdmmc
-    - driver # driver will be replaced with esp_driver_sdspi
+    - esp_driver_sdspi

 tools/test_apps/system/bootloader_sections:
  disable:
--- a/tools/test_apps/storage/sdmmc_console/components/cmd_sdmmc/CMakeLists.txt
+++ b/tools/test_apps/storage/sdmmc_console/components/cmd_sdmmc/CMakeLists.txt
@@ -1,5 +1,6 @@
 idf_component_register(SRCS cmd_sdmmc.c
                       INCLUDE_DIRS .
-                       PRIV_REQUIRES console sdmmc esp_driver_sdmmc esp_driver_gpio sdmmc_test_board
-                       driver # driver will be replaced with esp_driver_sdspi later
+                       PRIV_REQUIRES console sdmmc esp_driver_sdmmc esp_driver_gpio esp_driver_sdspi
+                                     sdmmc_test_board
+
 )
--- a/tools/test_apps/storage/sdmmc_console/components/sdmmc_test_board/CMakeLists.txt
+++ b/tools/test_apps/storage/sdmmc_console/components/sdmmc_test_board/CMakeLists.txt
@@ -1,3 +1,3 @@
 idf_component_register(SRCS sdmmc_test_board.c sdmmc_test_board_defs.c
                       INCLUDE_DIRS include
-                       PRIV_REQUIRES sdmmc driver)
+                       PRIV_REQUIRES sdmmc esp_driver_sdmmc esp_driver_sdspi)
--- a/tools/test_apps/storage/sdmmc_console/components/sdmmc_tests/CMakeLists.txt
+++ b/tools/test_apps/storage/sdmmc_console/components/sdmmc_tests/CMakeLists.txt
@@ -3,8 +3,7 @@ idf_component_register(
        sdmmc_test_cd_wp_common.c
        sdmmc_test_rw_common.c
     PRIV_REQUIRES
-          sdmmc esp_driver_sdmmc sdmmc_test_board esp_timer unity test_utils
-          driver # driver will be replaced with esp_driver_sdspi later
+          sdmmc esp_driver_sdmmc esp_driver_sdspi sdmmc_test_board esp_timer unity test_utils
     WHOLE_ARCHIVE TRUE
 )