MT2523 API Reference  LinkIt SDK v4
SD

This section introduces the Secure Digital Memory Dard/Embedded Multi Media Card(SD/eMMC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, SD/eMMC function groups, enums, structures and functions. More...

Overview

This section introduces the Secure Digital Memory Dard/Embedded Multi Media Card(SD/eMMC) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, SD/eMMC function groups, enums, structures and functions.

Terms and acronyms

Terms Details
CID Card identification number register. For an introduction to the CID, please refer to SD Memory Card Specification Version 2.0 or MultiMediaCard System Specification Version 4.41 .
CSD Card Specific Data register. For an introduction to the CSD, please refer to SD Memory Card Specification Version 2.0 or MultiMediaCard System Specification Version 4.41 .
DSR Driver Stage Register. For an introduction to the DSR, please refer to SD Memory Card Specification Version 2.0 or MultiMediaCard System Specification Version 4.41 .
MSDC MS/SD memory card controller, that support the MultiMediaCard System Specification Version 4.41,SD Memory Card Specification Version 2.0 and SDIO Card Specification Version 2.0.
OCR Operation Conditions Register. For an introduction to the OCR, please refer to SD Memory Card Specification Version 2.0 or MultiMediaCard System Specification Version 4.41 .
RCA Relative Card Address register. For an introduction to the RCA, please refer to SD Memory Card Specification Version 2.0 or MultiMediaCard System Specification Version 4.41 .
SD Secure Digital Memory Card. For an introduction to the Secure Digital Memory Card, please refer to Secure Digital in Wikipedia .
VSS Voltage Source Supply (ground), or power supply ground.
eMMC Embedded Multi Media Card. For an introduction to the Embedded Multi Media Card, please refer to MultiMediaCard in Wikipedia .

Supported features

Software architecture of the SD/eMMC

Call hal_sd_init() to initialize the MSDC and the SD/eMMC card. Then the SD/eMMC card gets into a transfer state and users can call hal_sd_write_blocks() or hal_sd_write_blocks_dma() to write data to the SD/eMMC card, or call hal_sd_read_blocks() or hal_sd_read_blocks_dma() to read data from the SD/eMMC card. Other supported APIs can also be called, such as hal_sd_erase_sectors(). Register an EINT callback function for card detection and a callback function will execute when the card is inserted or plugged out.

How to use this driver

Functions

hal_sd_status_t hal_sd_init (hal_sd_port_t sd_port, hal_sd_config_t *sd_config)
 This function initializes the MSDC and SD/eMMC card. More...
 
hal_sd_status_t hal_sd_deinit (hal_sd_port_t sd_port)
 This function deinitializes the MSDC and the SD/eMMC settings. More...
 
hal_sd_status_t hal_sd_register_card_detection_callback (hal_sd_port_t sd_port, hal_sd_callback_t sd_callback, void *user_data)
 This function registers a callback function to detect a card. More...
 
hal_sd_status_t hal_sd_set_bus_width (hal_sd_port_t sd_port, hal_sd_bus_width_t bus_width)
 This function sets a bus width for MSDC and the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_set_clock (hal_sd_port_t sd_port, uint32_t clock)
 This function sets the output clock of the MSDC. More...
 
hal_sd_status_t hal_sd_get_clock (hal_sd_port_t sd_port, uint32_t *clock)
 This function gets the output clock of the MSDC. More...
 
hal_sd_status_t hal_sd_get_capacity (hal_sd_port_t sd_port, uint64_t *capacity)
 This function gets the card capacity of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_get_erase_sector_size (hal_sd_port_t sd_port, uint32_t *erase_sector_size)
 This function gets the sector size of the SD/eMMC card, mainly for erase purpose. More...
 
hal_sd_status_t hal_sd_erase_sectors (hal_sd_port_t sd_port, uint32_t start_sector, uint32_t sector_number)
 This function erases the card sectors of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_read_blocks (hal_sd_port_t sd_port, uint32_t *read_buffer, uint32_t start_address, uint32_t block_number)
 This function reads data from the SD/eMMC card in the MCU mode. More...
 
hal_sd_status_t hal_sd_write_blocks (hal_sd_port_t sd_port, const uint32_t *write_data, uint32_t start_address, uint32_t block_number)
 This function writes data to the SD/eMMC card in the MCU mode. More...
 
hal_sd_status_t hal_sd_read_blocks_dma (hal_sd_port_t sd_port, uint32_t *read_buffer, uint32_t start_address, uint32_t block_number)
 This function reads data from the SD/eMMC card in the DMA mode. More...
 
hal_sd_status_t hal_sd_write_blocks_dma (hal_sd_port_t sd_port, const uint32_t *write_data, uint32_t start_address, uint32_t block_number)
 This function writes data to the SD/eMMC card in the DMA mode. More...
 
hal_sd_status_t hal_sd_get_csd (hal_sd_port_t sd_port, uint32_t *csd)
 This function gets the CSD register value of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_get_cid (hal_sd_port_t sd_port, uint32_t *cid)
 This function gets the CID register value of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_get_card_type (hal_sd_port_t sd_port, hal_sd_card_type_t *card_type)
 This function gets the card type of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_get_ocr (hal_sd_port_t sd_port, uint32_t *ocr)
 This function gets the OCR register value of the SD/eMMC card. More...
 
hal_sd_status_t hal_sd_get_card_status (hal_sd_port_t sd_port, uint32_t *card_status)
 This function gets the card status of the SD/eMMC card. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_sd_status_t hal_sd_deinit ( hal_sd_port_t  sd_port)

This function deinitializes the MSDC and the SD/eMMC settings.

Parameters
[in]sd_portis the MSDC deinitialization port.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully.
See also
hal_sd_init()
hal_sd_status_t hal_sd_erase_sectors ( hal_sd_port_t  sd_port,
uint32_t  start_sector,
uint32_t  sector_number 
)

This function erases the card sectors of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to erase the card sectors.
[in]start_sectoris the start address of a sector on the SD/eMMC card to erase.
[in]sector_numberis the sector number of the SD/eMMC card to erase.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.
hal_sd_status_t hal_sd_get_capacity ( hal_sd_port_t  sd_port,
uint64_t *  capacity 
)

This function gets the card capacity of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the card capacity.
[out]capacityis the SD/eMMC card capacity, the unit is bytes.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully.
hal_sd_status_t hal_sd_get_card_status ( hal_sd_port_t  sd_port,
uint32_t *  card_status 
)

This function gets the card status of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the card status.
[out]card_statusis a pointer to the card status that is read from the card status register.For an introduction to the card status register, please refer to SD Memory Card Specification Version 2.0
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_get_card_type ( hal_sd_port_t  sd_port,
hal_sd_card_type_t card_type 
)

This function gets the card type of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the card type.
[out]card_typeis the current card type of the SD/eMMC card.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_get_cid ( hal_sd_port_t  sd_port,
uint32_t *  cid 
)

This function gets the CID register value of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the CID register value.
[out]cidis the CID value of the SD/eMMC card.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_get_clock ( hal_sd_port_t  sd_port,
uint32_t *  clock 
)

This function gets the output clock of the MSDC.

Parameters
[in]sd_portis the MSDC port to get the clock.
[out]clockis the current output clock of the MSDC, the unit is kHz.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully.
hal_sd_status_t hal_sd_get_csd ( hal_sd_port_t  sd_port,
uint32_t *  csd 
)

This function gets the CSD register value of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the CSD register value.
[out]csdis the CSD register value of the SD/eMMC card.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_get_erase_sector_size ( hal_sd_port_t  sd_port,
uint32_t *  erase_sector_size 
)

This function gets the sector size of the SD/eMMC card, mainly for erase purpose.

Parameters
[in]sd_portis the MSDC port to get erase sector size.
[out]erase_sector_sizeis the card erase sector size of the SD/eMMC card, the unit is bytes.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_get_ocr ( hal_sd_port_t  sd_port,
uint32_t *  ocr 
)

This function gets the OCR register value of the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to get the OCR register value.
[out]ocris the OCR value of the SD/eMMC card.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given.
hal_sd_status_t hal_sd_init ( hal_sd_port_t  sd_port,
hal_sd_config_t sd_config 
)

This function initializes the MSDC and SD/eMMC card.

It can also set the MSDC output clock and bus width. The MSDC output clock is recommended set to 45000(kHz) as good and no need to modify.

Parameters
[in]sd_portis the initialization configuration port. For more details about this parameter, please refer to hal_sd_port_t.
[in]sd_configis the initialization configuration parameter. For more details about this parameter, please refer to hal_sd_config_t.
Returns
Indicates whether this function call is successful or not. If the return value is HAL_SD_STATUS_OK,the call successded, else the initialization failed.
See also
hal_sd_deinit()
hal_sd_status_t hal_sd_read_blocks ( hal_sd_port_t  sd_port,
uint32_t *  read_buffer,
uint32_t  start_address,
uint32_t  block_number 
)

This function reads data from the SD/eMMC card in the MCU mode.

Base on the consideration of transmission speed, this API is recommended when each transmission is less than or equal to 2 blocks.

Parameters
[in]sd_portis the MSDC port to read.
[out]read_bufferis the address to store the data read from the card.
[in]start_addressis the start address on the SD/eMMC card to read from.
[in]block_numberis the block number on the SD/eMMC card to read.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.
hal_sd_status_t hal_sd_read_blocks_dma ( hal_sd_port_t  sd_port,
uint32_t *  read_buffer,
uint32_t  start_address,
uint32_t  block_number 
)

This function reads data from the SD/eMMC card in the DMA mode.

This API may block the application task. Base on the consideration of transmission speed, this API is recommended when each transmission is greater than 2 blocks.

Parameters
[in]sd_portis the MSDC port to read.
[out]read_bufferis the address to store data read from the card. The address must be a noncacheable and 4 bytes aligned address.
[in]start_addressis the read start address of the SD/eMMC card.
[in]block_numberis the block number on the SD/eMMC card to read.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.
hal_sd_status_t hal_sd_register_card_detection_callback ( hal_sd_port_t  sd_port,
hal_sd_callback_t  sd_callback,
void *  user_data 
)

This function registers a callback function to detect a card.

Parameters
[in]sd_portis the MSDC port to detect a card.
[in]sd_callbackis the function pointer of the callback. The callback function is called once the SD/eMMC card is inserted or plugged out.
[in]user_datais the callback parameter.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully.
hal_sd_status_t hal_sd_set_bus_width ( hal_sd_port_t  sd_port,
hal_sd_bus_width_t  bus_width 
)

This function sets a bus width for MSDC and the SD/eMMC card.

Parameters
[in]sd_portis the MSDC port to be set.
[in]bus_widthis the SD/eMMC card's bus width.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, set the bus width error occurred.
hal_sd_status_t hal_sd_set_clock ( hal_sd_port_t  sd_port,
uint32_t  clock 
)

This function sets the output clock of the MSDC.

Parameters
[in]sd_portis the MSDC port to set the clock.
[in]clockis the expected output clock of the MSDC. It should be less than 50000, the unit is kHz.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.
hal_sd_status_t hal_sd_write_blocks ( hal_sd_port_t  sd_port,
const uint32_t *  write_data,
uint32_t  start_address,
uint32_t  block_number 
)

This function writes data to the SD/eMMC card in the MCU mode.

Base on the consideration of transmission speed, this API is recommended when each transmission is less than or equal to 2 blocks.

Parameters
[in]sd_portis the MSDC port to write.
[in]write_datais the address to store the data that will be written.
[in]start_addressis the start address on the SD/eMMC card to write into.
[in]block_numberis the block number on the SD/eMMC card to write.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.
hal_sd_status_t hal_sd_write_blocks_dma ( hal_sd_port_t  sd_port,
const uint32_t *  write_data,
uint32_t  start_address,
uint32_t  block_number 
)

This function writes data to the SD/eMMC card in the DMA mode.

This API may block the application task. Base on the consideration of transmission speed, this API is recommended when each transmission is greater than 2 blocks.

Parameters
[in]sd_portis the MSDC port to write.
[in]write_datais the address to store the data that will be written, the address must be a noncacheable and 4 bytes aligned address.
[in]start_addressis the start address on the SD/eMMC card to write into.
[in]block_numberis the block number of the SD/eMMC card to write.
Returns
HAL_SD_STATUS_OK, if the operation completed successfully. HAL_SD_STATUS_ERROR, an error occurred, such as a wrong parameter is given. HAL_SD_STATUS_BUSY, the MSDC is busy.