SD Card & SDIO¶

Hardware SD host, SDIO, and the PIO-based SD host.

hal_sdh.h¶

#include "hal_sdh.h" (Source)

SD card / eMMC driver on the SDH controller: card initialization, block read and write, erase and eMMC partition helpers.

Typical sequence: optionally call SDH_ClockSet(), then SDH_Init() with a caller-owned sd_card_t, then move 512-byte blocks with SDH_ReadMultiBlocks() and SDH_WriteMultiBlocks(). Block addresses passed to this API are always in 512-byte block units; for byte-addressed (SDSC) cards the driver converts them to byte addresses.

SDH_Init() keeps a pointer to the sd_card_t it is given, and the other functions use it, so that structure must stay valid while the card is in use. The functions busy-poll the controller and use static transfer descriptors: they are blocking and not reentrant, so serialize calls made from several tasks.

The header also provides the SD/MMC protocol constants used by the driver (command indexes, R1 card-status bits, EXT_CSD field offsets) and the status codes (status_t) that the SDIO host stack in hal_sdio.h extends.

SDH_ClockSet¶

status_t SDH_ClockSet(uint32_t clockInit, uint32_t clockSrc, uint32_t clockTransfer, SD_ID_Type sdId);

Set the clocks used by the next SDH_Init() or MMC_BootMode_Init().

Only stores the values; they take effect when the controller is next configured. Defaults: 400 kHz identification clock, 96 MHz source clock, 48 MHz transfer clock. No range check is done.

Returns: Always Status_Success.

SDH_Init¶

status_t SDH_Init(uint32_t bus_wide, sd_card_t *pOutCardInfo, SD_ID_Type sdId);

Reset the SDH controller and initialize the inserted SD card or eMMC device.

Resets and ungates the SDH peripheral, starts the bus in 1-bit mode at the identification clock and runs the SD initialization sequence (CMD0, CMD8, ACMD41, CMD2, CMD3, CMD9, CMD7, ACMD51, a best-effort CMD6 high-speed switch, CMD16, ACMD6, ACMD13); the bus then runs at the transfer clock. A card that does not answer CMD8 is treated as eMMC (CMD1, CMD2, CMD3, CMD9, CMD7, CMD8 SEND_EXT_CSD); see EMMC_HIGHSPEED_MODE for the eMMC bus mode. SD cards that do not answer CMD8 (Physical Layer v1.x) are therefore not supported.

Returns: Status_Success when the card is initialized; Status_InvalidArgument if pOutCardInfo is NULL; Status_SDH_SDIO_InvalidCard if neither the SD nor the eMMC sequence succeeded; otherwise the _sdmmc_status code of the step that failed (for example Status_SDH_GoIdleFailed or Status_SDH_SendCsdFailed).

SD_Erase¶

status_t SD_Erase(uint32_t startaddr, uint32_t endaddr, SD_ID_Type sdId);

Erase a range of blocks on an SD card and wait until the card is done.

Sends CMD32, CMD33 and CMD38, then polls the card state with CMD13 while it reports the programming or receiving state (no timeout). Intended for SD cards: eMMC devices use CMD35/CMD36 instead, which this function does not send. Call after SDH_Init().

SDH_ReadMultiBlocks¶

status_t SDH_ReadMultiBlocks(uint8_t *readbuff, uint32_t ReadAddr, uint16_t BlockSize, uint32_t NumberOfBlocks, SD_ID_Type sdId);

Read blocks from the card with ADMA2 and wait for completion.

Uses CMD17 for one block or CMD18 for several, ended with auto CMD23 when the card supports it (SD_SupportSetBlockCountCmd) or auto CMD12 otherwise. The data cache is cleaned and invalidated over the buffer before the transfer. Call after SDH_Init().

SDH_WriteMultiBlocks¶

status_t SDH_WriteMultiBlocks(const uint8_t *writebuff, uint32_t WriteAddr, uint16_t BlockSize, uint32_t NumberOfBlocks, SD_ID_Type sdId);

Write blocks to the card with ADMA2 and wait until the card is no longer busy.

Uses CMD24 for one block or CMD25 for several, ended with auto CMD23 when the card supports it or auto CMD12 otherwise. On an eMMC device with reliable write enabled (EMMC_SetRelWR()) and supported (EXT_CSD_WR_REL_PARAM_EN), the blocks are written as a reliable write. The data cache is cleaned over the buffer before the transfer. After the data phase the function waits, without a timeout, until the card releases DAT0. Call after SDH_Init().

SDH_ReadMultiBlocksBlocking¶

status_t SDH_ReadMultiBlocksBlocking(uint8_t *readbuff, uint32_t ReadAddr, uint16_t BlockSize, uint32_t NumberOfBlocks, SD_ID_Type sdId);

Read blocks using the low-level blocking transfer of the SDH driver.

Same commands and addressing as SDH_ReadMultiBlocks(); the data cache is cleaned and invalidated over the buffer before the transfer. Any command or data failure, including a timeout, is reported as Status_SDH_TransferFailed. Call after SDH_Init().

SDH_WriteMultiBlocksBlocking¶

status_t SDH_WriteMultiBlocksBlocking(uint8_t *writebuff, uint32_t WriteAddr, uint16_t BlockSize, uint32_t NumberOfBlocks, SD_ID_Type sdId);

Write blocks using the low-level blocking transfer of the SDH driver.

Same commands and addressing as SDH_WriteMultiBlocks(), without reliable write. Any command or data failure, including a timeout, is reported as Status_SDH_TransferFailed. Call after SDH_Init().

MMC_SwitchPartition¶

void MMC_SwitchPartition(int part, SD_ID_Type sdId);

Select the eMMC partition that later block accesses address.

Writes part to the EXT_CSD PARTITION_CONFIG byte with CMD6 (write-byte access) and then re-reads EXT_CSD into the sd_card_t registered by SDH_Init(). eMMC only; call after SDH_Init(). A failure is only reported on the console.

MMC_BootMode_Init¶

status_t MMC_BootMode_Init(void *data, uint32_t data_len, SD_ID_Type sdId);

Read eMMC boot data with the controller's boot-mode transfer.

Resets the SDH controller, configures it in 1-bit mode at the transfer clock set by SDH_ClockSet(), puts the device in pre-idle state (CMD0 with argument 0xF0F0F0F0) and starts a boot data transfer into data with ADMA2. Unlike SDH_Init(), it does not reset or ungate the SDH peripheral in GLB, and no data-cache maintenance is done on data.

Returns: Status_Success when the controller reports boot done, Status_Fail on a command error. If setting up the DMA descriptors or the data transfer fails, the low-level driver status (an SDH_Stat_Type value) is returned instead.

EMMC_SetRelWR¶

void EMMC_SetRelWR(int enable, SD_ID_Type sdId);

Enable or disable reliable write for SDH_WriteMultiBlocks() on eMMC.

Stores the setting in the sd_card_t registered by SDH_Init(), so call it after SDH_Init(). It takes effect only on eMMC devices whose EXT_CSD WR_REL_PARAM has EXT_CSD_WR_REL_PARAM_EN set; SDH_WriteMultiBlocksBlocking() ignores it.

SD_Error¶

Internal transfer wait states of the driver.

SD_OK has the value 0, the same as Status_Success, so a status_t result can also be compared against SD_OK.

_status_groups¶

Status group numbers.

_generic_status¶

Generic status return codes.

_sdmmc_status¶

SD/MMC card API's running status.

SDTransferState¶

SDIO Transfer state (not used by this driver).

SDCardState¶

SD card states: the CURRENT_STATE field, bits [12:9] of the R1 card status, plus a driver-defined error value.

_sd_ocr_flag¶

OCR register in SD card.

_sd_card_flag¶

SD card flags, stored in sd_card_t::flags.

_sd_card_type¶

Card type, stored in sd_card_t::type.

_sd_scr_flag¶

SD card SCR register flags.

sd_group_num¶

SD CMD6 (SWITCH_FUNC) function group, numbered from 0.

sd_timing_mode_t¶

SD card timing mode flags.

_sd_specification_version¶

SD card specification version number, stored in sd_card_t::version.

sd_switch_mode_t¶

SD card switch mode.

mmc_switch_mode_t¶

Access mode of the MMC CMD6 (SWITCH) argument, bits [25:24].

SD_CSD¶

Card Specific Data: CSD register, field-per-member layout.

Not filled by this driver; the decoded CSD is in sd_csd_t.

SD_CID¶

Card Identification Data: CID register, field-per-member layout.

Not filled by this driver; the decoded CID is in sd_cid_t.

SD_CardStatus¶

SD Status register (ACMD13), field-per-member layout.

Not filled by this driver; see sd_ssr_t and sd_card_t::rawSsr.

sd_cid_t¶

SD card CID register.

sd_csd_t¶

SD card CSD register.

SDH_Init() decodes csdStructure, dataReadAccessTime1, dataReadAccessTime2, transferSpeed, cardCommandClass, readBlockLength, deviceSize and (CSD v1.0 only) deviceSizeMultiplier. The other members are not written by the driver.

mmc_ext_csd_t¶

Raw 512-byte EXT_CSD register of an eMMC device.

Read with CMD8 (SEND_EXT_CSD) during SDH_Init() and again after MMC_SwitchPartition(). Each member is the EXT_CSD byte at the given offset; the ranges named reserved_* are bytes the driver does not decode.

sd_scr_t¶

SD card SCR register.

sd_ssr_t¶

SD Status register.

Not decoded by this driver; the raw SD Status block read by SDH_Init() is in sd_card_t::rawSsr.

sd_card_t¶

SD card state.

Define the card structure including the necessary fields to identify and describe the card. Allocated by the caller and filled in by SDH_Init(); the driver keeps a pointer to it for the later calls on the same controller.

Typedefs¶

Macros¶

hal_sdio.h¶

#include "hal_sdio.h" (Source)

SDIO host stack on the SDH controller: card enumeration, CMD52/CMD53 register and data access, function management and card interrupts.

Implements the host side of the SDIO Simplified Specification (CMD0, CMD5, CMD3, CMD7, CMD52, CMD53) so that an external SDIO device, such as a Wi-Fi module, can be enumerated and accessed over the SDH peripheral. hal_sdh.h provides the status-code scheme and controller types; this module adds the SDIO I/O semantics, CCCR/FBR/CIS parsing, function management and DAT1 card-interrupt dispatch. It drives the single SDH controller and uses FreeRTOS objects.

Typical sequence: sdio_host_init(), sdio_card_enumerate(), then bus setup (sdio_set_high_speed(), sdio_set_bus_width(), sdio_set_clock()), then sdio_set_block_size() and sdio_enable_func() for each function used, sdio_claim_irq() and sdio_enable_irq() for card interrupts, and sdio_readb() / sdio_writeb() / sdio_read_blocks() / sdio_write_blocks() for I/O.

Threading: all calls are synchronous (blocking). Each CMD52/CMD53 takes the host's recursive mutex for the duration of the command; sdio_claim_host() holds it across a sequence of commands. Card-interrupt handlers run in the task that calls sdio_wait_irq() or sdio_poll_irq(), not in the ISR.

sdio_host_init¶

SDIO_Status_Type sdio_host_init(SDIO_Host_Type *host, SD_ID_Type sd_id);

Initialize a host descriptor and bring up the SDH controller (no card I/O).

Clears host, creates its recursive mutex and card-interrupt semaphore, resets and ungates the SDH peripheral, configures 1-bit mode at 400 kHz with 3.3 V signalling and powers the bus. It then registers the card-interrupt ISR and enables the SDH interrupt at the CPU; the card-interrupt signal itself stays disabled until sdio_enable_irq().

sdio_host_reset¶

SDIO_Status_Type sdio_host_reset(SDIO_Host_Type *host);

Software-reset the SDH controller (reset all) and wait for completion.

The controller configuration is lost; run sdio_host_reinit() before further card I/O. Only the controller is reset: a device that needs a reset or power-enable GPIO must be sequenced by the caller.

sdio_card_enumerate¶

SDIO_Status_Type sdio_card_enumerate(SDIO_Host_Type *host);

Run full SDIO enumeration: CMD0, CMD8, CMD5, CMD3, CMD7, then read the common CIS pointer and each function's FBR and CIS.

The CMD8 response is ignored. CMD5 is repeated with the card's voltage window until the card reports ready (about 1 s at most). If the card does not answer the first CMD5, as happens with a card that stayed selected across a host reset, the CCCR I/O Abort RES bit is written to reset the card's I/O part, CMD5 is polled for up to 1 s, and if needed the sequence is restarted once from CMD0. On success host->ocr, num_funcs, rca, common_cis_ptr and funcs[1..num_funcs] are filled.

No function is enabled and the bus stays in 1-bit mode at 400 kHz: set up the bus, then call sdio_set_block_size() and sdio_enable_func() for each function used.

sdio_set_bus_width¶

SDIO_Status_Type sdio_set_bus_width(SDIO_Host_Type *host, uint8_t width);

Switch bus width on the card and on the controller.

Writes the width bits of CCCR bus interface control, then reprograms the SDH controller with that width, with its high-speed enable following host->high_speed and with a bus clock of 50 MHz (high speed) or 25 MHz (requested values, see sdio_set_clock()). Any clock set earlier with sdio_set_clock() is replaced. Card must support 4-bit (most do).

sdio_set_bus_width_fast¶

void sdio_set_bus_width_fast(SDIO_Host_Type *host, uint8_t width);

Switch the bus width on a live, enumerated bus without re-initializing the controller.

Changes only the card's CCCR width bits and the controller's data-width bit; no clock or controller re-initialization. The other CCCR bus interface bits are read once and cached. CMD53 reads use this internally for the 1-bit read options (sdio_set_reads_1bit(), sdio_set_read_1bit_max()). Command errors are ignored.

sdio_set_high_speed¶

SDIO_Status_Type sdio_set_high_speed(SDIO_Host_Type *host, bool enable);

Enable or disable SDIO High Speed (50 MHz) on the card and set the bus clock.

Reads CCCR bus speed select. When enabling, it fails if the card does not support high speed; otherwise it sets or clears EHS, records host->high_speed and calls sdio_set_clock() with 50 MHz or 25 MHz.

sdio_set_clock¶

SDIO_Status_Type sdio_set_clock(SDIO_Host_Type *host, uint32_t hz);

Set the SDH bus clock (SDCLK).

The caller is responsible for staying within the card capability (default speed: 25 MHz, high speed: 50 MHz). The divider is derived from the 96 MHz SDH source clock by integer division, so the resulting clock can differ from hz.

sdio_set_small_pio¶

void sdio_set_small_pio(int enable);

Select which CMD53 transfers use PIO instead of ADMA2.

Workaround for small transfers whose single ADMA2 descriptor fails to start the data engine at high speed / 4-bit. Applies to all hosts. Default 0.

sdio_set_sampling_clk_sel¶

void sdio_set_sampling_clk_sel(int enable);

Select the delayed (io_dly) sampling clock for reads (HOST_CTRL_2 bit7).

With the bit set (SAMPLING_CLK_SEL), the input-delay taps in the GLB register GLB_SMIH_0_IO_DLY_0 shift the read capture point; with it clear, the reset state, they have no effect. The register is written immediately.

sdio_set_ignore_rd_crc¶

void sdio_set_ignore_rd_crc(int enable);

Accept CMD53 read data even when the controller reports a data-phase error.

Data CRC (and other non-timeout data errors) are ignored for reads; a data timeout is still reported. Writes are not affected. Default off. A caller that enables this must verify the received data by other means.

sdio_set_reads_1bit¶

void sdio_set_reads_1bit(int enable);

Run all CMD53 reads at 1-bit while writes keep the configured width.

Each CMD53 read switches to 1-bit with sdio_set_bus_width_fast() inside the transfer's mutex and restores the width afterwards, so the switch is atomic against other tasks. Default off.

sdio_set_read_1bit_max¶

void sdio_set_read_1bit_max(uint32_t max_bytes);

Run CMD53 reads of at most max_bytes bytes at 1-bit.

Larger reads keep the configured width. The width switch happens inside the transfer's mutex, as for sdio_set_reads_1bit(). Independent of sdio_set_reads_1bit(), which forces every read to 1-bit.

sdio_set_dir_phase¶

void sdio_set_dir_phase(const SDIO_Phase_Type *rd_phase, const SDIO_Phase_Type *wr_phase, int enable);

Use separate sampling phases for CMD53 reads and CMD53 writes.

When enabled, each CMD53 applies rd_phase or wr_phase, chosen by transfer direction, inside the transfer's mutex. The last applied setting is cached, so consecutive transfers in the same direction write no registers. Useful when the read-optimal phase makes the host mis-sample the card's CRC status after a write. Combines with sdio_set_reads_1bit(): a 1-bit read still uses rd_phase. Default off.

sdio_host_reinit¶

SDIO_Status_Type sdio_host_reinit(SDIO_Host_Type *host);

Re-run the SDH controller bring-up and clear the enumeration state without re-creating the RTOS objects or re-registering the ISR.

Under the host mutex, repeats the controller bring-up of sdio_host_init() (reset, 1-bit, 400 kHz, power on) and clears rca, num_funcs, common_cis_ptr, funcs[], bus_width (1-bit) and high_speed. Registered interrupt handlers are kept, but sdio_enable_irq() must be called again after re-enumeration. Use it for repeated re-enumeration (follow with sdio_card_enumerate()); sdio_host_init() must not be called twice.

sdio_set_block_size¶

SDIO_Status_Type sdio_set_block_size(SDIO_Host_Type *host, uint8_t func_num, uint16_t block_size);

Set function block size (CCCR FN0_BLOCK_SIZE or FBR per-func).

Writes the 2-byte block size register with two CMD52 writes and records the value in funcs[func_num].cur_blk_size, which sdio_read_blocks() and sdio_write_blocks() use.

sdio_enable_func¶

SDIO_Status_Type sdio_enable_func(SDIO_Host_Type *host, uint8_t func_num);

Set IO Enable bit, poll IO Ready until function is ready.

IO_READY is polled up to 200 times at 5 ms intervals (about 1 s).

sdio_disable_func¶

SDIO_Status_Type sdio_disable_func(SDIO_Host_Type *host, uint8_t func_num);

Clear IO Enable bit.

sdio_claim_host¶

SDIO_Status_Type sdio_claim_host(SDIO_Host_Type *host);

Claim exclusive ownership of the SDIO host for a sequence of back-to-back CMDs (recursive).

Use it to span several sdio_readb() / sdio_writeb() / sdio_read_blocks() / sdio_write_blocks() calls without releasing the bus in between, for example polling a status register with CMD52 and then writing data with CMD53. Waits forever for the mutex. Each sdio_claim_host() must be paired with a sdio_release_host() on the same task.

Calling these is optional: every CMD52/CMD53 function already claims and releases the host internally. Nesting works because the host mutex is recursive.

sdio_release_host¶

SDIO_Status_Type sdio_release_host(SDIO_Host_Type *host);

Release the host claimed with sdio_claim_host().

sdio_readb¶

SDIO_Status_Type sdio_readb(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, uint8_t *out_val);

Read one byte from func/addr with CMD52 (IO_RW_DIRECT).

sdio_writeb¶

SDIO_Status_Type sdio_writeb(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, uint8_t val);

Write one byte with CMD52 (IO_RW_DIRECT).

sdio_writeb_readback¶

SDIO_Status_Type sdio_writeb_readback(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, uint8_t val, uint8_t *out_old);

Write one byte with CMD52 and the read-after-write (RAW) flag.

With RAW set the card returns the register content read back after the write in the R5 response, which is returned in out_old.

sdio_read_bytes¶

SDIO_Status_Type sdio_read_bytes(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, uint8_t *buf, uint16_t count, bool fixed_addr);

Byte-mode CMD53 read (count is byte length, max 511; 0 means 512).

Uses ADMA2 unless sdio_set_small_pio() selects PIO for this transfer; the data cache is maintained over buf by the function. Takes the host mutex and applies the read options set with sdio_set_dir_phase(), sdio_set_reads_1bit(), sdio_set_read_1bit_max() and sdio_set_ignore_rd_crc().

sdio_write_bytes¶

SDIO_Status_Type sdio_write_bytes(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, const uint8_t *buf, uint16_t count, bool fixed_addr);

Byte-mode CMD53 write (count is byte length, max 511; 0 means 512).

Uses ADMA2 unless sdio_set_small_pio() selects PIO for this transfer; the data cache is cleaned over buf before the transfer. Takes the host mutex and applies the write phase set with sdio_set_dir_phase().

sdio_read_blocks¶

SDIO_Status_Type sdio_read_blocks(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, uint8_t *buf, uint16_t count, bool fixed_addr);

Read blocks with CMD53 in block mode.

The function must have its block size set first: the block size is funcs[func_num].cur_blk_size, set with sdio_set_block_size(); total bytes = count * block size. Transfer, cache and option handling are as for sdio_read_bytes().

sdio_write_blocks¶

SDIO_Status_Type sdio_write_blocks(SDIO_Host_Type *host, uint8_t func_num, uint32_t addr, const uint8_t *buf, uint16_t count, bool fixed_addr);

Write blocks with CMD53 in block mode.

The function must have its block size set first: the block size is funcs[func_num].cur_blk_size, set with sdio_set_block_size(); total bytes = count * block size. Transfer and cache handling are as for sdio_write_bytes().

sdio_claim_irq¶

SDIO_Status_Type sdio_claim_irq(SDIO_Host_Type *host, uint8_t func_num, SDIO_IRQ_Handler handler, void *arg);

Register a per-function interrupt handler.

Must be called before sdio_enable_irq(). Only stores handler and arg in the host; sdio_enable_irq() enables the interrupt in the card for every function that has a handler.

sdio_release_irq¶

SDIO_Status_Type sdio_release_irq(SDIO_Host_Type *host, uint8_t func_num);

Unregister the interrupt handler of a function.

Clears the handler and argument only; CCCR INT_ENABLE in the card is not changed (call sdio_enable_irq() or sdio_disable_irq() to update it). Not synchronized with interrupt dispatch: release a handler only while no task is running sdio_wait_irq() or sdio_poll_irq() on this host. Not for ISR context.

sdio_enable_irq¶

SDIO_Status_Type sdio_enable_irq(SDIO_Host_Type *host);

Enable the DAT1 card interrupt at the SDH controller and set CCCR INT_ENABLE for registered functions.

Writes INT_ENABLE with the master enable bit plus the bit of every function 1..num_funcs that has a handler, then enables the controller's card-interrupt status and signal. Call once after all sdio_claim_irq() calls, and again after changing the set of handlers or after sdio_host_reinit().

sdio_disable_irq¶

SDIO_Status_Type sdio_disable_irq(SDIO_Host_Type *host);

Disable the card interrupt at the controller and clear CCCR INT_ENABLE.

sdio_set_wait_demotion¶

void sdio_set_wait_demotion(void *task, unsigned base_prio);

Lower a task's priority while it waits for the data phase of an SDH DMA transfer.

The SDH data phase of a blocking transfer, such as a CMD53, is polled. While the registered task polls, its priority is set to tskIDLE_PRIORITY + 1, so that lower-priority tasks can run, and is then set back to base_prio. Other tasks keep polling at their own priority.

sdio_poll_irq¶

SDIO_Status_Type sdio_poll_irq(SDIO_Host_Type *host);

Poll SDH for SDIO card interrupt and dispatch to registered handlers.

Non-blocking. Takes the card-interrupt semaphore with zero timeout; if the ISR has not given it, reads the controller's card-interrupt status directly (for use without sdio_enable_irq()). When an interrupt is pending, reads CCCR INT_PENDING with CMD52 and calls the handler of each pending function. Returns immediately whether or not any work was found.

Prefer sdio_wait_irq(): it blocks until the ISR signals instead of polling.

sdio_wait_irq¶

SDIO_Status_Type sdio_wait_irq(SDIO_Host_Type *host, uint32_t ticks);

Block on the SDH card-interrupt semaphore (given by the ISR), then read CCCR INT_PENDING over CMD52 and dispatch to registered per-function handlers.

Requires sdio_enable_irq().

sdio_walk_cis¶

SDIO_Status_Type sdio_walk_cis(SDIO_Host_Type *host, uint8_t func_num, uint32_t start_ptr, SDIO_CIS_Tuple_CB cb, void *arg);

Walk a CIS tuple chain from start_ptr and call cb for each tuple.

Tuples are read with CMD52 from the function 0 address space. Null tuples are skipped and not reported; the walk ends at SDIO_CISTPL_END, when cb returns non-zero, or at the end of the CIS area (0x17FFF). Used during enumeration; exposed for device-specific parsing.

SDIO_Status_Type¶

SDIO host status codes.

Status_SDIO_Success is 0, the same value as Status_Success. The other codes are in the StatusGroup_SDH group, numbered from 100.

SDIO_Func_Info_Type¶

Per-function information collected during enumeration.

Stored in SDIO_Host_Type::funcs, indexed by function number. sdio_card_enumerate() fills func_num, cis_ptr and, from the function CIS, func_class, manf_id, prod_id and max_blk_size.

SDIO_Host_Type¶

SDIO host descriptor.

One per SDH controller instance.

Caller allocates; pass to sdio_host_init() before any other API. The stack keeps a pointer to the most recently initialized host for its interrupt handler, so only one host is active at a time.

SDIO_Phase_Type¶

One SDH sampling-phase setting: the full GLB input-delay register word plus HOST_CTRL_2 bit7 SAMPLING_CLK_SEL.

Typedefs¶

Macros¶

hal_pio_sdh.h¶

#include "hal_pio_sdh.h" (Source)

SD card host built on the IPRO7 PIO state machines: card initialization, 512-byte block read and write, FatFS port.

An alternative to the hardware SDH controller (hal_sdh.h) for SD memory cards. A PIO state machine generates CLK by side-set and shifts the 48-bit commands out and the responses in on CMD; the same state machine then clocks the DATA lines (1-bit or 4-bit) for the data phase. The hardware SDH (on GPIO28-33) is independent of this host and is left untouched, so both can be used in the same system.

Typical use: fill a hal_pio_sdh_cfg_t, call hal_pio_sdh_init(), then hal_pio_sdh_read_blocks() and hal_pio_sdh_write_blocks(), or register the host with FatFS through fatfs_pio_sdh_driver_register(). Functions that return int return 0 on success and a negative value on error. The driver state is global (one card) and the functions are blocking and not thread-safe.

hal_pio_sdh_init¶

int hal_pio_sdh_init(const hal_pio_sdh_cfg_t *cfg, hal_pio_sdh_card_t *out);

Set up the PIO host and initialize the SD card.

Runs hal_pio_sdh_hw_setup(), sends the power-up clocks and then CMD0, CMD8, ACMD41 (repeated until the card is ready, up to 1000 attempts), CMD2, CMD3, CMD9, CMD7 and ACMD6 (4-bit bus). It then tries the CMD6 high-speed switch (best effort, see hal_pio_sdh_switch_hs()) and sets the 24 MHz transfer clock. Supports SD memory cards (SDSC, SDHC, SDXC).

hal_pio_sdh_hw_setup¶

int hal_pio_sdh_hw_setup(const hal_pio_sdh_cfg_t *cfg);

Configure the GLB PIO clock and pin mux, load the CLK/CMD program on the state machine and start it.

Copies cfg, selects the 400 kHz identification clock, and sets up the DMA channels when cfg->use_dma is set. The state machine clocks CLK only while it has bits to shift; CLK stays low when idle. hal_pio_sdh_init() calls this; call it directly only to drive the bus by hand with hal_pio_sdh_send_cmd() and hal_pio_sdh_clock_burst().

hal_pio_sdh_send_cmd¶

int hal_pio_sdh_send_cmd(uint8_t cmd, uint32_t arg, uint8_t resp_bits, uint32_t raw[2]);

Send one 48-bit command and optionally receive a 48-bit response.

Sends 8 idle clocks first. The response CRC is not checked: use sdio_check_r1_crc() for R1/R6/R7 responses (R3 has no CRC). Requires hal_pio_sdh_hw_setup() or hal_pio_sdh_init().

hal_pio_sdh_clock_burst¶

void hal_pio_sdh_clock_burst(uint32_t n);

Run n clock cycles with CMD released (>=74 required after card power-up).

CMD is not driven, so the card sees it high through the pull-up. Returns early, silently, if the state machine stops consuming bits.

hal_pio_sdh_read_blocks¶

int hal_pio_sdh_read_blocks(uint8_t *buf, uint32_t lba, uint32_t count);

Read 512-byte blocks from the card.

Uses CMD17 for one block. For several blocks it sends CMD23 and a bounded CMD18 when the card accepts CMD23, otherwise an open-ended CMD18 ended with CMD12. Works with a 1-bit or 4-bit bus, through DMA when cfg->use_dma was set. Call after hal_pio_sdh_init().

hal_pio_sdh_write_blocks¶

int hal_pio_sdh_write_blocks(const uint8_t *buf, uint32_t lba, uint32_t count);

Write 512-byte blocks to the card (4-bit bus only).

Uses CMD24 for one block, after which (by default) the card status is polled with CMD13 until the card is back in the transfer state, for at most 500 ms. For several blocks it sends CMD23 and a bounded CMD25 when the card accepts CMD23, otherwise an open-ended CMD25 ended with CMD12, and then waits for the card to finish programming. Call after hal_pio_sdh_init().

hal_pio_sdh_set_clock¶

int hal_pio_sdh_set_clock(uint32_t hz);

Set the SD clock.

The clock is 24 MHz / N with N = 24 MHz / hz rounded down and limited to 1..65535, so it is at most 24 MHz and otherwise not below hz. 0 selects the 400 kHz identification clock. Applies to the command and the data phases. Requires hal_pio_sdh_hw_setup() or hal_pio_sdh_init(); assumes the 96 MHz PIO clock.

Returns: Always 0.

fatfs_pio_sdh_driver_register¶

void fatfs_pio_sdh_driver_register(const hal_pio_sdh_cfg_t *cfg);

Register this host as the FatFS disk driver of the DEV_SD drive.

Implemented in the FatFS port of the SDK, built when CONFIG_HAL_PIO_SDH is enabled. Copies cfg; the card is initialized with hal_pio_sdh_init() on the first disk initialization, and registering again makes the next access re-initialize it. The hardware SDH FatFS port uses the same DEV_SD drive slot; the last registration wins. Failed reads and writes are retried once.

hal_pio_sdh_set_pad_cfg¶

int hal_pio_sdh_set_pad_cfg(uint8_t drive, uint8_t pull_up, uint8_t smt);

Set drive strength, internal pull-up and Schmitt trigger for all six SD pins.

The setting is sticky: it is stored and re-applied on every later hal_pio_sdh_init() / hal_pio_sdh_hw_setup(), and applied immediately if the hardware is already set up. Boot defaults: drive strength CONFIG_HAL_PIO_SDH_PAD_DRIVE (3 if not set), pull-ups on unless CONFIG_HAL_PIO_SDH_PULL_NONE is set, Schmitt trigger on.

Returns: Always 0.

hal_pio_sdh_set_bus_width¶

int hal_pio_sdh_set_bus_width(uint8_t width);

Switch DATA bus width (1 or 4) via ACMD6; needs an initialized card.

Writes need a 4-bit bus (see hal_pio_sdh_write_blocks()).

hal_pio_sdh_switch_hs¶

int hal_pio_sdh_switch_hs(uint8_t *status);

Switch the card to High-Speed access mode with CMD6 (SWITCH_FUNC).

Reads the 512-bit switch status and, when the card grants high speed, makes the host sample read data with high-speed timing. The clock is not changed. hal_pio_sdh_init() already calls this (best effort). The card must be initialized and in 4-bit mode.

hal_pio_sdh_card_status¶

int hal_pio_sdh_card_status(uint32_t *status, uint32_t *state);

Read the card status with CMD13 (SEND_STATUS).

Read-only: the card state is not changed.

hal_pio_sdh_deinit¶

void hal_pio_sdh_deinit(void);

Stop the PIO state machine used by the host.

Only the CLK/CMD state machine is disabled; pins, DMA channels and the PIO clock stay configured. Call hal_pio_sdh_init() to use the card again.

hal_pio_sdh_cfg_t¶

PIO SD host configuration.

Reference pin map: CLK = GPIO22, CMD = GPIO23, DAT0..DAT3 = GPIO24..27. Constraints: DAT0..DAT3 must be 4 contiguous ascending GPIOs, and pin_clk must equal pin_d0 - 2.