# FSDMMC 驱动程序 ## 1. 概述 SD/MMC控制器主要提供对固态非易失性存储的内存卡的访问能力，包括多媒体存储卡（MMC，MultiMedia Card）和安全和数据保护卡（SD，Secure Digital Card）。 ## 2. 功能 SD/MMC控制器驱动提供了SD/MMC卡的控制访问方法， - 初始化SD/MMC控制器 - 以轮询方式发送/接收数据和命令 - 以中断方式发送/接收数据和命令 - 设置SD/MMC控制器的中断工作模式和中断响应函数 访问SD/MMC卡需要兼容一系列协议命令，这一部分驱动不提供，可以通过第三方框架sdmmc使用 驱动相关的源文件包括， ``` fsdmmc ├── fsdmmc.c ├── fsdmmc.h ├── fsdmmc_dma.c ├── fsdmmc_dma.h ├── fsdmmc_g.c ├── fsdmmc_hw.c ├── fsdmmc_hw.h ├── fsdmmc_intr.c └── fsdmmc_sinit.c ``` ## 3. 配置方法 以下部分将指导您完成 FSDMMC 驱动的软件配置: - 初始化FSDMMC控制器 - 通过协议命令完成SD/MMC卡初始化 - 通过协议命令读写SD/MMC卡数据 ## 4 应用示例 ### [检测SD卡](../../../baremetal/example/peripheral/mmc/fsdmmc_probe) ### [SD/MMC卡协议实现](../../../third-party/sdmmc) ### [通过协议命令读写SD卡](../../../baremetal/example/storage/sdmmc_cmds) ### [通过文件系统使用SD卡](../../../baremetal/example/storage/sdmmc_fatfs) ## 5. API参考 ### 5.1. 用户数据结构 - FSDMMC控制数据 ```c typedef struct { FSdmmcConfig config; /* Current active configs */ u32 is_ready; /* Device is initialized and ready */ FSdmmcEventHandler evt_handler[FSDMMC_EVT_NUM]; } FSdmmc; /* Device instance */ ``` - FSDMMC配置数据 ```c typedef struct { u32 instance_id; /* Device instance id */ uintptr base_addr; /* Device base address */ u32 irq_num[FSDMMC_INTR_NUM]; } FSdmmcConfig; ``` - FSDMMC命令结构 ```c typedef struct { u32 cmdidx; u32 cmdarg; u32 resptype; u32 response[4]; u32 flag; #define FSDMMC_CMD_FLAG_NEED_STOP BIT(0) #define FSDMMC_CMD_FLAG_NEED_INIT BIT(1) #define FSDMMC_CMD_FLAG_EXP_RESP BIT(2) #define FSDMMC_CMD_FLAG_EXP_LONG_RESP BIT(3) #define FSDMMC_CMD_FLAG_NEED_RESP_CRC BIT(4) #define FSDMMC_CMD_FLAG_EXP_DATA BIT(5) #define FSDMMC_CMD_FLAG_WRITE_DATA BIT(6) #define FSDMMC_CMD_FLAG_READ_DATA BIT(7) #define FSDMMC_CMD_FLAG_NEED_AUTO_STOP BIT(8) #define FSDMMC_CMD_FLAG_ADTC BIT(9) FSdmmcData *data_p; } FSdmmcCmd; ``` - FSDMMC数据结构 ```c typedef struct { u8 *buf; u32 blksz; u32 blkcnt; u32 datalen; } FSdmmcData; ``` - FSDMMC中断类型和中断事件 ```c enum { FSDMMC_DMA_BD_INTR = 0, FSDMMC_CMD_INTR, FSDMMC_ERROR_INTR, FSDMMC_INTR_NUM }; /* 中断类型 */ enum { FSDMMC_EVT_CARD_REMOVED = 0, FSDMMC_EVT_CMD_DONE, FSDMMC_EVT_CMD_ERROR, FSDMMC_EVT_CMD_RESP_ERROR, FSDMMC_EVT_DATA_ERROR, FSDMMC_EVT_DATA_READ_DONE, FSDMMC_EVT_DATA_WRITE_DONE, FSDMMC_EVT_NUM }; /* 事件类型 */ ``` ### 5.2 错误码定义 - [0x0] FSDMMC_SUCCESS : success - [0x10c0001] FSDMMC_ERR_NOT_READY : FSDMMC控制器未初始化 - [0x10c0001] FSDMMC_ERR_TIMEOUT : 数据或者命令传输等待超时 - [0x10c0001] FSDMMC_ERR_CMD_FAILED : 命令传输失败 - [0x10c0001] FSDMMC_ERR_DATA_FAILED : 数据传输失败 - [0x10c0001] FSDMMC_ERR_CARD_NO_FOUND : 卡未检测到 - [0x10c0001] FSDMMC_ERR_INVALID_BUF : 数据缓冲区不合法 ### 5.3. 用户API接口 #### FSdmmcLookupConfig - 获取FSDMMC控制器默认配置 ```c const FSdmmcConfig *FSdmmcLookupConfig(u32 instance_id); ``` Note: - instance_id从0开始，取决于FSDMMC控制器的个数 Input: - {u32} instance_id 驱动控制器ID Return: - {const FSdmmcConfig *} FSDMMC默认配置，返回NULL如果找不到默认配置 #### FSdmmcCfgInitialize - 初始化FSDMMC控制器, 使之可以使用 ```c FError FSdmmcCfgInitialize(FSdmmc *instance_p, const FSdmmcConfig *input_config_p); ``` Note: - 输入配置通过FSdmmcLookupConfig获取，用户按照需要修改后传入此函数 Input: - {FSdmmc} *instance_p FSDMMC驱动控制数据 - {FSdmmcConfig} *input_config_p FSDMMC用户输入配置 Return: - {FError} 驱动初始化的错误码信息，FSDMMC_SUCCESS 表示初始化成功，其它返回值表示初始化失败 #### FSdmmcDeInitialize - 去使能FSDMMC控制器, 清零实例数据 ```c void FSdmmcDeInitialize(FSdmmc *instance_p); ``` Note: - 无 Input: - {FSdmmc} *instance_p FSDMMC驱动控制数据 Return: - 无 #### FSdmmcPollTransfer - 通过FSDMMC轮询方式发送/接收数据和命令 ```c FError FSdmmcPollTransfer(FSdmmc *instance_p, FSdmmcCmd *cmd_data_p); ``` Note: - FSDMMC控制器初始化后才能调用此函数 Input: - {FSdmmc} *instance_p FSDMMC驱动控制数据 - {FSdmmcCmd} *cmd_data_p FSDMMC数据和命令 Return: - {FError} 驱动初始化的错误码信息，FSDMMC_SUCCESS 表示发送/接收成功，其它返回值表示发送/接收失败 #### FSdmmcInterruptTransfer - 通过FSDMMC中断方式发送/接收数据和命令 ```c FError FSdmmcInterruptTransfer(FSdmmc *instance_p, FSdmmcCmd *cmd_data_p); ``` Note: - FSDMMC控制器初始化后才能调用此函数，使用前需要确保FSDMMC中断设置完成 Input: - {FSdmmc} *instance_p FSDMMC驱动控制数据 - {FSdmmcCmd} *cmd_data_p FSDMMC数据和命令 Return: - {FError} 驱动初始化的错误码信息，FSDMMC_SUCCESS 表示发送/接收成功，其它返回值表示发送/接收失败 #### FSdmmcGetInterruptMask - 获取FSDMMC的中断掩码 ```c u32 FSdmmcGetInterruptMask(uintptr base_addr, u32 intr_type); ``` Note: - FSDMMC控制器初始化后才能调用此函数 Input: - {uintptr} base_addr FSDMMC控制器基地址 - {u32} intr_type FSDMMC中断类型, 参考FSDMMC_INTR_NUM Return: - {u32} 中断掩码 #### FSdmmcSetInterruptMask - 设置FSDMMC的中断掩码 ```c void FSdmmcSetInterruptMask(uintptr base_addr, u32 intr_type, u32 mask, boolean enable); ``` Note: - FSDMMC控制器初始化后才能调用此函数 Input: - {uintptr} base_addr FSDMMC控制器基地址 - {u32} intr_type FSDMMC中断类型, 参考FSDMMC_INTR_NUM - {u32} mask 中断掩码 - {boolean} enable TRUE:打开中断, FALSE:关闭中断 Return: - 无 #### FSdmmcCmdInterrupHandler - 命令中断响应函数 ```c void FSdmmcCmdInterrupHandler(s32 vector, void *param); ``` Note: - 此函数用于设置FSDMMC中断时注册，用户可以自定义一个中断响应函数替换此函数 Input: - vector 中断向量号 - {void} *param 中断响应输入参数 Return: - 无 #### FSdmmcDmaInterrupHandler - DMA中断响应函数 ```c void FSdmmcDmaInterrupHandler(s32 vector, void *param); ``` Note: - 此函数用于设置FSDMMC中断时注册，用户可以自定义一个中断响应函数替换此函数 Input: - {s32} vector 中断向量号 - {void} *param 中断响应输入参数 Return: - 无 #### FSdmmcErrInterrupHandler - 错误中断响应函数 ```c void FSdmmcErrInterrupHandler(s32 vector, void *param); ``` Note: - 此函数用于设置FSDMMC中断时注册，用户可以自定义一个中断响应函数替换此函数 Input: - {s32} vector 中断向量号 - {void} *param 中断响应输入参数 Return: - 无 #### FSdmmcRegisterInterruptHandler - 注册中断事件响应函数 ```c void FSdmmcRegisterInterruptHandler(FSdmmc *instance_p, u32 event, FSdmmcEventHandler handler); ``` Note: - 此函数用于设置FSDMMC中断时注册，被注册的函数被FSdmmcCmdInterrupHandler、FSdmmcErrInterrupHandler * 和FSdmmcDmaInterrupHandler调用 Input: - {FSdmmc} *instance_p FSDMMC驱动控制数据 - {u32} event FSDMMC中断事件类型，参考FSDMMC_EVT_NUM - {FSdmmcEventHandler} handler, FSDMMC中断事件响应函数 Return: - 无