Lines Matching refs:the
5 efficiently log and transfer large quantities of data from the kernel
11 clients write into the channel buffers using efficient write
12 functions; these automatically log into the current cpu's channel
13 buffer. User space applications mmap() or read() from the relay files
14 and retrieve the data as it becomes available. The relay files
16 are associated with the channel buffers using the API described below.
18 The format of the data logged into the channel buffers is completely
19 up to the kernel client; the relay interface does however provide
20 hooks which allow kernel clients to impose some structure on the
22 filtering - this also is left to the kernel client. The purpose is to
25 This document provides an overview of the relay interface API. The
26 details of the function parameters are documented along with the
27 functions in the relay interface code - please see that for details.
33 sub-buffers. Messages are written to the first sub-buffer until it is
35 the next (if available). Messages are never split across sub-buffers.
36 At this point, userspace can be notified so it empties the first
37 sub-buffer, while the kernel continues writing to the next.
39 When notified that a sub-buffer is full, the kernel knows how many
44 After copying it, userspace can notify the kernel that a sub-buffer
51 data between userspace and kernel, allowing the kernel side to remain
56 The read() interface both removes padding and internally consumes the
58 the channel buffers, special-purpose communication between kernel and
61 One of the major goals of the relay interface is to provide a low
62 overhead mechanism for conveying kernel data to userspace. While the
63 read() interface is easy to use, it's not as efficient as the mmap()
64 approach; the example code attempts to make the tradeoff between the
73 The relay-apps example tarball, available on the relay sourceforge
75 pair of .c files containing boilerplate code for each of the user and
80 The 'klog debugging functions' patch (klog.patch in the relay-apps
81 tarball) provides a couple of high-level logging functions to the
84 whether the relay interface is compiled into the kernel or not. These
86 in the kernel or kernel modules; only when there is a 'klog handler'
87 registered will data actually be logged (see the klog and kleak
90 It is of course possible to use the relay interface from scratch,
91 i.e. without using any of the relay-apps example code or klog, but
93 allowing both to convey the state of buffers (full, empty, amount of
95 consumes the read sub-buffers; thus in cases where read(2) is being
96 used to drain the channel buffers, special-purpose communication
101 klog and the relay-apps examples can be found in the relay-apps
108 access to relay channel buffer data. Here are the file operations
113 mmap() results in channel buffer being mapped into the caller's
115 must map the entire file, which is NRBUF * SUBBUFSIZE.
117 read() 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
124 users should make sure that all logging to the channel has
127 the reader.
131 and will not be seen by the reader.
136 close() 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.
140 In order for a user application to make use of relay files, the
145 NOTE: the host filesystem doesn't need to be mounted for kernel
147 mounted when user space applications need access to the buffer
154 Here's a summary of the API the relay interface provides to in-kernel clients:
194 created for it in the host filesystem, which can be and mmapped or
196 where N is the number of online cpus, and by default will be created
197 in the root of the filesystem (if the parent param is NULL). If you
199 create it using the host filesystem's directory creation function,
200 e.g. debugfs_create_dir(), and pass the parent directory to
202 structure they create, when the channel is closed - again the host
206 In order for a channel to be created and the host filesystem's files
207 associated with its channel buffers, the user must provide definitions
210 relay_open() and allows the user to create the file which will be used
211 to represent the corresponding channel buffer. The callback should
212 return the dentry of the file created to represent the channel buffer.
214 the file(s) created in create_buf_file() and is called during
256 If the create_buf_file() callback fails, or isn't defined, channel
259 The total size of each per-cpu buffer is calculated by multiplying the
260 number of sub-buffers by the sub-buffer size passed into relay_open().
265 of sub-buffers is completely dependent on the application and even for
266 the same application, different conditions will warrant different
267 values for these parameters at different times. Typically, the right
271 depending on the channel mode being used.
274 as to allow the creation of a single 'global' buffer instead of the
276 mainly in seeing the relative ordering of system-wide events without
277 the need to bother with saving explicit timestamps for the purpose of
280 To have relay_open() create a global buffer, the create_buf_file()
281 implementation should set the value of the is_global outparam to a
282 non-zero value in addition to creating the file that will be used to
283 represent the single buffer. In the case of a global buffer,
286 used - writes from any cpu will transparently end up in the global
288 they use the proper locking for such a buffer, either by wrapping
290 creating a local version that internally does the proper locking.
302 as when doing early tracing in the kernel, before the VFS is up. In these
304 relay_late_setup_files() when the kernel is ready to handle files,
305 to expose the buffered data to the userspace.
311 'no-overwrite'. The mode is entirely determined by the implementation
312 of the subbuf_start() callback, as described below. The default if no
313 subbuf_start() callback is defined is 'no-overwrite' mode. If the
314 default mode suits your needs, and you plan to use the read()
315 interface to retrieve channel data, you can ignore the details of this
319 continuously cycle around the buffer and will never fail, but will
322 be lost, if the number of unconsumed sub-buffers equals the total
323 number of sub-buffers in the channel. It should be clear that if
324 there is no consumer or if the consumer can't consume sub-buffers fast
325 enough, data will be lost in either case; the only difference is
326 whether data is lost from the beginning or the end of a buffer.
331 the current sub-buffer of the channel's current per-cpu buffer via the
333 the current sub-buffer, because there's no room left for it, the
334 client is notified via the subbuf_start() callback that a switch to a
336 initialize the next sub-buffer if appropriate 2) finalize the previous
338 whether or not to actually move on to the next sub-buffer.
340 To implement 'no-overwrite' mode, the userspace client would provide
341 an implementation of the subbuf_start() callback something like the
360 If the current buffer is full, i.e. all sub-buffers remain unconsumed,
361 the callback returns 0 to indicate that the buffer switch should not
362 occur yet, i.e. until the consumer has had a chance to read the
363 current set of ready sub-buffers. For the relay_buf_full() function
364 to make sense, the consumer is responsible for notifying the relay
366 relay_subbufs_consumed(). Any subsequent attempts to write into the
367 buffer will again invoke the subbuf_start() callback with the same
368 parameters; only when the consumer has consumed one or more of the
369 ready sub-buffers will relay_buf_full() return 0, in which case the
372 The implementation of the subbuf_start() callback for 'overwrite' mode
388 In this case, the relay_buf_full() check is meaningless and the
389 callback always returns 1, causing the buffer switch to occur
390 unconditionally. It's also meaningless for the client to use the
394 The default subbuf_start() implementation, used if the client doesn't
395 define any callbacks, or doesn't define the subbuf_start() callback,
396 implements the simplest possible 'no-overwrite' mode, i.e. it does
399 Header information can be reserved at the beginning of each sub-buffer
400 by calling the subbuf_start_reserve() helper function from within the
402 whatever information the client wants. In the example above, room is
403 reserved in each sub-buffer to store the padding count for that
404 sub-buffer. This is filled in for the previous sub-buffer in the
405 subbuf_start() implementation; the padding value for the previous
406 sub-buffer is passed into the subbuf_start() callback along with a
407 pointer to the previous sub-buffer, since the padding value isn't
409 also called for the first sub-buffer when the channel is opened, to
410 give the client a chance to reserve space in it. In this case the
411 previous sub-buffer pointer passed into the callback will be NULL, so
412 the client should check the value of the prev_subbuf pointer before
413 writing into the previous sub-buffer.
418 Kernel clients write data into the current cpu's channel buffer using
419 relay_write() or __relay_write(). relay_write() is the main logging
420 function - it uses local_irqsave() to protect the buffer and should be
425 failed - the assumption is that you wouldn't want to check a return
426 value in the fast logging path anyway, and that they'll always succeed
427 unless the buffer is full and no-overwrite mode is being used, in
428 which case you can detect a failed write in the subbuf_start()
429 callback by calling the relay_buf_full() helper function.
434 stage data in a temporary buffer beforehand. Because the actual write
435 may not happen immediately after the slot is reserved, applications
436 using relay_reserve() can keep a count of the number of bytes actually
437 written, either in space reserved in the sub-buffers themselves or as
438 a separate array. See the 'reserve' example in the relay-apps tarball
440 done. Because the write is under control of the client and is
441 separated from the reserve, relay_reserve() doesn't protect the buffer
442 at all - it's up to the client to provide the appropriate
448 The client calls relay_close() when it's finished using the channel.
450 longer any references to any of the channel buffers. relay_flush()
451 forces a sub-buffer switch on all the channel buffers, and can be used
452 to finalize and process the last sub-buffers before the channel is
463 do so, i.e. when the channel isn't currently being written to.
469 within the kernel application, such as enabling/disabling logging to
470 the channel.
476 For news, example code, mailing list, etc. see the relay interface homepage:
484 The ideas and specs for the relay interface came about as a result of
485 discussions on tracing involving the following: