9.1. Enhanced Support for Specific Chipsets Overview

In addition to the standard WinDriver APIs and the DriverWizard code generation capabilities described in this manual, which support development of drivers for any PCI/ISA device, WinDriver features enhanced support for specific PCI chipsets. This enhanced support includes custom APIs, customized code generation (for some of the chipsets), and sample diagnostics code, which are all designed specifically for these chipsets.

WinDriver's enhanced support is currently available for the following PCI chipsets: PLX 6466, 9030, 9050, 9052, 9054, 9056, 9080 and 9656; Altera Qsys design; Xilinx BMD, XDMA, QDMA designs.

Customized code generation is available for the Altera Qsys design, Xilinx BMD, XDMA, QDMA designs chipsets.

9.2. Developing a Driver Using the Enhanced Chipset Support

When developing a driver for a device based on one of the enhanced-support chipsets described above, you can use WinDriver's chipset-set specific support in the following manner: if your device is based on the Altera Qsys, Avalon-MM designs, Xilinx BMD, XDMA, QDMA designs, you can generate customized code for the device by selecting this option in the DriverWizard code generation options dialogue (see 6.2. DriverWizard Walkthrough). Alternatively, or if you are using another enhanced-support device, follow the steps below to use one the enhanced-support WinDriver samples as the starting point for your development:

Locate the sample diagnostics program for your device under the
WinDriver/samples/language/chip_vendor/chip_name directory.

Most of the sample diagnostics programs are named xxx_diag and their source code is normally found under an xxx_diag subdirectory. The program's executable is found under a subdirectory for your target operating system (e.g., WIN32 for Windows.)

Run the custom diagnostics program to diagnose your device and familiarize yourself with the options provided by the sample program.
Use the source code of the diagnostics program as your skeletal device driver and modify the code, as needed, to suit your specific development needs. When modifying the code, you can utilize the custom WinDriver API for your specific chip. The custom API is typically found under the WinDriver/samples/language/chip_vendor/lib directory.
If the user-mode driver application that you created by following the steps above contains parts that require enhanced performance (e.g., an interrupt handler), you can move the relevant portions of your code to a Kernel PlugIn driver for optimal performance, as explained in Chapter 11: Improving PCI Performance.

9.3. The XDMA sample code

Starting from version 12.3, WinDriver supplies a user-mode sample code of a diagnostic utility that demonstrates several features of Xilinx PCI Express cards programmed with a Xilinx DMA IP.

The sample source code and the pre-compiled sample can be found in the
WinDriver/samples/c/xilinx/xdma directory.

Before running the diagnostic utility, make sure that DriverWizard is closed, to avoid a “resource overlap” error.

‍⚠ Attention

‍If you have a proper XDMA supporting device attached, the diagnostic utility might open it automatically on startup, as shown here. Otherwise, you can choose option 2 and to try to open a device yourself.

The xdma_diag utility

9.3.1. Performing Direct Memory Access (DMA) tests

After choosing option 6 from the XDMA main menu, the user can either Perform a DMA transfer or Measure DMA Performance.

The DMA transfer option allows the user to actually read or write data from device.

The writing option prompts the user to type a hexadecimal 32 bit packet of data, and this packet is repeatedly written to the device’s memory, according to the user entered Number of packets to transfer. The reading option prints out the contents of a certain memory area, according to the user entered FPGA offset.

A simple test can be:

Writing a certain 32 bit packet to the device’s memory.
Reading from the same offset and making sure whether the data previously written to the device is in fact the data that is now read.

XDMA Transfer example

The DMA performance option allows the user to test the speed of the device. The user is prompted to choose a transfer direction (to device, from device, or simultaneous bi-directional transfers). Then the user is prompted to enter a buffer size for the each transfer that will be made during the test, and the test’s duration. Afterwards the test takes place and in the end of the test the results will be printed out.

XDMA Performance test example

9.3.2. The XDMA GUI utility

Starting from WinDriver version 12.5, WinDriver also supplies a GUI utility, based upon the same xdma_diag source code, showcasing the above mentioned DMA Transfer and DMA Performance tests. The xdma_gui utility can be found in the WinDriver/samples/c/xilinx/xdma/gui directory. Similar to the console xdma_diag program, the xdma_gui utility will try to open an XDMA device automatically, and if it will fail then it will be required to first select and open an XDMA-supported device before being able to perform the tests.

The xdma_gui Utility

DMA Transfer test in xdma_gui

DMA Performance in the xdma_gui Utility

9.3.3. XDMA code generation in DriverWizard

Starting from WinDriver version 12.5, DriverWizard allows generating a user-mode diagnostics program source code that is similar to the supplied xdma_diag program, by choosing Xilinx XDMA design from the Add device specific customization (optional) menu.

See 6.2.9.1. Samples Or Code Generation for more information.

9.4. The QDMA sample code

Starting from version 14.4 WinDriver supplies a cross-platform user-mode sample code of a diagnostic utility that demonstrates several features of Xilinx PCI Express cards with QDMA IP (Multi Queue DMA) support.

The sample source code and the pre-compiled sample can be found in the
WinDriver/samples/c/xilinx/qdma directory.

Before running the diagnostic utility, make sure that DriverWizard is closed, to avoid a “resource overlap” error.

‍⚠ Attention

‍If you have a QDMA supporting device attached, the diagnostic utility will open it automatically on startup. Or you can choose “Find and open a QDMA device” option to try to open a device yourself.

9.4.1. Performing Direct Memory Access (DMA) transaction

After choosing “Direct Memory Access (DMA) transaction” option, the user can either Perform a DMA transaction. The DMA transaction option allows the user to actually read or write data from device.

In order to do this you will need to:

Add a MM queue.
Start a MM queue.
Create a read request or write request.

If you selected Blocking method you can see the transaction details (including transaction rate) when it is finished, otherwise (Non-blocking method), you can see it in the Requests sub-menu.

9.4.2. Changing between physical functions

Several QDMA devices can be opened simultaneously. To switch between physical functions select “Change physical function” in the menu.

9.4.3. Requests info

The following actions may be done on the Requests menu:

Show requests list (read and write requests).
Show buffer content.
Delete request from list (Including free for the assigned buffer of the request).
Get status of all queues.

In order to get queues status (Available/Programmed/Started), select “Get queue status”.

9.4.4. QDMA code generation in DriverWizard

Starting from WinDriver version 14.4, DriverWizard allows generating a user-mode diagnostics program source code that is similar to the supplied qdma_diag program, by choosing Xilinx QDMA design from the “Add device specific customization” (optional) menu.

See 6.2.9.1. Samples Or Code Generation for more information.

9.5. The Avalon-MM sample code

Starting from version 14.7, WinDriver supplies a user-mode sample code of a diagnostic utility that demonstrates several features of Intel Altera PCI Express cards programmed with a Avalon-MM IP.

The sample source code and the pre-compiled sample can be found in the
WinDriver/samples/c/altera/avalonmm directory.

9.5.1. Avalon-MM code generation in DriverWizard

DriverWizard allows generating a user-mode diagnostics program source code that is similar to the supplied avalonmm_diag program, by choosing Altera Avalon Memory Mapped (Avalon-MM) design from the Add device specific customization (optional) menu.

See 6.2.9.1. Samples Or Code Generation for more information.

9.6. The CPNXDMA sample code

Starting from version 16.4 WinDriver supplies a cross-platform user-mode sample code of a diagnostic utility that demonstrates several features of Lattice CertusProNX SGDMA PCIe IP support.

This sample locks a single scatter-gather buffer for DMA data and a single contiguous buffer for the descriptors describing the memory transfer that should be transformed. Each descriptor holds a source address, a destination address, the length of the current data block, the address of the next descriptor and control bits (to control EOP/Interrupt).

The Lattice CertusProNX SGDMA PCIe IP supports 2 MSI interrupt vectors, the interrupt vector used is set by writing to H2F/F2H_INT_VEC register.

A DMA transfer is initiated by setting bit CPNXDMA_START_DMA of H2F/F2H_SGDMA_CTRL register.

9.6.1. CPNXDMA diagnostic utility features

The diagnostic utility includes a 'Direct Memory Access (DMA)' menu which includes the sub-menus:

Perform DMA transfer - Allows the user to perform a single transfer 'to device' or 'from device'.
Perform DMA transfer to device, perform DMA transfer from device and compare the DMA buffers - Allows the user to validate the DMA transfers using a pattern.
Perform DMA transfer to device with incremented data, perform DMA transfer from device and compare the DMA buffers - Allows the user to validate the DMA transfers using incremental data.
Measure DMA performance - This menu includes the sub-menus:
i. DMA host-to-device performance - To measure throughput of DMA transfers 'to device'.
ii. DMA device-to-host performance - To measure throughput of DMA transfers 'from device'.
iii. DMA host-to-device and device-to-host performance running simultaneously - To measure throughput of DMA transfers 'to device' and 'from device' performed simultaneously.

‍ℹ️ Note

‍All the above operations can be done using a Kernel Plugin (for higher performance) as well as without a kernel plugin.

9.6.2. CPNXDMA code generation in DriverWizard

DriverWizard allows generating a user-mode diagnostics program source code that is similar to the supplied cpnxdma_diag program, by choosing 'Lattice CPNXDMA design' from the Add device specific customization (optional) menu.

See 6.2.9.1. Samples Or Code Generation for more information.

9.7. The AVANTDMA sample code

Starting from version 16.4 WinDriver supplies a cross-platform user-mode sample code of a diagnostic utility that demonstrates several features of Lattice Avant DMA Bridge Core PCIe IP support.

This sample locks a single scatter-gather buffer for DMA data and four contiguous buffers for:

S/G DMA source address queue.
S/G DMA destination address queue.
S/G DMA source status queue.
S/G DMA destination status queue.

The S/G source address and S/G destination address queues describe the fragmentation of the source and destination memory transfer respectively.

The Lattice Avant DMA Bridge Core PCIe IP supports two DMA channels. DMA channel i raises an interrupt over interrupt vector i.

A DMA transfer is initiated by providing the DMA channel with queue elements of the S/G DMA address queue and the S/G DMA destination address queue, by setting SRC_Q_LIMIT/DST_Q_LIMIT registers.

9.7.1. AVANTDMA diagnostic utility features

The AVANTDMA sample has identical features to the CPNXDMA sample, for more information see 9.6.1. CPNXDMA diagnostic utility features.

9.7.1. AVANTDMA code generation in DriverWizard

DriverWizard allows generating a user-mode diagnostics program source code that is similar to the supplied avantdma_diag program, by choosing 'Lattice AVANTDMA design' from the Add device specific customization (optional) menu.

See 6.2.9.1. Samples Or Code Generation for more information.