feat(sdmmc): support multi-block read/writes

This has the potential of speeding up SD card access significantly.

Reusing the DMA aligned buffer gives the additional option of having to
allocate the transaction buffer only once instead of for every
transaction, while still keeping the improved transaction time.

To give users the maximum amount of control, the Kconfig option for the
transaction buffer size applies only to the temporary buffer, which is
only allocated if the DMA aligned buffer has not been pre-allocated.

Author: jofrev

components/sdmmc/Kconfig

@@ -5,4 +5,21 @@ menu "SD Protocol Layer Configuration"
         help
             Enable SDIO support.
             Disabling this will skip SDIO-specific initialization steps
+    config SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE
+        int "The maximum size of the chunks a SDMMC read/write to/from an unaligned buffer will be split into"
+        range 1 99999
+        default 1
+        help
+            The maximum size in blocks of the chunks a SDMMC read/write with an unaligned buffer will be split into.
+            The SDMMC driver requires aligned buffers for DMA access. If unaligned buffers are passed and the host's
+            dma_aligned_buffer is NULL, an aligned temporary buffer must be allocated for the actual transfer.
+            This option defines the maximum size for the temporary buffer, which equals this option's value multiplied
+            with the block size (typically 512 Bytes). A value of 16 therefore leads to up to 8192 bytes being
+            allocated on the heap for each transfer. The allocated buffer will never be larger than the number of bytes
+            to transfer in total.
+            It also decides whether single (value == 1) or multi block read/write (value > 1) commands are used.
+            With the default value of 1 single-block read/write commands will be used with the allocated buffer size
+            matching the block size.
+            You should keep this option at 1 if your card or configuration doesn't support the read or write multiple
+            blocks commands (CMD18 & CMD25).
 endmenu

components/sdmmc/include/sd_protocol_types.h

@@ -224,7 +224,17 @@ typedef struct {
     sdmmc_delay_phase_t input_delay_phase; /*!< input delay phase, this will only take into effect when the host works in SDMMC_FREQ_HIGHSPEED or SDMMC_FREQ_52M. Driver will print out how long the delay is*/
     esp_err_t (*set_input_delay)(int slot, sdmmc_delay_phase_t delay_phase); /*!< set input delay phase */
     esp_err_t (*set_input_delayline)(int slot, sdmmc_delay_line_t delay_line); /*!< set input delay line */
-    void* dma_aligned_buffer; /*!< Leave it NULL. Reserved for cache aligned buffers for SDIO mode */
+    /**
+     * @brief Cache aligned buffer for multi-block RW and IO commands
+     *
+     * Use cases:
+     *  - Temporary buffer for multi-block read/write transactions to/from unaligned buffers.
+     *    Allocate with DMA capable memory, size should be an integer multiple of your card's sector size.
+     *    See also Kconfig option SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE.
+     *  - Cache aligned buffer for IO commands in SDIO mode.
+     *    If you allocate manually, make sure it is at least SDMMC_IO_BLOCK_SIZE bytes large.
+     */
+    void* dma_aligned_buffer;
     sd_pwr_ctrl_handle_t pwr_ctrl_handle;  /*!< Power control handle */
     bool (*check_buffer_alignment)(int slot, const void *buf, size_t size); /*!< Check if buffer meets alignment requirements */
     esp_err_t (*is_slot_set_to_uhs1)(int slot, bool *is_uhs1); /*!< host slot is set to uhs1 or not*/

components/sdmmc/sdmmc_cmd.c

@@ -5,8 +5,10 @@
  */
 
 #include <inttypes.h>
+#include <sys/param.h> // for MIN/MAX
 #include "esp_private/sdmmc_common.h"
 
+
 static const char* TAG = "sdmmc_cmd";
 
 
@@ -462,31 +464,52 @@ esp_err_t sdmmc_write_sectors(sdmmc_card_t* card, const void* src,
         err = sdmmc_write_sectors_dma(card, src, start_block, block_count, block_size * block_count);
     } else {
         // SDMMC peripheral needs DMA-capable buffers. Split the write into
-        // separate single block writes, if needed, and allocate a temporary
+        // separate (multi) block writes, if needed, and allocate a temporary
         // DMA-capable buffer.
-        void *tmp_buf = NULL;
-        size_t actual_size = 0;
-        // We don't want to force the allocation into SPIRAM, the allocator
-        // will decide based on the buffer size and memory availability.
-        tmp_buf = heap_caps_malloc(block_size, MALLOC_CAP_DMA);
-        if (!tmp_buf) {
-            ESP_LOGE(TAG, "%s: not enough mem, err=0x%x", __func__, ESP_ERR_NO_MEM);
-            return ESP_ERR_NO_MEM;
+        size_t blocks_per_write = MIN(CONFIG_SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE, block_count);
+
+        // prefer using DMA aligned buffer if available over allocating local temporary buffer
+        bool use_dma_aligned_buffer = (card->host.dma_aligned_buffer != NULL);
+        void* buf = use_dma_aligned_buffer ? card->host.dma_aligned_buffer : NULL;
+
+        // only allocate temporary buffer if we can't use the dma_aligned buffer
+        if (!use_dma_aligned_buffer) {
+            // We don't want to force the allocation into SPIRAM, the allocator
+            // will decide based on the buffer size and memory availability.
+            buf = heap_caps_malloc(block_size * blocks_per_write, MALLOC_CAP_DMA);
+            if (!buf) {
+                ESP_LOGE(TAG, "%s: not enough mem, err=0x%x", __func__, ESP_ERR_NO_MEM);
+                return ESP_ERR_NO_MEM;
+            }
+        }
+        size_t actual_size = heap_caps_get_allocated_size(buf);
+        blocks_per_write = actual_size / card->csd.sector_size;
+        // we should still respect the user configured maximum size
+        blocks_per_write = MIN(CONFIG_SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE, blocks_per_write);
+        if (blocks_per_write == 0) {
+            if (!use_dma_aligned_buffer) {
+                free(buf);
+            }
+            ESP_LOGE(TAG, "%s: buffer smaller than sector size: buf=%d, sector=%d", __func__, actual_size, card->csd.sector_size);
+            return ESP_ERR_INVALID_SIZE;
         }
-        actual_size = heap_caps_get_allocated_size(tmp_buf);
 
         const uint8_t* cur_src = (const uint8_t*) src;
-        for (size_t i = 0; i < block_count; ++i) {
-            memcpy(tmp_buf, cur_src, block_size);
-            cur_src += block_size;
-            err = sdmmc_write_sectors_dma(card, tmp_buf, start_block + i, 1, actual_size);
+        for (size_t i = 0; i < block_count; i += blocks_per_write) {
+            // make sure not to write more than the remaining blocks, i.e. block_count - i
+            blocks_per_write = MIN(blocks_per_write, (block_count - i));
+            memcpy(buf, cur_src, block_size * blocks_per_write);
+            cur_src += block_size * blocks_per_write;
+            err = sdmmc_write_sectors_dma(card, buf, start_block + i, blocks_per_write, actual_size);
             if (err != ESP_OK) {
-                ESP_LOGD(TAG, "%s: error 0x%x writing block %d+%d",
-                        __func__, err, start_block, i);
+                ESP_LOGD(TAG, "%s: error 0x%x writing blocks %d+[%d..%d]",
+                        __func__, err, start_block, i, i + blocks_per_write - 1);
                 break;
             }
         }
-        free(tmp_buf);
+        if (!use_dma_aligned_buffer) {
+            free(buf);
+        }
     }
     return err;
 }
@@ -600,33 +623,55 @@ esp_err_t sdmmc_read_sectors(sdmmc_card_t* card, void* dst,
         err = sdmmc_read_sectors_dma(card, dst, start_block, block_count, block_size * block_count);
     } else {
         // SDMMC peripheral needs DMA-capable buffers. Split the read into
-        // separate single block reads, if needed, and allocate a temporary
+        // separate (multi) block reads, if needed, and allocate a temporary
         // DMA-capable buffer.
-        void *tmp_buf = NULL;
-        size_t actual_size = 0;
-        tmp_buf = heap_caps_malloc(block_size, MALLOC_CAP_DMA);
-        if (!tmp_buf) {
-            ESP_LOGE(TAG, "%s: not enough mem, err=0x%x", __func__, ESP_ERR_NO_MEM);
-            return ESP_ERR_NO_MEM;
+        size_t blocks_per_read = MIN(CONFIG_SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE, block_count);
+
+        // prefer using DMA aligned buffer if available over allocating local temporary buffer
+        bool use_dma_aligned_buffer = (card->host.dma_aligned_buffer != NULL);
+        void* buf = use_dma_aligned_buffer ? card->host.dma_aligned_buffer : NULL;
+
+        // only allocate temporary buffer if we can't use the dma_aligned buffer
+        if (!use_dma_aligned_buffer) {
+            // We don't want to force the allocation into SPIRAM, the allocator
+            // will decide based on the buffer size and memory availability.
+            buf = heap_caps_malloc(block_size * blocks_per_read, MALLOC_CAP_DMA);
+            if (!buf) {
+                ESP_LOGE(TAG, "%s: not enough mem, err=0x%x", __func__, ESP_ERR_NO_MEM);
+                return ESP_ERR_NO_MEM;
+            }
+        }
+        size_t actual_size = heap_caps_get_allocated_size(buf);
+        blocks_per_read = actual_size / card->csd.sector_size;
+        // we should still respect the user configured maximum size
+        blocks_per_read = MIN(CONFIG_SD_UNALIGNED_MULTI_BLOCK_RW_MAX_CHUNK_SIZE, blocks_per_read);
+        if (blocks_per_read == 0) {
+            if (!use_dma_aligned_buffer) {
+                free(buf);
+            }
+            ESP_LOGE(TAG, "%s: buffer smaller than sector size: buf=%d, sector=%d", __func__, actual_size, card->csd.sector_size);
+            return ESP_ERR_INVALID_SIZE;
         }
-        actual_size = heap_caps_get_allocated_size(tmp_buf);
 
         uint8_t* cur_dst = (uint8_t*) dst;
-        for (size_t i = 0; i < block_count; ++i) {
-            err = sdmmc_read_sectors_dma(card, tmp_buf, start_block + i, 1, actual_size);
+        for (size_t i = 0; i < block_count; i += blocks_per_read) {
+            // make sure not to read more than the remaining blocks, i.e. block_count - i
+            blocks_per_read = MIN(blocks_per_read, (block_count - i));
+            err = sdmmc_read_sectors_dma(card, buf, start_block + i, blocks_per_read, actual_size);
             if (err != ESP_OK) {
-                ESP_LOGD(TAG, "%s: error 0x%x writing block %d+%d",
-                        __func__, err, start_block, i);
+                ESP_LOGD(TAG, "%s: error 0x%x reading blocks %d+[%d..%d]",
+                        __func__, err, start_block, i, i + blocks_per_read - 1);
                 break;
             }
-            memcpy(cur_dst, tmp_buf, block_size);
-            cur_dst += block_size;
+            memcpy(cur_dst, buf, block_size * blocks_per_read);
+            cur_dst += block_size * blocks_per_read;
+        }
+        if (!use_dma_aligned_buffer) {
+          free(buf);
         }
-        free(tmp_buf);
     }
     return err;
 }
-
 esp_err_t sdmmc_read_sectors_dma(sdmmc_card_t* card, void* dst,
         size_t start_block, size_t block_count, size_t buffer_len)
 {