From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- docs/Driver/html/group__mci__interface__gr.html | 1776 +++++++++++++++++++++++ 1 file changed, 1776 insertions(+) create mode 100644 docs/Driver/html/group__mci__interface__gr.html (limited to 'docs/Driver/html/group__mci__interface__gr.html') diff --git a/docs/Driver/html/group__mci__interface__gr.html b/docs/Driver/html/group__mci__interface__gr.html new file mode 100644 index 0000000..4f28689 --- /dev/null +++ b/docs/Driver/html/group__mci__interface__gr.html @@ -0,0 +1,1776 @@ + + + + + +MCI Interface +CMSIS-Driver: MCI Interface + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-Driver +  Version 2.6.0 +
+
Peripheral Interface for Middleware and Application Code
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Content | +Data Structures | +Typedefs | +Functions
+
+
MCI Interface
+
+
+ +

Driver API for Memory Card Interface using SD/MMC interface (Driver_MCI.h) +More...

+ + + + + + + + + + + + + + + + + +

+Content

 MCI Events
 The MCI driver generates call back events that are notified via the function ARM_MCI_SignalEvent.
 
 MCI Control Codes
 Configure and control the MCI using the ARM_MCI_Control.
 
 MCI Send Command Flags
 Specify various options for sending commands to the card and the expected response.
 
 MCI Transfer Controls
 Specify data transfer mode.
 
 MCI Card Power Controls
 Specify Memory Card Power supply voltage.
 
+ + + + + + + + + + +

+Data Structures

struct  ARM_DRIVER_MCI
 Access structure of the MCI Driver. More...
 
struct  ARM_MCI_CAPABILITIES
 MCI Driver Capabilities. More...
 
struct  ARM_MCI_STATUS
 MCI Status. More...
 
+ + + + +

+Typedefs

typedef void(* ARM_MCI_SignalEvent_t )(uint32_t event)
 Pointer to ARM_MCI_SignalEvent : Signal MCI Card Event. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

ARM_DRIVER_VERSION ARM_MCI_GetVersion (void)
 Get driver version. More...
 
ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities (void)
 Get driver capabilities. More...
 
int32_t ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event)
 Initialize the Memory Card Interface. More...
 
int32_t ARM_MCI_Uninitialize (void)
 De-initialize Memory Card Interface. More...
 
int32_t ARM_MCI_PowerControl (ARM_POWER_STATE state)
 Control Memory Card Interface Power. More...
 
int32_t ARM_MCI_CardPower (uint32_t voltage)
 Set Memory Card Power supply voltage. More...
 
int32_t ARM_MCI_ReadCD (void)
 Read Card Detect (CD) state. More...
 
int32_t ARM_MCI_ReadWP (void)
 Read Write Protect (WP) state. More...
 
int32_t ARM_MCI_SendCommand (uint32_t cmd, uint32_t arg, uint32_t flags, uint32_t *response)
 Send Command to card and get the response. More...
 
int32_t ARM_MCI_SetupTransfer (uint8_t *data, uint32_t block_count, uint32_t block_size, uint32_t mode)
 Setup read or write transfer operation. More...
 
int32_t ARM_MCI_AbortTransfer (void)
 Abort current read/write data transfer. More...
 
int32_t ARM_MCI_Control (uint32_t control, uint32_t arg)
 Control MCI Interface. More...
 
ARM_MCI_STATUS ARM_MCI_GetStatus (void)
 Get MCI status. More...
 
void ARM_MCI_SignalEvent (uint32_t event)
 Callback function that signals a MCI Card Event. More...
 
+

Description

+

Driver API for Memory Card Interface using SD/MMC interface (Driver_MCI.h)

+

The Memory Card Interface (MCI) implements the hardware abstraction layer for Secure Digital (SD) and Multi Media Card (MMC) memory that is typically used as file storage. For embedded systems, SD/MMC devices are available as memory cards in several forms (SD, miniSD, microSD, MMC, MMCmicro) or as non-removable devic es that are directly soldered to the PCB (eMMC).

+

References:

+
    +
  • Wikipedia offers more information about the Secure Digital memory.
    • +
  • Wikipedia offers more information about the MultiMediaCard.
    • +
  • The SD Association provides detailed documentation under www.sdcard.org.
    • +
  • The MultiMediaCard Association (merged with JEDEC) provides detailed documentation under www.jedec.org.
    • +
+

Block Diagram

+

The MCI driver allows you to exchange data of the SD/MMC memory via SD/MMC interface.

+

The following modes are supported by SD/MMC memory cards:

+
    +
  • SPI bus mode: Serial Peripheral Interface Bus supported by most microcontrollers.
    • +
  • 1-bit SD/MMC Bus mode: proprietary data transfer protocol supported by SD/MMC interfaces.
    • +
  • 4-bit SD/MMC Bus mode: high-speed version of the SD/MMC interface using 4 data I/O pins.
    • +
  • 8-bit SD/MMC Bus mode: high-speed version of the SD/MMC interface using 8 data I/O pins.
    • +
+
+SPI_BusMode.png +
+SD memory connected via SPI interface
+

 

+
+SD_1BitBusMode.png +
+SD memory connected via 1-bit SD Bus Mode
+

 

+
+SD_4BitBusMode.png +
+SD memory connected via 4-bit SD Bus Mode
+

MCI API

+

The following header files define the Application Programming Interface (API) for the MCI interface:

+
    +
  • Driver_MCI.h : Driver API for Memory Card Interface using SD/MMC interface
    • +
+

The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.

+
Note
For parameters, the value marked with (default) is the setting after the driver initialization.
+

Driver Functions

+

The driver functions are published in the access struct as explained in Common Driver Functions

+ +

Example Code

+

The following example code shows the usage of the MCI interface.

+
+
#include "Driver_MCI.h"
+
+
+
/* Usage example: ARM_MCI_Initialize ----------------------------------------*/
+
+
// ARM_MCI_SignalEvent callback function prototype
+
void MCI_SignalEvent_Callback (uint32_t event);
+
+
void init_driver (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
+
status = drv->Initialize (&MCI_SignalEvent_Callback);
+
+
if (status != ARM_DRIVER_OK) {
+
// Initialization and event callback registration failed
+
}
+
}
+
+
/* Usage example: ARM_MCI_Uninitialize --------------------------------------*/
+
+
void uninit_driver (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
+
status = drv->Uninitialize ();
+
+
if (status == ARM_DRIVER_OK) {
+
// Driver successfully uninitialized
+
}
+
}
+
+
/* Usage example: ARM_MCI_PowerControl --------------------------------------*/
+
+
void control_driver_power (ARM_DRIVER_MCI *drv, bool enable) {
+
int32_t status;
+
+
if (enable == true) {
+
status = drv->PowerControl (ARM_POWER_FULL);
+
}
+
else {
+
status = drv->PowerControl (ARM_POWER_OFF);
+
}
+
+
if (status == ARM_DRIVER_OK) {
+
// Driver power enabled/disabled
+
}
+
}
+
+
/* Usage example: ARM_MCI_CardPower -----------------------------------------*/
+
+
ARM_MCI_CAPABILITIES drv_capabilities;
+
+
void set_card_vdd_3v3 (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
+
if (drv_capabilities.vdd == 1U) {
+
// Power switching to 3.3V supported
+
status = drv->CardPower (ARM_MCI_POWER_VDD_3V3);
+
+
if (status == ARM_DRIVER_OK) {
+
// Card power set to 3.3V
+
}
+
}
+
}
+
+
/* Usage example: ARM_MCI_ReadCD --------------------------------------------*/
+
+
void read_card_detect_state (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
+
status = drv->ReadCD();
+
+
if (status == 1) {
+
// Memory card is detected
+
}
+
else {
+
if (status == 0) {
+
// Memory card is not detected
+
}
+
else {
+
// Error reading card detect pin state
+
}
+
}
+
}
+
+
/* Usage example: ARM_MCI_ReadWP --------------------------------------------*/
+
+
void read_write_protect_state (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
+
status = drv->ReadWP();
+
+
if (status == 1) {
+
// Memory card write protection is enabled
+
}
+
else {
+
if (status == 0) {
+
// Memory card write protection is disabled
+
}
+
else {
+
// Error reading write protect pin state
+
}
+
}
+
}
+
+
/* Usage example: ARM_MCI_SendCommand ---------------------------------------*/
+
+
volatile uint32_t MCI_Events;
+
+
void MCI_SignalEvent_Callback (uint32_t event) {
+
// Save current event
+
MCI_Events |= event;
+
}
+
+
void send_CMD0 (ARM_DRIVER_MCI *drv) {
+
int32_t status;
+
uint32_t cmd;
+
+
MCI_Events = 0U; //Clear MCI driver event flags
+
cmd = 0U; // Set GO_IDLE_STATE command code
+
+
status = drv->SendCommand (cmd, 0U, ARM_MCI_CARD_INITIALIZE | ARM_MCI_RESPONSE_NONE, NULL);
+
+
if (status == ARM_DRIVER_OK) {
+
/* Wait for event */
+
while ((MCI_Events & ARM_MCI_EVENT_COMMAND_COMPLETE) == 0U);
+
// Command was successfully sent to memory card
+
// ..
+
}
+
else {
+
// Error
+
}
+
}
+
+
/* Usage example: ARM_MCI_SetupTransfer -------------------------------------*/
+
+
volatile uint32_t MCI_Events;
+
+
void MCI_SignalEvent_Callback (uint32_t event) {
+
MCI_Events |= event; // Save current event
+
}
+
+
void read_sector (ARM_DRIVER_MCI *drv, uint8_t *buf, uint32_t sz) {
+
int32_t status;
+
uint32_t cmd, arg;
+
uint32_t resp;
+
+
if (sz < 512U) {
+
// Invalid buffer size, sector consists of 512 bytes
+
//...
+
}
+
+
status = drv->SetupTransfer (buf, 1U, 512U, ARM_MCI_TRANSFER_READ | ARM_MCI_TRANSFER_BLOCK);
+
+
if (status == ARM_DRIVER_OK) {
+
MCI_Events = 0U; //Clear MCI driver event flags
+
+
cmd = 17U; // Set READ_SINGLE_BLOCK command
+
arg = 0U; // Set sector number
+
+
status = drv->SendCommand (cmd, arg, ARM_MCI_RESPONSE_SHORT | ARM_MCI_RESPONSE_CRC | ARM_MCI_TRANSFER_DATA, &resp);
+
+
if (status == ARM_DRIVER_OK) {
+
/* Wait for event */
+
while ((MCI_Events & ARM_MCI_EVENT_COMMAND_COMPLETE) == 0U);
+
// Command was successfully sent to memory card
+
if ((resp & 0x03U) == 0U) {
+
// Sector number is valid, wait until data transfer completes
+
while ((MCI_Events & ARM_MCI_EVENT_TRANSFER_COMPLETE) == 0U);
+
// Data was successfully read from memory card
+
// ...
+
}
+
}
+
}
+
}
+
+
/* Usage example: ARM_MCI_AbortTransfer -------------------------------------*/
+
+
void abort_data_transfer (ARM_DRIVER_MCI *drv) {
+
ARM_MCI_STATUS drv_status;
+
+
drv_status = drv->GetStatus();
+
+
if (drv_status.transfer_active == 1U) {
+
// Data transfer is active, abort the transfer
+
if (drv->AbortTransfer() == ARM_DRIVER_OK) {
+
// Transfer aborted
+
// ...
+
}
+
}
+
}
+
+
/* Usage example: ARM_MCI_GetStatus -----------------------------------------*/
+
+
void check_transfer_status (ARM_DRIVER_MCI *drv) {
+
ARM_MCI_STATUS drv_status;
+
+
drv_status = drv->GetStatus();
+
+
if (drv_status.transfer_active == 1U) {
+
// Data transfer is active
+
}
+
+
if (drv_status.transfer_timeout == 1U) {
+
// Data not received, timeout expired
+
}
+
+
if (drv_status.transfer_error == 1U) {
+
// Data transfer ended with error
+
}
+
}
+
+
/* Usage example: ARM_MCI_SignalEvent ---------------------------------------*/
+
+
void MCI_SignalEvent_Callback (uint32_t event) {
+
if ((event & ARM_MCI_EVENT_CARD_INSERTED) != 0U) {
+
// Memory card was inserted into socket
+
}
+
if ((event & ARM_MCI_EVENT_CARD_REMOVED) != 0U) {
+
// Memory card was removed from socket
+
}
+
+
if ((event & ARM_MCI_EVENT_COMMAND_COMPLETE) != 0U) {
+
// Command was successfully sent to memory card
+
}
+
if ((event & ARM_MCI_EVENT_COMMAND_TIMEOUT) != 0U) {
+
// Command response was not received in time
+
}
+
if ((event & ARM_MCI_EVENT_COMMAND_ERROR) != 0U) {
+
// Command response was invalid
+
}
+
+
if ((event & ARM_MCI_EVENT_TRANSFER_COMPLETE) != 0U) {
+
// Data successfully transferred from/to memory card
+
}
+
if ((event & ARM_MCI_EVENT_TRANSFER_TIMEOUT) != 0U) {
+
// Data not transferred from/to memory card, timeout expired
+
}
+
if ((event & ARM_MCI_EVENT_TRANSFER_ERROR) != 0U) {
+
// Data transfer ended with errors
+
}
+
+
if ((event & ARM_MCI_EVENT_SDIO_INTERRUPT) != 0U) {
+
// SD I/O card sent interrupt request
+
}
+
+
if ((event & ARM_MCI_EVENT_CCS) != 0U) {
+
// CE-ATA command completion signal received
+
}
+
if ((event & ARM_MCI_EVENT_CCS_TIMEOUT) != 0U) {
+
// CE-ATA command completion signal wait timeout expired
+
}
+
}
+

Data Structure Documentation

+ +
+
+ + + + +
struct ARM_DRIVER_MCI
+
+

Access structure of the MCI Driver.

+

The functions of the MCI are accessed by function pointers exposed by this structure. Refer to Common Driver Functions for overview information.

+

Each instance of an MCI provides such an access structure. The instance is identified by a postfix number in the symbol name of the access structure, for example:

+
    +
  • Driver_MCI0 is the name of the access struct of the first instance (no. 0).
    • +
  • Driver_MCI1 is the name of the access struct of the second instance (no. 1).
    • +
+

A configuration setting in the middleware allows connecting the middleware to a specific driver instance Driver_MCIn. The default is 0, which connects a middleware to the first instance of a driver.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Data Fields

ARM_DRIVER_VERSION(* GetVersion )(void)
 Pointer to ARM_MCI_GetVersion : Get driver version. More...
 
ARM_MCI_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_MCI_GetCapabilities : Get driver capabilities. More...
 
int32_t(* Initialize )(ARM_MCI_SignalEvent_t cb_event)
 Pointer to ARM_MCI_Initialize : Initialize MCI Interface. More...
 
int32_t(* Uninitialize )(void)
 Pointer to ARM_MCI_Uninitialize : De-initialize MCI Interface. More...
 
int32_t(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_MCI_PowerControl : Control MCI Interface Power. More...
 
int32_t(* CardPower )(uint32_t voltage)
 Pointer to ARM_MCI_CardPower : Set card power supply voltage. More...
 
int32_t(* ReadCD )(void)
 Pointer to ARM_MCI_ReadCD : Read Card Detect (CD) state. More...
 
int32_t(* ReadWP )(void)
 Pointer to ARM_MCI_ReadWP : Read Write Protect (WP) state. More...
 
int32_t(* SendCommand )(uint32_t cmd, uint32_t arg, uint32_t flags, uint32_t *response)
 Pointer to ARM_MCI_SendCommand : Send Command to card and get the response. More...
 
int32_t(* SetupTransfer )(uint8_t *data, uint32_t block_count, uint32_t block_size, uint32_t mode)
 Pointer to ARM_MCI_SetupTransfer : Setup data transfer operation. More...
 
int32_t(* AbortTransfer )(void)
 Pointer to ARM_MCI_AbortTransfer : Abort current data transfer. More...
 
int32_t(* Control )(uint32_t control, uint32_t arg)
 Pointer to ARM_MCI_Control : Control MCI Interface. More...
 
ARM_MCI_STATUS(* GetStatus )(void)
 Pointer to ARM_MCI_GetStatus : Get MCI status. More...
 
+

Field Documentation

+ +
+
+ + + + +
ARM_DRIVER_VERSION(* GetVersion)(void)
+
+ +

Pointer to ARM_MCI_GetVersion : Get driver version.

+ +
+
+ +
+
+ + + + +
ARM_MCI_CAPABILITIES(* GetCapabilities)(void)
+
+ +

Pointer to ARM_MCI_GetCapabilities : Get driver capabilities.

+ +
+
+ +
+
+ + + + +
int32_t(* Initialize)(ARM_MCI_SignalEvent_t cb_event)
+
+ +

Pointer to ARM_MCI_Initialize : Initialize MCI Interface.

+ +
+
+ +
+
+ + + + +
int32_t(* Uninitialize)(void)
+
+ +

Pointer to ARM_MCI_Uninitialize : De-initialize MCI Interface.

+ +
+
+ +
+
+ + + + +
int32_t(* PowerControl)(ARM_POWER_STATE state)
+
+ +

Pointer to ARM_MCI_PowerControl : Control MCI Interface Power.

+ +
+
+ +
+
+ + + + +
int32_t(* CardPower)(uint32_t voltage)
+
+ +

Pointer to ARM_MCI_CardPower : Set card power supply voltage.

+ +
+
+ +
+
+ + + + +
int32_t(* ReadCD)(void)
+
+ +

Pointer to ARM_MCI_ReadCD : Read Card Detect (CD) state.

+ +
+
+ +
+
+ + + + +
int32_t(* ReadWP)(void)
+
+ +

Pointer to ARM_MCI_ReadWP : Read Write Protect (WP) state.

+ +
+
+ +
+
+ + + + +
int32_t(* SendCommand)(uint32_t cmd, uint32_t arg, uint32_t flags, uint32_t *response)
+
+ +

Pointer to ARM_MCI_SendCommand : Send Command to card and get the response.

+ +
+
+ +
+
+ + + + +
int32_t(* SetupTransfer)(uint8_t *data, uint32_t block_count, uint32_t block_size, uint32_t mode)
+
+ +

Pointer to ARM_MCI_SetupTransfer : Setup data transfer operation.

+ +
+
+ +
+
+ + + + +
int32_t(* AbortTransfer)(void)
+
+ +

Pointer to ARM_MCI_AbortTransfer : Abort current data transfer.

+ +
+
+ +
+
+ + + + +
int32_t(* Control)(uint32_t control, uint32_t arg)
+
+ +

Pointer to ARM_MCI_Control : Control MCI Interface.

+ +
+
+ +
+
+ + + + +
ARM_MCI_STATUS(* GetStatus)(void)
+
+ +

Pointer to ARM_MCI_GetStatus : Get MCI status.

+ +
+
+ +
+
+ +
+
+ + + + +
struct ARM_MCI_CAPABILITIES
+
+

MCI Driver Capabilities.

+

A MCI driver can be implemented with different capabilities. The data fields of this struct encode the capabilities implemented by this driver.

+

Returned by:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data Fields
+uint32_t +cd_state: 1 +Card Detect State available.
+uint32_t +cd_event: 1 +Signal Card Detect change event.
+uint32_t +wp_state: 1 +Write Protect State available.
+uint32_t +vdd: 1 +Supports VDD Card Power Supply Control.
+uint32_t +vdd_1v8: 1 +Supports 1.8 VDD Card Power Supply.
+uint32_t +vccq: 1 +Supports VCCQ Card Power Supply Control (eMMC)
+uint32_t +vccq_1v8: 1 +Supports 1.8 VCCQ Card Power Supply (eMMC)
+uint32_t +vccq_1v2: 1 +Supports 1.2 VCCQ Card Power Supply (eMMC)
+uint32_t +data_width_4: 1 +Supports 4-bit data.
+uint32_t +data_width_8: 1 +Supports 8-bit data.
+uint32_t +data_width_4_ddr: 1 +Supports 4-bit data, DDR (Dual Data Rate) - MMC only.
+uint32_t +data_width_8_ddr: 1 +Supports 8-bit data, DDR (Dual Data Rate) - MMC only.
+uint32_t +high_speed: 1 +Supports SD/MMC High Speed Mode.
+uint32_t +uhs_signaling: 1 +Supports SD UHS-I (Ultra High Speed) 1.8V signaling.
+uint32_t +uhs_tuning: 1 +Supports SD UHS-I tuning.
+uint32_t +uhs_sdr50: 1 +Supports SD UHS-I SDR50 (Single Data Rate) up to 50MB/s.
+uint32_t +uhs_sdr104: 1 +Supports SD UHS-I SDR104 (Single Data Rate) up to 104MB/s.
+uint32_t +uhs_ddr50: 1 +Supports SD UHS-I DDR50 (Dual Data Rate) up to 50MB/s.
+uint32_t +uhs_driver_type_a: 1 +Supports SD UHS-I Driver Type A.
+uint32_t +uhs_driver_type_c: 1 +Supports SD UHS-I Driver Type C.
+uint32_t +uhs_driver_type_d: 1 +Supports SD UHS-I Driver Type D.
+uint32_t +sdio_interrupt: 1 +Supports SD I/O Interrupt.
+uint32_t +read_wait: 1 +Supports Read Wait (SD I/O)
+uint32_t +suspend_resume: 1 +Supports Suspend/Resume (SD I/O)
+uint32_t +mmc_interrupt: 1 +Supports MMC Interrupt.
+uint32_t +mmc_boot: 1 +Supports MMC Boot.
+uint32_t +rst_n: 1 +Supports RST_n Pin Control (eMMC)
+uint32_t +ccs: 1 +Supports Command Completion Signal (CCS) for CE-ATA.
+uint32_t +ccs_timeout: 1 +Supports Command Completion Signal (CCS) timeout for CE-ATA.
+uint32_t +reserved: 3 +Reserved (must be zero)
+ +
+
+ +
+
+ + + + +
struct ARM_MCI_STATUS
+
+

MCI Status.

+

Structure with information about the status of the MCI.

+

Returned by:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data Fields
+uint32_t +command_active: 1 +Command active flag.
+uint32_t +command_timeout: 1 +Command timeout flag (cleared on start of next command)
+uint32_t +command_error: 1 +Command error flag (cleared on start of next command)
+uint32_t +transfer_active: 1 +Transfer active flag.
+uint32_t +transfer_timeout: 1 +Transfer timeout flag (cleared on start of next command)
+uint32_t +transfer_error: 1 +Transfer error flag (cleared on start of next command)
+uint32_t +sdio_interrupt: 1 +SD I/O Interrupt flag (cleared on start of monitoring)
+uint32_t +ccs: 1 +CCS flag (cleared on start of next command)
+uint32_t +reserved: 24 +
+ +
+
+

Typedef Documentation

+ +
+
+ + + + +
ARM_MCI_SignalEvent_t
+
+ +

Pointer to ARM_MCI_SignalEvent : Signal MCI Card Event.

+

Provides the typedef for the callback function ARM_MCI_SignalEvent.

+

Parameter for:

+ + +
+
+

Function Documentation

+ +
+
+ + + + + + + + +
ARM_DRIVER_VERSION ARM_MCI_GetVersion (void )
+
+ +

Get driver version.

+
Returns
ARM_DRIVER_VERSION
+

The function ARM_MCI_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION

+
    +
  • API version is the version of the CMSIS-Driver specification used to implement this driver.
    • +
  • Driver version is source code version of the actual driver implementation.
    • +
+

Example:

+
extern ARM_DRIVER_MCI Driver_MCI0;
+
ARM_DRIVER_MCI *drv_info;
+
+
void setup_mci (void) {
+
ARM_DRIVER_VERSION version;
+
+
drv_info = &Driver_MCI0;
+
version = drv_info->GetVersion ();
+
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
+
// error handling
+
return;
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities (void )
+
+ +

Get driver capabilities.

+
Returns
ARM_MCI_CAPABILITIES
+

The function ARM_MCI_GetCapabilities returns information about capabilities in this driver implementation. The data fields of the structure ARM_MCI_CAPABILITIES encode various capabilities, for example supported bus modes ...

+

Example:

+
extern ARM_DRIVER_MCI Driver_MCI0;
+
ARM_DRIVER_MCI *drv_info;
+
+
void read_capabilities (void) {
+
ARM_MCI_CAPABILITIES drv_capabilities;
+
+
drv_info = &Driver_MCI0;
+
drv_capabilities = drv_info->GetCapabilities ();
+
// interrogate capabilities
+
+
}
+
+
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event)
+
+ +

Initialize the Memory Card Interface.

+
Parameters
+ + +
[in]cb_eventPointer to ARM_MCI_SignalEvent
+
+
+
Returns
Status Error Codes
+

The function ARM_MCI_Initialize initializes the MCI interface. It is called when the middleware component starts operation.

+

The function performs the following operations:

+
    +
  • Initializes the resources needed for the MCI interface.
    • +
  • Registers the ARM_MCI_SignalEvent callback function.
    • +
+

The parameter cb_event is a pointer to the ARM_MCI_SignalEvent callback function; use a NULL pointer when no callback signals are required.

+

Example:

+ + +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_Uninitialize (void )
+
+ +

De-initialize Memory Card Interface.

+
Returns
Status Error Codes
+

The function ARM_MCI_Uninitialize de-initializes the resources of I2C interface.

+

It is called when the middleware component stops operation and releases the software resources used by the interface.

+ +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_PowerControl (ARM_POWER_STATE state)
+
+ +

Control Memory Card Interface Power.

+
Parameters
+ + +
[in]statePower state ARM_POWER_STATE
+
+
+
Returns
Status Error Codes
+

The function ARM_MCI_PowerControl operates the power modes of the MCI interface.

+

The parameter state can have the following values:

+
    +
  • ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode, then the function performs no operation and returns with ARM_DRIVER_OK.
    • +
  • ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
    • +
  • ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
    • +
+

Refer to Function Call Sequence for more information.

+ +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_CardPower (uint32_t voltage)
+
+ +

Set Memory Card Power supply voltage.

+
Parameters
+ + +
[in]voltageMemory Card Power supply voltage
+
+
+
Returns
Status Error Codes
+

The function ARM_MCI_CardPower operates the memory card power supply voltage.

+

The parameter voltage sets the voltage. Not every voltage might be supported by the driver implementation. The structure ARM_MCI_CAPABILITIES encodes the supported voltage. Retrieve the information with the function ARM_MCI_GetCapabilities and verify the data fields.

+

The following values:

+ + + + + + + + + + + + + + + + + +
Parameter voltage Description supported when ARM_MCI_CAPABILITIES
ARM_MCI_POWER_VDD_OFF VDD (VCC) turned off allways supported
ARM_MCI_POWER_VDD_3V3 VDD (VCC) = 3.3V data field vdd = 1
ARM_MCI_POWER_VDD_1V8 VDD (VCC) = 1.8V data field vdd_1v8 = 1
ARM_MCI_POWER_VCCQ_OFF eMMC VCCQ turned off allways supported
ARM_MCI_POWER_VCCQ_3V3 eMMC VCCQ = 3.3V data field vccq = 1
ARM_MCI_POWER_VCCQ_1V8 eMMC VCCQ = 1.8V data field vccq_1v8 = 1
ARM_MCI_POWER_VCCQ_1V2 eMMC VCCQ = 1.2V data field vccq_1v2 = 1
+ +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_ReadCD (void )
+
+ +

Read Card Detect (CD) state.

+
Returns
1:card detected, 0:card not detected, or error
+

The function ARM_MCI_ReadCD reads the status of the Card Detect (CD) pin.

+ +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_ReadWP (void )
+
+ +

Read Write Protect (WP) state.

+
Returns
1:write protected, 0:not write protected, or error
+

The function ARM_MCI_ReadWP reads the status of the Write Protect (WP) pin.

+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
int32_t ARM_MCI_SendCommand (uint32_t cmd,
uint32_t arg,
uint32_t flags,
uint32_t * response 
)
+
+ +

Send Command to card and get the response.

+
Parameters
+ + + + + +
[in]cmdMemory Card command
[in]argCommand argument
[in]flagsCommand flags
[out]responsePointer to buffer for response
+
+
+
Returns
Status Error Codes
+

The function ARM_MCI_SendCommand

+
    +
  • sends commands to the memory card
    • +
  • retrieve the response from the card
    • +
  • optionally, start the data transfer.
    • +
+

The parameter cmd is the command sent to the card.
+The parameter arg contains arguments for the command cmd.
+The parameter flags controls the behavior of the operation and takes predefined values listed in the table below.
+The parameter response is a pointer to receive data.

+

The parameter flags can have the following values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter flags Description
ARM_MCI_RESPONSE_NONE No response expected (default)
ARM_MCI_RESPONSE_SHORT Short response (48-bit) expected
ARM_MCI_RESPONSE_SHORT_BUSY Short response with busy signal (48-bit) expected
ARM_MCI_RESPONSE_LONG Long response (136-bit) expected
ARM_MCI_RESPONSE_INDEX Check command index in response
ARM_MCI_RESPONSE_CRC Check CRC in response
ARM_MCI_WAIT_BUSY Wait until busy before sending the command
ARM_MCI_TRANSFER_DATA Activate Data transfer
ARM_MCI_CARD_INITIALIZE Execute Memory Card initialization sequence
ARM_MCI_INTERRUPT_COMMAND Send Interrupt command (CMD40 - MMC only)
ARM_MCI_INTERRUPT_RESPONSE Send Interrupt response (CMD40 - MMC only)
ARM_MCI_BOOT_OPERATION Execute Boot operation (MMC only)
ARM_MCI_BOOT_ALTERNATIVE Execute Alternative Boot operation (MMC only)
ARM_MCI_BOOT_ACK Expect Boot Acknowledge (MMC only)
ARM_MCI_CCSD Send Command Completion Signal Disable (CCSD) for CE-ATA device
ARM_MCI_CCS Expect Command Completion Signal (CCS) for CE-ATA device
+

Calling the function ARM_MCI_SendCommand only starts the operation. The function is non-blocking and returns as soon as the driver has started the operation. It is not allowed to call this function again until the operation is in progress.

+

After the command is sent the response is retrieved if specified with ARM_MCI_RESPONSE_xxx flags. When the command completes successfully (requested response is received without errors) the ARM_MCI_EVENT_COMMAND_COMPLETE event is generated. In case that response is requested but not received the ARM_MCI_EVENT_COMMAND_TIMEOUT event is generated instead. In case of invalid response (or CRC error) the ARM_MCI_EVENT_COMMAND_ERROR event is generated instead. Progress of command operation can be monitored by calling the ARM_MCI_GetStatus and checking the command_active flag.

+

After the command operation the data transfer operation is started if specified with ARM_MCI_TRANSFER_DATA flag. The data transfer needs to be configured before that by calling the ARM_MCI_SetupTransfer. When the data transfer completes successfully the ARM_MCI_EVENT_TRANSFER_COMPLETE event is generated. In case that data transfer is not completed in-time (specified by ARM_MCI_DATA_TIMEOUT) the ARM_MCI_EVENT_TRANSFER_TIMEOUT event is generated instead. In case of CRC errors the ARM_MCI_EVENT_TRANSFER_ERROR event is generated instead. Progress of data transfer operation can be monitored by calling the ARM_MCI_GetStatus and checking the transfer_active flag.

+

See also:

+ + +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
int32_t ARM_MCI_SetupTransfer (uint8_t * data,
uint32_t block_count,
uint32_t block_size,
uint32_t mode 
)
+
+ +

Setup read or write transfer operation.

+
Parameters
+ + + + + +
[in,out]dataPointer to data block(s) to be written or read
[in]block_countNumber of blocks
[in]block_sizeSize of a block in bytes
[in]modeTransfer mode
+
+
+
Returns
Status Error Codes
+

The function ARM_MCI_SetupTransfer prepares the data transfer operation that is initiated by calling the function ARM_MCI_SendCommand with the parameter flags = ARM_MCI_TRANSFER_DATA.

+

The parameter data is a pointer to the data to transfer.
+The parameter block_count is the number of blocks to transfer.
+The parameter block_size is the size of a block.
+The parameter mode sets the transfer mode and can have the values liste in the table below:

+ + + + + + + + + + + +
Transfer Directions Description
ARM_MCI_TRANSFER_READ Read data from MCI
ARM_MCI_TRANSFER_WRITE Write data to MCI
ARM_MCI_TRANSFER_BLOCK (default) Block Data transfer
ARM_MCI_TRANSFER_STREAM Stream Data transfer (MMC only)
+ +
+
+ +
+
+ + + + + + + + +
int32_t ARM_MCI_AbortTransfer (void )
+
+ +

Abort current read/write data transfer.

+
Returns
Status Error Codes
+

The function ARM_MCI_AbortTransfer aborts the active data transfer operation initiated with ARM_MCI_SendCommand.

+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
int32_t ARM_MCI_Control (uint32_t control,
uint32_t arg 
)
+
+ +

Control MCI Interface.

+
Parameters
+ + + +
[in]controlOperation
[in]argArgument of operation (optional)
+
+
+
Returns
Status Error Codes
+

Th function ARM_MCI_Control controls the MCI interface and executes various operations.

+

The parameter control specifies the operation. Values for control cannot be ORed, but must be called separately in the code.
+The parameter arg provides, depending on the operation, additional information or sets values.

+
Note
For parameters, the values marked with (default) are the setting after the driver initialization.
+

The table lists values for the parameter control.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter control Operation
ARM_MCI_BUS_SPEED Set the Bus Speed. The parameter arg specifies the speed in bits/s; The function returns the bus speed configured in bits/s.
ARM_MCI_BUS_SPEED_MODE Set the Bus Speed Mode. Predefined values for arg are listed in the table Bus Speed Mode.
ARM_MCI_BUS_CMD_MODE Set the CMD Line Mode. Predefined values for arg are listed in the table Bus CMD Line Mode.
ARM_MCI_BUS_DATA_WIDTH Set data bus width. Predefined values for arg are encoded in Bus Data Width.
ARM_MCI_DRIVER_STRENGTH Set driver strength. Predefined values for arg are listed in the table Driver Type
ARM_MCI_CONTROL_RESET Control optional RST_n Pin (eMMC). The parameter arg can have the values [0:inactive(default); 1:active]
ARM_MCI_CONTROL_CLOCK_IDLE Control clock generation on CLK Pin when idle. The parameter arg can have the values [0:disabled; 1:enabled]
ARM_MCI_UHS_TUNING_OPERATION Sampling clock Tuning operation (SD UHS-I). The parameter arg can have the values [0:reset; 1:execute]
ARM_MCI_UHS_TUNING_RESULT Sampling clock Tuning result (SD UHS-I). Returns [0:done; 1:in progress; -1:error]
ARM_MCI_DATA_TIMEOUT Set Data timeout; The parameter arg sets the timeout in bus cycles.
ARM_MCI_CSS_TIMEOUT Set Command Completion Signal (CCS) timeout. The parameter arg sets timeout in bus cycles.
ARM_MCI_MONITOR_SDIO_INTERRUPT Monitor SD I/O interrupt. The parameter arg can have the values [0:disabled(default); 1:enabled]. Monitoring is automatically disabled when an interrupt is recognized.
ARM_MCI_CONTROL_READ_WAIT Control Read/Wait states for SD I/O. The parameter arg can have the values [0:disabled(default); 1:enabled].
ARM_MCI_SUSPEND_TRANSFER Suspend Data transfer (SD I/O). Returns the number of remaining bytes to transfer.
ARM_MCI_RESUME_TRANSFER Resume Data transfer (SD I/O).
+

Bus Speed Mode

+

The function ARM_MCI_GetCapabilities lists the supported bus speed modes. Initially, all SD cards use a 3.3 volt electrical interface. Some SD cards can switch to 1.8 volt operation. For example, the use of ultra-high-speed (UHS) SD cards requires 1.8 volt operation and a 4-bit bus data width. The bit field ARM_MCI_CAPABILITIES.uhs_signaling encodes whether the driver supports 1.8 volt UHS signaling.

+

The control operation ARM_MCI_BUS_SPEED_MODE sets the bus speed mode using the parameter arg.

+ + + + + + + + + + + + + + + + + +
Parameter arg Bus Speed Mode
ARM_MCI_BUS_DEFAULT_SPEED (default) Set the bus speed for SD/MMC cards: Default Speed mode up to [25;26]MHz
ARM_MCI_BUS_HIGH_SPEED Set the bus speed for SD/MMC: High Speed mode up to [50;52]MHz
ARM_MCI_BUS_UHS_SDR12 Set the bus speed for SD: SDR12 (Single Data Rate) up to 25MHz, 12.5MB/s: UHS-I (Ultra High Speed) 1.8V signalling
ARM_MCI_BUS_UHS_SDR25 Set the bus speed for SD: SDR25 (Single Data Rate) up to 50MHz, 25 MB/s: UHS-I (Ultra High Speed) 1.8V signalling
ARM_MCI_BUS_UHS_SDR50 Set the bus speed for SD: SDR50 (Single Data Rate) up to 100MHz, 50 MB/s: UHS-I (Ultra High Speed) 1.8V signalling
ARM_MCI_BUS_UHS_SDR104 Set the bus speed for SD: SDR104 (Single Data Rate) up to 208MHz, 104 MB/s: UHS-I (Ultra High Speed) 1.8V signalling
ARM_MCI_BUS_UHS_DDR50 Set the bus speed for SD: DDR50 (Dual Data Rate) up to 50MHz, 50 MB/s: UHS-I (Ultra High Speed) 1.8V signalling
+

Bus CMD Line Mode

+

The control operation ARM_MCI_BUS_CMD_MODE sets the bus command line mode using the parameter arg.

+ + + + + + + +
Parameter arg Bus CMD Line Mode
ARM_MCI_BUS_CMD_PUSH_PULL (default) Set the Push-Pull CMD line
ARM_MCI_BUS_CMD_OPEN_DRAIN Set the Open Drain CMD line (MMC only)
+

Bus Data Width

+

Specifies the bus data width (the number of data I/O pins on the SD/MMC interface).

+

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 ARM_MCI_CAPABILITIES.data_width_8 encode whether the driver supports a specific bus data with.

+

The control operation ARM_MCI_BUS_DATA_WIDTH sets the bus data width using the parameter arg.

+ + + + + + + + + + + + + +
Parameter arg Bus Data Width
ARM_MCI_BUS_DATA_WIDTH_1 (default) Set the Bus data width to 1 bit
ARM_MCI_BUS_DATA_WIDTH_4 Set the Bus data width to 4 bits
ARM_MCI_BUS_DATA_WIDTH_8 Set the Bus data width to 8 bits
ARM_MCI_BUS_DATA_WIDTH_4_DDR Set the Bus data width to 4 bits, DDR (Dual Data Rate) - MMC only
ARM_MCI_BUS_DATA_WIDTH_8_DDR Set the Bus data width to 8 bits, DDR (Dual Data Rate) - MMC only
+

Driver Type

+

Specifies the interface driver type.

+

The control operation ARM_MCI_DRIVER_STRENGTH sets the interface driver type using the parameter arg.

+ + + + + + + + + + + +
Parameter arg Driver Type
ARM_MCI_DRIVER_TYPE_A Set the interface to SD UHS-I Driver Type A
ARM_MCI_DRIVER_TYPE_B (default) Set the interface to SD UHS-I Driver Type B
ARM_MCI_DRIVER_TYPE_C Set the interface to SD UHS-I Driver Type C
ARM_MCI_DRIVER_TYPE_D Set the interface to SD UHS-I Driver Type D
+

Examples:

+
// Set Bus Speed to 25MHz
+
MCIdrv->Control(ARM_MCI_BUS_SPEED, 25000000);
+
+
// Set High Speed mode
+
MCIdrv->Control(ARM_MCI_BUS_SPEED_MODE, ARM_MCI_BUS_HIGH_SPEED);
+
+
// Configure CMD line as Open Drain (MMC only)
+
MCIdrv->Control(ARM_MCI_BUS_CMD_MODE, ARM_MCI_BUS_CMD_OPEN_DRAIN);
+
+
// Set Bus Data Width = 4bits
+
MCIdrv->Control(ARM_MCI_BUS_DATA_WIDTH, ARM_MCI_BUS_DATA_WIDTH_4);
+
+
// Set SD UHS-I Driver Type B
+
MCIdrv->Control(ARM_MCI_DRIVER_STRENGTH, ARM_MCI_DRIVER_TYPE_B);
+
+
// RTS_n Pin is not active by default
+
// Assert RTS_n Pin (eMMC)
+
MCIdrv->Control(ARM_MCI_CONTROL_RESET, 1);
+
// De-assert RTS_n Pin (eMMC)
+
MCIdrv->Control(ARM_MCI_CONTROL_RESET, 0);
+
+
// Clock generation on CLK when Idle: hardware specific default behavior
+
// Enable Clock generation on CLK when Idle
+
MCIdrv->Control(ARM_MCI_CONTROL_CLOCK_IDLE, 1);
+
// Disable Clock generation on CLK when Idle
+
MCIdrv->Control(ARM_MCI_CONTROL_CLOCK_IDLE, 0);
+
+
// UHS Tuning
+
MCIdrv->Control(ARM_MCI_UHS_TUNING_OPERATION, 1); // start tuning
+
do {
+
status = MCIdrv->Control(ARM_MCI_UHS_TUNING_RESULT, 0/*argument not used*/);
+
if (status == -1) { break; /* tuning failed */ }
+
} while (status == 1);
+
+
// Set Data Timeout to 12500000 bus cycles (0.5s @25MHz Bus Speed)
+
// Default value is hardware specific (typically 2^32-1)
+
MCIdrv->Control(ARM_MCI_DATA_TIMEOUT, 12500000);
+
+
// Set CSS Timeout to 1000000 bus cycles
+
// Default value is hardware specific
+
MCIdrv->Control(ARM_MCI_CSS_TIMEOUT, 1000000);
+
+
// SD I/O Interrupt Monitoring is disabled by default
+
// Enable SD I/O Interrupt Monitoring
+
MCIdrv->Control(ARM_MCI_MONITOR_SDIO_INTERRUPT, 1);
+
// Disable SD I/O Interrupt Monitoring
+
MCIdrv->Control(ARM_MCI_MONITOR_SDIO_INTERRUPT, 0);
+
+
// Read/Wait for SD I/O is disabled by default
+
// Enable Read/Wait for SD I/O
+
MCIdrv->Control(ARM_MCI_CONTROL_READ_WAIT, 1);
+
// Disable Read/Wait for SD I/O
+
MCIdrv->Control(ARM_MCI_CONTROL_READ_WAIT, 0);
+
+
// Suspend Data transfer (SD I/O)
+
MCIdrv->Control(ARM_MCI_SUSPEND_TRANSFER, 0/*argument not used*/);
+
+
// Resume Data transfer (SD I/O)
+
MCIdrv->Control(ARM_MCI_RESUME_TRANSFER, 0/*argument not used*/);
+
+
+
+ +
+
+ + + + + + + + +
ARM_MCI_STATUS ARM_MCI_GetStatus (void )
+
+ +

Get MCI status.

+
Returns
MCI status ARM_MCI_STATUS
+

The function ARM_MCI_GetStatus returns the current MCI interface status.

+ +
+
+ +
+
+ + + + + + + + +
void ARM_MCI_SignalEvent (uint32_t event)
+
+ +

Callback function that signals a MCI Card Event.

+
Parameters
+ + +
[in]eventMCI Events
+
+
+
Returns
none
+

The function ARM_MCI_SignalEvent is a callback function registered by the function ARM_MCI_Initialize.

+

The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

+

Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_NAND_CAPABILITIES, which can be retrieved with the function ARM_NAND_GetCapabilities.

+

The following events can be generated:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter event Bit Description supported when ARM_NAND_CAPABILITIES
ARM_MCI_EVENT_CARD_INSERTED 0 Occurs after Memory Card inserted always supported
ARM_MCI_EVENT_CARD_REMOVED 1 Occurs after Memory Card removal always supported
ARM_MCI_EVENT_COMMAND_COMPLETE 2 Occurs after command completed successfully always supported
ARM_MCI_EVENT_COMMAND_TIMEOUT 3 Occurs after command timeout always supported
ARM_MCI_EVENT_COMMAND_ERROR 4 Occurs after command response error (CRC error or invalid response) always supported
ARM_MCI_EVENT_TRANSFER_COMPLETE 5 Occurs after data transfer completed successfully always supported
ARM_MCI_EVENT_TRANSFER_TIMEOUT 6 Occurs after data transfer timeout always supported
ARM_MCI_EVENT_TRANSFER_ERROR 7 Occurs after data transfer error (CRC failed) always supported
ARM_MCI_EVENT_SDIO_INTERRUPT 8 Indicates SD I/O Interrupt data field sdio_interrupt = 1
ARM_MCI_EVENT_CCS 9 Indicates a Command Completion Signal (CCS) data field ccs = 1
ARM_MCI_EVENT_CCS_TIMEOUT 10 Indicates a Command Completion Signal (CCS) Timeout data field css_timeout = 1
+

See also:

+ + +
+
+
+
+ + + + -- cgit