502 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==================================4relay interface (formerly relayfs)5==================================6 7The relay interface provides a means for kernel applications to8efficiently log and transfer large quantities of data from the kernel9to userspace via user-defined 'relay channels'.10 11A 'relay channel' is a kernel->user data relay mechanism implemented12as a set of per-cpu kernel buffers ('channel buffers'), each13represented as a regular file ('relay file') in user space. Kernel14clients write into the channel buffers using efficient write15functions; these automatically log into the current cpu's channel16buffer. User space applications mmap() or read() from the relay files17and retrieve the data as it becomes available. The relay files18themselves are files created in a host filesystem, e.g. debugfs, and19are associated with the channel buffers using the API described below.20 21The format of the data logged into the channel buffers is completely22up to the kernel client; the relay interface does however provide23hooks which allow kernel clients to impose some structure on the24buffer data. The relay interface doesn't implement any form of data25filtering - this also is left to the kernel client. The purpose is to26keep things as simple as possible.27 28This document provides an overview of the relay interface API. The29details of the function parameters are documented along with the30functions in the relay interface code - please see that for details.31 32Semantics33=========34 35Each relay channel has one buffer per CPU, each buffer has one or more36sub-buffers. Messages are written to the first sub-buffer until it is37too full to contain a new message, in which case it is written to38the next (if available). Messages are never split across sub-buffers.39At this point, userspace can be notified so it empties the first40sub-buffer, while the kernel continues writing to the next.41 42When notified that a sub-buffer is full, the kernel knows how many43bytes of it are padding i.e. unused space occurring because a complete44message couldn't fit into a sub-buffer. Userspace can use this45knowledge to copy only valid data.46 47After copying it, userspace can notify the kernel that a sub-buffer48has been consumed.49 50A relay channel can operate in a mode where it will overwrite data not51yet collected by userspace, and not wait for it to be consumed.52 53The relay channel itself does not provide for communication of such54data between userspace and kernel, allowing the kernel side to remain55simple and not impose a single interface on userspace. It does56provide a set of examples and a separate helper though, described57below.58 59The read() interface both removes padding and internally consumes the60read sub-buffers; thus in cases where read(2) is being used to drain61the channel buffers, special-purpose communication between kernel and62user isn't necessary for basic operation.63 64One of the major goals of the relay interface is to provide a low65overhead mechanism for conveying kernel data to userspace. While the66read() interface is easy to use, it's not as efficient as the mmap()67approach; the example code attempts to make the tradeoff between the68two approaches as small as possible.69 70klog and relay-apps example code71================================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 sourceforge77site, contains a set of self-contained examples, each consisting of a78pair of .c files containing boilerplate code for each of the user and79kernel sides of a relay application. When combined these two sets of80boilerplate code provide glue to easily stream data to disk, without81having to bother with mundane housekeeping chores.82 83The 'klog debugging functions' patch (klog.patch in the relay-apps84tarball) provides a couple of high-level logging functions to the85kernel which allow writing formatted text or raw data to a channel,86regardless of whether a channel to write into exists or not, or even87whether the relay interface is compiled into the kernel or not. These88functions allow you to put unconditional 'trace' statements anywhere89in the kernel or kernel modules; only when there is a 'klog handler'90registered will data actually be logged (see the klog and kleak91examples 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, but95you'll have to implement communication between userspace and kernel,96allowing both to convey the state of buffers (full, empty, amount of97padding). The read() interface both removes padding and internally98consumes the read sub-buffers; thus in cases where read(2) is being99used to drain the channel buffers, special-purpose communication100between kernel and user isn't necessary for basic operation. Things101such as buffer-full conditions would still need to be communicated via102some channel though.103 104klog and the relay-apps examples can be found in the relay-apps105tarball on http://relayfs.sourceforge.net106 107The relay interface user space API108==================================109 110The relay interface implements basic file operations for user space111access to relay channel buffer data. Here are the file operations112that 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's118 memory space. Note that you can't do a partial mmap - you119 must map the entire file, which is NRBUF * SUBBUFSIZE.120 121read() read the contents of a channel buffer. The bytes read are122 'consumed' by the reader, i.e. they won't be available123 again to subsequent reads. If the channel is being used124 in no-overwrite mode (the default), it can be read at any125 time even if there's an active kernel writer. If the126 channel is being used in overwrite mode and there are127 active channel writers, results may be unpredictable -128 users should make sure that all logging to the channel has129 ended before using read() with overwrite mode. Sub-buffer130 padding is automatically removed and will not be seen by131 the reader.132 133sendfile() transfer data from a channel buffer to an output file134 descriptor. Sub-buffer padding is automatically removed135 and will not be seen by the reader.136 137poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are138 notified when sub-buffer boundaries are crossed.139 140close() decrements the channel buffer's refcount. When the refcount141 reaches 0, i.e. when no process or kernel client has the142 buffer open, the channel buffer is freed.143=========== ============================================================144 145In order for a user application to make use of relay files, the146host filesystem must be mounted. For example::147 148 mount -t debugfs debugfs /sys/kernel/debug149 150.. Note::151 152 the host filesystem doesn't need to be mounted for kernel153 clients to create or use channels - it only needs to be154 mounted when user space applications need access to the buffer155 data.156 157 158The relay interface kernel API159==============================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 channel197------------------198 199relay_open() is used to create a channel, along with its per-cpu200channel buffers. Each channel buffer will have an associated file201created for it in the host filesystem, which can be and mmapped or202read from in user space. The files are named basename0...basenameN-1203where N is the number of online cpus, and by default will be created204in the root of the filesystem (if the parent param is NULL). If you205want a directory structure to contain your relay files, you should206create it using the host filesystem's directory creation function,207e.g. debugfs_create_dir(), and pass the parent directory to208relay_open(). Users are responsible for cleaning up any directory209structure they create, when the channel is closed - again the host210filesystem'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 files214associated with its channel buffers, the user must provide definitions215for two callback functions, create_buf_file() and remove_buf_file().216create_buf_file() is called once for each per-cpu buffer from217relay_open() and allows the user to create the file which will be used218to represent the corresponding channel buffer. The callback should219return the dentry of the file created to represent the channel buffer.220remove_buf_file() must also be defined; it's responsible for deleting221the file(s) created in create_buf_file() and is called during222relay_close().223 224Here are some typical definitions for these callbacks, in this case225using 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 callbacks252 */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, channel264creation and thus relay_open() will fail.265 266The total size of each per-cpu buffer is calculated by multiplying the267number of sub-buffers by the sub-buffer size passed into relay_open().268The idea behind sub-buffers is that they're basically an extension of269double-buffering to N buffers, and they also allow applications to270easily implement random-access-on-buffer-boundary schemes, which can271be important for some high-volume applications. The number and size272of sub-buffers is completely dependent on the application and even for273the same application, different conditions will warrant different274values for these parameters at different times. Typically, the right275values to use are best decided after some experimentation; in general,276though, it's safe to assume that having only 1 sub-buffer is a bad277idea - you're guaranteed to either overwrite data or lose events278depending on the channel mode being used.279 280The create_buf_file() implementation can also be defined in such a way281as to allow the creation of a single 'global' buffer instead of the282default per-cpu set. This can be useful for applications interested283mainly in seeing the relative ordering of system-wide events without284the need to bother with saving explicit timestamps for the purpose of285merging/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 a289non-zero value in addition to creating the file that will be used to290represent the single buffer. In the case of a global buffer,291create_buf_file() and remove_buf_file() will be called only once. The292normal channel-writing functions, e.g. relay_write(), can still be293used - writes from any cpu will transparently end up in the global294buffer - but since it is a global buffer, callers should make sure295they use the proper locking for such a buffer, either by wrapping296writes in a spinlock, or by copying a write function from relay.h and297creating a local version that internally does the proper locking.298 299The private_data passed into relay_open() allows clients to associate300user-defined data with a channel, and is immediately available301(including in create_buf_file()) via chan->private_data or302buf->chan->private_data.303 304Buffer-only channels305--------------------306 307These channels have no files associated and can be created with308relay_open(NULL, NULL, ...). Such channels are useful in scenarios such309as when doing early tracing in the kernel, before the VFS is up. In these310cases, one may open a buffer-only channel and then call311relay_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' or318'no-overwrite'. The mode is entirely determined by the implementation319of the subbuf_start() callback, as described below. The default if no320subbuf_start() callback is defined is 'no-overwrite' mode. If the321default mode suits your needs, and you plan to use the read()322interface to retrieve channel data, you can ignore the details of this323section, as it pertains mainly to mmap() implementations.324 325In 'overwrite' mode, also known as 'flight recorder' mode, writes326continuously cycle around the buffer and will never fail, but will327unconditionally overwrite old data regardless of whether it's actually328been consumed. In no-overwrite mode, writes will fail, i.e. data will329be lost, if the number of unconsumed sub-buffers equals the total330number of sub-buffers in the channel. It should be clear that if331there is no consumer or if the consumer can't consume sub-buffers fast332enough, data will be lost in either case; the only difference is333whether 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 more336per-cpu channel buffers, each implemented as a circular buffer337subdivided into one or more sub-buffers. Messages are written into338the current sub-buffer of the channel's current per-cpu buffer via the339write functions described below. Whenever a message can't fit into340the current sub-buffer, because there's no room left for it, the341client is notified via the subbuf_start() callback that a switch to a342new sub-buffer is about to occur. The client uses this callback to 1)343initialize the next sub-buffer if appropriate 2) finalize the previous344sub-buffer if appropriate and 3) return a boolean value indicating345whether or not to actually move on to the next sub-buffer.346 347To implement 'no-overwrite' mode, the userspace client would provide348an implementation of the subbuf_start() callback something like the349following::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 not369occur yet, i.e. until the consumer has had a chance to read the370current set of ready sub-buffers. For the relay_buf_full() function371to make sense, the consumer is responsible for notifying the relay372interface when sub-buffers have been consumed via373relay_subbufs_consumed(). Any subsequent attempts to write into the374buffer will again invoke the subbuf_start() callback with the same375parameters; only when the consumer has consumed one or more of the376ready sub-buffers will relay_buf_full() return 0, in which case the377buffer switch can continue.378 379The implementation of the subbuf_start() callback for 'overwrite' mode380would 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 the396callback always returns 1, causing the buffer switch to occur397unconditionally. It's also meaningless for the client to use the398relay_subbufs_consumed() function in this mode, as it's never399consulted.400 401The default subbuf_start() implementation, used if the client doesn't402define any callbacks, or doesn't define the subbuf_start() callback,403implements the simplest possible 'no-overwrite' mode, i.e. it does404nothing but return 0.405 406Header information can be reserved at the beginning of each sub-buffer407by calling the subbuf_start_reserve() helper function from within the408subbuf_start() callback. This reserved area can be used to store409whatever information the client wants. In the example above, room is410reserved in each sub-buffer to store the padding count for that411sub-buffer. This is filled in for the previous sub-buffer in the412subbuf_start() implementation; the padding value for the previous413sub-buffer is passed into the subbuf_start() callback along with a414pointer to the previous sub-buffer, since the padding value isn't415known until a sub-buffer is filled. The subbuf_start() callback is416also called for the first sub-buffer when the channel is opened, to417give the client a chance to reserve space in it. In this case the418previous sub-buffer pointer passed into the callback will be NULL, so419the client should check the value of the prev_subbuf pointer before420writing into the previous sub-buffer.421 422Writing to a channel423--------------------424 425Kernel clients write data into the current cpu's channel buffer using426relay_write() or __relay_write(). relay_write() is the main logging427function - it uses local_irqsave() to protect the buffer and should be428used if you might be logging from interrupt context. If you know429you'll never be logging from interrupt context, you can use430__relay_write(), which only disables preemption. These functions431don't return a value, so you can't determine whether or not they432failed - the assumption is that you wouldn't want to check a return433value in the fast logging path anyway, and that they'll always succeed434unless the buffer is full and no-overwrite mode is being used, in435which 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 which439can be written to later. This would typically be used in applications440that need to write directly into a channel buffer without having to441stage data in a temporary buffer beforehand. Because the actual write442may not happen immediately after the slot is reserved, applications443using relay_reserve() can keep a count of the number of bytes actually444written, either in space reserved in the sub-buffers themselves or as445a separate array. See the 'reserve' example in the relay-apps tarball446at http://relayfs.sourceforge.net for an example of how this can be447done. Because the write is under control of the client and is448separated from the reserve, relay_reserve() doesn't protect the buffer449at all - it's up to the client to provide the appropriate450synchronization when using relay_reserve().451 452Closing a channel453-----------------454 455The client calls relay_close() when it's finished using the channel.456The channel and its associated buffers are destroyed when there are no457longer any references to any of the channel buffers. relay_flush()458forces a sub-buffer switch on all the channel buffers, and can be used459to finalize and process the last sub-buffers before the channel is460closed.461 462Misc463----464 465Some applications may want to keep a channel around and re-use it466rather than open and close a new channel for each use. relay_reset()467can be used for this purpose - it resets a channel to its initial468state without reallocating channel buffer memory or destroying469existing mappings. It should however only be called when it's safe to470do 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 for473different purposes. buf_mapped() is called whenever a channel buffer474is mmapped from user space and buf_unmapped() is called when it's475unmapped. The client can use this notification to trigger actions476within the kernel application, such as enabling/disabling logging to477the channel.478 479 480Resources481=========482 483For news, example code, mailing list, etc. see the relay interface homepage:484 485 http://relayfs.sourceforge.net486 487 488Credits489=======490 491The ideas and specs for the relay interface came about as a result of492discussions 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 bug501reports.502