^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) relay interface (formerly relayfs)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The relay interface provides a means for kernel applications to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) efficiently log and transfer large quantities of data from the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) to userspace via user-defined 'relay channels'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) A 'relay channel' is a kernel->user data relay mechanism implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) as a set of per-cpu kernel buffers ('channel buffers'), each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) represented as a regular file ('relay file') in user space. Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) clients write into the channel buffers using efficient write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) functions; these automatically log into the current cpu's channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) buffer. User space applications mmap() or read() from the relay files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) and retrieve the data as it becomes available. The relay files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) themselves are files created in a host filesystem, e.g. debugfs, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) are associated with the channel buffers using the API described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) The format of the data logged into the channel buffers is completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) up to the kernel client; the relay interface does however provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) hooks which allow kernel clients to impose some structure on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) buffer data. The relay interface doesn't implement any form of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) filtering - this also is left to the kernel client. The purpose is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) keep things as simple as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) This document provides an overview of the relay interface API. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) details of the function parameters are documented along with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) functions in the relay interface code - please see that for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Semantics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Each relay channel has one buffer per CPU, each buffer has one or more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) sub-buffers. Messages are written to the first sub-buffer until it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) too full to contain a new message, in which case it is written to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) the next (if available). Messages are never split across sub-buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) At this point, userspace can be notified so it empties the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) sub-buffer, while the kernel continues writing to the next.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) When notified that a sub-buffer is full, the kernel knows how many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) bytes of it are padding i.e. unused space occurring because a complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) message couldn't fit into a sub-buffer. Userspace can use this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) knowledge to copy only valid data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) After copying it, userspace can notify the kernel that a sub-buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) has been consumed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) A relay channel can operate in a mode where it will overwrite data not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) yet collected by userspace, and not wait for it to be consumed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) The relay channel itself does not provide for communication of such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) data between userspace and kernel, allowing the kernel side to remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) simple and not impose a single interface on userspace. It does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) provide a set of examples and a separate helper though, described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) The read() interface both removes padding and internally consumes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) read sub-buffers; thus in cases where read(2) is being used to drain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) the channel buffers, special-purpose communication between kernel and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) user isn't necessary for basic operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) One of the major goals of the relay interface is to provide a low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) overhead mechanism for conveying kernel data to userspace. While the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) read() interface is easy to use, it's not as efficient as the mmap()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) approach; the example code attempts to make the tradeoff between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) two approaches as small as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) klog and relay-apps example code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) The relay interface itself is ready to use, but to make things easier,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) a couple simple utility functions and a set of examples are provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The relay-apps example tarball, available on the relay sourceforge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) site, contains a set of self-contained examples, each consisting of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) pair of .c files containing boilerplate code for each of the user and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) kernel sides of a relay application. When combined these two sets of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) boilerplate code provide glue to easily stream data to disk, without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) having to bother with mundane housekeeping chores.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) The 'klog debugging functions' patch (klog.patch in the relay-apps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) tarball) provides a couple of high-level logging functions to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) kernel which allow writing formatted text or raw data to a channel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) regardless of whether a channel to write into exists or not, or even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) whether the relay interface is compiled into the kernel or not. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) functions allow you to put unconditional 'trace' statements anywhere
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) in the kernel or kernel modules; only when there is a 'klog handler'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) registered will data actually be logged (see the klog and kleak
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) examples for details).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) It is of course possible to use the relay interface from scratch,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) i.e. without using any of the relay-apps example code or klog, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) you'll have to implement communication between userspace and kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) allowing both to convey the state of buffers (full, empty, amount of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) padding). The read() interface both removes padding and internally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) consumes the read sub-buffers; thus in cases where read(2) is being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) used to drain the channel buffers, special-purpose communication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) between kernel and user isn't necessary for basic operation. Things
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) such as buffer-full conditions would still need to be communicated via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) some channel though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) klog and the relay-apps examples can be found in the relay-apps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) tarball on http://relayfs.sourceforge.net
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The relay interface user space API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) The relay interface implements basic file operations for user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) access to relay channel buffer data. Here are the file operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) that are available and some comments regarding their behavior:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) =========== ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) open() enables user to open an _existing_ channel buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) mmap() results in channel buffer being mapped into the caller's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) memory space. Note that you can't do a partial mmap - you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) must map the entire file, which is NRBUF * SUBBUFSIZE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) read() read the contents of a channel buffer. The bytes read are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 'consumed' by the reader, i.e. they won't be available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) again to subsequent reads. If the channel is being used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) in no-overwrite mode (the default), it can be read at any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) time even if there's an active kernel writer. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) channel is being used in overwrite mode and there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) active channel writers, results may be unpredictable -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) users should make sure that all logging to the channel has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ended before using read() with overwrite mode. Sub-buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) padding is automatically removed and will not be seen by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) the reader.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) sendfile() transfer data from a channel buffer to an output file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) descriptor. Sub-buffer padding is automatically removed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) and will not be seen by the reader.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) notified when sub-buffer boundaries are crossed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) close() decrements the channel buffer's refcount. When the refcount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) reaches 0, i.e. when no process or kernel client has the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) buffer open, the channel buffer is freed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) =========== ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) In order for a user application to make use of relay files, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) host filesystem must be mounted. For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) mount -t debugfs debugfs /sys/kernel/debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) .. Note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) the host filesystem doesn't need to be mounted for kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) clients to create or use channels - it only needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) mounted when user space applications need access to the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) The relay interface kernel API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) Here's a summary of the API the relay interface provides to in-kernel clients:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) TBD(curr. line MT:/API/)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) channel management functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) relay_open(base_filename, parent, subbuf_size, n_subbufs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) callbacks, private_data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) relay_close(chan)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) relay_flush(chan)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) relay_reset(chan)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) channel management typically called on instigation of userspace::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) relay_subbufs_consumed(chan, cpu, subbufs_consumed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) write functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) relay_write(chan, data, length)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) __relay_write(chan, data, length)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) relay_reserve(chan, length)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) buf_mapped(buf, filp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) buf_unmapped(buf, filp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) create_buf_file(filename, parent, mode, buf, is_global)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) remove_buf_file(dentry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) helper functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) relay_buf_full(buf)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) subbuf_start_reserve(buf, length)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Creating a channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) relay_open() is used to create a channel, along with its per-cpu
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) channel buffers. Each channel buffer will have an associated file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) created for it in the host filesystem, which can be and mmapped or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) read from in user space. The files are named basename0...basenameN-1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) where N is the number of online cpus, and by default will be created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) in the root of the filesystem (if the parent param is NULL). If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) want a directory structure to contain your relay files, you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) create it using the host filesystem's directory creation function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) e.g. debugfs_create_dir(), and pass the parent directory to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) relay_open(). Users are responsible for cleaning up any directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) structure they create, when the channel is closed - again the host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) filesystem's directory removal functions should be used for that,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) e.g. debugfs_remove().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) In order for a channel to be created and the host filesystem's files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) associated with its channel buffers, the user must provide definitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) for two callback functions, create_buf_file() and remove_buf_file().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) create_buf_file() is called once for each per-cpu buffer from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) relay_open() and allows the user to create the file which will be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) to represent the corresponding channel buffer. The callback should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) return the dentry of the file created to represent the channel buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) remove_buf_file() must also be defined; it's responsible for deleting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) the file(s) created in create_buf_file() and is called during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) relay_close().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) Here are some typical definitions for these callbacks, in this case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) using debugfs::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) * create_buf_file() callback. Creates relay file in debugfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) static struct dentry *create_buf_file_handler(const char *filename,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) struct dentry *parent,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) umode_t mode,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) struct rchan_buf *buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) int *is_global)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) return debugfs_create_file(filename, mode, parent, buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) &relay_file_operations);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) * remove_buf_file() callback. Removes relay file from debugfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) static int remove_buf_file_handler(struct dentry *dentry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) debugfs_remove(dentry);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) * relay interface callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) static struct rchan_callbacks relay_callbacks =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) .create_buf_file = create_buf_file_handler,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) .remove_buf_file = remove_buf_file_handler,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) And an example relay_open() invocation using them::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) If the create_buf_file() callback fails, or isn't defined, channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) creation and thus relay_open() will fail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) The total size of each per-cpu buffer is calculated by multiplying the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) number of sub-buffers by the sub-buffer size passed into relay_open().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) The idea behind sub-buffers is that they're basically an extension of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) double-buffering to N buffers, and they also allow applications to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) easily implement random-access-on-buffer-boundary schemes, which can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) be important for some high-volume applications. The number and size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) of sub-buffers is completely dependent on the application and even for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) the same application, different conditions will warrant different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) values for these parameters at different times. Typically, the right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) values to use are best decided after some experimentation; in general,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) though, it's safe to assume that having only 1 sub-buffer is a bad
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) idea - you're guaranteed to either overwrite data or lose events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) depending on the channel mode being used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) The create_buf_file() implementation can also be defined in such a way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) as to allow the creation of a single 'global' buffer instead of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) default per-cpu set. This can be useful for applications interested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) mainly in seeing the relative ordering of system-wide events without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) the need to bother with saving explicit timestamps for the purpose of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) merging/sorting per-cpu files in a postprocessing step.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) To have relay_open() create a global buffer, the create_buf_file()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) implementation should set the value of the is_global outparam to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) non-zero value in addition to creating the file that will be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) represent the single buffer. In the case of a global buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) create_buf_file() and remove_buf_file() will be called only once. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) normal channel-writing functions, e.g. relay_write(), can still be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) used - writes from any cpu will transparently end up in the global
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) buffer - but since it is a global buffer, callers should make sure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) they use the proper locking for such a buffer, either by wrapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) writes in a spinlock, or by copying a write function from relay.h and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) creating a local version that internally does the proper locking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) The private_data passed into relay_open() allows clients to associate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) user-defined data with a channel, and is immediately available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) (including in create_buf_file()) via chan->private_data or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) buf->chan->private_data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Buffer-only channels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) These channels have no files associated and can be created with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) relay_open(NULL, NULL, ...). Such channels are useful in scenarios such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) as when doing early tracing in the kernel, before the VFS is up. In these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) cases, one may open a buffer-only channel and then call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) relay_late_setup_files() when the kernel is ready to handle files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) to expose the buffered data to the userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) Channel 'modes'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) relay channels can be used in either of two modes - 'overwrite' or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 'no-overwrite'. The mode is entirely determined by the implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) of the subbuf_start() callback, as described below. The default if no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) subbuf_start() callback is defined is 'no-overwrite' mode. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) default mode suits your needs, and you plan to use the read()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) interface to retrieve channel data, you can ignore the details of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) section, as it pertains mainly to mmap() implementations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) In 'overwrite' mode, also known as 'flight recorder' mode, writes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) continuously cycle around the buffer and will never fail, but will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) unconditionally overwrite old data regardless of whether it's actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) been consumed. In no-overwrite mode, writes will fail, i.e. data will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) be lost, if the number of unconsumed sub-buffers equals the total
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) number of sub-buffers in the channel. It should be clear that if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) there is no consumer or if the consumer can't consume sub-buffers fast
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) enough, data will be lost in either case; the only difference is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) whether data is lost from the beginning or the end of a buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) As explained above, a relay channel is made of up one or more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) per-cpu channel buffers, each implemented as a circular buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) subdivided into one or more sub-buffers. Messages are written into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) the current sub-buffer of the channel's current per-cpu buffer via the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) write functions described below. Whenever a message can't fit into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) the current sub-buffer, because there's no room left for it, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) client is notified via the subbuf_start() callback that a switch to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) new sub-buffer is about to occur. The client uses this callback to 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) initialize the next sub-buffer if appropriate 2) finalize the previous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) sub-buffer if appropriate and 3) return a boolean value indicating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) whether or not to actually move on to the next sub-buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) To implement 'no-overwrite' mode, the userspace client would provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) an implementation of the subbuf_start() callback something like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) static int subbuf_start(struct rchan_buf *buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) void *subbuf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) void *prev_subbuf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) unsigned int prev_padding)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) if (prev_subbuf)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) *((unsigned *)prev_subbuf) = prev_padding;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) if (relay_buf_full(buf))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) subbuf_start_reserve(buf, sizeof(unsigned int));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) If the current buffer is full, i.e. all sub-buffers remain unconsumed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) the callback returns 0 to indicate that the buffer switch should not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) occur yet, i.e. until the consumer has had a chance to read the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) current set of ready sub-buffers. For the relay_buf_full() function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) to make sense, the consumer is responsible for notifying the relay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) interface when sub-buffers have been consumed via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) relay_subbufs_consumed(). Any subsequent attempts to write into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) buffer will again invoke the subbuf_start() callback with the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) parameters; only when the consumer has consumed one or more of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) ready sub-buffers will relay_buf_full() return 0, in which case the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) buffer switch can continue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) The implementation of the subbuf_start() callback for 'overwrite' mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) would be very similar::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) static int subbuf_start(struct rchan_buf *buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) void *subbuf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) void *prev_subbuf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) size_t prev_padding)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) if (prev_subbuf)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) *((unsigned *)prev_subbuf) = prev_padding;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) subbuf_start_reserve(buf, sizeof(unsigned int));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) In this case, the relay_buf_full() check is meaningless and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) callback always returns 1, causing the buffer switch to occur
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) unconditionally. It's also meaningless for the client to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) relay_subbufs_consumed() function in this mode, as it's never
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) consulted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) The default subbuf_start() implementation, used if the client doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) define any callbacks, or doesn't define the subbuf_start() callback,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) implements the simplest possible 'no-overwrite' mode, i.e. it does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) nothing but return 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) Header information can be reserved at the beginning of each sub-buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) by calling the subbuf_start_reserve() helper function from within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) subbuf_start() callback. This reserved area can be used to store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) whatever information the client wants. In the example above, room is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) reserved in each sub-buffer to store the padding count for that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) sub-buffer. This is filled in for the previous sub-buffer in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) subbuf_start() implementation; the padding value for the previous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) sub-buffer is passed into the subbuf_start() callback along with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) pointer to the previous sub-buffer, since the padding value isn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) known until a sub-buffer is filled. The subbuf_start() callback is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) also called for the first sub-buffer when the channel is opened, to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) give the client a chance to reserve space in it. In this case the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) previous sub-buffer pointer passed into the callback will be NULL, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) the client should check the value of the prev_subbuf pointer before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) writing into the previous sub-buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) Writing to a channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) Kernel clients write data into the current cpu's channel buffer using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) relay_write() or __relay_write(). relay_write() is the main logging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) function - it uses local_irqsave() to protect the buffer and should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) used if you might be logging from interrupt context. If you know
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) you'll never be logging from interrupt context, you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) __relay_write(), which only disables preemption. These functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) don't return a value, so you can't determine whether or not they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) failed - the assumption is that you wouldn't want to check a return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) value in the fast logging path anyway, and that they'll always succeed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) unless the buffer is full and no-overwrite mode is being used, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) which case you can detect a failed write in the subbuf_start()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) callback by calling the relay_buf_full() helper function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) relay_reserve() is used to reserve a slot in a channel buffer which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) can be written to later. This would typically be used in applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) that need to write directly into a channel buffer without having to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) stage data in a temporary buffer beforehand. Because the actual write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) may not happen immediately after the slot is reserved, applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) using relay_reserve() can keep a count of the number of bytes actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) written, either in space reserved in the sub-buffers themselves or as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) a separate array. See the 'reserve' example in the relay-apps tarball
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) at http://relayfs.sourceforge.net for an example of how this can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) done. Because the write is under control of the client and is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) separated from the reserve, relay_reserve() doesn't protect the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) at all - it's up to the client to provide the appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) synchronization when using relay_reserve().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) Closing a channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) The client calls relay_close() when it's finished using the channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) The channel and its associated buffers are destroyed when there are no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) longer any references to any of the channel buffers. relay_flush()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) forces a sub-buffer switch on all the channel buffers, and can be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) to finalize and process the last sub-buffers before the channel is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Misc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) Some applications may want to keep a channel around and re-use it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) rather than open and close a new channel for each use. relay_reset()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) can be used for this purpose - it resets a channel to its initial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) state without reallocating channel buffer memory or destroying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) existing mappings. It should however only be called when it's safe to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) do so, i.e. when the channel isn't currently being written to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) Finally, there are a couple of utility callbacks that can be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) different purposes. buf_mapped() is called whenever a channel buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) is mmapped from user space and buf_unmapped() is called when it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) unmapped. The client can use this notification to trigger actions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) within the kernel application, such as enabling/disabling logging to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) the channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) Resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) For news, example code, mailing list, etc. see the relay interface homepage:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) http://relayfs.sourceforge.net
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) Credits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) The ideas and specs for the relay interface came about as a result of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) discussions on tracing involving the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) Michel Dagenais <michel.dagenais@polymtl.ca>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) Richard Moore <richardj_moore@uk.ibm.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) Bob Wisniewski <bob@watson.ibm.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) Karim Yaghmour <karim@opersys.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) Tom Zanussi <zanussi@us.ibm.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) Also thanks to Hubertus Franke for a lot of useful suggestions and bug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) reports.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags