blob: 094f2d2f38b1a5571283ee745aa494c12b12808c [file] [log] [blame]
Tom Zanussie88d78f2006-08-27 01:23:47 -07001relay 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
Randy Dunlap254012f2008-02-03 16:30:51 +0200143 mount -t debugfs debugfs /sys/kernel/debug
Tom Zanussie88d78f2006-08-27 01:23:47 -0700144
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,
Mathieu Desnoyers23c88752007-02-10 01:45:05 -0800160 callbacks, private_data)
Tom Zanussie88d78f2006-08-27 01:23:47 -0700161 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
Mathieu Desnoyers23c88752007-02-10 01:45:05 -0800254 chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
Tom Zanussie88d78f2006-08-27 01:23:47 -0700255
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
Mathieu Desnoyers23c88752007-02-10 01:45:05 -0800292The 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
Tom Zanussie88d78f2006-08-27 01:23:47 -0700297Channel 'modes'
298---------------
299
300relay channels can be used in either of two modes - 'overwrite' or
301'no-overwrite'. The mode is entirely determined by the implementation
302of the subbuf_start() callback, as described below. The default if no
303subbuf_start() callback is defined is 'no-overwrite' mode. If the
304default mode suits your needs, and you plan to use the read()
305interface to retrieve channel data, you can ignore the details of this
306section, as it pertains mainly to mmap() implementations.
307
308In 'overwrite' mode, also known as 'flight recorder' mode, writes
309continuously cycle around the buffer and will never fail, but will
310unconditionally overwrite old data regardless of whether it's actually
311been consumed. In no-overwrite mode, writes will fail, i.e. data will
312be lost, if the number of unconsumed sub-buffers equals the total
313number of sub-buffers in the channel. It should be clear that if
314there is no consumer or if the consumer can't consume sub-buffers fast
315enough, data will be lost in either case; the only difference is
316whether data is lost from the beginning or the end of a buffer.
317
318As explained above, a relay channel is made of up one or more
319per-cpu channel buffers, each implemented as a circular buffer
320subdivided into one or more sub-buffers. Messages are written into
321the current sub-buffer of the channel's current per-cpu buffer via the
322write functions described below. Whenever a message can't fit into
323the current sub-buffer, because there's no room left for it, the
324client is notified via the subbuf_start() callback that a switch to a
325new sub-buffer is about to occur. The client uses this callback to 1)
326initialize the next sub-buffer if appropriate 2) finalize the previous
327sub-buffer if appropriate and 3) return a boolean value indicating
328whether or not to actually move on to the next sub-buffer.
329
330To implement 'no-overwrite' mode, the userspace client would provide
331an implementation of the subbuf_start() callback something like the
332following:
333
334static int subbuf_start(struct rchan_buf *buf,
335 void *subbuf,
336 void *prev_subbuf,
337 unsigned int prev_padding)
338{
339 if (prev_subbuf)
340 *((unsigned *)prev_subbuf) = prev_padding;
341
342 if (relay_buf_full(buf))
343 return 0;
344
345 subbuf_start_reserve(buf, sizeof(unsigned int));
346
347 return 1;
348}
349
350If the current buffer is full, i.e. all sub-buffers remain unconsumed,
351the callback returns 0 to indicate that the buffer switch should not
352occur yet, i.e. until the consumer has had a chance to read the
353current set of ready sub-buffers. For the relay_buf_full() function
Matt LaPlantea982ac02007-05-09 07:35:06 +0200354to make sense, the consumer is responsible for notifying the relay
Tom Zanussie88d78f2006-08-27 01:23:47 -0700355interface when sub-buffers have been consumed via
356relay_subbufs_consumed(). Any subsequent attempts to write into the
357buffer will again invoke the subbuf_start() callback with the same
358parameters; only when the consumer has consumed one or more of the
359ready sub-buffers will relay_buf_full() return 0, in which case the
360buffer switch can continue.
361
362The implementation of the subbuf_start() callback for 'overwrite' mode
363would be very similar:
364
365static int subbuf_start(struct rchan_buf *buf,
366 void *subbuf,
367 void *prev_subbuf,
368 unsigned int prev_padding)
369{
370 if (prev_subbuf)
371 *((unsigned *)prev_subbuf) = prev_padding;
372
373 subbuf_start_reserve(buf, sizeof(unsigned int));
374
375 return 1;
376}
377
378In this case, the relay_buf_full() check is meaningless and the
379callback always returns 1, causing the buffer switch to occur
380unconditionally. It's also meaningless for the client to use the
381relay_subbufs_consumed() function in this mode, as it's never
382consulted.
383
384The default subbuf_start() implementation, used if the client doesn't
385define any callbacks, or doesn't define the subbuf_start() callback,
386implements the simplest possible 'no-overwrite' mode, i.e. it does
387nothing but return 0.
388
389Header information can be reserved at the beginning of each sub-buffer
390by calling the subbuf_start_reserve() helper function from within the
391subbuf_start() callback. This reserved area can be used to store
392whatever information the client wants. In the example above, room is
393reserved in each sub-buffer to store the padding count for that
394sub-buffer. This is filled in for the previous sub-buffer in the
395subbuf_start() implementation; the padding value for the previous
396sub-buffer is passed into the subbuf_start() callback along with a
397pointer to the previous sub-buffer, since the padding value isn't
398known until a sub-buffer is filled. The subbuf_start() callback is
399also called for the first sub-buffer when the channel is opened, to
400give the client a chance to reserve space in it. In this case the
401previous sub-buffer pointer passed into the callback will be NULL, so
402the client should check the value of the prev_subbuf pointer before
403writing into the previous sub-buffer.
404
405Writing to a channel
406--------------------
407
408Kernel clients write data into the current cpu's channel buffer using
409relay_write() or __relay_write(). relay_write() is the main logging
410function - it uses local_irqsave() to protect the buffer and should be
411used if you might be logging from interrupt context. If you know
412you'll never be logging from interrupt context, you can use
413__relay_write(), which only disables preemption. These functions
414don't return a value, so you can't determine whether or not they
415failed - the assumption is that you wouldn't want to check a return
416value in the fast logging path anyway, and that they'll always succeed
417unless the buffer is full and no-overwrite mode is being used, in
418which case you can detect a failed write in the subbuf_start()
419callback by calling the relay_buf_full() helper function.
420
421relay_reserve() is used to reserve a slot in a channel buffer which
422can be written to later. This would typically be used in applications
423that need to write directly into a channel buffer without having to
424stage data in a temporary buffer beforehand. Because the actual write
425may not happen immediately after the slot is reserved, applications
426using relay_reserve() can keep a count of the number of bytes actually
427written, either in space reserved in the sub-buffers themselves or as
428a separate array. See the 'reserve' example in the relay-apps tarball
429at http://relayfs.sourceforge.net for an example of how this can be
430done. Because the write is under control of the client and is
431separated from the reserve, relay_reserve() doesn't protect the buffer
432at all - it's up to the client to provide the appropriate
433synchronization when using relay_reserve().
434
435Closing a channel
436-----------------
437
438The client calls relay_close() when it's finished using the channel.
439The channel and its associated buffers are destroyed when there are no
440longer any references to any of the channel buffers. relay_flush()
441forces a sub-buffer switch on all the channel buffers, and can be used
442to finalize and process the last sub-buffers before the channel is
443closed.
444
445Misc
446----
447
448Some applications may want to keep a channel around and re-use it
449rather than open and close a new channel for each use. relay_reset()
450can be used for this purpose - it resets a channel to its initial
451state without reallocating channel buffer memory or destroying
452existing mappings. It should however only be called when it's safe to
453do so, i.e. when the channel isn't currently being written to.
454
455Finally, there are a couple of utility callbacks that can be used for
456different purposes. buf_mapped() is called whenever a channel buffer
457is mmapped from user space and buf_unmapped() is called when it's
458unmapped. The client can use this notification to trigger actions
459within the kernel application, such as enabling/disabling logging to
460the channel.
461
462
463Resources
464=========
465
466For news, example code, mailing list, etc. see the relay interface homepage:
467
468 http://relayfs.sourceforge.net
469
470
471Credits
472=======
473
474The ideas and specs for the relay interface came about as a result of
475discussions on tracing involving the following:
476
477Michel Dagenais <michel.dagenais@polymtl.ca>
478Richard Moore <richardj_moore@uk.ibm.com>
479Bob Wisniewski <bob@watson.ibm.com>
480Karim Yaghmour <karim@opersys.com>
481Tom Zanussi <zanussi@us.ibm.com>
482
483Also thanks to Hubertus Franke for a lot of useful suggestions and bug
484reports.