linux/Documentation/filesystems/relay.rst
<<
>>
Prefs
   1.. SPDX-License-Identifier: GPL-2.0
   2
   3==================================
   4relay interface (formerly relayfs)
   5==================================
   6
   7The relay interface provides a means for kernel applications to
   8efficiently log and transfer large quantities of data from the kernel
   9to userspace via user-defined 'relay channels'.
  10
  11A 'relay channel' is a kernel->user data relay mechanism implemented
  12as a set of per-cpu kernel buffers ('channel buffers'), each
  13represented as a regular file ('relay file') in user space.  Kernel
  14clients write into the channel buffers using efficient write
  15functions; these automatically log into the current cpu's channel
  16buffer.  User space applications mmap() or read() from the relay files
  17and retrieve the data as it becomes available.  The relay files
  18themselves are files created in a host filesystem, e.g. debugfs, and
  19are associated with the channel buffers using the API described below.
  20
  21The format of the data logged into the channel buffers is completely
  22up to the kernel client; the relay interface does however provide
  23hooks which allow kernel clients to impose some structure on the
  24buffer data.  The relay interface doesn't implement any form of data
  25filtering - this also is left to the kernel client.  The purpose is to
  26keep things as simple as possible.
  27
  28This document provides an overview of the relay interface API.  The
  29details of the function parameters are documented along with the
  30functions in the relay interface code - please see that for details.
  31
  32Semantics
  33=========
  34
  35Each relay channel has one buffer per CPU, each buffer has one or more
  36sub-buffers.  Messages are written to the first sub-buffer until it is
  37too full to contain a new message, in which case it is written to
  38the next (if available).  Messages are never split across sub-buffers.
  39At this point, userspace can be notified so it empties the first
  40sub-buffer, while the kernel continues writing to the next.
  41
  42When notified that a sub-buffer is full, the kernel knows how many
  43bytes of it are padding i.e. unused space occurring because a complete
  44message couldn't fit into a sub-buffer.  Userspace can use this
  45knowledge to copy only valid data.
  46
  47After copying it, userspace can notify the kernel that a sub-buffer
  48has been consumed.
  49
  50A relay channel can operate in a mode where it will overwrite data not
  51yet collected by userspace, and not wait for it to be consumed.
  52
  53The relay channel itself does not provide for communication of such
  54data between userspace and kernel, allowing the kernel side to remain
  55simple and not impose a single interface on userspace.  It does
  56provide a set of examples and a separate helper though, described
  57below.
  58
  59The read() interface both removes padding and internally consumes the
  60read sub-buffers; thus in cases where read(2) is being used to drain
  61the channel buffers, special-purpose communication between kernel and
  62user isn't necessary for basic operation.
  63
  64One of the major goals of the relay interface is to provide a low
  65overhead mechanism for conveying kernel data to userspace.  While the
  66read() interface is easy to use, it's not as efficient as the mmap()
  67approach; the example code attempts to make the tradeoff between the
  68two approaches as small as possible.
  69
  70klog and relay-apps example code
  71================================
  72
  73The relay interface itself is ready to use, but to make things easier,
  74a couple simple utility functions and a set of examples are provided.
  75
  76The relay-apps example tarball, available on the relay sourceforge
  77site, contains a set of self-contained examples, each consisting of a
  78pair of .c files containing boilerplate code for each of the user and
  79kernel sides of a relay application.  When combined these two sets of
  80boilerplate code provide glue to easily stream data to disk, without
  81having to bother with mundane housekeeping chores.
  82
  83The 'klog debugging functions' patch (klog.patch in the relay-apps
  84tarball) provides a couple of high-level logging functions to the
  85kernel which allow writing formatted text or raw data to a channel,
  86regardless of whether a channel to write into exists or not, or even
  87whether the relay interface is compiled into the kernel or not.  These
  88functions allow you to put unconditional 'trace' statements anywhere
  89in the kernel or kernel modules; only when there is a 'klog handler'
  90registered will data actually be logged (see the klog and kleak
  91examples for details).
  92
  93It is of course possible to use the relay interface from scratch,
  94i.e. without using any of the relay-apps example code or klog, but
  95you'll have to implement communication between userspace and kernel,
  96allowing both to convey the state of buffers (full, empty, amount of
  97padding).  The read() interface both removes padding and internally
  98consumes the read sub-buffers; thus in cases where read(2) is being
  99used to drain the channel buffers, special-purpose communication
 100between kernel and user isn't necessary for basic operation.  Things
 101such as buffer-full conditions would still need to be communicated via
 102some channel though.
 103
 104klog and the relay-apps examples can be found in the relay-apps
 105tarball on http://relayfs.sourceforge.net
 106
 107The relay interface user space API
 108==================================
 109
 110The relay interface implements basic file operations for user space
 111access to relay channel buffer data.  Here are the file operations
 112that are available and some comments regarding their behavior:
 113
 114=========== ============================================================
 115open()      enables user to open an _existing_ channel buffer.
 116
 117mmap()      results in channel buffer being mapped into the caller's
 118            memory space. Note that you can't do a partial mmap - you
 119            must map the entire file, which is NRBUF * SUBBUFSIZE.
 120
 121read()      read the contents of a channel buffer.  The bytes read are
 122            'consumed' by the reader, i.e. they won't be available
 123            again to subsequent reads.  If the channel is being used
 124            in no-overwrite mode (the default), it can be read at any
 125            time even if there's an active kernel writer.  If the
 126            channel is being used in overwrite mode and there are
 127            active channel writers, results may be unpredictable -
 128            users should make sure that all logging to the channel has
 129            ended before using read() with overwrite mode.  Sub-buffer
 130            padding is automatically removed and will not be seen by
 131            the reader.
 132
 133sendfile()  transfer data from a channel buffer to an output file
 134            descriptor. Sub-buffer padding is automatically removed
 135            and will not be seen by the reader.
 136
 137poll()      POLLIN/POLLRDNORM/POLLERR supported.  User applications are
 138            notified when sub-buffer boundaries are crossed.
 139
 140close()     decrements the channel buffer's refcount.  When the refcount
 141            reaches 0, i.e. when no process or kernel client has the
 142            buffer open, the channel buffer is freed.
 143=========== ============================================================
 144
 145In order for a user application to make use of relay files, the
 146host filesystem must be mounted.  For example::
 147
 148        mount -t debugfs debugfs /sys/kernel/debug
 149
 150.. Note::
 151
 152        the host filesystem doesn't need to be mounted for kernel
 153        clients to create or use channels - it only needs to be
 154        mounted when user space applications need access to the buffer
 155        data.
 156
 157
 158The relay interface kernel API
 159==============================
 160
 161Here's a summary of the API the relay interface provides to in-kernel clients:
 162
 163TBD(curr. line MT:/API/)
 164  channel management functions::
 165
 166    relay_open(base_filename, parent, subbuf_size, n_subbufs,
 167               callbacks, private_data)
 168    relay_close(chan)
 169    relay_flush(chan)
 170    relay_reset(chan)
 171
 172  channel management typically called on instigation of userspace::
 173
 174    relay_subbufs_consumed(chan, cpu, subbufs_consumed)
 175
 176  write functions::
 177
 178    relay_write(chan, data, length)
 179    __relay_write(chan, data, length)
 180    relay_reserve(chan, length)
 181
 182  callbacks::
 183
 184    subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
 185    buf_mapped(buf, filp)
 186    buf_unmapped(buf, filp)
 187    create_buf_file(filename, parent, mode, buf, is_global)
 188    remove_buf_file(dentry)
 189
 190  helper functions::
 191
 192    relay_buf_full(buf)
 193    subbuf_start_reserve(buf, length)
 194
 195
 196Creating a channel
 197------------------
 198
 199relay_open() is used to create a channel, along with its per-cpu
 200channel buffers.  Each channel buffer will have an associated file
 201created for it in the host filesystem, which can be and mmapped or
 202read from in user space.  The files are named basename0...basenameN-1
 203where N is the number of online cpus, and by default will be created
 204in the root of the filesystem (if the parent param is NULL).  If you
 205want a directory structure to contain your relay files, you should
 206create it using the host filesystem's directory creation function,
 207e.g. debugfs_create_dir(), and pass the parent directory to
 208relay_open().  Users are responsible for cleaning up any directory
 209structure they create, when the channel is closed - again the host
 210filesystem's directory removal functions should be used for that,
 211e.g. debugfs_remove().
 212
 213In order for a channel to be created and the host filesystem's files
 214associated with its channel buffers, the user must provide definitions
 215for two callback functions, create_buf_file() and remove_buf_file().
 216create_buf_file() is called once for each per-cpu buffer from
 217relay_open() and allows the user to create the file which will be used
 218to represent the corresponding channel buffer.  The callback should
 219return the dentry of the file created to represent the channel buffer.
 220remove_buf_file() must also be defined; it's responsible for deleting
 221the file(s) created in create_buf_file() and is called during
 222relay_close().
 223
 224Here are some typical definitions for these callbacks, in this case
 225using debugfs::
 226
 227    /*
 228    * create_buf_file() callback.  Creates relay file in debugfs.
 229    */
 230    static struct dentry *create_buf_file_handler(const char *filename,
 231                                                struct dentry *parent,
 232                                                umode_t mode,
 233                                                struct rchan_buf *buf,
 234                                                int *is_global)
 235    {
 236            return debugfs_create_file(filename, mode, parent, buf,
 237                                    &relay_file_operations);
 238    }
 239
 240    /*
 241    * remove_buf_file() callback.  Removes relay file from debugfs.
 242    */
 243    static int remove_buf_file_handler(struct dentry *dentry)
 244    {
 245            debugfs_remove(dentry);
 246
 247            return 0;
 248    }
 249
 250    /*
 251    * relay interface callbacks
 252    */
 253    static struct rchan_callbacks relay_callbacks =
 254    {
 255            .create_buf_file = create_buf_file_handler,
 256            .remove_buf_file = remove_buf_file_handler,
 257    };
 258
 259And an example relay_open() invocation using them::
 260
 261  chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
 262
 263If the create_buf_file() callback fails, or isn't defined, channel
 264creation and thus relay_open() will fail.
 265
 266The total size of each per-cpu buffer is calculated by multiplying the
 267number of sub-buffers by the sub-buffer size passed into relay_open().
 268The idea behind sub-buffers is that they're basically an extension of
 269double-buffering to N buffers, and they also allow applications to
 270easily implement random-access-on-buffer-boundary schemes, which can
 271be important for some high-volume applications.  The number and size
 272of sub-buffers is completely dependent on the application and even for
 273the same application, different conditions will warrant different
 274values for these parameters at different times.  Typically, the right
 275values to use are best decided after some experimentation; in general,
 276though, it's safe to assume that having only 1 sub-buffer is a bad
 277idea - you're guaranteed to either overwrite data or lose events
 278depending on the channel mode being used.
 279
 280The create_buf_file() implementation can also be defined in such a way
 281as to allow the creation of a single 'global' buffer instead of the
 282default per-cpu set.  This can be useful for applications interested
 283mainly in seeing the relative ordering of system-wide events without
 284the need to bother with saving explicit timestamps for the purpose of
 285merging/sorting per-cpu files in a postprocessing step.
 286
 287To have relay_open() create a global buffer, the create_buf_file()
 288implementation should set the value of the is_global outparam to a
 289non-zero value in addition to creating the file that will be used to
 290represent the single buffer.  In the case of a global buffer,
 291create_buf_file() and remove_buf_file() will be called only once.  The
 292normal channel-writing functions, e.g. relay_write(), can still be
 293used - writes from any cpu will transparently end up in the global
 294buffer - but since it is a global buffer, callers should make sure
 295they use the proper locking for such a buffer, either by wrapping
 296writes in a spinlock, or by copying a write function from relay.h and
 297creating a local version that internally does the proper locking.
 298
 299The private_data passed into relay_open() allows clients to associate
 300user-defined data with a channel, and is immediately available
 301(including in create_buf_file()) via chan->private_data or
 302buf->chan->private_data.
 303
 304Buffer-only channels
 305--------------------
 306
 307These channels have no files associated and can be created with
 308relay_open(NULL, NULL, ...). Such channels are useful in scenarios such
 309as when doing early tracing in the kernel, before the VFS is up. In these
 310cases, one may open a buffer-only channel and then call
 311relay_late_setup_files() when the kernel is ready to handle files,
 312to expose the buffered data to the userspace.
 313
 314Channel 'modes'
 315---------------
 316
 317relay channels can be used in either of two modes - 'overwrite' or
 318'no-overwrite'.  The mode is entirely determined by the implementation
 319of the subbuf_start() callback, as described below.  The default if no
 320subbuf_start() callback is defined is 'no-overwrite' mode.  If the
 321default mode suits your needs, and you plan to use the read()
 322interface to retrieve channel data, you can ignore the details of this
 323section, as it pertains mainly to mmap() implementations.
 324
 325In 'overwrite' mode, also known as 'flight recorder' mode, writes
 326continuously cycle around the buffer and will never fail, but will
 327unconditionally overwrite old data regardless of whether it's actually
 328been consumed.  In no-overwrite mode, writes will fail, i.e. data will
 329be lost, if the number of unconsumed sub-buffers equals the total
 330number of sub-buffers in the channel.  It should be clear that if
 331there is no consumer or if the consumer can't consume sub-buffers fast
 332enough, data will be lost in either case; the only difference is
 333whether data is lost from the beginning or the end of a buffer.
 334
 335As explained above, a relay channel is made of up one or more
 336per-cpu channel buffers, each implemented as a circular buffer
 337subdivided into one or more sub-buffers.  Messages are written into
 338the current sub-buffer of the channel's current per-cpu buffer via the
 339write functions described below.  Whenever a message can't fit into
 340the current sub-buffer, because there's no room left for it, the
 341client is notified via the subbuf_start() callback that a switch to a
 342new sub-buffer is about to occur.  The client uses this callback to 1)
 343initialize the next sub-buffer if appropriate 2) finalize the previous
 344sub-buffer if appropriate and 3) return a boolean value indicating
 345whether or not to actually move on to the next sub-buffer.
 346
 347To implement 'no-overwrite' mode, the userspace client would provide
 348an implementation of the subbuf_start() callback something like the
 349following::
 350
 351    static int subbuf_start(struct rchan_buf *buf,
 352                            void *subbuf,
 353                            void *prev_subbuf,
 354                            unsigned int prev_padding)
 355    {
 356            if (prev_subbuf)
 357                    *((unsigned *)prev_subbuf) = prev_padding;
 358
 359            if (relay_buf_full(buf))
 360                    return 0;
 361
 362            subbuf_start_reserve(buf, sizeof(unsigned int));
 363
 364            return 1;
 365    }
 366
 367If the current buffer is full, i.e. all sub-buffers remain unconsumed,
 368the callback returns 0 to indicate that the buffer switch should not
 369occur yet, i.e. until the consumer has had a chance to read the
 370current set of ready sub-buffers.  For the relay_buf_full() function
 371to make sense, the consumer is responsible for notifying the relay
 372interface when sub-buffers have been consumed via
 373relay_subbufs_consumed().  Any subsequent attempts to write into the
 374buffer will again invoke the subbuf_start() callback with the same
 375parameters; only when the consumer has consumed one or more of the
 376ready sub-buffers will relay_buf_full() return 0, in which case the
 377buffer switch can continue.
 378
 379The implementation of the subbuf_start() callback for 'overwrite' mode
 380would be very similar::
 381
 382    static int subbuf_start(struct rchan_buf *buf,
 383                            void *subbuf,
 384                            void *prev_subbuf,
 385                            size_t prev_padding)
 386    {
 387            if (prev_subbuf)
 388                    *((unsigned *)prev_subbuf) = prev_padding;
 389
 390            subbuf_start_reserve(buf, sizeof(unsigned int));
 391
 392            return 1;
 393    }
 394
 395In this case, the relay_buf_full() check is meaningless and the
 396callback always returns 1, causing the buffer switch to occur
 397unconditionally.  It's also meaningless for the client to use the
 398relay_subbufs_consumed() function in this mode, as it's never
 399consulted.
 400
 401The default subbuf_start() implementation, used if the client doesn't
 402define any callbacks, or doesn't define the subbuf_start() callback,
 403implements the simplest possible 'no-overwrite' mode, i.e. it does
 404nothing but return 0.
 405
 406Header information can be reserved at the beginning of each sub-buffer
 407by calling the subbuf_start_reserve() helper function from within the
 408subbuf_start() callback.  This reserved area can be used to store
 409whatever information the client wants.  In the example above, room is
 410reserved in each sub-buffer to store the padding count for that
 411sub-buffer.  This is filled in for the previous sub-buffer in the
 412subbuf_start() implementation; the padding value for the previous
 413sub-buffer is passed into the subbuf_start() callback along with a
 414pointer to the previous sub-buffer, since the padding value isn't
 415known until a sub-buffer is filled.  The subbuf_start() callback is
 416also called for the first sub-buffer when the channel is opened, to
 417give the client a chance to reserve space in it.  In this case the
 418previous sub-buffer pointer passed into the callback will be NULL, so
 419the client should check the value of the prev_subbuf pointer before
 420writing into the previous sub-buffer.
 421
 422Writing to a channel
 423--------------------
 424
 425Kernel clients write data into the current cpu's channel buffer using
 426relay_write() or __relay_write().  relay_write() is the main logging
 427function - it uses local_irqsave() to protect the buffer and should be
 428used if you might be logging from interrupt context.  If you know
 429you'll never be logging from interrupt context, you can use
 430__relay_write(), which only disables preemption.  These functions
 431don't return a value, so you can't determine whether or not they
 432failed - the assumption is that you wouldn't want to check a return
 433value in the fast logging path anyway, and that they'll always succeed
 434unless the buffer is full and no-overwrite mode is being used, in
 435which case you can detect a failed write in the subbuf_start()
 436callback by calling the relay_buf_full() helper function.
 437
 438relay_reserve() is used to reserve a slot in a channel buffer which
 439can be written to later.  This would typically be used in applications
 440that need to write directly into a channel buffer without having to
 441stage data in a temporary buffer beforehand.  Because the actual write
 442may not happen immediately after the slot is reserved, applications
 443using relay_reserve() can keep a count of the number of bytes actually
 444written, either in space reserved in the sub-buffers themselves or as
 445a separate array.  See the 'reserve' example in the relay-apps tarball
 446at http://relayfs.sourceforge.net for an example of how this can be
 447done.  Because the write is under control of the client and is
 448separated from the reserve, relay_reserve() doesn't protect the buffer
 449at all - it's up to the client to provide the appropriate
 450synchronization when using relay_reserve().
 451
 452Closing a channel
 453-----------------
 454
 455The client calls relay_close() when it's finished using the channel.
 456The channel and its associated buffers are destroyed when there are no
 457longer any references to any of the channel buffers.  relay_flush()
 458forces a sub-buffer switch on all the channel buffers, and can be used
 459to finalize and process the last sub-buffers before the channel is
 460closed.
 461
 462Misc
 463----
 464
 465Some applications may want to keep a channel around and re-use it
 466rather than open and close a new channel for each use.  relay_reset()
 467can be used for this purpose - it resets a channel to its initial
 468state without reallocating channel buffer memory or destroying
 469existing mappings.  It should however only be called when it's safe to
 470do so, i.e. when the channel isn't currently being written to.
 471
 472Finally, there are a couple of utility callbacks that can be used for
 473different purposes.  buf_mapped() is called whenever a channel buffer
 474is mmapped from user space and buf_unmapped() is called when it's
 475unmapped.  The client can use this notification to trigger actions
 476within the kernel application, such as enabling/disabling logging to
 477the channel.
 478
 479
 480Resources
 481=========
 482
 483For news, example code, mailing list, etc. see the relay interface homepage:
 484
 485    http://relayfs.sourceforge.net
 486
 487
 488Credits
 489=======
 490
 491The ideas and specs for the relay interface came about as a result of
 492discussions on tracing involving the following:
 493
 494Michel Dagenais         <michel.dagenais@polymtl.ca>
 495Richard Moore           <richardj_moore@uk.ibm.com>
 496Bob Wisniewski          <bob@watson.ibm.com>
 497Karim Yaghmour          <karim@opersys.com>
 498Tom Zanussi             <zanussi@us.ibm.com>
 499
 500Also thanks to Hubertus Franke for a lot of useful suggestions and bug
 501reports.
 502