Documentation/driver-api/xillybus.rst

10  - Introduction
11   -- Background
12   -- Xillybus Overview
14  - Usage
15   -- User interface
16   -- Synchronization
17   -- Seekable pipes
19  - Internals
20   -- Source code organization
21   -- Pipe attributes
22   -- Host never reads from the FPGA
23   -- Channels, pipes, and the message channel
24   -- Data streaming
25   -- Data granularity
26   -- Probing
27   -- Buffer allocation
28   -- The "nonempty" message (supporting poll)
35 ----------
50 again, pre-designed building blocks, IP cores, are often used. These are the
59 low-level bus protocol and the somewhat higher-level interface with the host
61 function is a well-known one (e.g. a video adapter card, or a NIC), it can
63 A special driver is then written to present the FPGA as a well-known interface
67 It's however common that the desired data communication doesn't fit any well-
73 interface logic for the FPGA, and write a simple ad-hoc driver for the kernel.
76 -----------------
78 Xillybus is an IP core and a Linux driver. Together, they form a kit for
79 elementary data transport between an FPGA and the host, providing pipe-like
80 data streams with a straightforward user interface. It's intended as a low-
81 effort solution for mixed FPGA-host projects, for which it makes sense to
82 have the project-specific part of the driver running in a user-space program.
87 IP core. Rather, the IP core is configured and built based upon a
93 the data. This is contrary to a common method of communicating through fixed-
95 There may be more than a hundred of these streams on a single IP core, but
98 In order to ease the deployment of the Xillybus IP core, it contains a simple
99 data structure which completely defines the core's configuration. The Linux
101 up the DMA buffers and character devices accordingly. As a result, a single
102 driver is used to work out of the box with any Xillybus IP core.
111 --------------
115 names of these files depend on the IP core that is loaded in the FPGA (see
125 possibly pressing CTRL-C as some stage, even though the xillybus_* pipes have
130 * Supporting non-blocking I/O (by setting O_NONBLOCK on open() ).
142 ---------------
144 Xillybus pipes are configured (on the IP core) to be either synchronous or
170 --------------
184 ------------------------
186 The Xillybus driver consists of a core module, xillybus_core.c, and modules
191 dependent by their nature, are used by the core module, a
192 xilly_endpoint_hardware structure is passed to the core module on
194 which execute the DMA-related operations on the bus.
197 ---------------
200 (IP core) is built. They are fetched from the IDT (the data structure which
201 defines the core's configuration, see Probing below) by xilly_setupchannels()
204 * is_writebuf: The pipe's direction. A non-zero value means it's an FPGA to
212 * allowpartial: A non-zero value means that a read() or write() (whichever
214   choice is a non-zero value, to match standard UNIX behavior.
216 * synchronous: A non-zero value means that the pipe is synchronous. See
223 * exclusive_open: A non-zero value forces exclusive opening of the associated
227 * seekable: A non-zero value indicates that the pipe is seekable. See
230 * supports_nonempty: A non-zero value (which is typical) indicates that the
235 ------------------------------
253 This mechanism is used on non-PCIe buses as well for the sake of uniformity.
257 ----------------------------------------
261 and pipes is necessary only because of channel 0, which is used for interrupt-
265 --------------
267 Even though a non-segmented data stream is presented to the user at both
271 FPGA, the Xillybus IP core writes it to one of the DMA buffers. When the
279 This is not good enough for creating a TCP/IP-like stream: If the data flow
300 and yet enjoy a stream-like interface.
307 ----------------
312 For example, reading single bytes from a pipe with 32 bit granularity works
313 with no issues. Writing single bytes to pipes with 16 or 32 bit granularity
325 -------
328 loads and their attributes depend on the Xillybus IP core in the FPGA. During
342 -----------------
361 single page is requested from the kernel, and that page is partially used.
367 ----------------------------------------
378 These messages are used only to support poll() and select(). The IP core can