1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its 3 * affiliates 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef R_SDMMC_API_H 9 #define R_SDMMC_API_H 10 11 /*********************************************************************************************************************** 12 * Includes 13 **********************************************************************************************************************/ 14 15 /* Register definitions, common services and error codes. */ 16 #include "bsp_api.h" 17 #include "r_transfer_api.h" 18 19 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 20 FSP_HEADER 21 22 /*******************************************************************************************************************//** 23 * @ingroup RENESAS_STORAGE_INTERFACES 24 * @defgroup SDMMC_API SD/MMC Interface 25 * @brief Interface for accessing SD, eMMC, and SDIO devices. 26 * 27 * @section SDMMC_API_SUMMARY Summary 28 * The r_sdhi interface provides standard SD and eMMC media functionality. This interface also supports SDIO. 29 * 30 * 31 * @{ 32 **********************************************************************************************************************/ 33 34 /********************************************************************************************************************** 35 * Macro definitions 36 **********************************************************************************************************************/ 37 38 /********************************************************************************************************************** 39 * Typedef definitions 40 **********************************************************************************************************************/ 41 42 /** SD/MMC media uses SD protocol or MMC protocol. */ 43 typedef enum e_sdmmc_card_type 44 { 45 SDMMC_CARD_TYPE_MMC = 0, ///< The media is an eMMC device. 46 SDMMC_CARD_TYPE_SD = 1, ///< The media is an SD card. 47 SDMMC_CARD_TYPE_SDIO = 2, ///< The media is an SDIO card. 48 } sdmmc_card_type_t; 49 50 /** SD/MMC data bus is 1, 4 or 8 bits wide. */ 51 typedef enum e_sdmmc_bus_width 52 { 53 SDMMC_BUS_WIDTH_1_BIT = 1, ///< Data bus is 1 bit wide. 54 SDMMC_BUS_WIDTH_4_BITS = 4, ///< Data bus is 4 bits wide. 55 SDMMC_BUS_WIDTH_8_BITS = 8, ///< Data bus is 8 bits wide. 56 } sdmmc_bus_width_t; 57 58 /** SDIO transfer mode, configurable in SDIO read/write extended commands. */ 59 typedef enum e_sdmmc_io_transfer_mode 60 { 61 SDMMC_IO_MODE_TRANSFER_BYTE = 0, ///< SDIO byte transfer mode 62 SDMMC_IO_MODE_TRANSFER_BLOCK ///< SDIO block transfer mode 63 } sdmmc_io_transfer_mode_t; 64 65 /** SDIO address mode, configurable in SDIO read/write extended commands. */ 66 typedef enum e_sdmmc_io_address_mode 67 { 68 SDMMC_IO_ADDRESS_MODE_FIXED = 0, ///< Write all data to the same address 69 SDMMC_IO_ADDRESS_MODE_INCREMENT ///< Increment destination address after each write 70 } sdmmc_io_address_mode_t; 71 72 /** Controls the RAW (read after write) flag of CMD52. Used to read back the status after writing a control register. */ 73 typedef enum e_sdmmc_io_write_mode 74 { 75 SDMMC_IO_WRITE_MODE_NO_READ = 0, ///< Write only (do not read back) 76 SDMMC_IO_WRITE_READ_AFTER_WRITE ///< Read back the register after write 77 } sdmmc_io_write_mode_t; 78 79 /** Events that can trigger a callback function */ 80 typedef enum e_sdmmc_event 81 { 82 SDMMC_EVENT_CARD_REMOVED = 1U << 0, ///< Card removed event. 83 SDMMC_EVENT_CARD_INSERTED = 1U << 1, ///< Card inserted event. 84 SDMMC_EVENT_RESPONSE = 1U << 3, ///< Response event. 85 SDMMC_EVENT_SDIO = 1U << 4, ///< IO event. 86 SDMMC_EVENT_TRANSFER_COMPLETE = 1U << 5, ///< Read or write complete. 87 SDMMC_EVENT_TRANSFER_ERROR = 1U << 6, ///< Read or write failed. 88 SDMMC_EVENT_ERASE_COMPLETE = 1U << 7, ///< Erase completed. 89 SDMMC_EVENT_ERASE_BUSY = 1U << 8, ///< Erase timeout, poll @ref sdmmc_api_t::statusGet. 90 } sdmmc_event_t; 91 92 /** Card detection configuration options. */ 93 /* Card detection using DAT3 is not supported. */ 94 typedef enum e_sdmmc_card_detect 95 { 96 SDMMC_CARD_DETECT_NONE, ///< Card detection unused. 97 SDMMC_CARD_DETECT_CD, ///< Card detection using the CD pin 98 } sdmmc_card_detect_t; 99 100 /** Write protection configuration options. */ 101 typedef enum e_sdmmc_write_protect 102 { 103 SDMMC_WRITE_PROTECT_NONE, ///< Write protection unused. 104 SDMMC_WRITE_PROTECT_WP, ///< Write protection using WP pin 105 } sdmmc_write_protect_t; 106 107 /** Card state when receiving the prior command. */ 108 typedef enum e_sdmmc_r1_state 109 { 110 SDMMC_R1_STATE_IDLE = 0, ///< Idle State 111 SDMMC_R1_STATE_READY = 0, ///< Ready State 112 SDMMC_R1_STATE_IDENT = 0, ///< Identification State 113 SDMMC_R1_STATE_STBY = 0, ///< Stand-by State 114 SDMMC_R1_STATE_TRAN = 0, ///< Transfer State 115 SDMMC_R1_STATE_DATA = 0, ///< Sending-data State 116 SDMMC_R1_STATE_RCV = 0, ///< Receive-data State 117 SDMMC_R1_STATE_PRG = 0, ///< Programming State 118 SDMMC_R1_STATE_DIS = 0, ///< Disconnect State (between programming and stand-by) 119 SDMMC_R1_STATE_IO = 15, ///< This is an I/O card and memory states do not apply 120 } sdmmc_r1_state_t; 121 122 /* Structure for decoding the response of a command. For advanced use only. */ 123 typedef union u_sdmmc_response 124 { 125 uint32_t status; 126 127 /** SDIO Card Status Register. */ 128 struct 129 { 130 uint32_t : 3; 131 uint32_t ake_seq_error : 1; // Error in the sequence of the authentication process 132 uint32_t : 1; 133 uint32_t app_cmd : 1; // The card will expect ACMD, or an indication that the command has been interpreted as ACMD 134 uint32_t fx_event : 1; // Extension Functions may set this bit to get host to deal with events 135 uint32_t switch_error : 1; // 136 uint32_t ready_for_data : 1; // Corresponds to the buffer empty signaling on the bus 137 138 /* The state of the card when receiving the command. If the command execution causes a state change, it will be 139 * visible to the host in the response to the next command. */ 140 sdmmc_r1_state_t current_state : 4; 141 uint32_t erase_reset : 1; // An erase sequence was cleared before executing because an out of erase sequence command was received. 142 uint32_t card_ecc_disabled : 1; // The command has been executed without using the internal ECC. 143 uint32_t wp_erase_skip : 1; // Set when only partial address space was erased due to existing write protected blocks or the temporary or permanent write protected card was erased. 144 uint32_t csd_overwrite : 1; // The read only section of the CSD does not match the card content or an attempt to reverse the copy or permanent WP bits was made. 145 uint32_t : 2; 146 uint32_t error : 1; // A general or unknown error occurred during the operation. 147 uint32_t cc_error : 1; // Internal card controller error. 148 uint32_t card_ecc_failed : 1; // Card internal ECC was applied but failed to correct the data. 149 uint32_t illegal_command : 1; // Command not legal for the card state. 150 uint32_t com_crc_error : 1; // The CRC check of the previous command failed. 151 uint32_t lock_unlock_failed : 1; // Set when a sequence or password error has been detected in the lock/unlock command. 152 uint32_t device_is_locked : 1; // When set, signals that the card is locked by the host. 153 uint32_t wp_violation : 1; // Set when the host attempts to write to a protected block or to the temporary or permanent write protected card. 154 uint32_t erase_param : 1; // An invalid selection of write-blocks for erase occurred. 155 uint32_t erase_seq_error : 1; // An error in the sequence of erase commands occurred. 156 uint32_t block_len_error : 1; // The transferred block length is not allowed for this card, or the number of transferred bytes does not match the block length. 157 uint32_t address_error : 1; // A misaligned address which did not match the block length was used in the command. 158 uint32_t out_of_range : 1; // The command's argument was out of the allowed range for this card. 159 } status_b; 160 161 struct 162 { 163 uint32_t reserved_0 : 7; 164 165 uint32_t reserved_lvr : 1; 166 uint32_t reserved_8 : 7; 167 uint32_t v_27_28 : 1; 168 uint32_t v_28_29 : 1; 169 uint32_t v_29_30 : 1; 170 uint32_t v_30_31 : 1; 171 uint32_t v_31_32 : 1; 172 uint32_t v_32_33 : 1; 173 uint32_t v_33_34 : 1; 174 uint32_t v_34_35 : 1; 175 uint32_t v_35_36 : 1; 176 uint32_t s18A : 1; 177 uint32_t reserved_25 : 5; 178 uint32_t card_capacity_status : 1; 179 uint32_t power_up_status : 1; 180 } r3; 181 182 struct 183 { 184 uint32_t ocr : 24; 185 186 uint32_t reserved_24 : 3; 187 uint32_t memory : 1; 188 uint32_t io_functions : 3; 189 uint32_t ready : 1; 190 } r4; 191 192 struct 193 { 194 uint32_t read_write_data : 8; 195 196 uint32_t out_of_range : 1; 197 uint32_t invalid_function : 1; 198 uint32_t rfu : 1; 199 uint32_t error : 1; 200 uint32_t current_state : 2; 201 uint32_t illegal_command : 1; 202 uint32_t crc_error : 1; 203 uint32_t reserved_16 : 16; 204 } r5; 205 206 struct 207 { 208 uint32_t reserved_0 : 3; 209 210 uint32_t ake_seq_error : 1; 211 uint32_t reserved_4 : 1; 212 uint32_t app_cmd : 1; 213 uint32_t reserved_6 : 2; 214 uint32_t ready_for_data : 1; 215 sdmmc_r1_state_t current_state : 4; 216 uint32_t error : 1; 217 uint32_t illegal_command : 1; 218 uint32_t com_crc_error : 1; 219 uint32_t rca : 16; 220 } r6; 221 222 struct 223 { 224 uint32_t check_pattern : 8; 225 226 uint32_t voltage_accepted : 4; 227 uint32_t reserved_11 : 20; 228 } r7; 229 } sdmmc_response_t; 230 231 /** Current status. */ 232 typedef struct s_sdmmc_status 233 { 234 /** False if card was removed (only applies if MCU supports card detection and SDnCD pin is connected), true otherwise. 235 * 236 * If ready is false, call @ref sdmmc_api_t::mediaInit to reinitialize it 237 */ 238 bool initialized; 239 bool transfer_in_progress; ///< true = Card is busy 240 bool card_inserted; ///< Card detect status, true if card detect is not used 241 } sdmmc_status_t; 242 243 /** Information obtained from the media device. */ 244 typedef struct s_sdmmc_device 245 { 246 sdmmc_card_type_t card_type; ///< SD, eMMC, or SDIO 247 bool write_protected; ///< true = Card is write protected 248 uint32_t clock_rate; ///< Current clock rate 249 uint32_t sector_count; ///< Sector count 250 uint32_t sector_size_bytes; ///< Sector size 251 uint32_t erase_sector_count; ///< Minimum erasable unit (in 512 byte sectors) 252 } sdmmc_device_t; 253 254 /** Callback function parameter data */ 255 typedef struct st_sdmmc_callback_args 256 { 257 sdmmc_event_t event; ///< The event can be used to identify what caused the callback. 258 sdmmc_response_t response; ///< Response from card, only valid if SDMMC_EVENT_RESPONSE is set in event. 259 void const * p_context; ///< Placeholder for user data. 260 } sdmmc_callback_args_t; 261 262 /** Non-secure arguments for writeIo guard function */ 263 typedef struct st_sdmmc_write_io_args_t 264 { 265 uint8_t * const p_data; 266 uint32_t function; 267 uint32_t address; 268 sdmmc_io_write_mode_t read_after_write; 269 } sdmmc_write_io_args_t; 270 271 /** Non-secure arguments for readIoExt guard function */ 272 typedef struct st_sdmmc_read_io_ext_args_t 273 { 274 uint8_t * const p_dest; 275 uint32_t function; 276 uint32_t address; 277 uint32_t * const count; 278 sdmmc_io_transfer_mode_t transfer_mode; 279 sdmmc_io_address_mode_t address_mode; 280 } sdmmc_read_io_ext_args_t; 281 282 /** Non-secure arguments for writeIoExt guard function */ 283 typedef struct st_sdmmc_write_io_ext_args_t 284 { 285 uint8_t const * const p_source; 286 uint32_t function; 287 uint32_t address; 288 uint32_t count; 289 sdmmc_io_transfer_mode_t transfer_mode; 290 sdmmc_io_address_mode_t address_mode; 291 } sdmmc_write_io_ext_args_t; 292 293 /** SD/MMC Configuration */ 294 typedef struct st_sdmmc_cfg 295 { 296 /* SD/MMC generic configuration */ 297 uint8_t channel; ///< Channel of SD/MMC host interface. 298 sdmmc_bus_width_t bus_width; ///< Device bus width is 1, 4 or 8 bits wide. 299 transfer_instance_t const * p_lower_lvl_transfer; ///< Transfer instance used to move data with DMA or DTC 300 301 /* Configuration for SD/MMC Event processing */ 302 void (* p_callback)(sdmmc_callback_args_t * p_args); ///< Pointer to callback function 303 void const * p_context; ///< User defined context passed into callback function 304 305 /* Pointer to SD/MMC peripheral specific configuration */ 306 void const * p_extend; ///< SD/MMC hardware dependent configuration 307 308 /** Block size in bytes. Block size must be 512 bytes for SD cards and eMMC devices. Block size can be 1-512 309 * bytes for SDIO. */ 310 uint32_t block_size; 311 312 /** Whether or not card detection is used. */ 313 sdmmc_card_detect_t card_detect; 314 315 /** Select whether or not to use the write protect pin. Select Not Used if the MCU or device does not have a write protect pin. */ 316 sdmmc_write_protect_t write_protect; 317 IRQn_Type access_irq; ///< Access IRQ number 318 IRQn_Type sdio_irq; ///< SDIO IRQ number 319 IRQn_Type card_irq; ///< Card IRQ number 320 IRQn_Type dma_req_irq; ///< DMA request IRQ number 321 uint8_t access_ipl; ///< Access interrupt priority 322 uint8_t sdio_ipl; ///< SDIO interrupt priority 323 uint8_t card_ipl; ///< Card interrupt priority 324 uint8_t dma_req_ipl; ///< DMA request interrupt priority 325 } sdmmc_cfg_t; 326 327 /** SD/MMC control block. Allocate an instance specific control block to pass into the SD/MMC API calls. 328 */ 329 typedef void sdmmc_ctrl_t; 330 331 /** SD/MMC functions implemented at the HAL layer API. */ 332 typedef struct st_sdmmc_api 333 { 334 /** Open the SD/MMC driver. 335 * 336 * 337 * @param[in] p_ctrl Pointer to SD/MMC instance control block. 338 * @param[in] p_cfg Pointer to SD/MMC instance configuration structure. 339 */ 340 fsp_err_t (* open)(sdmmc_ctrl_t * const p_ctrl, sdmmc_cfg_t const * const p_cfg); 341 342 /** Initializes an SD/MMC device. If the device is a card, the card must be plugged in prior to calling this API. 343 * This API blocks until the device initialization procedure is complete. 344 * 345 * 346 * @param[in] p_ctrl Pointer to SD/MMC instance control block. 347 * @param[out] p_device Pointer to store device information. 348 */ 349 fsp_err_t (* mediaInit)(sdmmc_ctrl_t * const p_ctrl, sdmmc_device_t * const p_device); 350 351 /** Read data from an SD/MMC channel. 352 * This API is not supported for SDIO devices. 353 * 354 * 355 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 356 * @param[out] p_dest Pointer to data buffer to read data to. 357 * @param[in] start_sector First sector address to read. 358 * @param[in] sector_count Number of sectors to read. All sectors must be in the range of 359 * sdmmc_device_t::sector_count. 360 */ 361 fsp_err_t (* read)(sdmmc_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const start_sector, 362 uint32_t const sector_count); 363 364 /** Write data to SD/MMC channel. 365 * This API is not supported for SDIO devices. 366 * 367 * 368 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 369 * @param[in] p_source Pointer to data buffer to write data from. 370 * @param[in] start_sector First sector address to write to. 371 * @param[in] sector_count Number of sectors to write. All sectors must be in the range of 372 * sdmmc_device_t::sector_count. 373 */ 374 fsp_err_t (* write)(sdmmc_ctrl_t * const p_ctrl, uint8_t const * const p_source, uint32_t const start_sector, 375 uint32_t const sector_count); 376 377 /** Read one byte of I/O data from an SDIO device. 378 * This API is not supported for SD or eMMC memory devices. 379 * 380 * 381 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 382 * @param[out] p_data Pointer to location to store data byte. 383 * @param[in] function SDIO Function Number. 384 * @param[in] address SDIO register address. 385 */ 386 fsp_err_t (* readIo)(sdmmc_ctrl_t * const p_ctrl, uint8_t * const p_data, uint32_t const function, 387 uint32_t const address); 388 389 /** Write one byte of I/O data to an SDIO device. 390 * This API is not supported for SD or eMMC memory devices. 391 * 392 * 393 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 394 * @param[in,out] p_data Pointer to data byte to write. Read data is also provided here if 395 * read_after_write is true. 396 * @param[in] function SDIO Function Number. 397 * @param[in] address SDIO register address. 398 * @param[in] read_after_write Whether or not to read back the same register after writing 399 */ 400 fsp_err_t (* writeIo)(sdmmc_ctrl_t * const p_ctrl, uint8_t * const p_data, uint32_t const function, 401 uint32_t const address, sdmmc_io_write_mode_t const read_after_write); 402 403 /** Read multiple bytes or blocks of I/O data from an SDIO device. 404 * This API is not supported for SD or eMMC memory devices. 405 * 406 * 407 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 408 * @param[out] p_dest Pointer to data buffer to read data to. 409 * @param[in] function SDIO Function Number. 410 * @param[in] address SDIO register address. 411 * @param[in] count Number of bytes or blocks to read, maximum 512 bytes or 511 blocks. 412 * @param[in] transfer_mode Byte or block mode 413 * @param[in] address_mode Fixed or incrementing address mode 414 */ 415 fsp_err_t (* readIoExt)(sdmmc_ctrl_t * const p_ctrl, uint8_t * const p_dest, uint32_t const function, 416 uint32_t const address, uint32_t * const count, sdmmc_io_transfer_mode_t transfer_mode, 417 sdmmc_io_address_mode_t address_mode); 418 419 /** Write multiple bytes or blocks of I/O data to an SDIO device. 420 * This API is not supported for SD or eMMC memory devices. 421 * 422 * 423 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 424 * @param[in] p_source Pointer to data buffer to write data from. 425 * @param[in] function_number SDIO Function Number. 426 * @param[in] address SDIO register address. 427 * @param[in] count Number of bytes or blocks to write, maximum 512 bytes or 511 blocks. 428 * @param[in] transfer_mode Byte or block mode 429 * @param[in] address_mode Fixed or incrementing address mode 430 */ 431 fsp_err_t (* writeIoExt)(sdmmc_ctrl_t * const p_ctrl, uint8_t const * const p_source, uint32_t const function, 432 uint32_t const address, uint32_t const count, sdmmc_io_transfer_mode_t transfer_mode, 433 sdmmc_io_address_mode_t address_mode); 434 435 /** Enables SDIO interrupt for SD/MMC instance. 436 * This API is not supported for SD or eMMC memory devices. 437 * 438 * 439 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 440 * @param[in] enable Interrupt enable = true, interrupt disable = false. 441 */ 442 fsp_err_t (* ioIntEnable)(sdmmc_ctrl_t * const p_ctrl, bool enable); 443 444 /** Get SD/MMC device status. 445 * 446 * 447 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 448 * @param[out] p_status Pointer to current driver status. 449 */ 450 fsp_err_t (* statusGet)(sdmmc_ctrl_t * const p_ctrl, sdmmc_status_t * const p_status); 451 452 /** Erase SD/MMC sectors. The sector size for erase is fixed at 512 bytes. 453 * This API is not supported for SDIO devices. 454 * 455 * 456 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 457 * @param[in] start_sector First sector to erase. Must be a multiple of sdmmc_device_t::erase_sector_count. 458 * @param[in] sector_count Number of sectors to erase. Must be a multiple of sdmmc_device_t::erase_sector_count. 459 * All sectors must be in the range of sdmmc_device_t::sector_count. 460 */ 461 fsp_err_t (* erase)(sdmmc_ctrl_t * const p_ctrl, uint32_t const start_sector, uint32_t const sector_count); 462 463 /** Specify callback function and optional context pointer and working memory pointer. 464 * 465 * @param[in] p_ctrl Control block set in @ref sdmmc_api_t::open call. 466 * @param[in] p_callback Callback function to register 467 * @param[in] p_context Pointer to send to callback function 468 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 469 * Callback arguments allocated here are only valid during the callback. 470 */ 471 fsp_err_t (* callbackSet)(sdmmc_ctrl_t * const p_ctrl, void (* p_callback)(sdmmc_callback_args_t *), 472 void const * const p_context, sdmmc_callback_args_t * const p_callback_memory); 473 474 /** Close open SD/MMC device. 475 * 476 * 477 * @param[in] p_ctrl Pointer to an open SD/MMC instance control block. 478 */ 479 fsp_err_t (* close)(sdmmc_ctrl_t * const p_ctrl); 480 } sdmmc_api_t; 481 482 /** This structure encompasses everything that is needed to use an instance of this interface. */ 483 typedef struct st_sdmmc_instance 484 { 485 sdmmc_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 486 sdmmc_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 487 sdmmc_api_t const * p_api; ///< Pointer to the API structure for this instance 488 } sdmmc_instance_t; 489 490 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 491 FSP_FOOTER 492 493 #endif 494 495 /*******************************************************************************************************************//** 496 * @} (end defgroup SDMMC_API) 497 **********************************************************************************************************************/ 498
