SD

This section introduces the Secure Digital Memory Dard/Embedded Multimedia 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 Multimedia 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

• Supports DMA and MCU modes.
  
  • DMA mode: In this mode, the DMA hardware carries data directly from the RAM to the MSDC FIFO and Stores in the SD/eMMC card or read data directly from the MSDC FIFO to the RAM. Base on the consideration of transmission speed, this mode is recommended when each transmission is greater than 2 blocks.
  • MCU mode: In this mode, the MCU writes data from the RAM to the MSDC FIFO and Stores in the SD/eMMC card or read data from the MSDC FIFO to the RAM. Base on the consideration of transmission speed, this mode is recommended when each transmission is less than or equal to 2 blocks.
  There are two APIs for the DMA mode, hal_sd_read_blocks_dma() to read data from the SD/eMMC card and hal_sd_write_blocks_dma() to write data to the card. Similarly, there are two APIs for the MCU mode, hal_sd_read_blocks() to read data from the SD/eMMC card and hal_sd_write_blocks() to write data to the card.
  
  
• Supports 1-bit or 4-bit bus width.
  1-bit bus width or 4-bit bus width is available to select for data transmission. For 1-bit bus width, only data line 0 (DAT0) is enabled to transfer data, The data line 1-3 (DAT[3:1]) cannot be in used. All four data line (DAT[3:0]) are available in the 4-bit bus width mode. The corresponding API is hal_sd_set_bus_width().
  
  
• Supports card detection.
  Connect one of the EINT pins to the SD card VSS2 pin on the device, then register EINT callback function in the software. Once the SD card is inserted or removed, an EINT interrupt occurs and the registered callback is executed. Please note that the SD card detection (HAL_SD_CARD_DETECTION) only works for the SD card. If the eMMC card is in use, the SD card detection (HAL_SD_CARD_DETECTION) should be switched off. The Easy Pinmux Tool (EPT) is used to configure the SD card detection pin for the EINT mode. Follow the steps below to configure the SD card detection pin in the EPT.
  
  • Step 1. Select the correct GPIO pin for the EINT mode and PU-47K_ohms in EPT tool's GPIO Setting window.
  • Step 2. Select the corresponding EINT pin's name for 'HAL_MSDC_EINT' in EPT tool's EINT Setting window.
  • Step 3. Switch on the corresponding feature option (HAL_SD_CARD_DETECTION).

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

• Read from or write to the SD/eMMC in the MCU mode.
  
  • Step 1. Call hal_gpio_init() to initialize the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if EPT tool hasn't been used to configure the related pinmux.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_read_blocks() to read the SD/eMMC card data.
  • Step 5. Call hal_sd_write_blocks() to write data to the SD/eMMC card.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t read_buffer;
    uint32_t write_buffer;
    uint32_t start_address;
    uint32_t block_number;
    
    sd_port=HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
        // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_read_blocks(sd_port, &read_buffer, start_address, block_number)) {
        // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_write_blocks(sd_port, &write_data, start_address, block_number)) {
        // Error handler.
    }

• Read from or write to the SD/eMMC in the DMA blocking mode.
  
  • Step 1. Call hal_gpio_init() to initialize the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if EPT tool hasn't been used to configure the related pinmux.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_read_blocks_dma() to read the SD/eMMC card data.
  • Step 5. Call hal_sd_write_blocks_dma() to write data to the SD/eMMC card.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t read_buffer;
    uint32_t write_buffer;
    uint32_t start_address;
    uint32_t block_number;
    
    sd_port=HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
        // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_read_blocks_dma_blocking(sd_port, &read_buffer, start_address, block_number)) {
        // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_write_blocks_dma_blcoking(sd_port, &read_buffer, start_address, block_number)) {
        // Error handler.
    }

• Read from or write to the SD/eMMC in the DMA interrupt mode.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_register_callback() to register the transfer result callback.
  • Step 5. Call hal_sd_read_blocks_dma() to read the SD/eMMC card data.
  • Step 6. Call hal_sd_write_blocks_dma() to write data to the SD/eMMC card.
  • Sample code:

     hal_sd_port_t sd_port;
     hal_sd_config_t sd_config;
     uint32_t read_buffer;
     uint32_t write_buffer;
     uint32_t start_address;
     uint32_t block_number;
    
     sd_port=HAL_SD_PORT_0;
     sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
     // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
     sd_config.clock=45000;
    
     // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
     hal_gpio_init(HAL_GPIO_30);
     hal_gpio_init(HAL_GPIO_31);
     hal_gpio_init(HAL_GPIO_32);
     hal_gpio_init(HAL_GPIO_33);
     hal_gpio_init(HAL_GPIO_34);
     hal_gpio_init(HAL_GPIO_35);
    
     // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
     // No need to configure the pinmux, if EPT is used.
     // function_index = HAL_GPIO_30_MC0_CK
     hal_pinmux_set_function(HAL_GPIO_30, function_index);
     // function_index = HAL_GPIO_31_MC0_CM0
     hal_pinmux_set_function(HAL_GPIO_31, function_index);
     // function_index = HAL_GPIO_32_MC0_DA0
     hal_pinmux_set_function(HAL_GPIO_32, function_index);
     // function_index = HAL_GPIO_33_MC0_DA1
     hal_pinmux_set_function(HAL_GPIO_33, function_index);
     // function_index = HAL_GPIO_34_MC0_DA2
     hal_pinmux_set_function(HAL_GPIO_34, function_index);
     // function_index = HAL_GPIO_35_MC0_DA3
     hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    void sd_dma_transfer_callback(hal_sd_callback_event_t sd_event, void *user_data)
    {
         if (HAL_SD_EVENT_SUCCESS == sd_event) {
           // DMA transfer OK.
         } else if (HAL_SD_EVENT_TRANSFER_ERROR == sd_event) {
           // DMA transfer error.
         }
         } else if (HAL_SD_EVENT_CRC_ERROR == sd_event) {
           // DMA transfer with CRC error.
         }
         } else if (HAL_SD_EVENT_DATA_TIMEOUT == sd_event) {
           // DMA transfer with timeout.
         }
     }
    
     if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
         // Error handler.
     }
    
     if (HAL_SD_STATUS_OK != hal_sd_register_callback(sd_port, sd_dma_transfer_callback,NULL)) {
          // Error handler.
     }
    
     if (HAL_SD_STATUS_OK != hal_sd_read_blocks_dma(sd_port, &read_buffer, start_address, block_number)) {
         // Error handler.
     }
    
     if (HAL_SD_STATUS_OK != hal_sd_write_blocks_dma(sd_port, &read_buffer, start_address, block_number)) {
         // Error handler.
     }

• Erase the SD/eMMC sector.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_erase_sector_size() to get the erase sector unit size.
  • Step 5. Call hal_sd_erase_sectors() to erase the SD/eMMC card.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    
    uint32_t  sector_size;
    uint32_t  sector_number;
    uint32_t  erase_size;
    uint32_t  start_sector;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    if (HAL_SD_STATUS_EARSE_DONE != hal_sd_get_erase_sector_size(sd_port, &sector_size)) {
        // Error handler.
    }
    sector_number = erase_size / sector_size;
    if (HAL_SD_STATUS_EARSE_DONE != hal_sd_erase_sectors(sd_port, start_sector, sector_number)) {
        // Error handler.
    }

• Get the SD/eMMC capacity.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_capacity() to get the SD/eMMC card capacity.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint64_t card_capacity;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_get_capacity(sd_port, &card_capacity)) {
       // Error handler.
    }

• Get the SD/eMMC CSD register value.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_csd() to get the SD/eMMC card CSD register value.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    hal_pinmux_set_function(gpio_pin, function_index);//Set the GPIO pinmux.
    uint32_t card_csd;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    if (HAL_SD_STATUS_OK != hal_sd_get_csd(sd_port, &card_csd)) {
       // Error handler.
    }

• Get the SD/eMMC CID register value.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_cid() to get the SD/eMMC card CID register value.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t card_cid;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    
    if (HAL_SD_STATUS_OK != hal_sd_get_cid(sd_port, &card_cid)) {
       // Error handler.
    }

• Get the SD/eMMC OCR register value.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_ocr() to get the SD/eMMC card OCR register value.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t card_ocr;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
     // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    
    if (HAL_SD_STATUS_OK != hal_sd_get_ocr(sd_port, &card_ocr)) {
       // Error handler.
    }

• Get the SD/eMMC card type.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_card_type() to get the SD/eMMC card OCR register value.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    hal_sd_card_type_t card_type;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    
    if (HAL_SD_STATUS_OK != hal_sd_get_card_type(sd_port, &card_type)) {
       // Error handler.
    }

• Get the SD/eMMC erase sector size.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Step 4. Call hal_sd_get_erase_sector_size() to get the SD/eMMC card OCR register value.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t erase_sector_size;
    
    sd_port = HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
       // Error handler.
    }
    
    
    if (HAL_SD_STATUS_OK != hal_sd_get_erase_sector_size(sd_port, &erase_sector_size)) {
       // Error handler.
    }

• Retry mechanism is used for read from or write to the SD/eMMC in the DMA mode.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API again if init fail and the retry times is less than 3.
  • Step 4. Call hal_sd_read_blocks_dma() to read the SD/eMMC card data. Call this API again if read fail and the retry times is less than 3.
  • Step 5. Call hal_sd_write_blocks_dma() to write data to the SD/eMMC card. Call this API again if write fail and the retry times is less than 3.
  • Sample code:

    hal_sd_port_t sd_port;
    hal_sd_config_t sd_config;
    uint32_t read_buffer;
    uint32_t write_buffer;
    uint32_t start_address;
    uint32_t block_number;
    uint32_t retry;
    
    sd_port=HAL_SD_PORT_0;
    sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
    // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
    sd_config.clock=45000;
    
    // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    hal_gpio_init(HAL_GPIO_33);
    hal_gpio_init(HAL_GPIO_34);
    hal_gpio_init(HAL_GPIO_35);
    
    // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
    // No need to configure the pinmux, if EPT is used.
    // function_index = HAL_GPIO_30_MC0_CK
    hal_pinmux_set_function(HAL_GPIO_30, function_index);
    // function_index = HAL_GPIO_31_MC0_CM0
    hal_pinmux_set_function(HAL_GPIO_31, function_index);
    // function_index = HAL_GPIO_32_MC0_DA0
    hal_pinmux_set_function(HAL_GPIO_32, function_index);
    // function_index = HAL_GPIO_33_MC0_DA1
    hal_pinmux_set_function(HAL_GPIO_33, function_index);
    // function_index = HAL_GPIO_34_MC0_DA2
    hal_pinmux_set_function(HAL_GPIO_34, function_index);
    // function_index = HAL_GPIO_35_MC0_DA3
    hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    retry = 0;
    while (retry < 3) {
        if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
            retry++;
        } else {
            break;
        }
    }
    
    if (3 <= retry) {
        // Error handler.
    }
    
    retry = 0;
    while (retry < 3) {
        if (HAL_SD_STATUS_OK != hal_sd_read_blocks_dma(sd_port, &read_buffer, start_address, block_number)) {
            // Error handler.
        } else {
            break;
        }
    }
    
    if (3 <= retry) {
        //Error handler.
    }
    
    retry = 0;
    while (retry < 3) {
        if (HAL_SD_STATUS_OK != hal_sd_write_blocks_dma(sd_port, &read_buffer, start_address, block_number)) {
            // Error handler.
        } else {
            break;
        }
    }
    
    if (3 <= retry) {
        // Error handler.
    }

• Register the SD card detection callback.
  
  • Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
  • Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux if the EPT is not in use.
  • Step 3. Call hal_sd_register_card_detection_callback() to register the SD card detection callback.
  • Step 4. Call hal_sd_init() to initialize the MSDC and the SD/eMMC card transfer states. Call this API only once.
  • Sample code:

      hal_sd_port_t sd_port;
      hal_sd_config_t sd_config;
    
      sd_port = HAL_SD_PORT_0;
      sd_config.bus_width=HAL_SD_BUS_WIDTH_4;
      // Set the output clock. The output clock is recommended set to to 45000kHz and no need to modify.
      sd_config.clock=45000;
    
      // Initialize the GPIO, set GPIO pinmux(if EPT tool hasn't been used to configure the related pinmux).
      hal_gpio_init(HAL_GPIO_30);
      hal_gpio_init(HAL_GPIO_31);
      hal_gpio_init(HAL_GPIO_32);
      hal_gpio_init(HAL_GPIO_33);
      hal_gpio_init(HAL_GPIO_34);
      hal_gpio_init(HAL_GPIO_35);
    
      // Call hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
      // No need to configure the pinmux, if EPT is used.
      // function_index = HAL_GPIO_30_MC0_CK
      hal_pinmux_set_function(HAL_GPIO_30, function_index);
      // function_index = HAL_GPIO_31_MC0_CM0
      hal_pinmux_set_function(HAL_GPIO_31, function_index);
      // function_index = HAL_GPIO_32_MC0_DA0
      hal_pinmux_set_function(HAL_GPIO_32, function_index);
      // function_index = HAL_GPIO_33_MC0_DA1
      hal_pinmux_set_function(HAL_GPIO_33, function_index);
      // function_index = HAL_GPIO_34_MC0_DA2
      hal_pinmux_set_function(HAL_GPIO_34, function_index);
      // function_index = HAL_GPIO_35_MC0_DA3
      hal_pinmux_set_function(HAL_GPIO_35, function_index);
    
    void sd_detection_callback(hal_sd_card_event_t sd_detection_event, void *user_data)
    {
         if (HAL_SD_EVENT_CARD_INSERTED == sd_detection_event) {
            // Card insert handler.
         } else if (HAL_SD_EVENT_CARD_REMOVED == sd_detection_event) {
            // Card remove handler.
         }
     }
    
    
      if (HAL_SD_STATUS_OK != hal_sd_register_card_detection_callback(sd_port, sd_detection_callback, NULL)) {
         // Error handler.
      }
    
    
      if (HAL_SD_STATUS_OK != hal_sd_init(sd_port, &sd_config)) {
         // Error handler.
      }

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 to erase. 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_blocking (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 blocking mode. More...
hal_sd_status_t	hal_sd_write_blocks_dma_blocking (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 blocking 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...
hal_sd_status_t	hal_sd_register_callback (hal_sd_port_t sd_port, hal_sd_callback_t sd_callback, void *user_data)
	This function registers a callback function to transfer data with DMA. More...
hal_sd_status_t	hal_sd_read_blocks_dma (hal_sd_port_t sd_port, uint32_t *read_buffer, uint32_t read_address, uint32_t block_number)
	This function reads data from the SD/eMMC card in the DMA interrupt mode. More...
hal_sd_status_t	hal_sd_write_blocks_dma (hal_sd_port_t sd_port, const uint32_t *write_buffer, uint32_t write_address, uint32_t block_number)
	This function writes data to the SD/eMMC card in the DMA interrupt mode. 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_port

is 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_port	is the MSDC port to erase the card sectors.
[in]	start_sector	is the start address of a sector on the SD/eMMC card to erase.
[in]	sector_number	is 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_port	is the MSDC port to get the card capacity.
[out]	capacity	is 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_port	is the MSDC port to get the card status.
[out]	card_status	is 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_port	is the MSDC port to get the card type.
[out]	card_type	is 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_port	is the MSDC port to get the CID register value.
[out]	cid	is 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_port	is the MSDC port to get the clock.
[out]	clock	is 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_port	is the MSDC port to get the CSD register value.
[out]	csd	is 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 to erase.

Parameters

[in]	sd_port	is the MSDC port to get the sector size.
[out]	erase_sector_size	is 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_port	is the MSDC port to get the OCR register value.
[out]	ocr	is 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 to set to 45000kHz, no need to modify.

Parameters

[in]	sd_port	is the initialization configuration port. For more details about this parameter, please refer to hal_sd_port_t.
[in]	sd_config	is 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. If the return value is HAL_SD_STATUS_OK,the call succeeded, else the initialization has 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.

This API is recommended when each transmission is less than or equal to 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to read.
[out]	read_buffer	is the address to store the data read from the card.
[in]	start_address	is the start address on the SD/eMMC card to read from.
[in]	block_number	is 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	read_address,
		uint32_t	block_number
	)

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

This API will not block the application task. This API is recommended when each transmission is greater than 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to read.
[out]	read_buffer	is the address to store data read from the card. The address must be a noncacheable and 4 bytes aligned address.
[in]	start_address	is the read start address of the SD/eMMC card.
[in]	block_number	is 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_blocking	(	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 blocking mode.

This API may block the application task. This API is recommended when each transmission is greater than 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to read.
[out]	read_buffer	is the address to store data read from the card. The address must be a noncacheable and 4 bytes aligned address.
[in]	start_address	is the read start address of the SD/eMMC card.
[in]	block_number	is 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_callback	(	hal_sd_port_t	sd_port,
		hal_sd_callback_t	sd_callback,
		void *	user_data
	)

This function registers a callback function to transfer data with DMA.

Parameters

[in]	sd_port	is the MSDC port to transfer data
[in]	hal_sd_callback_t	is the function pointer of the callback. The callback function is called once the SD/eMMC data transfer done.
[in]	user_data	is the callback parameter.

Returns

HAL_SD_STATUS_OK, if the operation completed successfully.

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_port	is the MSDC port to detect a card.
[in]	sd_callback	is a pointer to the callback function. The callback function is called once the SD/eMMC card is inserted or plugged out.
[in]	user_data	is 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_port	is the MSDC port to be set.
[in]	bus_width	is 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_port	is the MSDC port to set the clock.
[in]	clock	is 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.

This API is recommended when each transmission is less than or equal to 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to write.
[in]	write_data	is the address to store the data that will be written.
[in]	start_address	is the start address on the SD/eMMC card to write into.
[in]	block_number	is 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_buffer,
		uint32_t	write_address,
		uint32_t	block_number
	)

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

This API will not block the application task. This API is recommended when each transmission is greater than 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to write.
[in]	write_data	is the address to store the data that will be written, the address must be a noncacheable and 4 bytes aligned address.
[in]	start_address	is the start address on the SD/eMMC card to write into.
[in]	block_number	is 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.

hal_sd_status_t hal_sd_write_blocks_dma_blocking	(	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 blocking mode.

This API may block the application task. This API is recommended when each transmission is greater than 2 blocks.

Parameters

[in]	sd_port	is the MSDC port to write.
[in]	write_data	is the address to store the data that will be written, the address must be a noncacheable and 4 bytes aligned address.
[in]	start_address	is the start address on the SD/eMMC card to write into.
[in]	block_number	is 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.