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
60 (registers, interrupts, DMA etc.) is a project in itself. When the FPGA's
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 -----------------
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.
93 the data. This is contrary to a common method of communicating through fixed-
101 up the DMA buffers and character devices accordingly. As a result, a single
111 --------------
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() ).
134 * Being bandwidth efficient under load (using DMA) but also handle small
142 ---------------
170 --------------
184 ------------------------
190 the kernel. Since the DMA mapping and synchronization functions, which are bus
194 which execute the DMA-related operations on the bus.
197 ---------------
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
219 * bufsize: Each DMA buffer's size. Always a power of two.
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 ------------------------------
248 the host is done through DMA. In particular, the Interrupt Service Routine
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-
262 related messages from the FPGA, and has no pipe attached to it.
265 --------------
267 Even though a non-segmented data stream is presented to the user at both
268 sides, the implementation relies on a set of DMA buffers which is allocated
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
280 stops momentarily before a DMA buffer is filled, the intuitive expectation is
289 the FPGA to submit a DMA buffer as soon as it can. This timeout mechanism
294 partial DMA buffers is somewhat different, though. The user can tell the
300 and yet enjoy a stream-like interface.
304 to lay around in the DMA buffers between read() and write() anyhow.
307 ----------------
322 that mention "leftovers" in some way are related to this complication.
325 -------
342 -----------------
348 pages from the kernel, and diving them into DMA buffers as necessary. Since
367 ----------------------------------------
370 catch regarding the FPGA to host direction: The FPGA may have filled a DMA