Root/
1 | relay interface (formerly relayfs) |
2 | ================================== |
3 | |
4 | The relay interface provides a means for kernel applications to |
5 | efficiently log and transfer large quantities of data from the kernel |
6 | to userspace via user-defined 'relay channels'. |
7 | |
8 | A 'relay channel' is a kernel->user data relay mechanism implemented |
9 | as a set of per-cpu kernel buffers ('channel buffers'), each |
10 | represented as a regular file ('relay file') in user space. 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 |
15 | themselves are files created in a host filesystem, e.g. debugfs, and |
16 | are associated with the channel buffers using the API described below. |
17 | |
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 |
21 | buffer data. The relay interface doesn't implement any form of data |
22 | filtering - this also is left to the kernel client. The purpose is to |
23 | keep things as simple as possible. |
24 | |
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. |
28 | |
29 | Semantics |
30 | ========= |
31 | |
32 | Each relay channel has one buffer per CPU, each buffer has one or more |
33 | sub-buffers. Messages are written to the first sub-buffer until it is |
34 | too full to contain a new message, in which case it it is written to |
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. |
38 | |
39 | When notified that a sub-buffer is full, the kernel knows how many |
40 | bytes of it are padding i.e. unused space occurring because a complete |
41 | message couldn't fit into a sub-buffer. Userspace can use this |
42 | knowledge to copy only valid data. |
43 | |
44 | After copying it, userspace can notify the kernel that a sub-buffer |
45 | has been consumed. |
46 | |
47 | A relay channel can operate in a mode where it will overwrite data not |
48 | yet collected by userspace, and not wait for it to be consumed. |
49 | |
50 | The relay channel itself does not provide for communication of such |
51 | data between userspace and kernel, allowing the kernel side to remain |
52 | simple and not impose a single interface on userspace. It does |
53 | provide a set of examples and a separate helper though, described |
54 | below. |
55 | |
56 | The read() interface both removes padding and internally consumes the |
57 | read sub-buffers; thus in cases where read(2) is being used to drain |
58 | the channel buffers, special-purpose communication between kernel and |
59 | user isn't necessary for basic operation. |
60 | |
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 |
65 | two approaches as small as possible. |
66 | |
67 | klog and relay-apps example code |
68 | ================================ |
69 | |
70 | The relay interface itself is ready to use, but to make things easier, |
71 | a couple simple utility functions and a set of examples are provided. |
72 | |
73 | The relay-apps example tarball, available on the relay sourceforge |
74 | site, contains a set of self-contained examples, each consisting of a |
75 | pair of .c files containing boilerplate code for each of the user and |
76 | kernel sides of a relay application. When combined these two sets of |
77 | boilerplate code provide glue to easily stream data to disk, without |
78 | having to bother with mundane housekeeping chores. |
79 | |
80 | The 'klog debugging functions' patch (klog.patch in the relay-apps |
81 | tarball) provides a couple of high-level logging functions to the |
82 | kernel which allow writing formatted text or raw data to a channel, |
83 | regardless of whether a channel to write into exists or not, or even |
84 | whether the relay interface is compiled into the kernel or not. These |
85 | functions allow you to put unconditional 'trace' statements anywhere |
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 |
88 | examples for details). |
89 | |
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 |
92 | you'll have to implement communication between userspace and kernel, |
93 | allowing both to convey the state of buffers (full, empty, amount of |
94 | padding). The read() interface both removes padding and internally |
95 | consumes the read sub-buffers; thus in cases where read(2) is being |
96 | used to drain the channel buffers, special-purpose communication |
97 | between kernel and user isn't necessary for basic operation. Things |
98 | such as buffer-full conditions would still need to be communicated via |
99 | some channel though. |
100 | |
101 | klog and the relay-apps examples can be found in the relay-apps |
102 | tarball on http://relayfs.sourceforge.net |
103 | |
104 | The relay interface user space API |
105 | ================================== |
106 | |
107 | The relay interface implements basic file operations for user space |
108 | access to relay channel buffer data. Here are the file operations |
109 | that are available and some comments regarding their behavior: |
110 | |
111 | open() enables user to open an _existing_ channel buffer. |
112 | |
113 | mmap() 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 | |
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 |
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 | |
129 | sendfile() 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 | |
133 | poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are |
134 | notified when sub-buffer boundaries are crossed. |
135 | |
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. |
139 | |
140 | In order for a user application to make use of relay files, the |
141 | host filesystem must be mounted. For example, |
142 | |
143 | mount -t debugfs debugfs /sys/kernel/debug |
144 | |
145 | NOTE: 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 | |
151 | The relay interface kernel API |
152 | ============================== |
153 | |
154 | Here's a summary of the API the relay interface provides to in-kernel clients: |
155 | |
156 | TBD(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 | |
189 | Creating a channel |
190 | ------------------ |
191 | |
192 | relay_open() is used to create a channel, along with its per-cpu |
193 | channel buffers. Each channel buffer will have an associated file |
194 | created for it in the host filesystem, which can be and mmapped or |
195 | read from in user space. The files are named basename0...basenameN-1 |
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 |
198 | want a directory structure to contain your relay files, you should |
199 | create it using the host filesystem's directory creation function, |
200 | e.g. debugfs_create_dir(), and pass the parent directory to |
201 | relay_open(). Users are responsible for cleaning up any directory |
202 | structure they create, when the channel is closed - again the host |
203 | filesystem's directory removal functions should be used for that, |
204 | e.g. debugfs_remove(). |
205 | |
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 |
208 | for two callback functions, create_buf_file() and remove_buf_file(). |
209 | create_buf_file() is called once for each per-cpu buffer from |
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. |
213 | remove_buf_file() must also be defined; it's responsible for deleting |
214 | the file(s) created in create_buf_file() and is called during |
215 | relay_close(). |
216 | |
217 | Here are some typical definitions for these callbacks, in this case |
218 | using debugfs: |
219 | |
220 | /* |
221 | * create_buf_file() callback. Creates relay file in debugfs. |
222 | */ |
223 | static 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 | */ |
236 | static 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 | */ |
246 | static struct rchan_callbacks relay_callbacks = |
247 | { |
248 | .create_buf_file = create_buf_file_handler, |
249 | .remove_buf_file = remove_buf_file_handler, |
250 | }; |
251 | |
252 | And an example relay_open() invocation using them: |
253 | |
254 | chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL); |
255 | |
256 | If the create_buf_file() callback fails, or isn't defined, channel |
257 | creation and thus relay_open() will fail. |
258 | |
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(). |
261 | The idea behind sub-buffers is that they're basically an extension of |
262 | double-buffering to N buffers, and they also allow applications to |
263 | easily implement random-access-on-buffer-boundary schemes, which can |
264 | be important for some high-volume applications. The number and size |
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 |
268 | values to use are best decided after some experimentation; in general, |
269 | though, it's safe to assume that having only 1 sub-buffer is a bad |
270 | idea - you're guaranteed to either overwrite data or lose events |
271 | depending on the channel mode being used. |
272 | |
273 | The create_buf_file() implementation can also be defined in such a way |
274 | as to allow the creation of a single 'global' buffer instead of the |
275 | default per-cpu set. This can be useful for applications interested |
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 |
278 | merging/sorting per-cpu files in a postprocessing step. |
279 | |
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, |
284 | create_buf_file() and remove_buf_file() will be called only once. The |
285 | normal channel-writing functions, e.g. relay_write(), can still be |
286 | used - writes from any cpu will transparently end up in the global |
287 | buffer - but since it is a global buffer, callers should make sure |
288 | they use the proper locking for such a buffer, either by wrapping |
289 | writes in a spinlock, or by copying a write function from relay.h and |
290 | creating a local version that internally does the proper locking. |
291 | |
292 | The private_data passed into relay_open() allows clients to associate |
293 | user-defined data with a channel, and is immediately available |
294 | (including in create_buf_file()) via chan->private_data or |
295 | buf->chan->private_data. |
296 | |
297 | Buffer-only channels |
298 | -------------------- |
299 | |
300 | These channels have no files associated and can be created with |
301 | relay_open(NULL, NULL, ...). Such channels are useful in scenarios such |
302 | as when doing early tracing in the kernel, before the VFS is up. In these |
303 | cases, one may open a buffer-only channel and then call |
304 | relay_late_setup_files() when the kernel is ready to handle files, |
305 | to expose the buffered data to the userspace. |
306 | |
307 | Channel 'modes' |
308 | --------------- |
309 | |
310 | relay channels can be used in either of two modes - 'overwrite' or |
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 |
316 | section, as it pertains mainly to mmap() implementations. |
317 | |
318 | In 'overwrite' mode, also known as 'flight recorder' mode, writes |
319 | continuously cycle around the buffer and will never fail, but will |
320 | unconditionally overwrite old data regardless of whether it's actually |
321 | been consumed. In no-overwrite mode, writes will fail, i.e. data 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. |
327 | |
328 | As explained above, a relay channel is made of up one or more |
329 | per-cpu channel buffers, each implemented as a circular buffer |
330 | subdivided into one or more sub-buffers. Messages are written into |
331 | the current sub-buffer of the channel's current per-cpu buffer via the |
332 | write functions described below. Whenever a message can't fit into |
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 |
335 | new sub-buffer is about to occur. The client uses this callback to 1) |
336 | initialize the next sub-buffer if appropriate 2) finalize the previous |
337 | sub-buffer if appropriate and 3) return a boolean value indicating |
338 | whether or not to actually move on to the next sub-buffer. |
339 | |
340 | To implement 'no-overwrite' mode, the userspace client would provide |
341 | an implementation of the subbuf_start() callback something like the |
342 | following: |
343 | |
344 | static 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 | |
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 |
365 | interface when sub-buffers have been consumed via |
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 |
370 | buffer switch can continue. |
371 | |
372 | The implementation of the subbuf_start() callback for 'overwrite' mode |
373 | would be very similar: |
374 | |
375 | static 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 | |
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 |
391 | relay_subbufs_consumed() function in this mode, as it's never |
392 | consulted. |
393 | |
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 |
397 | nothing but return 0. |
398 | |
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 |
401 | subbuf_start() callback. This reserved area can be used to store |
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 |
408 | known until a sub-buffer is filled. The subbuf_start() callback is |
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. |
414 | |
415 | Writing to a channel |
416 | -------------------- |
417 | |
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 |
421 | used if you might be logging from interrupt context. If you know |
422 | you'll never be logging from interrupt context, you can use |
423 | __relay_write(), which only disables preemption. These functions |
424 | don't return a value, so you can't determine whether or not they |
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. |
430 | |
431 | relay_reserve() is used to reserve a slot in a channel buffer which |
432 | can be written to later. This would typically be used in applications |
433 | that need to write directly into a channel buffer without having to |
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 |
439 | at http://relayfs.sourceforge.net for an example of how this can be |
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 |
443 | synchronization when using relay_reserve(). |
444 | |
445 | Closing a channel |
446 | ----------------- |
447 | |
448 | The client calls relay_close() when it's finished using the channel. |
449 | The channel and its associated buffers are destroyed when there are no |
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 |
453 | closed. |
454 | |
455 | Misc |
456 | ---- |
457 | |
458 | Some applications may want to keep a channel around and re-use it |
459 | rather than open and close a new channel for each use. relay_reset() |
460 | can be used for this purpose - it resets a channel to its initial |
461 | state without reallocating channel buffer memory or destroying |
462 | existing mappings. It should however only be called when it's safe to |
463 | do so, i.e. when the channel isn't currently being written to. |
464 | |
465 | Finally, there are a couple of utility callbacks that can be used for |
466 | different purposes. buf_mapped() is called whenever a channel buffer |
467 | is mmapped from user space and buf_unmapped() is called when it's |
468 | unmapped. The client can use this notification to trigger actions |
469 | within the kernel application, such as enabling/disabling logging to |
470 | the channel. |
471 | |
472 | |
473 | Resources |
474 | ========= |
475 | |
476 | For news, example code, mailing list, etc. see the relay interface homepage: |
477 | |
478 | http://relayfs.sourceforge.net |
479 | |
480 | |
481 | Credits |
482 | ======= |
483 | |
484 | The ideas and specs for the relay interface came about as a result of |
485 | discussions on tracing involving the following: |
486 | |
487 | Michel Dagenais <michel.dagenais@polymtl.ca> |
488 | Richard Moore <richardj_moore@uk.ibm.com> |
489 | Bob Wisniewski <bob@watson.ibm.com> |
490 | Karim Yaghmour <karim@opersys.com> |
491 | Tom Zanussi <zanussi@us.ibm.com> |
492 | |
493 | Also thanks to Hubertus Franke for a lot of useful suggestions and bug |
494 | reports. |
495 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9