phoenix-rtos-doc / devices / libsdio / README.md

Libsdio

General description

Libsdio is a static, precompiled library containing a generic SDIO driver which directly controls the platform hardware. This driver defines an API providing basic interface control functionality.

Platform support

Target	Supported?
armv7a7-imx6ull	:heavy_check_mark:
armv7m7-imxrt106x	:x:
ia32-generic-pc	:x:

Limitations

only one library instance per system
no fallback SD protocol support (SDIO only)
no support for multiple SDIO devices
no support for SDIO in SPI mode
only 4-bit data transfer mode supported
only 50/25 MHz clock speeds available on imx6ull

API summary

Contents of <sdio.h> header are listed below.

Functions:

int sdio_init(void);


void sdio_free(void);


int sdio_config(uint32_t freq, uint16_t blocksz);


int sdio_transferDirect(sdio_dir_t dir, uint32_t address, uint8_t area, uint8_t *data);


int sdio_transferBulk(sdio_dir_t dir, int blockMode, uint32_t address, uint8_t area,
    uint8_t *data, size_t len);


int sdio_eventRegister(uint8_t event, sdio_event_handler_t handler, void *arg);


int sdio_eventEnable(uint8_t event, int enabled);

Types:

typedef enum {
    sdio_read,
    sdio_write
} sdio_dir_t;


typedef void (*sdio_event_handler_t)(void *arg);

Definitions:

define	description
SDIO_EVENT_CARD_IN	SDIO device is inserted
SDIO_EVENT_CARD_OUT	SDIO device is removed
SDIO_EVENT_CARD_IRQ	SDIO device requested an interrupt

NOTE: These definitions are meant for use with sdio_eventEnable and sdio_eventRegister functions exclusively.

API description

Following sections describe the API in detail, including the behavior of certain functions.

NOTE: Codes returned by API calls are defined in <errno.h> header, which provides more detailed information about specific values.

typedef enum {
    sdio_read,
    sdio_write
} sdio_dir_t;

Description:

This enumeration type is meant as parameter for sdio_transferDirect and sdio_transferBulk functions to indicate the direction of a given data transfer.

typedef void (*sdio_event_handler_t)(void *arg);

Description:

This type describes a callback for an interrupt handler. Handlers of interrupts events are assigned to a specific event, and every event can only have a single handler. Handler argument is provided during handler registration using sdio_eventRegister, and will remain unchanged until the handler registration is modified via the same function.

int sdio_init(void);

Description:

This function initializes the SDIO interface hardware and tries to detect and select the connected device. It has to be called before any other API function. Should no device be present, or it does not respond to SDIO initialization sequence, this function shall return an error code and free resources it acquired.

NOTE: Calling this function more than once after successful completion will have no effect. In order to reinitialize the interface, sdio_free should be called between concurrent sdio_init calls instead.

Parameters:

none

Returns:

code	description
EOK	success
-EIO	I/O hardware fault occurred
-ENOMEM	not enough memory available

void sdio_free(void);

Description:

This function frees the SDIO bus, reset the host controller, deregister and disable all previously registered event handlers. Calling this function before sdio_init has no effect.

NOTE: Due to its current implementation, calling this function does not allow for creation of new library instances in other running processes.

Parameters:

none

Returns:

nothing

int sdio_config(uint32_t freq, uint16_t blocksz);

Description:

This function provides a configuration interface for the SDIO bus controller. This function can be called at any time after sdio_init.

Parameters:

parameter	description	possible values
[in] `uint32_t freq`	SDIO clock frequency in Hz	any
[in] `uint16_t blocksz`	block size for bulk transfers	25000000 / 50000000

Returns:

code	description
EOK	success
-EINVAL	provided `blocksz` is invalid
-ETIMEDOUT	device configuration took too long
-EIO	I/O hardware fault occurred

int sdio_transferDirect(sdio_dir_t dir, uint32_t address, uint8_t area, uint8_t *data);

Description:

This function initiates a direct, single 8-bit register read/write operation. When dir is specified as sdio_write the byte inside the data buffer is written to the device, otherwise if dir equals sdio_read, the buffer is set to the value read from the device.

NOTE: This function is a blocking call which only returns upon successful transfer completion or failure.

Parameters:

parameter	description	possible values
[in] `sdio_dir_t dir`	transfer direction	sdio_read / sdio_write
[in] `uint32_t address`	card register address to access	any 17-bit value
[in] `uint8_t area`	card I/O area index to access	any 3-bit value
[in/out] `uint8_t *data`	bidirectional single byte buffer	any valid pointer

Returns:

code	description
EOK	success
-EBUSY	device is currently busy
-ETIMEDOUT	device did not respond in time

int sdio_transferBulk(sdio_dir_t dir, int blockMode, uint32_t address, uint8_t area,
    uint8_t *data, size_t len);

Description:

This function initiates an indirect, multibyte transfer of up to 2048 bytes at once. As is the case with sdio_transferDirect, this call can service bidirectional transfers.

NOTE: This function is a blocking call which only returns upon successful transfer completion or failure.

Parameters:

parameter	description	possible values
[in] `sdio_dir_t dir`	transfer direction	sdio_read / sdio_write
[in] `int blockMode`	divide transfer into blocks	boolean
[in] `uint32_t address`	card base address to access	any 17-bit value
[in] `uint8_t area`	card I/O area index to access	any 3-bit value
[in/out] `uint8_t *data`	bidirectional multibyte buffer	any valid pointer
[in] `size_t len`	total transfer size in bytes	≤2048

NOTE: len parameter has to be a multiple of blocksz when performing a block transfer with blockMode set to true. NOTE: address parameter specifies only the base address of the transfer. If blockMode is set to true, then the address is automatically incremented by the device with every completed block.

Returns:

code	description
EOK	success
-EIO	I/O hardware fault occurred
-EBUSY	interface is currently busy
-ETIMEDOUT	transfer request was not serviced in time
-EINVAL	see parameters section

int sdio_eventRegister(uint8_t event, sdio_event_handler_t handler, void *arg);

This function registers an event handler to be called when a given interrupt event occurs. An interrupt event will not be signalled until its detection is enabled by sdio_eventEnable. Please note that only one handler can be registered per event - calling this function multiple times for the same event will result in the previous handler being overwritten. In order to deregister the handler one can pass NULL as the handler parameter.

Parameters:

parameter	description	possible values
[in] `uint8_t event`	event to be handled	see note below
[in] `sdio_event_handler_t handler`	pointer to event handler function	any pointer
[in/out] `void *arg`	argument for the handler function	any pointer

NOTE: event argument is passed using appropriate defines beginning with SDIO_EVENT.

Returns:

code	description
EOK	success
-EINVAL	provided `event` is not valid

NOTE: Codes returned are defined in <errno.h> header.

int sdio_eventEnable(uint8_t event, int enabled);

This function can enable or disable interrupt event signalling of the SD host controller. If a handler is registered via sdio_eventRegister for a given enabled event, it will be called when an interrupt fires.

Parameters:

parameter	description	possible values
[in] `uint8_t event`	event for which signalling enable is to be set	see note below
[in] `int enabled`	state of signalling enable (1/0)	boolean

NOTE: event argument is passed using appropriate defines beginning with SDIO_EVENT.

Returns:

code	description
EOK	success
-EINVAL	provided `event` is not valid