Lines Matching +full:trace +full:- +full:buffer +full:- +full:extension
1 .. SPDX-License-Identifier: GPL-2.0
9 to userspace via user-defined 'relay channels'.
11 A 'relay channel' is a kernel->user data relay mechanism implemented
12 as a set of per-cpu kernel buffers ('channel buffers'), each
16 buffer. User space applications mmap() or read() from the relay files
24 buffer data. The relay interface doesn't implement any form of data
25 filtering - this also is left to the kernel client. The purpose is to
30 functions in the relay interface code - please see that for details.
35 Each relay channel has one buffer per CPU; each buffer has one or more
36 sub-buffers. Messages are written to the first sub-buffer until it is
38 the next (if available). Messages are never split across sub-buffers.
40 sub-buffer, while the kernel continues writing to the next.
42 When notified that a sub-buffer is full, the kernel knows how many
44 message couldn't fit into a sub-buffer. Userspace can use this
47 After copying it, userspace can notify the kernel that a sub-buffer
60 read sub-buffers; thus in cases where read(2) is being used to drain
61 the channel buffers, special-purpose communication between kernel and
70 klog and relay-apps example code
76 The relay-apps example tarball, available on the relay sourceforge
77 site, contains a set of self-contained examples, each consisting of a
83 The 'klog debugging functions' patch (klog.patch in the relay-apps
84 tarball) provides a couple of high-level logging functions to the
88 functions allow you to put unconditional 'trace' statements anywhere
94 i.e., without using any of the relay-apps example code or klog, but
98 consumes the read sub-buffers; thus in cases where read(2) is being
99 used to drain the channel buffers, special-purpose communication
101 such as buffer-full conditions would still need to be communicated via
104 klog and the relay-apps examples can be found in the relay-apps
111 access to relay channel buffer data. Here are the file operations
115 open() enables user to open an _existing_ channel buffer.
117 mmap() results in channel buffer being mapped into the caller's
118 memory space. Note that you can't do a partial mmap - you
121 read() read the contents of a channel buffer. The bytes read are
124 in no-overwrite mode (the default), it can be read at any
127 active channel writers, results may be unpredictable -
129 ended before using read() with overwrite mode. Sub-buffer
133 sendfile() transfer data from a channel buffer to an output file
134 descriptor. Sub-buffer padding is automatically removed
138 notified when sub-buffer boundaries are crossed.
140 close() decrements the channel buffer's refcount. When the refcount
142 buffer open, the channel buffer is freed.
148 mount -t debugfs debugfs /sys/kernel/debug
153 clients to create or use channels - it only needs to be
154 mounted when user space applications need access to the buffer
161 Here's a summary of the API the relay interface provides to in-kernel clients:
197 ------------------
199 relay_open() is used to create a channel, along with its per-cpu
200 channel buffers. Each channel buffer will have an associated file
202 read from in user space. The files are named basename0...basenameN-1
209 structure they create, when the channel is closed - again the host
216 create_buf_file() is called once for each per-cpu buffer from
218 to represent the corresponding channel buffer. The callback should
219 return the dentry of the file created to represent the channel buffer.
266 The total size of each per-cpu buffer is calculated by multiplying the
267 number of sub-buffers by the sub-buffer size passed into relay_open().
268 The idea behind sub-buffers is that they're basically an extension of
269 double-buffering to N buffers, and they also allow applications to
270 easily implement random-access-on-buffer-boundary schemes, which can
271 be important for some high-volume applications. The number and size
272 of sub-buffers is completely dependent on the application and even for
276 though, it's safe to assume that having only 1 sub-buffer is a bad
277 idea - you're guaranteed to either overwrite data or lose events
281 as to allow the creation of a single 'global' buffer instead of the
282 default per-cpu set. This can be useful for applications interested
283 mainly in seeing the relative ordering of system-wide events without
285 merging/sorting per-cpu files in a postprocessing step.
287 To have relay_open() create a global buffer, the create_buf_file()
289 non-zero value in addition to creating the file that will be used to
290 represent the single buffer. In the case of a global buffer,
292 normal channel-writing functions, e.g. relay_write(), can still be
293 used - writes from any cpu will transparently end up in the global
294 buffer - but since it is a global buffer, callers should make sure
295 they use the proper locking for such a buffer, either by wrapping
300 user-defined data with a channel, and is immediately available
301 (including in create_buf_file()) via chan->private_data or
302 buf->chan->private_data.
305 ---------------
307 relay channels can be used in either of two modes - 'overwrite' or
308 'no-overwrite'. The mode is entirely determined by the implementation
310 subbuf_start() callback is defined is 'no-overwrite' mode. If the
316 continuously cycle around the buffer and will never fail, but will
318 been consumed. In no-overwrite mode, writes will fail, i.e., data will
319 be lost, if the number of unconsumed sub-buffers equals the total
320 number of sub-buffers in the channel. It should be clear that if
321 there is no consumer or if the consumer can't consume sub-buffers fast
323 whether data is lost from the beginning or the end of a buffer.
326 per-cpu channel buffers, each implemented as a circular buffer
327 subdivided into one or more sub-buffers. Messages are written into
328 the current sub-buffer of the channel's current per-cpu buffer via the
330 the current sub-buffer, because there's no room left for it, the
332 new sub-buffer is about to occur. The client uses this callback to 1)
333 initialize the next sub-buffer if appropriate 2) finalize the previous
334 sub-buffer if appropriate and 3) return a boolean value indicating
335 whether or not to actually move on to the next sub-buffer.
337 To implement 'no-overwrite' mode, the userspace client provides
357 If the current buffer is full, i.e., all sub-buffers remain unconsumed,
358 the callback returns 0 to indicate that the buffer switch should not
360 current set of ready sub-buffers. For the relay_buf_full() function
362 interface when sub-buffers have been consumed via
364 buffer will again invoke the subbuf_start() callback with the same
366 ready sub-buffers will relay_buf_full() return 0, in which case the
367 buffer switch can continue.
386 callback always returns 1, causing the buffer switch to occur
393 implements the simplest possible 'no-overwrite' mode, i.e., it does
396 Header information can be reserved at the beginning of each sub-buffer
400 reserved in each sub-buffer to store the padding count for that
401 sub-buffer. This is filled in for the previous sub-buffer in the
403 sub-buffer is passed into the subbuf_start() callback along with a
404 pointer to the previous sub-buffer, since the padding value isn't
405 known until a sub-buffer is filled. The subbuf_start() callback is
406 also called for the first sub-buffer when the channel is opened, to
408 previous sub-buffer pointer passed into the callback will be NULL, so
410 writing into the previous sub-buffer.
413 --------------------
415 Kernel clients write data into the current cpu's channel buffer using
417 function - it uses local_irqsave() to protect the buffer and should be
422 failed - the assumption is that you wouldn't want to check a return
424 unless the buffer is full and no-overwrite mode is being used, in
428 relay_reserve() is used to reserve a slot in a channel buffer which
430 that need to write directly into a channel buffer without having to
431 stage data in a temporary buffer beforehand. Because the actual write
434 written, either in space reserved in the sub-buffers themselves or as
435 a separate array. See the 'reserve' example in the relay-apps tarball
438 separated from the reserve, relay_reserve() doesn't protect the buffer
439 at all - it's up to the client to provide the appropriate
443 -----------------
448 forces a sub-buffer switch on all the channel buffers, and can be used
449 to finalize and process the last sub-buffers before the channel is
453 ----
455 Some applications may want to keep a channel around and re-use it
457 can be used for this purpose - it resets a channel to its initial
458 state without reallocating channel buffer memory or destroying
463 different purposes. buf_mapped() is called whenever a channel buffer