【正点原子FPGA连载】第十四章SD卡读写TXT文本实验 摘自【正点原子】DFZU2EG_4EV MPSoC之嵌入式Vitis开发指南

1）实验平台：正点原子MPSoC开发板
2）平台购买地址：https://detail.tmall.com/item.htm?id=692450874670
3）全套实验源码+手册+视频下载地址： http://www.openedv.com/thread-340252-1-1.html

第十四章SD卡读写TXT文本实验

SD存储卡是一种基于半导体快闪记忆器的记忆设备。它具有体积小、传输速度快、支持热插拔等优点，在便携式装置领域得到了广泛的应用，如手机、多媒体播放器等。本章我们将使用MPSOC开发板学习如何对SD卡（这里特指Micro SD卡，即TF卡）进行TXT文本的读写操作。
本章包括以下几个部分：
1414.1简介
14.2实验任务
14.3硬件设计
14.4软件设计
14.5下载验证
14.1简介
我们开发板上的SD卡接口为小卡的设计，可以连接Micro SD卡（也叫TF卡），在介绍TF卡之前，我们先来介绍一下较大的一种存储卡，即SD卡。
SD卡介绍
SD卡的英文全称是Secure Digital Card，即安全数字卡（又叫安全数码卡），是在MMC卡（Multimedia Card，多媒体卡）的基础上发展而来，主要增加了两个特色：更高的安全性和更快的读写速度。SD卡和MMC卡的长度和宽度都是32mm x 24mm，不同的是，SD卡的厚度为2.1mm，而MMC卡的厚度为1.4mm，SD卡比MMC卡略厚，以容纳更大容量的存贮单元，同时SD卡比MMC卡触点引脚要多，且在侧面多了一个写保护开关。SD卡与MMC卡保持着向上兼容，也就是说，MMC卡可以被新的SD设备存取，兼容性则取决于应用软件，但SD卡却不可以被MMC设备存取。SD卡和MMC卡可通过卡片上面的标注进行区分，如下图左侧图片上面标注为“MultiMediaCard”字母样式的为MMC卡，右侧图片上面标注为“SD”字母样式的为SD卡。

图 14.1.1 MMC外观图（左）和SD卡外观图（右）
上图中右侧图片的SD卡实际上为SDHC卡，SD卡从存储容量上分为3个级别，分别为：SD卡、SDHC卡（Secure Digital High Capacity，高容量安全数字卡）和SDXC卡（SD eXtended Capacity，容量扩大化的安全存储卡）。SD卡在MMC卡的基础上发展而来，使用FAT12/FAT16文件系统，SD卡采用SD1.0协议规范，该协议规定了SD卡的最大存储容量为2GB；SDHC卡是大容量存储SD卡，使用FAT32文件系统，SDHC卡采用SD2.0协议规范，该协议规定了SDHC卡的存储容量范围为2GB至32GB；SDXC卡是新提出的标准，不同于SD卡和SDHC卡使用的FAT文件系统，SDXC卡使用exFAT文件系统，即扩展FAT文件系统。SDXC卡采用SD3.0协议规范，该协议规定了SDXC卡的存储容量范围为32GB至2TB（2048GB），一般用于中高端单反相机和高清摄像机。
下表为不同类型的SD卡采用的协议规范、容量等级及支持的文件系统。
表 14.1.1 SD卡的类型、协议规范、容量等级及支持的文件系统

不同协议规范的SD卡有着不同速度等级的表示方法。在SD1.0协议规范中（现在用的较少），使用“X”表示不同的速度等级；在SD2.0协议规范中，使用SpeedClass表示不同的速度等级；SD3.0协议规范使用UHS（Ultra High Speed）表示不同的速度等级。SD2.0规范中对SD卡的速度等级划分为普通卡（Class2、Class4、Class6）和高速卡（Class10）；SD3.0规范对SD卡的速度等级划分为UHS速度等级1和3。不同等级的读写速度和应用如下图所示。

图 14.1.2 SD卡不同速度等级表示法
SD卡共有9个引脚线，可工作在SDIO模式或者SPI模式。在SDIO模式下，共用到CLK、CMD、DAT[3:0]六根信号线；在SPI模式下，共用到CS（SDIO_DAT[3]）、CLK（SDIO_CLK）、MISO（SDIO_DAT[0]）、MOSI（SDIO_CMD）四根信号线。SD卡接口定义以及各引脚功能说明如图 14.1.3所示。

图 14.1.3 SD卡接口定义以及各引脚功能说明
市面上除标准SD卡外，还有Micro SD卡（原名TF卡），是一种极细小的快闪存储器卡，是由SanDisk(闪迪)公司发明，主要用于移动手机。MicroSD卡插入适配器（Adapter）可以转换成SD卡，其操作时序和SD卡是一样的。MicroSD卡接口定义以及各引脚功能说明如图 14.1.4所示。

图 14.1.4 MicroSD卡接口定义以及各引脚功能说明
标准SD卡2.0版本中，工作时钟频率可以达到50Mhz，在SDIO模式下采用4位数据位宽，理论上可以达到200Mbps（50Mx4bit）的传输速率；在SPI模式下采用1位数据位宽，理论上可以达到50Mbps的传输速率。因此SD卡在SDIO模式下的传输速率更快，同时其操作时序也更复杂。值得一提的是，MPSOC内部集成了两个SD卡控制器，并且Xilinx Vitis的standalone已经移植好了FATFS（Vitis软件中叫做xilffs）文件系统，因此在Vitis中添加xilffs库后，就可以在程序中使用FATFS中的API函数来操作SD卡。
SD控制器（SD/SDIO/eMMC Controller）
MPSOC中的SD控制器符合SD3.0协议规范，接口兼容eMMC4.51、MMC4.51、SDIO3.0、SD3.01。SD控制器通过AXI主端口和AXI从端口连接至系统总线上，其系统框图如下图所示：

图 14.1.5 SD卡控制器内部框图
AXI从接口用于访问SD控制器内部的寄存器，除此之外，在PIO（Programmed I/O）模式下运行时，驱动程序可以通过该接口访问SD数据端口寄存器。
AXI主接口用于访问DMA控制器（当使用DMA模式或者ADMA2模式）。DMA控制器使用DMA主接口在内部缓存和系统内存之间传输数据。
SD控制器连接SD卡时，支持几种不同的速度模式如下图所示：

图 14.1.6 SD卡速度模式
由上图可知，在不同的速度模式下，SD_CLK能够运行的最大时钟频率不一样，且对SD卡IO电平也有要求。由于我们的MPSOC开发板，将TF卡连接至MPSOC芯片的BANK501，电平固定为3.3V，所以只支持默认模式和高速模式，在高速模式下，带宽最大为25MB/s。
FATFS文件系统
FATFS是一个完全开源免费的FAT文件系统模块，专门为小型的嵌入式系统而设计。它完全用标准C语言编写，所以具有良好的硬件平台独立性，可以很方便的移植到各种嵌入式处理器中。Xilinx Vitis的standalone已经移植好了FATFS文件系统，因此在Vitis中添加xilffs库后，就可以在程序中使用FATFS中的API函数来操作SD卡。
FATFS的特点如下：
1、结构清晰，代码量少，文件系统和IO底层分开，特别适合新手入门学习；
2、支持最多10个逻辑盘符和两级文件夹；
3、支持FAT12/FAT16和FAT32文件系统；
4、支持长文件名称。
FATFS的这些特点，加上开源、免费的原则，使得FATFS的应用非常广泛。FATFS模块的层次结构如图 14.1.7所示：

图 14.1.7 FATFS层次结构图
最顶层是应用层，使用者无需理会FATFS的内部结构和复杂的FAT协议，只需要调用FATFS 模块提供给用户的一系列应用接口函数，如f_open，f_read，f_write和f_close等，就可以像在 PC上读／写文件那样简单。
中间层FATFS模块，实现了FAT文件读／写协议。FATFS模块提供的是ff.c和ff.h。除非有必要，使用者一般不用修改，使用时将头文件直接包含进去即可。
FATFS模块提供的底层接口，它包括存储媒介读／写接口（disk I/O）和供给文件创建修改时间的实时时钟。
关于FATFS源码以及API函数的介绍，大家可以在：http://elm-chan.org/fsw/ff/00index_e.html这个网站上查看。
14.2实验任务
本章的实验任务是通过Xilinx Vitis自带的FATFS库，完成对TF卡中TXT文本读写的功能，并将读写测试结果通过串口打印出来。
14.3硬件设计
我们的MPSOC开发板上面有一个SD卡接口，可以连接Micor SD卡（TF卡），原理图如下图所示：

图 14.3.1 Micro SD卡原理图
由上图可知，SD卡共有四根数据线（SD_D0~D3），连接至MPSOC的引脚。值得注意的是，图中SD_CD信号是TF卡检测信号，用于标志开发板是否连接了TF卡。当开发板没有连接TF卡时，SD_CD信号为高电平；而当开发板连接了TF卡之后，SD_CD信号为低电平，表示开发板已经连接了TF卡。
从实验任务我们可以画出如下的系统框图，DDR4中存放和运行程序、SD卡控制器驱动TF卡，UART实现串口通信。

图 14.3.2 系统框图
由系统框图可知，本次实验在MPSOC嵌入式最小系统的基础上，添加了SD卡控制器，用于驱动TF卡。需要说明的是，TF卡连接的是PS的MIO端口，因此本次实验没有用到PL的资源。
我们直接在“Hello World实验”的基础上，将工程另存为“micro_sd_rw”工程。
这里简单介绍下MPSOC PS的配置界面，配置界面选择的是SD1 MIO46…MIO51、CD（MIO45），如下图所示。

图 14.3.3 外设IO配置界面
需要注意的是，TF卡的引脚连接到MPSOC的Bank 1端口（BANK501），Bank 1的IO电压为3.3V，因此在MIO的配置界面将Bank1的电压改为“LVCMOS 3.3V”。图 14.3.3中勾选了CD信号，CD信号用于指示当前开发板有没有连接TF卡，这里勾选中CD信号，并将引脚分配至MIO45。另外，由于本次实验连接的是16GB的TF卡，所以Slot Type选择SD2.0，而Data Transfer Mode选择4Bit。
UART配置界面选择UART0 MIO42…MIO43，如下图所示。

图 14.3.4 UART配置界面
嵌入式系统最终搭建的框图如图 14.3.5所示。

图 14.3.5 嵌入式系统框图界面
14.4软件设计
在Vitis软件中新建一个BSP工程和一个空的应用工程，应用工程名为“micro_sd_rw”。
接下来添加FATFS库。点击micro_sd_rw界面下的“Navigate to BSP Setting”，如下图所示。

图 14.4.1 关闭system.mss
如果不小心关闭该界面的话，可以直接双击图中左侧micro_sd_rw.prj即可。
接下来会弹出Board Support Package的界面，点击“Modify BSP Settings…”，对应用工程的板级支持包进行设置，如下图所示：

图 14.4.2 Board Support Package界面
在弹出的界面中勾选“xilffs”，xilffs即为FATFS库，如下图所示：

图 14.4.3 勾选xilffs
勾选后，会在左侧Overview的standalone一栏出现xilffs，点击xilffs。可以看到use_lfn的默认设置为0，即不使能。use_lfn用于设置是否使能长文件名以及文件名的小写字母，这里将use_lfn设置为1，点击“OK”按钮完成设置。如图 14.4.4所示：

图 14.4.4 使能use_lfn
设置完成后，在design_1_wrapper→psu_cortexa53_0→standalone_domain→bsp→psu_cortexa53_0→libsrc一栏下，会多出FATFS的库函数。如图 14.4.5所示：

图 14.4.5 xilffs_v4_2库函数
添加完FATFS库之后，对TF卡的操作会简单很多，我们只需要在程序中调用FATFS的库函数即可。
接下来为应用工程新建一个源文件“main.c”，我们在新建的main.c文件中输入本次实验的代码。代码的主体部分如下所示：
1 #include “xparameters.h”
2 #include “xil_printf.h”
3 #include “ff.h”
4 #include “xstatus.h”
5
6 #define FILE_NAME “ZDYZ.txt” //定义文件名
7
8 const char src_str[30] = “www.openedv.com”; //定义文本内容
9 static FATFS fatfs; //文件系统
10
11 //初始化文件系统
12 int platform_init_fs()
13 {
14 FRESULT status;
15 TCHAR *Path = “0:/”;
16 BYTE work[FF_MAX_SS];
17
18 //注册一个工作区(挂载分区文件系统)
19 //在使用任何其它文件函数之前，必须使用f_mount函数为每个使用卷注册一个工作区
20 status = f_mount(&fatfs, Path, 1); //挂载SD卡
21 if (status != FR_OK) {
22 xil_printf(“Volume is not FAT formated; formating FAT\r\n”);
23 //格式化SD卡
24 status = f_mkfs(Path, FM_FAT32, 0, work, sizeof work);
25 if (status != FR_OK) {
26 xil_printf(“Unable to format FATfs\r\n”);
27 return -1;
28 }
29 //格式化之后，重新挂载SD卡
30 status = f_mount(&fatfs, Path, 1);
31 if (status != FR_OK) {
32 xil_printf(“Unable to mount FATfs\r\n”);
33 return -1;
34 }
35 }
36 return 0;
37 }
38
39 //挂载SD(TF)卡
40 int sd_mount()
41 {
42 FRESULT status;
43 //初始化文件系统（挂载SD卡，如果挂载不成功，则格式化SD卡）
44 status = platform_init_fs();
45 if(status){
46 xil_printf(“ERROR: f_mount returned %d!\n”,status);
47 return XST_FAILURE;
48 }
49 return XST_SUCCESS;
50 }
51
52 //SD卡写数据
53 int sd_write_data(char file_name,u32 src_addr,u32 byte_len)
54 {
55 FIL fil; //文件对象
56 UINT bw; //f_write函数返回已写入的字节数
57
58 //打开一个文件,如果不存在，则创建一个文件
59 f_open(&fil,file_name,FA_CREATE_ALWAYS | FA_WRITE);
60 //移动打开的文件对象的文件读/写指针 0:指向文件开头
61 f_lseek(&fil, 0);
62 //向文件中写入数据
63 f_write(&fil,(void) src_addr,byte_len,&bw);
64 //关闭文件
65 f_close(&fil);
66 return 0;
67 }
68
69 //SD卡读数据
70 int sd_read_data(char file_name,u32 src_addr,u32 byte_len)
71 {
72 FIL fil; //文件对象
73 UINT br; //f_read函数返回已读出的字节数
74
75 //打开一个只读的文件
76 f_open(&fil,file_name,FA_READ);
77 //移动打开的文件对象的文件读/写指针 0:指向文件开头
78 f_lseek(&fil,0);
79 //从SD卡中读出数据
80 f_read(&fil,(void)src_addr,byte_len,&br);
81 //关闭文件
82 f_close(&fil);
83 return 0;
84 }
85
86 //main函数
87 int main()
88 {
89 int status,len;
90 char dest_str[30] = “”;
91
92 status = sd_mount(); //挂载SD卡
93 if(status != XST_SUCCESS){
94 xil_printf(“Failed to open SD card!\n”);
95 return 0;
96 }
97 else
98 xil_printf(“Success to open SD card!\n”);
99
100 len = strlen(src_str); //计算字符串长度
101 //SD卡写数据
102 sd_write_data(FILE_NAME,(u32)src_str,len);
103 //SD卡读数据
104 sd_read_data(FILE_NAME,(u32)dest_str,len);
105
106 //比较写入的字符串和读出的字符串是否相等
107 if (strcmp(src_str, dest_str) == 0)
108 xil_printf(“src_str is equal to dest_str,SD card test success!\n”);
109 else
110 xil_printf(“src_str is not equal to dest_str,SD card test failed!\n”);
111
112 return 0;
113 }
在main函数中，实现的功能是向TF卡中读写TXT文本，并比较写入的数据和读出的数据是否一致。程序首先调用sd_mount()函数挂载TF卡，接下来根据待写入字符串的长度，通过sd_write_data()函数和sd_read_data()函数对TF卡中的TXT文本进行写入和读出，然后比较写入和读出的值，并打印比较的结果值，如代码中第86行至第113行所示。
sd_mount()函数实现的功能是挂载TF卡，并返回挂载的结果。sd_mount()函数里通过调用platform_init_fs()函数实现对TF卡的挂载，如果挂载不成功，则格式化TF卡，并重新挂载TF卡。在使用任何其它文件系统函数之前，必须先对TF卡进行挂载，sd_mount()函数如代码中第39至第50行所示，platform_init_fs()函数如代码中第12至第37行所示。需要注意的是，挂载函数同样会对硬件进行检查，如果未插入TF卡，会导致SD卡挂载失败。
sd_write_data()函数在TF卡中打开一个文本，并写入程序开头定义的字符数组“www.openedv.com”。写入之前，先通过f_open函数打开一个文件名为“ZDYZ.txt”的文件，如果不存在，则在TF卡中创建该文件。随后通过f_lseek函数移动已打开文件对象的读写指针，为0则代表移动到文件的开头位置。接下来通过f_write函数向打开的文件中写入数据，写完之后则通过f_close函数关闭该文件。如代码的第52行至67行代码所示。
sd_read_data()函数从TF卡的TXT文本中读出数据。TF卡的读操作和写操作类似，读数据的函数为f_read函数，如代码中第69行至第84行代码所示。
14.5下载验证
首先我们将下载器与开发板的JTAG接口连接，下载器另外一端与电脑连接。然后使用USB连接线将开发板的PS_PORT（PS_UART）接口与电脑连接，用于串口通信。接下来插入TF卡（TF卡插槽位于开发板背面）。最后连接开发板的电源。开发板背面TF卡卡座如图 14.5.1所示：

图 14.5.1 开发板背面TF卡卡座
打开Vitis Terminal终端，设置并连接串口。然后下载本次实验的程序，下载完成后，在下方的Terminal中可以看到应用程序打印的信息，如下图所示：

图 14.5.2 打印SD卡读写测试结果
由上图可知，显示写入的字符和读出的字符一致，说明TF卡读写测试成功。
接下来从开发板的卡槽中取出TF卡，通过连接读卡器来插入电脑的USB接口，此时可以看到TF中的文件内容如所示。

图 14.5.3 创建的TXT文本
打开“ZDYZ.txt”文本，可以看到文本的内容，如下图所示：

图 14.5.4 TXT文本内容
TXT文本的内容为“www.openedv.com”字符串，和串口中打印的字符串一致，说明本次实验在MPSOC开发板上面下载验证成功。