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