Xillybus' "Hello, world" test
This is the third step in getting started with Xillybus: The bitstream that contains Xillybus has already been loaded into the FPGA, and the driver is installed on the host. Now it's time to make a simple test. The purpose of this test is to verify that the device files have been created and that they work.
This page talks about Xillybus on a Windows host. There's a similar page for Linux.
I shall focus on Xillybus with PCIe here, but everything is almost the same with XillyUSB. The differences are listed at the bottom of this page.
For more information about this topic, refer to Getting started with Xillybus on a Windows.
Is the PCIe device detected?
The Device Manager shows the PCIe devices that have been detected. This was previously explained in the context of installing the driver.
Before the driver was installed, Xillybus' device appeared in the list for "Other Devices". After the installation, this device appears in a group called "Xillybus". If the Device Manager doesn't show any of these two options, the FPGA is not detected as a PCIe device: There is probably a problem with the FPGA. Often the reason is a confusion about which bitstream is loaded into the FPGA.
There are screenshots and a more detailed explanation about this topic in the Getting Started guide for Windows.
Did the driver start properly?
The next step is to check the driver's status. This is done in the Device Manager: Right-click the icon in the Xillybus group (the name of the device is "Xillybus driver for generic FPGA interface"). Choose "Properties". A pop-up window will appear. Look in the text window with the title "Device status". The text there should be "The device is working properly". This means that the driver has successfully initialized Xillybus and created the necessary device files.
If the text says anything else, something went wrong during the driver's initialization. This is usually a problem with the FPGA's logic. In particular, this tends to happen when the PCIe block in the FPGA is configured incorrectly. For example, if you changed the parameters of the PCIe block in the demo bundle, it can cause errors of this sort.
More information about the problem can be found in Windows' Event Viewer. The messages from Xillybus' driver can be filtered: Create a custom view that displays messages from the source called "Xillybus". How to do this is explained in detail in the Getting Started guide for Windows.
"Hello, world"
The driver creates five device files: \\.\xillybus_read_8, \\.\xillybus_read_32, \\.\xillybus_write_8, \\.\xillybus_write_32 and \\.\xillybus_mem_8. Note that if you create a custom IP core at the IP Core Factory, you can choose how many device files are created, as well as their names and properties.
But right now the FPGA contains the demo bundle. Let's try out two of the device files. These device files are in fact operating system objects, but they can be accessed like regular files. The "\\.\" part may seem peculiar to people who are not familiar with low-level programming in Windows. However, this is how the user-space software (often DLLs) usually accesses the hardware.
There is a loopback in the demo bundle between read_8 and write_8. This means that when the computer writes data to write_8, the FPGA returns exactly the same data through read_8. This is only intended as a demonstration. There is no other practical use for this loopback.
The test is as follows: Open two Command Prompt windows on your computer. In both Command Prompt windows, change the directory to "precompiled-demoapps". This directory is inside the "xillybus-windowspack" directory. Recall that I suggested downloading xillybus-windowspack.zip along with the demo bundle.
Type this on the first Command Prompt window:
$ streamread \\.\xillybus_read_8
Then type this on the second Command Prompt window:
$ streamwrite \\.\xillybus_write_8
Now type anything on the second Command Prompt window and press ENTER. The same text will appear in the first terminal. This shows how the text was written to the first device file, then reached the FPGA, and finally returned back to the computer.
You can stop these two programs with CTRL-C.
These programs' source code can be found in the demoapps subdirectory (from the same zip file). The programs are written in C, and they demonstrate how to access Xillybus' device files with a standard I/O API. The Getting Started guide for Windows suggests how to perform a compilation of these programs.
Even though this example is simple, it's important to understand how it works. In particular, it's important to understand how the logic in the FPGA made this happen. This is the starting point for integrating your own logic.
XillyUSB
If you're using XillyUSB, everything that is said above applies, but there are a few differences.
XillyUSB has a tool called showdiagnostics for examining the quality of the physical connection with the FPGA. It is highly recommended to use this tool in order to ensure that the raw data link is free from errors. Even if XillyUSB appears to work perfectly, it's important to make this check. The reason is that the USB 3.0 protocol hides errors on the raw data link, but these errors can still cause rare problems that look like a bug.
There is no reason to tolerate errors of this sort. The solution is often simple, e.g. using another USB plug of the computer.
Other differences:
- The names of the device files are slightly different. For example, instead of \\.\xillybus_read_8, the name is \\.\xillyusb_00_read_8. The "00" part may vary.
- The Device Manager will show the device under the group called "Universal Serial Bus controllers" (regardless of whether the driver is installed or not).