[PATCH] relayfs: add Documentation on global relay buffers
[linux-2.6.git] / Documentation / filesystems / relayfs.txt
1
2 relayfs - a high-speed data relay filesystem
3 ============================================
4
5 relayfs is a filesystem designed to provide an efficient mechanism for
6 tools and facilities to relay large and potentially sustained streams
7 of data from kernel space to user space.
8
9 The main abstraction of relayfs is the 'channel'.  A channel consists
10 of a set of per-cpu kernel buffers each represented by a file in the
11 relayfs filesystem.  Kernel clients write into a channel using
12 efficient write functions which automatically log to the current cpu's
13 channel buffer.  User space applications mmap() the per-cpu files and
14 retrieve the data as it becomes available.
15
16 The format of the data logged into the channel buffers is completely
17 up to the relayfs client; relayfs does however provide hooks which
18 allow clients to impose some structure on the buffer data.  Nor does
19 relayfs implement any form of data filtering - this also is left to
20 the client.  The purpose is to keep relayfs as simple as possible.
21
22 This document provides an overview of the relayfs API.  The details of
23 the function parameters are documented along with the functions in the
24 filesystem code - please see that for details.
25
26 Semantics
27 =========
28
29 Each relayfs channel has one buffer per CPU, each buffer has one or
30 more sub-buffers. Messages are written to the first sub-buffer until
31 it is too full to contain a new message, in which case it it is
32 written to the next (if available).  Messages are never split across
33 sub-buffers.  At this point, userspace can be notified so it empties
34 the first sub-buffer, while the kernel continues writing to the next.
35
36 When notified that a sub-buffer is full, the kernel knows how many
37 bytes of it are padding i.e. unused.  Userspace can use this knowledge
38 to copy only valid data.
39
40 After copying it, userspace can notify the kernel that a sub-buffer
41 has been consumed.
42
43 relayfs can operate in a mode where it will overwrite data not yet
44 collected by userspace, and not wait for it to consume it.
45
46 relayfs itself does not provide for communication of such data between
47 userspace and kernel, allowing the kernel side to remain simple and not
48 impose a single interface on userspace. It does provide a separate
49 helper though, described below.
50
51 klog, relay-app & librelay
52 ==========================
53
54 relayfs itself is ready to use, but to make things easier, two
55 additional systems are provided.  klog is a simple wrapper to make
56 writing formatted text or raw data to a channel simpler, regardless of
57 whether a channel to write into exists or not, or whether relayfs is
58 compiled into the kernel or is configured as a module.  relay-app is
59 the kernel counterpart of userspace librelay.c, combined these two
60 files provide glue to easily stream data to disk, without having to
61 bother with housekeeping.  klog and relay-app can be used together,
62 with klog providing high-level logging functions to the kernel and
63 relay-app taking care of kernel-user control and disk-logging chores.
64
65 It is possible to use relayfs without relay-app & librelay, but you'll
66 have to implement communication between userspace and kernel, allowing
67 both to convey the state of buffers (full, empty, amount of padding).
68
69 klog, relay-app and librelay can be found in the relay-apps tarball on
70 http://relayfs.sourceforge.net
71
72 The relayfs user space API
73 ==========================
74
75 relayfs implements basic file operations for user space access to
76 relayfs channel buffer data.  Here are the file operations that are
77 available and some comments regarding their behavior:
78
79 open()   enables user to open an _existing_ buffer.
80
81 mmap()   results in channel buffer being mapped into the caller's
82          memory space. Note that you can't do a partial mmap - you must
83          map the entire file, which is NRBUF * SUBBUFSIZE.
84
85 read()   read the contents of a channel buffer.  The bytes read are
86          'consumed' by the reader i.e. they won't be available again
87          to subsequent reads.  If the channel is being used in
88          no-overwrite mode (the default), it can be read at any time
89          even if there's an active kernel writer.  If the channel is
90          being used in overwrite mode and there are active channel
91          writers, results may be unpredictable - users should make
92          sure that all logging to the channel has ended before using
93          read() with overwrite mode.
94
95 poll()   POLLIN/POLLRDNORM/POLLERR supported.  User applications are
96          notified when sub-buffer boundaries are crossed.
97
98 close() decrements the channel buffer's refcount.  When the refcount
99         reaches 0 i.e. when no process or kernel client has the buffer
100         open, the channel buffer is freed.
101
102
103 In order for a user application to make use of relayfs files, the
104 relayfs filesystem must be mounted.  For example,
105
106         mount -t relayfs relayfs /mnt/relay
107
108 NOTE:   relayfs doesn't need to be mounted for kernel clients to create
109         or use channels - it only needs to be mounted when user space
110         applications need access to the buffer data.
111
112
113 The relayfs kernel API
114 ======================
115
116 Here's a summary of the API relayfs provides to in-kernel clients:
117
118
119   channel management functions:
120
121     relay_open(base_filename, parent, subbuf_size, n_subbufs,
122                callbacks)
123     relay_close(chan)
124     relay_flush(chan)
125     relay_reset(chan)
126     relayfs_create_dir(name, parent)
127     relayfs_remove_dir(dentry)
128     relayfs_create_file(name, parent, mode, fops, data)
129     relayfs_remove_file(dentry)
130
131   channel management typically called on instigation of userspace:
132
133     relay_subbufs_consumed(chan, cpu, subbufs_consumed)
134
135   write functions:
136
137     relay_write(chan, data, length)
138     __relay_write(chan, data, length)
139     relay_reserve(chan, length)
140
141   callbacks:
142
143     subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
144     buf_mapped(buf, filp)
145     buf_unmapped(buf, filp)
146     create_buf_file(filename, parent, mode, buf, is_global)
147     remove_buf_file(dentry)
148
149   helper functions:
150
151     relay_buf_full(buf)
152     subbuf_start_reserve(buf, length)
153
154
155 Creating a channel
156 ------------------
157
158 relay_open() is used to create a channel, along with its per-cpu
159 channel buffers.  Each channel buffer will have an associated file
160 created for it in the relayfs filesystem, which can be opened and
161 mmapped from user space if desired.  The files are named
162 basename0...basenameN-1 where N is the number of online cpus, and by
163 default will be created in the root of the filesystem.  If you want a
164 directory structure to contain your relayfs files, you can create it
165 with relayfs_create_dir() and pass the parent directory to
166 relay_open().  Clients are responsible for cleaning up any directory
167 structure they create when the channel is closed - use
168 relayfs_remove_dir() for that.
169
170 The total size of each per-cpu buffer is calculated by multiplying the
171 number of sub-buffers by the sub-buffer size passed into relay_open().
172 The idea behind sub-buffers is that they're basically an extension of
173 double-buffering to N buffers, and they also allow applications to
174 easily implement random-access-on-buffer-boundary schemes, which can
175 be important for some high-volume applications.  The number and size
176 of sub-buffers is completely dependent on the application and even for
177 the same application, different conditions will warrant different
178 values for these parameters at different times.  Typically, the right
179 values to use are best decided after some experimentation; in general,
180 though, it's safe to assume that having only 1 sub-buffer is a bad
181 idea - you're guaranteed to either overwrite data or lose events
182 depending on the channel mode being used.
183
184 Channel 'modes'
185 ---------------
186
187 relayfs channels can be used in either of two modes - 'overwrite' or
188 'no-overwrite'.  The mode is entirely determined by the implementation
189 of the subbuf_start() callback, as described below.  In 'overwrite'
190 mode, also known as 'flight recorder' mode, writes continuously cycle
191 around the buffer and will never fail, but will unconditionally
192 overwrite old data regardless of whether it's actually been consumed.
193 In no-overwrite mode, writes will fail i.e. data will be lost, if the
194 number of unconsumed sub-buffers equals the total number of
195 sub-buffers in the channel.  It should be clear that if there is no
196 consumer or if the consumer can't consume sub-buffers fast enought,
197 data will be lost in either case; the only difference is whether data
198 is lost from the beginning or the end of a buffer.
199
200 As explained above, a relayfs channel is made of up one or more
201 per-cpu channel buffers, each implemented as a circular buffer
202 subdivided into one or more sub-buffers.  Messages are written into
203 the current sub-buffer of the channel's current per-cpu buffer via the
204 write functions described below.  Whenever a message can't fit into
205 the current sub-buffer, because there's no room left for it, the
206 client is notified via the subbuf_start() callback that a switch to a
207 new sub-buffer is about to occur.  The client uses this callback to 1)
208 initialize the next sub-buffer if appropriate 2) finalize the previous
209 sub-buffer if appropriate and 3) return a boolean value indicating
210 whether or not to actually go ahead with the sub-buffer switch.
211
212 To implement 'no-overwrite' mode, the userspace client would provide
213 an implementation of the subbuf_start() callback something like the
214 following:
215
216 static int subbuf_start(struct rchan_buf *buf,
217                         void *subbuf,
218                         void *prev_subbuf,
219                         unsigned int prev_padding)
220 {
221         if (prev_subbuf)
222                 *((unsigned *)prev_subbuf) = prev_padding;
223
224         if (relay_buf_full(buf))
225                 return 0;
226
227         subbuf_start_reserve(buf, sizeof(unsigned int));
228
229         return 1;
230 }
231
232 If the current buffer is full i.e. all sub-buffers remain unconsumed,
233 the callback returns 0 to indicate that the buffer switch should not
234 occur yet i.e. until the consumer has had a chance to read the current
235 set of ready sub-buffers.  For the relay_buf_full() function to make
236 sense, the consumer is reponsible for notifying relayfs when
237 sub-buffers have been consumed via relay_subbufs_consumed().  Any
238 subsequent attempts to write into the buffer will again invoke the
239 subbuf_start() callback with the same parameters; only when the
240 consumer has consumed one or more of the ready sub-buffers will
241 relay_buf_full() return 0, in which case the buffer switch can
242 continue.
243
244 The implementation of the subbuf_start() callback for 'overwrite' mode
245 would be very similar:
246
247 static int subbuf_start(struct rchan_buf *buf,
248                         void *subbuf,
249                         void *prev_subbuf,
250                         unsigned int prev_padding)
251 {
252         if (prev_subbuf)
253                 *((unsigned *)prev_subbuf) = prev_padding;
254
255         subbuf_start_reserve(buf, sizeof(unsigned int));
256
257         return 1;
258 }
259
260 In this case, the relay_buf_full() check is meaningless and the
261 callback always returns 1, causing the buffer switch to occur
262 unconditionally.  It's also meaningless for the client to use the
263 relay_subbufs_consumed() function in this mode, as it's never
264 consulted.
265
266 The default subbuf_start() implementation, used if the client doesn't
267 define any callbacks, or doesn't define the subbuf_start() callback,
268 implements the simplest possible 'no-overwrite' mode i.e. it does
269 nothing but return 0.
270
271 Header information can be reserved at the beginning of each sub-buffer
272 by calling the subbuf_start_reserve() helper function from within the
273 subbuf_start() callback.  This reserved area can be used to store
274 whatever information the client wants.  In the example above, room is
275 reserved in each sub-buffer to store the padding count for that
276 sub-buffer.  This is filled in for the previous sub-buffer in the
277 subbuf_start() implementation; the padding value for the previous
278 sub-buffer is passed into the subbuf_start() callback along with a
279 pointer to the previous sub-buffer, since the padding value isn't
280 known until a sub-buffer is filled.  The subbuf_start() callback is
281 also called for the first sub-buffer when the channel is opened, to
282 give the client a chance to reserve space in it.  In this case the
283 previous sub-buffer pointer passed into the callback will be NULL, so
284 the client should check the value of the prev_subbuf pointer before
285 writing into the previous sub-buffer.
286
287 Writing to a channel
288 --------------------
289
290 kernel clients write data into the current cpu's channel buffer using
291 relay_write() or __relay_write().  relay_write() is the main logging
292 function - it uses local_irqsave() to protect the buffer and should be
293 used if you might be logging from interrupt context.  If you know
294 you'll never be logging from interrupt context, you can use
295 __relay_write(), which only disables preemption.  These functions
296 don't return a value, so you can't determine whether or not they
297 failed - the assumption is that you wouldn't want to check a return
298 value in the fast logging path anyway, and that they'll always succeed
299 unless the buffer is full and no-overwrite mode is being used, in
300 which case you can detect a failed write in the subbuf_start()
301 callback by calling the relay_buf_full() helper function.
302
303 relay_reserve() is used to reserve a slot in a channel buffer which
304 can be written to later.  This would typically be used in applications
305 that need to write directly into a channel buffer without having to
306 stage data in a temporary buffer beforehand.  Because the actual write
307 may not happen immediately after the slot is reserved, applications
308 using relay_reserve() can keep a count of the number of bytes actually
309 written, either in space reserved in the sub-buffers themselves or as
310 a separate array.  See the 'reserve' example in the relay-apps tarball
311 at http://relayfs.sourceforge.net for an example of how this can be
312 done.  Because the write is under control of the client and is
313 separated from the reserve, relay_reserve() doesn't protect the buffer
314 at all - it's up to the client to provide the appropriate
315 synchronization when using relay_reserve().
316
317 Closing a channel
318 -----------------
319
320 The client calls relay_close() when it's finished using the channel.
321 The channel and its associated buffers are destroyed when there are no
322 longer any references to any of the channel buffers.  relay_flush()
323 forces a sub-buffer switch on all the channel buffers, and can be used
324 to finalize and process the last sub-buffers before the channel is
325 closed.
326
327 Creating non-relay files
328 ------------------------
329
330 relay_open() automatically creates files in the relayfs filesystem to
331 represent the per-cpu kernel buffers; it's often useful for
332 applications to be able to create their own files alongside the relay
333 files in the relayfs filesystem as well e.g. 'control' files much like
334 those created in /proc or debugfs for similar purposes, used to
335 communicate control information between the kernel and user sides of a
336 relayfs application.  For this purpose the relayfs_create_file() and
337 relayfs_remove_file() API functions exist.  For relayfs_create_file(),
338 the caller passes in a set of user-defined file operations to be used
339 for the file and an optional void * to a user-specified data item,
340 which will be accessible via inode->u.generic_ip (see the relay-apps
341 tarball for examples).  The file_operations are a required parameter
342 to relayfs_create_file() and thus the semantics of these files are
343 completely defined by the caller.
344
345 See the relay-apps tarball at http://relayfs.sourceforge.net for
346 examples of how these non-relay files are meant to be used.
347
348 Creating relay files in other filesystems
349 -----------------------------------------
350
351 By default of course, relay_open() creates relay files in the relayfs
352 filesystem.  Because relay_file_operations is exported, however, it's
353 also possible to create and use relay files in other pseudo-filesytems
354 such as debugfs.
355
356 For this purpose, two callback functions are provided,
357 create_buf_file() and remove_buf_file().  create_buf_file() is called
358 once for each per-cpu buffer from relay_open() to allow the client to
359 create a file to be used to represent the corresponding buffer; if
360 this callback is not defined, the default implementation will create
361 and return a file in the relayfs filesystem to represent the buffer.
362 The callback should return the dentry of the file created to represent
363 the relay buffer.  Note that the parent directory passed to
364 relay_open() (and passed along to the callback), if specified, must
365 exist in the same filesystem the new relay file is created in.  If
366 create_buf_file() is defined, remove_buf_file() must also be defined;
367 it's responsible for deleting the file(s) created in create_buf_file()
368 and is called during relay_close().
369
370 The create_buf_file() implementation can also be defined in such a way
371 as to allow the creation of a single 'global' buffer instead of the
372 default per-cpu set.  This can be useful for applications interested
373 mainly in seeing the relative ordering of system-wide events without
374 the need to bother with saving explicit timestamps for the purpose of
375 merging/sorting per-cpu files in a postprocessing step.
376
377 To have relay_open() create a global buffer, the create_buf_file()
378 implementation should set the value of the is_global outparam to a
379 non-zero value in addition to creating the file that will be used to
380 represent the single buffer.  In the case of a global buffer,
381 create_buf_file() and remove_buf_file() will be called only once.  The
382 normal channel-writing functions e.g. relay_write() can still be used
383 - writes from any cpu will transparently end up in the global buffer -
384 but since it is a global buffer, callers should make sure they use the
385 proper locking for such a buffer, either by wrapping writes in a
386 spinlock, or by copying a write function from relayfs_fs.h and
387 creating a local version that internally does the proper locking.
388
389 See the 'exported-relayfile' examples in the relay-apps tarball for
390 examples of creating and using relay files in debugfs.
391
392 Misc
393 ----
394
395 Some applications may want to keep a channel around and re-use it
396 rather than open and close a new channel for each use.  relay_reset()
397 can be used for this purpose - it resets a channel to its initial
398 state without reallocating channel buffer memory or destroying
399 existing mappings.  It should however only be called when it's safe to
400 do so i.e. when the channel isn't currently being written to.
401
402 Finally, there are a couple of utility callbacks that can be used for
403 different purposes.  buf_mapped() is called whenever a channel buffer
404 is mmapped from user space and buf_unmapped() is called when it's
405 unmapped.  The client can use this notification to trigger actions
406 within the kernel application, such as enabling/disabling logging to
407 the channel.
408
409
410 Resources
411 =========
412
413 For news, example code, mailing list, etc. see the relayfs homepage:
414
415     http://relayfs.sourceforge.net
416
417
418 Credits
419 =======
420
421 The ideas and specs for relayfs came about as a result of discussions
422 on tracing involving the following:
423
424 Michel Dagenais         <michel.dagenais@polymtl.ca>
425 Richard Moore           <richardj_moore@uk.ibm.com>
426 Bob Wisniewski          <bob@watson.ibm.com>
427 Karim Yaghmour          <karim@opersys.com>
428 Tom Zanussi             <zanussi@us.ibm.com>
429
430 Also thanks to Hubertus Franke for a lot of useful suggestions and bug
431 reports.