1 Introduction
Xillybus was designed to present the Linux host with a simple and well-known interface, having a natural and expected behavior. The host driver generates device files that behave like named pipes. They are opened, read from and written to just like any file, but behave much like pipes between processes or TCP/IP streams. To the program running on the host, the difference is that the other side of the stream is not another process (over the network or on the same computer), but a FIFO in the FPGA. Just like a TCP/IP stream, the Xillybus stream is designed to work well with high-rate data transfers as well single bytes arriving or sent occasionally.
Since the interface with Xillybus is all through device files that are accessed like just any file, typically any practical programming language can be used, with no need for a special module, extension or any other adaption. If a file can be opened with the chosen language, it can be used to access the FPGA through Xillybus.
One driver binary supports any Xillybus IP core configuration: The streams and their attributes are auto-detected by the driver as initializes the device, and device files are created accordingly. These device files are accessed as /dev/xillybus_something (or /dev/xillyusb_something with XillyUSB).
During operation, a handshake protocol between the FPGA and host makes an illusion of a continuous data stream. Behind the scenes, the driver’s buffers are filled and processed. Techniques similar to those used for TCP/IP streaming are used to ensure an efficient utilization of the buffers, while maintaining responsiveness for small pieces of data.
Since Xillybus I/O is carried out just like any device file I/O in Linux, there is apparently no need for a programming guide, as common programming practices can be employed.
Even so, communication with FPGA often involves tasks that are not typical to file I/O. This guide suggests methods to implementing common FPGA-related projects, as well as how to achieve optimal performance. Experienced programmers may choose different methods with equal success.
Much of this guide is no more than an outline of how robust and efficient I/O is implemented in UNIX systems. Those familiar with such techniques may find several parts in this guide redundant, and indeed they are; Xillybus was designed not to invent any new API, but rather behave like experienced programmers would expect it to.
The examples in this guide are given in plain C, for clarity and because it has a set of functions that are known to be closely related to low-level system calls. The techniques described can be implemented in several other languages, including script languages such as Perl and Python, in particular when the requirements for performance and synchronization between host and FPGA actions are less strict.
Some I/O can even be done with shell scripts and one-liners.