【分享】VCK190 PCIe QDMA 通用数据传输参考设计

VCK190 PCIe QDMA 通用数据传输参考设计

目录

• VCK190 PCIe QDMA 通用数据传输参考设计
• 1. 概述
  • 作者
  • 测试环境
  • 代码来源
  • 主要改进
    • 内存复制
    • 忙等待
    • 剥离GStreamer
    • 握手机制
• X86-Host
  • 头文件
  • 数据结构
  • 初始化函数pcie_host_init
  • 退出函数pcie_host_exit
  • H2C函数pcie_host_qdma_h2c
  • C2H函数pcie_host_qdma_c2h
  • 使用流程
  • 测试过程
    • QDMA初始化流程
    • 数据校验
    • 性能
• Versal-Endpoint
  • BSP
    • devicetree
    • Linux Kernel
  • Versal-Endpoint应用程序
    • 头文件
    • 数据结构
    • 初始化函数pcie_ep_init
    • 退出函数pcie_ep_exit
    • H2C函数pcie_ep_qdma_h2c
    • C2H函数pcie_ep_qdma_c2h
    • 使用流程
• 调试技巧
  • 更新VCK190系统映像
  • 查找PCI设备
  • pcimem读写BAR的内存空间
  • PCIe rescan

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