sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget%/translations/zh_CN/filesystems/relaymodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/zh_TW/filesystems/relaymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/it_IT/filesystems/relaymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ja_JP/filesystems/relaymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ko_KR/filesystems/relaymodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/sp_SP/filesystems/relaymodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh?/var/lib/git/docbuild/linux/Documentation/filesystems/relay.rsthKubhsection)}(hhh](htitle)}(h"relay interface (formerly relayfs)h]h"relay interface (formerly relayfs)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThe relay interface provides a means for kernel applications to efficiently log and transfer large quantities of data from the kernel to userspace via user-defined 'relay channels'.h]hThe relay interface provides a means for kernel applications to efficiently log and transfer large quantities of data from the kernel to userspace via user-defined ‘relay channels’.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXWA 'relay channel' is a kernel->user data relay mechanism implemented as a set of per-cpu kernel buffers ('channel buffers'), each represented as a regular file ('relay file') in user space. Kernel clients write into the channel buffers using efficient write functions; these automatically log into the current cpu's channel buffer. User space applications mmap() or read() from the relay files and retrieve the data as it becomes available. The relay files themselves are files created in a host filesystem, e.g. debugfs, and are associated with the channel buffers using the API described below.h]hXeA ‘relay channel’ is a kernel->user data relay mechanism implemented as a set of per-cpu kernel buffers (‘channel buffers’), each represented as a regular file (‘relay file’) in user space. Kernel clients write into the channel buffers using efficient write functions; these automatically log into the current cpu’s channel buffer. User space applications mmap() or read() from the relay files and retrieve the data as it becomes available. The relay files themselves are files created in a host filesystem, e.g. debugfs, and are associated with the channel buffers using the API described below.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hXvThe format of the data logged into the channel buffers is completely up to the kernel client; the relay interface does however provide hooks which allow kernel clients to impose some structure on the buffer data. The relay interface doesn't implement any form of data filtering - this also is left to the kernel client. The purpose is to keep things as simple as possible.h]hXxThe format of the data logged into the channel buffers is completely up to the kernel client; the relay interface does however provide hooks which allow kernel clients to impose some structure on the buffer data. The relay interface doesn’t implement any form of data filtering - this also is left to the kernel client. The purpose is to keep things as simple as possible.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThis document provides an overview of the relay interface API. The details of the function parameters are documented along with the functions in the relay interface code - please see that for details.h]hThis document provides an overview of the relay interface API. The details of the function parameters are documented along with the functions in the relay interface code - please see that for details.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h Semanticsh]h Semantics}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK!ubh)}(hXEach relay channel has one buffer per CPU; each buffer has one or more sub-buffers. Messages are written to the first sub-buffer until it is too full to contain a new message, in which case it is written to the next (if available). Messages are never split across sub-buffers. At this point, userspace can be notified so it empties the first sub-buffer, while the kernel continues writing to the next.h]hXEach relay channel has one buffer per CPU; each buffer has one or more sub-buffers. Messages are written to the first sub-buffer until it is too full to contain a new message, in which case it is written to the next (if available). Messages are never split across sub-buffers. At this point, userspace can be notified so it empties the first sub-buffer, while the kernel continues writing to the next.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjhhubh)}(hWhen notified that a sub-buffer is full, the kernel knows how many bytes of it are padding, i.e., unused space occurring because a complete message couldn't fit into a sub-buffer. Userspace can use this knowledge to copy only valid data.h]hWhen notified that a sub-buffer is full, the kernel knows how many bytes of it are padding, i.e., unused space occurring because a complete message couldn’t fit into a sub-buffer. Userspace can use this knowledge to copy only valid data.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubh)}(hVAfter copying it, userspace can notify the kernel that a sub-buffer has been consumed.h]hVAfter copying it, userspace can notify the kernel that a sub-buffer has been consumed.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjhhubh)}(hA relay channel can operate in a mode where it will overwrite data not yet collected by userspace, and not wait for it to be consumed.h]hA relay channel can operate in a mode where it will overwrite data not yet collected by userspace, and not wait for it to be consumed.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjhhubh)}(hXThe relay channel itself does not provide for communication of such data between userspace and kernel, allowing the kernel side to remain simple and not impose a single interface on userspace. It does provide a set of examples and a separate helper though, described below.h]hXThe relay channel itself does not provide for communication of such data between userspace and kernel, allowing the kernel side to remain simple and not impose a single interface on userspace. It does provide a set of examples and a separate helper though, described below.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjhhubh)}(hThe read() interface both removes padding and internally consumes the read sub-buffers; thus in cases where read(2) is being used to drain the channel buffers, special-purpose communication between kernel and user isn't necessary for basic operation.h]hThe read() interface both removes padding and internally consumes the read sub-buffers; thus in cases where read(2) is being used to drain the channel buffers, special-purpose communication between kernel and user isn’t necessary for basic operation.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjhhubh)}(hX6One of the major goals of the relay interface is to provide a low overhead mechanism for conveying kernel data to userspace. While the read() interface is easy to use, it's not as efficient as the mmap() approach; the example code attempts to make the tradeoff between the two approaches as small as possible.h]hX8One of the major goals of the relay interface is to provide a low overhead mechanism for conveying kernel data to userspace. While the read() interface is easy to use, it’s not as efficient as the mmap() approach; the example code attempts to make the tradeoff between the two approaches as small as possible.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjhhubeh}(h] semanticsah ]h"] semanticsah$]h&]uh1hhhhhhhhK!ubh)}(hhh](h)}(h klog and relay-apps example codeh]h klog and relay-apps example code}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj~hhhhhKGubh)}(hThe relay interface itself is ready to use, but to make things easier, a couple of simple utility functions and a set of examples are provided.h]hThe relay interface itself is ready to use, but to make things easier, a couple of simple utility functions and a set of examples are provided.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhj~hhubh)}(hXThe relay-apps example tarball, available on the relay sourceforge site, contains a set of self-contained examples, each consisting of a pair of .c files containing boilerplate code for each of the user and kernel sides of a relay application. When combined these two sets of boilerplate code provide glue to easily stream data to disk, without having to bother with mundane housekeeping chores.h]hXThe relay-apps example tarball, available on the relay sourceforge site, contains a set of self-contained examples, each consisting of a pair of .c files containing boilerplate code for each of the user and kernel sides of a relay application. When combined these two sets of boilerplate code provide glue to easily stream data to disk, without having to bother with mundane housekeeping chores.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhj~hhubh)}(hX5The 'klog debugging functions' patch (klog.patch in the relay-apps tarball) provides a couple of high-level logging functions to the kernel which allow writing formatted text or raw data to a channel, regardless of whether a channel to write into exists or not, or even whether the relay interface is compiled into the kernel or not. These functions allow you to put unconditional 'trace' statements anywhere in the kernel or kernel modules; only when there is a 'klog handler' registered will data actually be logged (see the klog and kleak examples for details).h]hXAThe ‘klog debugging functions’ patch (klog.patch in the relay-apps tarball) provides a couple of high-level logging functions to the kernel which allow writing formatted text or raw data to a channel, regardless of whether a channel to write into exists or not, or even whether the relay interface is compiled into the kernel or not. These functions allow you to put unconditional ‘trace’ statements anywhere in the kernel or kernel modules; only when there is a ‘klog handler’ registered will data actually be logged (see the klog and kleak examples for details).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShj~hhubh)}(hXyIt is of course possible to use the relay interface from scratch, i.e., without using any of the relay-apps example code or klog, but you'll have to implement communication between userspace and kernel, allowing both to convey the state of buffers (full, empty, amount of padding). The read() interface both removes padding and internally consumes the read sub-buffers; thus in cases where read(2) is being used to drain the channel buffers, special-purpose communication between kernel and user isn't necessary for basic operation. Things such as buffer-full conditions would still need to be communicated via some channel though.h]hX}It is of course possible to use the relay interface from scratch, i.e., without using any of the relay-apps example code or klog, but you’ll have to implement communication between userspace and kernel, allowing both to convey the state of buffers (full, empty, amount of padding). The read() interface both removes padding and internally consumes the read sub-buffers; thus in cases where read(2) is being used to drain the channel buffers, special-purpose communication between kernel and user isn’t necessary for basic operation. Things such as buffer-full conditions would still need to be communicated via some channel though.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hj~hhubh)}(hiklog and the relay-apps examples can be found in the relay-apps tarball on http://relayfs.sourceforge.neth](hKklog and the relay-apps examples can be found in the relay-apps tarball on }(hjhhhNhNubh reference)}(hhttp://relayfs.sourceforge.neth]hhttp://relayfs.sourceforge.net}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhKhhj~hhubeh}(h] klog-and-relay-apps-example-codeah ]h"] klog and relay-apps example codeah$]h&]uh1hhhhhhhhKGubh)}(hhh](h)}(h"The relay interface user space APIh]h"The relay interface user space API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKlubh)}(hThe relay interface implements basic file operations for user space access to relay channel buffer data. Here are the file operations that are available and some comments regarding their behavior:h]hThe relay interface implements basic file operations for user space access to relay channel buffer data. Here are the file operations that are available and some comments regarding their behavior:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjhhubhtable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKprivate_data or buf->chan->private_data.h]hThe private_data passed into relay_open() allows clients to associate user-defined data with a channel, and is immediately available (including in create_buf_file()) via chan->private_data or buf->chan->private_data.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM+hjhhubeh}(h]creating-a-channelah ]h"]creating a channelah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hChannel 'modes'h]hChannel ‘modes’}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjchhhhhM1ubh)}(hXrelay channels can be used in either of two modes - 'overwrite' or 'no-overwrite'. The mode is entirely determined by the implementation of the subbuf_start() callback, as described below. The default if no subbuf_start() callback is defined is 'no-overwrite' mode. If the default mode suits your needs, and you plan to use the read() interface to retrieve channel data, you can ignore the details of this section, as it pertains mainly to mmap() implementations.h]hXrelay channels can be used in either of two modes - ‘overwrite’ or ‘no-overwrite’. The mode is entirely determined by the implementation of the subbuf_start() callback, as described below. The default if no subbuf_start() callback is defined is ‘no-overwrite’ mode. If the default mode suits your needs, and you plan to use the read() interface to retrieve channel data, you can ignore the details of this section, as it pertains mainly to mmap() implementations.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hjchhubh)}(hX_In 'overwrite' mode, also known as 'flight recorder' mode, writes continuously cycle around the buffer and will never fail, but will unconditionally overwrite old data regardless of whether it's actually been consumed. In no-overwrite mode, writes will fail, i.e., data will be lost, if the number of unconsumed sub-buffers equals the total number of sub-buffers in the channel. It should be clear that if there is no consumer or if the consumer can't consume sub-buffers fast enough, data will be lost in either case; the only difference is whether data is lost from the beginning or the end of a buffer.h]hXkIn ‘overwrite’ mode, also known as ‘flight recorder’ mode, writes continuously cycle around the buffer and will never fail, but will unconditionally overwrite old data regardless of whether it’s actually been consumed. In no-overwrite mode, writes will fail, i.e., data will be lost, if the number of unconsumed sub-buffers equals the total number of sub-buffers in the channel. It should be clear that if there is no consumer or if the consumer can’t consume sub-buffers fast enough, data will be lost in either case; the only difference is whether data is lost from the beginning or the end of a buffer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM;hjchhubh)}(hXAs explained above, a relay channel is made of up one or more per-cpu channel buffers, each implemented as a circular buffer subdivided into one or more sub-buffers. Messages are written into the current sub-buffer of the channel's current per-cpu buffer via the write functions described below. Whenever a message can't fit into the current sub-buffer, because there's no room left for it, the client is notified via the subbuf_start() callback that a switch to a new sub-buffer is about to occur. The client uses this callback to 1) initialize the next sub-buffer if appropriate 2) finalize the previous sub-buffer if appropriate and 3) return a boolean value indicating whether or not to actually move on to the next sub-buffer.h]hXAs explained above, a relay channel is made of up one or more per-cpu channel buffers, each implemented as a circular buffer subdivided into one or more sub-buffers. Messages are written into the current sub-buffer of the channel’s current per-cpu buffer via the write functions described below. Whenever a message can’t fit into the current sub-buffer, because there’s no room left for it, the client is notified via the subbuf_start() callback that a switch to a new sub-buffer is about to occur. The client uses this callback to 1) initialize the next sub-buffer if appropriate 2) finalize the previous sub-buffer if appropriate and 3) return a boolean value indicating whether or not to actually move on to the next sub-buffer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhjchhubh)}(hTo implement 'no-overwrite' mode, the userspace client provides an implementation of the subbuf_start() callback something like the following::h]hTo implement ‘no-overwrite’ mode, the userspace client provides an implementation of the subbuf_start() callback something like the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMQhjchhubj)}(hXstatic int subbuf_start(struct rchan_buf *buf, void *subbuf, void *prev_subbuf, unsigned int prev_padding) { if (prev_subbuf) *((unsigned *)prev_subbuf) = prev_padding; if (relay_buf_full(buf)) return 0; subbuf_start_reserve(buf, sizeof(unsigned int)); return 1; }h]hXstatic int subbuf_start(struct rchan_buf *buf, void *subbuf, void *prev_subbuf, unsigned int prev_padding) { if (prev_subbuf) *((unsigned *)prev_subbuf) = prev_padding; if (relay_buf_full(buf)) return 0; subbuf_start_reserve(buf, sizeof(unsigned int)); return 1; }}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMUhjchhubh)}(hXIf the current buffer is full, i.e., all sub-buffers remain unconsumed, the callback returns 0 to indicate that the buffer switch should not occur yet, i.e., until the consumer has had a chance to read the current set of ready sub-buffers. For the relay_buf_full() function to make sense, the consumer is responsible for notifying the relay interface when sub-buffers have been consumed via relay_subbufs_consumed(). Any subsequent attempts to write into the buffer will again invoke the subbuf_start() callback with the same parameters; only when the consumer has consumed one or more of the ready sub-buffers will relay_buf_full() return 0, in which case the buffer switch can continue.h]hXIf the current buffer is full, i.e., all sub-buffers remain unconsumed, the callback returns 0 to indicate that the buffer switch should not occur yet, i.e., until the consumer has had a chance to read the current set of ready sub-buffers. For the relay_buf_full() function to make sense, the consumer is responsible for notifying the relay interface when sub-buffers have been consumed via relay_subbufs_consumed(). Any subsequent attempts to write into the buffer will again invoke the subbuf_start() callback with the same parameters; only when the consumer has consumed one or more of the ready sub-buffers will relay_buf_full() return 0, in which case the buffer switch can continue.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehjchhubh)}(h^The implementation of the subbuf_start() callback for 'overwrite' mode would be very similar::h]haThe implementation of the subbuf_start() callback for ‘overwrite’ mode would be very similar:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMqhjchhubj)}(hXQstatic int subbuf_start(struct rchan_buf *buf, void *subbuf, void *prev_subbuf, size_t prev_padding) { if (prev_subbuf) *((unsigned *)prev_subbuf) = prev_padding; subbuf_start_reserve(buf, sizeof(unsigned int)); return 1; }h]hXQstatic int subbuf_start(struct rchan_buf *buf, void *subbuf, void *prev_subbuf, size_t prev_padding) { if (prev_subbuf) *((unsigned *)prev_subbuf) = prev_padding; subbuf_start_reserve(buf, sizeof(unsigned int)); return 1; }}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMthjchhubh)}(hXIn this case, the relay_buf_full() check is meaningless and the callback always returns 1, causing the buffer switch to occur unconditionally. It's also meaningless for the client to use the relay_subbufs_consumed() function in this mode, as it's never consulted.h]hX In this case, the relay_buf_full() check is meaningless and the callback always returns 1, causing the buffer switch to occur unconditionally. It’s also meaningless for the client to use the relay_subbufs_consumed() function in this mode, as it’s never consulted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjchhubh)}(hThe default subbuf_start() implementation, used if the client doesn't define any callbacks, or doesn't define the subbuf_start() callback, implements the simplest possible 'no-overwrite' mode, i.e., it does nothing but return 0.h]hThe default subbuf_start() implementation, used if the client doesn’t define any callbacks, or doesn’t define the subbuf_start() callback, implements the simplest possible ‘no-overwrite’ mode, i.e., it does nothing but return 0.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjchhubh)}(hXHeader information can be reserved at the beginning of each sub-buffer by calling the subbuf_start_reserve() helper function from within the subbuf_start() callback. This reserved area can be used to store whatever information the client wants. In the example above, room is reserved in each sub-buffer to store the padding count for that sub-buffer. This is filled in for the previous sub-buffer in the subbuf_start() implementation; the padding value for the previous sub-buffer is passed into the subbuf_start() callback along with a pointer to the previous sub-buffer, since the padding value isn't known until a sub-buffer is filled. The subbuf_start() callback is also called for the first sub-buffer when the channel is opened, to give the client a chance to reserve space in it. In this case the previous sub-buffer pointer passed into the callback will be NULL, so the client should check the value of the prev_subbuf pointer before writing into the previous sub-buffer.h]hXHeader information can be reserved at the beginning of each sub-buffer by calling the subbuf_start_reserve() helper function from within the subbuf_start() callback. This reserved area can be used to store whatever information the client wants. In the example above, room is reserved in each sub-buffer to store the padding count for that sub-buffer. This is filled in for the previous sub-buffer in the subbuf_start() implementation; the padding value for the previous sub-buffer is passed into the subbuf_start() callback along with a pointer to the previous sub-buffer, since the padding value isn’t known until a sub-buffer is filled. The subbuf_start() callback is also called for the first sub-buffer when the channel is opened, to give the client a chance to reserve space in it. In this case the previous sub-buffer pointer passed into the callback will be NULL, so the client should check the value of the prev_subbuf pointer before writing into the previous sub-buffer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjchhubeh}(h] channel-modesah ]h"]channel 'modes'ah$]h&]uh1hhjhhhhhM1ubh)}(hhh](h)}(hWriting to a channelh]hWriting to a channel}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXKernel clients write data into the current cpu's channel buffer using relay_write() or __relay_write(). relay_write() is the main logging function - it uses local_irqsave() to protect the buffer and should be used if you might be logging from interrupt context. If you know you'll never be logging from interrupt context, you can use __relay_write(), which only disables preemption. These functions don't return a value, so you can't determine whether or not they failed - the assumption is that you wouldn't want to check a return value in the fast logging path anyway, and that they'll always succeed unless the buffer is full and no-overwrite mode is being used, in which case you can detect a failed write in the subbuf_start() callback by calling the relay_buf_full() helper function.h]hX$Kernel clients write data into the current cpu’s channel buffer using relay_write() or __relay_write(). relay_write() is the main logging function - it uses local_irqsave() to protect the buffer and should be used if you might be logging from interrupt context. If you know you’ll never be logging from interrupt context, you can use __relay_write(), which only disables preemption. These functions don’t return a value, so you can’t determine whether or not they failed - the assumption is that you wouldn’t want to check a return value in the fast logging path anyway, and that they’ll always succeed unless the buffer is full and no-overwrite mode is being used, in which case you can detect a failed write in the subbuf_start() callback by calling the relay_buf_full() helper function.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX]relay_reserve() is used to reserve a slot in a channel buffer which can be written to later. This would typically be used in applications that need to write directly into a channel buffer without having to stage data in a temporary buffer beforehand. Because the actual write may not happen immediately after the slot is reserved, applications using relay_reserve() can keep a count of the number of bytes actually written, either in space reserved in the sub-buffers themselves or as a separate array. See the 'reserve' example in the relay-apps tarball at http://relayfs.sourceforge.net for an example of how this can be done. Because the write is under control of the client and is separated from the reserve, relay_reserve() doesn't protect the buffer at all - it's up to the client to provide the appropriate synchronization when using relay_reserve().h](hX5relay_reserve() is used to reserve a slot in a channel buffer which can be written to later. This would typically be used in applications that need to write directly into a channel buffer without having to stage data in a temporary buffer beforehand. Because the actual write may not happen immediately after the slot is reserved, applications using relay_reserve() can keep a count of the number of bytes actually written, either in space reserved in the sub-buffers themselves or as a separate array. See the ‘reserve’ example in the relay-apps tarball at }(hj5hhhNhNubj)}(hhttp://relayfs.sourceforge.neth]hhttp://relayfs.sourceforge.net}(hj=hhhNhNubah}(h]h ]h"]h$]h&]refurij?uh1jhj5ubhX for an example of how this can be done. Because the write is under control of the client and is separated from the reserve, relay_reserve() doesn’t protect the buffer at all - it’s up to the client to provide the appropriate synchronization when using relay_reserve().}(hj5hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]writing-to-a-channelah ]h"]writing to a channelah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hClosing a channelh]hClosing a channel}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^hhhhhMubh)}(hXaThe client calls relay_close() when it's finished using the channel. The channel and its associated buffers are destroyed when there are no longer any references to any of the channel buffers. relay_flush() forces a sub-buffer switch on all the channel buffers, and can be used to finalize and process the last sub-buffers before the channel is closed.h]hXcThe client calls relay_close() when it’s finished using the channel. The channel and its associated buffers are destroyed when there are no longer any references to any of the channel buffers. relay_flush() forces a sub-buffer switch on all the channel buffers, and can be used to finalize and process the last sub-buffers before the channel is closed.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubeh}(h]closing-a-channelah ]h"]closing a channelah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hMisch]hMisc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXSome applications may want to keep a channel around and re-use it rather than open and close a new channel for each use. relay_reset() can be used for this purpose - it resets a channel to its initial state without reallocating channel buffer memory or destroying existing mappings. It should however only be called when it's safe to do so, i.e., when the channel isn't currently being written to.h]hXSome applications may want to keep a channel around and re-use it rather than open and close a new channel for each use. relay_reset() can be used for this purpose - it resets a channel to its initial state without reallocating channel buffer memory or destroying existing mappings. It should however only be called when it’s safe to do so, i.e., when the channel isn’t currently being written to.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXbFinally, there are a couple of utility callbacks that can be used for different purposes. buf_mapped() is called whenever a channel buffer is mmapped from user space and buf_unmapped() is called when it's unmapped. The client can use this notification to trigger actions within the kernel application, such as enabling/disabling logging to the channel.h]hXdFinally, there are a couple of utility callbacks that can be used for different purposes. buf_mapped() is called whenever a channel buffer is mmapped from user space and buf_unmapped() is called when it’s unmapped. The client can use this notification to trigger actions within the kernel application, such as enabling/disabling logging to the channel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]miscah ]h"]miscah$]h&]uh1hhjhhhhhMubeh}(h]the-relay-interface-kernel-apiah ]h"]the relay interface kernel apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Resourcesh]h Resources}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hLFor news, example code, mailing list, etc. see the relay interface homepage:h]hLFor news, example code, mailing list, etc. see the relay interface homepage:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh block_quote)}(h http://relayfs.sourceforge.net h]h)}(hhttp://relayfs.sourceforge.neth]j)}(hjh]hhttp://relayfs.sourceforge.net}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h] resourcesah ]h"] resourcesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hCreditsh]hCredits}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(huThe ideas and specs for the relay interface came about as a result of discussions on tracing involving the following:h]huThe ideas and specs for the relay interface came about as a result of discussions on tracing involving the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hMichel Dagenais Richard Moore Bob Wisniewski Karim Yaghmour Tom Zanussi h](hMichel Dagenais <}(hj,hhhNhNubj)}(hmichel.dagenais@polymtl.cah]hmichel.dagenais@polymtl.ca}(hj4hhhNhNubah}(h]h ]h"]h$]h&]refuri!mailto:michel.dagenais@polymtl.cauh1jhj,ubh> Richard Moore <}(hj,hhhNhNubj)}(hrichardj_moore@uk.ibm.comh]hrichardj_moore@uk.ibm.com}(hjHhhhNhNubah}(h]h ]h"]h$]h&]refuri mailto:richardj_moore@uk.ibm.comuh1jhj,ubh> Bob Wisniewski <}(hj,hhhNhNubj)}(hbob@watson.ibm.comh]hbob@watson.ibm.com}(hj\hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:bob@watson.ibm.comuh1jhj,ubh> Karim Yaghmour <}(hj,hhhNhNubj)}(hkarim@opersys.comh]hkarim@opersys.com}(hjphhhNhNubah}(h]h ]h"]h$]h&]refurimailto:karim@opersys.comuh1jhj,ubh> Tom Zanussi <}(hj,hhhNhNubj)}(hzanussi@us.ibm.comh]hzanussi@us.ibm.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:zanussi@us.ibm.comuh1jhj,ubh>}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hOAlso thanks to Hubertus Franke for a lot of useful suggestions and bug reports.h]hOAlso thanks to Hubertus Franke for a lot of useful suggestions and bug reports.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]creditsah ]h"]creditsah$]h&]uh1hhhhhhhhMubeh}(h] relay-interface-formerly-relayfsah ]h"]"relay interface (formerly relayfs)ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksj7footnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjj{jxjjjjjjj`j]jjj[jXjjjjj jjju nametypes}(jj{jjjj`jj[jjj juh}(jhjxjjj~jjjjj]jjjcjXjjj^jjjjjj u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.