1. 项目背景与核心价值最近在做一个基于ZYNQ的嵌入式数据采集项目需要把传感器采集到的大量数据实时存储到SD卡里然后在PS端Processing System也就是ARM Cortex-A9核心进行读取和处理。听起来是个挺常见的需求对吧但真动手做的时候发现网上关于ZYNQ PS端SD卡文件读取的完整、可用的代码示例要么语焉不详要么就是只给个函数名关键的驱动配置、文件系统挂载、错误处理这些细节一概没有。踩了几个坑之后我决定把整个流程从硬件配置到软件代码再到调试过程中遇到的那些“坑”完整地梳理出来。这篇文章就是这份“踩坑实录”的总结目标是给你一份从零开始、能直接编译运行的完整代码和操作指南让你在ZYNQ上玩转SD卡文件读取时能少走点弯路。这个项目的核心就是在ZYNQ的PS端通过SDIO控制器对插入的SD卡或MicroSD卡进行文件级别的读写操作。这不仅仅是简单的底层寄存器操作更涉及到驱动初始化、文件系统挂载通常是FATFS、标准C库文件操作API的使用以及如何将这些环节无缝集成到你的应用中。无论是用于加载配置文件、记录日志还是像我的项目一样处理采集的数据这都是一个非常基础且关键的功能。下面我就从硬件设计开始一步步带你走通整个流程。2. 硬件平台设计与Vivado工程配置在开始写代码之前硬件平台的正确配置是基石。ZYNQ的PS端已经集成了SD/SDIO控制器SD0我们通常就是用它来连接SD卡槽。2.1 Vivado中PS端SDIO外设的启用与引脚分配首先打开Vivado我用的版本是2019.2其他版本大同小异创建一个新的工程选择你的ZYNQ芯片型号例如XC7Z010。在Block Design中添加ZYNQ7 Processing System IP核。双击这个IP核进行配置这是最关键的一步。在弹出来的重定制Re-customize IP界面里你需要关注两个地方MIO配置在“Peripheral I/O Pins”标签页下找到“SD 0”这一项。把它勾选上。这时Vivado会自动为SD0分配一组MIOMultiplexed I/O引脚。对于最常见的SD卡模式4位数据线这通常是MIO 40到MIO 45。其中MIO 40: SD0_CLK (时钟)MIO 41: SD0_CMD (命令)MIO 42: SD0_DAT[0] (数据线0)MIO 43: SD0_DAT[1] (数据线1)MIO 44: SD0_DAT[2] (数据线2)MIO 45: SD0_DAT[3] (数据线3) 务必确认你的开发板原理图上SD卡槽的这6根信号线确实连接到了ZYNQ PS端的这组MIO上。有些板子可能用了EMIO即通过PL引出的PS IO那配置会更复杂一些本文以最通用的MIO连接为例。时钟配置SDIO控制器需要一个时钟。在“Clock Configuration”标签页下找到“SD 0”的时钟设置。你需要确保“SDIO Clock Frequency”设置在一个合理的范围内比如50MHz或100MHz。同时在“Input Clock Frequency”中为SDIO的参考时钟例如FCLK_CLK0设置一个频率Vivado内部的时钟分频器会基于此产生SDIO时钟。一个常见的配置是ARM PLL提供100MHz的FCLK_CLK0然后SDIO时钟分频设置为2得到50MHz的SDIO操作时钟。注意SD卡本身有工作频率限制在初始化阶段识别卡阶段必须使用低速时钟通常400kHz初始化完成后才能切换到高速模式如25MHz或50MHz。不过这个高低速切换是由SD卡驱动如Xilinx提供的xsdps驱动在底层自动完成的我们只需要在Vivado中配置一个足够高的基准时钟频率即可驱动会自己去分频。配置完成后点击OK在Block Design中为ZYNQ IP核自动连接时钟和复位信号然后Validate Design。没问题的话就可以Create HDL Wrapper然后生成比特流文件Generate Bitstream。虽然我们主要用PS端PL端可能没逻辑但生成比特流是导出硬件信息XSA文件的必要步骤。2.2 导出硬件平台与XSA文件比特流生成成功后在菜单栏选择File - Export - Export Hardware...。在弹出窗口中务必勾选“Include bitstream”然后指定导出路径。这一步会生成一个.xsa(Xilinx Support Archive) 文件。这个文件包含了我们刚才在Vivado中配置的所有硬件信息是后续在Vitis或SDK中创建平台工程Platform Project和应用程序工程Application Project的基础。至此硬件部分的工作就完成了。接下来我们将进入软件开发的环节。3. Vitis软件开发环境搭建与BSP配置拿到.xsa文件后我们就可以打开Vitis或旧版的Xilinx SDK进行软件开发了。这里以Vitis 2019.2为例。3.1 创建平台工程与应用工程创建工作空间启动Vitis选择一个空文件夹作为工作空间Workspace。创建平台工程File - New - Platform Project。输入工程名例如zynq_sd_platform。点击Next在“Hardware Specification”页面点击“Browse”选择我们刚才导出的.xsa文件。其他设置可以保持默认点击Finish。Vitis会基于这个XSA文件生成对应的硬件平台。生成平台在左侧的Explorer视图中右键点击刚才创建的平台工程选择“Build Project”。这会为我们的硬件平台生成设备树Device Tree、FSBLFirst Stage Bootloader等必要的支持文件。创建应用工程File - New - Application Project。输入工程名例如sd_card_read_test。点击Next在“Platform”页面选择我们刚刚创建并构建好的平台zynq_sd_platform。点击Next选择“Empty Application”模板。点击Finish。现在我们有了一个空的应用工程。接下来需要配置板级支持包BSP。3.2 配置板级支持包BSP中的SD卡驱动与文件系统在Vitis中应用工程下面会有一个[工程名]_bsp的文件夹这就是该应用的板级支持包。右键点击它选择“Board Support Package Settings”。驱动配置在“Overview”页面找到“drivers”部分。这里应该能看到ps7_sd_0已经被分配了驱动xsdps。xsdps是Xilinx提供的标准SD/SDIO驱动支持SD卡规范。通常不需要改动但你可以点击它进入详细配置。在xsdps的配置中可以检查或修改一些参数比如Has CD你的SD卡槽是否有卡检测Card Detect引脚如果有且接到了PS的MIO上需要在这里启用并指定MIO编号。很多开发板为了简化没有使用硬件CD而是靠软件检测这里就选false。Has WP写保护检测同理通常为false。Slot Type选择SD 2.0或SD 3.0根据你的卡和需求选择。选SD 3.0通常兼容性更好。文件系统配置关键在左侧导航栏找到并展开“standalone”。这里有一个至关重要的组件xilffs。这就是Xilinx提供的FAT文件系统库。你必须确保它被勾选并添加到BSP中。如果没有点击“Modify BSP Settings”在“Overview”的可用库列表里找到xilffs并勾选它。 添加xilffs后在“standalone”下会出现它的配置项。点击xilffs进行关键配置fs_interface选择PS_SD0。这告诉文件系统库底层存储设备是PS端的SD0控制器。use_lfn是否使用长文件名。建议设置为true这样支持超过8.3格式的文件名。read_only是否只读。根据你的需求设置我们做读取测试可以先设为false。enable_multi_partition是否支持多分区。通常SD卡只有一个FAT分区设为false即可。配置完成后点击“OK”关闭BSP设置窗口。Vitis会自动重新编译BSP将SD卡驱动和FATFS文件系统库链接到你的应用程序中。4. 核心代码实现从驱动初始化到文件读取BSP配置好之后我们就可以在src文件夹下创建主程序文件例如main.c了。下面的代码是一个完整的、可直接运行的示例实现了SD卡的初始化、文件系统挂载、文件读取和卸载。/** * file main.c * brief ZYNQ PS端SD卡文件读取完整示例 * details 此代码演示了如何在ZYNQ PS端初始化SD卡、挂载FAT文件系统、打开文件、读取内容并打印。 */ #include stdio.h #include xparameters.h // 硬件参数定义 #include xsdps.h // SD卡驱动头文件 #include ff.h // FATFS文件系统头文件 #include xil_printf.h /************************** 常量定义 **************************/ #define SD_DEVICE_ID XPAR_XSDPS_0_DEVICE_ID // SD0的设备ID在xparameters.h中定义 #define FILE_NAME 0:/testfile.txt // 要读取的文件路径。0: 是FATFS中物理驱动器0的标识符 #define BUFFER_SIZE 512 // 读取缓冲区大小 /************************** 变量声明 **************************/ static XSdPs SdInstance; // SD卡驱动实例 static FATFS fatfs; // FATFS文件系统对象 static FIL file; // 文件对象 static char read_buffer[BUFFER_SIZE]; // 文件读取缓冲区 UINT bytes_read; // 实际读取到的字节数 FRESULT fresult; // 文件系统操作结果 int status; // 驱动操作状态 /************************** 主函数 **************************/ int main(void) { xil_printf(ZYNQ SD Card File Read Test Start...\r\n); /* 1. 初始化SD卡驱动 */ status XSdPs_CfgInitialize(SdInstance, XSdPs_LookupConfig(SD_DEVICE_ID), XPAR_XSDPS_0_BASEADDR); if (status ! XST_SUCCESS) { xil_printf(ERROR: Failed to initialize SD driver.\r\n); return XST_FAILURE; } xil_printf(SD Driver Initialized Successfully.\r\n); /* 2. 配置SD卡为4位总线模式并识别卡 */ status XSdPs_CardInitialize(SdInstance); if (status ! XST_SUCCESS) { xil_printf(ERROR: Failed to initialize SD card. Please check if the card is inserted.\r\n); // 可以在这里添加重试逻辑 return XST_FAILURE; } xil_printf(SD Card Identified. Capacity: %llu MB\r\n, (XSdPs_GetSdCardInfo(SdInstance)-CardCapacity) 20); // 容量单位转换 /* 3. 挂载文件系统 */ fresult f_mount(fatfs, 0:/, 1); // “1”表示立即挂载强制挂载 if (fresult ! FR_OK) { xil_printf(ERROR: Failed to mount filesystem. FRESULT %d\r\n, fresult); // 常见错误FR_NO_FILESYSTEM (13) - 卡没有有效的FAT文件系统需要格式化 // FR_DISK_ERR (1) - 底层磁盘访问错误检查硬件连接 return XST_FAILURE; } xil_printf(FATFS mounted successfully.\r\n); /* 4. 打开文件 */ fresult f_open(file, FILE_NAME, FA_READ); // 以只读方式打开 if (fresult ! FR_OK) { xil_printf(ERROR: Failed to open file %s. FRESULT %d\r\n, FILE_NAME, fresult); // 常见错误FR_NO_FILE (4) - 文件不存在 // FR_NO_PATH (3) - 路径错误 f_unmount(0:/); // 关闭文件系统前先卸载 return XST_FAILURE; } xil_printf(File %s opened successfully.\r\n, FILE_NAME); /* 5. 读取文件内容并打印 */ xil_printf(File content:\r\n); xil_printf(----------------------------------------\r\n); do { fresult f_read(file, read_buffer, BUFFER_SIZE, bytes_read); if (fresult ! FR_OK) { xil_printf(\r\nERROR: Failed to read file. FRESULT %d\r\n, fresult); break; } // 将读取到的字节以字符串形式打印假设文件是文本文件 for (UINT i 0; i bytes_read; i) { xil_printf(%c, read_buffer[i]); } } while (bytes_read BUFFER_SIZE); // 循环读取直到读完文件 xil_printf(\r\n----------------------------------------\r\n); xil_printf(File read completed.\r\n); /* 6. 关闭文件和卸载文件系统 */ fresult f_close(file); if (fresult ! FR_OK) { xil_printf(WARNING: Failed to close file. FRESULT %d\r\n, fresult); } fresult f_unmount(0:/); if (fresult ! FR_OK) { xil_printf(WARNING: Failed to unmount filesystem. FRESULT %d\r\n, fresult); } xil_printf(SD Card File Read Test Finished.\r\n); return XST_SUCCESS; }4.1 代码关键点解析与避坑指南这段代码逻辑清晰但有几个地方是新手极易出错的重灾区设备ID与基地址XPAR_XSDPS_0_DEVICE_ID和XPAR_XSDPS_0_BASEADDR这两个宏定义来自于BSP自动生成的xparameters.h文件。绝对不要自己硬编码数字。Vitis会根据你的硬件设计自动分配这些值。直接使用这些宏是最安全的方式。文件路径中的“0:”在FATFS中“0:”代表第一个物理驱动器。当我们把fs_interface配置为PS_SD0后这个驱动器就映射到了我们的SD卡。所以文件路径必须是“0:/filename”或“0:/dir/filename”的形式。开头的“0:/”是必须的它指向根目录。f_mount的第二个参数这个参数是逻辑驱动器路径同样需要带上“0:”。第三个参数是1代表立即挂载。如果设为0则是延迟挂载只在首次访问驱动器时才执行挂载操作。对于简单的应用直接设为1更稳妥。错误处理代码中对每一步操作都进行了错误检查并打印了FRESULT文件系统结果码或驱动状态码。这是调试时最重要的信息。你需要一份ff.h头文件中的FRESULT枚举定义或者去查FATFS文档才能知道每个数字代表什么错误。比如FR_NO_FILESYSTEM (13)意味着卡没有被正确格式化不是FAT16/FAT32/exFAT格式。卡容量打印XSdPs_GetSdCardInfo函数返回的容量单位是字节。我们通过右移20位除以2^20来转换为MB单位。这是一个很方便的调试信息可以确认系统是否正确识别了你的SD卡。5. 实战调试常见问题与解决方案即使代码看起来没问题第一次运行时也大概率会遇到各种错误。下面是我在调试过程中遇到的一些典型问题及其解决方法。5.1 SD卡初始化失败XSdPs_CardInitialize返回错误这是最常见的问题现象是程序打印“Failed to initialize SD card”后卡住或退出。检查硬件连接首先也是最基础的确认SD卡已完全插入卡槽。有些卡槽比较紧需要听到“咔哒”声。用万用表量一下MIO引脚到卡槽的连通性排除虚焊或断线。检查电源SD卡需要稳定的3.3V供电。用示波器测量一下卡槽的VCC引脚看电压是否稳定在3.3V上电瞬间有无大的跌落。有些开发板的SD卡供电电路带载能力不足换一张小容量的SD卡比如2GB试试或者给板子的电源接口提供更充足的电流。检查时钟频率回顾在Vivado中为SDIO控制器配置的时钟频率。如果设置得过高比如超过100MHz在初始化阶段可能会失败。尝试在Vivado中降低SDIO Clock Frequency例如设为25MHz重新生成比特流和XSA文件再测试。更换SD卡不同的SD卡尤其是不同品牌、不同等级、不同容量的初始化时序和兼容性可能有差异。准备一张标准容量SDSC ≤2GB的卡和一张高容量SDHC 4GB-32GB的卡进行测试。有些旧版驱动或硬件对SDXC32GB卡支持不好。强烈建议在开发阶段使用一张知名品牌的、已格式化为FAT32的4GB或8GB SDHC卡这是兼容性最好的选择。检查MIO配置再次确认Vivado中SD0的MIO引脚分配必须和开发板原理图完全一致。如果板子用了MIO 46~51或其他一组你需要在这里修改而不是用默认的40~45。5.2 文件系统挂载失败f_mount返回非FR_OK如果SD卡驱动初始化成功打印出了卡容量但挂载文件系统失败问题通常出在卡的文件系统格式上。错误码FR_NO_FILESYSTEM(13)这明确表示SD卡上没有找到有效的FAT文件系统。解决方案就是格式化SD卡。格式化工具不要在Linux下用mkfs命令简单格式化建议使用Windows系统自带的格式化工具或者像“SD Card Formatter”这样的专用工具。格式化参数务必选择FAT32格式分配单元大小选择“默认大小”或“4096字节”。不要用exFAT或NTFS早期的xilffs库可能不支持。格式化后将你的测试文件如testfile.txt复制到SD卡的根目录。错误码FR_DISK_ERR(1)底层磁盘访问错误。这可能是硬件问题如接触不良、信号完整性差的延续也可能是驱动初始化其实不彻底。可以尝试在f_mount之前加入一小段延时例如usleep(100000)让硬件状态更稳定。检查BSP中的xilffs配置确保fs_interface确实设置为PS_SD0。一个低级错误是这里选成了GENERIC或别的接口。5.3 文件打开失败f_open返回FR_NO_FILE挂载成功了但打不开文件。确认文件路径和名称检查代码中FILE_NAME宏定义的文件名是否和SD卡根目录下的文件名完全一致包括大小写。在FATFS中如果use_lfn设置为false则只支持8.3格式的短文件名如TESTFILE.TXT。确认文件确实存在将SD卡拔下来插到电脑上确认文件确实在根目录。尝试绝对路径虽然根目录下可以直接用文件名但为了保险可以尝试使用“0:/testfile.txt”这样的绝对路径。5.4 程序运行无输出或卡死如果连“SD Card File Read Test Start...”都没打印问题可能更底层。确认串口终端首先确认你的串口终端软件如Putty、Tera Term配置是否正确波特率通常为115200、数据位、停止位、校验位以及是否正确连接到了ZYNQ的UART端口通常是PS端的MIO 48, 49。检查启动模式ZYNQ的启动模式跳线是否设置正确对于从SD卡启动FSBL和应用程序的情况需要设置为SD模式。如果是调试阶段通过JTAG下载程序则启动模式可以是JTAG。但无论如何串口应该是工作的。简化测试可以先不进行SD卡操作只写一个简单的“Hello World”程序通过串口打印来验证最基本的PS端、DDR内存、UART和Vitis工程配置是否正确。6. 进阶话题性能优化与可靠性设计当基本功能跑通后我们可能会关心如何读得更快、更稳。这里分享几个进阶的考量点。6.1 提升读取速度默认的f_read是单次读取对于大文件频繁调用会有开销。同时SD卡驱动本身有一些可调参数。增大读取缓冲区如代码中的BUFFER_SIZE可以适当增大比如设置为2048或4096字节减少函数调用次数。使用多扇区读写XSdPs驱动支持配置多扇区传输Block Count。在BSP的xsdps驱动高级配置中可以找到相关选项。启用后驱动会在一次命令中传输多个数据块显著提升连续读写的吞吐量。提高SDIO时钟频率在确保硬件信号质量布线良好无过冲振铃的前提下可以在Vivado中尝试提高SDIO控制器的运行频率例如从50MHz提升到100MHz需参考芯片手册和SD卡规范的支持上限。使用DMASDIO控制器支持DMA传输。在BSP的xsdps驱动配置中确保DMA被启用。这可以将数据搬运任务 offload 给DMA控制器减轻CPU负担并在传输大块数据时提升效率。6.2 增强代码健壮性产品化代码需要考虑更多异常情况。添加重试机制对于XSdPs_CardInitialize和f_mount这类操作可以封装在一个带超时和重试次数的循环中。因为SD卡接触瞬间可能不稳定或者上电时序稍有偏差重试几次可能就成功了。int retry_count 3; while (retry_count--) { status XSdPs_CardInitialize(SdInstance); if (status XST_SUCCESS) break; usleep(500000); // 延迟500ms再试 xil_printf(“Retrying SD card initialization… %d attempts left\r\n”, retry_count); } if (status ! XST_SUCCESS) { /* 处理最终失败 */ }检查写保护与卡在位状态如果你的硬件支持卡检测CD和写保护WP引脚可以在BSP中启用它们并在代码中通过XSdPs_GetPresentStatus()和XSdPs_GetWriteProtectStatus()等API进行状态检查在用户拔卡或写保护打开时给出友好提示。安全卸载在程序退出或需要移除SD卡前务必确保所有文件都已关闭f_close并且文件系统已卸载f_unmount。直接断电或热拔插可能导致文件系统损坏。f_unmount函数会同步缓存数据到物理介质。处理大文件与长路径确保xilffs配置中use_lfn启用以支持长文件名。对于非常大的文件注意f_read返回的bytes_read可能小于请求的字节数例如到达文件尾循环读取的逻辑需要正确处理这种情况。6.3 集成到更复杂的应用框架中在实际项目中SD卡读写可能只是模块之一。你需要考虑如何将这部分代码优雅地集成。封装为独立模块将SD卡初始化、挂载、文件操作等函数封装到一个单独的.c/.h文件对中例如sd_card.c和sd_card.h。对外提供清晰的接口如SD_Init(),SD_ReadFile(),SD_WriteFile()并隐藏内部全局变量如SdInstance,fatfs。与FreeRTOS结合如果你的应用运行在FreeRTOS上需要特别注意FATFS的重入Re-entrancy问题。标准的xilffs可能不是线程安全的。你需要启用FATFS配置中的_FS_REENTRANT选项并提供操作系统相关的同步信号量函数如ff_mutex_create,ff_mutex_lock等。Xilinx有时会提供适配FreeRTOS的FATFS版本或者你需要自己实现这些接口。错误日志记录将操作失败时的FRESULT或驱动错误码记录到非易失性存储器如EEPROM或通过网络发送出去便于现场问题诊断。从硬件引脚配置到驱动和文件系统库的BSP设置再到应用层代码的编写和调试最后到性能与可靠性的打磨在ZYNQ PS端实现一个稳定可靠的SD卡文件读取功能需要贯穿整个软硬件链条的细致操作。希望这份超详细的指南和完整的代码能帮你一次性打通这个环节把精力更多地投入到上层更有趣的应用开发中去。如果在实际操作中遇到了上面没覆盖到的问题不妨从最基础的硬件连接和SD卡格式化开始配合串口打印的错误码一步步缩小排查范围问题总能解决的。
1. 项目背景与核心价值最近在做一个基于ZYNQ的嵌入式数据采集项目需要把传感器采集到的大量数据实时存储到SD卡里然后在PS端Processing System也就是ARM Cortex-A9核心进行读取和处理。听起来是个挺常见的需求对吧但真动手做的时候发现网上关于ZYNQ PS端SD卡文件读取的完整、可用的代码示例要么语焉不详要么就是只给个函数名关键的驱动配置、文件系统挂载、错误处理这些细节一概没有。踩了几个坑之后我决定把整个流程从硬件配置到软件代码再到调试过程中遇到的那些“坑”完整地梳理出来。这篇文章就是这份“踩坑实录”的总结目标是给你一份从零开始、能直接编译运行的完整代码和操作指南让你在ZYNQ上玩转SD卡文件读取时能少走点弯路。这个项目的核心就是在ZYNQ的PS端通过SDIO控制器对插入的SD卡或MicroSD卡进行文件级别的读写操作。这不仅仅是简单的底层寄存器操作更涉及到驱动初始化、文件系统挂载通常是FATFS、标准C库文件操作API的使用以及如何将这些环节无缝集成到你的应用中。无论是用于加载配置文件、记录日志还是像我的项目一样处理采集的数据这都是一个非常基础且关键的功能。下面我就从硬件设计开始一步步带你走通整个流程。2. 硬件平台设计与Vivado工程配置在开始写代码之前硬件平台的正确配置是基石。ZYNQ的PS端已经集成了SD/SDIO控制器SD0我们通常就是用它来连接SD卡槽。2.1 Vivado中PS端SDIO外设的启用与引脚分配首先打开Vivado我用的版本是2019.2其他版本大同小异创建一个新的工程选择你的ZYNQ芯片型号例如XC7Z010。在Block Design中添加ZYNQ7 Processing System IP核。双击这个IP核进行配置这是最关键的一步。在弹出来的重定制Re-customize IP界面里你需要关注两个地方MIO配置在“Peripheral I/O Pins”标签页下找到“SD 0”这一项。把它勾选上。这时Vivado会自动为SD0分配一组MIOMultiplexed I/O引脚。对于最常见的SD卡模式4位数据线这通常是MIO 40到MIO 45。其中MIO 40: SD0_CLK (时钟)MIO 41: SD0_CMD (命令)MIO 42: SD0_DAT[0] (数据线0)MIO 43: SD0_DAT[1] (数据线1)MIO 44: SD0_DAT[2] (数据线2)MIO 45: SD0_DAT[3] (数据线3) 务必确认你的开发板原理图上SD卡槽的这6根信号线确实连接到了ZYNQ PS端的这组MIO上。有些板子可能用了EMIO即通过PL引出的PS IO那配置会更复杂一些本文以最通用的MIO连接为例。时钟配置SDIO控制器需要一个时钟。在“Clock Configuration”标签页下找到“SD 0”的时钟设置。你需要确保“SDIO Clock Frequency”设置在一个合理的范围内比如50MHz或100MHz。同时在“Input Clock Frequency”中为SDIO的参考时钟例如FCLK_CLK0设置一个频率Vivado内部的时钟分频器会基于此产生SDIO时钟。一个常见的配置是ARM PLL提供100MHz的FCLK_CLK0然后SDIO时钟分频设置为2得到50MHz的SDIO操作时钟。注意SD卡本身有工作频率限制在初始化阶段识别卡阶段必须使用低速时钟通常400kHz初始化完成后才能切换到高速模式如25MHz或50MHz。不过这个高低速切换是由SD卡驱动如Xilinx提供的xsdps驱动在底层自动完成的我们只需要在Vivado中配置一个足够高的基准时钟频率即可驱动会自己去分频。配置完成后点击OK在Block Design中为ZYNQ IP核自动连接时钟和复位信号然后Validate Design。没问题的话就可以Create HDL Wrapper然后生成比特流文件Generate Bitstream。虽然我们主要用PS端PL端可能没逻辑但生成比特流是导出硬件信息XSA文件的必要步骤。2.2 导出硬件平台与XSA文件比特流生成成功后在菜单栏选择File - Export - Export Hardware...。在弹出窗口中务必勾选“Include bitstream”然后指定导出路径。这一步会生成一个.xsa(Xilinx Support Archive) 文件。这个文件包含了我们刚才在Vivado中配置的所有硬件信息是后续在Vitis或SDK中创建平台工程Platform Project和应用程序工程Application Project的基础。至此硬件部分的工作就完成了。接下来我们将进入软件开发的环节。3. Vitis软件开发环境搭建与BSP配置拿到.xsa文件后我们就可以打开Vitis或旧版的Xilinx SDK进行软件开发了。这里以Vitis 2019.2为例。3.1 创建平台工程与应用工程创建工作空间启动Vitis选择一个空文件夹作为工作空间Workspace。创建平台工程File - New - Platform Project。输入工程名例如zynq_sd_platform。点击Next在“Hardware Specification”页面点击“Browse”选择我们刚才导出的.xsa文件。其他设置可以保持默认点击Finish。Vitis会基于这个XSA文件生成对应的硬件平台。生成平台在左侧的Explorer视图中右键点击刚才创建的平台工程选择“Build Project”。这会为我们的硬件平台生成设备树Device Tree、FSBLFirst Stage Bootloader等必要的支持文件。创建应用工程File - New - Application Project。输入工程名例如sd_card_read_test。点击Next在“Platform”页面选择我们刚刚创建并构建好的平台zynq_sd_platform。点击Next选择“Empty Application”模板。点击Finish。现在我们有了一个空的应用工程。接下来需要配置板级支持包BSP。3.2 配置板级支持包BSP中的SD卡驱动与文件系统在Vitis中应用工程下面会有一个[工程名]_bsp的文件夹这就是该应用的板级支持包。右键点击它选择“Board Support Package Settings”。驱动配置在“Overview”页面找到“drivers”部分。这里应该能看到ps7_sd_0已经被分配了驱动xsdps。xsdps是Xilinx提供的标准SD/SDIO驱动支持SD卡规范。通常不需要改动但你可以点击它进入详细配置。在xsdps的配置中可以检查或修改一些参数比如Has CD你的SD卡槽是否有卡检测Card Detect引脚如果有且接到了PS的MIO上需要在这里启用并指定MIO编号。很多开发板为了简化没有使用硬件CD而是靠软件检测这里就选false。Has WP写保护检测同理通常为false。Slot Type选择SD 2.0或SD 3.0根据你的卡和需求选择。选SD 3.0通常兼容性更好。文件系统配置关键在左侧导航栏找到并展开“standalone”。这里有一个至关重要的组件xilffs。这就是Xilinx提供的FAT文件系统库。你必须确保它被勾选并添加到BSP中。如果没有点击“Modify BSP Settings”在“Overview”的可用库列表里找到xilffs并勾选它。 添加xilffs后在“standalone”下会出现它的配置项。点击xilffs进行关键配置fs_interface选择PS_SD0。这告诉文件系统库底层存储设备是PS端的SD0控制器。use_lfn是否使用长文件名。建议设置为true这样支持超过8.3格式的文件名。read_only是否只读。根据你的需求设置我们做读取测试可以先设为false。enable_multi_partition是否支持多分区。通常SD卡只有一个FAT分区设为false即可。配置完成后点击“OK”关闭BSP设置窗口。Vitis会自动重新编译BSP将SD卡驱动和FATFS文件系统库链接到你的应用程序中。4. 核心代码实现从驱动初始化到文件读取BSP配置好之后我们就可以在src文件夹下创建主程序文件例如main.c了。下面的代码是一个完整的、可直接运行的示例实现了SD卡的初始化、文件系统挂载、文件读取和卸载。/** * file main.c * brief ZYNQ PS端SD卡文件读取完整示例 * details 此代码演示了如何在ZYNQ PS端初始化SD卡、挂载FAT文件系统、打开文件、读取内容并打印。 */ #include stdio.h #include xparameters.h // 硬件参数定义 #include xsdps.h // SD卡驱动头文件 #include ff.h // FATFS文件系统头文件 #include xil_printf.h /************************** 常量定义 **************************/ #define SD_DEVICE_ID XPAR_XSDPS_0_DEVICE_ID // SD0的设备ID在xparameters.h中定义 #define FILE_NAME 0:/testfile.txt // 要读取的文件路径。0: 是FATFS中物理驱动器0的标识符 #define BUFFER_SIZE 512 // 读取缓冲区大小 /************************** 变量声明 **************************/ static XSdPs SdInstance; // SD卡驱动实例 static FATFS fatfs; // FATFS文件系统对象 static FIL file; // 文件对象 static char read_buffer[BUFFER_SIZE]; // 文件读取缓冲区 UINT bytes_read; // 实际读取到的字节数 FRESULT fresult; // 文件系统操作结果 int status; // 驱动操作状态 /************************** 主函数 **************************/ int main(void) { xil_printf(ZYNQ SD Card File Read Test Start...\r\n); /* 1. 初始化SD卡驱动 */ status XSdPs_CfgInitialize(SdInstance, XSdPs_LookupConfig(SD_DEVICE_ID), XPAR_XSDPS_0_BASEADDR); if (status ! XST_SUCCESS) { xil_printf(ERROR: Failed to initialize SD driver.\r\n); return XST_FAILURE; } xil_printf(SD Driver Initialized Successfully.\r\n); /* 2. 配置SD卡为4位总线模式并识别卡 */ status XSdPs_CardInitialize(SdInstance); if (status ! XST_SUCCESS) { xil_printf(ERROR: Failed to initialize SD card. Please check if the card is inserted.\r\n); // 可以在这里添加重试逻辑 return XST_FAILURE; } xil_printf(SD Card Identified. Capacity: %llu MB\r\n, (XSdPs_GetSdCardInfo(SdInstance)-CardCapacity) 20); // 容量单位转换 /* 3. 挂载文件系统 */ fresult f_mount(fatfs, 0:/, 1); // “1”表示立即挂载强制挂载 if (fresult ! FR_OK) { xil_printf(ERROR: Failed to mount filesystem. FRESULT %d\r\n, fresult); // 常见错误FR_NO_FILESYSTEM (13) - 卡没有有效的FAT文件系统需要格式化 // FR_DISK_ERR (1) - 底层磁盘访问错误检查硬件连接 return XST_FAILURE; } xil_printf(FATFS mounted successfully.\r\n); /* 4. 打开文件 */ fresult f_open(file, FILE_NAME, FA_READ); // 以只读方式打开 if (fresult ! FR_OK) { xil_printf(ERROR: Failed to open file %s. FRESULT %d\r\n, FILE_NAME, fresult); // 常见错误FR_NO_FILE (4) - 文件不存在 // FR_NO_PATH (3) - 路径错误 f_unmount(0:/); // 关闭文件系统前先卸载 return XST_FAILURE; } xil_printf(File %s opened successfully.\r\n, FILE_NAME); /* 5. 读取文件内容并打印 */ xil_printf(File content:\r\n); xil_printf(----------------------------------------\r\n); do { fresult f_read(file, read_buffer, BUFFER_SIZE, bytes_read); if (fresult ! FR_OK) { xil_printf(\r\nERROR: Failed to read file. FRESULT %d\r\n, fresult); break; } // 将读取到的字节以字符串形式打印假设文件是文本文件 for (UINT i 0; i bytes_read; i) { xil_printf(%c, read_buffer[i]); } } while (bytes_read BUFFER_SIZE); // 循环读取直到读完文件 xil_printf(\r\n----------------------------------------\r\n); xil_printf(File read completed.\r\n); /* 6. 关闭文件和卸载文件系统 */ fresult f_close(file); if (fresult ! FR_OK) { xil_printf(WARNING: Failed to close file. FRESULT %d\r\n, fresult); } fresult f_unmount(0:/); if (fresult ! FR_OK) { xil_printf(WARNING: Failed to unmount filesystem. FRESULT %d\r\n, fresult); } xil_printf(SD Card File Read Test Finished.\r\n); return XST_SUCCESS; }4.1 代码关键点解析与避坑指南这段代码逻辑清晰但有几个地方是新手极易出错的重灾区设备ID与基地址XPAR_XSDPS_0_DEVICE_ID和XPAR_XSDPS_0_BASEADDR这两个宏定义来自于BSP自动生成的xparameters.h文件。绝对不要自己硬编码数字。Vitis会根据你的硬件设计自动分配这些值。直接使用这些宏是最安全的方式。文件路径中的“0:”在FATFS中“0:”代表第一个物理驱动器。当我们把fs_interface配置为PS_SD0后这个驱动器就映射到了我们的SD卡。所以文件路径必须是“0:/filename”或“0:/dir/filename”的形式。开头的“0:/”是必须的它指向根目录。f_mount的第二个参数这个参数是逻辑驱动器路径同样需要带上“0:”。第三个参数是1代表立即挂载。如果设为0则是延迟挂载只在首次访问驱动器时才执行挂载操作。对于简单的应用直接设为1更稳妥。错误处理代码中对每一步操作都进行了错误检查并打印了FRESULT文件系统结果码或驱动状态码。这是调试时最重要的信息。你需要一份ff.h头文件中的FRESULT枚举定义或者去查FATFS文档才能知道每个数字代表什么错误。比如FR_NO_FILESYSTEM (13)意味着卡没有被正确格式化不是FAT16/FAT32/exFAT格式。卡容量打印XSdPs_GetSdCardInfo函数返回的容量单位是字节。我们通过右移20位除以2^20来转换为MB单位。这是一个很方便的调试信息可以确认系统是否正确识别了你的SD卡。5. 实战调试常见问题与解决方案即使代码看起来没问题第一次运行时也大概率会遇到各种错误。下面是我在调试过程中遇到的一些典型问题及其解决方法。5.1 SD卡初始化失败XSdPs_CardInitialize返回错误这是最常见的问题现象是程序打印“Failed to initialize SD card”后卡住或退出。检查硬件连接首先也是最基础的确认SD卡已完全插入卡槽。有些卡槽比较紧需要听到“咔哒”声。用万用表量一下MIO引脚到卡槽的连通性排除虚焊或断线。检查电源SD卡需要稳定的3.3V供电。用示波器测量一下卡槽的VCC引脚看电压是否稳定在3.3V上电瞬间有无大的跌落。有些开发板的SD卡供电电路带载能力不足换一张小容量的SD卡比如2GB试试或者给板子的电源接口提供更充足的电流。检查时钟频率回顾在Vivado中为SDIO控制器配置的时钟频率。如果设置得过高比如超过100MHz在初始化阶段可能会失败。尝试在Vivado中降低SDIO Clock Frequency例如设为25MHz重新生成比特流和XSA文件再测试。更换SD卡不同的SD卡尤其是不同品牌、不同等级、不同容量的初始化时序和兼容性可能有差异。准备一张标准容量SDSC ≤2GB的卡和一张高容量SDHC 4GB-32GB的卡进行测试。有些旧版驱动或硬件对SDXC32GB卡支持不好。强烈建议在开发阶段使用一张知名品牌的、已格式化为FAT32的4GB或8GB SDHC卡这是兼容性最好的选择。检查MIO配置再次确认Vivado中SD0的MIO引脚分配必须和开发板原理图完全一致。如果板子用了MIO 46~51或其他一组你需要在这里修改而不是用默认的40~45。5.2 文件系统挂载失败f_mount返回非FR_OK如果SD卡驱动初始化成功打印出了卡容量但挂载文件系统失败问题通常出在卡的文件系统格式上。错误码FR_NO_FILESYSTEM(13)这明确表示SD卡上没有找到有效的FAT文件系统。解决方案就是格式化SD卡。格式化工具不要在Linux下用mkfs命令简单格式化建议使用Windows系统自带的格式化工具或者像“SD Card Formatter”这样的专用工具。格式化参数务必选择FAT32格式分配单元大小选择“默认大小”或“4096字节”。不要用exFAT或NTFS早期的xilffs库可能不支持。格式化后将你的测试文件如testfile.txt复制到SD卡的根目录。错误码FR_DISK_ERR(1)底层磁盘访问错误。这可能是硬件问题如接触不良、信号完整性差的延续也可能是驱动初始化其实不彻底。可以尝试在f_mount之前加入一小段延时例如usleep(100000)让硬件状态更稳定。检查BSP中的xilffs配置确保fs_interface确实设置为PS_SD0。一个低级错误是这里选成了GENERIC或别的接口。5.3 文件打开失败f_open返回FR_NO_FILE挂载成功了但打不开文件。确认文件路径和名称检查代码中FILE_NAME宏定义的文件名是否和SD卡根目录下的文件名完全一致包括大小写。在FATFS中如果use_lfn设置为false则只支持8.3格式的短文件名如TESTFILE.TXT。确认文件确实存在将SD卡拔下来插到电脑上确认文件确实在根目录。尝试绝对路径虽然根目录下可以直接用文件名但为了保险可以尝试使用“0:/testfile.txt”这样的绝对路径。5.4 程序运行无输出或卡死如果连“SD Card File Read Test Start...”都没打印问题可能更底层。确认串口终端首先确认你的串口终端软件如Putty、Tera Term配置是否正确波特率通常为115200、数据位、停止位、校验位以及是否正确连接到了ZYNQ的UART端口通常是PS端的MIO 48, 49。检查启动模式ZYNQ的启动模式跳线是否设置正确对于从SD卡启动FSBL和应用程序的情况需要设置为SD模式。如果是调试阶段通过JTAG下载程序则启动模式可以是JTAG。但无论如何串口应该是工作的。简化测试可以先不进行SD卡操作只写一个简单的“Hello World”程序通过串口打印来验证最基本的PS端、DDR内存、UART和Vitis工程配置是否正确。6. 进阶话题性能优化与可靠性设计当基本功能跑通后我们可能会关心如何读得更快、更稳。这里分享几个进阶的考量点。6.1 提升读取速度默认的f_read是单次读取对于大文件频繁调用会有开销。同时SD卡驱动本身有一些可调参数。增大读取缓冲区如代码中的BUFFER_SIZE可以适当增大比如设置为2048或4096字节减少函数调用次数。使用多扇区读写XSdPs驱动支持配置多扇区传输Block Count。在BSP的xsdps驱动高级配置中可以找到相关选项。启用后驱动会在一次命令中传输多个数据块显著提升连续读写的吞吐量。提高SDIO时钟频率在确保硬件信号质量布线良好无过冲振铃的前提下可以在Vivado中尝试提高SDIO控制器的运行频率例如从50MHz提升到100MHz需参考芯片手册和SD卡规范的支持上限。使用DMASDIO控制器支持DMA传输。在BSP的xsdps驱动配置中确保DMA被启用。这可以将数据搬运任务 offload 给DMA控制器减轻CPU负担并在传输大块数据时提升效率。6.2 增强代码健壮性产品化代码需要考虑更多异常情况。添加重试机制对于XSdPs_CardInitialize和f_mount这类操作可以封装在一个带超时和重试次数的循环中。因为SD卡接触瞬间可能不稳定或者上电时序稍有偏差重试几次可能就成功了。int retry_count 3; while (retry_count--) { status XSdPs_CardInitialize(SdInstance); if (status XST_SUCCESS) break; usleep(500000); // 延迟500ms再试 xil_printf(“Retrying SD card initialization… %d attempts left\r\n”, retry_count); } if (status ! XST_SUCCESS) { /* 处理最终失败 */ }检查写保护与卡在位状态如果你的硬件支持卡检测CD和写保护WP引脚可以在BSP中启用它们并在代码中通过XSdPs_GetPresentStatus()和XSdPs_GetWriteProtectStatus()等API进行状态检查在用户拔卡或写保护打开时给出友好提示。安全卸载在程序退出或需要移除SD卡前务必确保所有文件都已关闭f_close并且文件系统已卸载f_unmount。直接断电或热拔插可能导致文件系统损坏。f_unmount函数会同步缓存数据到物理介质。处理大文件与长路径确保xilffs配置中use_lfn启用以支持长文件名。对于非常大的文件注意f_read返回的bytes_read可能小于请求的字节数例如到达文件尾循环读取的逻辑需要正确处理这种情况。6.3 集成到更复杂的应用框架中在实际项目中SD卡读写可能只是模块之一。你需要考虑如何将这部分代码优雅地集成。封装为独立模块将SD卡初始化、挂载、文件操作等函数封装到一个单独的.c/.h文件对中例如sd_card.c和sd_card.h。对外提供清晰的接口如SD_Init(),SD_ReadFile(),SD_WriteFile()并隐藏内部全局变量如SdInstance,fatfs。与FreeRTOS结合如果你的应用运行在FreeRTOS上需要特别注意FATFS的重入Re-entrancy问题。标准的xilffs可能不是线程安全的。你需要启用FATFS配置中的_FS_REENTRANT选项并提供操作系统相关的同步信号量函数如ff_mutex_create,ff_mutex_lock等。Xilinx有时会提供适配FreeRTOS的FATFS版本或者你需要自己实现这些接口。错误日志记录将操作失败时的FRESULT或驱动错误码记录到非易失性存储器如EEPROM或通过网络发送出去便于现场问题诊断。从硬件引脚配置到驱动和文件系统库的BSP设置再到应用层代码的编写和调试最后到性能与可靠性的打磨在ZYNQ PS端实现一个稳定可靠的SD卡文件读取功能需要贯穿整个软硬件链条的细致操作。希望这份超详细的指南和完整的代码能帮你一次性打通这个环节把精力更多地投入到上层更有趣的应用开发中去。如果在实际操作中遇到了上面没覆盖到的问题不妨从最基础的硬件连接和SD卡格式化开始配合串口打印的错误码一步步缩小排查范围问题总能解决的。
