# SDIO Usage Guidelines - [How to Use](#section1962415610383) - [Opening an SDIO Controller](#section814751015461) - [Claiming a Host Exclusively](#section49274582455) - [Enabling the SDIO Device](#section1431520410489) - [Claiming an SDIO IRQ](#section3662781537) - [Performing SDIO Communication](#section391941913484) - [Releasing the SDIO IRQ](#section56205204481) - [Disabling the SDIO Device](#section181181621124815) - [Releasing the Exclusively Claimed Host](#section657117215486) - [Closing an SDIO Controller](#section1898172114818) ## How to Use [Figure 1](spiusage-guidelines.md#fig23885455594) illustrates the process of using an SDIO. **Figure 1** Process of using an SDIO ![](figures/en-us_image_0000001054440624.png) ## Opening an SDIO Controller Before performing SDIO communication, obtain the device handle of an SDIO controller by calling **SdioOpen**. This function returns the device handle of the SDIO controller with a specified bus number. DevHandle SdioOpen\(int16\_t mmcBusNum, struct SdioFunctionConfig \*config\); **Table 1** Parameters and return values of SdioOpen

Parameter	Description
mmcBusNum	Bus number.
config	SDIO functionality configurations.
Return Value	Description
NULL	Failed to obtain the device handle of an SDIO controller.
Device handle	Device handle of an SDIO controller.

The following example shows how to open an SDIO controller. ``` DevHandle handle = NULL; struct SdioFunctionConfig config; config.funcNr = 1; config.vendorId = 0x123; config.deviceId = 0x456; /* Open an SDIO controller whose bus number is 1. */ handle = SdioOpen(1, &config); if (handle == NULL) { HDF_LOGE("SdioOpen: failed!\n"); } ``` ## Claiming a Host Exclusively After obtaining the device handle of an SDIO controller, exclusively claim the host before performing subsequent operations on the SDIO device. void SdioClaimHost\(DevHandle handle\); **Table 2** Parameter description of SdioClaimHost

Parameter	Description
handle	Device handle of an SDIO controller.

The following example shows how to exclusively claim a host. ``` SdioClaimHost(handle); /* Claim a host exclusively. */ ``` ## Enabling the SDIO Device Before accessing a register, enable the SDIO device. int32\_t SdioEnableFunc\(DevHandle handle\); **Table 3** Parameters and return values of SdioEnableFunc

Parameter	Description
handle	Device handle of an SDIO controller.
Return Value	Description
0	The SDIO device is enabled.
Negative value	Failed to enable the SDIO device.

The following example shows how to enable the SDIO device. ``` int32_t ret; /* Enable the SDIO device. */ ret = SdioEnableFunc(handle); if (ret != 0) { HDF_LOGE("SdioEnableFunc: failed, ret %d\n", ret); } ``` ## Claiming an SDIO IRQ Before SDIO communication, claim an SDIO IRQ. int32\_t SdioClaimIrq\(DevHandle handle, SdioIrqHandler \*handler\); **Table 4** Parameters and return values of SdioClaimIrq

Parameter	Description
handle	Device handle of an SDIO controller.
handler	Pointer to the SDIO IRQ function.
Return Value	Description
0	The SDIO IRQ is claimed.
Negative value	Failed to claim an SDIO IRQ.

The following example shows how to claim an SDIO IRQ. ``` /* Implement the SDIO IRQ function based on the application. */ static void SdioIrqFunc(void *data) { if (data == NULL) { HDF_LOGE("SdioIrqFunc: data is NULL.\n"); return; } /* You need to add specific implementations. */ } int32_t ret; /* Claim an SDIO IRQ. */ ret = SdioClaimIrq(handle, SdioIrqFunc); if (ret != 0) { HDF_LOGE("SdioClaimIrq: failed, ret %d\n", ret); } ``` ## Performing SDIO Communication - Incrementally write a given length of data into the SDIO device. The corresponding function is as follows: int32\_t SdioWriteBytes\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size\); **Table 5** Parameters and return values of SdioWriteBytes

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to write.
addr	Start address where the data is written into.
size	Length of the data to write.
Return Value	Description
0	Data is written into the SDIO device.
Negative value	Failed to write data into the SDIO device.

The following example shows how to incrementally write a given length of data into the SDIO device. ``` int32_t ret; uint8_t wbuff[] = {1,2,3,4,5}; uint32_t addr = 0x100 + 0x09; /* Incrementally write 5-byte data into the start address 0x109 of the SDIO device. */ ret = SdioWriteBytes(handle, wbuff, addr, sizeof(wbuff) / sizeof(wbuff[0])); if (ret != 0) { HDF_LOGE("SdioWriteBytes: failed, ret %d\n", ret); } ``` - Incrementally read a given length of data from the SDIO device. The corresponding function is as follows: int32\_t SdioReadBytes\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size\); **Table 6** Parameters and return values of SdioReadBytes

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to read.
addr	Start address where the data is read from.
size	Length of the data to read.
Return Value	Description
0	Data is read from the SDIO device.
Negative value	Failed to read data from the SDIO device.

The following example shows how to incrementally read a given length of data from the SDIO device. ``` int32_t ret; uint8_t rbuff[5] = {0}; uint32_t addr = 0x100 + 0x09; /* Incrementally read 5-byte data from the start address 0x109 of the SDIO device. */ ret = SdioReadBytes(handle, rbuff, addr, 5); if (ret != 0) { HDF_LOGE("SdioReadBytes: failed, ret %d\n", ret); } ``` - Write a given length of data into the fixed address of an SDIO device. The corresponding function is as follows: int32\_t SdioWriteBytesToFixedAddr\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size, uint32\_t scatterLen\); **Table 7** Parameters and return values of SdioWriteBytesToFixedAddr

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to write.
addr	Fixed address where the data is written into.
size	Length of the data to write.
scatterLen	Length of the scatter list. If the value is not 0, the data is of the scatter list type.
Return Value	Description
0	Data is written into the SDIO device.
Negative value	Failed to write data into the SDIO device.

The following example shows how to write a given length of data into the fixed address of an SDIO device. ``` int32_t ret; uint8_t wbuff[] = {1, 2, 3, 4, 5}; uint32_t addr = 0x100 + 0x09; /* Write 5-byte data into the fixed address 0x109 of the SDIO device. */ ret = SdioWriteBytesToFixedAddr(handle, wbuff, addr, sizeof(wbuff) / sizeof(wbuff[0]), 0); if (ret != 0) { HDF_LOGE("SdioWriteBytesToFixedAddr: failed, ret %d\n", ret); } ``` - Read a given length of data from the fixed address of an SDIO device. The corresponding function is as follows: int32\_t SdioReadBytesFromFixedAddr\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size, uint32\_t scatterLen\); **Table 8** Parameters and return values of SdioReadBytesFromFixedAddr

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to read.
addr	Start address where the data is read from.
size	Length of the data to read.
scatterLen	Length of the scatter list. If the value is not 0, the data is of the scatter list type.
Return Value	Description
0	Data is read from the SDIO device.
Negative value	Failed to read data from the SDIO device.

The following example shows how to read a given length of data from the fixed address of an SDIO device. ``` int32_t ret; uint8_t rbuff[5] = {0}; uint32_t addr = 0x100 + 0x09; /* Read 5-byte data from the fixed address 0x109 of the SDIO device. */ ret = SdioReadBytesFromFixedAddr(handle, rbuff, addr, 5, 0); if (ret != 0) { HDF_LOGE("SdioReadBytesFromFixedAddr: failed, ret %d\n", ret); } ``` - Write a given length of data into the address space of SDIO function 0. Currently, only 1-byte data can be written. The corresponding function is as follows: int32\_t SdioWriteBytesToFunc0\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size\); **Table 9** Parameters and return values of SdioWriteBytesToFunc0

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to write.
addr	Start address where the data is written into.
size	Length of the data to write.
Return Value	Description
0	Data is written into the SDIO device.
Negative value	Failed to write data into the SDIO device.

The following example shows how to write a given length of data into the address space of SDIO function 0. ``` int32_t ret; uint8_t wbuff = 1; /* Write 1-byte data into the address 0x2 of SDIO function 0. */ ret = SdioWriteBytesToFunc0(handle, &wbuff, 0x2, 1); if (ret != 0) { HDF_LOGE("SdioWriteBytesToFunc0: failed, ret %d\n", ret); } ``` - Read a given length of data from the address space of SDIO function 0. Currently, only 1-byte data can be read. The corresponding function is as follows: int32\_t SdioReadBytesFromFunc0\(DevHandle handle, uint8\_t \*data, uint32\_t addr, uint32\_t size\); **Table 10** Parameters and return values of SdioReadBytesFromFunc0

Parameter	Description
handle	Device handle of an SDIO controller.
data	Pointer to the data to read.
addr	Start address where the data is read from.
size	Length of the data to read.
Return Value	Description
0	Data is read from the SDIO device.
Negative value	Failed to read data from the SDIO device.

The following example shows how to read a given length of data from the address space of SDIO function 0. ``` int32_t ret; uint8_t rbuff; /* Read 1-byte data from the address 0x2 of SDIO function 0. */ ret = SdioReadBytesFromFunc0(handle, &rbuff, 0x2, 1); if (ret != 0) { HDF_LOGE("SdioReadBytesFromFunc0: failed, ret %d\n", ret); } ``` ## Releasing the SDIO IRQ After the SDIO communication, release the SDIO IRQ. int32\_t SdioReleaseIrq\(DevHandle handle\); **Table 11** Parameters and return values of SdioReleaseIrq

Parameter	Description
handle	Device handle of an SDIO controller.
Return Value	Description
0	The SDIO IRQ is released.
Negative value	Failed to release the SDIO IRQ.

The following example shows how to release the SDIO IRQ. ``` int32_t ret; /* Release the SDIO IRQ. */ ret = SdioReleaseIrq(handle); if (ret != 0) { HDF_LOGE("SdioReleaseIrq: failed, ret %d\n", ret); } ``` ## Disabling the SDIO Device After the SDIO communication, disable the SDIO device. int32\_t SdioDisableFunc\(DevHandle handle\); **Table 12** Parameters and return values of SdioDisableFunc

Parameter	Description
handle	Device handle of an SDIO controller.
Return Value	Description
0	The SDIO device is disabled.
Negative value	Failed to disable the SDIO device.

The following example shows how to disable the SDIO device. ``` int32_t ret; /* Disable the SDIO device. */ ret = SdioDisableFunc(handle); if (ret != 0) { HDF_LOGE("SdioDisableFunc: failed, ret %d\n", ret); } ``` ## Releasing the Exclusively Claimed Host After the SDIO communication, release the exclusively claimed host. void SdioReleaseHost\(DevHandle handle\); **Table 13** Parameter description of SdioReleaseHost

Parameter	Description
handle	Device handle of an SDIO controller.

The following example shows how to release the exclusively claimed host. ``` SdioReleaseHost(handle); /* Release the exclusively claimed host. */ ``` ## Closing an SDIO Controller After the SDIO communication, close the SDIO controller. void SdioClose\(DevHandle handle\); This function releases the resources requested. **Table 14** Parameter description of SdioClose

Parameter	Description
handle	Device handle of an SDIO controller.

The following example shows how to close an SDIO controller. ``` SdioClose(handle); /* Close an SDIO controller. */ ```