1 /* 2 * SPDX-FileCopyrightText: 2006 Uwe Stuehler <uwe@openbsd.org> 3 * 4 * SPDX-License-Identifier: ISC 5 * 6 * SPDX-FileContributor: 2016-2021 Espressif Systems (Shanghai) CO LTD 7 */ 8 /* 9 * Copyright (c) 2006 Uwe Stuehler <uwe@openbsd.org> 10 * 11 * Permission to use, copy, modify, and distribute this software for any 12 * purpose with or without fee is hereby granted, provided that the above 13 * copyright notice and this permission notice appear in all copies. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 18 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22 */ 23 24 #ifndef _SDMMC_TYPES_H_ 25 #define _SDMMC_TYPES_H_ 26 27 #include <stdint.h> 28 #include <stddef.h> 29 #include "esp_err.h" 30 #include "freertos/FreeRTOS.h" 31 32 /** 33 * Decoded values from SD card Card Specific Data register 34 */ 35 typedef struct { 36 int csd_ver; /*!< CSD structure format */ 37 int mmc_ver; /*!< MMC version (for CID format) */ 38 int capacity; /*!< total number of sectors */ 39 int sector_size; /*!< sector size in bytes */ 40 int read_block_len; /*!< block length for reads */ 41 int card_command_class; /*!< Card Command Class for SD */ 42 int tr_speed; /*!< Max transfer speed */ 43 } sdmmc_csd_t; 44 45 /** 46 * Decoded values from SD card Card IDentification register 47 */ 48 typedef struct { 49 int mfg_id; /*!< manufacturer identification number */ 50 int oem_id; /*!< OEM/product identification number */ 51 char name[8]; /*!< product name (MMC v1 has the longest) */ 52 int revision; /*!< product revision */ 53 int serial; /*!< product serial number */ 54 int date; /*!< manufacturing date */ 55 } sdmmc_cid_t; 56 57 /** 58 * Decoded values from SD Configuration Register 59 */ 60 typedef struct { 61 int sd_spec; /*!< SD Physical layer specification version, reported by card */ 62 int bus_width; /*!< bus widths supported by card: BIT(0) — 1-bit bus, BIT(2) — 4-bit bus */ 63 } sdmmc_scr_t; 64 65 /** 66 * Decoded values of Extended Card Specific Data 67 */ 68 typedef struct { 69 uint8_t power_class; /*!< Power class used by the card */ 70 } sdmmc_ext_csd_t; 71 72 /** 73 * SD/MMC command response buffer 74 */ 75 typedef uint32_t sdmmc_response_t[4]; 76 77 /** 78 * SD SWITCH_FUNC response buffer 79 */ 80 typedef struct { 81 uint32_t data[512 / 8 / sizeof(uint32_t)]; /*!< response data */ 82 } sdmmc_switch_func_rsp_t; 83 84 /** 85 * SD/MMC command information 86 */ 87 typedef struct { 88 uint32_t opcode; /*!< SD or MMC command index */ 89 uint32_t arg; /*!< SD/MMC command argument */ 90 sdmmc_response_t response; /*!< response buffer */ 91 void* data; /*!< buffer to send or read into */ 92 size_t datalen; /*!< length of data buffer */ 93 size_t blklen; /*!< block length */ 94 int flags; /*!< see below */ 95 /** @cond */ 96 #define SCF_ITSDONE 0x0001 /*!< command is complete */ 97 #define SCF_CMD(flags) ((flags) & 0x00f0) 98 #define SCF_CMD_AC 0x0000 99 #define SCF_CMD_ADTC 0x0010 100 #define SCF_CMD_BC 0x0020 101 #define SCF_CMD_BCR 0x0030 102 #define SCF_CMD_READ 0x0040 /*!< read command (data expected) */ 103 #define SCF_RSP_BSY 0x0100 104 #define SCF_RSP_136 0x0200 105 #define SCF_RSP_CRC 0x0400 106 #define SCF_RSP_IDX 0x0800 107 #define SCF_RSP_PRESENT 0x1000 108 /* response types */ 109 #define SCF_RSP_R0 0 /*!< none */ 110 #define SCF_RSP_R1 (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX) 111 #define SCF_RSP_R1B (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX|SCF_RSP_BSY) 112 #define SCF_RSP_R2 (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_136) 113 #define SCF_RSP_R3 (SCF_RSP_PRESENT) 114 #define SCF_RSP_R4 (SCF_RSP_PRESENT) 115 #define SCF_RSP_R5 (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX) 116 #define SCF_RSP_R5B (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX|SCF_RSP_BSY) 117 #define SCF_RSP_R6 (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX) 118 #define SCF_RSP_R7 (SCF_RSP_PRESENT|SCF_RSP_CRC|SCF_RSP_IDX) 119 /* special flags */ 120 #define SCF_WAIT_BUSY 0x2000 /*!< Wait for completion of card busy signal before returning */ 121 /** @endcond */ 122 esp_err_t error; /*!< error returned from transfer */ 123 int timeout_ms; /*!< response timeout, in milliseconds */ 124 } sdmmc_command_t; 125 126 /** 127 * SD/MMC Host description 128 * 129 * This structure defines properties of SD/MMC host and functions 130 * of SD/MMC host which can be used by upper layers. 131 */ 132 typedef struct { 133 uint32_t flags; /*!< flags defining host properties */ 134 #define SDMMC_HOST_FLAG_1BIT BIT(0) /*!< host supports 1-line SD and MMC protocol */ 135 #define SDMMC_HOST_FLAG_4BIT BIT(1) /*!< host supports 4-line SD and MMC protocol */ 136 #define SDMMC_HOST_FLAG_8BIT BIT(2) /*!< host supports 8-line MMC protocol */ 137 #define SDMMC_HOST_FLAG_SPI BIT(3) /*!< host supports SPI protocol */ 138 #define SDMMC_HOST_FLAG_DDR BIT(4) /*!< host supports DDR mode for SD/MMC */ 139 #define SDMMC_HOST_FLAG_DEINIT_ARG BIT(5) /*!< host `deinit` function called with the slot argument */ 140 int slot; /*!< slot number, to be passed to host functions */ 141 int max_freq_khz; /*!< max frequency supported by the host */ 142 #define SDMMC_FREQ_DEFAULT 20000 /*!< SD/MMC Default speed (limited by clock divider) */ 143 #define SDMMC_FREQ_HIGHSPEED 40000 /*!< SD High speed (limited by clock divider) */ 144 #define SDMMC_FREQ_PROBING 400 /*!< SD/MMC probing speed */ 145 #define SDMMC_FREQ_52M 52000 /*!< MMC 52MHz speed */ 146 #define SDMMC_FREQ_26M 26000 /*!< MMC 26MHz speed */ 147 float io_voltage; /*!< I/O voltage used by the controller (voltage switching is not supported) */ 148 esp_err_t (*init)(void); /*!< Host function to initialize the driver */ 149 esp_err_t (*set_bus_width)(int slot, size_t width); /*!< host function to set bus width */ 150 size_t (*get_bus_width)(int slot); /*!< host function to get bus width */ 151 esp_err_t (*set_bus_ddr_mode)(int slot, bool ddr_enable); /*!< host function to set DDR mode */ 152 esp_err_t (*set_card_clk)(int slot, uint32_t freq_khz); /*!< host function to set card clock frequency */ 153 esp_err_t (*do_transaction)(int slot, sdmmc_command_t* cmdinfo); /*!< host function to do a transaction */ 154 union { 155 esp_err_t (*deinit)(void); /*!< host function to deinitialize the driver */ 156 esp_err_t (*deinit_p)(int slot); /*!< host function to deinitialize the driver, called with the `slot` */ 157 }; 158 esp_err_t (*io_int_enable)(int slot); /*!< Host function to enable SDIO interrupt line */ 159 esp_err_t (*io_int_wait)(int slot, TickType_t timeout_ticks); /*!< Host function to wait for SDIO interrupt line to be active */ 160 int command_timeout_ms; /*!< timeout, in milliseconds, of a single command. Set to 0 to use the default value. */ 161 } sdmmc_host_t; 162 163 /** 164 * SD/MMC card information structure 165 */ 166 typedef struct { 167 sdmmc_host_t host; /*!< Host with which the card is associated */ 168 uint32_t ocr; /*!< OCR (Operation Conditions Register) value */ 169 union { 170 sdmmc_cid_t cid; /*!< decoded CID (Card IDentification) register value */ 171 sdmmc_response_t raw_cid; /*!< raw CID of MMC card to be decoded 172 after the CSD is fetched in the data transfer mode*/ 173 }; 174 sdmmc_csd_t csd; /*!< decoded CSD (Card-Specific Data) register value */ 175 sdmmc_scr_t scr; /*!< decoded SCR (SD card Configuration Register) value */ 176 sdmmc_ext_csd_t ext_csd; /*!< decoded EXT_CSD (Extended Card Specific Data) register value */ 177 uint16_t rca; /*!< RCA (Relative Card Address) */ 178 uint16_t max_freq_khz; /*!< Maximum frequency, in kHz, supported by the card */ 179 uint32_t is_mem : 1; /*!< Bit indicates if the card is a memory card */ 180 uint32_t is_sdio : 1; /*!< Bit indicates if the card is an IO card */ 181 uint32_t is_mmc : 1; /*!< Bit indicates if the card is MMC */ 182 uint32_t num_io_functions : 3; /*!< If is_sdio is 1, contains the number of IO functions on the card */ 183 uint32_t log_bus_width : 2; /*!< log2(bus width supported by card) */ 184 uint32_t is_ddr : 1; /*!< Card supports DDR mode */ 185 uint32_t reserved : 23; /*!< Reserved for future expansion */ 186 } sdmmc_card_t; 187 188 189 #endif // _SDMMC_TYPES_H_ 190
