Documentation/filesystems/relay.rst

1 .. SPDX-License-Identifier: GPL-2.0
9 to userspace via user-defined 'relay channels'.
11 A 'relay channel' is a kernel->user data relay mechanism implemented
12 as a set of per-cpu kernel buffers ('channel buffers'), each
25 filtering - this also is left to the kernel client.  The purpose is to
29 details of the function parameters are documented along with the
30 functions in the relay interface code - please see that for details.
36 sub-buffers.  Messages are written to the first sub-buffer until it is
38 the next (if available).  Messages are never split across sub-buffers.
40 sub-buffer, while the kernel continues writing to the next.
42 When notified that a sub-buffer is full, the kernel knows how many
44 message couldn't fit into a sub-buffer.  Userspace can use this
47 After copying it, userspace can notify the kernel that a sub-buffer
60 read sub-buffers; thus in cases where read(2) is being used to drain
61 the channel buffers, special-purpose communication between kernel and
70 klog and relay-apps example code
76 The relay-apps example tarball, available on the relay sourceforge
77 site, contains a set of self-contained examples, each consisting of a
83 The 'klog debugging functions' patch (klog.patch in the relay-apps
84 tarball) provides a couple of high-level logging functions to the
94 i.e. without using any of the relay-apps example code or klog, but
98 consumes the read sub-buffers; thus in cases where read(2) is being
99 used to drain the channel buffers, special-purpose communication
101 such as buffer-full conditions would still need to be communicated via
104 klog and the relay-apps examples can be found in the relay-apps
118 	    memory space. Note that you can't do a partial mmap - you
124 	    in no-overwrite mode (the default), it can be read at any
127 	    active channel writers, results may be unpredictable -
129 	    ended before using read() with overwrite mode.  Sub-buffer
134 	    descriptor. Sub-buffer padding is automatically removed
138 	    notified when sub-buffer boundaries are crossed.
148 	mount -t debugfs debugfs /sys/kernel/debug
153 	clients to create or use channels - it only needs to be
161 Here's a summary of the API the relay interface provides to in-kernel clients:
197 ------------------
199 relay_open() is used to create a channel, along with its per-cpu
202 read from in user space.  The files are named basename0...basenameN-1
206 create it using the host filesystem's directory creation function,
209 structure they create, when the channel is closed - again the host
216 create_buf_file() is called once for each per-cpu buffer from
266 The total size of each per-cpu buffer is calculated by multiplying the
267 number of sub-buffers by the sub-buffer size passed into relay_open().
268 The idea behind sub-buffers is that they're basically an extension of
269 double-buffering to N buffers, and they also allow applications to
270 easily implement random-access-on-buffer-boundary schemes, which can
271 be important for some high-volume applications.  The number and size
272 of sub-buffers is completely dependent on the application and even for
276 though, it's safe to assume that having only 1 sub-buffer is a bad
277 idea - you're guaranteed to either overwrite data or lose events
282 default per-cpu set.  This can be useful for applications interested
283 mainly in seeing the relative ordering of system-wide events without
285 merging/sorting per-cpu files in a postprocessing step.
289 non-zero value in addition to creating the file that will be used to
292 normal channel-writing functions, e.g. relay_write(), can still be
293 used - writes from any cpu will transparently end up in the global
294 buffer - but since it is a global buffer, callers should make sure
296 writes in a spinlock, or by copying a write function from relay.h and
300 user-defined data with a channel, and is immediately available
301 (including in create_buf_file()) via chan->private_data or
302 buf->chan->private_data.
304 Buffer-only channels
305 --------------------
310 cases, one may open a buffer-only channel and then call
315 ---------------
317 relay channels can be used in either of two modes - 'overwrite' or
318 'no-overwrite'.  The mode is entirely determined by the implementation
320 subbuf_start() callback is defined is 'no-overwrite' mode.  If the
328 been consumed.  In no-overwrite mode, writes will fail, i.e. data will
329 be lost, if the number of unconsumed sub-buffers equals the total
330 number of sub-buffers in the channel.  It should be clear that if
331 there is no consumer or if the consumer can't consume sub-buffers fast
336 per-cpu channel buffers, each implemented as a circular buffer
337 subdivided into one or more sub-buffers.  Messages are written into
338 the current sub-buffer of the channel's current per-cpu buffer via the
340 the current sub-buffer, because there's no room left for it, the
342 new sub-buffer is about to occur.  The client uses this callback to 1)
343 initialize the next sub-buffer if appropriate 2) finalize the previous
344 sub-buffer if appropriate and 3) return a boolean value indicating
345 whether or not to actually move on to the next sub-buffer.
347 To implement 'no-overwrite' mode, the userspace client would provide
367 If the current buffer is full, i.e. all sub-buffers remain unconsumed,
370 current set of ready sub-buffers.  For the relay_buf_full() function
372 interface when sub-buffers have been consumed via
376 ready sub-buffers will relay_buf_full() return 0, in which case the
398 relay_subbufs_consumed() function in this mode, as it's never
403 implements the simplest possible 'no-overwrite' mode, i.e. it does
406 Header information can be reserved at the beginning of each sub-buffer
407 by calling the subbuf_start_reserve() helper function from within the
410 reserved in each sub-buffer to store the padding count for that
411 sub-buffer.  This is filled in for the previous sub-buffer in the
413 sub-buffer is passed into the subbuf_start() callback along with a
414 pointer to the previous sub-buffer, since the padding value isn't
415 known until a sub-buffer is filled.  The subbuf_start() callback is
416 also called for the first sub-buffer when the channel is opened, to
418 previous sub-buffer pointer passed into the callback will be NULL, so
420 writing into the previous sub-buffer.
423 --------------------
427 function - it uses local_irqsave() to protect the buffer and should be
432 failed - the assumption is that you wouldn't want to check a return
434 unless the buffer is full and no-overwrite mode is being used, in
436 callback by calling the relay_buf_full() helper function.
444 written, either in space reserved in the sub-buffers themselves or as
445 a separate array.  See the 'reserve' example in the relay-apps tarball
449 at all - it's up to the client to provide the appropriate
453 -----------------
458 forces a sub-buffer switch on all the channel buffers, and can be used
459 to finalize and process the last sub-buffers before the channel is
463 ----
465 Some applications may want to keep a channel around and re-use it
467 can be used for this purpose - it resets a channel to its initial