From 384d61f1560738a79784b192b905075ab05d7d85 Mon Sep 17 00:00:00 2001 From: Matus Fabo Date: Mon, 30 May 2022 09:23:27 +0200 Subject: [PATCH] remove: sdspi_host deprecated api add: migration guide documentation --- components/driver/include/driver/sdspi_host.h | 54 ------------------- components/driver/sdspi_host.c | 50 ----------------- .../driver/test/test_sdmmc_sdspi_init.cpp | 4 +- components/fatfs/vfs/esp_vfs_fat.h | 2 - components/fatfs/vfs/vfs_fat_sdmmc.c | 35 +++--------- components/sdmmc/test/test_sd.c | 24 --------- docs/en/migration-guides/storage.rst | 6 +++ examples/storage/sd_card/sdspi/README.md | 2 +- 8 files changed, 16 insertions(+), 161 deletions(-) diff --git a/components/driver/include/driver/sdspi_host.h b/components/driver/include/driver/sdspi_host.h index a5d942e9d8..61f29811dd 100644 --- a/components/driver/include/driver/sdspi_host.h +++ b/components/driver/include/driver/sdspi_host.h @@ -187,60 +187,6 @@ esp_err_t sdspi_host_io_int_enable(sdspi_dev_handle_t handle); */ esp_err_t sdspi_host_io_int_wait(sdspi_dev_handle_t handle, TickType_t timeout_ticks); -/******************************************************************************* - * Deprecated APIs - ******************************************************************************/ - -/** - * Extra configuration for SPI host. - * - * @deprecated Use `sdspi_device_config_t` and corresponding `sdspi_host_init_device()` instead. - */ -typedef struct { - gpio_num_t gpio_cs; ///< GPIO number of CS signal - gpio_num_t gpio_cd; ///< GPIO number of card detect signal - gpio_num_t gpio_wp; ///< GPIO number of write protect signal - gpio_num_t gpio_int; ///< GPIO number of interrupt line (input) for SDIO card. - gpio_num_t gpio_miso; ///< GPIO number of MISO signal. - gpio_num_t gpio_mosi; ///< GPIO number of MOSI signal. - gpio_num_t gpio_sck; ///< GPIO number of SCK signal. - int dma_channel; ///< DMA channel to be used by SPI driver (1 or 2). -} sdspi_slot_config_t; - -/** - * Macro defining default configuration of SPI host - */ -#define SDSPI_SLOT_CONFIG_DEFAULT() {\ - .gpio_cs = GPIO_NUM_13, \ - .gpio_cd = SDSPI_SLOT_NO_CD, \ - .gpio_wp = SDSPI_SLOT_NO_WP, \ - .gpio_int = GPIO_NUM_NC, \ - .gpio_miso = GPIO_NUM_2, \ - .gpio_mosi = GPIO_NUM_15, \ - .gpio_sck = GPIO_NUM_14, \ - .dma_channel = SDSPI_DEFAULT_DMA, \ -} - -/** -* @brief Initialize SD SPI driver for the specific SPI controller -* -* @note This function is not thread safe -* -* @note The SDIO over sdspi needs an extra interrupt line. Call ``gpio_install_isr_service()`` before this function. -* -* @param slot SPI controller to use (SPI2_HOST or SPI3_HOST) -* @param slot_config pointer to slot configuration structure - -* @deprecated Use `sdspi_host_init_device` instead. -* -* @return -* - ESP_OK on success -* - ESP_ERR_INVALID_ARG if sdspi_init_slot has invalid arguments -* - ESP_ERR_NO_MEM if memory can not be allocated -* - other errors from the underlying spi_master and gpio drivers -*/ -esp_err_t sdspi_host_init_slot(int slot, const sdspi_slot_config_t* slot_config); - #ifdef __cplusplus } #endif diff --git a/components/driver/sdspi_host.c b/components/driver/sdspi_host.c index fd9749a33d..a09a63595d 100644 --- a/components/driver/sdspi_host.c +++ b/components/driver/sdspi_host.c @@ -957,53 +957,3 @@ esp_err_t sdspi_host_io_int_wait(sdspi_dev_handle_t handle, TickType_t timeout_t } return ESP_OK; } - -//Deprecated, make use of new sdspi_host_init_device -esp_err_t sdspi_host_init_slot(int slot, const sdspi_slot_config_t* slot_config) -{ - esp_err_t ret = ESP_OK; - if (get_slot_info(slot) != NULL) { - ESP_LOGE(TAG, "Bus already initialized. Call `sdspi_host_init_dev` to attach an sdspi device to an initialized bus."); - return ESP_ERR_INVALID_STATE; - } - - //Assume the slot number equals to the host id. - spi_host_device_t host_id = slot; - // Initialize SPI bus - spi_bus_config_t buscfg = { - .miso_io_num = slot_config->gpio_miso, - .mosi_io_num = slot_config->gpio_mosi, - .sclk_io_num = slot_config->gpio_sck, - .quadwp_io_num = GPIO_NUM_NC, - .quadhd_io_num = GPIO_NUM_NC - }; - ret = spi_bus_initialize(host_id, &buscfg, - slot_config->dma_channel); - if (ret != ESP_OK) { - ESP_LOGE(TAG, "spi_bus_initialize failed with rc=0x%x", ret); - return ret; - } - - sdspi_dev_handle_t sdspi_handle; - sdspi_device_config_t dev_config = { - .host_id = host_id, - .gpio_cs = slot_config->gpio_cs, - .gpio_cd = slot_config->gpio_cd, - .gpio_wp = slot_config->gpio_wp, - .gpio_int = slot_config->gpio_int, - }; - ret = sdspi_host_init_device(&dev_config, &sdspi_handle); - if (ret != ESP_OK) { - goto cleanup; - } - if (sdspi_handle != (int)host_id) { - ESP_LOGE(TAG, "The deprecated sdspi_host_init_slot should be called before all other devices on the specified bus."); - sdspi_host_remove_device(sdspi_handle); - ret = ESP_ERR_INVALID_STATE; - goto cleanup; - } - return ESP_OK; -cleanup: - spi_bus_free(slot); - return ret; -} diff --git a/components/driver/test/test_sdmmc_sdspi_init.cpp b/components/driver/test/test_sdmmc_sdspi_init.cpp index 31e9fc515d..f34114aaba 100644 --- a/components/driver/test/test_sdmmc_sdspi_init.cpp +++ b/components/driver/test/test_sdmmc_sdspi_init.cpp @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -27,8 +27,6 @@ static void test_initializers() #endif sdmmc_host_t sdspi_host = SDSPI_HOST_DEFAULT(); (void) sdspi_host; - sdspi_slot_config_t sdspi_slot = SDSPI_SLOT_CONFIG_DEFAULT(); - (void) sdspi_slot; sdspi_device_config_t sdspi_dev = SDSPI_DEVICE_CONFIG_DEFAULT(); (void) sdspi_dev; } diff --git a/components/fatfs/vfs/esp_vfs_fat.h b/components/fatfs/vfs/esp_vfs_fat.h index 4925e758fc..3dc0f67075 100644 --- a/components/fatfs/vfs/esp_vfs_fat.h +++ b/components/fatfs/vfs/esp_vfs_fat.h @@ -116,8 +116,6 @@ typedef esp_vfs_fat_mount_config_t esp_vfs_fat_sdmmc_mount_config_t; * @param slot_config Pointer to structure with slot configuration. * For SDMMC peripheral, pass a pointer to sdmmc_slot_config_t * structure initialized using SDMMC_SLOT_CONFIG_DEFAULT. - * (Deprecated) For SPI peripheral, pass a pointer to sdspi_slot_config_t - * structure initialized using SDSPI_SLOT_CONFIG_DEFAULT(). * @param mount_config pointer to structure with extra parameters for mounting FATFS * @param[out] out_card if not NULL, pointer to the card information structure will be returned via this argument * @return diff --git a/components/fatfs/vfs/vfs_fat_sdmmc.c b/components/fatfs/vfs/vfs_fat_sdmmc.c index 0782a8f7f1..fa8d66ab69 100644 --- a/components/fatfs/vfs/vfs_fat_sdmmc.c +++ b/components/fatfs/vfs/vfs_fat_sdmmc.c @@ -178,11 +178,6 @@ static esp_err_t init_sdmmc_host(int slot, const void *slot_config, int *out_slo return sdmmc_host_init_slot(slot, (const sdmmc_slot_config_t*) slot_config); } -static esp_err_t init_sdspi_host_deprecated(int slot, const void *slot_config, int *out_slot) -{ - *out_slot = slot; - return sdspi_host_init_slot(slot, (const sdspi_slot_config_t*) slot_config); -} esp_err_t esp_vfs_fat_sdmmc_mount(const char* base_path, const sdmmc_host_t* host_config, @@ -203,28 +198,14 @@ esp_err_t esp_vfs_fat_sdmmc_mount(const char* base_path, return err; } - if (host_config->flags == SDMMC_HOST_FLAG_SPI) { - //Deprecated API - //the init() function is usually empty, doesn't require any deinit to revert it - err = (*host_config->init)(); - CHECK_EXECUTE_RESULT(err, "host init failed"); - err = init_sdspi_host_deprecated(host_config->slot, slot_config, &card_handle); - CHECK_EXECUTE_RESULT(err, "slot init failed"); - //Set `host_inited` to true to indicate that host_config->deinit() needs - //to be called to revert `init_sdspi_host_deprecated`; set `card_handle` - //to -1 to indicate that no other deinit is required. - host_inited = true; - card_handle = -1; - } else { - err = (*host_config->init)(); - CHECK_EXECUTE_RESULT(err, "host init failed"); - //deinit() needs to be called to revert the init - host_inited = true; - //If this failed (indicated by card_handle != -1), slot deinit needs to called() - //leave card_handle as is to indicate that (though slot deinit not implemented yet. - err = init_sdmmc_host(host_config->slot, slot_config, &card_handle); - CHECK_EXECUTE_RESULT(err, "slot init failed"); - } + err = (*host_config->init)(); + CHECK_EXECUTE_RESULT(err, "host init failed"); + //deinit() needs to be called to revert the init + host_inited = true; + //If this failed (indicated by card_handle != -1), slot deinit needs to called() + //leave card_handle as is to indicate that (though slot deinit not implemented yet. + err = init_sdmmc_host(host_config->slot, slot_config, &card_handle); + CHECK_EXECUTE_RESULT(err, "slot init failed"); // probe and initialize card err = sdmmc_card_init(host_config, card); diff --git a/components/sdmmc/test/test_sd.c b/components/sdmmc/test/test_sd.c index 0a04d3166a..642ed37a3b 100644 --- a/components/sdmmc/test/test_sd.c +++ b/components/sdmmc/test/test_sd.c @@ -249,40 +249,16 @@ static void probe_spi(int freq_khz, int pin_miso, int pin_mosi, int pin_sck, int sd_test_board_power_off(); } -static void probe_spi_legacy(int freq_khz, int pin_miso, int pin_mosi, int pin_sck, int pin_cs) -{ - sd_test_board_power_on(); - sdmmc_host_t config = SDSPI_HOST_DEFAULT(); - sdspi_slot_config_t slot_config = SDSPI_SLOT_CONFIG_DEFAULT(); - slot_config.gpio_miso = pin_miso; - slot_config.gpio_mosi = pin_mosi; - slot_config.gpio_sck = pin_sck; - slot_config.gpio_cs = pin_cs; - slot_config.dma_channel = SPI_DMA_CH_AUTO; - - TEST_ESP_OK(sdspi_host_init()); - TEST_ESP_OK(sdspi_host_init_slot(config.slot, &slot_config)); - - probe_core(config.slot); - - TEST_ESP_OK(sdspi_host_deinit()); - - TEST_ESP_OK(spi_bus_free(config.slot)); - - sd_test_board_power_off(); -} TEST_CASE("probe SD in SPI mode", "[sd][test_env=UT_T1_SPIMODE]") { probe_spi(SDMMC_FREQ_DEFAULT, SDSPI_TEST_MISO_PIN, SDSPI_TEST_MOSI_PIN, SDSPI_TEST_SCLK_PIN, SDSPI_TEST_CS_PIN); - probe_spi_legacy(SDMMC_FREQ_DEFAULT, SDSPI_TEST_MISO_PIN, SDSPI_TEST_MOSI_PIN, SDSPI_TEST_SCLK_PIN, SDSPI_TEST_CS_PIN); } // No runner for this TEST_CASE("probe SD in SPI mode, slot 0", "[sd][ignore]") { probe_spi(SDMMC_FREQ_DEFAULT, 7, 11, 6, 10); - probe_spi_legacy(SDMMC_FREQ_DEFAULT, 7, 11, 6, 10); } #endif //WITH_SDSPI_TEST diff --git a/docs/en/migration-guides/storage.rst b/docs/en/migration-guides/storage.rst index ea1bb06c48..c571ea8875 100644 --- a/docs/en/migration-guides/storage.rst +++ b/docs/en/migration-guides/storage.rst @@ -67,3 +67,9 @@ Iterator Validity ^^^^^^^^^^^^^^^^^ Note that due to the new signatures, it is possible to have an invalid iterator from ``nvs_entry_find()``, if there is a parameter errors. Hence, it is important to initialize the iterator with ``NULL`` before using ``nvs_entry_find()`` to avoid complex error checking before calling ``nvs_release_iterator()``. A good example is the programming pattern above. + +Removed SDSPI deprecated API +---------------------------- + +Removed structure ``sdspi_slot_config_t`` and fuction ``sdspi_host_init_slot``. These were replaced by a structure ``sdspi_device_config_t`` and a fuction ``sdspi_host_init_device`` respectively. + diff --git a/examples/storage/sd_card/sdspi/README.md b/examples/storage/sd_card/sdspi/README.md index 2750fbae9d..71b3b30a81 100644 --- a/examples/storage/sd_card/sdspi/README.md +++ b/examples/storage/sd_card/sdspi/README.md @@ -32,7 +32,7 @@ It is recommended to get familiar with [the document about pullup requirements]( The GPIO pin numbers used to connect an SD card can be customized. This can be done in two ways: 1. Using menuconfig: Run `idf.py menuconfig` in the project directory and open "SD SPI Example Configuration" menu. -2. In the source code: See the initialization of ``spi_bus_config_t`` and ``sdspi_slot_config_t`` structures in the example code. +2. In the source code: See the initialization of ``spi_bus_config_t`` and ``sdspi_device_config_t`` structures in the example code. This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.