1 /* 2 * Copyright (c) 2013-2020 ARM Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * $Date: 31. March 2020 19 * $Revision: V2.4 20 * 21 * Project: MCI (Memory Card Interface) Driver definitions 22 */ 23 24 /* History: 25 * Version 2.4 26 * Removed volatile from ARM_MCI_STATUS 27 * Version 2.3 28 * ARM_MCI_STATUS made volatile 29 * Version 2.2 30 * Added timeout and error flags to ARM_MCI_STATUS 31 * Added support for controlling optional RST_n pin (eMMC) 32 * Removed explicit Clock Control (ARM_MCI_CONTROL_CLOCK) 33 * Removed event ARM_MCI_EVENT_BOOT_ACK_TIMEOUT 34 * Version 2.1 35 * Decoupled SPI mode from MCI driver 36 * Replaced function ARM_MCI_CardSwitchRead with ARM_MCI_ReadCD and ARM_MCI_ReadWP 37 * Version 2.0 38 * Added support for: 39 * SD UHS-I (Ultra High Speed) 40 * SD I/O Interrupt 41 * Read Wait (SD I/O) 42 * Suspend/Resume (SD I/O) 43 * MMC Interrupt 44 * MMC Boot 45 * Stream Data transfer (MMC) 46 * VCCQ Power Supply Control (eMMC) 47 * Command Completion Signal (CCS) for CE-ATA 48 * Added ARM_MCI_Control function 49 * Added ARM_MCI_GetStatus function 50 * Removed ARM_MCI_BusMode, ARM_MCI_BusDataWidth, ARM_MCI_BusSingaling functions 51 * (replaced by ARM_MCI_Control) 52 * Changed ARM_MCI_CardPower function (voltage parameter) 53 * Changed ARM_MCI_SendCommnad function (flags parameter) 54 * Changed ARM_MCI_SetupTransfer function (mode parameter) 55 * Removed ARM_MCI_ReadTransfer and ARM_MCI_WriteTransfer functions 56 * Changed prefix ARM_DRV -> ARM_DRIVER 57 * Changed return values of some functions to int32_t 58 * Version 1.10 59 * Namespace prefix ARM_ added 60 * Version 1.00 61 * Initial release 62 */ 63 64 #ifndef DRIVER_MCI_H_ 65 #define DRIVER_MCI_H_ 66 67 #ifdef __cplusplus 68 extern "C" 69 { 70 #endif 71 72 #include "Driver_Common.h" 73 74 #define ARM_MCI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,4) /* API version */ 75 76 77 #define _ARM_Driver_MCI_(n) Driver_MCI##n 78 #define ARM_Driver_MCI_(n) _ARM_Driver_MCI_(n) 79 80 81 /****** MCI Send Command Flags *****/ 82 #define ARM_MCI_RESPONSE_Pos 0 83 #define ARM_MCI_RESPONSE_Msk (3UL << ARM_MCI_RESPONSE_Pos) 84 #define ARM_MCI_RESPONSE_NONE (0UL << ARM_MCI_RESPONSE_Pos) ///< No response expected (default) 85 #define ARM_MCI_RESPONSE_SHORT (1UL << ARM_MCI_RESPONSE_Pos) ///< Short response (48-bit) 86 #define ARM_MCI_RESPONSE_SHORT_BUSY (2UL << ARM_MCI_RESPONSE_Pos) ///< Short response with busy signal (48-bit) 87 #define ARM_MCI_RESPONSE_LONG (3UL << ARM_MCI_RESPONSE_Pos) ///< Long response (136-bit) 88 89 #define ARM_MCI_RESPONSE_INDEX (1UL << 2) ///< Check command index in response 90 #define ARM_MCI_RESPONSE_CRC (1UL << 3) ///< Check CRC in response 91 92 #define ARM_MCI_WAIT_BUSY (1UL << 4) ///< Wait until busy before sending the command 93 94 #define ARM_MCI_TRANSFER_DATA (1UL << 5) ///< Activate Data transfer 95 96 #define ARM_MCI_CARD_INITIALIZE (1UL << 6) ///< Execute Memory Card initialization sequence 97 98 #define ARM_MCI_INTERRUPT_COMMAND (1UL << 7) ///< Send Interrupt command (CMD40 - MMC only) 99 #define ARM_MCI_INTERRUPT_RESPONSE (1UL << 8) ///< Send Interrupt response (CMD40 - MMC only) 100 101 #define ARM_MCI_BOOT_OPERATION (1UL << 9) ///< Execute Boot operation (MMC only) 102 #define ARM_MCI_BOOT_ALTERNATIVE (1UL << 10) ///< Execute Alternative Boot operation (MMC only) 103 #define ARM_MCI_BOOT_ACK (1UL << 11) ///< Expect Boot Acknowledge (MMC only) 104 105 #define ARM_MCI_CCSD (1UL << 12) ///< Send Command Completion Signal Disable (CCSD) for CE-ATA device 106 #define ARM_MCI_CCS (1UL << 13) ///< Expect Command Completion Signal (CCS) for CE-ATA device 107 108 109 /****** MCI Setup Transfer Mode *****/ 110 #define ARM_MCI_TRANSFER_READ (0UL << 0) ///< Data Read Transfer (from MCI) 111 #define ARM_MCI_TRANSFER_WRITE (1UL << 0) ///< Data Write Transfer (to MCI) 112 #define ARM_MCI_TRANSFER_BLOCK (0UL << 1) ///< Block Data transfer (default) 113 #define ARM_MCI_TRANSFER_STREAM (1UL << 1) ///< Stream Data transfer (MMC only) 114 115 116 /****** MCI Control Codes *****/ 117 #define ARM_MCI_BUS_SPEED (0x01UL) ///< Set Bus Speed; arg = requested speed in bits/s; returns configured speed in bits/s 118 #define ARM_MCI_BUS_SPEED_MODE (0x02UL) ///< Set Bus Speed Mode as specified with arg 119 #define ARM_MCI_BUS_CMD_MODE (0x03UL) ///< Set CMD Line Mode as specified with arg 120 #define ARM_MCI_BUS_DATA_WIDTH (0x04UL) ///< Set Bus Data Width as specified with arg 121 #define ARM_MCI_DRIVER_STRENGTH (0x05UL) ///< Set SD UHS-I Driver Strength as specified with arg 122 #define ARM_MCI_CONTROL_RESET (0x06UL) ///< Control optional RST_n Pin (eMMC); arg: 0=inactive, 1=active 123 #define ARM_MCI_CONTROL_CLOCK_IDLE (0x07UL) ///< Control Clock generation on CLK Pin when idle; arg: 0=disabled, 1=enabled 124 #define ARM_MCI_UHS_TUNING_OPERATION (0x08UL) ///< Sampling clock Tuning operation (SD UHS-I); arg: 0=reset, 1=execute 125 #define ARM_MCI_UHS_TUNING_RESULT (0x09UL) ///< Sampling clock Tuning result (SD UHS-I); returns: 0=done, 1=in progress, -1=error 126 #define ARM_MCI_DATA_TIMEOUT (0x0AUL) ///< Set Data timeout; arg = timeout in bus cycles 127 #define ARM_MCI_CSS_TIMEOUT (0x0BUL) ///< Set Command Completion Signal (CCS) timeout; arg = timeout in bus cycles 128 #define ARM_MCI_MONITOR_SDIO_INTERRUPT (0x0CUL) ///< Monitor SD I/O interrupt: arg: 0=disabled, 1=enabled 129 #define ARM_MCI_CONTROL_READ_WAIT (0x0DUL) ///< Control Read/Wait for SD I/O; arg: 0=disabled, 1=enabled 130 #define ARM_MCI_SUSPEND_TRANSFER (0x0EUL) ///< Suspend Data transfer (SD I/O); returns number of remaining bytes to transfer 131 #define ARM_MCI_RESUME_TRANSFER (0x0FUL) ///< Resume Data transfer (SD I/O) 132 133 /*----- MCI Bus Speed Mode -----*/ 134 #define ARM_MCI_BUS_DEFAULT_SPEED (0x00UL) ///< SD/MMC: Default Speed mode up to 25/26MHz 135 #define ARM_MCI_BUS_HIGH_SPEED (0x01UL) ///< SD/MMC: High Speed mode up to 50/52MHz 136 #define ARM_MCI_BUS_UHS_SDR12 (0x02UL) ///< SD: SDR12 (Single Data Rate) up to 25MHz, 12.5MB/s: UHS-I (Ultra High Speed) 1.8V signaling 137 #define ARM_MCI_BUS_UHS_SDR25 (0x03UL) ///< SD: SDR25 (Single Data Rate) up to 50MHz, 25 MB/s: UHS-I (Ultra High Speed) 1.8V signaling 138 #define ARM_MCI_BUS_UHS_SDR50 (0x04UL) ///< SD: SDR50 (Single Data Rate) up to 100MHz, 50 MB/s: UHS-I (Ultra High Speed) 1.8V signaling 139 #define ARM_MCI_BUS_UHS_SDR104 (0x05UL) ///< SD: SDR104 (Single Data Rate) up to 208MHz, 104 MB/s: UHS-I (Ultra High Speed) 1.8V signaling 140 #define ARM_MCI_BUS_UHS_DDR50 (0x06UL) ///< SD: DDR50 (Dual Data Rate) up to 50MHz, 50 MB/s: UHS-I (Ultra High Speed) 1.8V signaling 141 142 /*----- MCI CMD Line Mode -----*/ 143 #define ARM_MCI_BUS_CMD_PUSH_PULL (0x00UL) ///< Push-Pull CMD line (default) 144 #define ARM_MCI_BUS_CMD_OPEN_DRAIN (0x01UL) ///< Open Drain CMD line (MMC only) 145 146 /*----- MCI Bus Data Width -----*/ 147 #define ARM_MCI_BUS_DATA_WIDTH_1 (0x00UL) ///< Bus data width: 1 bit (default) 148 #define ARM_MCI_BUS_DATA_WIDTH_4 (0x01UL) ///< Bus data width: 4 bits 149 #define ARM_MCI_BUS_DATA_WIDTH_8 (0x02UL) ///< Bus data width: 8 bits 150 #define ARM_MCI_BUS_DATA_WIDTH_4_DDR (0x03UL) ///< Bus data width: 4 bits, DDR (Dual Data Rate) - MMC only 151 #define ARM_MCI_BUS_DATA_WIDTH_8_DDR (0x04UL) ///< Bus data width: 8 bits, DDR (Dual Data Rate) - MMC only 152 153 /*----- MCI Driver Strength -----*/ 154 #define ARM_MCI_DRIVER_TYPE_A (0x01UL) ///< SD UHS-I Driver Type A 155 #define ARM_MCI_DRIVER_TYPE_B (0x00UL) ///< SD UHS-I Driver Type B (default) 156 #define ARM_MCI_DRIVER_TYPE_C (0x02UL) ///< SD UHS-I Driver Type C 157 #define ARM_MCI_DRIVER_TYPE_D (0x03UL) ///< SD UHS-I Driver Type D 158 159 160 /****** MCI Card Power *****/ 161 #define ARM_MCI_POWER_VDD_Pos 0 162 #define ARM_MCI_POWER_VDD_Msk (0x0FUL << ARM_MCI_POWER_VDD_Pos) 163 #define ARM_MCI_POWER_VDD_OFF (0x01UL << ARM_MCI_POWER_VDD_Pos) ///< VDD (VCC) turned off 164 #define ARM_MCI_POWER_VDD_3V3 (0x02UL << ARM_MCI_POWER_VDD_Pos) ///< VDD (VCC) = 3.3V 165 #define ARM_MCI_POWER_VDD_1V8 (0x03UL << ARM_MCI_POWER_VDD_Pos) ///< VDD (VCC) = 1.8V 166 #define ARM_MCI_POWER_VCCQ_Pos 4 167 #define ARM_MCI_POWER_VCCQ_Msk (0x0FUL << ARM_MCI_POWER_VCCQ_Pos) 168 #define ARM_MCI_POWER_VCCQ_OFF (0x01UL << ARM_MCI_POWER_VCCQ_Pos) ///< eMMC VCCQ turned off 169 #define ARM_MCI_POWER_VCCQ_3V3 (0x02UL << ARM_MCI_POWER_VCCQ_Pos) ///< eMMC VCCQ = 3.3V 170 #define ARM_MCI_POWER_VCCQ_1V8 (0x03UL << ARM_MCI_POWER_VCCQ_Pos) ///< eMMC VCCQ = 1.8V 171 #define ARM_MCI_POWER_VCCQ_1V2 (0x04UL << ARM_MCI_POWER_VCCQ_Pos) ///< eMMC VCCQ = 1.2V 172 173 174 /** 175 \brief MCI Status 176 */ 177 typedef struct _ARM_MCI_STATUS { 178 uint32_t command_active : 1; ///< Command active flag 179 uint32_t command_timeout : 1; ///< Command timeout flag (cleared on start of next command) 180 uint32_t command_error : 1; ///< Command error flag (cleared on start of next command) 181 uint32_t transfer_active : 1; ///< Transfer active flag 182 uint32_t transfer_timeout : 1; ///< Transfer timeout flag (cleared on start of next command) 183 uint32_t transfer_error : 1; ///< Transfer error flag (cleared on start of next command) 184 uint32_t sdio_interrupt : 1; ///< SD I/O Interrupt flag (cleared on start of monitoring) 185 uint32_t ccs : 1; ///< CCS flag (cleared on start of next command) 186 uint32_t reserved : 24; 187 } ARM_MCI_STATUS; 188 189 190 /****** MCI Card Event *****/ 191 #define ARM_MCI_EVENT_CARD_INSERTED (1UL << 0) ///< Memory Card inserted 192 #define ARM_MCI_EVENT_CARD_REMOVED (1UL << 1) ///< Memory Card removed 193 #define ARM_MCI_EVENT_COMMAND_COMPLETE (1UL << 2) ///< Command completed 194 #define ARM_MCI_EVENT_COMMAND_TIMEOUT (1UL << 3) ///< Command timeout 195 #define ARM_MCI_EVENT_COMMAND_ERROR (1UL << 4) ///< Command response error (CRC error or invalid response) 196 #define ARM_MCI_EVENT_TRANSFER_COMPLETE (1UL << 5) ///< Data transfer completed 197 #define ARM_MCI_EVENT_TRANSFER_TIMEOUT (1UL << 6) ///< Data transfer timeout 198 #define ARM_MCI_EVENT_TRANSFER_ERROR (1UL << 7) ///< Data transfer CRC failed 199 #define ARM_MCI_EVENT_SDIO_INTERRUPT (1UL << 8) ///< SD I/O Interrupt 200 #define ARM_MCI_EVENT_CCS (1UL << 9) ///< Command Completion Signal (CCS) 201 #define ARM_MCI_EVENT_CCS_TIMEOUT (1UL << 10) ///< Command Completion Signal (CCS) Timeout 202 203 204 // Function documentation 205 /** 206 \fn ARM_DRIVER_VERSION ARM_MCI_GetVersion (void) 207 \brief Get driver version. 208 \return \ref ARM_DRIVER_VERSION 209 */ 210 /** 211 \fn ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities (void) 212 \brief Get driver capabilities. 213 \return \ref ARM_MCI_CAPABILITIES 214 */ 215 /** 216 \fn int32_t ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event) 217 \brief Initialize the Memory Card Interface 218 \param[in] cb_event Pointer to \ref ARM_MCI_SignalEvent 219 \return \ref execution_status 220 */ 221 /** 222 \fn int32_t ARM_MCI_Uninitialize (void) 223 \brief De-initialize Memory Card Interface. 224 \return \ref execution_status 225 */ 226 /** 227 \fn int32_t ARM_MCI_PowerControl (ARM_POWER_STATE state) 228 \brief Control Memory Card Interface Power. 229 \param[in] state Power state \ref ARM_POWER_STATE 230 \return \ref execution_status 231 */ 232 /** 233 \fn int32_t ARM_MCI_CardPower (uint32_t voltage) 234 \brief Set Memory Card Power supply voltage. 235 \param[in] voltage Memory Card Power supply voltage 236 \return \ref execution_status 237 */ 238 /** 239 \fn int32_t ARM_MCI_ReadCD (void) 240 \brief Read Card Detect (CD) state. 241 \return 1:card detected, 0:card not detected, or error 242 */ 243 /** 244 \fn int32_t ARM_MCI_ReadWP (void) 245 \brief Read Write Protect (WP) state. 246 \return 1:write protected, 0:not write protected, or error 247 */ 248 /** 249 \fn int32_t ARM_MCI_SendCommand (uint32_t cmd, 250 uint32_t arg, 251 uint32_t flags, 252 uint32_t *response) 253 \brief Send Command to card and get the response. 254 \param[in] cmd Memory Card command 255 \param[in] arg Command argument 256 \param[in] flags Command flags 257 \param[out] response Pointer to buffer for response 258 \return \ref execution_status 259 */ 260 /** 261 \fn int32_t ARM_MCI_SetupTransfer (uint8_t *data, 262 uint32_t block_count, 263 uint32_t block_size, 264 uint32_t mode) 265 \brief Setup read or write transfer operation. 266 \param[in,out] data Pointer to data block(s) to be written or read 267 \param[in] block_count Number of blocks 268 \param[in] block_size Size of a block in bytes 269 \param[in] mode Transfer mode 270 \return \ref execution_status 271 */ 272 /** 273 \fn int32_t ARM_MCI_AbortTransfer (void) 274 \brief Abort current read/write data transfer. 275 \return \ref execution_status 276 */ 277 /** 278 \fn int32_t ARM_MCI_Control (uint32_t control, uint32_t arg) 279 \brief Control MCI Interface. 280 \param[in] control Operation 281 \param[in] arg Argument of operation (optional) 282 \return \ref execution_status 283 */ 284 /** 285 \fn ARM_MCI_STATUS ARM_MCI_GetStatus (void) 286 \brief Get MCI status. 287 \return MCI status \ref ARM_MCI_STATUS 288 */ 289 290 /** 291 \fn void ARM_MCI_SignalEvent (uint32_t event) 292 \brief Callback function that signals a MCI Card Event. 293 \param[in] event \ref mci_event_gr 294 \return none 295 */ 296 297 typedef void (*ARM_MCI_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_MCI_SignalEvent : Signal MCI Card Event. 298 299 300 /** 301 \brief MCI Driver Capabilities. 302 */ 303 typedef struct _ARM_MCI_CAPABILITIES { 304 uint32_t cd_state : 1; ///< Card Detect State available 305 uint32_t cd_event : 1; ///< Signal Card Detect change event 306 uint32_t wp_state : 1; ///< Write Protect State available 307 uint32_t vdd : 1; ///< Supports VDD Card Power Supply Control 308 uint32_t vdd_1v8 : 1; ///< Supports 1.8 VDD Card Power Supply 309 uint32_t vccq : 1; ///< Supports VCCQ Card Power Supply Control (eMMC) 310 uint32_t vccq_1v8 : 1; ///< Supports 1.8 VCCQ Card Power Supply (eMMC) 311 uint32_t vccq_1v2 : 1; ///< Supports 1.2 VCCQ Card Power Supply (eMMC) 312 uint32_t data_width_4 : 1; ///< Supports 4-bit data 313 uint32_t data_width_8 : 1; ///< Supports 8-bit data 314 uint32_t data_width_4_ddr : 1; ///< Supports 4-bit data, DDR (Dual Data Rate) - MMC only 315 uint32_t data_width_8_ddr : 1; ///< Supports 8-bit data, DDR (Dual Data Rate) - MMC only 316 uint32_t high_speed : 1; ///< Supports SD/MMC High Speed Mode 317 uint32_t uhs_signaling : 1; ///< Supports SD UHS-I (Ultra High Speed) 1.8V signaling 318 uint32_t uhs_tuning : 1; ///< Supports SD UHS-I tuning 319 uint32_t uhs_sdr50 : 1; ///< Supports SD UHS-I SDR50 (Single Data Rate) up to 50MB/s 320 uint32_t uhs_sdr104 : 1; ///< Supports SD UHS-I SDR104 (Single Data Rate) up to 104MB/s 321 uint32_t uhs_ddr50 : 1; ///< Supports SD UHS-I DDR50 (Dual Data Rate) up to 50MB/s 322 uint32_t uhs_driver_type_a : 1; ///< Supports SD UHS-I Driver Type A 323 uint32_t uhs_driver_type_c : 1; ///< Supports SD UHS-I Driver Type C 324 uint32_t uhs_driver_type_d : 1; ///< Supports SD UHS-I Driver Type D 325 uint32_t sdio_interrupt : 1; ///< Supports SD I/O Interrupt 326 uint32_t read_wait : 1; ///< Supports Read Wait (SD I/O) 327 uint32_t suspend_resume : 1; ///< Supports Suspend/Resume (SD I/O) 328 uint32_t mmc_interrupt : 1; ///< Supports MMC Interrupt 329 uint32_t mmc_boot : 1; ///< Supports MMC Boot 330 uint32_t rst_n : 1; ///< Supports RST_n Pin Control (eMMC) 331 uint32_t ccs : 1; ///< Supports Command Completion Signal (CCS) for CE-ATA 332 uint32_t ccs_timeout : 1; ///< Supports Command Completion Signal (CCS) timeout for CE-ATA 333 uint32_t reserved : 3; ///< Reserved (must be zero) 334 } ARM_MCI_CAPABILITIES; 335 336 337 /** 338 \brief Access structure of the MCI Driver. 339 */ 340 typedef struct _ARM_DRIVER_MCI { 341 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_MCI_GetVersion : Get driver version. 342 ARM_MCI_CAPABILITIES (*GetCapabilities)(void); ///< Pointer to \ref ARM_MCI_GetCapabilities : Get driver capabilities. 343 int32_t (*Initialize) (ARM_MCI_SignalEvent_t cb_event); ///< Pointer to \ref ARM_MCI_Initialize : Initialize MCI Interface. 344 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_MCI_Uninitialize : De-initialize MCI Interface. 345 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_MCI_PowerControl : Control MCI Interface Power. 346 int32_t (*CardPower) (uint32_t voltage); ///< Pointer to \ref ARM_MCI_CardPower : Set card power supply voltage. 347 int32_t (*ReadCD) (void); ///< Pointer to \ref ARM_MCI_ReadCD : Read Card Detect (CD) state. 348 int32_t (*ReadWP) (void); ///< Pointer to \ref ARM_MCI_ReadWP : Read Write Protect (WP) state. 349 int32_t (*SendCommand) (uint32_t cmd, 350 uint32_t arg, 351 uint32_t flags, 352 uint32_t *response); ///< Pointer to \ref ARM_MCI_SendCommand : Send Command to card and get the response. 353 int32_t (*SetupTransfer) (uint8_t *data, 354 uint32_t block_count, 355 uint32_t block_size, 356 uint32_t mode); ///< Pointer to \ref ARM_MCI_SetupTransfer : Setup data transfer operation. 357 int32_t (*AbortTransfer) (void); ///< Pointer to \ref ARM_MCI_AbortTransfer : Abort current data transfer. 358 int32_t (*Control) (uint32_t control, uint32_t arg); ///< Pointer to \ref ARM_MCI_Control : Control MCI Interface. 359 ARM_MCI_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_MCI_GetStatus : Get MCI status. 360 } const ARM_DRIVER_MCI; 361 362 #ifdef __cplusplus 363 } 364 #endif 365 366 #endif /* DRIVER_MCI_H_ */ 367
