SD/MMC (r_sdhi)

Functions
fsp_err_t	R_SDHI_Open (sdmmc_ctrl_t *const p_api_ctrl, sdmmc_cfg_t const *const p_cfg)
fsp_err_t	R_SDHI_MediaInit (sdmmc_ctrl_t *const p_api_ctrl, sdmmc_device_t *const p_device)
fsp_err_t	R_SDHI_Read (sdmmc_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const start_sector, uint32_t const sector_count)
fsp_err_t	R_SDHI_Write (sdmmc_ctrl_t *const p_api_ctrl, uint8_t const *const p_source, uint32_t const start_sector, uint32_t const sector_count)
fsp_err_t	R_SDHI_ReadIo (sdmmc_ctrl_t *const p_api_ctrl, uint8_t *const p_data, uint32_t const function, uint32_t const address)
fsp_err_t	R_SDHI_WriteIo (sdmmc_ctrl_t *const p_api_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	R_SDHI_ReadIoExt (sdmmc_ctrl_t *const p_api_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	R_SDHI_WriteIoExt (sdmmc_ctrl_t *const p_api_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	R_SDHI_IoIntEnable (sdmmc_ctrl_t *const p_api_ctrl, bool enable)
fsp_err_t	R_SDHI_StatusGet (sdmmc_ctrl_t *const p_api_ctrl, sdmmc_status_t *const p_status)
fsp_err_t	R_SDHI_Erase (sdmmc_ctrl_t *const p_api_ctrl, uint32_t const start_sector, uint32_t const sector_count)
fsp_err_t	R_SDHI_CallbackSet (sdmmc_ctrl_t *const p_api_ctrl, void(*p_callback)(sdmmc_callback_args_t *), void const *const p_context, sdmmc_callback_args_t *const p_callback_memory)
fsp_err_t	R_SDHI_Close (sdmmc_ctrl_t *const p_api_ctrl)

Detailed Description

Driver for the SD/MMC Host Interface (SDHI) peripheral on RA MCUs. This module implements the SD/MMC Interface.

Overview

Features

• Supports the following memory devices: SDSC (SD Standard Capacity), SDHC (SD High Capacity), SDXC (SD Extended Capacity) and eMMC (embedded Multi Media Card)
  • Supports reading, writing and erasing SD memory devices
  • Supports 1, 4 or 8-bit data bus (8-bit bus is supported for eMMC only)
  • Supports detection of device write protection (SD cards only)
  • Supports high speed mode
• Automatically configures the clock to the maximum clock rate supported by both host (MCU) and device
• Supports hardware acceleration using DMAC or DTC
• Supports callback notification when an operation completes or an error occurs

Configuration

Build Time Configurations for r_sdhi

The following build time configurations are defined in fsp_cfg/r_sdhi_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Unaligned Access Support	Disabled Enabled	Enabled	If enabled, code for supporting buffers that are not aligned on a 4-byte boundary is included in the build. Only disable this if all buffers passed to the driver are 4-byte aligned.
SD Support	Disabled Enabled	Enabled	If selected code for SD card support is included in the build.
eMMC Support	Disabled Enabled	Disabled	If selected code for eMMC device support is included in the build.

Configurations for Storage > SD/MMC (r_sdhi)

This module can be added to the Stacks tab via New Stack > Storage > SD/MMC (r_sdhi). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_sdmmc0	Module name.
Channel	Value must be a non-negative integer	0	Select the channel.
Bus Width	MCU Specific Options		Select the bus width.
Block Size	Value must be an integer between 1 and 512	512	Select the media block size. Must be 512 for SD cards or eMMC devices. Must be 1-512 for SDIO.
Card Detection	Not Used CD Pin	CD Pin	Select the card detection method.
Write Protection	Not Used WP Pin	WP Pin	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.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Access Interrupt Priority	MCU Specific Options		Select the access interrupt priority.
Card Interrupt Priority	MCU Specific Options		Select the card interrupt priority.
DTC Interrupt Priority	MCU Specific Options		Select the DTC interrupt priority.

Interrupt Configurations:

The following interrupts are required to use the r_sdhi module:

Using SD/MMC with DTC:

• Access Interrupt
• DTC Interrupt

Using SD/MMC with DMAC:

• Access Interrupt
• DMAC Interrupt (in DMAC instance)

The Card interrupt is optional and only available on MCU packages that have the SDnCD pin (n = channel number).

Clock Configuration

The SDMMC MCU peripheral (SDHI) uses the PCLKA for its clock source. The SDMMC driver selects the optimal built-in divider based on the PCLKA frequency and the maximum clock rate allowed by the device obtained at media initialization.

Pin Configuration

The SDMMC driver supports the following pins (n = channel number):

• SDnCLK
• SDnCMD
• SDnDAT0
• SDnDAT1
• SDnDAT2
• SDnDAT3
• SDnDAT4 (not available on all MCUs)
• SDnDAT5 (not available on all MCUs)
• SDnDAT6 (not available on all MCUs)
• SDnDAT7 (not available on all MCUs)
• SDnCD (not available on all MCUs)
• SDnWP

The drive capacity for each pin should be set to "Medium" or "High" for most hardware designs. This can be configured in the Pins tab of the RA Configuration editor by selecting the pin under Pin Selection -> Ports.

Usage Notes

Card Detection

When Card Detection is configured to "CD Pin" in the RA Configuration editor, interrupt flags are cleared and card detection is enabled during R_SDHI_Open().

R_SDHI_StatusGet() can be called to retrieve the current status of the card (including whether a card is present). If the Card Interrupt Priority is enabled, a callback is called when a card is inserted or removed.

If a card is removed and reinserted, R_SDHI_MediaInit() must be called before reading from the card or writing to the card.

Note

R_SDHI_StatusGet() should be used to initially determine the card state after opening the interface.

DMA Request Interrupt Priority

When data transfers are not 4-byte aligned or not a multiple of 4 bytes, a software copy of the block size (up to 512 bytes) is done in the DMA Request interrupt. This blocks all other interrupts that are a lower or equal priority to the access interrupt until the software copy is complete.

Timing Notes for R_SDHI_MediaInit

The R_SDHI_MediaInit() API completes the entire device identification and configuration process. This involves several command-response cycles at a bus width of 1 bit and a bus speed of 400 kHz or less.

Limitations

Developers should be aware of the following limitations when using the SDHI:

Blocking Calls

The following functions block execution until the response is received for at least one command:

• R_SDHI_MediaInit
• R_SDHI_Erase

Once the function returns the status of the operation can be determined via R_SDHI_StatusGet or through receipt of a callback.

Note

Due to the variability in clocking configurations it is recommended to determine blocking delays experimentally on the target system.

Data Alignment and Size

Data transfers should be 4-byte aligned and a multiple of 4 bytes in size whenever possible. This recommendation applies to the read(), write(), readIoExt(), and writeIoExt() APIs. When data transfers are 4-byte aligned and a multiple of 4-bytes, the r_sdhi driver is zero copy and takes full advantage of hardware acceleration by the DMAC or DTC. When data transfers are not 4-byte aligned or not a multiple of 4 bytes an extra CPU interrupt is required for each block transferred and a software copy is used to move data to the destination buffer.

Examples

Basic Example

This is a basic example of minimal use of the r_sdhi in an application.

uint8_t  g_dest[SDHI_MAX_BLOCK_SIZE] BSP_ALIGN_VARIABLE(4);
uint8_t  g_src[SDHI_MAX_BLOCK_SIZE]  BSP_ALIGN_VARIABLE(4);
uint32_t g_transfer_complete = 0;
void r_sdhi_basic_example (void)
{
    /* Initialize g_src to known data */
    for (uint32_t i = 0; i < SDHI_MAX_BLOCK_SIZE; i++)
    {
        g_src[i] = (uint8_t) ('A' + (i % 26));
    }


    /* Open the SDHI driver. */
    fsp_err_t err = R_SDHI_Open(&g_sdmmc0_ctrl, &g_sdmmc0_cfg);

    assert(FSP_SUCCESS == err);


    /* A device shall be ready to accept the first command within 1ms from detecting VDD min. Reference section 6.4.1.1
     * "Power Up Time of Card" in the SD Physical Layer Simplified Specification Version 6.00. */
    R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);

    /* Initialize the SD card.  This should not be done until the card is plugged in for SD devices. */
    err = R_SDHI_MediaInit(&g_sdmmc0_ctrl, NULL);

    assert(FSP_SUCCESS == err);


    err = R_SDHI_Write(&g_sdmmc0_ctrl, g_src, 3, 1);

    assert(FSP_SUCCESS == err);

    while (!g_transfer_complete)
    {
        /* Wait for transfer. */
    }


    err = R_SDHI_Read(&g_sdmmc0_ctrl, g_dest, 3, 1);

    assert(FSP_SUCCESS == err);

    while (!g_transfer_complete)
    {
        /* Wait for transfer. */
    }
}

/* The callback is called when a transfer completes. */
void r_sdhi_example_callback (sdmmc_callback_args_t * p_args)
{
    if (SDMMC_EVENT_TRANSFER_COMPLETE == p_args->event)
    {
        g_transfer_complete = 1;
    }
}

Card Detection Example

This is an example of using SDHI when the card may not be plugged in. The card detection interrupt must be enabled to use this example.

bool g_card_inserted = false;
void r_sdhi_card_detect_example (void)
{
    /* Open the SDHI driver. This enables the card detection interrupt. */
    fsp_err_t err = R_SDHI_Open(&g_sdmmc0_ctrl, &g_sdmmc0_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);


    /* Check if card is inserted. */
    sdmmc_status_t status;
    err = R_SDHI_StatusGet(&g_sdmmc0_ctrl, &status);
    assert(FSP_SUCCESS == err);

    if (!status.card_inserted)
    {
        while (!g_card_inserted)
        {
            /* Wait for a card insertion interrupt. */
        }
    }


    /* A device shall be ready to accept the first command within 1ms from detecting VDD min. Reference section 6.4.1.1
     * "Power Up Time of Card" in the SD Physical Layer Simplified Specification Version 6.00. */
    R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);

    /* Initialize the SD card after card insertion is detected. */
    err = R_SDHI_MediaInit(&g_sdmmc0_ctrl, NULL);
    assert(FSP_SUCCESS == err);
}

/* The callback is called when a card detection event occurs if the card detection interrupt is enabled. */
void r_sdhi_card_detect_example_callback (sdmmc_callback_args_t * p_args)
{
    if (SDMMC_EVENT_CARD_INSERTED == p_args->event)
    {
        g_card_inserted = true;
    }

    if (SDMMC_EVENT_CARD_REMOVED == p_args->event)
    {
        g_card_inserted = false;
    }
}

Function Documentation

R_SDHI_Open()

fsp_err_t R_SDHI_Open	(	sdmmc_ctrl_t *const	p_api_ctrl,
		sdmmc_cfg_t const *const	p_cfg
	)

Opens the driver. Resets SDHI, and enables card detection interrupts if card detection is enabled. R_SDHI_MediaInit must be called after this function before any other functions can be used.

Implements sdmmc_api_t::open().

Example:

    /* Open the SDHI driver. */
    fsp_err_t err = R_SDHI_Open(&g_sdmmc0_ctrl, &g_sdmmc0_cfg);

Return values

FSP_SUCCESS	Module is now open.
FSP_ERR_ASSERTION	Null Pointer or block size is not in the valid range of 1-512. Block size must be 512 bytes for SD cards and eMMC devices. It is configurable for SDIO only.
FSP_ERR_ALREADY_OPEN	Driver has already been opened with this instance of the control structure.
FSP_ERR_IRQ_BSP_DISABLED	Access interrupt is not enabled.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	Requested channel does not exist on this MCU.

R_SDHI_MediaInit()

fsp_err_t R_SDHI_MediaInit	(	sdmmc_ctrl_t *const	p_api_ctrl,
		sdmmc_device_t *const	p_device
	)

Initializes the SDHI hardware and completes identification and configuration for the SD or eMMC device. This procedure requires several sequential commands. This function blocks until all identification and configuration commands are complete.

Implements sdmmc_api_t::mediaInit().

Example:

    /* A device shall be ready to accept the first command within 1ms from detecting VDD min. Reference section 6.4.1.1
     * "Power Up Time of Card" in the SD Physical Layer Simplified Specification Version 6.00. */
    R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);

    /* Initialize the SD card.  This should not be done until the card is plugged in for SD devices. */
    err = R_SDHI_MediaInit(&g_sdmmc0_ctrl, NULL);

Return values

FSP_SUCCESS	Module is now ready for read/write access.
FSP_ERR_ASSERTION	Null Pointer or block size is not in the valid range of 1-512. Block size must be 512 bytes for SD cards and eMMC devices. It is configurable for SDIO only.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_INIT_FAILED	Device was not identified as an SD card, eMMC device, or SDIO card.
FSP_ERR_RESPONSE	Device responded with an error.
FSP_ERR_TIMEOUT	Device did not respond.
FSP_ERR_DEVICE_BUSY	Device is holding DAT0 low (device is busy) or another operation is ongoing.

R_SDHI_Read()

fsp_err_t R_SDHI_Read	(	sdmmc_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	start_sector,
		uint32_t const	sector_count
	)

Reads data from an SD or eMMC device. Up to 0x10000 sectors can be read at a time. Implements sdmmc_api_t::read().

A callback with the event SDMMC_EVENT_TRANSFER_COMPLETE is called when the read data is available.

Example:

    err = R_SDHI_Read(&g_sdmmc0_ctrl, g_dest, 3, 1);

Return values

FSP_SUCCESS	Data read successfully.
FSP_ERR_ASSERTION	NULL pointer.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_DEVICE_BUSY	Driver is busy with a previous operation.

R_SDHI_Write()

fsp_err_t R_SDHI_Write	(	sdmmc_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_source,
		uint32_t const	start_sector,
		uint32_t const	sector_count
	)

Writes data to an SD or eMMC device. Up to 0x10000 sectors can be written at a time. Implements sdmmc_api_t::write().

A callback with the event SDMMC_EVENT_TRANSFER_COMPLETE is called when the all data has been written and the device is no longer holding DAT0 low to indicate it is busy.

Example:

    err = R_SDHI_Write(&g_sdmmc0_ctrl, g_src, 3, 1);

Return values

FSP_SUCCESS	Card write finished successfully.
FSP_ERR_ASSERTION	Handle or Source address is NULL.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_DEVICE_BUSY	Driver is busy with a previous operation.
FSP_ERR_CARD_WRITE_PROTECTED	SD card is Write Protected.
FSP_ERR_WRITE_FAILED	Write operation failed.

R_SDHI_ReadIo()

fsp_err_t R_SDHI_ReadIo	(	sdmmc_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_data,
		uint32_t const	function,
		uint32_t const	address
	)

The Read function reads a one byte register from an SDIO card. Implements sdmmc_api_t::readIo().

This function blocks until the command is sent and the response is received. p_data contains the register value read when this function returns.

Return values

FSP_SUCCESS	Data read successfully.
FSP_ERR_ASSERTION	NULL pointer.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_UNSUPPORTED	SDIO support disabled in SDHI_CFG_SDIO_SUPPORT_ENABLE.
FSP_ERR_RESPONSE	Device responded with an error.
FSP_ERR_TIMEOUT	Device did not respond.
FSP_ERR_DEVICE_BUSY	Device is holding DAT0 low (device is busy) or another operation is ongoing.

R_SDHI_WriteIo()

fsp_err_t R_SDHI_WriteIo	(	sdmmc_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_data,
		uint32_t const	function,
		uint32_t const	address,
		sdmmc_io_write_mode_t const	read_after_write
	)

Writes a one byte register to an SDIO card. Implements sdmmc_api_t::writeIo().

This function blocks until the command is sent and the response is received. The register has been written when this function returns. If read_after_write is true, p_data contains the register value read when this function returns.

Return values

FSP_SUCCESS	Card write finished successfully.
FSP_ERR_ASSERTION	Handle or Source address is NULL.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_WRITE_FAILED	Write operation failed.
FSP_ERR_UNSUPPORTED	SDIO support disabled in SDHI_CFG_SDIO_SUPPORT_ENABLE.
FSP_ERR_RESPONSE	Device responded with an error.
FSP_ERR_TIMEOUT	Device did not respond.
FSP_ERR_DEVICE_BUSY	Device is holding DAT0 low (device is busy) or another operation is ongoing.

R_SDHI_ReadIoExt()

fsp_err_t R_SDHI_ReadIoExt	(	sdmmc_ctrl_t *const	p_api_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
	)

Reads data from an SDIO card function. Implements sdmmc_api_t::readIoExt().

This function blocks until the command is sent and the response is received. A callback with the event SDMMC_EVENT_TRANSFER_COMPLETE is called when the read data is available.

Return values

FSP_SUCCESS	Data read successfully.
FSP_ERR_ASSERTION	NULL pointer, or count is not in the valid range of 1-512 for byte mode or 1-511 for block mode.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_DEVICE_BUSY	Driver is busy with a previous operation.
FSP_ERR_UNSUPPORTED	SDIO support disabled in SDHI_CFG_SDIO_SUPPORT_ENABLE.

R_SDHI_WriteIoExt()

fsp_err_t R_SDHI_WriteIoExt	(	sdmmc_ctrl_t *const	p_api_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
	)

Writes data to an SDIO card function. Implements sdmmc_api_t::writeIoExt().

This function blocks until the command is sent and the response is received. A callback with the event SDMMC_EVENT_TRANSFER_COMPLETE is called when the all data has been written.

Return values

FSP_SUCCESS	Card write finished successfully.
FSP_ERR_ASSERTION	NULL pointer, or count is not in the valid range of 1-512 for byte mode or 1-511 for block mode.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_DEVICE_BUSY	Driver is busy with a previous operation.
FSP_ERR_WRITE_FAILED	Write operation failed.
FSP_ERR_UNSUPPORTED	SDIO support disabled in SDHI_CFG_SDIO_SUPPORT_ENABLE.

R_SDHI_IoIntEnable()

fsp_err_t R_SDHI_IoIntEnable	(	sdmmc_ctrl_t *const	p_api_ctrl,
		bool	enable
	)

Enables or disables the SDIO Interrupt. Implements sdmmc_api_t::ioIntEnable().

Return values

FSP_SUCCESS	Card enabled or disabled SDIO interrupts successfully.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_ASSERTION	NULL pointer.
FSP_ERR_DEVICE_BUSY	Driver is busy with a previous operation.
FSP_ERR_UNSUPPORTED	SDIO support disabled in SDHI_CFG_SDIO_SUPPORT_ENABLE.

R_SDHI_StatusGet()

fsp_err_t R_SDHI_StatusGet	(	sdmmc_ctrl_t *const	p_api_ctrl,
		sdmmc_status_t *const	p_status
	)

Provides driver status. Implements sdmmc_api_t::statusGet().

Return values

FSP_SUCCESS	Status stored in p_status.
FSP_ERR_ASSERTION	NULL pointer.
FSP_ERR_NOT_OPEN	Driver has not been initialized.

R_SDHI_Erase()

fsp_err_t R_SDHI_Erase	(	sdmmc_ctrl_t *const	p_api_ctrl,
		uint32_t const	start_sector,
		uint32_t const	sector_count
	)

Erases sectors of an SD card or eMMC device. Implements sdmmc_api_t::erase().

This function blocks until the erase command is sent. Poll the status to determine when erase is complete.

Return values

FSP_SUCCESS	Erase operation requested.
FSP_ERR_ASSERTION	A required pointer is NULL or an argument is invalid.
FSP_ERR_NOT_OPEN	Driver has not been initialized.
FSP_ERR_CARD_NOT_INITIALIZED	Card was unplugged.
FSP_ERR_CARD_WRITE_PROTECTED	SD card is Write Protected.
FSP_ERR_RESPONSE	Device responded with an error.
FSP_ERR_TIMEOUT	Device did not respond.
FSP_ERR_DEVICE_BUSY	Device is holding DAT0 low (device is busy) or another operation is ongoing.

R_SDHI_CallbackSet()

fsp_err_t R_SDHI_CallbackSet	(	sdmmc_ctrl_t *const	p_api_ctrl,
		void(*)(sdmmc_callback_args_t *)	p_callback,
		void const *const	p_context,
		sdmmc_callback_args_t *const	p_callback_memory
	)

Updates the user callback with the option to provide memory for the callback argument structure. Implements sdmmc_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.

R_SDHI_Close()

fsp_err_t R_SDHI_Close

(

sdmmc_ctrl_t *const

p_api_ctrl

)

Closes an open SD/MMC device. Implements sdmmc_api_t::close().

Return values

FSP_SUCCESS	Successful close.
FSP_ERR_ASSERTION	The parameter p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Driver has not been initialized.