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 Linux host. There's a similar page for Microsoft Windows.
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. As for Xillinux, everything works in the same way, except for topics that are related directly to PCIe.
For more information about this topic, refer to Getting started with Xillybus on Linux.
Is the PCIe device detected?
The first thing to check is that computer recognizes the FPGA as a PCIe device. Use the "lspci" command for this purpose. This command shows all devices that the computer has found on the PCIe bus. Sometimes it's a very long list.
For example, with Xillybus on a Xilinx / AMD FPGA:
$ lspci [ ... several lines ... ] 01:00.0 Class ff00: Xilinx Corporation Device ebeb [ ... several lines ... ]
And with Altera:
01:00.0 Class ff00: Altera Corporation Unknown device ebeb
The output might be slightly different on your computer. The important part is "ebeb". This is the Device ID, which indicates that this is a Xillybus device.
If there is no such row in lspci's output, there is some problem with the FPGA. Often the reason is a confusion about which bitstream is loaded into the FPGA.
Did the driver start properly?
The next step is to check the driver's status. The easiest way is to search for the word "xillybus" in the kernel log. For example:
$ dmesg | grep xillybus
xillybus_pcie 0000:01:00.0: can't disable ASPM; OS doesn't have ASPM control
xillybus_pcie 0000:01:00.0: Created 5 device files.
The output's format varies from one computer to the next. The row that mentions ASPM is normal, and doesn't indicate an error. But it's also OK if there is no such row.
The row that says "Created 5 device files" confirms that the driver has successfully initialized Xillybus. If this row is absent, there was a problem with initializing the driver.
If there are other rows in the kernel log that are related to Xillybus, they can help explain what went wrong. 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 prevent the driver from initializing properly.
What if there is no row containing the word "xillybus" in the kernel log, but there was a row with "ebeb" in lspci's output? This means that the driver isn't loaded into the kernel. Check this with lsmod as follows:
$ lsmod | grep xillybus xillybus_pcie 16384 0 xillybus_core 28672 1 xillybus_pcie
This example shows the correct output when the driver is loaded into the kernel. The numbers (16384 and 28672) may be different. It's possible that xillybus_class will also appear in this list.
Note that if you just installed this driver, you need to restart the the computer or load the driver manually with insmod.
"Hello, world"
The driver creates five device files: /dev/xillybus_read_8, /dev/xillybus_read_32, /dev/xillybus_write_8, /dev/xillybus_write_32 and /dev/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.
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 terminal windows on the computer. Alternatively, utilize any other arrangement that gives you two shell prompts. For example, two ssh connections.
Type this on the first shell prompt:
$ cat /dev/xillybus_read_8
Then type this on the second shell prompt:
$ cat > /dev/xillybus_write_8
Now type anything on the second terminal 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.
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.
If these commands fail because of a permission denied error, repeat this as root. Alternatively, install the udev file as suggested before.
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:
- Use lsusb instead of lspci.
- The driver's modules are xillyusb and possibly xillybus_class.
- There is no need to restart the computer after installing the driver. The driver is loaded automatically when the device is connected to the USB plug (after being disconnected).
- The names of the device files are slightly different. For example, instead of /dev/xillybus_read_8, the name is /dev/xillyusb_00_read_8. The "00" part may vary.