![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
Driver API for Memory Card Interface using SDIO or SPI (Driver_MCI.h) More...
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... | |
Typedefs | |
typedef void(* | ARM_MCI_SignalEvent_t )(ARM_MCI_EVENT event) |
Pointer to ARM_MCI_SignalEvent : Signal MCI Card Event. | |
Functions | |
ARM_DRV_VERSION | ARM_MCI_GetVersion (void) |
Get driver version. | |
ARM_MCI_CAPABILITIES | ARM_MCI_GetCapabilities (void) |
Get driver capabilities. | |
ARM_MCI_STATUS | ARM_MCI_Initialize (ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
Initialize the Memory Card Interface. | |
ARM_MCI_STATUS | ARM_MCI_Uninitialize (void) |
De-initialize Memory Card Interface. | |
ARM_MCI_STATUS | ARM_MCI_PowerControl (ARM_POWER_STATE state) |
Control Memory Card Interface Power. | |
ARM_MCI_STATUS | ARM_MCI_BusMode (ARM_MCI_BUS_MODE mode) |
Setup the bus mode for Memory Card transfers. | |
ARM_MCI_STATUS | ARM_MCI_BusDataWidth (ARM_MCI_BUS_DATA_WIDTH width) |
Setup bus data width for Memory Card transfers. | |
ARM_MCI_STATUS | ARM_MCI_BusSignaling (ARM_MCI_BUS_SIGNALING voltage) |
Set bus signaling voltage for MCI transfers. | |
uint32_t | ARM_MCI_BusSpeed (uint32_t bps) |
Setup bus speed for Memory Card transfers. | |
ARM_MCI_STATUS | ARM_MCI_CardPower (ARM_MCI_POWER voltage) |
Set Memory Card supply voltage. | |
ARM_MCI_SWITCH | ARM_MCI_CardSwitchRead (void) |
Read state of Memory Card switches. | |
ARM_MCI_STATUS | ARM_MCI_CardInitialize (void) |
Perform Memory Card initialization sequence. | |
ARM_MCI_STATUS | ARM_MCI_SendCommand (ARM_MC_COMMAND cmd, uint32_t cmd_arg, ARM_MC_RESPONSE response_type, uint32_t *ptr_response) |
Send Command to card and get the response. | |
ARM_MCI_STATUS | ARM_MCI_SetupTransfer (uint8_t *data, uint32_t block_count, uint32_t block_size, ARM_MCI_TRANSFER_MODE mode) |
Setup read or write transfer operation. | |
ARM_MCI_STATUS | ARM_MCI_ReadTransfer (uint8_t *data, uint32_t block_count, uint32_t block_size) |
Perform read transfer. | |
ARM_MCI_STATUS | ARM_MCI_WriteTransfer (uint8_t *data, uint32_t block_count, uint32_t block_size) |
Perform write transfer. | |
ARM_MCI_STATUS | ARM_MCI_AbortTransfer (void) |
Abort current read/write data transfer. | |
void | ARM_MCI_SignalEvent (ARM_MCI_EVENT event) |
Callback function that signals a MCI Card Event. | |
Driver API for Memory Card Interface using SDIO or SPI (Driver_MCI.h)
The Memory Card Interface (MCI) implements the hardware abstraction layer for Secure Digital (SD) memory that is typically used as file storage. For embedded systems, SD devices are available as memory cards in several forms (SD, miniSD, microSD) or as non-removable devices that are directly soldered to the PCB.
References:
The MCI driver allows to exchange data of the SD memory via SDIO or SPI Bus mode. The following modes are supported by SD 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
A typical setup sequence for the driver is shown below:
Example Code:
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 ARM_DRIVER_MCIn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRV_VERSION(* | GetVersion )(void) |
Pointer to ARM_MCI_GetVersion : Get driver version. | |
ARM_MCI_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_MCI_GetCapabilities : Get driver capabilities. | |
ARM_MCI_STATUS(* | Initialize )(ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
Pointer to ARM_MCI_Initialize : Initialize MCI Interface. | |
ARM_MCI_STATUS(* | Uninitialize )(void) |
Pointer to ARM_MCI_Uninitialize : De-initialize MCI Interface. | |
ARM_MCI_STATUS(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_MCI_PowerControl : Control MCI Interface Power. | |
ARM_MCI_STATUS(* | BusMode )(ARM_MCI_BUS_MODE mode) |
Pointer to ARM_MCI_BusMode : Set bus mode for MCI transfers. | |
ARM_MCI_STATUS(* | BusDataWidth )(ARM_MCI_BUS_DATA_WIDTH width) |
Pointer to ARM_MCI_BusDataWidth : Set bus data width for MCI transfers. | |
ARM_MCI_STATUS(* | BusSignaling )(ARM_MCI_BUS_SIGNALING voltage) |
Pointer to ARM_MCI_BusSignaling : Set bus signaling voltage for MCI transfers. | |
uint32_t(* | BusSpeed )(uint32_t bps) |
Pointer to ARM_MCI_BusSpeed : Set bus speed for MCI transfers. | |
ARM_MCI_STATUS(* | CardPower )(ARM_MCI_POWER 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. | |
ARM_MCI_STATUS(* | CardInitialize )(void) |
Pointer to ARM_MCI_CardInitialize : Perform Card initialization sequence. | |
ARM_MCI_STATUS(* | SendCommand )(ARM_MC_COMMAND cmd, uint32_t cmd_arg, ARM_MC_RESPONSE response_type, uint32_t *ptr_response) |
Pointer to ARM_MCI_SendCommand : Send Command to card and get the response. | |
ARM_MCI_STATUS(* | SetupTransfer )(uint8_t *data, uint32_t block_count, uint32_t block_size, ARM_MCI_TRANSFER_MODE mode) |
Pointer to ARM_MCI_SetupTransfer : Setup transfer operation. | |
ARM_MCI_STATUS(* | ReadTransfer )(uint8_t *data, uint32_t block_count, uint32_t block_size) |
Pointer to ARM_MCI_ReadTransfer : Perform read transfer. | |
ARM_MCI_STATUS(* | WriteTransfer )(uint8_t *data, uint32_t block_count, uint32_t block_size) |
Pointer to ARM_MCI_WriteTransfer : Perform write transfer. | |
ARM_MCI_STATUS(* | AbortTransfer )(void) |
Pointer to ARM_MCI_AbortTransfer : Abort current read/write transfer. | |
ARM_MCI_STATUS(* AbortTransfer)(void) |
Pointer to ARM_MCI_AbortTransfer : Abort current read/write transfer.
ARM_MCI_STATUS(* BusDataWidth)(ARM_MCI_BUS_DATA_WIDTH width) |
Pointer to ARM_MCI_BusDataWidth : Set bus data width for MCI transfers.
ARM_MCI_STATUS(* BusMode)(ARM_MCI_BUS_MODE mode) |
Pointer to ARM_MCI_BusMode : Set bus mode for MCI transfers.
ARM_MCI_STATUS(* BusSignaling)(ARM_MCI_BUS_SIGNALING voltage) |
Pointer to ARM_MCI_BusSignaling : Set bus signaling voltage for MCI transfers.
uint32_t(* BusSpeed)(uint32_t bps) |
Pointer to ARM_MCI_BusSpeed : Set bus speed for MCI transfers.
ARM_MCI_STATUS(* CardInitialize)(void) |
Pointer to ARM_MCI_CardInitialize : Perform Card initialization sequence.
ARM_MCI_STATUS(* CardPower)(ARM_MCI_POWER 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.
ARM_MCI_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_MCI_GetCapabilities : Get driver capabilities.
ARM_DRV_VERSION(* GetVersion)(void) |
Pointer to ARM_MCI_GetVersion : Get driver version.
ARM_MCI_STATUS(* Initialize)(ARM_MCI_SignalEvent_t cb_event, bool spi_mode) |
Pointer to ARM_MCI_Initialize : Initialize MCI Interface.
ARM_MCI_STATUS(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_MCI_PowerControl : Control MCI Interface Power.
ARM_MCI_STATUS(* ReadTransfer)(uint8_t *data, uint32_t block_count, uint32_t block_size) |
Pointer to ARM_MCI_ReadTransfer : Perform read transfer.
ARM_MCI_STATUS(* SendCommand)(ARM_MC_COMMAND cmd, uint32_t cmd_arg, ARM_MC_RESPONSE response_type, uint32_t *ptr_response) |
Pointer to ARM_MCI_SendCommand : Send Command to card and get the response.
ARM_MCI_STATUS(* SetupTransfer)(uint8_t *data, uint32_t block_count, uint32_t block_size, ARM_MCI_TRANSFER_MODE mode) |
Pointer to ARM_MCI_SetupTransfer : Setup transfer operation.
ARM_MCI_STATUS(* Uninitialize)(void) |
Pointer to ARM_MCI_Uninitialize : De-initialize MCI Interface.
ARM_MCI_STATUS(* WriteTransfer)(uint8_t *data, uint32_t block_count, uint32_t block_size) |
Pointer to ARM_MCI_WriteTransfer : Perform write transfer.
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 |
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:
enum ARM_MC_COMMAND |
Memory Card Command Set.
Defines the command set for a memory card.
Parameter for:
enum ARM_MC_RESPONSE |
Memory Card Response Types.
Defines the response type for a memory card.
Parameter for:
MCI Bus Data Width.
MCI Bus Data Width specifies the number of data I/O pins on the SDIO interface. For high-speed memory cards, a 4-bit bus data width should be used. The bitfields ARM_MCI_CAPABILITIES.data_width_4 and ARM_MCI_CAPABILITIES.data_width_8 encode whether the driver supports a specific bus data with.
Parameter for:
enum ARM_MCI_BUS_MODE |
MCI Bus Mode.
The MCI Bus Mode specifies open drain (which allows ganging multiple cards on the same interface) or push-pull (which achieves in practice higher speeds and a more reliable communication) bus operation. Parameter for:
MCI Bus Signaling.
Lists the supported bus signaling voltage. Initially, all SD card families 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 bitfield ARM_MCI_CAPABILITIES.signaling_1v8 encodes whether the driver supports 1.8 volt signaling.
Parameter for:
enum ARM_MCI_EVENT |
MCI Card Event.
Specifies the MCI Card Event for the ARM_MCI_SignalEvent callback function (which is registered by the function ARM_MCI_Initialize). The function ARM_MCI_GetCapabilities returns information about the implemented callback events in a driver.
Parameter for:
enum ARM_MCI_POWER |
MCI Card Power.
Lists the supported power supply for a memory card.
Parameter for:
enum ARM_MCI_STATUS |
MCI Status of executed operation.
Defines status and error codes returned by most of the MCI driver functions.
Returned by:
MCI Transfer Mode.
Lists the supported data transfer directions (read from MCI; write to MCI).
Parameter for:
ARM_MCI_STATUS ARM_MCI_AbortTransfer | ( | void | ) |
Abort current read/write data transfer.
Abort a data transfer operation initiated with ARM_MCI_ReadTransfer or ARM_MCI_WriteTransfer.
ARM_MCI_STATUS ARM_MCI_BusDataWidth | ( | ARM_MCI_BUS_DATA_WIDTH | width | ) |
Setup bus data width for Memory Card transfers.
[in] | width | Requested bus data width |
Set the bus data width of the MCI interface as specified by ARM_MCI_BUS_DATA_WIDTH in width. For example, the use of ultra-high-speed (UHS) SD cards requires 1.8 volt operation and 4-bit bus data width.
ARM_MCI_STATUS ARM_MCI_BusMode | ( | ARM_MCI_BUS_MODE | mode | ) |
Setup the bus mode for Memory Card transfers.
[in] | mode | Requested bus mode |
Set the bus mode of the MCI interface as specified by ARM_MCI_BUS_MODE in mode.
ARM_MCI_STATUS ARM_MCI_BusSignaling | ( | ARM_MCI_BUS_SIGNALING | voltage | ) |
Set bus signaling voltage for MCI transfers.
[in] | voltage | Requested signaling voltage |
Set the bus signal voltage of the MCI interface as specified by ARM_MCI_BUS_SIGNALING in voltage. All SD card families initially use a 3.3 volt electrical interface. On command, 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 4-bit bus data width.
uint32_t ARM_MCI_BusSpeed | ( | uint32_t | bps | ) |
Setup bus speed for Memory Card transfers.
[in] | bps | Requested speed in bits/s |
Set the data transfer speed of the MCI to the requested baud rate in bits per second.
ARM_MCI_STATUS ARM_MCI_CardInitialize | ( | void | ) |
Perform Memory Card initialization sequence.
Send card initialization sequence.
ARM_MCI_STATUS ARM_MCI_CardPower | ( | ARM_MCI_POWER | voltage | ) |
Set Memory Card supply voltage.
[in] | voltage | Memory Card supply voltage ARM_MCI_POWER |
Switch the SD memory power supply voltage.
ARM_MCI_SWITCH ARM_MCI_CardSwitchRead | ( | void | ) |
Read state of Memory Card switches.
Read the status of optional card switches.
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_DRV_VERSION ARM_MCI_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_MCI_STATUS 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 MMC/SD 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:
ARM_MCI_STATUS 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_MCI_ERROR_UNSUPPORTED.
ARM_MCI_STATUS ARM_MCI_ReadTransfer | ( | uint8_t * | data, |
uint32_t | block_count, | ||
uint32_t | block_size | ||
) |
Perform read transfer.
[out] | data | Pointer to data block(s) to be read |
[in] | block_count | Number of blocks |
[in] | block_size | Size of a block in bytes |
Read data from the SD memory.
ARM_MCI_STATUS ARM_MCI_SendCommand | ( | ARM_MC_COMMAND | cmd, |
uint32_t | cmd_arg, | ||
ARM_MC_RESPONSE | response_type, | ||
uint32_t * | ptr_response | ||
) |
Send Command to card and get the response.
[in] | cmd | Memory Card command ARM_MC_COMMAND |
[in] | cmd_arg | Command argument |
[in] | response_type | Expected response type |
[out] | ptr_response | Pointer to response |
Send commands to the SD memory and return the command response.
ARM_MCI_STATUS ARM_MCI_SetupTransfer | ( | uint8_t * | data, |
uint32_t | block_count, | ||
uint32_t | block_size, | ||
ARM_MCI_TRANSFER_MODE | 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 | Read or write transfer mode |
Setup a data transfer operation.
void ARM_MCI_SignalEvent | ( | ARM_MCI_EVENT | event | ) |
Callback function that signals a MCI Card Event.
[in] | event | ARM_MCI_EVENT |
Signal that a SD card operation has been completed or information about the card status. This optional call back function is implemented in the middleware and published to the driver by the function ARM_MCI_Initialize.
ARM_MCI_STATUS 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.
ARM_MCI_STATUS ARM_MCI_WriteTransfer | ( | uint8_t * | data, |
uint32_t | block_count, | ||
uint32_t | block_size | ||
) |
Perform write transfer.
[in] | data | Pointer to data block(s) to be written |
[in] | block_count | Number of blocks |
[in] | block_size | Size of a block in bytes |
Write data to the SD memory.