3 The “Hello, world” test
3.1 The goal
Xillybus is a tool that is intended as a building block in a logic design. The best way to learn about Xillybus’ capabilities is hence to integrate it with your own user application logic. The demo bundle’s purpose is to be a starting point for working with Xillybus.
Therefore, the simplest possible application is implemented in the demo bundle: A loopback between two device files. This is achieved by connecting both sides of a FIFO to the Xillybus IP Core in the FPGA. As a result, when the host writes data to one device file, the FPGA returns the same data to the host through another device file.
The next few sections below explain how to test this simple functionality. This test is a simple method to verify that Xillybus operates correctly: The IP Core in the FPGA works as expected, the host detects the PCIe peripheral correctly, and the driver is installed properly. On top of that, this test is also an opportunity to learn how Xillybus works by making small modifications to the logic design in the FPGA.
As a first step, it’s recommended to make simple experiments with the demo bundle in order to understand how the logic in the FPGA and the device files work together. This alone often clarifies how to use Xillybus for your own application’s needs.
Aside from the loopback that is mentioned above, the demo bundle also implements a RAM and an additional loopback. This additional loopback is discussed briefly below. Regarding the RAM, it demonstrates how to access a memory array or registers. More information about this in section 4.4.
3.2 Preparations
A few preperations are required in order to perform the “Hello world” test:
-
Xillybus’ driver is installed on the computer, as described in section 2.
-
The FPGA must be loaded with the bitstream that is created from a demo bundle (without modifications). How to achieve this is explained in Getting started with the FPGA demo bundle for AMD or Getting started with the FPGA demo bundle for Altera.
Those who use Xillinux (with Zynq or Cyclone V SoC), see Getting started with Xillinux for Zynq-7000 or Getting started with Xillinux for Cyclone V SoC (SoCKit): The demo bundle is already included in this system by default.
-
Relevant for PCIe only: The FPGA was detected on the PCIe bus when the computer performed boot. This can be verified using the “lspci” command.
-
Relevant for USB only: The FPGA is connected to the computer through a USB port, and the computer has detected the FPGA as a USB device. This can be verified using the “lsusb” command.
-
You should be comfortable with using Linux command-line. Appendix A may help with this.
If these preparations have been done correctly, Xillybus’ device files should be available. For example, a file named /dev/xillybus_read_8 should exist.
3.3 The trivial loopback test
The easiest way to perform this test is using a Linux command-line utility that is named “cat”:
Open two terminal windows. On some computers, this can be done by double-clicking an icon with the name “Terminal”. If there is no such icon, search for it in the desktop’s menus.
On the first terminal window, type the following command at command prompt (don’t type the dollar sign, it’s the prompt):
$ cat /dev/xillybus_read_8
This makes the “cat” program print out everything it reads from the xillybus_read_8 device file. Nothing is expected to happen at this stage.
Those using XillyUSB will find the device file as xillyusb_00_read_8 instead. The “xillyusb” prefix is obvious, and the “00” index is intended to allow multiple USB devices to be connected to the same host. The naming convention for PCIe and for AXI is used in this guide.
On the second terminal window, type
$ cat > /dev/xillybus_write_8
Note the > character. It tells “cat” to send everything that is typed on the console to xillybus_write_8 (redirection).
Now type some text on the second terminal, and press ENTER. The same text will appear on the first terminal. Nothing is sent to xillybus_write_8 until ENTER is pressed. This is a common convention on Linux computers.
Both of these two “cat” commands can be stopped with CTRL-C.
If an error message is encountered while attempting these two “cat” commands, first verify that the device files have been created (i.e. that /dev/xillybus_read_8 and /dev/xillybus_write_8 exist). Also verify that there are no typos.
If the error is “permission denied”, this can be fixed as shown in section 2.7. However, note that a udev file becomes effective only when the kernel modules are loaded into the kernel. Refer to section 2.8 on how to reload the kernel modules. Alternatively, perform a reboot on the computer.
Another possibility to overcome the “permission denied” error is to work with the Xillybus device files as the root user. This is less recommended on desktop computers (but this is commonly done on embedded platforms). More about this in Appendix section A.4.
For other errors, follow the guidelines in section 2.8 on finding more information in /var/log/syslog or by using the “dmesg” command (or similar methods for obtaining the kernel log).
It’s also possible to perform trivial file operations. For example, without stopping the “cat” command in the first terminal, type the following in the second terminal:
$ date > /dev/xillybus_write_8
Note that the FIFOs inside the FPGA are not at risk for overflow nor underflow: The core respects the ’full’ and ’empty’ signals inside the FPGA. When necessary, the Xillybus driver forces the computer program to wait until the FIFO is ready for I/O. This is called blocking, which means forcing the user space program to sleep.
There is another pair of device files that have a loopback between them: /dev/xillybus_read_32 and /dev/xillybus_write_32. These device files work with a 32-bit word, and this is also true for the FIFO inside the FPGA. The “hello world” test with these device files will therefore result in similar behavior, with one difference: All I/O is carried out in groups of 4 bytes. Therefore, when the input hasn’t reached a boundary of 4 bytes, the last bytes from the input will remain untransmitted.