0003 Xillybus driver for generic FPGA interface
0006 Author: Eli Billauer, Xillybus Ltd. (http://xillybus.com)
0007 Email: firstname.lastname@example.org or as advertised on Xillybus' site.
0011 - Introduction
0012 -- Background
0013 -- Xillybus Overview
0015 - Usage
0016 -- User interface
0017 -- Synchronization
0018 -- Seekable pipes
0020 - Internals
0021 -- Source code organization
0022 -- Pipe attributes
0023 -- Host never reads from the FPGA
0024 -- Channels, pipes, and the message channel
0025 -- Data streaming
0026 -- Data granularity
0027 -- Probing
0028 -- Buffer allocation
0029 -- The "nonempty" message (supporting poll)
0038 An FPGA (Field Programmable Gate Array) is a piece of logic hardware, which
0039 can be programmed to become virtually anything that is usually found as a
0040 dedicated chipset: For instance, a display adapter, network interface card,
0041 or even a processor with its peripherals. FPGAs are the LEGO of hardware:
0042 Based upon certain building blocks, you make your own toys the way you like
0043 them. It's usually pointless to reimplement something that is already
0044 available on the market as a chipset, so FPGAs are mostly used when some
0045 special functionality is needed, and the production volume is relatively low
0046 (hence not justifying the development of an ASIC).
0048 The challenge with FPGAs is that everything is implemented at a very low
0049 level, even lower than assembly language. In order to allow FPGA designers to
0050 focus on their specific project, and not reinvent the wheel over and over
0051 again, pre-designed building blocks, IP cores, are often used. These are the
0052 FPGA parallels of library functions. IP cores may implement certain
0053 mathematical functions, a functional unit (e.g. a USB interface), an entire
0054 processor (e.g. ARM) or anything that might come handy. Think of them as a
0055 building block, with electrical wires dangling on the sides for connection to
0056 other blocks.
0058 One of the daunting tasks in FPGA design is communicating with a fullblown
0059 operating system (actually, with the processor running it): Implementing the
0060 low-level bus protocol and the somewhat higher-level interface with the host
0061 (registers, interrupts, DMA etc.) is a project in itself. When the FPGA's
0062 function is a well-known one (e.g. a video adapter card, or a NIC), it can
0063 make sense to design the FPGA's interface logic specifically for the project.
0064 A special driver is then written to present the FPGA as a well-known interface
0065 to the kernel and/or user space. In that case, there is no reason to treat the
0066 FPGA differently than any device on the bus.
0068 It's however common that the desired data communication doesn't fit any well-
0069 known peripheral function. Also, the effort of designing an elegant
0070 abstraction for the data exchange is often considered too big. In those cases,
0071 a quicker and possibly less elegant solution is sought: The driver is
0072 effectively written as a user space program, leaving the kernel space part
0073 with just elementary data transport. This still requires designing some
0074 interface logic for the FPGA, and write a simple ad-hoc driver for the kernel.
0076 Xillybus Overview
0079 Xillybus is an IP core and a Linux driver. Together, they form a kit for
0080 elementary data transport between an FPGA and the host, providing pipe-like
0081 data streams with a straightforward user interface. It's intended as a low-
0082 effort solution for mixed FPGA-host projects, for which it makes sense to
0083 have the project-specific part of the driver running in a user-space program.
0085 Since the communication requirements may vary significantly from one FPGA
0086 project to another (the number of data pipes needed in each direction and
0087 their attributes), there isn't one specific chunk of logic being the Xillybus
0088 IP core. Rather, the IP core is configured and built based upon a
0089 specification given by its end user.
0091 Xillybus presents independent data streams, which resemble pipes or TCP/IP
0092 communication to the user. At the host side, a character device file is used
0093 just like any pipe file. On the FPGA side, hardware FIFOs are used to stream
0094 the data. This is contrary to a common method of communicating through fixed-
0095 sized buffers (even though such buffers are used by Xillybus under the hood).
0096 There may be more than a hundred of these streams on a single IP core, but
0097 also no more than one, depending on the configuration.
0099 In order to ease the deployment of the Xillybus IP core, it contains a simple
0100 data structure which completely defines the core's configuration. The Linux
0101 driver fetches this data structure during its initialization process, and sets
0102 up the DMA buffers and character devices accordingly. As a result, a single
0103 driver is used to work out of the box with any Xillybus IP core.
0105 The data structure just mentioned should not be confused with PCI's
0106 configuration space or the Flattened Device Tree.
0111 User interface
0114 On the host, all interface with Xillybus is done through /dev/xillybus_*
0115 device files, which are generated automatically as the drivers loads. The
0116 names of these files depend on the IP core that is loaded in the FPGA (see
0117 Probing below). To communicate with the FPGA, open the device file that
0118 corresponds to the hardware FIFO you want to send data or receive data from,
0119 and use plain write() or read() calls, just like with a regular pipe. In
0120 particular, it makes perfect sense to go:
0122 $ cat mydata > /dev/xillybus_thisfifo
0124 $ cat /dev/xillybus_thatfifo > hisdata
0126 possibly pressing CTRL-C as some stage, even though the xillybus_* pipes have
0127 the capability to send an EOF (but may not use it).
0129 The driver and hardware are designed to behave sensibly as pipes, including:
0131 * Supporting non-blocking I/O (by setting O_NONBLOCK on open() ).
0133 * Supporting poll() and select().
0135 * Being bandwidth efficient under load (using DMA) but also handle small
0136 pieces of data sent across (like TCP/IP) by autoflushing.
0138 A device file can be read only, write only or bidirectional. Bidirectional
0139 device files are treated like two independent pipes (except for sharing a
0140 "channel" structure in the implementation code).
0145 Xillybus pipes are configured (on the IP core) to be either synchronous or
0146 asynchronous. For a synchronous pipe, write() returns successfully only after
0147 some data has been submitted and acknowledged by the FPGA. This slows down
0148 bulk data transfers, and is nearly impossible for use with streams that
0149 require data at a constant rate: There is no data transmitted to the FPGA
0150 between write() calls, in particular when the process loses the CPU.
0152 When a pipe is configured asynchronous, write() returns if there was enough
0153 room in the buffers to store any of the data in the buffers.
0155 For FPGA to host pipes, asynchronous pipes allow data transfer from the FPGA
0156 as soon as the respective device file is opened, regardless of if the data
0157 has been requested by a read() call. On synchronous pipes, only the amount
0158 of data requested by a read() call is transmitted.
0160 In summary, for synchronous pipes, data between the host and FPGA is
0161 transmitted only to satisfy the read() or write() call currently handled
0162 by the driver, and those calls wait for the transmission to complete before
0165 Note that the synchronization attribute has nothing to do with the possibility
0166 that read() or write() completes less bytes than requested. There is a
0167 separate configuration flag ("allowpartial") that determines whether such a
0168 partial completion is allowed.
0170 Seekable pipes
0173 A synchronous pipe can be configured to have the stream's position exposed
0174 to the user logic at the FPGA. Such a pipe is also seekable on the host API.
0175 With this feature, a memory or register interface can be attached on the
0176 FPGA side to the seekable stream. Reading or writing to a certain address in
0177 the attached memory is done by seeking to the desired address, and calling
0178 read() or write() as required.
0184 Source code organization
0187 The Xillybus driver consists of a core module, xillybus_core.c, and modules
0188 that depend on the specific bus interface (xillybus_of.c and xillybus_pcie.c).
0190 The bus specific modules are those probed when a suitable device is found by
0191 the kernel. Since the DMA mapping and synchronization functions, which are bus
0192 dependent by their nature, are used by the core module, a
0193 xilly_endpoint_hardware structure is passed to the core module on
0194 initialization. This structure is populated with pointers to wrapper functions
0195 which execute the DMA-related operations on the bus.
0197 Pipe attributes
0200 Each pipe has a number of attributes which are set when the FPGA component
0201 (IP core) is built. They are fetched from the IDT (the data structure which
0202 defines the core's configuration, see Probing below) by xilly_setupchannels()
0203 in xillybus_core.c as follows:
0205 * is_writebuf: The pipe's direction. A non-zero value means it's an FPGA to
0206 host pipe (the FPGA "writes").
0208 * channelnum: The pipe's identification number in communication between the
0209 host and FPGA.
0211 * format: The underlying data width. See Data Granularity below.
0213 * allowpartial: A non-zero value means that a read() or write() (whichever
0214 applies) may return with less than the requested number of bytes. The common
0215 choice is a non-zero value, to match standard UNIX behavior.
0217 * synchronous: A non-zero value means that the pipe is synchronous. See
0218 Synchronization above.
0220 * bufsize: Each DMA buffer's size. Always a power of two.
0222 * bufnum: The number of buffers allocated for this pipe. Always a power of two.
0224 * exclusive_open: A non-zero value forces exclusive opening of the associated
0225 device file. If the device file is bidirectional, and already opened only in
0226 one direction, the opposite direction may be opened once.
0228 * seekable: A non-zero value indicates that the pipe is seekable. See
0229 Seekable pipes above.
0231 * supports_nonempty: A non-zero value (which is typical) indicates that the
0232 hardware will send the messages that are necessary to support select() and
0233 poll() for this pipe.
0235 Host never reads from the FPGA
0238 Even though PCI Express is hotpluggable in general, a typical motherboard
0239 doesn't expect a card to go away all of the sudden. But since the PCIe card
0240 is based upon reprogrammable logic, a sudden disappearance from the bus is
0241 quite likely as a result of an accidental reprogramming of the FPGA while the
0242 host is up. In practice, nothing happens immediately in such a situation. But
0243 if the host attempts to read from an address that is mapped to the PCI Express
0244 device, that leads to an immediate freeze of the system on some motherboards,
0245 even though the PCIe standard requires a graceful recovery.
0247 In order to avoid these freezes, the Xillybus driver refrains completely from
0248 reading from the device's register space. All communication from the FPGA to
0249 the host is done through DMA. In particular, the Interrupt Service Routine
0250 doesn't follow the common practice of checking a status register when it's
0251 invoked. Rather, the FPGA prepares a small buffer which contains short
0252 messages, which inform the host what the interrupt was about.
0254 This mechanism is used on non-PCIe buses as well for the sake of uniformity.
0257 Channels, pipes, and the message channel
0260 Each of the (possibly bidirectional) pipes presented to the user is allocated
0261 a data channel between the FPGA and the host. The distinction between channels
0262 and pipes is necessary only because of channel 0, which is used for interrupt-
0263 related messages from the FPGA, and has no pipe attached to it.
0265 Data streaming
0268 Even though a non-segmented data stream is presented to the user at both
0269 sides, the implementation relies on a set of DMA buffers which is allocated
0270 for each channel. For the sake of illustration, let's take the FPGA to host
0271 direction: As data streams into the respective channel's interface in the
0272 FPGA, the Xillybus IP core writes it to one of the DMA buffers. When the
0273 buffer is full, the FPGA informs the host about that (appending a
0274 XILLYMSG_OPCODE_RELEASEBUF message channel 0 and sending an interrupt if
0275 necessary). The host responds by making the data available for reading through
0276 the character device. When all data has been read, the host writes on the
0277 the FPGA's buffer control register, allowing the buffer's overwriting. Flow
0278 control mechanisms exist on both sides to prevent underflows and overflows.
0280 This is not good enough for creating a TCP/IP-like stream: If the data flow
0281 stops momentarily before a DMA buffer is filled, the intuitive expectation is
0282 that the partial data in buffer will arrive anyhow, despite the buffer not
0283 being completed. This is implemented by adding a field in the
0284 XILLYMSG_OPCODE_RELEASEBUF message, through which the FPGA informs not just
0285 which buffer is submitted, but how much data it contains.
0287 But the FPGA will submit a partially filled buffer only if directed to do so
0288 by the host. This situation occurs when the read() method has been blocking
0289 for XILLY_RX_TIMEOUT jiffies (currently 10 ms), after which the host commands
0290 the FPGA to submit a DMA buffer as soon as it can. This timeout mechanism
0291 balances between bus bandwidth efficiency (preventing a lot of partially
0292 filled buffers being sent) and a latency held fairly low for tails of data.
0294 A similar setting is used in the host to FPGA direction. The handling of
0295 partial DMA buffers is somewhat different, though. The user can tell the
0296 driver to submit all data it has in the buffers to the FPGA, by issuing a
0297 write() with the byte count set to zero. This is similar to a flush request,
0298 but it doesn't block. There is also an autoflushing mechanism, which triggers
0299 an equivalent flush roughly XILLY_RX_TIMEOUT jiffies after the last write().
0300 This allows the user to be oblivious about the underlying buffering mechanism
0301 and yet enjoy a stream-like interface.
0303 Note that the issue of partial buffer flushing is irrelevant for pipes having
0304 the "synchronous" attribute nonzero, since synchronous pipes don't allow data
0305 to lay around in the DMA buffers between read() and write() anyhow.
0307 Data granularity
0310 The data arrives or is sent at the FPGA as 8, 16 or 32 bit wide words, as
0311 configured by the "format" attribute. Whenever possible, the driver attempts
0312 to hide this when the pipe is accessed differently from its natural alignment.
0313 For example, reading single bytes from a pipe with 32 bit granularity works
0314 with no issues. Writing single bytes to pipes with 16 or 32 bit granularity
0315 will also work, but the driver can't send partially completed words to the
0316 FPGA, so the transmission of up to one word may be held until it's fully
0317 occupied with user data.
0319 This somewhat complicates the handling of host to FPGA streams, because
0320 when a buffer is flushed, it may contain up to 3 bytes don't form a word in
0321 the FPGA, and hence can't be sent. To prevent loss of data, these leftover
0322 bytes need to be moved to the next buffer. The parts in xillybus_core.c
0323 that mention "leftovers" in some way are related to this complication.
0328 As mentioned earlier, the number of pipes that are created when the driver
0329 loads and their attributes depend on the Xillybus IP core in the FPGA. During
0330 the driver's initialization, a blob containing configuration info, the
0331 Interface Description Table (IDT), is sent from the FPGA to the host. The
0332 bootstrap process is done in three phases:
0334 1. Acquire the length of the IDT, so a buffer can be allocated for it. This
0335 is done by sending a quiesce command to the device, since the acknowledge
0336 for this command contains the IDT's buffer length.
0338 2. Acquire the IDT itself.
0340 3. Create the interfaces according to the IDT.
0342 Buffer allocation
0345 In order to simplify the logic that prevents illegal boundary crossings of
0346 PCIe packets, the following rule applies: If a buffer is smaller than 4kB,
0347 it must not cross a 4kB boundary. Otherwise, it must be 4kB aligned. The
0348 xilly_setupchannels() functions allocates these buffers by requesting whole
0349 pages from the kernel, and diving them into DMA buffers as necessary. Since
0350 all buffers' sizes are powers of two, it's possible to pack any set of such
0351 buffers, with a maximal waste of one page of memory.
0353 All buffers are allocated when the driver is loaded. This is necessary,
0354 since large continuous physical memory segments are sometimes requested,
0355 which are more likely to be available when the system is freshly booted.
0357 The allocation of buffer memory takes place in the same order they appear in
0358 the IDT. The driver relies on a rule that the pipes are sorted with decreasing
0359 buffer size in the IDT. If a requested buffer is larger or equal to a page,
0360 the necessary number of pages is requested from the kernel, and these are
0361 used for this buffer. If the requested buffer is smaller than a page, one
0362 single page is requested from the kernel, and that page is partially used.
0363 Or, if there already is a partially used page at hand, the buffer is packed
0364 into that page. It can be shown that all pages requested from the kernel
0365 (except possibly for the last) are 100% utilized this way.
0367 The "nonempty" message (supporting poll)
0370 In order to support the "poll" method (and hence select() ), there is a small
0371 catch regarding the FPGA to host direction: The FPGA may have filled a DMA
0372 buffer with some data, but not submitted that buffer. If the host waited for
0373 the buffer's submission by the FPGA, there would be a possibility that the
0374 FPGA side has sent data, but a select() call would still block, because the
0375 host has not received any notification about this. This is solved with
0376 XILLYMSG_OPCODE_NONEMPTY messages sent by the FPGA when a channel goes from
0377 completely empty to containing some data.
0379 These messages are used only to support poll() and select(). The IP core can
0380 be configured not to send them for a slight reduction of bandwidth.