Download complete pdf

2 Installing the host driver

2.1 Stages for installing Xillybus’ driver

Installing the Linux kernel driver consists of the following steps:

  • Checking if an installation is needed at all. If not, skip the other steps below (possibly not skipping the last step, i.e. copying the udev file)

  • Checking for prerequisites (i.e. checking that the compiler and kernel headers are installed)

  • Uncompressing the downloaded file which contains the driver as a kernel module.

  • Running a compilation of the kernel module

  • Installing the kernel module

  • Installing the udev file, so that Xillybus device files become accessible to any user (and not only root).

These steps are carried out using command-line (“Terminal”). The short Linux survival guide in Appendix A may be helpful for those who are less experienced with this interface.

2.2 Do you really need to install anything?

2.2.1 General

The majority of Linux kernels and Linux distributions support Xillybus (for PCIe or AXI) without a need to do anything. This is explained further below.

That said, it’s worth looking at section 2.7 regarding the installation of a udev file, even if Xillybus is already supported.

The driver for XillyUSB is part of the Linux kernel from version 5.14 (released in August 2021).

2.2.2 Linux distributions with pre-installed driver

Most Linux distributions have the PCIe / AXI Xillybus driver already installed (“out of the box”). For example:

  • Ubuntu 14.04 and later

  • Any fairly recent Fedora distribution

  • Xillinux (for the Zynq and Cyclone V SoC platforms only)

In order to quickly check if the driver is installed, type the following at shell prompt:

$ modinfo xillybus_core

If the driver is installed, information about it is printed. Otherwise it says “modinfo: ERROR: Module xillybus_core not found”.

Likewise, to check for XillyUSB’s driver, the command is:

$ modinfo xillyusb

XillyUSB works without any need for installation with Ubuntu 22.04 and later, Fedora 35 and later, as well as distributions that are derived from these two.

Note that if Linux runs inside a virtual machine, it will not detect Xillybus on the PCIe bus. The operating system with the driver must run on bare metal. XillyUSB may work inside a virtual machine.

Section 2.7 shows how to permanently change the permissions of the Xillybus device files. This change makes these files accessible to any user (and not only to the root user). This modification is often desired when using Xillybus on a desktop computer.

2.2.3 Linux kernels that include Xillybus’ driver

Xillybus’ driver (for PCIe and AXI) is included in the official Linux kernel starting from version 3.12. In kernels with versions between 3.12 and 3.17, the driver was included as “staging driver”, which is a preliminary stage before Linux’ community fully accepts a new driver. Xillybus’ driver was admitted as non-staging in version 3.18. Despite several changes that are related to coding style, there are almost no functional differences between the earliest driver (in version 3.12 of the kernel) and the driver that is available today.

When a staging driver is loaded, the kernel issues a warning in the system log. This warning says that the driver’s quality is unknown. Regarding Xillybus, this warning can be ignored safely.

As mentioned above, the driver for XillyUSB is included in the Linux kernel starting from version 5.14.

Regarding kernels that are a part of a Linux distribution: Even when Xillybus’ drivers are part of the kernel’s source code, these drivers are included in the compilation only if the kernel is configured to include these drivers. Xillybus’ drivers are included as kernel modules in most mainstream Linux distributions, but each distribution has its own criteria for choosing what to include in the kernel. Accordingly, Xillybus may not be included in the kernel that arrives along with a distribution.

This guide focuses on installing the drivers by virtue of a separate compilation of the kernel modules. This is usually the easiest way. However, those who carry out a compilation of their kernel anyhow, may instead prefer to configure the kernel to include Xillybus’ drivers. This method is discussed in section 2.9.

2.3 Checking for prerequisites

A Linux system may lack the basic tools for a kernel module compilation. The simplest way to know if these tools exist is to attempt running them. For example, type “make coffee” on command prompt. This is the correct response:

$ make coffee

make: *** No rule to make target `coffee'. Stop.

Even though this is an error, we can see that the “make” utility exists. But if GNU make is missing and needs to be installed, the output will be something like this:

$ make coffee
bash: make: command not found

The C compiler is needed as well. Type “gcc” in order to check if the compiler is installed:

$ gcc
gcc: no input files

This response indicates that “gcc” is installed. There was an error message again, but not “command not found”.

On top of these two tools, the kernel headers need to be installed as well. This is a bit more difficult to check up. The common way to know if these files are missing is when the kernel compilation fails with an error saying that a header file is missing.

A kernel module compilation is a common task, so there is a lot of information on the Internet that is specific to each Linux distribution regarding how to prepare the system for the compilation.

On Fedora, RHEL, CentOS and other derivatives of Red Hat, a command of this sort is likely to get the computer prepared:

# yum install gcc make kernel-devel-$(uname -r)

For Ubuntu and other distributions that are based upon Debian:

# apt install gcc make linux-headers-$(uname -r)

IMPORTANT:
These installation commands must be issued as root. Those who are not familiar with the concept of being the root user are urged to learn about it first. See the Appendix’ section A.4.

2.4 Uncompressing the downloaded file

After downloading the driver from Xillybus’ site, change directory to where the downloaded file is. At command prompt, type (excluding the $ sign):

$ tar -xzf xillybus.tar.gz

For the XillyUSB driver:

$ tar -xzf xillyusb.tar.gz

There should be no response, just a new command prompt.

2.5 Running the compilation of the kernel module

Change directory to where the source code of the kernel module is. For the Xillybus driver:

$ cd xillybus/module

And for the XillyUSB driver:

$ cd xillyusb/driver

Type “make” to carry out the compilation of the modules. The transcript should be something like this:

$ make
make -C /lib/modules/3.10.0/build SUBDIRS=/home/myself/xillybus/module modules
make[1]: Entering directory `/usr/src/kernels/3.10.0'
 CC [M] /home/myself/xillybus/module/xillybus_core.o
 CC [M] /home/myself/xillybus/module/xillybus_pcie.o
 Building modules, stage 2.
 MODPOST 2 modules
 CC     /home/myself/xillybus/module/xillybus_core.mod.o
 LD [M] /home/myself/xillybus/module/xillybus_core.ko
 CC     /home/myself/xillybus/module/xillybus_pcie.mod.o
 LD [M] /home/myself/xillybus/module/xillybus_pcie.ko
make[1]: Leaving directory `/usr/src/kernels/3.10.0'

The details may vary slightly, but no errors or warnings should appear. For XillyUSB, only a single module, xillyusb.ko, is generated.

Note that the compilation of the kernel modules is specific to the kernel that is running during the compilation.

If another kernel is intended for use, type “make TARGET=kernel-version”, where “kernel-version” is the name of the required version of the kernel. This is the name that appears in /lib/modules/. Alternatively, edit the following line in the file with the name “Makefile”:

KDIR := /lib/modules/$(TARGET)/build

Change the value of KDIR to the path of the required kernel headers.

2.6 Installing the kernel module

Without changing directory, change the user to root (e.g. with “sudo su”). Then type the following command:

# make install

This command can take a few seconds to complete, but shouldn’t generate any errors.

If this fails, copy the *.ko files that were generated by the compilation to an existing subdirectory for kernel modules. Then run depmod. The following example shows how to do this for the PCIe driver, if the relevant version of the kernel is 3.10.0:

# cp xillybus_core.ko /lib/modules/3.10.0/kernel/drivers/char/
# cp xillybus_pcie.ko /lib/modules/3.10.0/kernel/drivers/char/

# depmod -a

The installation does not load the module into the kernel immediately. This is done on the next boot of the system if a Xillybus peripheral is discovered. How to load the module manually is shown in section 2.8.

For XillyUSB, a reboot is not necessary: The module is loaded automatically the next time the USB device is connected to the computer.

2.7 Copying the udev rule file

By default, Xillybus device files are accessible only by their owner, which is root. It makes a lot of sense to make these files accessible to any user, so that working as root can be avoided. The udev mechanism changes the file permissions when the device files are generated, by obeying specific rules.

How to enable this feature: Remain in the same directory, and remain being the root user. Copy the udev rule file to where such files are stored in your system (most likely /etc/udev/rules.d/).

For example:

# cp 10-xillybus.rules /etc/udev/rules.d/

The content of this file is simply:

SUBSYSTEM=="xillybus", MODE="666", OPTIONS="last_rule"

This means that all files that are generated by the Xillybus device driver should be given permission mode 0666. In other words, reading and writing is allowed to everyone.

For XillyUSB, the file is 10-xillyusb.rules, containing

SUBSYSTEM=="xilly*", KERNEL=="xillyusb_*", MODE="0666"

Note that the udev file can be changed to achieve different results. For example, it’s possible to change the device files’ owner instead, so only a specific user has access to these files.

2.8 Loading and unloading the module

In order to load the module (and start working with Xillybus), type as root:

# modprobe xillybus_pcie

Or, for XillyUSB:

# modprobe xillyusb

This will make the Xillybus device files appear (assuming that a Xillybus device is detected on the bus).

Note that this should not be necessary if a Xillybus PCIe / AXI peripheral was detected when the system carried out its boot process and the driver was already installed as described above. Neither is this necessary if a XillyUSB device is connected to the computer when the driver is already installed.

To see a list of modules in the kernel, type “lsmod”. To remove the module from the kernel, type (for the PCIe driver)

# rmmod xillybus_pcie xillybus_core

This will make the device files vanish.

If something seems to have gone wrong, please check up the /var/log/syslog file for messages containing the word “xillybus” or “xillyusb”, as applicable. Valuable clues are often found in this log file. The same log information is also accessible with the “dmesg” command.

If no /var/log/syslog log file exists, it’s probably /var/log/messages instead. Possibly try the command “journalctl -k”.

2.9 Xillybus drivers in the official Linux kernel

As mentioned before, the driver for Xillybus is included in the Linux kernel, starting from version v3.12.0. It’s therefore possible to carry out a compilation of the entire kernel, so that this kernel supports Xillybus. This is an alternative to installing the kernel modules separately, as shown above.

From a functional point of view, the method that involves kernel compilation yields the same result as the steps described in sections 2.3 to 2.6.

In order to include Xillybus’ driver in a kernel that is intended for compilation, it is necessary to enable a few kernel configuration options. There are two ways to include the driver: Either as kernel modules or as part of the kernel image.

For example, this is the part that enables Xillybus’ driver for the PCIe interface in the kernel’s configuration file (.config):

CONFIG_XILLYBUS=m
CONFIG_XILLYBUS_PCIE=m

“m” means that the driver is included as a kernel module. “y” means to include the driver in the kernel image.

Likewise, for XillyUSB (with kernel v5.14 and later):

CONFIG_XILLYUSB=m

The common way to make changes to .config is to use the kernel’s configuration tools: “make config”, “make xconfig” or “make gconfig”.

xconfig and gconfig are GUI tools that are easier to use, because they allow searching for the string “xillybus” in order to find Xillybus’ drivers. The driver is enabled by clicking on checkboxes. The textual representation of the .config file helps to verify that the correct options have been set.

On kernels that have a version below 3.18, it may be required to enable staging drivers before attempting to enable Xillybus. This results in the following line in the .config file.

CONFIG_STAGING=y

After enabling Xillybus’ driver in the .config file, run the kernel compilation as usual.

Starting from kernel 5.14, an option with the name CONFIG_XILLYBUS_CLASS is automatically enabled when a driver for Xillybus or XillyUSB is enabled. This is a result of the configuration system’s dependency rules. Changing this option manually is therefore unnecessary (and often impossible).