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