Introduction
This page is a short summary on how to get started with Xillybus or XillyUSB. This is usually a quick and simple procedure, which doesn't require a lot of guidance. However, there are slight variations between different FPGAs.
Only the most common use cases and the most recent FPGAs are covered here. When the information in this page is obviously lacking, refer to Xillybus' documentation page, which contains more detailed and specific information.
I shall not discuss Xillinux here, because its procedure is a bit different.
Overview
There are three steps to getting started with Xillybus:
- Generating a bitstream file for the FPGA from the demo bundle.
- Installing the driver on the computer (this is often not necessary).
- Performing a simple test on the computer that shows that Xillybus works (explained on separate pages for Linux and for Windows).
Later on, you may want to create your custom IP core at the IP Core Factory. This will allow you to choose as many streams as you like. But before getting to that, trying the demo bundle will help you understand how Xillybus works.
Xillybus vs. XillyUSB
If you're thinking about using XillyUSB, consider choosing Xillybus for PCIe instead, if that is a realistic option: The PCIe bus is by far more robust than USB.
XillyUSB should be chosen only when the FPGA must be physically outside the computer (for example, when a laptop is used as the host).
Downloading the demo bundle and software
Everything that is available for download from Xillybus' website is fully functional. This includes the IP cores from the IP Core Factory as well as the demo bundles. There is no need to request an activation code or anything of that sort. However, the legal permission to use the IP core is limited: You may use the IP core only for evaluation. After that, it may be necessary to purchase a license in order to continue using the IP core legally. So make sure that you understand the conditions.
There are two separate web pages for downloading files: For Xillybus using PCIe, and for XillyUSB. Go to the relevant web page, and download the following items:
- The demo bundle that is intended for your board.
- The driver for Linux or Microsoft Windows. Do this even if you're using Linux, and the driver is part of the Linux distribution.
- Windows users only: The Xillybus package for Windows.
- Windows users of XillyUSB only: The diagnostic utility for Windows.
All these files are in .zip or .tar.gz format. So start with an uncompression of their content into the disk.
If your board is not on the list of demo bundles, you will need to make modifications in this demo bundle. Select the demo bundle that is based upon the same FPGA family and follow the guidelines in the documentation for Xilinx or Intel FPGA.
The next step is different for AMD / Xilinx and Altera (formerly Intel FPGA).
Creating the bitstream for AMD / Xilinx
You need to have Vivado installed on your computer. The documentation contains a list of suitable versions for each FPGA. But if you already have installed Vivado, try using it. If Vivado's version is unsuitable, the procedure that is detailed below will fail: There will be an error saying that a newer version is required. If no such error occurs, your version of Vivado is OK.
These are the steps to create the bitstream file:
- Inside Vivado, select Tools > Tcl Script… and find xillydemo-vivado.tcl. This file is in the subdirectory with the name verilog/ or vhdl/. You probably know which one you prefer. If you don't know, choose verilog/.
- Vivado creates a new FPGA project in response. Vivado's Tcl console will say "INFO: Project created: xillydemo".
- Then click "Generate Bitstream".
- Vivado responds with running the implementation of the project. In the end of this process, there is a bitstream file that is ready for use. The name of this file is xillydemo.bit.
Vivado generates several warnings during the implementation, but there should be no Critical Warnings nor errors.
The detailed explanation is in this document: Getting started with the FPGA demo bundle for Xilinx. Note that Vivado doesn't work with Virtex-5, Spartan-6 and Virtex-6. If you use one of these FPGAs, refer to this document.
Don't try to create the FPGA project without the Tcl script. If you try to create a new project and import the source files, it will probably not work properly.
Creating the bitstream for Altera
You need to have Quartus installed on your computer. The documentation contains a list of suitable versions for each FPGA. But if you already have installed Quartus, try using it. If Quartus' version is unsuitable, the procedure that is detailed below will fail: There will be an error saying that a newer version is required. If no such error occurs, your version of Quartus is OK.
These are the steps to create the bitstream file:
- Double-click the "xillydemo.qpf" file. This file is in the subdirectory with the name verilog/ or vhdl/. You probably know which one you prefer. If you don't know, choose verilog/.
- Quartus opens the FPGA project in response.
- Click "Compile Design".
- Quartus responds with running the implementation of the project. In the end of this process, there is a bitstream file that is ready for use. The name of this file is xillydemo.sof.
Quartus generates several warnings during the implementation, but there should be no Critical Warnings nor errors.
The detailed explanation is in this document: Getting started with the FPGA demo bundle for Intel FPGA. If your FPGA is earlier than series-V (e.g. Cyclone IV), the procedure is a bit longer. Refer to this document for more information.
Installing the driver for Microsoft Windows
Xillybus' driver for Windows is installed in the standard way: Start the computer with the FPGA board inside. The FPGA must be loaded with the bitstream that contains Xillybus before the computer is turned on.
First, open the Zip archive that contains the driver into the local disk. This file can be found in the demo bundle's download page. The name of this file is something like xillybus-windriver-1.2.0.0.zip.
Inside the Device Manager, there should be a device that is listed under "Other Devices". This device's icon will indicate that the device is not installed properly (with an exclamation mark). Right-click this icon and select "Update Driver Software…". Choose to select a file from the computer ("Browse my computer for driver software"). Then select the directory with the name "xillybus-windriver-1.2.0.0" (or similar). Click "Next" and then "Install".
After the driver's proper installation, there will be a new group in the Device Manager, with the name "Xillybus". Inside this group, there will be a device with the title "Xillybus driver for generic FPGA interface". The device's icon should not indicate an error (i.e. no exclamation mark on this icon).
If XillyUSB is used, the device will appear under the group called "Universal Serial Bus controllers", and the driver is in xillyusb-windriver-1.1.2.0-win10.zip.
This installation procedure is described in more detail with screenshots in the guide for Windows.
After installing the driver for Windows, the next step is to make a simple test. This is explained on a separate page.
Installing the driver for Linux(?)
Xillybus' driver is included in many Linux distributions for desktop computers. So if you are using Fedora, Ubuntu or Mint, Xillybus' driver is probably installed on your computer already.
In order to check if the driver is already installed, type this at shell prompt:
$ modinfo xillybus_core
If the response is several lines of output: The driver is already installed, and there is no need to do anything. You need to install the driver only if the answer is "modinfo: ERROR: Module xillybus_core not found".
If you want to use XillyUSB, the command is
$ modinfo xillyusb
Even if the driver is already installed, it's a good idea to install Xillybus' udev file. See the bottom of this page. You can also skip this, and go directly to a simple test.
If the driver is not installed, there are two options:
- Installation of the driver as a kernel module. How to do this is explained below. This option is suitable if you have not prepared the kernel yourself (i.e. you have received the kernel as part of a distribution or a BSP (Board Support Package).
- Enable the driver that is inside the kernel tree. This method requires a compilation of the entire kernel. If a kernel compilation is part of your work procedure, this is the easier way. The relevant flags are CONFIG_XILLYBUS and CONFIG_XILLYBUS_PCIE (or CONFIG_XILLYUSB).
The driver for Xillybus is part of the Linux kernel tree since version v3.12. If your kernel's version is v4.6 or later, there is no reason to upgrade the driver: There has been no meaningful change since that version (only changes in coding style). The driver for XillyUSB was added to Linux v5.14.
More information about getting started with Linux can be found in the related guide.
Compilation of the kernel module
The compilation of Xillybus' kernel module requires that three things are already installed on the computer that performs the compilation:
- The gcc compiler
- "make"
- The kernel headers for the kernel that is used with Xillybus
The relevant guide for Linux suggests how to examine if these elements are installed, and how to install them if this is not the case.
The compilation of the driver is done as follows:
$ tar -xzf xillybus.tar.gz $ cd xillybus/module/ $ make make -C /lib/modules/4.15.0/build M=/home/01signal/xillybus/module modules make[1]: Entering directory '/usr/src/linux-headers-4.15.0' CC [M] /home/01signal/xillybus/module/xillybus_core.o CC [M] /home/01signal/xillybus/module/xillybus_pcie.o Building modules, stage 2. MODPOST 2 modules CC /home/01signal/xillybus/module/xillybus_core.mod.o LD [M] /home/01signal/xillybus/module/xillybus_core.ko CC /home/01signal/xillybus/module/xillybus_pcie.mod.o LD [M] /home/01signal/xillybus/module/xillybus_pcie.ko make[1]: Leaving directory '/usr/src/linux-headers-4.15.0'
In order to install the kernel modules, type "make install" (this requires root).
The driver will be loaded automatically on the next time that the kernel starts with a Xillybus device existing on the bus. It's also possible to use insmod to load the driver manually.
Note that those who intend to use Xillybus on an embedded Linux device may need to use a cross compiler. The kernel headers that are related to the embedded kernel are also required in this situation.
If you don't want to use "make install", it's possible to do the same thing manually: Copy the module files into the directory that contains the kernel modules. The name of this directory must contain the version number of the kernel that will run with Xillybus.
For example,
# cp xillybus_core.ko /lib/modules/4.15.0/kernel/drivers/char/ # cp xillybus_pcie.ko /lib/modules/4.15.0/kernel/drivers/char/
After this, run depmod so that the kernel will be aware of the new modules. For example:
# depmod -a 4.15.0-20
udev file (Linux)
It's recommended to install Xillybus' udev file, even if the driver is already installed. This allows accessing Xillybus without being the root user. This file is part of the package that contains the driver (xillybus.tar.gz or xillyusb.tar.gz).
The installation of the udev file for Xillybus consists of this command (or similar). As the root user:
# cp 10-xillybus.rules /etc/udev/rules.d/
Is it working?
The next step is to see if you did everything right, and Xillybus works on your hardware. How to do this is shown separately for Linux and for Windows.