【SD卡专栏】STM32官方代码（SD卡驱动）注释欣赏
本文欣赏 STM32 官方 EVAL 开发板给出的SD卡例程的代码注释。
1. 在函数部分之前，将D.M.V.F（定义、宏、变量、函数）在文档之前全部用注释表明清楚，罗列好。
1 /* Private macro -------------------------------------------------------------*/ 2 /** 3 * @brief SDIO Static flags, TimeOut, FIFO Address 4 */ 5 #define NULL 0 6 #define SDIO_STATIC_FLAGS ((uint32_t)0x000005FF) 7 #define SDIO_CMD0TIMEOUT ((uint32_t)0x00010000) 8 ... 9 /* Private variables ---------------------------------------------------------*/ 10 static uint32_t CardType = SDIO_STD_CAPACITY_SD_CARD_V1_1; //存储卡的类型，先把它初始化为1.1协议的卡 11 static uint32_t CSD_Tab[4], CID_Tab[4], RCA = 0;//存储CSD，DID，寄存器和卡相对地址 12 ..... 13 14 /* Private function prototypes -----------------------------------------------*/ 15 static SD_Error CmdError(void); 16 static SD_Error CmdResp1Error(uint8_t cmd); 17 static SD_Error CmdResp7Error(void); 18 ...
2. 每个函数都有简介说明，和输入、输出参数的罗列和说明，有的甚至有函数的输入可选的参数的说明。
SD_DMA_RxConfig 包含输入参数的说明。
1 /* 2 * 函数名：SD_DMA_RxConfig 3 * 描述 ：为SDIO接收数据配置DMA2的通道4的请求 4 * 输入 ：BufferDST：用于装载数据的变量指针 5 * : BufferSize： 缓冲区大小 6 * 输出 ：无 7 */ 8 void SD_DMA_RxConfig(uint32_t *BufferDST, uint32_t BufferSize) 9 { 10 DMA_InitTypeDef DMA_InitStructure; 11 12 DMA_ClearFlag(DMA2_FLAG_TC4 | DMA2_FLAG_TE4 | DMA2_FLAG_HT4 | DMA2_FLAG_GL4);//清除DMA标志位 13 .... 14 }
SD_Init 包含输出参数的说明。
1 /** 2 * 函数名：SD_Init 3 * 描述 ：初始化SD卡，使卡处于就绪状态(准备传输数据) 4 * 输入 ：无 5 * 输出 ：-SD_Error SD卡错误代码 6 * 成功时则为 SD_OK 7 * 调用 ：外部调用 8 */ 9 SD_Error SD_Init(void) 10 { 11 /*重置SD_Error状态*/ 12 SD_Error errorstatus = SD_OK; 13 14 NVIC_Configuration(); 15 ... 16 }
3. 对于状态，由于状态是有限可选的数据类型，因此采用枚举定义。
1 typedef enum {FAILED = 0, PASSED = !FAILED} TestStatus; 2 volatile TestStatus EraseStatus = FAILED, TransferStatus1 = FAILED, TransferStatus2 = FAILED;
4. 整个文件有日期、版本、简介、作者、文件路径等信息
/** ****************************************************************************** * @file SDIO/uSDCard/main.c * @author MCD Application Team * @version V3.5.0 * @date 08-April-2011 * @brief Main program body ****************************************************************************** * @attention ..... */
