![]() |
CMSIS-Driver
Version 2.00
Peripheral Interface for Middleware and Application Code
|
Driver API for Memory Card Interface using SD/MMC interface or SPI (Driver_MCI.h) More...
Content | |
MCI Events | |
MCI Card Event for the ARM_MCI_SignalEvent callback function. | |
MCI Control Codes | |
Set MCI driver parameters with control codes. | |
MCI Send Command Flags | |
Set the response type expected from a card. | |
MCI Transfer Controls | |
Data transfer direction codes (read from/write to MCI) | |
MCI Card Power Controls | |
Set Memory Card power supply type. | |
Data Structures | |
struct | ARM_DRIVER_MCI |
Access structure of the MCI Driver. More... | |
struct | ARM_MCI_CAPABILITIES |
MCI Driver Capabilities. More... | |
struct | ARM_MCI_SWITCH |
MCI Card Switch. 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. | |
Functions | |
ARM_DRIVER_VERSION | ARM_MCI_GetVersion (void) |
Get driver version. | |
ARM_MCI_CAPABILITIES | ARM_MCI_GetCapabilities (void) |
Get driver capabilities. | |
int32_t | ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
Initialize the Memory Card Interface. | |
int32_t | ARM_MCI_Uninitialize (void) |
De-initialize Memory Card Interface. | |
int32_t | ARM_MCI_PowerControl (ARM_POWER_STATE state) |
Control Memory Card Interface Power. | |
int32_t | ARM_MCI_CardPower (uint32_t voltage) |
Set Memory Card supply voltage. | |
ARM_MCI_SWITCH | ARM_MCI_CardSwitchRead (void) |
Read state of Memory Card switches. | |
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. | |
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. | |
int32_t | ARM_MCI_AbortTransfer (void) |
Abort current read/write data transfer. | |
int32_t | ARM_MCI_Control (uint32_t control, uint32_t arg) |
Control MCI Interface. | |
ARM_MCI_STATUS | ARM_MCI_GetStatus (void) |
Get MCI status. | |
void | ARM_MCI_SignalEvent (uint32_t event) |
Callback function that signals a MCI Card Event. | |
Driver API for Memory Card Interface using SD/MMC interface or SPI (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 devices that are directly soldered to the PCB (eMMC).
References:
The MCI driver allows to exchange data of the SD/MMC memory via SD/MMC interface or SPI Bus mode. The following modes are supported by SD/MMC memory cards:
The following header files define the Application Programming Interface (API) for the MCI interface:
The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.
The driver functions are published in the access struct as explained in Driver Functions
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 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:
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. | |
ARM_MCI_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_MCI_GetCapabilities : Get driver capabilities. | |
int32_t(* | Initialize )(ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
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. | |
ARM_MCI_SWITCH(* | CardSwitchRead )(void) |
Pointer to ARM_MCI_CardSwitchRead : Read state of Card switches. | |
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. | |
int32_t(* AbortTransfer)(void) |
Pointer to ARM_MCI_AbortTransfer : Abort current data transfer.
int32_t(* CardPower)(uint32_t voltage) |
Pointer to ARM_MCI_CardPower : Set card power supply voltage.
ARM_MCI_SWITCH(* CardSwitchRead)(void) |
Pointer to ARM_MCI_CardSwitchRead : Read state of Card switches.
int32_t(* Control)(uint32_t control, uint32_t arg) |
Pointer to ARM_MCI_Control : Control MCI Interface.
ARM_MCI_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_MCI_GetCapabilities : Get driver capabilities.
ARM_MCI_STATUS(* GetStatus)(void) |
Pointer to ARM_MCI_GetStatus : Get MCI status.
ARM_DRIVER_VERSION(* GetVersion)(void) |
Pointer to ARM_MCI_GetVersion : Get driver version.
int32_t(* Initialize)(ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
Pointer to ARM_MCI_Initialize : Initialize MCI Interface.
int32_t(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_MCI_PowerControl : Control MCI Interface Power.
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(* Uninitialize)(void) |
Pointer to ARM_MCI_Uninitialize : De-initialize MCI Interface.
struct ARM_MCI_CAPABILITIES |
MCI Driver Capabilities.
An MCI driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.
Returned by:
struct ARM_MCI_SWITCH |
struct ARM_MCI_STATUS |
MCI Status.
MCI status flags.
Read status information with the function ARM_MCI_GetStatus.
Returned by:
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:
int23_t ARM_MCI_AbortTransfer | ( | void | ) |
Abort current read/write data transfer.
Abort a data transfer operation initiated with ARM_MCI_SetupTransfer or ARM_MCI_SendCommand.
int32_t ARM_MCI_CardPower | ( | uint32_t | voltage | ) |
Set Memory Card supply voltage.
[in] | voltage | Memory Card supply voltage |
Switch the SD memory power supply voltage. The following predefined codes can be used for the argument voltage.
Voltage Control | Description |
---|---|
ARM_MCI_POWER_VDD_OFF | Set the card power to VDD (VCC) turned off |
ARM_MCI_POWER_VDD_3V3 | Set the card power to VDD (VCC) = 3.3V |
ARM_MCI_POWER_VDD_1V8 | Set the card power to VDD (VCC) = 1.8V |
ARM_MCI_POWER_VCCQ_OFF | Set the card power to eMMC VCCQ turned off |
ARM_MCI_POWER_VCCQ_3V3 | Set the card power to eMMC VCCQ = 3.3V |
ARM_MCI_POWER_VCCQ_1V8 | Set the card power to eMMC VCCQ = 1.8V |
ARM_MCI_POWER_VCCQ_1V2 | Set the card power to eMMC VCCQ = 1.2V |
ARM_MCI_SWITCH ARM_MCI_CardSwitchRead | ( | void | ) |
Read state of Memory Card switches.
Read the status of optional card switches.
int32_t ARM_MCI_Control | ( | uint32_t | control, |
uint32_t | arg | ||
) |
Control MCI Interface.
[in] | control | operation |
[in] | arg | argument of operation (optional) |
Control the MCI interface settings and execute various operations.
The parameter control specifies various parameters with the ARM_MCI_xxx values (see tables below). Depending on the control value, the parameter arg provides additional information or sets values.
ARM_MCI_xxx control bits specify the control mode of the MCI interface.
Control Mode | Description |
---|---|
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. The parameter arg specifies the speed. Predefined Bus Speed Modes are encoded in MCI Bus Speed Mode Values. |
ARM_MCI_BUS_CMD_MODE | Set the CMD Line Mode. The parameter arg specifies the CMD Line Mode. Predefined values are encoded in MCI Command Line Values. |
ARM_MCI_BUS_DATA_WIDTH | Set data bus width. The parameter arg specifies the width. Predefined values are encoded in MCI Bus Data Width Values. |
ARM_MCI_DRIVER_STRENGTH | Set driver type. The parameter arg specifies the type. Predefined values are encoded in MCI Driver Type Values |
ARM_MCI_CONTROL_CLOCK | Enable or disable the MCI interface clock on CLK pin. The parameter arg = [0:disabled; 1:enabled] |
ARM_MCI_CONTROL_CLOCK_IDLE | Control clock generation on CLK Pin when idle; The parameter arg = [0:disabled; 1:enabled] |
ARM_MCI_UHS_TUNING_OPERATION | Sampling clock Tuning operation (SD UHS-I). The parameter arg = [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 = timeout in bus cycles. |
ARM_MCI_CSS_TIMEOUT | Set Command Completion Signal (CCS) timeout. The parameter arg = timeout in bus cycles. |
ARM_MCI_MONITOR_SDIO_INTERRUPT | Monitor SD I/O interrupt. The parameter arg = [0:disabled; 1:enabled]. |
ARM_MCI_CONTROL_READ_WAIT | Control Read/Wait states for SD I/O. The parameter arg = [0:disabled; 1:enabled]. |
ARM_MCI_SUSPEND_TRANSFER | Suspend Data transfer (SD I/O). Returns number of remaining bytes to transfer. |
ARM_MCI_RESUME_TRANSFER | Resume Data transfer (SD I/O). |
For control = ARM_MCI_BUS_SPEED_MODE the parameter arg specifies the bus speed mode using the following ARM_MCI_BUS_xxx values.
Bus Speed Mode | Description |
---|---|
ARM_MCI_BUS_DEFAULT_SPEED | Set the bus speed for SD/MMC cards. Default Speed mode up to [25;26]MHz (default) |
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 |
For control = ARM_MCI_BUS_CMD_MODE the parameter arg specifies the CMD Line Mode using the following ARM_MCI_BUS_CMD_xxx values.
CMD Line Mode | Description |
---|---|
ARM_MCI_BUS_CMD_PUSH_PULL | Set the Push-Pull CMD line (default). |
ARM_MCI_BUS_CMD_OPEN_DRAIN | Set the Open Drain CMD line (MMC only). |
For control = ARM_MCI_BUS_DATA_WIDTH the parameter arg specifies the Bus Data Width using the following ARM_MCI_BUS_DATA_WIDTH_xxx values.
Bus Data Width | Description |
---|---|
ARM_MCI_BUS_DATA_WIDTH_1 | Set the Bus data width to 1 bit (default) |
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 |
For control = ARM_MCI_DRIVER_STRENGTH the parameter arg specifies the Driver Type using the following ARM_MCI_DRIVER_TYPE_x values.
Driver Type | Description |
---|---|
ARM_MCI_DRIVER_TYPE_A | Set the interface to SD UHS-I Driver Type A |
ARM_MCI_DRIVER_TYPE_B | Set the interface to SD UHS-I Driver Type B (default) |
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 |
ARM_MCI_CAPABILITIES ARM_MCI_GetCapabilities | ( | void | ) |
Get driver capabilities.
Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_MCI_CAPABILITIES encode various capabilities, for example if a hardware is write protected or is able to create signal events using the ARM_MCI_SignalEvent callback function.
Example:
ARM_MCI_STATUS ARM_MCI_GetStatus | ( | void | ) |
Get MCI status.
ARM_DRIVER_VERSION ARM_MCI_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t ARM_MCI_Initialize | ( | ARM_MCI_SignalEvent_t | cb_event, |
bool | spi_mode | ||
) |
Initialize the Memory Card Interface.
[in] | cb_event | Pointer to ARM_MCI_SignalEvent |
[in] | spi_mode | SPI Mode (default is native SD/MMC Mode) |
The function initializes the MCI interface. It is called when the middleware component starts operation.
The function performs the following operations:
The parameter cb_event is a pointer to the ARM_MCI_SignalEvent callback function; use a NULL pointer when no callback signals are required.
The parameter spi_mode is a boolean value indicating whether the device is running in SPI mode or not.
Example:
int32_t ARM_MCI_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control Memory Card Interface Power.
[in] | state | Power state ARM_POWER_STATE |
Controls the power modes of the MCI interface.
state can be:
If state specifies an unsupported mode, the function returns ARM_DRIVER_ERROR_UNSUPPORTED.
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.
[in] | cmd | Memory Card command |
[in] | arg | Command argument |
[in] | flags | Command flags |
[out] | response | Pointer to response |
Send commands to the SD/MMC card and return the command response. The following codes can be used for the argument flags to set the response type expected from the card.
Send Command Flag | Description |
---|---|
ARM_MCI_RESPONSE_NONE | No response expected (default) |
ARM_MCI_RESPONSE_SHORT | Short response (48-bit) |
ARM_MCI_RESPONSE_SHORT_BUSY | Short response with busy signal (48-bit) |
ARM_MCI_RESPONSE_LONG | Long response (136-bit) |
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 |
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.
[in,out] | data | Pointer to data block(s) to be written or read |
[in] | block_count | Number of blocks |
[in] | block_size | Size of a block in bytes |
[in] | mode | Transfer mode |
Setup a data transfer operation. The argument mode can have the following codes to steer the transfer direction.
Transfer Directions | Description |
---|---|
ARM_MCI_TRANSFER_READ | Read data from MCI |
ARM_MCI_TRANSFER_WRITE | Write data to MCI |
ARM_MCI_TRANSFER_BLOCK | Block Data transfer (default) |
ARM_MCI_TRANSFER_STREAM | Stream Data transfer (MMC only) |
void ARM_MCI_SignalEvent | ( | uint32_t | event | ) |
Callback function that signals a MCI Card Event.
[in] | event | MCI Events |
The optional call back function ARM_MCI_SignalEvent notifies the application about MCI Events and is registered by the function ARM_MCI_Initialize. The function ARM_MCI_GetCapabilities returns information about the implemented events in a driver.
The argument event represents the notification mask of the events. One or more events may be notified with the same callback, because each event is coded in a separate bit. The following call back notifications are generated:
Bit | Event | Description |
---|---|---|
0 | ARM_MCI_EVENT_CARD_INSERTED | Occurs after Memory Card inserted |
1 | ARM_MCI_EVENT_CARD_REMOVED | Occurs after Memory Card removal |
2 | ARM_MCI_EVENT_COMMAND_COMPLETE | Indicates that the Command completed |
3 | ARM_MCI_EVENT_COMMAND_TIMEOUT | Indicates a Command timeout |
4 | ARM_MCI_EVENT_COMMAND_ERROR | Occurs after a command response error (CRC error or invalid response) |
5 | ARM_MCI_EVENT_TRANSFER_COMPLETE | Indicates that a data transfer completed |
6 | ARM_MCI_EVENT_TRANSFER_TIMEOUT | Indicates a data transfer timeout |
7 | ARM_MCI_EVENT_TRANSFER_ERROR | Occurs after a data transfer CRC failed |
8 | ARM_MCI_EVENT_SDIO_INTERRUPT | Occurs after an SD I/O Interrupt |
9 | ARM_MCI_EVENT_BOOT_ACK_TIMEOUT | Indicates a Boot Acknowledge timeout (MMC only) |
10 | ARM_MCI_EVENT_CCS | Indicates a Command Completion Signal (CCS) |
11 | ARM_MCI_EVENT_CCS_TIMEOUT | Indicates a Command Completion Signal (CCS) Timeout |
int32_t ARM_MCI_Uninitialize | ( | void | ) |
De-initialize Memory Card Interface.
The function ARM_MCI_Uninitialize de-initializes the resources of I2C interface and sets the peripheral to ARM_POWER_OFF power mode.
It is called when the middleware component stops operation and releases the software resources used by the interface.