Documentation/driver-api/xillybus.rst

37 An FPGA (Field Programmable Gate Array) is a piece of logic hardware, which
38 can be programmed to become virtually anything that is usually found as a
39 dedicated chipset: For instance, a display adapter, network interface card,
40 or even a processor with its peripherals. FPGAs are the LEGO of hardware:
43 available on the market as a chipset, so FPGAs are mostly used when some
47 The challenge with FPGAs is that everything is implemented at a very low
52 mathematical functions, a functional unit (e.g. a USB interface), an entire
53 processor (e.g. ARM) or anything that might come handy. Think of them as a
57 One of the daunting tasks in FPGA design is communicating with a fullblown
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
70 a quicker and possibly less elegant solution is sought: The driver is
71 effectively written as a user space program, leaving the kernel space part
73 interface logic for the FPGA, and write a simple ad-hoc driver for the kernel.
78 Xillybus is an IP core and a Linux driver. Together, they form a kit for
80 data streams with a straightforward user interface. It's intended as a low-
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
91 communication to the user. At the host side, a character device file is used
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
101 up the DMA buffers and character devices accordingly. As a result, a single
118 and use plain write() or read() calls, just like with a regular pipe. In
138 device files are treated like two independent pipes (except for sharing a
145 asynchronous. For a synchronous pipe, write() returns successfully only after
148 require data at a constant rate: There is no data transmitted to the FPGA
151 When a pipe is configured asynchronous, write() returns if there was enough
156 has been requested by a read() call. On synchronous pipes, only the amount
157 of data requested by a read() call is transmitted.
165 that read() or write() completes less bytes than requested. There is a
166 separate configuration flag ("allowpartial") that determines whether such a
173 to the user logic at the FPGA. Such a pipe is also seekable on the host API.
174 With this feature, a memory or register interface can be attached on the
175 FPGA side to the seekable stream. Reading or writing to a certain address in
186 The Xillybus driver consists of a core module, xillybus_core.c, and modules
189 The bus specific modules are those probed when a suitable device is found by
191 dependent by their nature, are used by the core module, a
199 Each pipe has a number of attributes which are set when the FPGA component
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.
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.
237 Even though PCI Express is hotpluggable in general, a typical motherboard
238 doesn't expect a card to go away all of the sudden. But since the PCIe card
239 is based upon reprogrammable logic, a sudden disappearance from the bus is
240 quite likely as a result of an accidental reprogramming of the FPGA while the
241 host is up. In practice, nothing happens immediately in such a situation. But
244 even though the PCIe standard requires a graceful recovery.
249 doesn't follow the common practice of checking a status register when it's
250 invoked. Rather, the FPGA prepares a small buffer which contains short
260 a data channel between the FPGA and the host. The distinction between channels
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
272 buffer is full, the FPGA informs the host about that (appending a
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
282 being completed. This is implemented by adding a field in the
286 But the FPGA will submit a partially filled buffer only if directed to do so
289 the FPGA to submit a DMA buffer as soon as it can. This timeout mechanism
290 balances between bus bandwidth efficiency (preventing a lot of partially
291 filled buffers being sent) and a latency held fairly low for tails of data.
295 driver to submit all data it has in the buffers to the FPGA, by issuing a
296 write() with the byte count set to zero. This is similar to a flush request,
300 and yet enjoy a stream-like interface.
312 For example, reading single bytes from a pipe with 32 bit granularity works
319 when a buffer is flushed, it may contain up to 3 bytes don't form a word in
329 the driver's initialization, a blob containing configuration info, the
333 1. Acquire the length of the IDT, so a buffer can be allocated for it. This
334    is done by sending a quiesce command to the device, since the acknowledge
345 PCIe packets, the following rule applies: If a buffer is smaller than 4kB,
346 it must not cross a 4kB boundary. Otherwise, it must be 4kB aligned. The
350 buffers, with a maximal waste of one page of memory.
357 the IDT. The driver relies on a rule that the pipes are sorted with decreasing
358 buffer size in the IDT. If a requested buffer is larger or equal to a page,
360 used for this buffer. If the requested buffer is smaller than a page, one
362 Or, if there already is a partially used page at hand, the buffer is packed
369 In order to support the "poll" method (and hence select() ), there is a small
370 catch regarding the FPGA to host direction: The FPGA may have filled a DMA
372 the buffer's submission by the FPGA, there would be a possibility that the
373 FPGA side has sent data, but a select() call would still block, because the
375 XILLYMSG_OPCODE_NONEMPTY messages sent by the FPGA when a channel goes from
379 be configured not to send them for a slight reduction of bandwidth.