Import latest XDMA Driver to fix some version bugs

doc/load_xdma_driver.md

@@ -22,7 +22,7 @@ $ lspci
 然后 cd 到以下目录中，并运行 `make` 编译 Xilinx 提供的 XDMA 驱动 (注意这里需要用管理员权限) 。
 
 ```bash
-$ cd host_software/driver/xdma
+$ cd host_software/driver/XDMA/linux-kernel/xdma/
 $ sudo make
 ```
 
@@ -36,15 +36,24 @@ $ sudo rm *.ko
 $ sudo make
 ```
 
-
+## 编译测试工具
+
+本项目采用 Xilinx 官方提供的 [XDMA Linux 驱动](https://github.com/Xilinx/dma_ip_drivers) ，官方为其配套了一些测试工具，需要用户自行编译。借助这些工具，用户可以检查自己的驱动是否安装正确
+
+切换到 `tools` 目录，并运行 `make` 对工具进行编译
+
+```bash
+$ cd ../tools/
+$ sudo make
+```
 
 ## 加载 XDMA 驱动
 
-编译成功后，cd 到 上级目录，运行 `load_driver.sh` 脚本来加载驱动 。
+编译成功后，cd 到 `tests` 目录，运行 `load_driver.sh` 脚本来加载驱动 。需要注意 ，这里的 `load_driver.sh` 脚本 ，默认使用中断方式调用设备 ，因为我们前期配置中没有使用到XDMA的中断功能 ，因此需要使用一个参数来使用轮询方式加载驱动
 
 ```bash
-$ cd ..                     # cd 到上级目录 host_software/driver 中
-$ sudo ./load_driver
+$ cd ../tests/                     # cd 到上级目录 linux-kernel/tests 中
+$ sudo ./load_driver.sh 4
 ```
 
 如果驱动加载成功，则显示 `"DONE"` 。
@@ -61,5 +70,22 @@ $ ls /dev/xdma*
 
 其中我们要用到的设备是 `/dev/xdma0_c2h_0` 和 `/dev/xdma0_h2c_0` ，前者用来从 FPGA 中读取数据 (device_to_host) ，后者用来向 FPGA 中传送数据 (host_to_device)
 
-
+## 检验驱动是否正确启用
+
+完成加载后，可以通过调用 Xilinx 提供的测试工具来检测驱动正确性。在 `test` 目录中调用 `run_test.sh` 脚本，等待测试完毕即可
+
+```bash
+$ sudo sh ./run_test.sh
+```
+
+如果测试正常 ，程序将快速返回 ，给出 `Info: All PCIe DMA memory mapped tests passed.` 和 `Info: All tests in run_tests.sh passed.` 的结果
+
+如果卡死 ，可以卸载之前的 XDMA 驱动并检查之前步骤中是否以轮询方式加载 ，卸载使用下面的命令
+
+```bash
+$ sudo rmmod xdma
+```
+
+更多使用信息可以参考 `driver/XDMA/linux-kernel/readme.txt` 或前往 官方repo 进行查询
+
 

host_software/driver/XDMA/linux-kernel/LICENSE

@@ -0,0 +1,30 @@
+BSD License
+
+For Xilinx DMA IP software
+
+Copyright (c) 2016-present, Xilinx, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Xilinx nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

host_software/driver/XDMA/linux-kernel/RELEASE

@@ -0,0 +1,39 @@
+v2020.2.0
+=========
+- renamed module parameter "enable_credit_mp" to "enable_st_c2h_credit" to 
+  accurately describe its usage.
+- turn off the ST C2H credit as default (i.e., enable_st_c2h_credit = 0)
+- fixed c2h streaming credit issue when data buffers uses >= 1K descriptors.
+
+v2020.1.08
+===============
+- replaced module parameter "sgdma_timeout" to "h2c_timeout" and "c2h_timeout"
+  for H2C and C2H channels.
+  value of 0 means no timeout: wait forever for the dma completion.
+- added new "-e" option to dma_from_device
+  this is for streaming mode only, when -e is set, the driver will end the dma
+     and return the data when an EOP (end-of-packet) is received or the
+     specified bytes of data is received. 
+  without "-e" option, the driver will end the dma when the specified bytes of
+     data is received.
+- added gen4 device ids
+- fixed next adjacent descriptors when dma_alloc_coherent doesn't return a
+  page-aligned address
+
+v2020.1.06
+===============
+- added memory aperture support (-k) option in dma_from_device and dma_to_device.
+- fixed holding spinlock while doing wait_event_interruptible_xxx
+- kernel 5.0 support
+- fixed next adjacent descriptors crossing the 4K boundary
+
+Release: 2019.2
+===============
+
+Change list:
+- Updated data rate for performance run. Now it will print data rate based on the size.
+- remove BUG_ON, return proper error code instead
+- Streaming mode: enable credit mechanism by default 
+- Streaming mode: Do not read more than user supplied buffer size on C2H
+- Streaming mode: Added support for Async-IO for both streaming and MM transfers
+- fixed performance appliaction crash

host_software/driver/xdma/libxdma_api.h → host_software/driver/XDMA/linux-kernel/include/libxdma_api.h

@@ -4,10 +4,17 @@
  * Copyright (c) 2016-present,  Xilinx, Inc.
  * All rights reserved.
  *
- * This source code is licensed under both the BSD-style license (found in the
- * LICENSE file in the root directory of this source tree) and the GPLv2 (found
- * in the COPYING file in the root directory of this source tree).
- * You may select, at your option, one of the above-listed licenses.
+ * This source code is free software; you can redistribute it and/or modify it
+ * under the terms and conditions of the GNU General Public License,
+ * version 2, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * The full GNU General Public License is included in this distribution in
+ * the file called "COPYING".
  */
 
 #ifndef __XDMA_BASE_API_H__
@@ -125,6 +132,19 @@ int xdma_user_isr_disable(void *dev_hndl, unsigned int mask);
  */
 ssize_t xdma_xfer_submit(void *dev_hndl, int channel, bool write, u64 ep_addr,
 			struct sg_table *sgt, bool dma_mapped, int timeout_ms);
+
+ssize_t xdma_xfer_submit_nowait(void *cb_hndl, void *dev_hndl, int channel, bool write, u64 ep_addr,
+			struct sg_table *sgt, bool dma_mapped, int timeout_ms);
+
+
+ssize_t xdma_xfer_completion(void *cb_hndl, void *dev_hndl, int channel, bool write, u64 ep_addr,
+			struct sg_table *sgt, bool dma_mapped, int timeout_ms);
+
 
 
+/////////////////////missing API////////////////////
+
+//xdma_get_channle_state - if no interrupt on DMA hang is available
+//xdma_channle_restart
+
 #endif

host_software/driver/XDMA/linux-kernel/readme.txt

@@ -0,0 +1,177 @@
+The files in this directory provide Xilinx PCIe DMA drivers, example software,
+and example test scripts that can be used to exercise the Xilinx PCIe DMA IP.
+
+This software can be used directly or referenced to create drivers and software
+for your Xilinx FPGA hardware design.
+
+Operating System Support:
+=========================
+Operating System Architecture: x86_64
+Linux kernel:	3.10+
+RHEL/CentOS:	7.6, 7.7, 7.8, 7.9,
+		8.1, 8.2
+Ubuntu:		16.04.5 LTS, 16.04.6 LTS
+		18.04.1 LTS, 18.04.2 LTS, 18.04.4 LTS3, 18.04.5 LTS
+		20.04 LTS, 20.04.1 LT
+
+HW Requirement:
+===============
+The PCIe DMA supports UltraScale+, UltraScale, Virtex-7 XT and 7 Series Gen2
+devices.
+
+Please refer to the Xilinx documentation "PG195 DMA/Bridge Subsystem for PCI
+Express" for details of the IP.
+
+
+Directory and file description:
+===============================
+ - xdma/: This directory contains the Xilinx PCIe DMA kernel module
+       driver files.
+
+ - include/: This directory contains all include files that are needed for
+	compiling driver.
+
+ - tests/: This directory contains example application software to exercise the
+	provided kernel module driver and Xilinx PCIe DMA IP. This directory
+	also contains the following scripts and directories.
+
+	- load_driver.sh:
+		This script loads the kernel module and creates the necissary
+		kernel nodes used by the provided software.
+		The The kernel device nodes will be created under /dev/xdma*.
+		Additional device nodes are created under /dev/xdma/card* to
+		more easily differentiate between multiple PCIe DMA enabled
+		cards. Root permissions will be required to run this script.
+
+	- run_test.sh: 
+	- dma_memory_mapped_test.sh, dma_streaming_test.sh:
+	- data/:
+		run_test.sh runs sample tests on a Xilinx PCIe DMA target and
+		returns a pass (0) or fail (1) result.
+		This script calls 2 other scripts in the same directory:
+		- dma_memory_mapped_test.sh for memory-mapped dma mode
+		- dma_streaming_test.sh for streaming dma mode
+		The data/ directory contains binary data files that are used
+		for DMA data transfers to the Xilinx FPGA PCIe endpoint device
+		with the run_test.sh.
+		!NOTE!:
+		=======
+		These scripts are intended for use with the PCIe DMA EXAMPLE
+		DESIGN ONLY.
+
+	 - perform_hwcount.sh:
+		This script runs hardware performance for XDMA for both Host to
+		Card (H2C) and Card to Host (C2H). The result are copied to
+		'hw_log_h2c.txt' and hw_log_c2h.txt' text files. 
+		For each direction the performance script loops from 64 bytes
+		to 4MBytes and generate performance numbers (byte size doubles
+		for each loop count).
+		You can grep for 'data rate' on those two files to see data
+		rate values.
+		Data rate values are in percentage of maximum throughput.
+		Maximum data rate for x8 Gen3 is 8Gbytes/s, so for a x8Gen3
+		design value of 0.81 data rate is 0.81*8 = 6.48Gbytes/s.
+		Maximum data rate for x16 Gen3 is 16Gbytes/s, so for a x16Gen3
+		design value of 0.78 data rate is 0.78*16 = 12.48Gbytes/s.
+		This program can be run on AXI-MM example design.
+		AXI-ST example design is a loopback design, both H2C and C2H
+		are connected. Running on AXI-ST example design will not
+		generate proper numbers.
+		If a AXI-ST design is independent of H2C and C2H, performance
+		number can be generated. 
+
+	- scripts_mm/
+		This directory contains a set of scripts to check basic driver
+		loading/unloading and perform dma operations in memory-mapped
+		mode.
+		Compare with dma_memory_mapped_test.sh, the test is more
+		extensive with more dma size and it also utilizes fio tool in
+		addition to dma_from/to_device tools.
+
+		- xdma_mm.sh
+			top level script.
+
+		- io_sweep.sh, io.sh, unaligned
+			dma test via dma_from/to_device
+
+		- fio_test.sh fio_parse_result.sh
+			dma test via fio tool
+
+	- scripts_mm/ dependency
+		Some test in script_mm/ requires fio tool and python extension
+
+		Install fio:
+		- Centos/RHEL: yum install fio
+		- Ubuntu: apt install fio
+
+		Install python extension openpyxl, xlrd(version 1.2.0)
+			python --version
+			pip2 install openpyxl
+			pip2 install xlrd=1.2.0
+
+Usage:
+  - Change directory to the driver directory.
+        cd xdma
+  - Compile and install the kernel module driver.
+        make install
+  - Change directory to the tools directory.
+        cd tools
+  - Compile the provided example test tools.
+        make
+  - Load the kernel module driver:
+	a. modprobe xdma
+	b. using the provided script.
+		cd tests
+        	./load_driver.sh
+  - Run the provided test script to generate basic DMA traffic.
+        ./run_test.sh
+
+	For more extensive memory mapped test:
+	assume the XDMA FGPA is at pci slot 0000:01:00.0
+		cd scripts_mm
+		./xdma_mm.sh 0000:01:00.0 | tee /tmp/xdma_mm.log
+
+  - Check driver Version number
+        modinfo xdma (or)
+        modinfo ../xdma/xdma.ko    
+
+Updates and Backward Compaitiblity:
+  - The following features were added to the PCIe DMA IP and driver in Vivado
+    2016.1. These features cannot be used with PCIe DMA IP if the IP was
+    generated using a Vivado build earlier than 2016.1.
+      - Poll Mode: Earlier versions of Vivado only support interrupt mode which
+	is the default behavior of the driver.
+      - Source/Destination Address: Earlier versions of Vivado PCIe DMA IP
+	required the low-order bits of the Source and Destination address to be
+	the same.
+	As of 2016.1 this restriction has been removed and the Source and
+	Destination addresses can be any arbitrary address that is valid for
+        your system.
+
+Frequently asked questions:
+  Q: How do I uninstall the kernel module driver?
+  A: Use the following commands to uninstall the driver.
+       - Uninstall the kernel module.
+             rmmod -s xdma
+
+  Q: How do I modify the PCIe Device IDs recognized by the kernel module driver?
+  A: The xdma/xdma_mod.c file constains the pci_device_id struct that identifies
+     the PCIe Device IDs that are recognized by the driver in the following
+     format:
+         { PCI_DEVICE(0x10ee, 0x8038), },
+     Add, remove, or modify the PCIe Device IDs in this struct as desired. Then
+     uninstall the existing xdma kernel module, compile the driver again, and
+     re-install the driver using the load_driver.sh script.
+
+  Q: By default the driver uses interupts to signal when DMA transfers are
+     completed. How do I modify the driver to use polling rather than
+     interrupts to determine when DMA transactions are completed?
+  A: The driver can be changed from being interrupt driven (default) to being
+     polling driven (poll mode) when the kernel module is inserted. To do this
+     modify the load_driver.sh file as follows:
+        Change: insmod xdma/xdma.ko
+        To:     insmod xdma/xdma.ko poll_mode=1
+     Note: Interrupt vs Poll mode will apply to all DMA channels. If desired the
+     driver can be modified such that some channels are interrupt driven while
+     others are polling driven. Refer to the poll mode section of PG195 for
+     additional information on using the PCIe DMA IP in poll mode.