【分享】VCK190 PCIe QDMA 通用数据传输参考设计
VCK190 PCIe QDMA 通用数据传输参考设计
1. 概述
作者
作者: 付汉杰 hankf@xilinx.com hankf@amd.com
硬件设计工作由季茂林（maolinj@xilinx.com）完成。
测试环境
目前在X86机箱里插VCK190测试。X86、PCIe Host、Host都是指X86运行的Linux环境。Versal、Endpoint、A72都是指A72运行的Linux环境。Endpoint有时使用EP来简化。
测试单板： VCK190
测试单板操作系统： PetaLinux 2021.2 Linux
root@dapd-0316-peta:~# uname -a
Linux dapd-0316-peta 5.10.0-xilinx-v2021.2 #1 SMP Wed Mar 16 06:30:24 UTC 2022 aarch64 GNU/Linux
测试X86主板：ASUS Z490
测试X86操作系统：CentOS Linux 7.9
[root@localhost pcie_host_fifo_app]# dmidecode |grep -A16 "System Information$"
System Information
Manufacturer: ASUS
Product Name: System Product Name
Version: System Version
Serial Number: System Serial Number
UUID: 8c1cddc3-8472-bd61-6e23-d45d64ef96f0
Wake-up Type: Power Switch
SKU Number: SKU
Family: Default string
Handle 0x0002, DMI type 2, 15 bytes
Base Board Information
Manufacturer: ASUSTeK COMPUTER INC.
Product Name: ROG STRIX Z490-F GAMING
Version: Rev 1.xx
Serial Number: 200467903600324
Asset Tag: Default string
[root@localhost pcie_host_fifo_app]# lsb_release -a
LSB Version: :core-4.1-amd64:core-4.1-noarch:cxx-4.1-amd64:cxx-4.1-noarch:desktop-4.1-amd64:desktop-4.1-noarch:languages-4.1-amd64:languages-4.1-noarch:printing-4.1-amd64:printing-4.1-noarch
Distributor ID: CentOS
Description: CentOS Linux release 7.9.2009 (Core)
Release: 7.9.2009
Codename: Core
代码来源
设计继承自VMK180 TRD 2021.2。
Host的应用程序，来自于“vmk180-trd/pcie_host_package/qdma/pcie_app”。
Endpoint的应用程序，来自于“vmk180-trd/petalinux/xilinx-vmk180-trd/project-spec/meta-vmk180-trd/recipes-apps/pcie-gst-app/files/src”。
主要改进
内存复制
VMK180 TRD 2021.2使用了下面的CPU内存复制操作，既占用CPU时间，也降低了性能。本设计中去掉了内存复制操作。
memcpy(data, cb->tail, cb->sz);
忙等待
VMK180 TRD 2021.2在等待Buffer时，使用了下面的无间断读取PCIe设备的寄存器，既占用CPU时间，也占用PCIe带宽。曾经有客户使用类似设计，导致PCIe传输带宽只有理论带宽的十分之一；去掉无间断读PCIe寄存器后，PCIe传输带宽提高5倍。
本设计中去掉了下面的忙等待操作。
while (!(buffer_ready & 0x1))
{
buffer_ready = *((uint32_t *)(trans.map_base + PCIEP_READ_BUFFER_READY));
read_complete = *((uint32_t *)(trans.map_base + PCIEP_READ_TRANSFER_COMPLETE));
if (read_complete == 0xef)
break;
}
剥离GStreamer
VMK180 TRD 2021.2的代码，必须使用GStreamer。本设计剥离GStreamer了，成了一个通用的PCIe Host和Endpoint通过QDMA传输数据的一个参考设计。
握手机制
在VMK180 TRD 2021.2中，如果BUFFER_READY的最低位是1，表示BUFFER就绪，继续读BUFFER的地址和大小，实现数据传输。下面的操作，Host等待buffer_ready最低位变为0，因为操作系统调度的原因，有可能再Endpoint开始新的传输后才得到执行，导致永远都等不到，从而引起数据传输异常。
*transfer_done = 0x1;
while ((buffer_ready & 0x1)) {
buffer_ready = *((uint32_t *)(trans.map_base + PCIEP_READ_BUFFER_READY));
}
本设计中，如果BUFFER_READY的低16位是预期的序列号，表示BUFFER就绪，继续读BUFFER的地址和大小，实现数据传输。既可以减少上面的第二次握手带来的时间开销，也可以根除上述危险情况，还可以避免endpoint异常退出后，Host读到无效的数据。
X86-Host
头文件
"pcie_host_abstract.h"
"dma_xfer_utils.h"
数据结构
数据结构 struct pcie_qdma_transfer包含PCIe QDMA传输时需要使用的信息。
下列四个整型成员，与应用层有关。
user_quit_req表示上层应用退出，提前退出传输函数。
ep_h2c_quit表示H2C endpoint设备退出，提前退出传输函数。
ep_c2h_quit表示C2H endpoint设备退出，提前退出传输函数。
i_irq_check表示是否检查C2H的中断响应情况。
int user_quit_req;
int ep_h2c_quit;
int ep_c2h_quit;
int i_irq_check;
初始化函数pcie_host_init
第一个参数qdma_h2c_device，是QDMA H2C队列的设备名称。
第二个参数qdma_c2h_device，是QDMA C2H队列的设备名称。
qdma_h2c_device和qdma_c2h_device，至少一个是正确的设备名称。
第三个参数reg_device_name，是PCIe Register的设备名称。它通过QDMA的BAR访问，注意BAR的序号。
第四个参数p_xfer_info，是QDMA传输过程中的信息，是数据结果struct pcie_qdma_transfer的指针。应用程序要定义一个全局变量，并提供指针。
第五个参数i_max_frame_size，是最大的帧大小，单位是字节。传输的帧，可以比它小，不能比它大。
第六个参数i_app_id，是一个32位的数，向EP指示Host运行的应用程序类型。
/*
* qdma_h2c_device, QDMA H2C device name, for example, "/dev/qdma01000-MM-0"
* qdma_c2h_device, QDMA C2H device name, for example, "/dev/qdma01000-MM-1"
* At least one of qdma_h2c_device and qdma_c2h_device must be valid device name.
* reg_device_name, PCIe register device name, for example, "/sys/bus/pci/devices/0000:01:00.0/resource1"
* p_xfer_info, pointer for PCIe transfer information.
* i_max_frame_size, Maximum frame size.
* i_app_id: ID to indicate the application is running.
*/
int pcie_host_init
(
const char *qdma_h2c_device,
const char *qdma_c2h_device,
const char *reg_device_name,
pcie_transfer* p_xfer_info,
int i_max_frame_size,
int i_app_id
)
退出函数pcie_host_exit
退出函数pcie_host_exit只有一个参数，是数据结构struct pcie_qdma_transfer的指针，与调用初始化函数pcie_host_init时一样的参数。
int pcie_host_exit
(
pcie_qdma_transfer* p_xfer_info
)
H2C函数pcie_host_qdma_h2c
H2C函数pcie_host_qdma_h2c有三个参数。
第一个参数是pcie_qdma_transfer的指针，与调用初始化函数pcie_host_init时一样的参数。
第二个参数是数据缓冲区的指针，用于保存即将写到PCIe endpoint的数据。
第三个参数是以字节位单位的数据缓冲区的大小。
第二、三个参数，和标准文件操作函数的write( )中的第二、三个参数一样。
返回值，是写到PCIe endpoint的数据大小。
H2C函数pcie_host_qdma_h2c的用法，也和标准文件操作函数的write( )中的用法一样。
/*
* pcie_host_qdma_h2c :
* Start dma write transaction from host to endpoint.
* @p_xfer_info : pointer for PCIe transfer information
* @write_buffer : porinter to data buffer to be transferred to endpoint
* @data_size : Size in bytes
*/
int pcie_host_qdma_h2c
(
pcie_qdma_transfer* pt_xfer_info,
void *read_allocated,
int size_frame
);
C2H函数pcie_host_qdma_c2h
C2H函数pcie_host_qdma_c2h有三个参数，含义基本与H2C函数pcie_host_qdma_h2c一样。
第一个参数是pcie_qdma_transfer的指针，与调用初始化函数pcie_host_init时一样的参数。
第二个参数是数据缓冲区的指针，用来存储从PCIe endpoint接收到的数据。
第三个参数是以字节位单位的数据缓冲区的大小。
第二、三个参数，和标准文件操作函数的read( )中的第二、三个参数一样。
返回值，是接收（读取）到的数据大小。
H2C函数pcie_host_qdma_c2h的用法，也和标准文件操作函数的read( )中的用法一样。
/**
* pcie_host_qdma_c2h :
* Start dma write transaction from endpoint to endpoint host.
* @p_xfer_info : pointer for PCIe transfer information
* @read_buffer : porinter to data buffer to be filled by data from endpoint
* @data_size : Size in bytes
*/
int pcie_host_qdma_c2h
(
pcie_qdma_transfer* pt_xfer_info,
void *write_allocated,
int size_frame
);
使用流程
先调用pcie_host_init(), 再根据需要调用pcie_host_qdma_h2c()/pcie_host_qdma_c2h()，最后调用pcie_host_exit()退出传输。
如果需要提前退出，可以设置user_quit_req位非0值，指示pcie_host_qdma_h2c()/pcie_host_qdma_c2h()退出等待过程。
user_quit_req表示上层应用退出，提前退出传输函数。
从pcie_host_qdma_h2c()返回后，建议检查ep_h2c_quit。如果是非0值， 表示H2C endpoint设备已经退出传输过程。
从pcie_host_qdma_c2h()返回后，建议检查ep_c2h_quit。如果是非0值， 表示H2C endpoint设备已经退出传输过程。
测试过程
QDMA初始化流程
QDMA初始化流程请参考 Xilinx QDMA软件简明教程。
从QDMA X86 PCIe Host侧的Linux内核驱动 下载QDMA X86 PCIe Host侧的Linux内核驱动，使用命令“make”编译，使用命令“sudo make install”安装驱动。
编译好驱动后，可以执行脚本“init-c2h-h2c.sh”创建队列。
verify.sh和perf-3840.sh系列脚本里，也会自动检查PCIe设备情况。默认PCIe总线号是1，设备号是0。
如果没有PCIe设备，自动扫描PCIe总线。
if [ ! -f /sys/bus/pci/devices/0000:01:00.0/resource1 ]; then
echo -e "\nPCIe rescan.\n"
echo 1 > /sys/bus/pci/rescan
sleep 1
fi
如果没有QDMA队列，自动脚本“init-c2h-h2c.sh”创建队列。
if [ ! -f /dev/qdma01000-MM-0 ]; then
echo -e "\nInitialize QDMA device.\n"
./init-c2h-h2c.sh
fi
数据校验
Host运行verify-3840.sh; endpoint运行”qdma_ep_echo.elf 200”.
测试200帧3840x2160的YUV422数据（3840x2160x2 bytes），H2C前和C2H后的每帧都写入文件，比较0-9， 190-199帧的md5值。都正确。
性能
Host运行perf-3840.sh; endpoint运行“qdma_ep_echo.elf 1000000”。运行100万次，顺利完成。
Versal-Endpoint
BSP
devicetree
在硬件工程中添加pcie-reg-space，然后在devicetree增加下列内容。
其中0xa42f0000是pcie-reg-space在A72 AXI总线上的地址，94、95、96是它的三个中断。
&pcie_reg_space_0{
status = "okay";
compatible = "xlnx,pcie-reg-space-v1-0-1.0";
reg = < 0x0 0xa42f0000 0x0 0x10000 0x00000201 0x00000000 0x0 0x10000>;
interrupt-parent = <&gic>;
interrupts = <0x0 94 0x4 0x0 95 0x4 0x0 96 0x4 >;
interrupt-names = "read", "write", "close";
};
Linux Kernel
在Linux Kernel源代码的drivers/misc/目录下，添加文件xilinx_pci_endpoint.c.
在drivers/misc/Kconfig中增加如下内容：
config XILINX_PCIEP
tristate "Xilinx PCIe Endpoint driver"
help
This module provides support to access and read write PCIe userspace bar map registers.
If unsure, say N
在drivers/misc/Makefile中增加如下内容：
obj-$(CONFIG_XILINX_PCIEP) += xilinx_pci_endpoint.o
执行命令"petalinux-config -c kernel"， 搜索并选择XILINX_PCIEP。之后，在目录“meta-user/recipes-kernel/linux/linux-xlnx/”中有.cfg文件，其中含有下列内容。
[hankf@localhost project-spec]$ grep -rn "XILINX_PCIEP"
CONFIG_XILINX_PCIEP=m
Versal-Endpoint应用程序
头文件
"pcie_src.h"
"pcie_sink.h"
数据结构
Endpoint使用一个数据结构struct pcie_ep_xfer_info在应用和底层程序之间共享数据。应用要定义一个数据结构struct pcie_ep_xfer_info，把它的指针传递给后续的所有函数。
成员c2h_read_frame_size，指示H2C传输后得到的dmabuf里的有效数据的字节数。
成员user_quit_req表示上层应用退出，提前退出传输函数。
初始化函数pcie_ep_init
第一个参数，指定PCIe Endpoint的设备名称，比如是"/dev/pciep0"。这个设备名称由驱动程序xilinx_pci_endpoint.c中的代码决定。
第二个参数，是应用和底层程序之间共享数据的数据结构的指针。
第三个参数，i_max_frame_size，是最大的帧大小，单位是字节。传输的帧，可以比它小，不能比它大。
第四个参数，i_app_id，是一个32位的数，向Host指示EP运行的应用程序类型。
/*
* pcie_ep_device, PCIe Endpoint device name, for example, "/dev/pciep0"
* p_ep_xfer_info, pointer for PCIe Endpoint transfer information.
* i_max_frame_size, Maximum frame size.
* i_app_id: ID to indicate the application is running.
*/
int pcie_ep_init( const char *pcie_ep_device,
pcie_ep_xfer_info* p_ep_xfer_info,
int i_max_frame_size,
int i_app_id );
退出函数pcie_ep_exit
退出函数pcie_ep_exit只有一个参数，是应用和底层程序之间共享数据的数据结构的指针。
/*
* p_ep_xfer_info, pointer for PCIe Endpoint transfer information.
*/
int pcie_ep_exit( pcie_ep_xfer_info* p_ep_xfer_info );
H2C函数pcie_ep_qdma_h2c
H2C函数pcie_ep_qdma_h2c只有一个参数，是应用和底层程序之间共享数据的数据结构的指针，要与调用初始化函数pcie_ep_init()时的参数一样。
H2C函数pcie_ep_qdma_h2c的返回值，是dmabuf的文件描述符，可以通过它得到dmabuf，然后做映射，访问dmabuf里的数据。如果Host退出传输，返回-ENOENT。
p_ep_xfer_info中的成员c2h_read_frame_size，指示了dmabuf里的有效数据的字节数。
/*
* p_ep_xfer_info, pointer for PCIe Endpoint transfer information.
* @return, file descriptor of dmabuf that holds the data from PCIe Host
*/
int pcie_ep_qdma_h2c (pcie_ep_xfer_info* p_ep_xfer_info);
C2H函数pcie_ep_qdma_c2h
C2H函数pcie_ep_qdma_c2h的第一个参数，是应用和底层程序之间共享数据的数据结构的指针，要与调用初始化函数pcie_ep_init()时的参数一样。
第二个参数是dmabuf的文件描述符i_dmabuf_fd，可以通过它得到dmabuf。
第三个参数i_size，指示dmabuf里的有效数据的字节数。
如果传输正确，返回0。如果Host退出传输，返回-ENOENT。
/*
* @p_ep_xfer_info, pointer for PCIe Endpoint transfer information.
* @i_dmabuf_fd, file descriptor of dmabuf that holds the data to be sent to PCIe Host
* @i_size, Size, in bytes, of data in the dmabuf
* @return, 0 on success
*/
int pcie_ep_qdma_c2h( pcie_ep_xfer_info* p_ep_xfer_info,
int i_dmabuf_fd, int i_size );
使用流程
先调用pcie_ep_init()初始化传输过程, 再根据需要调用pcie_ep_qdma_h2c()/pcie_ep_qdma_c2h()传输数据，最后调用pcie_ep_exit()退出传输。
如果需要提前退出，可以设置user_quit_req位非0值，指示pcie_ep_qdma_h2c()和pcie_ep_qdma_c2h()退出等待过程。
数据结构pcie_ep_xfer_info的user_quit_req表示上层应用退出，提前退出传输函数。
如果Host退出传输， pcie_ep_qdma_h2c()和pcie_ep_qdma_c2h()，都返回-ENOENT。
调试技巧
更新VCK190系统映像
调试时，修改Linux代码、Linux驱动代码、Devicetree后，需要重新生成VCK190系统映像的boot.bin, image.ub等文件。
如果VCK190从TF卡启动，一般需要把上面的文件复制到TF卡上。传统做法，是拔插TF卡到PC机，复制后再插TF卡到VCK190。
更方便的办法，是使用网络传输到VCK190的TF卡。Windows的winscp可以用来完成这个工作。但是Linux上流行的软件FileZilla 3.7.4.1, 与VCK190使用的Dropbear不能完成密钥交换，不能建立SFTP连接。下面是FileZilla报告的消息。
10:11:07 Trace: Couldn't agree a key exchange algorithm (available: curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp521,ecdh-sha2-nistp384,ecdh-sha2-nistp256,diffie-hellman-group14-sha256,kexguess2@matt.ucc.asn.au)
10:11:07 Error: Couldn't agree a key exchange algorithm (available: curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp521,ecdh-sha2-nistp384,ecdh-sha2-nistp256,diffie-hellman-group14-sha256,kexguess2@matt.ucc.asn.au)
经过尝试，使用gFTP,能建立SFTP连接。另外，默认的PetaLinux工程生成的Linux，每次启动时会重新生成新的密钥。gFTP第二次连接时，会报告密钥错误，也不能建立连接。建议删除文件“~/.ssh/known_hosts”中的VCK190对应的条目，gFTP就能建立连接。如果没有其它应用程序使用这个文件，可以删除整个文件。
rm ~/.ssh/known_hosts
gftp
查找PCI设备
使用lspci查找PCI设备。再结合grep工具，能快速找到xilinx的设备。找到设备后，指定总线信息，lspci可以读出更多的设备信息，比如BAR分配到的地址。下面的设备，BAR 0分配到的地址是a2000000；BAR 1分配到的地址是a0000000。
[root@localhost hankf]# lspci | grep -i xilinx
01:00.0 RAM memory: Xilinx Corporation Device b03f
[root@localhost hankf]# lspci -s 01:00.0 -v
01:00.0 RAM memory: Xilinx Corporation Device b03f
Subsystem: Xilinx Corporation Device 0007
Flags: bus master, fast devsel, latency 0
Memory at a2000000 (32-bit, non-prefetchable) [size=128K]
Memory at a0000000 (32-bit, non-prefetchable) [size=32M]
Capabilities: [40] Power Management version 3
Capabilities: [60] MSI-X: Enable+ Count=8 Masked-
Capabilities: [70] Express Endpoint, MSI 00
Capabilities: [100] Advanced Error Reporting
Capabilities: [140] Single Root I/O Virtualization (SR-IOV)
Capabilities: [180] Alternative Routing-ID Interpretation (ARI)
Capabilities: [1c0] #19
Capabilities: [3a0] #25
Capabilities: [3b0] #26
Capabilities: [400] #27
Kernel driver in use: qdma-pf
Kernel modules: qdma_pf
pcimem读写BAR的内存空间
Linux通过Sysfs，提供了各个PCI设备的详细信息，其中的resourceN对应各个BAR，再通过mmap可以访问其中的内容。更多信息，请参考文章Accessing PCI device resources through sysfs.
pcimem 通过Sysfs的resourceN，可以读写每个BAR的memory空间。pcimem的帮助信息如下。
[root@localhost pcie_host_fifo_app]# pcimem
Usage: pcimem { sysfile } { offset } [ type*count [ data ] ]
sys file: sysfs file for the pci resource to act on
offset : offset into pci memory region to act upon
type : access operation type : [b]yte, [h]alfword, [w]ord, [d]ouble-word
*count : number of items to read: w*100 will dump 100 words
data : data to be written
pcimem读BAR 1的memory空间中的32个word。
[root@localhost hankf]# pcimem /sys/bus/pci/devices/0000:01:00.0/resource1 0x00 w*32
/sys/bus/pci/devices/0000:01:00.0/resource1 opened.
Target offset is 0x0, page size is 4096
mmap(0, 4096, 0x3, 0x1, 3, 0x0)
PCI Memory mapped to address 0x7fa9117ff000.
0x0000: 0x00000000
...
0x0020: 0x64617064
0x0024: 0x00000000
0x0028: 0x00FD2000
0x002C: 0x00000000
...
0x0040: 0x73900000
0x0044: 0x00000000
0x0048: 0x017BB000
0x004C: 0x786C20D7
0x0050: 0x73900000
0x0054: 0x00000000
0x0058: 0x00FD2000
0x005C: 0x00000000
...
0x0064: 0x64617064
0x0068: 0x00000000
...
0x007C: 0xB4BE7EEF
pcimem写0到BAR 1的memory空间中的32个word。
[root@localhost pcie_host_fifo_app]# pcimem /sys/bus/pci/devices/0000:01:00.0/resource1 0x00 w*32 0x0
/sys/bus/pci/devices/0000:01:00.0/resource1 opened.
Target offset is 0x0, page size is 4096
mmap(0, 4096, 0x3, 0x1, 3, 0x0)
PCI Memory mapped to address 0x7f36f4215000.
0x0000: 0x00000000
...
0x0020: 0x64617064
0x0024: 0x00000000
0x0028: 0x00FD2000
0x002C: 0x00000000
...
0x0040: 0x73900000
0x0044: 0x00000000
...
0x0050: 0x72100000
0x0054: 0x00000000
...
0x0064: 0x64617064
0x0068: 0x00000000
...
0x007C: 0x7A7460D1
Written 0x0000; readback 0x7A7466F9
PCIe rescan
VCK190重启动后，PCIe Host会找不到设备，Linux系统里没有对应的设备和Sysfs节点。向“/sys/bus/pci/rescan”写入1，能触发Linux系统扫描PCIe总线。通过这种办法，VCK190重启动后，PCIe Host不需要重启动。
echo 1 > /sys/bus/pci/rescan
