Detailed Description

Interface for accessing SD, eMMC, and SDIO devices.

Summary

The r_sdhi interface provides standard SD and eMMC media functionality. This interface also supports SDIO.

Data Structures
struct	sdmmc_response_t.status_b

struct	sdmmc_status_t

struct	sdmmc_device_t

struct	sdmmc_callback_args_t

struct	sdmmc_write_io_args_t

struct	sdmmc_read_io_ext_args_t

struct	sdmmc_write_io_ext_args_t

struct	sdmmc_cfg_t

struct	sdmmc_api_t

struct	sdmmc_instance_t

Typedefs
typedef void	sdmmc_ctrl_t

Enumerations
enum	sdmmc_card_type_t

enum	sdmmc_bus_width_t

enum	sdmmc_io_transfer_mode_t

enum	sdmmc_io_address_mode_t

enum	sdmmc_io_write_mode_t

enum	sdmmc_event_t

enum	sdmmc_card_detect_t

enum	sdmmc_write_protect_t

enum	sdmmc_r1_state_t

Data Structure Documentation

◆ sdmmc_response_t.status_b

struct sdmmc_response_t.status_b

SDIO Card Status Register.

◆ sdmmc_status_t

struct sdmmc_status_t

Current status.

Data Fields

bool

initialized

False if card was removed (only applies if MCU supports card detection and SDnCD pin is connected), true otherwise.

If ready is false, call sdmmc_api_t::mediaInit to reinitialize it

bool transfer_in_progress true = Card is busy

bool card_inserted Card detect status, true if card detect is not used.

◆ sdmmc_device_t

struct sdmmc_device_t

Information obtained from the media device.

Data Fields
sdmmc_card_type_t	card_type	SD, eMMC, or SDIO.
bool	write_protected	true = Card is write protected
uint32_t	clock_rate	Current clock rate.
uint32_t	sector_count	Sector count.
uint32_t	sector_size_bytes	Sector size.
uint32_t	erase_sector_count	Minimum erasable unit (in 512 byte sectors)

◆ sdmmc_callback_args_t

struct sdmmc_callback_args_t

Callback function parameter data

Data Fields
sdmmc_event_t	event	The event can be used to identify what caused the callback.
sdmmc_response_t	response	Response from card, only valid if SDMMC_EVENT_RESPONSE is set in event.
void const *	p_context	Placeholder for user data.

◆ sdmmc_write_io_args_t

struct sdmmc_write_io_args_t

Non-secure arguments for writeIo guard function

◆ sdmmc_read_io_ext_args_t

struct sdmmc_read_io_ext_args_t

Non-secure arguments for readIoExt guard function

◆ sdmmc_write_io_ext_args_t

struct sdmmc_write_io_ext_args_t

Non-secure arguments for writeIoExt guard function

◆ sdmmc_cfg_t

struct sdmmc_cfg_t

SD/MMC Configuration

Data Fields
uint8_t	channel
	Channel of SD/MMC host interface.

sdmmc_bus_width_t	bus_width
	Device bus width is 1, 4 or 8 bits wide.

transfer_instance_t const *	p_lower_lvl_transfer
	Transfer instance used to move data with DMA or DTC.

void(*	p_callback )(sdmmc_callback_args_t *p_args)
	Pointer to callback function.

void const *	p_context
	User defined context passed into callback function.

void const *	p_extend
	SD/MMC hardware dependent configuration.

uint32_t	block_size

sdmmc_card_detect_t	card_detect

sdmmc_write_protect_t	write_protect

IRQn_Type	access_irq
	Access IRQ number.

IRQn_Type	sdio_irq
	SDIO IRQ number.

IRQn_Type	card_irq
	Card IRQ number.

IRQn_Type	dma_req_irq
	DMA request IRQ number.

uint8_t	access_ipl
	Access interrupt priority.

uint8_t	sdio_ipl
	SDIO interrupt priority.

uint8_t	card_ipl
	Card interrupt priority.

uint8_t	dma_req_ipl
	DMA request interrupt priority.

Field Documentation

◆ block_size

uint32_t sdmmc_cfg_t::block_size

Block size in bytes. Block size must be 512 bytes for SD cards and eMMC devices. Block size can be 1-512 bytes for SDIO.

◆ card_detect

sdmmc_card_detect_t sdmmc_cfg_t::card_detect

Whether or not card detection is used.

◆ write_protect

sdmmc_write_protect_t sdmmc_cfg_t::write_protect

Select whether or not to use the write protect pin. Select Not Used if the MCU or device does not have a write protect pin.

◆ sdmmc_api_t

struct sdmmc_api_t

SD/MMC functions implemented at the HAL layer API.

Data Fields
fsp_err_t(*	open )(sdmmc_ctrl_t const p_ctrl, sdmmc_cfg_t const const p_cfg)

fsp_err_t(*	mediaInit )(sdmmc_ctrl_t const p_ctrl, sdmmc_device_t const p_device)

fsp_err_t(*	read )(sdmmc_ctrl_t const p_ctrl, uint8_t const p_dest, uint32_t const start_sector, uint32_t const sector_count)

fsp_err_t(*	write )(sdmmc_ctrl_t const p_ctrl, uint8_t const const p_source, uint32_t const start_sector, uint32_t const sector_count)

fsp_err_t(*	readIo )(sdmmc_ctrl_t const p_ctrl, uint8_t const p_data, uint32_t const function, uint32_t const address)

fsp_err_t(*	writeIo )(sdmmc_ctrl_t const p_ctrl, uint8_t const p_data, uint32_t const function, uint32_t const address, sdmmc_io_write_mode_t const read_after_write)

fsp_err_t(*	readIoExt )(sdmmc_ctrl_t const p_ctrl, uint8_t const p_dest, uint32_t const function, uint32_t const address, uint32_t *const count, sdmmc_io_transfer_mode_t transfer_mode, sdmmc_io_address_mode_t address_mode)

fsp_err_t(*	writeIoExt )(sdmmc_ctrl_t const p_ctrl, uint8_t const const p_source, uint32_t const function, uint32_t const address, uint32_t const count, sdmmc_io_transfer_mode_t transfer_mode, sdmmc_io_address_mode_t address_mode)

fsp_err_t(*	ioIntEnable )(sdmmc_ctrl_t *const p_ctrl, bool enable)

fsp_err_t(*	statusGet )(sdmmc_ctrl_t const p_ctrl, sdmmc_status_t const p_status)

fsp_err_t(*	erase )(sdmmc_ctrl_t *const p_ctrl, uint32_t const start_sector, uint32_t const sector_count)

fsp_err_t(*	callbackSet )(sdmmc_ctrl_t const p_ctrl, void(p_callback)(sdmmc_callback_args_t ), void const const p_context, sdmmc_callback_args_t *const p_callback_memory)

fsp_err_t(*	close )(sdmmc_ctrl_t *const p_ctrl)

Field Documentation

◆ open

fsp_err_t(* sdmmc_api_t::open) (sdmmc_ctrl_t *const p_ctrl, sdmmc_cfg_t const *const p_cfg)

Open the SD/MMC driver.

Parameters

[in]	p_ctrl	Pointer to SD/MMC instance control block.
[in]	p_cfg	Pointer to SD/MMC instance configuration structure.

◆ mediaInit

fsp_err_t(* sdmmc_api_t::mediaInit) (sdmmc_ctrl_t *const p_ctrl, sdmmc_device_t *const p_device)

Initializes an SD/MMC device. If the device is a card, the card must be plugged in prior to calling this API. This API blocks until the device initialization procedure is complete.

Parameters

[in]	p_ctrl	Pointer to SD/MMC instance control block.
[out]	p_device	Pointer to store device information.

◆ read

fsp_err_t(* sdmmc_api_t::read) (sdmmc_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const start_sector, uint32_t const sector_count)

Read data from an SD/MMC channel. This API is not supported for SDIO devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[out]	p_dest	Pointer to data buffer to read data to.
[in]	start_sector	First sector address to read.
[in]	sector_count	Number of sectors to read. All sectors must be in the range of sdmmc_device_t::sector_count.

◆ write

fsp_err_t(* sdmmc_api_t::write) (sdmmc_ctrl_t *const p_ctrl, uint8_t const *const p_source, uint32_t const start_sector, uint32_t const sector_count)

Write data to SD/MMC channel. This API is not supported for SDIO devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[in]	p_source	Pointer to data buffer to write data from.
[in]	start_sector	First sector address to write to.
[in]	sector_count	Number of sectors to write. All sectors must be in the range of sdmmc_device_t::sector_count.

◆ readIo

fsp_err_t(* sdmmc_api_t::readIo) (sdmmc_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t const function, uint32_t const address)

Read one byte of I/O data from an SDIO device. This API is not supported for SD or eMMC memory devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[out]	p_data	Pointer to location to store data byte.
[in]	function	SDIO Function Number.
[in]	address	SDIO register address.

◆ writeIo

fsp_err_t(* sdmmc_api_t::writeIo) (sdmmc_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t const function, uint32_t const address, sdmmc_io_write_mode_t const read_after_write)

Write one byte of I/O data to an SDIO device. This API is not supported for SD or eMMC memory devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[in,out]	p_data	Pointer to data byte to write. Read data is also provided here if read_after_write is true.
[in]	function	SDIO Function Number.
[in]	address	SDIO register address.
[in]	read_after_write	Whether or not to read back the same register after writing

◆ readIoExt

fsp_err_t(* sdmmc_api_t::readIoExt) (sdmmc_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const function, uint32_t const address, uint32_t *const count, sdmmc_io_transfer_mode_t transfer_mode, sdmmc_io_address_mode_t address_mode)

Read multiple bytes or blocks of I/O data from an SDIO device. This API is not supported for SD or eMMC memory devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[out]	p_dest	Pointer to data buffer to read data to.
[in]	function	SDIO Function Number.
[in]	address	SDIO register address.
[in]	count	Number of bytes or blocks to read, maximum 512 bytes or 511 blocks.
[in]	transfer_mode	Byte or block mode
[in]	address_mode	Fixed or incrementing address mode

◆ writeIoExt

fsp_err_t(* sdmmc_api_t::writeIoExt) (sdmmc_ctrl_t *const p_ctrl, uint8_t const *const p_source, uint32_t const function, uint32_t const address, uint32_t const count, sdmmc_io_transfer_mode_t transfer_mode, sdmmc_io_address_mode_t address_mode)

Write multiple bytes or blocks of I/O data to an SDIO device. This API is not supported for SD or eMMC memory devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[in]	p_source	Pointer to data buffer to write data from.
[in]	function_number	SDIO Function Number.
[in]	address	SDIO register address.
[in]	count	Number of bytes or blocks to write, maximum 512 bytes or 511 blocks.
[in]	transfer_mode	Byte or block mode
[in]	address_mode	Fixed or incrementing address mode

◆ ioIntEnable

fsp_err_t(* sdmmc_api_t::ioIntEnable) (sdmmc_ctrl_t *const p_ctrl, bool enable)

Enables SDIO interrupt for SD/MMC instance. This API is not supported for SD or eMMC memory devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[in]	enable	Interrupt enable = true, interrupt disable = false.

◆ statusGet

fsp_err_t(* sdmmc_api_t::statusGet) (sdmmc_ctrl_t *const p_ctrl, sdmmc_status_t *const p_status)

Get SD/MMC device status.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[out]	p_status	Pointer to current driver status.

◆ erase

fsp_err_t(* sdmmc_api_t::erase) (sdmmc_ctrl_t *const p_ctrl, uint32_t const start_sector, uint32_t const sector_count)

Erase SD/MMC sectors. The sector size for erase is fixed at 512 bytes. This API is not supported for SDIO devices.

Parameters

[in]	p_ctrl	Pointer to an open SD/MMC instance control block.
[in]	start_sector	First sector to erase. Must be a multiple of sdmmc_device_t::erase_sector_count.
[in]	sector_count	Number of sectors to erase. Must be a multiple of sdmmc_device_t::erase_sector_count. All sectors must be in the range of sdmmc_device_t::sector_count.

◆ callbackSet

fsp_err_t(* sdmmc_api_t::callbackSet) (sdmmc_ctrl_t *const p_ctrl, void(*p_callback)(sdmmc_callback_args_t *), void const *const p_context, sdmmc_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Control block set in sdmmc_api_t::open call.
[in]	p_callback	Callback function to register
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

◆ close

fsp_err_t(* sdmmc_api_t::close) (sdmmc_ctrl_t *const p_ctrl)

Close open SD/MMC device.

Parameters

[in] p_ctrl Pointer to an open SD/MMC instance control block.

◆ sdmmc_instance_t

struct sdmmc_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
sdmmc_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
sdmmc_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
sdmmc_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

◆ sdmmc_ctrl_t

typedef void sdmmc_ctrl_t

SD/MMC control block. Allocate an instance specific control block to pass into the SD/MMC API calls.

Enumeration Type Documentation

◆ sdmmc_card_type_t

enum sdmmc_card_type_t

SD/MMC media uses SD protocol or MMC protocol.

Enumerator
SDMMC_CARD_TYPE_MMC	The media is an eMMC device.
SDMMC_CARD_TYPE_SD	The media is an SD card.
SDMMC_CARD_TYPE_SDIO	The media is an SDIO card.

◆ sdmmc_bus_width_t

enum sdmmc_bus_width_t

SD/MMC data bus is 1, 4 or 8 bits wide.

Enumerator
SDMMC_BUS_WIDTH_1_BIT	Data bus is 1 bit wide.
SDMMC_BUS_WIDTH_4_BITS	Data bus is 4 bits wide.
SDMMC_BUS_WIDTH_8_BITS	Data bus is 8 bits wide.

◆ sdmmc_io_transfer_mode_t

enum sdmmc_io_transfer_mode_t

SDIO transfer mode, configurable in SDIO read/write extended commands.

Enumerator
SDMMC_IO_MODE_TRANSFER_BYTE	SDIO byte transfer mode.
SDMMC_IO_MODE_TRANSFER_BLOCK	SDIO block transfer mode.

◆ sdmmc_io_address_mode_t

enum sdmmc_io_address_mode_t

SDIO address mode, configurable in SDIO read/write extended commands.

Enumerator
SDMMC_IO_ADDRESS_MODE_FIXED	Write all data to the same address.
SDMMC_IO_ADDRESS_MODE_INCREMENT	Increment destination address after each write.

◆ sdmmc_io_write_mode_t

enum sdmmc_io_write_mode_t

Controls the RAW (read after write) flag of CMD52. Used to read back the status after writing a control register.

Enumerator
SDMMC_IO_WRITE_MODE_NO_READ	Write only (do not read back)
SDMMC_IO_WRITE_READ_AFTER_WRITE	Read back the register after write.

◆ sdmmc_event_t

enum sdmmc_event_t

Events that can trigger a callback function

Enumerator
SDMMC_EVENT_CARD_REMOVED	Card removed event.
SDMMC_EVENT_CARD_INSERTED	Card inserted event.
SDMMC_EVENT_RESPONSE	Response event.
SDMMC_EVENT_SDIO	IO event.
SDMMC_EVENT_TRANSFER_COMPLETE	Read or write complete.
SDMMC_EVENT_TRANSFER_ERROR	Read or write failed.
SDMMC_EVENT_ERASE_COMPLETE	Erase completed.
SDMMC_EVENT_ERASE_BUSY	Erase timeout, poll sdmmc_api_t::statusGet.

◆ sdmmc_card_detect_t

enum sdmmc_card_detect_t

Card detection configuration options.

Enumerator
SDMMC_CARD_DETECT_NONE	Card detection unused.
SDMMC_CARD_DETECT_CD	Card detection using the CD pin.

◆ sdmmc_write_protect_t

enum sdmmc_write_protect_t

Write protection configuration options.

Enumerator
SDMMC_WRITE_PROTECT_NONE	Write protection unused.
SDMMC_WRITE_PROTECT_WP	Write protection using WP pin.

◆ sdmmc_r1_state_t

enum sdmmc_r1_state_t

Card state when receiving the prior command.

Enumerator
SDMMC_R1_STATE_IDLE	Idle State.
SDMMC_R1_STATE_READY	Ready State.
SDMMC_R1_STATE_IDENT	Identification State.
SDMMC_R1_STATE_STBY	Stand-by State.
SDMMC_R1_STATE_TRAN	Transfer State.
SDMMC_R1_STATE_DATA	Sending-data State.
SDMMC_R1_STATE_RCV	Receive-data State.
SDMMC_R1_STATE_PRG	Programming State.
SDMMC_R1_STATE_DIS	Disconnect State (between programming and stand-by)
SDMMC_R1_STATE_IO	This is an I/O card and memory states do not apply.

Detailed Description

Summary

Data Structures

Typedefs

Enumerations

Data Structure Documentation

◆ sdmmc_response_t.status_b

◆ sdmmc_status_t

◆ sdmmc_device_t

◆ sdmmc_callback_args_t

◆ sdmmc_write_io_args_t

◆ sdmmc_read_io_ext_args_t

◆ sdmmc_write_io_ext_args_t

◆ sdmmc_cfg_t

Data Fields

Field Documentation

◆ block_size

◆ card_detect

◆ write_protect

◆ sdmmc_api_t

Data Fields

Field Documentation

◆ open

◆ mediaInit

◆ read

◆ write

◆ readIo

◆ writeIo

◆ readIoExt

◆ writeIoExt

◆ ioIntEnable

◆ statusGet

◆ erase

◆ callbackSet

◆ close

◆ sdmmc_instance_t

Typedef Documentation

◆ sdmmc_ctrl_t

Enumeration Type Documentation

◆ sdmmc_card_type_t

◆ sdmmc_bus_width_t

◆ sdmmc_io_transfer_mode_t

◆ sdmmc_io_address_mode_t

◆ sdmmc_io_write_mode_t

◆ sdmmc_event_t

◆ sdmmc_card_detect_t

◆ sdmmc_write_protect_t

◆ sdmmc_r1_state_t