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
54 building block, with electrical wires dangling on the sides for connection to
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 -----------------
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-
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() ).
138 device files are treated like two independent pipes (except for sharing a
142 ---------------
170 --------------
184 ------------------------
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.
221 * bufnum: The number of buffers allocated for this pipe. 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 ------------------------------
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
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 ----------------
325 -------
342 -----------------
349 all buffers' sizes are powers of two, it's possible to pack any set of such
367 ----------------------------------------