PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Data Structures | Enumerations | Functions
SDHC (SD Host Controller)
HAL API Reference » HAL Drivers

## General Description

High level interface to the Secure Digital Host Controller (SDHC).

The SDHC driver allows data to be read from and written to an SD Card using the SDHC block. The data is transferred in blocks with a block size of 512 bytes.

# Features

- Supports the 4-bit interface
- Supports Ultra High Speed (UHS-I) mode
- Supports Default Speed (DS), High Speed (HS), SDR12, SDR25 and SDR50 speed modes

# Quick Start

Initialize SDHC by using Device Configurator and selecting the pins according to the target device used. Specify the SDHC configuration using the configuration structure (const mtb_hal_sdhc_configurator_t * config).
See Snippet 1: SDHC Initialization and configuration

# Code Snippets

## Snippet 1: SDHC Initialization and configuration

The following snippet is used to initialize the SDHC block. SDHC object - mtb_hal_sdhc_t, SDHC card configuration structure (const mtb_hal_sdhc_config_t * config). The pins connected to the SDHC block needs to be provided by the design.modus file after using Device Configurator.

cy_rslt_t rslt = CY_RSLT_SUCCESS;
mtb_hal_sdhc_t sdhc_object;
cy_stc_sd_host_context_t sdhc_context;
// Use PDL to configure SDHC hardware
(void)Cy_SD_Host_Enable(SDHC_sdhc_hal_config.base);
// Configure interrupt handling
cy_stc_sysint_t intr_cfg_1 = { .intrSrc = SDHC_IRQ, .intrPriority = 7u }; // SDHC_IRQ generated
// through device
// configurator
Cy_SysInt_Init(&intr_cfg_1, my_sdhc_interrupt_handler); // User implements interrupt handler
NVIC_EnableIRQ(SDHC_IRQ);
// Continue using PDL for SDHC hardware configuration
if (rslt == CY_RSLT_SUCCESS)
{
rslt = (cy_rslt_t)Cy_SD_Host_Init(SDHC_sdhc_hal_config.base,
SDHC_sdhc_hal_config.host_config, &sdhc_context);
}
if (rslt == CY_RSLT_SUCCESS)
{
rslt = (cy_rslt_t)Cy_SD_Host_InitCard(SDHC_sdhc_hal_config.base,
SDHC_sdhc_hal_config.card_config, &sdhc_context);
}
// Set up our SDHC HAL object
rslt = mtb_hal_sdhc_setup(&sdhc_object, &SDHC_sdhc_hal_config, NULL, &sdhc_context);
mtb_hal_sdhc_t
SDHC object.
Definition: mtb_hal_hw_types_sdhc_mxsdhc.h:53
mtb_hal_sdhc_setup
cy_rslt_t mtb_hal_sdhc_setup(mtb_hal_sdhc_t *obj, const mtb_hal_sdhc_configurator_t *config, const mtb_hal_clock_t *clock, cy_stc_sd_host_context_t *sdhc_host_context)
Sets up a HAL instance to use the specified hardware resource.
Definition: mtb_hal_sdhc.c:886
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486
cy_stc_sd_host_context_t
Context structure.
Definition: cy_sd_host.h:1401
Cy_SD_Host_InitCard
cy_en_sd_host_status_t Cy_SD_Host_InitCard(SDHC_Type *base, cy_stc_sd_host_sd_card_config_t *config, cy_stc_sd_host_context_t *context)
Initializes a card if it is connected.
Definition: cy_sd_host.c:653
Cy_SD_Host_Init
cy_en_sd_host_status_t Cy_SD_Host_Init(SDHC_Type *base, const cy_stc_sd_host_init_config_t *config, cy_stc_sd_host_context_t *context)
Initializes the SD host module.
Definition: cy_sd_host.c:2950
Cy_SD_Host_Enable
void Cy_SD_Host_Enable(SDHC_Type *base)
Enables the SD host block.
Definition: cy_sd_host.c:4275
cy_stc_sysint_t::intrSrc
IRQn_Type intrSrc
Interrupt source.
Definition: cy_sysint.h:229
cy_stc_sysint_t
Initialization configuration structure for a single interrupt channel.
Definition: cy_sysint.h:227
Cy_SysInt_Init
cy_en_sysint_status_t Cy_SysInt_Init(const cy_stc_sysint_t *config, cy_israddress userIsr)
Initializes the referenced interrupt by setting the priority and the interrupt vector.
Definition: cy_sysint_v2.c:80

## Snippet 2: Reading a block of data from an SD Card

The following snippet reads a block of data from the SD Card. The setup steps from Snippet 1: SDHC Initialization and configuration must be followed before reading.

#define DEFAULT_BLOCKSIZE 512
// Data buffer to store the data read from the SD Card
uint8_t read_buff[DEFAULT_BLOCKSIZE] = { 0 };
// Starting block address from which the data needs to be read
uint32_t block_address = 0;
// Number of blocks that needs to be read
size_t block_count = 1;
// Call to make the asynchronous read
rslt = mtb_hal_sdhc_read_async(&sdhc_obj, block_address, read_buff, &block_count);
mtb_hal_sdhc_read_async
cy_rslt_t mtb_hal_sdhc_read_async(mtb_hal_sdhc_t *obj, uint32_t address, uint8_t *data, size_t *length)
Start SDHC asynchronous read.
Definition: mtb_hal_sdhc.c:1103

## Snippet 3: Writing a block of data to an SD Card

The following snippet writes a block of data to the SD Card. The setup steps from Snippet 1: SDHC Initialization and configuration must be followed before writing.

#define DEFAULT_BLOCKSIZE 512
// Number of bytes of data to be written into the SD Card
#define DATA_BYTE_COUNT (2 * DEFAULT_BLOCKSIZE)
// Data buffer that stores the data to be written into the SD Card
uint8_t write_buff[DATA_BYTE_COUNT];
// Starting block address into which the data is to be written
uint32_t block_address = 0;
// Number of blocks that needs to be written
size_t block_count = 2;
// Generate sample data
for (int i = 0; i < DATA_BYTE_COUNT; i++)
{
write_buff[i] = i;
}
// Call to make the asynchronous write
rslt = mtb_hal_sdhc_write_async(&sdhc_obj, block_address, write_buff, &block_count);
mtb_hal_sdhc_write_async
cy_rslt_t mtb_hal_sdhc_write_async(mtb_hal_sdhc_t *obj, uint32_t address, const uint8_t *data, size_t *length)
Start asynchronous SDHC write.
Definition: mtb_hal_sdhc.c:1118

## API Reference
| SDHC HAL Results
| SDHC specific return codes.

## Data Structures
struct | mtb_hal_sdhc_config_t
| Defines configuration options for the SDHC block. More...
struct | mtb_hal_sdhc_data_config_t
| Defines data configuration. More...
struct | mtb_hal_sdhc_cmd_config_t
| Defines command configuration for mtb_hal_sdhc_send_cmd function. More...

## Enumerations
enum | mtb_hal_sdhc_card_type_t { MTB_HAL_SDHC_SD , MTB_HAL_SDHC_SDIO , MTB_HAL_SDHC_EMMC , MTB_HAL_SDHC_COMBO , MTB_HAL_SDHC_UNUSABLE , MTB_HAL_SDHC_NOT_EMMC }
| Card types. More...
enum | mtb_hal_sdhc_io_voltage_t { MTB_HAL_SDHC_IO_VOLTAGE_3_3V = 0U , MTB_HAL_SDHC_IO_VOLTAGE_1_8V = 1U }
| I/O voltage levels. More...
enum | mtb_hal_sdhc_io_volt_action_type_t { MTB_HAL_SDHC_IO_VOLT_ACTION_NEGOTIATE = 0U , MTB_HAL_SDHC_IO_VOLT_ACTION_SWITCH_SEQ_ONLY = 1U , MTB_HAL_SDHC_IO_VOLT_ACTION_NONE = 2U }
| SDHC I/O voltage select principle. More...
enum | mtb_hal_sdhc_cmd_response_type_t { MTB_HAL_SDHC_RESPONSE_NONE = 0U , MTB_HAL_SDHC_RESPONSE_LEN_136 = 1U , MTB_HAL_SDHC_RESPONSE_LEN_48 = 2U , MTB_HAL_SDHC_RESPONSE_LEN_48B = 3U }
| SDHC response types. More...
enum | mtb_hal_sdhc_auto_cmd_t { MTB_HAL_SDHC_AUTO_CMD_NONE = 0U , MTB_HAL_SDHC_AUTO_CMD_12 = 1U , MTB_HAL_SDHC_AUTO_CMD_23 = 2U , MTB_HAL_SDHC_AUTO_CMD_AUTO = 3U }
| SDHC auto command enable selection. More...
enum | mtb_hal_sdhc_cmd_type_t { MTB_HAL_SDHC_CMD_NORMAL = 0U , MTB_HAL_SDHC_CMD_SUSPEND = 1U , MTB_HAL_SDHC_CMD_RESUME = 2U , MTB_HAL_SDHC_CMD_ABORT = 3U }
| SDHC command types. More...
enum | mtb_hal_sdhc_error_type_t { MTB_HAL_SDHC_NO_ERR = 0x0000U , MTB_HAL_SDHC_CMD_TOUT_ERR = 0x0001U , MTB_HAL_SDHC_CMD_CRC_ERR = 0x0002U , MTB_HAL_SDHC_CMD_END_BIT_ERR = 0x0004U , MTB_HAL_SDHC_CMD_IDX_ERR = 0x0008U , MTB_HAL_SDHC_DATA_TOUT_ERR = 0x0010U , MTB_HAL_SDHC_DATA_CRC_ERR = 0x0020U , MTB_HAL_SDHC_DATA_END_BIT_ERR = 0x0040U , MTB_HAL_SDHC_CUR_LMT_ERR = 0x0080U , MTB_HAL_SDHC_AUTO_CMD_ERR = 0x0100U , MTB_HAL_SDHC_ADMA_ERR = 0x0200U , MTB_HAL_SDHC_TUNNING_ERR = 0x0400U , MTB_HAL_SDHC_RESP_ERR = 0x0800U , MTB_HAL_SDHC_BOOT_ACK_ERR = 0x1000U }
| SDHC command error states. More...

## Functions
cy_rslt_t | mtb_hal_sdhc_setup (mtb_hal_sdhc_t *obj, const mtb_hal_sdhc_configurator_t *config, const mtb_hal_clock_t *clock, cy_stc_sd_host_context_t *sdhc_host_context)
| Sets up a HAL instance to use the specified hardware resource. More...
cy_rslt_t | mtb_hal_sdhc_erase (mtb_hal_sdhc_t *obj, uint32_t start_addr, size_t length, uint32_t timeout_ms)
| Erases a block of data over the SDHC peripheral. More...
cy_rslt_t | mtb_hal_sdhc_read_async (mtb_hal_sdhc_t *obj, uint32_t address, uint8_t *data, size_t *length)
| Start SDHC asynchronous read. More...
cy_rslt_t | mtb_hal_sdhc_write_async (mtb_hal_sdhc_t *obj, uint32_t address, const uint8_t *data, size_t *length)
| Start asynchronous SDHC write. More...
bool | mtb_hal_sdhc_is_card_inserted (const mtb_hal_sdhc_t *obj)
| Checks if SD card is inserted. More...
bool | mtb_hal_sdhc_is_card_mech_write_protected (const mtb_hal_sdhc_t *obj)
| Checks if the inserted SD card is mechanically write protected. More...
cy_rslt_t | mtb_hal_sdhc_get_block_count (mtb_hal_sdhc_t *obj, uint32_t *block_count)
| Get block count of inserted SD card / eMMC. More...
cy_rslt_t | mtb_hal_sdhc_set_frequency (mtb_hal_sdhc_t *obj, uint32_t hz, bool negotiate)
| Sets the SD bus frequency (frequency on which SD card / eMMC is accessed) More...
uint32_t | mtb_hal_sdhc_get_frequency (mtb_hal_sdhc_t *obj)
| Get the actual frequency that SD bus is configured for. More...
cy_rslt_t | mtb_hal_sdhc_set_data_read_timeout (mtb_hal_sdhc_t *obj, uint32_t timeout, bool auto_reconfigure)
| Sets the maximum time to wait for data from the card. More...
cy_rslt_t | mtb_hal_sdhc_config_data_transfer (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_data_config_t *data_config)
| Initializes the SD block and DMA for a data transfer. More...
cy_rslt_t | mtb_hal_sdhc_send_cmd (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_cmd_config_t *cmd_config)
| Sends a command to the card and wait until it is sent. More...
cy_rslt_t | mtb_hal_sdhc_get_response (mtb_hal_sdhc_t *obj, uint32_t *response, bool large_response)
| Returns a response of last issued by mtb_hal_sdhc_send_cmd function command. More...
cy_rslt_t | mtb_hal_sdhc_wait_transfer_complete (mtb_hal_sdhc_t *obj)
| Wait for asynchronous data transfer to complete. More...
cy_rslt_t | mtb_hal_sdhc_set_io_voltage (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_io_voltage_t io_voltage, mtb_hal_sdhc_io_volt_action_type_t io_switch_type)
| Sets the voltage level of the I/O lines. More...
mtb_hal_sdhc_io_voltage_t | mtb_hal_sdhc_get_io_voltage (mtb_hal_sdhc_t *obj)
| Returns the current voltage level of the I/O lines. More...
cy_rslt_t | mtb_hal_sdhc_set_bus_width (mtb_hal_sdhc_t *obj, uint8_t bus_width, bool configure_card)
| Configures data bus width on host side and (optionally) informs the card about new width configuration. More...
uint8_t | mtb_hal_sdhc_get_bus_width (mtb_hal_sdhc_t *obj)
| Returns currently configured data bus width. More...
mtb_hal_sdhc_error_type_t | mtb_hal_sdhc_get_last_command_errors (mtb_hal_sdhc_t *obj)
| Returns last issued SD operation error states. More...
void | mtb_hal_sdhc_clear_errors (mtb_hal_sdhc_t *obj)
| Clears SDHC hardware error states. More...
void | mtb_hal_sdhc_software_reset (mtb_hal_sdhc_t *obj)
| Resets CMD and Data lines and corresponding circuits of SD Host. More...
cy_rslt_t | mtb_hal_sdhc_enable_card_power (mtb_hal_sdhc_t *obj, bool enable)
| Powers up / down the card based on provided parameter. More...
cy_rslt_t | mtb_hal_sdhc_process_interrupt (mtb_hal_sdhc_t *obj)
| Process interrupts related to an SDHC instance. More...

## Data Structure Documentation

## ◆ mtb_hal_sdhc_config_t

struct mtb_hal_sdhc_config_t

Data Fields
bool | enableLedControl | Drive one IO to indicate when the card is being accessed.
bool | lowVoltageSignaling | Whether 1.8V signaling is supported.
bool | isEmmc | true if eMMC card, otherwise false
uint8_t | busWidth | The desired bus width, 1-bit, 4-bit, 8-bit.

## ◆ mtb_hal_sdhc_data_config_t

struct mtb_hal_sdhc_data_config_t

Data Fields
uint32_t * | data_ptr | The pointer to data for send/receive. Data will be transfered using DMA, which will be configured automaticaly by SDHC HAL driver.
uint32_t | block_size | The size of the data block.
uint32_t | number_of_blocks | The number of blocks with size block_size to send. Selects which auto commands are used if any.
mtb_hal_sdhc_auto_cmd_t | auto_command |
bool | is_read | true = Read from the card,false = Write to the card.

## ◆ mtb_hal_sdhc_cmd_config_t

struct mtb_hal_sdhc_cmd_config_t

Data Fields
uint32_t | command_index | The index of the command.
uint32_t | command_argument | The argument for the command.
bool | enable_crc_check | Enables the CRC check on the response.
mtb_hal_sdhc_cmd_response_type_t | response_type | The response type.
bool | enable_idx_check | Checks the index of the response.
mtb_hal_sdhc_cmd_type_t | command_type | The command type.
mtb_hal_sdhc_data_config_t * | data_config | Data transfer configuration, defined in mtb_hal_sdhc_data_config_t. Should be NULL if data transfer is not expected for provided command.

## Enumeration Type Documentation

## ◆ mtb_hal_sdhc_card_type_t

enum mtb_hal_sdhc_card_type_t

Card types.

Enumerator
MTB_HAL_SDHC_SD | Secure Digital card.
MTB_HAL_SDHC_SDIO | SD Input Output card.
MTB_HAL_SDHC_EMMC | Embedded Multimedia card.
MTB_HAL_SDHC_COMBO | Combo Card (SD + SDIO)
MTB_HAL_SDHC_UNUSABLE | Unusable card or unsupported type.
MTB_HAL_SDHC_NOT_EMMC | Not an eMMC card.

## ◆ mtb_hal_sdhc_io_voltage_t

enum mtb_hal_sdhc_io_voltage_t

I/O voltage levels.

Enumerator
MTB_HAL_SDHC_IO_VOLTAGE_3_3V | I/O voltage is 3.3V.
MTB_HAL_SDHC_IO_VOLTAGE_1_8V | I/O voltage is 1.8V.

## ◆ mtb_hal_sdhc_io_volt_action_type_t

enum mtb_hal_sdhc_io_volt_action_type_t

SDHC I/O voltage select principle.

Enumerator
MTB_HAL_SDHC_IO_VOLT_ACTION_NEGOTIATE | (Recommended) HAL driver performs all steps, needed for switching I/O bus voltage to certain level: sends needed commands to prepare card, changes level of io_volt_sel pin and performs switching sequence according to SD specification.
MTB_HAL_SDHC_IO_VOLT_ACTION_SWITCH_SEQ_ONLY | HAL driver performs switching sequence (if voltage is being switched to 1.8V) and changes io_volt_sel pin level accordingly. No commands are being send to the card in this mode.
MTB_HAL_SDHC_IO_VOLT_ACTION_NONE | I/O voltage is changed by changing io_volt_sel pin's level. No commands are being send to the card in this mode.

## ◆ mtb_hal_sdhc_cmd_response_type_t

enum mtb_hal_sdhc_cmd_response_type_t

SDHC response types.

Enumerator
MTB_HAL_SDHC_RESPONSE_NONE | No Response.
MTB_HAL_SDHC_RESPONSE_LEN_136 | Response Length 136.
MTB_HAL_SDHC_RESPONSE_LEN_48 | Response Length 48.
MTB_HAL_SDHC_RESPONSE_LEN_48B | Response Length 48. Check Busy after response.

## ◆ mtb_hal_sdhc_auto_cmd_t

enum mtb_hal_sdhc_auto_cmd_t

SDHC auto command enable selection.

Enumerator
MTB_HAL_SDHC_AUTO_CMD_NONE | Auto command disable.
MTB_HAL_SDHC_AUTO_CMD_12 | Auto command 12 enable.
MTB_HAL_SDHC_AUTO_CMD_23 | Auto command 23 enable.
MTB_HAL_SDHC_AUTO_CMD_AUTO | Auto command Auto enable.

## ◆ mtb_hal_sdhc_cmd_type_t

enum mtb_hal_sdhc_cmd_type_t

SDHC command types.

Enumerator
MTB_HAL_SDHC_CMD_NORMAL | Other commands.
MTB_HAL_SDHC_CMD_SUSPEND | CMD52 for writing "Bus Suspend" in CCCR.
MTB_HAL_SDHC_CMD_RESUME | CMD52 for writing "Function Select" in CCCR.
MTB_HAL_SDHC_CMD_ABORT | CMD12, CMD52 for writing "I/O Abort" in CCCR.

## ◆ mtb_hal_sdhc_error_type_t

enum mtb_hal_sdhc_error_type_t

SDHC command error states.

Enumerator
MTB_HAL_SDHC_NO_ERR | Last operation did not cause any error status.
MTB_HAL_SDHC_CMD_TOUT_ERR | Command timeout error. In SD/eMMC Mode, this event is set only if no response is returned within 64 SD clock cycles from the end bit of the command. If the Host Controller detects a CMD line conflict, along with Command CRC Error bit, this event is set to 1, without waiting for 64 SD/eMMC card clock cycles.
MTB_HAL_SDHC_CMD_CRC_ERR | Command CRC error. A Command CRC Error is generated in SD/eMMC mode when: A response is returned and the Command Timeout Error is set to 0 (indicating no timeout), this bit is set to 1 when detecting a CRC error in the command response. The Host Controller detects a CMD line conflict by monitoring the CMD line when a command is issued. If the Host Controller drives the CMD line to level 1, but detects level 0 on the CMD line at the next SD clock edge, then the Host Controller aborts the command (stop driving CMD line) and sets this bit to 1. The Command Timeout Error is also set to 1 to distinguish a CMD line conflict.
MTB_HAL_SDHC_CMD_END_BIT_ERR | Command End Bit error. This bit is set after detecting that the end bit of a command response is 0 in SD/eMMC mode.
MTB_HAL_SDHC_CMD_IDX_ERR | Command Index error. This bit is set if a Command Index error occurs in the command response in SD/eMMC mode.
MTB_HAL_SDHC_DATA_TOUT_ERR | Data Timeout error. This bit is set in SD/eMMC mode when detecting one of the following timeout conditions: Busy timeout for R1b, R5b type Busy timeout after Write CRC status Write CRC Status timeout Read Data timeout.
MTB_HAL_SDHC_DATA_CRC_ERR | Data CRC error. This error occurs in SD/eMMC mode after detecting a CRC error while transferring read data that uses the DAT line, detecting the Write CRC status having a value other than 010 or when writing a CRC status timeout.
MTB_HAL_SDHC_DATA_END_BIT_ERR | Data End Bit error. This error occurs in SD/eMMC mode either when detecting 0 at the end bit position of read data that uses the DAT line or at the end bit position of the CRC status.
MTB_HAL_SDHC_CUR_LMT_ERR | Current Limit error.
MTB_HAL_SDHC_AUTO_CMD_ERR | Auto CMD error. This error status is used by Auto CMD12 and Auto CMD23 in SD/eMMC mode. This bit is set after detecting that any of the bits D00 to D05 in the Auto CMD Error Status register has changed from 0 to 1. D07 is effective in case for Auto CMD12. The Auto CMD Error Status register is valid while this bit is set to 1 and may be cleared by clearing this bit.
MTB_HAL_SDHC_ADMA_ERR | ADMA error. This bit is set when the Host Controller detects an error during an ADMA-based data transfer. The possible reasons for an error: An error response is received from the System bus; ADMA3, ADMA2 Descriptors are invalid; CQE Task or Transfer descriptors are invalid. When an error occurs, the state of the ADMA is saved in the ADMA Error Status register.
MTB_HAL_SDHC_TUNNING_ERR | Tuning error.
MTB_HAL_SDHC_RESP_ERR | Response error. Host Controller Version 4.00 supports the response error check function to avoid overhead of the response error check by Host Driver during DMA execution. If the Response Error Check Enable is set to 1 in the Transfer Mode register, the Host Controller checks R1 or R5 response. If an error is detected in a response, this bit is set to 1. This is applicable in SD/eMMC mode.
MTB_HAL_SDHC_BOOT_ACK_ERR | Boot Acknowledgement error. This bit is set when there is a timeout for boot acknowledgement or after detecting the boot ACK status having a value other than 010. This is applicable only when boot acknowledgement is expected in eMMC mode.

## Function Documentation

## ◆ mtb_hal_sdhc_setup()

cy_rslt_t mtb_hal_sdhc_setup | ( | mtb_hal_sdhc_t * | obj,
|  | const mtb_hal_sdhc_configurator_t * | config,
|  | const mtb_hal_clock_t * | clock,
|  | cy_stc_sd_host_context_t * | sdhc_host_context
| ) |  |

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

  [out] | obj | The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
  [in] | config | The configurator-generated HAL config structure for this peripheral instance
  [in] | clock | The HAL clock object that is connected to this peripheral instance
  [in] | sdhc_host_context | The context for the sdhc instance allocated by the user

Returns
  the status of the HAL setup

## ◆ mtb_hal_sdhc_erase()

cy_rslt_t mtb_hal_sdhc_erase | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t | start_addr,
|  | size_t | length,
|  | uint32_t | timeout_ms
| ) |  |

Erases a block of data over the SDHC peripheral.

Parameters

  [in] | obj | The SDHC object
  [in] | start_addr | Is the address of the first byte to erase
  [in] | length | Number of 512 byte blocks (starting at start_addr) to erase
  [in] | timeout_ms | Timeout value in ms for waiting/polling operations. If zero is provided for this parameter the default value will be used. See implementation specific documentation for timeout details.

Returns
  The status of the erase request

## ◆ mtb_hal_sdhc_read_async()

cy_rslt_t mtb_hal_sdhc_read_async | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t | address,
|  | uint8_t * | data,
|  | size_t * | length
| ) |  |

Start SDHC asynchronous read.

This will transfer `length` 512 byte blocks into the buffer pointed to by `data` in the background. When the requested quantity of data has been read, the mtb_hal_sdhc_wait_transfer_complete function returns true.

Parameters

  [in] | obj | The SDHC object that holds the transfer information
  [in] | address | The address to read data from
  [out] | data | The receive buffer
  [in,out] | length | Number of 512 byte blocks to read, updated with the number actually read

Returns
  The status of the read_async request

## ◆ mtb_hal_sdhc_write_async()

cy_rslt_t mtb_hal_sdhc_write_async | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t | address,
|  | const uint8_t * | data,
|  | size_t * | length
| ) |  |

Start asynchronous SDHC write.

This will transfer `length` 512 byte blocks from the buffer pointed to by `data` in the background. When the requested quantity of data has been written, the mtb_hal_sdhc_wait_transfer_complete function returns true.

Parameters

  [in] | obj | The SDHC object that holds the transfer information
  [in] | address | The address to write data to
  [in] | data | The transmit buffer
  [in,out] | length | The number of 512 byte blocks to write, updated with the number actually written

Returns
  The status of the write_async request

## ◆ mtb_hal_sdhc_is_card_inserted()

bool mtb_hal_sdhc_is_card_inserted | ( | const mtb_hal_sdhc_t * | obj | ) |

Checks if SD card is inserted.

Parameters

  [in] | obj | The SDHC peripheral to check

Returns
  Indication of whether the card is inserted.

## ◆ mtb_hal_sdhc_is_card_mech_write_protected()

bool mtb_hal_sdhc_is_card_mech_write_protected | ( | const mtb_hal_sdhc_t * | obj | ) |

Checks if the inserted SD card is mechanically write protected.

Parameters

  [in] | obj | The SDHC peripheral to check

Returns
  Indication of whether the inserted SD card is mechanically write protected

## ◆ mtb_hal_sdhc_get_block_count()

cy_rslt_t mtb_hal_sdhc_get_block_count | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t * | block_count
| ) |  |

Get block count of inserted SD card / eMMC.

Note
  SDHC driver should be initialized prior to using this function.

Parameters

  [in] | obj | The SDHC object
  [in] | block_count | Pointer to variable where block count will be stored

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_set_frequency()

cy_rslt_t mtb_hal_sdhc_set_frequency | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t | hz,
|  | bool | negotiate
| ) |  |

Sets the SD bus frequency (frequency on which SD card / eMMC is accessed)

Note
  Actual frequency may differ from the desired frequency due to available dividers and the frequency of source clock. Function will set the closest possible (but not greater than) frequency to what was requested. Use mtb_hal_sdhc_get_frequency function to get actual frequency value that was achieved and set.
  If data timeout was configured by mtb_hal_sdhc_set_data_read_timeout, it can be automaticaly recalculated according to new SD bus frequency. For details, please refer to mtb_hal_sdhc_set_data_read_timeout function description.

Parameters

  [in] | obj | The SDHC object
  [in] | hz | Desired SD bus frequency in Hz
  [in] | negotiate | Whether new frequency value needs to be negotiated with card or not. true is recommended and it means that new frequency will be negotiated.

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_get_frequency()

uint32_t mtb_hal_sdhc_get_frequency | ( | mtb_hal_sdhc_t * | obj | ) |

Get the actual frequency that SD bus is configured for.

Parameters

  [in] | obj | The SDHC object

Returns
  Frequency in Hz

## ◆ mtb_hal_sdhc_set_data_read_timeout()

cy_rslt_t mtb_hal_sdhc_set_data_read_timeout | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t | timeout,
|  | bool | auto_reconfigure
| ) |  |

Sets the maximum time to wait for data from the card.

The time is specified in number of card clock cycles. With SD bus frequency changed by mtb_hal_sdhc_set_frequency, timeout can automaticaly be recalculated according to new clock frequency. This can be activated by 'auto_reconfigure' parameter.

Parameters

  [in] | obj | The SDHC object
  [in] | timeout | Time to wait for data from the card.
  [in] | auto_reconfigure | Timeout value will be automaticaly reconfigured upon clock change

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_config_data_transfer()

cy_rslt_t mtb_hal_sdhc_config_data_transfer | ( | mtb_hal_sdhc_t * | obj,
|  | mtb_hal_sdhc_data_config_t * | data_config
| ) |  |

Initializes the SD block and DMA for a data transfer.

It does not start a transfer. mtb_hal_sdhc_send_cmd needs to be called after this function in order to start data transfer.

Parameters

  [in] | obj | The SDHC object
  [in] | data_config | Data transfer configuration

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_send_cmd()

cy_rslt_t mtb_hal_sdhc_send_cmd | ( | mtb_hal_sdhc_t * | obj,
|  | mtb_hal_sdhc_cmd_config_t * | cmd_config
| ) |  |

Sends a command to the card and wait until it is sent.

If the command assumes data transfer via data lines, mtb_hal_sdhc_config_data_transfer function needs to be called prior to this one. The response of issued command can be retrieved by using mtb_hal_sdhc_get_response function.

Note
  Function does not wait until data (configured with mtb_hal_sdhc_config_data_transfer) transfer complete. In order to do so, user can use the mtb_hal_sdhc_wait_transfer_complete function

Parameters

  [in] | obj | The SDHC object
  [in] | cmd_config | Command configuration

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_get_response()

cy_rslt_t mtb_hal_sdhc_get_response | ( | mtb_hal_sdhc_t * | obj,
|  | uint32_t * | response,
|  | bool | large_response
| ) |  |

Returns a response of last issued by mtb_hal_sdhc_send_cmd function command.

Parameters

  [in] | obj | The SDHC object
  [in] | response | Pointer to array where response will be stored
  [in] | large_response | If true, the expected response is 136 bits, false - 48 bits, which correspond to 120 and 32 bits of useful for application data respectively. So for large_response a 4 uint32_t element array can be used while for not large_response 1 uint32_t value will be enough.

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_wait_transfer_complete()

cy_rslt_t mtb_hal_sdhc_wait_transfer_complete | ( | mtb_hal_sdhc_t * | obj | ) |

Wait for asynchronous data transfer to complete.

Such data transfer can be triggered by mtb_hal_sdhc_write_async, mtb_hal_sdhc_read_async or by mtb_hal_sdhc_config_data_transfer + mtb_hal_sdhc_send_cmd functions.

Parameters

  [in] | obj | The SDHC object

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_set_io_voltage()

cy_rslt_t mtb_hal_sdhc_set_io_voltage | ( | mtb_hal_sdhc_t * | obj,
|  | mtb_hal_sdhc_io_voltage_t | io_voltage,
|  | mtb_hal_sdhc_io_volt_action_type_t | io_switch_type
| ) |  |

Sets the voltage level of the I/O lines.

Note
  This function requires io_volt_sel and (for some cases) card_pwr_en pins to be assigned. Please refer to the device datasheet and PDL documentation for details.
  Switching from 1.8V to 3.3V can be done only via power cycle sequence (power down card, wait, power up card), which is supported by HAL driver and performed only if MTB_HAL_SDHC_IO_VOLT_ACTION_NEGOTIATE selected. card_pwr_en pin has to be assigned. Please refer to the PDL documentation for details.

Parameters

  [in] | obj | The SDHC object
  [in] | io_voltage | I/O voltage to be set on lines
  [in] | io_switch_type | Defines how I/O voltage will be switched

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_get_io_voltage()

mtb_hal_sdhc_io_voltage_t mtb_hal_sdhc_get_io_voltage | ( | mtb_hal_sdhc_t * | obj | ) |

Returns the current voltage level of the I/O lines.

Parameters

  [in] | obj | The SDHC object

Returns
  Current I/O voltage setting value

## ◆ mtb_hal_sdhc_set_bus_width()

cy_rslt_t mtb_hal_sdhc_set_bus_width | ( | mtb_hal_sdhc_t * | obj,
|  | uint8_t | bus_width,
|  | bool | configure_card
| ) |  |

Configures data bus width on host side and (optionally) informs the card about new width configuration.

Parameters

  [in] | obj | The SDHC object
  [in] | bus_width | The desired bus width, 1-bit, 4-bit, 8-bit
  [in] | configure_card | Whether card needs to be configured with new bus width. true is recommended.

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_get_bus_width()

uint8_t mtb_hal_sdhc_get_bus_width | ( | mtb_hal_sdhc_t * | obj | ) |

Returns currently configured data bus width.

Parameters

  [in] | obj | The SDHC object

Returns
  Currently configured bus width, 1-bit, 4-bit, 8-bit

## ◆ mtb_hal_sdhc_get_last_command_errors()

mtb_hal_sdhc_error_type_t mtb_hal_sdhc_get_last_command_errors | ( | mtb_hal_sdhc_t * | obj | ) |

Returns last issued SD operation error states.

This function can be used for error checking after any of cmd / data transfer-related operations. For list of possible errors, that are being tracked, please refer to mtb_hal_sdhc_error_type_t.

Parameters

  [in] | obj | The SDHC object

Returns
  Errors occurred during last command

## ◆ mtb_hal_sdhc_clear_errors()

void mtb_hal_sdhc_clear_errors | ( | mtb_hal_sdhc_t * | obj | ) |

Clears SDHC hardware error states.

Error statuses are indicated by mtb_hal_sdhc_get_last_command_errors function.

Parameters

  [in] | obj | The SDHC object

## ◆ mtb_hal_sdhc_software_reset()

void mtb_hal_sdhc_software_reset | ( | mtb_hal_sdhc_t * | obj | ) |

Resets CMD and Data lines and corresponding circuits of SD Host.

Parameters

  [in] | obj | The SDHC object

## ◆ mtb_hal_sdhc_enable_card_power()

cy_rslt_t mtb_hal_sdhc_enable_card_power | ( | mtb_hal_sdhc_t * | obj,
|  | bool | enable
| ) |  |

Powers up / down the card based on provided parameter.

This function uses card_pwr_en pin to change card power state. Please refer to the device datasheet for pin description.

Parameters

  [in] | obj | The SDHC peripheral to configure
  [in] | enable | Card is powered if true, not powered if false.

Returns
  The status of the operation

## ◆ mtb_hal_sdhc_process_interrupt()

cy_rslt_t mtb_hal_sdhc_process_interrupt | ( | mtb_hal_sdhc_t * | obj | ) |

Process interrupts related to an SDHC instance.

Parameters

  obj | HAL object for which the interrupt should be processed

Returns
  CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error