This file contains all the SDIO HAL API definitions. Here we define SDIO driver as a protocol layer driver which builds on top of SDMMC host driver. SDMMC host driver operates at physical layer and provide APIs to send commands to the slave device and receive command responses, send and receive data, and handle error conditions on the bus. More...

#include <stdint.h>
#include <stdbool.h>

Data Structures
struct	IotSdioCardDetectParam_t
	input parameter type for eSDIOSetCardDetectParams ioctl request More...

struct	IoTSdioPowerOnOffCard_t
	input parameter type for eSDIOPowerOnOffCard ioctl request More...

struct	IotSdioFuncBlkSize_t
	input parameter type for eSDIOSetFuncBlockSize ioctl request More...

struct	IotSdioPerFuncEnable_t
	input parameter type for eSDIOEnableIOFunctionIrq ioctl request and for eSDIOEnableIo ioctl request More...

struct	IotSdioReadCis_t
	input parameter type for eSDIOReadCis ioctl request More...

Macros
#define	IOT_SDIO_SUCCESS ( 0 )
	The return codes for the functions in SDIO.

#define	IOT_SDIO_IOCTL_FAIL ( 1 )

#define	IOT_SDIO_HOST_INIT_FAIL ( 2 )

#define	IOT_SDIO_INVALID_VALUE ( 3 )

#define	IOT_SDIO_TRANSFER_FAIL ( 4 )

#define	IOT_SDIO_SWITCH_HIGH_SPEED_FAIL ( 5 )

#define	IOT_SDIO_LOW_SPEED_CARD ( 6 )

#define	IOT_SDIO_SELECT_BUS_TIMING_FAIL ( 7 )

#define	IOT_SDIO_SET_CARD_BLOCK_SIZE_FAIL ( 8 )

#define	IOT_SDIO_SWITCH_VOLTAGE_FAIL ( 9 )

#define	IOT_SDIO_HOST_NOT_READY ( 10 )

#define	IOT_SDIO_INVALID_CARD ( 11 )

#define	IOT_SDIO_SEND_RELATIVE_ADDRESS_FAIL ( 12 )

#define	IOT_SDIO_SELECT_CARD_FAIL ( 13 )

#define	IOT_SDIO_READ_CIS_FAIL ( 14 )

#define	IOT_SDIO_SET_DATA_BUS_WIDTH_FAIL ( 15 )

#define	IOT_SDIO_ASYNC_INT_NOT_SUPPORTED ( 16 )

#define	IOT_SDIO_GET_CARD_CAPABILITY_FAIL ( 17 )

#define	IOT_SDIO_FUNCTION_NOT_SUPPORTED ( 18 )

#define	IOT_SDIO_BUS_1BIT ( 0 )
	sdio io bus width

#define	IOT_SDIO_BUS_4BIT ( 2 )

#define	IOT_SDIO_BUS_8BIT ( 3 )

Typedefs
typedef struct IotSdioSlotDescriptor *	IotSdioSlotHandle_t
	IotSdioSlotHandle_t type is the SDIO slot handle returned by calling iot_sdio_open()

typedef void(*	IotSdioCallback_t) (IotSdioSlotHandle_t const pxSdioHandle, IotSdioEventType_t eSdioEvent, void *pvUserContext)
	The callback function for sdio event operation. This callback is passed to driver by using iot_sdio_set_callback API. It's called when one of the events (IotSdioEventType_t) happens.

typedef void(*	IotSdioIOFunctionCallback_t) (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, void *pvUserContext)
	SDIO I/O function callback type. User can call iot_sdio_set_io_function_callback() API to set one IOFunctionCallback per each standard SDIO function supported on a sdio card.

Enumerations
enum	IotSdioDirection_t { eIORead = 0U , eIOWrite = 1U }
	sdio io read/write direction More...

enum	IotSdioFunction_t { eSdioFunction0 , eSdioFunction1 , eSdioFunction2 , eSdioFunction3 , eSdioFunction4 , eSdioFunction5 , eSdioFunction6 , eSdioFunction7 , eSdioFunctionMemory }
	SDIO I/O function number type Each SDIO card can support up to 7 I/O functions. Each I/O function can implement one of the following: More...

enum	IotSdioCardDetectType_t { eDetectCardByGpioCD , eDetectCardByHostCD , eDetectCardByHostDATA3 , eDetectCardNonStandard }
	card detect type More...

enum	IotSdioEventType_t { eSdioCardInterruptEvent , eSdioCardInsertedEvent , eSdioCardRemovedEvent , eSdioCardPowerOnEvent , eSdioCardPowerOffEvent }
	common notify event types in sdio callback More...

enum	IotSdioIoctlRequest_t { eSDIOSetDriverStrength , eSDIOSetCardInactive , eSDIOSwitchToHighSpeed , eSDIOSetDataBusWidth , eSDIOGetCardCapabilities , eSDIOSetCardDetectParams , eSDIOSetFuncBlockSize , eSDIOEnableIOFunctionIrq , eSDIOEnableAsyncIrqMode , eSDIOEnableIo , eSDIOSelectIo , eSDIOAbortIo , eSDIOReadCis , eSDIOPowerOnOffCard , eSDIOCheckCardPresence }
	IOCTL request types. More...

enum	IotSdioBusWidth_t { eDataBus1Bit = IOT_SDIO_BUS_1BIT , eDataBus4Bit = IOT_SDIO_BUS_4BIT , eDataBus8Bit = IOT_SDIO_BUS_8BIT }
	sdio bus width, input parameter type for eSDIOSetDataBusWidth ioctl request More...

enum	IotSdioSdDriverStrength_t { eSdDriverStrengthTypeB = 0U , eSdDriverStrengthTypeA = 1U , eSdDriverStrengthTypeC = 2U , eSdDriverStrengthTypeD = 3U }
	SDIO card driver strength, input parameter type for eSDIOSetDriverStrength ioctl request. More...

Functions
IotSdioSlotHandle_t	iot_sdio_open (uint8_t ucHostIdx, uint8_t ucSlotIdx)
	iot_sdio_open() is used to open a handle to a sdio card slot.

int32_t	iot_sdio_close (IotSdioSlotHandle_t const pxSdioHandle)
	iot_sdio_close() is used to close the sdio card slot handle. IO operation initiated through this handle before will not be aborted. Caller should call iot_sdio_abort_io() to abort IO operation.

int32_t	iot_sdio_card_connect (IotSdioSlotHandle_t const pxSdioHandle)
	iot_sdio_card_connect() is used to connect SDIO card.

int32_t	iot_sdio_card_disconnect (IotSdioSlotHandle_t const pxSdioHandle)
	iot_sdio_card_disconnect() is used to disconnect SDIO card.

int32_t	iot_sdio_card_reset (IotSdioSlotHandle_t const pxSdioHandle)
	iot_sdio_card_reset() is used to reset the sdio card in the target slot. This API should soft reset all I/O functions in sdio card.

int32_t	iot_sdio_io_write_direct (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, uint32_t ulRegAddr, uint8_t *pucData, bool bRaw)
	iot_sdio_io_write_direct() implements the write portion of CMD52. It is used to write 1 byte to a single register within the register space of a card I/O function.

int32_t	iot_sdio_io_read_direct (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, uint32_t ulRegAddr, uint8_t *pucData)
	iot_sdio_io_read_direct() implements the read portion of CMD52. It is used to read 1 byte from a single register within the register space of a card I/O function.

int32_t	iot_sdio_io_write_extended (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, bool bBlockMode, bool bOpcode, uint32_t ulRegAddr, uint8_t *pucBuf, uint32_t ulCount)
	iot_sdio_io_write_extended() implements the write portion of CMD53. It is used to write multiple bytes or blocks to a single address or incremental addresses within the register space in a I/O function. It provides highest transfer rate possible.

int32_t	iot_sdio_io_read_extended (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, bool bBlockMode, bool bOpcode, uint32_t ulRegAddr, uint8_t *pucBuf, uint32_t ulCount)
	iot_sdio_io_read_extended() implements the read portion of CMD53. It is used to read multiple bytes or blocks from a single address or incremental addresses within the register space in a I/O function. It provides highest transfer rate possible.

int32_t	iot_sdio_set_io_function_callback (IotSdioSlotHandle_t const pxSdioHandle, IotSdioFunction_t eFunc, IotSdioIOFunctionCallback_t xIOFunctionCallback, void *pvIOFunctionCallbackUserContext)
	iot_sdio_set_io_function_callback() is used to set IOFunctionCallback for each I/O function the card supports.

int32_t	iot_sdio_set_sdio_callback (IotSdioSlotHandle_t const pxSdioHandle, IotSdioCallback_t xSdioCallback, void *pvSdioCallbackUserContext)
	iot_sdio_set_sdio_callback() is used to set sdio card interrupt callback.

int32_t	iot_sdio_ioctl (IotSdioSlotHandle_t const pxSdioHandle, IotSdioIoctlRequest_t xSdioIoctlRequest, void *const pvBuffer)
	iot_sdio_ioctl() is Used for various sdio control function.

Detailed Description

This file contains all the SDIO HAL API definitions. Here we define SDIO driver as a protocol layer driver which builds on top of SDMMC host driver. SDMMC host driver operates at physical layer and provide APIs to send commands to the slave device and receive command responses, send and receive data, and handle error conditions on the bus.

SD/SDIO/MMC driver can be built on top of SDMMC host. This interface only define the APIs for SDIO applications, the interface can be expanded to support SD/MMC either by expanding the APIs in this file or adding separate files for SD/MMC.

Consideration

SDIO HAL APIs performs protocol layer tasks between SDIO host and SDIO card.
Some APIs perform a single task and some APIs perform a sequence of tasks.
For examples, iot_sdio_io_read_direct() API performs a single task of reading
one byte from card register, and iot_sdio_card_connect() API performs all tasks
required by card initialization as specified in section 3.1.2 in "SD Specification
Part E1 SDIO".

Upon calling iot_sdio_open() API, the user is a given a pxSdioHandle, a
reference to the SDIO card slot that the user is interested in. Thereafter, user
uses this handle to call other APIs to perform tasks associated with the target
card slot. For example, iot_sdio_check_card_presence_status(pxSdioHandle, true)
checks SDIO card presence, and iot_sdio_io_write_extended(pxSdioHandle)
writes data to SDIO card in the slot, etc.

Limitation

SDIO HAL APIs are intended to be used in embedded systems where each SDIO host
controller is connected to either a single hot swappable sdio card slot or multiple
eSDIO devices in a Shared Bus Configuration (Refer to Section 7.3 of "SD Specification
Part E1 SDIO").

These APIs are not suitable for systems where a single SDIO host controller supports
multiple hot swappable slots. With multiple hot swappable slots available on a single
host controller, it is not possible pre-determine which card slot SDIO device will be
inserted, and know which card slot handle to request. Since this type of host controller
is very rare even in non-embedded world, it is not worth to add complexity to SDIO HAL
APIs to support it.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description