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