begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_MCI.c

   1 /* -----------------------------------------------------------------------------
   2  * Copyright (c) 2013-2014 ARM Limited. All rights reserved.
   3  *
   4  * $Date:        2. January 2014
   5  * $Revision:    V2.00
   6  *
   7  * Project:      MCI Driver API
   8  * -------------------------------------------------------------------------- */
   9
  10
  11 /**
  12 \defgroup mci_interface_gr MCI Interface
  13 \brief    Driver API for Memory Card Interface using SD/MMC interface (%Driver_MCI.h)
  14
  15 \details
  16 The <b>Memory Card Interface</b> (MCI) implements the hardware abstraction layer for Secure Digital (SD) and Multi Media Card (MMC)
  17 memory that is typically used as file storage. For embedded systems, SD/MMC devices are available as memory cards in several
  18 forms (SD, miniSD, microSD, MMC, MMCmicro) or as non-removable devic
  19 es that are directly soldered to the PCB (eMMC).
  20
  21 \b References:
  22 - Wikipedia offers more information about the <a href="http://en.wikipedia.org/wiki/SD_card" target="_blank"><b>Secure Digital</b> memory</a>.
  23 - Wikipedia offers more information about the <a href="http://en.wikipedia.org/wiki/MultiMediaCard" target="_blank"><b>MultiMediaCard</b></a>.
  24 - The SD Association provides detailed documentation under <a href="http://www.sdcard.org">www.sdcard.org</a>.
  25 - The MultiMediaCard Association (merged with JEDEC) provides detailed documentation under <a href="http://www.jedec.org">www.jedec.org</a>.
  26
  27 **Block Diagram**
  28
  29 The MCI driver allows you to exchange data of the SD/MMC memory via SD/MMC interface.
  30
  31 The following modes are supported by SD/MMC memory cards:
  32
  33 - SPI bus mode: Serial Peripheral Interface Bus supported by most microcontrollers.
  34 - 1-bit SD/MMC Bus mode: proprietary data transfer protocol supported by SD/MMC interfaces.
  35 - 4-bit SD/MMC Bus mode: high-speed version of the SD/MMC interface using 4 data I/O pins.
  36 - 8-bit SD/MMC Bus mode: high-speed version of the SD/MMC interface using 8 data I/O pins.
  37
  38 \image html SPI_BusMode.png  "SD memory connected via SPI interface"
  39 <p>&nbsp;</p>
  40 \image html SD_1BitBusMode.png  "SD memory connected via 1-bit SD Bus Mode"
  41 <p>&nbsp;</p>
  42 \image html SD_4BitBusMode.png  "SD memory connected via 4-bit SD Bus Mode"
  43
  44
  45 **MCI API**
  46
  47 The following header files define the Application Programming Interface (API) for the MCI interface:
  48   - \b %Driver_MCI.h : Driver API for Memory Card Interface using SD/MMC interface
  49
  50 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
  51 peripherals of the microcontroller family.
  52
  53 \note
  54 For parameters, the value marked with (default) is the setting after the driver initialization.
  55
  56
  57 **Driver Functions**
  58
  59 The driver functions are published in the access struct as explained in \ref DriverFunctions
  60   - \ref ARM_DRIVER_MCI : access struct for MCI driver functions
  61 @{
  62 */
  63 /*
  64 A typical setup sequence for the driver is shown below:
  65
  66 <b>Example Code:</b>
  67
  68 \todo example
  69
  70
  71
  72 */
  73
  74 /*************   Structures ******************************************************************************************************/
  75 /**
  76 \struct     ARM_DRIVER_MCI
  77 \details
  78 The functions of the MCI are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for overview information.
  79
  80 Each instance of an MCI provides such an access structure.
  81 The instance is identified by a postfix number in the symbol name of the access structure, for example:
  82  - \b Driver_MCI0 is the name of the access struct of the first instance (no. 0).
  83  - \b Driver_MCI1 is the name of the access struct of the second instance (no. 1).
  84
  85 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_MCI<i>n</i></b>.
  86 The default is \token{0}, which connects a middleware to the first instance of a driver.
  87 *******************************************************************************************************************/
  88
  89 /**
  90 \struct     ARM_MCI_CAPABILITIES
  91 \details
  92 A MCI driver can be implemented with different capabilities.
  93 The data fields of this struct encode the capabilities implemented by this driver.
  94
  95 <b>Returned by:</b>
  96   - \ref ARM_MCI_GetCapabilities
  97 *******************************************************************************************************************/
  98
  99 /**
 100 \defgroup mci_event_gr MCI Events
 101 \brief The MCI driver generates call back events that are notified via the function \ref ARM_MCI_SignalEvent.
 102 \details
 103 This section provides the event values for the \ref ARM_MCI_SignalEvent callback function.
 104
 105 The following call back notification events are generated:
 106 @{
 107 \def ARM_MCI_EVENT_CARD_INSERTED
 108 \sa \ref ARM_MCI_SignalEvent
 109 \def ARM_MCI_EVENT_CARD_REMOVED
 110 \sa \ref  ARM_MCI_SignalEvent
 111 \def ARM_MCI_EVENT_COMMAND_COMPLETE
 112 \sa \ref ARM_MCI_SignalEvent
 113 \def ARM_MCI_EVENT_COMMAND_TIMEOUT
 114 \sa \ref ARM_MCI_SignalEvent
 115 \def ARM_MCI_EVENT_COMMAND_ERROR
 116 \sa \ref ARM_MCI_SignalEvent
 117 \def ARM_MCI_EVENT_TRANSFER_COMPLETE
 118 \sa \ref ARM_MCI_SignalEvent
 119 \def ARM_MCI_EVENT_TRANSFER_TIMEOUT
 120 \sa \ref ARM_MCI_SignalEvent
 121 \def ARM_MCI_EVENT_TRANSFER_ERROR
 122 \sa \ref ARM_MCI_SignalEvent
 123 \def ARM_MCI_EVENT_SDIO_INTERRUPT
 124 \sa \ref ARM_MCI_SignalEvent
 125 \def ARM_MCI_EVENT_CCS
 126 \sa \ref ARM_MCI_SignalEvent
 127 \def ARM_MCI_EVENT_CCS_TIMEOUT
 128 \sa \ref ARM_MCI_SignalEvent
 129 @}
 130 *******************************************************************************************************************/
 131
 132 //open mci_contorl_gr
 133 /**
 134 @{
 135 */
 136 /**
 137 \defgroup mci_control_gr MCI Control Codes
 138 \ingroup mci_interface_gr
 139 \brief Configure and control the MCI using the \ref ARM_MCI_Control.
 140 \details
 141 @{
 142 Many parameters of the MCI driver are configured using the \ref ARM_MCI_Control function.
 143
 144 The various MCI control codes define:
 145   - \ref mci_mode_ctrls configures and controls the MCI interface
 146   - \ref mci_bus_speed_ctrls specifies the bus speed mode
 147   - \ref mci_bus_data_width_ctrls specifies the data bus width
 148   - \ref mci_cmd_line_ctrls specifies the CMD line mode
 149   - \ref mci_driver_strength_ctrls specifies the driver strength
 150
 151 Refer to the function \ref ARM_MCI_Control for further details.
 152 @}
 153 *******************************************************************************************************************/
 154
 155
 156 /**
 157 \defgroup mci_mode_ctrls MCI Controls
 158 \ingroup mci_control_gr
 159 \brief Configure and control the MCI interface.
 160 \details
 161 The following codes are used as values for the parameter \em control of the function \ref ARM_MCI_Control to setup the MCI interface.
 162 @{
 163 \def ARM_MCI_BUS_SPEED
 164 \def ARM_MCI_BUS_SPEED_MODE
 165 \def ARM_MCI_BUS_CMD_MODE
 166 \def ARM_MCI_BUS_DATA_WIDTH
 167 \def ARM_MCI_DRIVER_STRENGTH
 168 \def ARM_MCI_CONTROL_RESET
 169 \def ARM_MCI_CONTROL_CLOCK_IDLE
 170 \def ARM_MCI_UHS_TUNING_OPERATION
 171 \def ARM_MCI_UHS_TUNING_RESULT
 172 \def ARM_MCI_DATA_TIMEOUT
 173 \def ARM_MCI_CSS_TIMEOUT
 174 \def ARM_MCI_MONITOR_SDIO_INTERRUPT
 175 \def ARM_MCI_CONTROL_READ_WAIT
 176 \def ARM_MCI_SUSPEND_TRANSFER
 177 \def ARM_MCI_RESUME_TRANSFER
 178 @}
 179 *******************************************************************************************************************/
 180
 181
 182 /**
 183 \defgroup mci_bus_speed_ctrls MCI Bus Speed Mode
 184 \ingroup mci_control_gr
 185 \brief Specify the bus speed mode.
 186 \details
 187 @{
 188 The function \ref ARM_MCI_Control with \em control = \ref ARM_MCI_BUS_SPEED configures the bus speed of the MCI to the
 189 requested bits/s specified with \em arg.
 190
 191 The function \ref ARM_MCI_Control with \em control = \ref ARM_MCI_BUS_SPEED_MODE configures the bus speed mode of the MCI
 192 as specified with \em arg listed bellow.
 193
 194 The function \ref ARM_MCI_GetCapabilities lists the supported bus speed modes. Initially, all SD cards use a 3.3 volt electrical interface.
 195 Some SD cards can switch to 1.8 volt operation. For example, the use of ultra-high-speed (UHS)
 196 SD cards requires 1.8 volt operation and a 4-bit bus data width. The data field \em uhs_signaling of the structure ARM_MCI_CAPABILITIES encodes
 197 whether the driver supports 1.8 volt UHS signaling.
 198
 199 \sa
 200  - \ref mci_driver_strength_ctrls
 201
 202 The following codes are defined:
 203
 204 \def ARM_MCI_BUS_DEFAULT_SPEED
 205 \def ARM_MCI_BUS_HIGH_SPEED
 206 \def ARM_MCI_BUS_UHS_SDR12
 207 \def ARM_MCI_BUS_UHS_SDR25
 208 \def ARM_MCI_BUS_UHS_SDR50
 209 \def ARM_MCI_BUS_UHS_SDR104
 210 \def ARM_MCI_BUS_UHS_DDR50
 211 @}
 212 *******************************************************************************************************************/
 213
 214
 215 /**
 216 \defgroup mci_bus_data_width_ctrls MCI Bus Data Width
 217 \ingroup mci_control_gr
 218 \brief Specify the data bus width.
 219 \details
 220 @{
 221 The function \ref ARM_MCI_Control with \em control = \ref ARM_MCI_BUS_DATA_WIDTH specifies with \em arg the number of data I/O pins on the SD/MMC interface.
 222
 223 For high-speed memory cards, a 4-bit bus data width should be used (or 8-bit for eMMC). The data fields \em data_width_4 and \em data_width_8
 224 of the structure ARM_MCI_CAPABILITIES encode whether the driver supports a specific bus data with.
 225
 226 The following codes are defined:
 227
 228 \def ARM_MCI_BUS_DATA_WIDTH_1
 229 \def ARM_MCI_BUS_DATA_WIDTH_4
 230 \def ARM_MCI_BUS_DATA_WIDTH_8
 231 \def ARM_MCI_BUS_DATA_WIDTH_4_DDR
 232 \def ARM_MCI_BUS_DATA_WIDTH_8_DDR
 233 @}
 234 *******************************************************************************************************************/
 235
 236
 237 /**
 238 \defgroup mci_cmd_line_ctrls MCI CMD Line Mode
 239 \ingroup mci_control_gr
 240 \brief Specify the CMD line mode (Push-Pull or Open Drain).
 241 \details
 242 @{
 243 Set the CMD line type with the function \ref ARM_MCI_Control.
 244 The CMD line mode is push-pull (default) or open drain (needed for older MMC).
 245
 246 \def ARM_MCI_BUS_CMD_PUSH_PULL
 247 \def ARM_MCI_BUS_CMD_OPEN_DRAIN
 248 @}
 249 *******************************************************************************************************************/
 250
 251
 252 /**
 253 \defgroup mci_driver_strength_ctrls MCI Driver Strength
 254 \ingroup mci_control_gr
 255 \brief Specify the driver strength.
 256 \details
 257 @{
 258 The function \ref ARM_MCI_Control with \em control = \ref ARM_MCI_DRIVER_STRENGTH specifies with \em arg the driver type of the SD interface.
 259
 260 \sa
 261   - \ref mci_bus_speed_ctrls
 262
 263 The following codes are defined:
 264
 265 \def ARM_MCI_DRIVER_TYPE_A
 266 \def ARM_MCI_DRIVER_TYPE_B
 267 \def ARM_MCI_DRIVER_TYPE_C
 268 \def ARM_MCI_DRIVER_TYPE_D
 269 @}
 270 *******************************************************************************************************************/
 271
 272 /**
 273 @}
 274 */   // close group mci_control_gr
 275
 276 /**
 277 \defgroup mci_send_command_flags_ctrls MCI Send Command Flags
 278 \ingroup mci_interface_gr
 279 \brief Specify various options for sending commands to the card and the expected response.
 280 \details
 281 \b ARM_MCI_xxx flags are sent with the function \ref ARM_MCI_SendCommand as the parameter \em flag.
 282 It controls the behavior of the command sent to the card and provides information about the expected response from the card.
 283
 284 The following codes are defined:
 285 @{
 286 \def ARM_MCI_RESPONSE_NONE
 287 \def ARM_MCI_RESPONSE_SHORT
 288 \def ARM_MCI_RESPONSE_SHORT_BUSY
 289 \def ARM_MCI_RESPONSE_LONG
 290 \def ARM_MCI_RESPONSE_INDEX
 291 \def ARM_MCI_RESPONSE_CRC
 292 \def ARM_MCI_WAIT_BUSY
 293 \def ARM_MCI_TRANSFER_DATA
 294 \def ARM_MCI_CARD_INITIALIZE
 295 \def ARM_MCI_INTERRUPT_COMMAND
 296 \def ARM_MCI_INTERRUPT_RESPONSE
 297 \def ARM_MCI_BOOT_OPERATION
 298 \def ARM_MCI_BOOT_ALTERNATIVE
 299 \def ARM_MCI_BOOT_ACK
 300 \def ARM_MCI_CCSD
 301 \def ARM_MCI_CCS
 302 @}
 303 *******************************************************************************************************************/
 304
 305 /**
 306 \defgroup mci_transfer_ctrls MCI Transfer Controls
 307 \ingroup mci_interface_gr
 308 \brief  Specify data transfer mode.
 309 \details
 310 Data transfer codes specifies the transfer direction and type and are used with the function \ref ARM_MCI_SetupTransfer as the parameter \em mode.
 311
 312 The following codes are defined:
 313 @{
 314 \def ARM_MCI_TRANSFER_READ
 315 \def ARM_MCI_TRANSFER_WRITE
 316 \def ARM_MCI_TRANSFER_BLOCK
 317 \def ARM_MCI_TRANSFER_STREAM
 318 @}
 319 *******************************************************************************************************************/
 320
 321 /**
 322 \defgroup mci_card_power_ctrls MCI Card Power Controls
 323 \ingroup mci_interface_gr
 324 \brief Specify Memory Card Power supply voltage
 325 \details
 326 Specifies the power supply volatge for a memory card. Used with the function \ref ARM_MCI_CardPower as the parameter \em voltage.
 327
 328 The following codes are defined:
 329 @{
 330 \def ARM_MCI_POWER_VDD_OFF
 331 \def ARM_MCI_POWER_VDD_3V3
 332 \def ARM_MCI_POWER_VDD_1V8
 333 \def ARM_MCI_POWER_VCCQ_OFF
 334 \def ARM_MCI_POWER_VCCQ_3V3
 335 \def ARM_MCI_POWER_VCCQ_1V8
 336 \def ARM_MCI_POWER_VCCQ_1V2
 337 @}
 338 *******************************************************************************************************************/
 339
 340
 341 /**
 342 \struct   ARM_MCI_STATUS
 343 \details
 344 Structure with information about the status of the MCI.
 345
 346 <b>Returned by:</b>
 347   - \ref ARM_MCI_GetStatus
 348 *******************************************************************************************************************/
 349
 350 /**
 351 \typedef    ARM_MCI_SignalEvent_t
 352 \details
 353 Provides the typedef for the callback function \ref ARM_MCI_SignalEvent.
 354
 355 <b>Parameter for:</b>
 356   - \ref ARM_MCI_Initialize
 357 *******************************************************************************************************************/
 358
 359
 360 //
 361 //   Functions
 362 //
 363 ARM_DRIVER_VERSION ARM_MCI_GetVersion (void)  {
 364   return { 0, 0 };
 365 }
 366 /**
 367 \fn       ARM_DRIVER_VERSION ARM_MCI_GetVersion (void)
 368 \details
 369 The function \b ARM_MCI_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 370  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 371  - Driver version is source code version of the actual driver implementation.
 372
 373 Example:
 374 \code
 375 extern ARM_DRIVER_MCI Driver_MCI0;
 376 ARM_DRIVER_MCI *drv_info;
 377
 378 void setup_mci (void)  {
 379   ARM_DRIVER_VERSION  version;
 380
 381   drv_info = &Driver_MCI0;
 382   version = drv_info->GetVersion ();
 383   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 384     // error handling
 385     return;
 386   }
 387 }
 388 \endcode
 389 *******************************************************************************************************************/
 390
 391 ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities (void)  {
 392   return { 0 };
 393 }
 394 /**
 395 \fn       ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities (void)
 396 \details
 397 The function \b ARM_MCI_GetCapabilities returns information about capabilities in this driver implementation.
 398 The data fields of the structure \ref ARM_MCI_CAPABILITIES encode various capabilities, for example
 399 supported bus modes ...
 400
 401 Example:
 402 \code
 403 extern ARM_DRIVER_MCI Driver_MCI0;
 404 ARM_DRIVER_MCI *drv_info;
 405
 406 void read_capabilities (void)  {
 407   ARM_MCI_CAPABILITIES drv_capabilities;
 408
 409   drv_info = &Driver_MCI0;
 410   drv_capabilities = drv_info->GetCapabilities ();
 411   // interrogate capabilities
 412
 413 }
 414 \endcode
 415 *******************************************************************************************************************/
 416
 417 int32_t ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event)  {
 418   return ARM_DRIVER_OK;
 419 }
 420 /**
 421 \fn       int32_t ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event)
 422 \details
 423 The function \b ARM_MCI_Initialize initializes the MCI interface.
 424 It is called when the middleware component starts operation.
 425
 426 The function performs the following operations:
 427   - Initializes the resources needed for the MCI interface.
 428   - Registers the \ref ARM_MCI_SignalEvent callback function.
 429
 430 The parameter \em cb_event is a pointer to the \ref ARM_MCI_SignalEvent callback function; use a NULL pointer
 431 when no callback signals are required.
 432
 433 \b Example:
 434  - see \ref mci_interface_gr - Driver Functions
 435
 436 *******************************************************************************************************************/
 437
 438 int32_t ARM_MCI_Uninitialize (void)  {
 439   return ARM_DRIVER_OK;
 440 }
 441 /**
 442 \fn       int32_t ARM_MCI_Uninitialize (void)
 443 \details
 444 The function \b ARM_MCI_Uninitialize de-initializes the resources of I2C interface.
 445
 446 It is called when the middleware component stops operation and releases the software resources used by the interface.
 447 *******************************************************************************************************************/
 448
 449 int32_t ARM_MCI_PowerControl (ARM_POWER_STATE state)  {
 450   return ARM_DRIVER_OK;
 451 }
 452 /**
 453 \fn int32_t ARM_MCI_PowerControl (ARM_POWER_STATE state)
 454 \details
 455 The function \b ARM_MCI_PowerControl operates the power modes of the MCI interface.
 456
 457 The parameter \em state can have the following values:
 458   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times.
 459                           If the peripheral is already in this mode, then the function performs no operation and returns with \ref ARM_DRIVER_OK.
 460   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 461   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 462
 463 Refer to \ref CallSequence for more information.
 464 *******************************************************************************************************************/
 465
 466 int32_t ARM_MCI_CardPower (uint32_t voltage)  {
 467   return ARM_DRIVER_OK;
 468 }
 469 /**
 470 \fn int32_t ARM_MCI_CardPower (uint32_t voltage)
 471 \details
 472 The function \b ARM_MCI_CardPower operates the memory card power supply voltage.
 473
 474 The parameter \em voltage sets the voltage. Not every voltage might be supported by the driver implementation.
 475 The structure \ref ARM_MCI_CAPABILITIES encodes the supported voltage. Retrieve the information with the function \ref ARM_MCI_GetCapabilities and
 476 verify the data fields.
 477
 478 The following values:
 479
 480 Parameter \em voltage                 | Description                   | supported when ARM_MCI_CAPABILITIES
 481 :-------------------------------------|:------------------------------|-----------------------------------------
 482 \ref ARM_MCI_POWER_VDD_OFF            | VDD (VCC) turned off          | <i>allways supported</i>
 483 \ref ARM_MCI_POWER_VDD_3V3            | VDD (VCC) = \token{3.3V}      | data field \em vdd = \token{1}
 484 \ref ARM_MCI_POWER_VDD_1V8            | VDD (VCC) = \token{1.8V}      | data field \em vdd_1v8 = \token{1}
 485 \ref ARM_MCI_POWER_VCCQ_OFF           | eMMC VCCQ turned off          | <i>allways supported</i>
 486 \ref ARM_MCI_POWER_VCCQ_3V3           | eMMC VCCQ = \token{3.3V}      | data field \em vccq = \token{1}
 487 \ref ARM_MCI_POWER_VCCQ_1V8           | eMMC VCCQ = \token{1.8V}      | data field \em vccq_1v8 = \token{1}
 488 \ref ARM_MCI_POWER_VCCQ_1V2           | eMMC VCCQ = \token{1.2V}      | data field \em vccq_1v2 = \token{1}
 489
 490 *******************************************************************************************************************/
 491
 492 int32_t ARM_MCI_ReadCD (void)  {
 493   return 0;
 494 }
 495 /**
 496 \fn int32_t ARM_MCI_ReadCD (void)
 497 \details
 498 The function \b ARM_MCI_ReadCD reads the status of the Card Detect (CD) pin.
 499 *******************************************************************************************************************/
 500
 501 int32_t ARM_MCI_ReadWP (void)  {
 502   return 0;
 503 }
 504 /**
 505 \fn int32_t ARM_MCI_ReadWP (void)
 506 \details
 507 The function \b ARM_MCI_ReadWP reads the status of the Write Protect (WP) pin.
 508 *******************************************************************************************************************/
 509
 510 int32_t ARM_MCI_SendCommand (uint32_t cmd, uint32_t arg, uint32_t flags, uint32_t *response)  {
 511   return ARM_DRIVER_OK;
 512 }
 513 /**
 514 \fn int32_t ARM_MCI_SendCommand (uint32_t cmd, uint32_t arg, uint32_t flags, uint32_t *response)
 515 \details
 516 The function \b ARM_MCI_SendCommand
 517  - sends commands to the memory card
 518  - retrieve the response from the card
 519  - optionally, start the data transfer.
 520
 521 The parameter \em cmd is the command sent to the card. \n
 522 The parameter \em arg contains arguments for the command \em cmd. \n
 523 The parameter \em flags controls the behavior of the operation and takes predefined values listed in the table below. \n
 524 The parameter \em response is a pointer to receive data.
 525
 526 The parameter \em flags can have the following values:
 527
 528 Parameter \em flags                   | Description
 529 :-------------------------------------|:------------
 530 \ref ARM_MCI_RESPONSE_NONE            | No response expected (default)
 531 \ref ARM_MCI_RESPONSE_SHORT           | Short response (\token{48}-bit) expected
 532 \ref ARM_MCI_RESPONSE_SHORT_BUSY      | Short response with busy signal (\token{48}-bit) expected
 533 \ref ARM_MCI_RESPONSE_LONG            | Long response (\token{136}-bit) expected
 534 \ref ARM_MCI_RESPONSE_INDEX           | Check command index in response
 535 \ref ARM_MCI_RESPONSE_CRC             | Check CRC in response
 536 \ref ARM_MCI_WAIT_BUSY                | Wait until busy before sending the command
 537 \ref ARM_MCI_TRANSFER_DATA            | Activate Data transfer
 538 \ref ARM_MCI_CARD_INITIALIZE          | Execute Memory Card initialization sequence
 539 \ref ARM_MCI_INTERRUPT_COMMAND        | Send Interrupt command (CMD40 - MMC only)
 540 \ref ARM_MCI_INTERRUPT_RESPONSE       | Send Interrupt response (CMD40 - MMC only)
 541 \ref ARM_MCI_BOOT_OPERATION           | Execute Boot operation (MMC only)
 542 \ref ARM_MCI_BOOT_ALTERNATIVE         | Execute Alternative Boot operation (MMC only)
 543 \ref ARM_MCI_BOOT_ACK                 | Expect Boot Acknowledge (MMC only)
 544 \ref ARM_MCI_CCSD                     | Send Command Completion Signal Disable (CCSD) for CE-ATA device
 545 \ref ARM_MCI_CCS                      | Expect Command Completion Signal (CCS) for CE-ATA device
 546
 547 Calling the function <b>ARM_MCI_SendCommand</b> only starts the operation.
 548 The function is non-blocking and returns as soon as the driver has started the operation.
 549 It is not allowed to call this function again until the operation is in progress.
 550
 551 After the command is sent the response is retrieved if specified with <b>ARM_MCI_RESPONSE_xxx</b> flags.
 552 When the command completes successfully (requested response is received without errors) the \ref ARM_MCI_EVENT_COMMAND_COMPLETE event is generated.
 553 In case that response is requested but not received the \ref ARM_MCI_EVENT_COMMAND_TIMEOUT event is generated instead.
 554 In case of invalid response (or CRC error) the \ref ARM_MCI_EVENT_COMMAND_ERROR event is generated instead.
 555 Progress of command operation can be monitored by calling the \ref ARM_MCI_GetStatus and checking the \em command_active flag.
 556
 557 After the command operation the data transfer operation is started if specified with <b>ARM_MCI_TRANSFER_DATA</b> flag.
 558 The data transfer needs to be configured before that by calling the \ref ARM_MCI_SetupTransfer.
 559 When the data transfer completes successfully the \ref ARM_MCI_EVENT_TRANSFER_COMPLETE event is generated.
 560 In case that data transfer is not completed in-time (specified by \ref ARM_MCI_DATA_TIMEOUT) the \ref ARM_MCI_EVENT_TRANSFER_TIMEOUT event is generated instead.
 561 In case of CRC errors the \ref ARM_MCI_EVENT_TRANSFER_ERROR event is generated instead.
 562 Progress of data transfer operation can be monitored by calling the \ref ARM_MCI_GetStatus and checking the \em transfer_active flag.
 563
 564 <b>See also:</b>
 565  - \ref ARM_MCI_SignalEvent
 566 *******************************************************************************************************************/
 567
 568 int32_t ARM_MCI_SetupTransfer (uint8_t  *data, uint32_t block_count, uint32_t block_size, uint32_t mode)  {
 569   return ARM_DRIVER_OK;
 570 }
 571 /**
 572 \fn int32_t ARM_MCI_SetupTransfer (uint8_t  *data, uint32_t block_count, uint32_t block_size, uint32_t mode)
 573 \details
 574 The function \b ARM_MCI_SetupTransfer prepares the data transfer operation that is initiated
 575 by calling the function \ref ARM_MCI_SendCommand with the parameter \em flags = \ref ARM_MCI_TRANSFER_DATA.
 576
 577 The parameter \em data is a pointer to the data to transfer. \n
 578 The parameter \em block_count is the number of blocks to transfer. \n
 579 The parameter \em block_size is the size of a block. \n
 580 The parameter \em mode sets the transfer mode and can have the values liste in the table below:
 581
 582 Transfer Directions                   | Description
 583 :-------------------------------------|:------------
 584 \ref ARM_MCI_TRANSFER_READ            | Read data from MCI
 585 \ref ARM_MCI_TRANSFER_WRITE           | Write data to MCI
 586 \ref ARM_MCI_TRANSFER_BLOCK (default) | Block Data transfer
 587 \ref ARM_MCI_TRANSFER_STREAM          | Stream Data transfer (MMC only)
 588
 589 *******************************************************************************************************************/
 590
 591 int32_t ARM_MCI_AbortTransfer (void)  {
 592   return ARM_DRIVER_OK;
 593 }
 594 /**
 595 \fn int32_t ARM_MCI_AbortTransfer (void)
 596 \details
 597 The function \b ARM_MCI_AbortTransfer aborts the active data transfer operation initiated with \ref ARM_MCI_SendCommand.
 598 *******************************************************************************************************************/
 599
 600
 601 int32_t ARM_MCI_Control (uint32_t control, uint32_t arg)  {
 602   return ARM_DRIVER_OK;
 603 }
 604 /**
 605 \fn            int32_t ARM_MCI_Control (uint32_t control, uint32_t arg)
 606 \details
 607 Th function \b ARM_MCI_Control controls the MCI interface and executes various operations.
 608
 609 The parameter \em control specifies the operation.
 610 Values for \em control cannot be ORed, but must be called separately in the code. \n
 611 The parameter \em arg provides, depending on the operation, additional information or sets values.
 612
 613 \note
 614 For parameters, the values marked with (default) are the setting after the driver initialization.
 615
 616 The table lists values for the parameter \em control.
 617
 618 Parameter \em control                 | Operation
 619 :-------------------------------------|:------------
 620 \ref ARM_MCI_BUS_SPEED                | Set the Bus Speed. The parameter \em arg specifies the speed in bits/s; The function returns the bus speed configured in bits/s.
 621 \ref ARM_MCI_BUS_SPEED_MODE           | Set the Bus Speed Mode. Predefined values for \em arg are listed in the table <b>Bus Speed Mode</b>.
 622 \ref ARM_MCI_BUS_CMD_MODE             | Set the CMD Line Mode. Predefined values for \em arg are listed in the table <b>Bus CMD Line Mode</b>.
 623 \ref ARM_MCI_BUS_DATA_WIDTH           | Set data bus width. Predefined values for \em arg are encoded in <b>Bus Data Width</b>.
 624 \ref ARM_MCI_DRIVER_STRENGTH          | Set driver strength. Predefined values for \em arg are listed in the table <b>Driver Type</b>
 625 \ref ARM_MCI_CONTROL_RESET            | Control optional RST_n Pin (eMMC). The parameter \em arg can have the values \token{[0:inactive(default); 1:active]}
 626 \ref ARM_MCI_CONTROL_CLOCK_IDLE       | Control clock generation on CLK Pin when idle. The parameter \em arg  can have the values \token{[0:disabled; 1:enabled]}
 627 \ref ARM_MCI_UHS_TUNING_OPERATION     | Sampling clock Tuning operation (SD UHS-I). The parameter \em arg  can have the values  \token{[0:reset; 1:execute]}
 628 \ref ARM_MCI_UHS_TUNING_RESULT        | Sampling clock Tuning result (SD UHS-I). Returns \token{[0:done; 1:in progress; -1:error]}
 629 \ref ARM_MCI_DATA_TIMEOUT             | Set Data timeout;  The parameter \em arg sets the timeout in bus cycles.
 630 \ref ARM_MCI_CSS_TIMEOUT              | Set Command Completion Signal (CCS) timeout. The parameter \em arg sets timeout in bus cycles.
 631 \ref ARM_MCI_MONITOR_SDIO_INTERRUPT   | Monitor SD I/O interrupt. The parameter \em arg  can have the values \token{[0:disabled(default); 1:enabled]}. Monitoring is automatically disabled when an interrupt is recognized.
 632 \ref ARM_MCI_CONTROL_READ_WAIT        | Control Read/Wait states for SD I/O. The parameter \em arg  can have the values \token{[0:disabled(default); 1:enabled]}.
 633 \ref ARM_MCI_SUSPEND_TRANSFER         | Suspend Data transfer (SD I/O). Returns the number of remaining bytes to transfer.
 634 \ref ARM_MCI_RESUME_TRANSFER          | Resume Data transfer (SD I/O).
 635
 636
 637 <b>Bus Speed Mode</b>
 638
 639 The function \ref ARM_MCI_GetCapabilities lists the supported bus speed modes. Initially, all SD cards use a 3.3 volt electrical interface.
 640 Some SD cards can switch to 1.8 volt operation. For example, the use of ultra-high-speed (UHS)
 641 SD cards requires 1.8 volt operation and a 4-bit bus data width. The bit field ARM_MCI_CAPABILITIES.uhs_signaling encodes
 642 whether the driver supports 1.8 volt UHS signaling.
 643
 644 The \em control operation \b ARM_MCI_BUS_SPEED_MODE  sets the bus speed mode using the parameter \em arg.
 645
 646 Parameter \em arg                                             | Bus Speed Mode
 647 :-------------------------------------------------------------|:------------------------------------------
 648 \ref  ARM_MCI_BUS_DEFAULT_SPEED (default)                     | Set the bus speed for SD/MMC cards: Default Speed mode up to \token{[25;26]MHz}
 649 \ref  ARM_MCI_BUS_HIGH_SPEED                                  | Set the bus speed for SD/MMC: High    Speed mode up to \token{[50;52]MHz}
 650 \ref  ARM_MCI_BUS_UHS_SDR12                                   | Set the bus speed for SD: SDR12  (Single Data Rate) up to  \token{25MHz,  12.5MB/s: UHS-I (Ultra High Speed) 1.8V signalling}
 651 \ref  ARM_MCI_BUS_UHS_SDR25                                   | Set the bus speed for SD: SDR25  (Single Data Rate) up to  \token{50MHz,  25  MB/s: UHS-I (Ultra High Speed) 1.8V signalling}
 652 \ref  ARM_MCI_BUS_UHS_SDR50                                   | Set the bus speed for SD: SDR50  (Single Data Rate) up to \token{100MHz,  50  MB/s: UHS-I (Ultra High Speed) 1.8V signalling}
 653 \ref  ARM_MCI_BUS_UHS_SDR104                                  | Set the bus speed for SD: SDR104 (Single Data Rate) up to \token{208MHz, 104  MB/s: UHS-I (Ultra High Speed) 1.8V signalling}
 654 \ref  ARM_MCI_BUS_UHS_DDR50                                   | Set the bus speed for SD: DDR50  (Dual Data Rate)   up to  \token{50MHz,  50  MB/s: UHS-I (Ultra High Speed) 1.8V signalling}
 655
 656
 657 <b>Bus CMD Line Mode</b>
 658
 659 The \em control operation \b ARM_MCI_BUS_CMD_MODE sets the bus command line mode using the parameter \em arg.
 660
 661 Parameter \em arg                                             | Bus CMD Line Mode
 662 :-------------------------------------------------------------|:------------------------------------------
 663 \ref ARM_MCI_BUS_CMD_PUSH_PULL  (default)                     | Set the Push-Pull CMD line
 664 \ref ARM_MCI_BUS_CMD_OPEN_DRAIN                               | Set the Open Drain CMD line (MMC only)
 665
 666
 667 <b>Bus Data Width</b>
 668
 669 Specifies the bus data width (the number of data I/O pins on the SD/MMC interface).
 670
 671 For high speed memory cards, a 4-bit bus data width should be used (or 8-bit for eMMC). The bit fields ARM_MCI_CAPABILITIES.data_width_4 and
 672 ARM_MCI_CAPABILITIES.data_width_8 encode whether the driver supports a specific bus data with.
 673
 674 The \em control operation \b ARM_MCI_BUS_DATA_WIDTH  sets the bus data width using the parameter \em arg.
 675
 676 Parameter \em arg                                             | Bus Data Width
 677 :-------------------------------------------------------------|:------------------------------------------
 678 \ref ARM_MCI_BUS_DATA_WIDTH_1 (default)                       | Set the Bus data width to \token{1 bit}
 679 \ref ARM_MCI_BUS_DATA_WIDTH_4                                 | Set the Bus data width to \token{4 bits}
 680 \ref ARM_MCI_BUS_DATA_WIDTH_8                                 | Set the Bus data width to \token{8 bits}
 681 \ref ARM_MCI_BUS_DATA_WIDTH_4_DDR                             | Set the Bus data width to \token{4 bits}, DDR (Dual Data Rate) - MMC only
 682 \ref ARM_MCI_BUS_DATA_WIDTH_8_DDR                             | Set the Bus data width to \token{8 bits}, DDR (Dual Data Rate) - MMC only
 683
 684
 685 <b>Driver Type</b>
 686
 687 Specifies the interface driver type.
 688
 689 The \em control operation \b ARM_MCI_DRIVER_STRENGTH  sets the interface driver type using the parameter \em arg.
 690
 691 Parameter \em arg                                             | Driver Type
 692 :-------------------------------------------------------------|:------------------------------------------
 693 \ref ARM_MCI_DRIVER_TYPE_A                                    | Set the interface to SD UHS-I Driver Type A
 694 \ref ARM_MCI_DRIVER_TYPE_B  (default)                         | Set the interface to SD UHS-I Driver Type B
 695 \ref ARM_MCI_DRIVER_TYPE_C                                    | Set the interface to SD UHS-I Driver Type C
 696 \ref ARM_MCI_DRIVER_TYPE_D                                    | Set the interface to SD UHS-I Driver Type D
 697
 698 \b Examples:
 699 \code
 700 // Set Bus Speed to 25MHz
 701 MCIdrv->Control(ARM_MCI_BUS_SPEED, 25000000);
 702
 703 // Set High Speed mode
 704 MCIdrv->Control(ARM_MCI_BUS_SPEED_MODE, ARM_MCI_BUS_HIGH_SPEED);
 705
 706 // Configure CMD line as Open Drain (MMC only)
 707 MCIdrv->Control(ARM_MCI_BUS_CMD_MODE, ARM_MCI_BUS_CMD_OPEN_DRAIN);
 708
 709 // Set Bus Data Width = 4bits
 710 MCIdrv->Control(ARM_MCI_BUS_DATA_WIDTH, ARM_MCI_BUS_DATA_WIDTH_4);
 711
 712 // Set SD UHS-I Driver Type B
 713 MCIdrv->Control(ARM_MCI_DRIVER_STRENGTH, ARM_MCI_DRIVER_TYPE_B);
 714
 715 // RTS_n Pin is not active by default
 716 // Assert RTS_n Pin (eMMC)
 717 MCIdrv->Control(ARM_MCI_CONTROL_RESET, 1);
 718 // De-assert RTS_n Pin (eMMC)
 719 MCIdrv->Control(ARM_MCI_CONTROL_RESET, 0);
 720
 721 // Clock generation on CLK when Idle: hardware specific default behavior
 722 // Enable Clock generation on CLK when Idle
 723 MCIdrv->Control(ARM_MCI_CONTROL_CLOCK_IDLE, 1);
 724 // Disable Clock generation on CLK when Idle
 725 MCIdrv->Control(ARM_MCI_CONTROL_CLOCK_IDLE, 0);
 726
 727 // UHS Tuning
 728 MCIdrv->Control(ARM_MCI_UHS_TUNING_OPERATION, 1);  // start tuning
 729 do {
 730   status = MCIdrv->Control(ARM_MCI_UHS_TUNING_RESULT, 0/*argument not used*/);
 731   if (status == -1) { break; /* tuning failed */ }
 732 } while (status == 1);
 733
 734 // Set Data Timeout to 12500000 bus cycles (0.5s @25MHz Bus Speed)
 735 // Default value is hardware specific (typically 2^32-1)
 736 MCIdrv->Control(ARM_MCI_DATA_TIMEOUT, 12500000);
 737
 738 // Set CSS Timeout to 1000000 bus cycles
 739 // Default value is hardware specific
 740 MCIdrv->Control(ARM_MCI_CSS_TIMEOUT, 1000000);
 741
 742 // SD I/O Interrupt Monitoring is disabled by default
 743 // Enable SD I/O Interrupt Monitoring
 744 MCIdrv->Control(ARM_MCI_MONITOR_SDIO_INTERRUPT, 1);
 745 // Disable SD I/O Interrupt Monitoring
 746 MCIdrv->Control(ARM_MCI_MONITOR_SDIO_INTERRUPT, 0);
 747
 748 // Read/Wait for SD I/O is disabled by default
 749 // Enable Read/Wait for SD I/O
 750 MCIdrv->Control(ARM_MCI_CONTROL_READ_WAIT, 1);
 751 // Disable Read/Wait for SD I/O
 752 MCIdrv->Control(ARM_MCI_CONTROL_READ_WAIT, 0);
 753
 754 // Suspend Data transfer (SD I/O)
 755 MCIdrv->Control(ARM_MCI_SUSPEND_TRANSFER, 0/*argument not used*/);
 756
 757 // Resume Data transfer (SD I/O)
 758 MCIdrv->Control(ARM_MCI_RESUME_TRANSFER, 0/*argument not used*/);
 759 \endcode
 760 *******************************************************************************************************************/
 761
 762 ARM_MCI_STATUS ARM_MCI_GetStatus (void)  {
 763   return ARM_DRIVER_OK;
 764 }
 765 /**
 766 \fn            ARM_MCI_STATUS ARM_MCI_GetStatus (void)
 767 \details
 768 The function \b ARM_MCI_GetStatus returns the current MCI interface status.
 769 *******************************************************************************************************************/
 770
 771 void ARM_MCI_SignalEvent (uint32_t event)  {
 772  // function body
 773 }
 774 /**
 775 \fn void ARM_MCI_SignalEvent (uint32_t event)
 776 \details
 777 The function \b ARM_MCI_SignalEvent is a callback function registered by the function \ref ARM_MCI_Initialize.
 778
 779 The parameter \em event indicates one or more events that occurred during driver operation.
 780 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 781
 782 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 783 data fields of the structure \ref ARM_NAND_CAPABILITIES, which can be retrieved with the function \ref ARM_NAND_GetCapabilities.
 784
 785 The following events can be generated:
 786
 787 Parameter \em event                        |Bit | Description                                                           | supported when \ref ARM_NAND_CAPABILITIES
 788 :------------------------------------------|---:|:----------------------------------------------------------------------|:---------------------------------------------
 789 \ref ARM_MCI_EVENT_CARD_INSERTED           | 0  | Occurs after Memory Card inserted                                     | <i>always supported</i>
 790 \ref ARM_MCI_EVENT_CARD_REMOVED            | 1  | Occurs after Memory Card removal                                      | <i>always supported</i>
 791 \ref ARM_MCI_EVENT_COMMAND_COMPLETE        | 2  | Occurs after command completed successfully                           | <i>always supported</i>
 792 \ref ARM_MCI_EVENT_COMMAND_TIMEOUT         | 3  | Occurs after command timeout                                          | <i>always supported</i>
 793 \ref ARM_MCI_EVENT_COMMAND_ERROR           | 4  | Occurs after command response error (CRC error or invalid response)   | <i>always supported</i>
 794 \ref ARM_MCI_EVENT_TRANSFER_COMPLETE       | 5  | Occurs after data transfer completed successfully                     | <i>always supported</i>
 795 \ref ARM_MCI_EVENT_TRANSFER_TIMEOUT        | 6  | Occurs after data transfer timeout                                    | <i>always supported</i>
 796 \ref ARM_MCI_EVENT_TRANSFER_ERROR          | 7  | Occurs after data transfer error (CRC failed)                         | <i>always supported</i>
 797 \ref ARM_MCI_EVENT_SDIO_INTERRUPT          | 8  | Indicates SD I/O Interrupt                                            | data field \em sdio_interrupt = \token{1}
 798 \ref ARM_MCI_EVENT_CCS                     | 9  | Indicates a Command Completion Signal (CCS)                           | data field \em ccs = \token{1}
 799 \ref ARM_MCI_EVENT_CCS_TIMEOUT             |10  | Indicates a Command Completion Signal (CCS) Timeout                   | data field \em css_timeout = \token{1}
 800
 801 <b>See also:</b>
 802  - \ref ARM_MCI_SendCommand
 803
 804 *******************************************************************************************************************/
 805
 806
 807 /**
 808 @}
 809 */
 810 // End MCI Interface