€•Œë      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ%/translations/zh_CN/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/zh_TW/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/it_IT/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/ja_JP/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/ko_KR/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/sp_SP/filesystems/relay”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒ?/var/lib/git/docbuild/linux/Documentation/filesystems/relay.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ"relay interface (formerly relayfs)”h]”hŒ"relay interface (formerly relayfs)”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒµThe 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]”hŒ¹The 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hËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hXW  A '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]”hXe  A â€˜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hÙhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hXv  The 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]”hXx  The 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hçhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒÉThis 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]”hŒÉThis 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hõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒ	Semantics”h]”hŒ	Semantics”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K!ubhÊ)”}”(hX“  Each 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]”hX“  Each 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K#hj  hžhubhÊ)”}”(hŒîWhen 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]”hŒðWhen 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j"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K*hj  hžhubhÊ)”}”(hŒVAfter copying it, userspace can notify the kernel that a sub-buffer
has been consumed.”h]”hŒVAfter copying it, userspace can notify the kernel that a sub-buffer
has been consumed.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hj  hžhubhÊ)”}”(hŒ†A 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]”hŒ†A 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j>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K2hj  hžhubhÊ)”}”(hX  The 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]”hX  The 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jL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K5hj  hžhubhÊ)”}”(hŒú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.”h]”hŒü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.”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K;hj  hžhubhÊ)”}”(hX6  One 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]”hX8  One 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jh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K@hj  hžhubeh}”(h]”Œ	semantics”ah ]”h"]”Œ	semantics”ah$]”h&]”uh1h´hh¶hžhhŸh³h K!ubhµ)”}”(hhh]”(hº)”}”(hŒ klog and relay-apps example code”h]”hŒ klog and relay-apps example code”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj~  hžhhŸh³h KGubhÊ)”}”(hŒThe 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]”hŒThe 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KIhj~  hžhubhÊ)”}”(hXŒ  The 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]”hXŒ  The 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KLhj~  hžhubhÊ)”}”(hX5  The '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]”hXA  The â€˜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j«  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KShj~  hžhubhÊ)”}”(hXy  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.”h]”hX}  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.”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K]hj~  hžhubhÊ)”}”(hŒiklog and the relay-apps examples can be found in the relay-apps
tarball on http://relayfs.sourceforge.net”h]”(hŒKklog and the relay-apps examples can be found in the relay-apps
tarball on ”…””}”(hjÇ  hžhhŸNh NubhŒ	reference”“”)”}”(hŒhttp://relayfs.sourceforge.net”h]”hŒhttp://relayfs.sourceforge.net”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jÓ  uh1jÏ  hjÇ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhj~  hžhubeh}”(h]”Œ klog-and-relay-apps-example-code”ah ]”h"]”Œ klog and relay-apps example code”ah$]”h&]”uh1h´hh¶hžhhŸh³h KGubhµ)”}”(hhh]”(hº)”}”(hŒ"The relay interface user space API”h]”hŒ"The relay interface user space API”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjî  hžhhŸh³h KlubhÊ)”}”(hŒÅThe 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]”hŒÅThe 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jÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Knhjî  hžhubhŒtable”“”)”}”(hhh]”hŒtgroup”“”)”}”(hhh]”(hŒcolspec”“”)”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”Œcolwidth”Kuh1j  hj  ubj  )”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”Œcolwidth”K<uh1j  hj  ubhŒtbody”“”)”}”(hhh]”(hŒrow”“”)”}”(hhh]”(hŒentry”“”)”}”(hhh]”hÊ)”}”(hŒopen()”h]”hŒopen()”…””}”(hj<  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kshj9  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj4  ubj8  )”}”(hhh]”hÊ)”}”(hŒ2enables user to open an _existing_ channel buffer.”h]”hŒ2enables user to open an _existing_ channel buffer.”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KshjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj4  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubj3  )”}”(hhh]”(j8  )”}”(hhh]”hÊ)”}”(hŒmmap()”h]”hŒmmap()”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kuhjp  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjm  ubj8  )”}”(hhh]”hÊ)”}”(hŒ©results in channel buffer being mapped into the caller's
memory space. Note that you can't do a partial mmap - you
must map the entire file, which is NRBUF * SUBBUFSIZE.”h]”hŒ­results in channel buffer being mapped into the callerâ€™s
memory space. Note that you canâ€™t do a partial mmap - you
must map the entire file, which is NRBUF * SUBBUFSIZE.”…””}”(hjŠ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kuhj‡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjm  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubj3  )”}”(hhh]”(j8  )”}”(hhh]”hÊ)”}”(hŒread()”h]”hŒread()”…””}”(hjª  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kyhj§  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj¤  ubj8  )”}”(hhh]”hÊ)”}”(hXC  read the contents of a channel buffer.  The bytes read are
'consumed' by the reader, i.e., they won't be available
again to subsequent reads.  If the channel is being used
in no-overwrite mode (the default), it can be read at any
time even if there's an active kernel writer.  If the
channel is being used in overwrite mode and there are
active channel writers, results may be unpredictable -
users should make sure that all logging to the channel has
ended before using read() with overwrite mode.  Sub-buffer
padding is automatically removed and will not be seen by
the reader.”h]”hXK  read the contents of a channel buffer.  The bytes read are
â€˜consumedâ€™ by the reader, i.e., they wonâ€™t be available
again to subsequent reads.  If the channel is being used
in no-overwrite mode (the default), it can be read at any
time even if thereâ€™s an active kernel writer.  If the
channel is being used in overwrite mode and there are
active channel writers, results may be unpredictable -
users should make sure that all logging to the channel has
ended before using read() with overwrite mode.  Sub-buffer
padding is automatically removed and will not be seen by
the reader.”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kyhj¾  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj¤  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubj3  )”}”(hhh]”(j8  )”}”(hhh]”hÊ)”}”(hŒ
sendfile()”h]”hŒ
sendfile()”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K…hjÞ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjÛ  ubj8  )”}”(hhh]”hÊ)”}”(hŒ‘transfer data from a channel buffer to an output file
descriptor. Sub-buffer padding is automatically removed
and will not be seen by the reader.”h]”hŒ‘transfer data from a channel buffer to an output file
descriptor. Sub-buffer padding is automatically removed
and will not be seen by the reader.”…””}”(hjø  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K…hjõ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjÛ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubj3  )”}”(hhh]”(j8  )”}”(hhh]”hÊ)”}”(hŒpoll()”h]”hŒpoll()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K‰hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj  ubj8  )”}”(hhh]”hÊ)”}”(hŒlPOLLIN/POLLRDNORM/POLLERR supported.  User applications are
notified when sub-buffer boundaries are crossed.”h]”hŒlPOLLIN/POLLRDNORM/POLLERR supported.  User applications are
notified when sub-buffer boundaries are crossed.”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K‰hj,  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubj3  )”}”(hhh]”(j8  )”}”(hhh]”hÊ)”}”(hŒclose()”h]”hŒclose()”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŒhjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjI  ubj8  )”}”(hhh]”hÊ)”}”(hŒ decrements the channel buffer's refcount.  When the refcount
reaches 0, i.e., when no process or kernel client has the
buffer open, the channel buffer is freed.”h]”hŒ¢decrements the channel bufferâ€™s refcount.  When the refcount
reaches 0, i.e., when no process or kernel client has the
buffer open, the channel buffer is freed.”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŒhjc  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hjI  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j2  hj/  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j-  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”Œcols”Kuh1j  hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjî  hžhhŸh³h NubhÊ)”}”(hŒoIn order for a user application to make use of relay files, the
host filesystem must be mounted.  For example::”h]”hŒnIn order for a user application to make use of relay files, the
host filesystem must be mounted.  For example:”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K‘hjî  hžhubhŒliteral_block”“”)”}”(hŒ*mount -t debugfs debugfs /sys/kernel/debug”h]”hŒ*mount -t debugfs debugfs /sys/kernel/debug”…””}”hj£  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h K”hjî  hžhubhŒnote”“”)”}”(hŒ¶The host filesystem doesn't need to be mounted for kernel
clients to create or use channels - it only needs to be
mounted when user space applications need access to the buffer
data.”h]”hÊ)”}”(hŒ¶The host filesystem doesn't need to be mounted for kernel
clients to create or use channels - it only needs to be
mounted when user space applications need access to the buffer
data.”h]”hŒ¸The host filesystem doesnâ€™t need to be mounted for kernel
clients to create or use channels - it only needs to be
mounted when user space applications need access to the buffer
data.”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K˜hj³  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j±  hjî  hžhhŸh³h Nubeh}”(h]”Œ"the-relay-interface-user-space-api”ah ]”h"]”Œ"the relay interface user space api”ah$]”h&]”uh1h´hh¶hžhhŸh³h Klubhµ)”}”(hhh]”(hº)”}”(hŒThe relay interface kernel API”h]”hŒThe relay interface kernel API”…””}”(hjÖ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÓ  hžhhŸh³h KŸubhÊ)”}”(hŒNHere's a summary of the API the relay interface provides to in-kernel clients:”h]”hŒPHereâ€™s a summary of the API the relay interface provides to in-kernel clients:”…””}”(hjä  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¡hjÓ  hžhubhŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hXä  TBD(curr. line MT:/API/)
channel management functions::

  relay_open(base_filename, parent, subbuf_size, n_subbufs,
             callbacks, private_data)
  relay_close(chan)
  relay_flush(chan)
  relay_reset(chan)

channel management typically called on instigation of userspace::

  relay_subbufs_consumed(chan, cpu, subbufs_consumed)

write functions::

  relay_write(chan, data, length)
  __relay_write(chan, data, length)
  relay_reserve(chan, length)

callbacks::

  subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
  buf_mapped(buf, filp)
  buf_unmapped(buf, filp)
  create_buf_file(filename, parent, mode, buf, is_global)
  remove_buf_file(dentry)

helper functions::

  relay_buf_full(buf)
  subbuf_start_reserve(buf, length)

”h]”(hŒterm”“”)”}”(hŒTBD(curr. line MT:/API/)”h]”hŒTBD(curr. line MT:/API/)”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jý  hŸh³h KÂhjù  ubhŒ
definition”“”)”}”(hhh]”(hÊ)”}”(hŒchannel management functions::”h]”hŒchannel management functions:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¤hj  ubj¢  )”}”(hŒ“relay_open(base_filename, parent, subbuf_size, n_subbufs,
           callbacks, private_data)
relay_close(chan)
relay_flush(chan)
relay_reset(chan)”h]”hŒ“relay_open(base_filename, parent, subbuf_size, n_subbufs,
           callbacks, private_data)
relay_close(chan)
relay_flush(chan)
relay_reset(chan)”…””}”hj   sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h K¦hj  ubhÊ)”}”(hŒAchannel management typically called on instigation of userspace::”h]”hŒ@channel management typically called on instigation of userspace:”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¬hj  ubj¢  )”}”(hŒ3relay_subbufs_consumed(chan, cpu, subbufs_consumed)”h]”hŒ3relay_subbufs_consumed(chan, cpu, subbufs_consumed)”…””}”hj<  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h K®hj  ubhÊ)”}”(hŒwrite functions::”h]”hŒwrite functions:”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K°hj  ubj¢  )”}”(hŒ]relay_write(chan, data, length)
__relay_write(chan, data, length)
relay_reserve(chan, length)”h]”hŒ]relay_write(chan, data, length)
__relay_write(chan, data, length)
relay_reserve(chan, length)”…””}”hjX  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h K²hj  ubhÊ)”}”(hŒcallbacks::”h]”hŒ
callbacks:”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¶hj  ubj¢  )”}”(hŒ²subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
buf_mapped(buf, filp)
buf_unmapped(buf, filp)
create_buf_file(filename, parent, mode, buf, is_global)
remove_buf_file(dentry)”h]”hŒ²subbuf_start(buf, subbuf, prev_subbuf, prev_padding)
buf_mapped(buf, filp)
buf_unmapped(buf, filp)
create_buf_file(filename, parent, mode, buf, is_global)
remove_buf_file(dentry)”…””}”hjt  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h K¸hj  ubhÊ)”}”(hŒhelper functions::”h]”hŒhelper functions:”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¾hj  ubj¢  )”}”(hŒ5relay_buf_full(buf)
subbuf_start_reserve(buf, length)”h]”hŒ5relay_buf_full(buf)
subbuf_start_reserve(buf, length)”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h KÀhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjù  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j÷  hŸh³h KÂhjô  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jò  hjÓ  hžhhŸh³h Nubhµ)”}”(hhh]”(hº)”}”(hŒCreating a channel”h]”hŒCreating a channel”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj°  hžhhŸh³h KÅubhÊ)”}”(hX7  relay_open() is used to create a channel, along with its per-cpu
channel buffers.  Each channel buffer will have an associated file
created for it in the host filesystem, which can be and mmapped or
read from in user space.  The files are named basename0...basenameN-1
where N is the number of online cpus, and by default will be created
in the root of the filesystem (if the parent param is NULL).  If you
want a directory structure to contain your relay files, you should
create it using the host filesystem's directory creation function,
e.g. debugfs_create_dir(), and pass the parent directory to
relay_open().  Users are responsible for cleaning up any directory
structure they create, when the channel is closed - again the host
filesystem's directory removal functions should be used for that,
e.g. debugfs_remove().”h]”hX;  relay_open() is used to create a channel, along with its per-cpu
channel buffers.  Each channel buffer will have an associated file
created for it in the host filesystem, which can be and mmapped or
read from in user space.  The files are named basename0...basenameN-1
where N is the number of online cpus, and by default will be created
in the root of the filesystem (if the parent param is NULL).  If you
want a directory structure to contain your relay files, you should
create it using the host filesystemâ€™s directory creation function,
e.g. debugfs_create_dir(), and pass the parent directory to
relay_open().  Users are responsible for cleaning up any directory
structure they create, when the channel is closed - again the host
filesystemâ€™s directory removal functions should be used for that,
e.g. debugfs_remove().”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÇhj°  hžhubhÊ)”}”(hXs  In order for a channel to be created and the host filesystem's files
associated with its channel buffers, the user must provide definitions
for two callback functions, create_buf_file() and remove_buf_file().
create_buf_file() is called once for each per-cpu buffer from
relay_open() and allows the user to create the file which will be used
to represent the corresponding channel buffer.  The callback should
return the dentry of the file created to represent the channel buffer.
remove_buf_file() must also be defined; it's responsible for deleting
the file(s) created in create_buf_file() and is called during
relay_close().”h]”hXw  In order for a channel to be created and the host filesystemâ€™s files
associated with its channel buffers, the user must provide definitions
for two callback functions, create_buf_file() and remove_buf_file().
create_buf_file() is called once for each per-cpu buffer from
relay_open() and allows the user to create the file which will be used
to represent the corresponding channel buffer.  The callback should
return the dentry of the file created to represent the channel buffer.
remove_buf_file() must also be defined; itâ€™s responsible for deleting
the file(s) created in create_buf_file() and is called during
relay_close().”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KÕhj°  hžhubhÊ)”}”(hŒSHere are some typical definitions for these callbacks, in this case
using debugfs::”h]”hŒRHere are some typical definitions for these callbacks, in this case
using debugfs:”…””}”(hjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kàhj°  hžhubj¢  )”}”(hXx  /*
* create_buf_file() callback.  Creates relay file in debugfs.
*/
static struct dentry *create_buf_file_handler(const char *filename,
                                            struct dentry *parent,
                                            umode_t mode,
                                            struct rchan_buf *buf,
                                            int *is_global)
{
        return debugfs_create_file(filename, mode, parent, buf,
                                &relay_file_operations);
}

/*
* remove_buf_file() callback.  Removes relay file from debugfs.
*/
static int remove_buf_file_handler(struct dentry *dentry)
{
        debugfs_remove(dentry);

        return 0;
}

/*
* relay interface callbacks
*/
static struct rchan_callbacks relay_callbacks =
{
        .create_buf_file = create_buf_file_handler,
        .remove_buf_file = remove_buf_file_handler,
};”h]”hXx  /*
* create_buf_file() callback.  Creates relay file in debugfs.
*/
static struct dentry *create_buf_file_handler(const char *filename,
                                            struct dentry *parent,
                                            umode_t mode,
                                            struct rchan_buf *buf,
                                            int *is_global)
{
        return debugfs_create_file(filename, mode, parent, buf,
                                &relay_file_operations);
}

/*
* remove_buf_file() callback.  Removes relay file from debugfs.
*/
static int remove_buf_file_handler(struct dentry *dentry)
{
        debugfs_remove(dentry);

        return 0;
}

/*
* relay interface callbacks
*/
static struct rchan_callbacks relay_callbacks =
{
        .create_buf_file = create_buf_file_handler,
        .remove_buf_file = remove_buf_file_handler,
};”…””}”hjë  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h Kãhj°  hžhubhÊ)”}”(hŒ3And an example relay_open() invocation using them::”h]”hŒ2And an example relay_open() invocation using them:”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj°  hžhubj¢  )”}”(hŒOchan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);”h]”hŒOchan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h Mhj°  hžhubhÊ)”}”(hŒlIf the create_buf_file() callback fails, or isn't defined, channel
creation and thus relay_open() will fail.”h]”hŒnIf the create_buf_file() callback fails, or isnâ€™t defined, channel
creation and thus relay_open() will fail.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj°  hžhubhÊ)”}”(hXd  The total size of each per-cpu buffer is calculated by multiplying the
number of sub-buffers by the sub-buffer size passed into relay_open().
The idea behind sub-buffers is that they're basically an extension of
double-buffering to N buffers, and they also allow applications to
easily implement random-access-on-buffer-boundary schemes, which can
be important for some high-volume applications.  The number and size
of sub-buffers is completely dependent on the application and even for
the same application, different conditions will warrant different
values for these parameters at different times.  Typically, the right
values to use are best decided after some experimentation; in general,
though, it's safe to assume that having only 1 sub-buffer is a bad
idea - you're guaranteed to either overwrite data or lose events
depending on the channel mode being used.”h]”hXj  The total size of each per-cpu buffer is calculated by multiplying the
number of sub-buffers by the sub-buffer size passed into relay_open().
The idea behind sub-buffers is that theyâ€™re basically an extension of
double-buffering to N buffers, and they also allow applications to
easily implement random-access-on-buffer-boundary schemes, which can
be important for some high-volume applications.  The number and size
of sub-buffers is completely dependent on the application and even for
the same application, different conditions will warrant different
values for these parameters at different times.  Typically, the right
values to use are best decided after some experimentation; in general,
though, itâ€™s safe to assume that having only 1 sub-buffer is a bad
idea - youâ€™re guaranteed to either overwrite data or lose events
depending on the channel mode being used.”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M
hj°  hžhubhÊ)”}”(hX’  The create_buf_file() implementation can also be defined in such a way
as to allow the creation of a single 'global' buffer instead of the
default per-cpu set.  This can be useful for applications interested
mainly in seeing the relative ordering of system-wide events without
the need to bother with saving explicit timestamps for the purpose of
merging/sorting per-cpu files in a postprocessing step.”h]”hX–  The create_buf_file() implementation can also be defined in such a way
as to allow the creation of a single â€˜globalâ€™ buffer instead of the
default per-cpu set.  This can be useful for applications interested
mainly in seeing the relative ordering of system-wide events without
the need to bother with saving explicit timestamps for the purpose of
merging/sorting per-cpu files in a postprocessing step.”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj°  hžhubhÊ)”}”(hXâ  To have relay_open() create a global buffer, the create_buf_file()
implementation should set the value of the is_global outparam to a
non-zero value in addition to creating the file that will be used to
represent the single buffer.  In the case of a global buffer,
create_buf_file() and remove_buf_file() will be called only once.  The
normal channel-writing functions, e.g. relay_write(), can still be
used - writes from any cpu will transparently end up in the global
buffer - but since it is a global buffer, callers should make sure
they use the proper locking for such a buffer, either by wrapping
writes in a spinlock, or by copying a write function from relay.h and
creating a local version that internally does the proper locking.”h]”hXâ  To have relay_open() create a global buffer, the create_buf_file()
implementation should set the value of the is_global outparam to a
non-zero value in addition to creating the file that will be used to
represent the single buffer.  In the case of a global buffer,
create_buf_file() and remove_buf_file() will be called only once.  The
normal channel-writing functions, e.g. relay_write(), can still be
used - writes from any cpu will transparently end up in the global
buffer - but since it is a global buffer, callers should make sure
they use the proper locking for such a buffer, either by wrapping
writes in a spinlock, or by copying a write function from relay.h and
creating a local version that internally does the proper locking.”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhj°  hžhubhÊ)”}”(hŒØThe 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.”h]”hŒØThe 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.”…””}”(hjM  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M+hj°  hžhubeh}”(h]”Œcreating-a-channel”ah ]”h"]”Œcreating a channel”ah$]”h&]”uh1h´hjÓ  hžhhŸh³h KÅubhµ)”}”(hhh]”(hº)”}”(hŒChannel 'modes'”h]”hŒChannel â€˜modesâ€™”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjc  hžhhŸh³h M1ubhÊ)”}”(hXÒ  relay 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]”hXÞ  relay 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jt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M3hjc  hžhubhÊ)”}”(hX_  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]”hXk  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j‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M;hjc  hžhubhÊ)”}”(hXÞ  As 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]”hXä  As 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MEhjc  hžhubhÊ)”}”(hŒTo implement 'no-overwrite' mode, the userspace client provides
an implementation of the subbuf_start() callback something like the
following::”h]”hŒ’To implement â€˜no-overwriteâ€™ mode, the userspace client provides
an implementation of the subbuf_start() callback something like the
following:”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MQhjc  hžhubj¢  )”}”(hX“  static 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]”hX“  static 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j¬  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h MUhjc  hžhubhÊ)”}”(hX²  If 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]”hX²  If 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jº  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mehjc  hžhubhÊ)”}”(hŒ^The implementation of the subbuf_start() callback for 'overwrite' mode
would be very similar::”h]”hŒaThe implementation of the subbuf_start() callback for â€˜overwriteâ€™ mode
would be very similar:”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mqhjc  hžhubj¢  )”}”(hXQ  static 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]”hXQ  static 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jÖ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j¡  hŸh³h Mthjc  hžhubhÊ)”}”(hX  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.”h]”hX  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.”…””}”(hjä  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mhjc  hžhubhÊ)”}”(hŒäThe 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]”hŒìThe 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jò  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M‡hjc  hžhubhÊ)”}”(hXØ  Header 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]”hXÚ  Header 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j   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MŒhjc  hžhubeh}”(h]”Œchannel-modes”ah ]”h"]”Œchannel 'modes'”ah$]”h&]”uh1h´hjÓ  hžhhŸh³h M1ubhµ)”}”(hhh]”(hº)”}”(hŒWriting to a channel”h]”hŒWriting to a channel”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h MubhÊ)”}”(hX  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.”h]”hX$  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.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MŸhj  hžhubhÊ)”}”(hX]  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]”(hX5  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 ”…””}”(hj5  hžhhŸNh NubjÐ  )”}”(hŒhttp://relayfs.sourceforge.net”h]”hŒhttp://relayfs.sourceforge.net”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j?  uh1jÏ  hj5  ubhX   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j5  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M¬hj  hžhubeh}”(h]”Œwriting-to-a-channel”ah ]”h"]”Œwriting to a channel”ah$]”h&]”uh1h´hjÓ  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒClosing a channel”h]”hŒClosing a channel”…””}”(hja  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj^  hžhhŸh³h M»ubhÊ)”}”(hXa  The 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]”hXc  The 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jo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h M½hj^  hžhubeh}”(h]”Œclosing-a-channel”ah ]”h"]”Œclosing a channel”ah$]”h&]”uh1h´hjÓ  hžhhŸh³h M»ubhµ)”}”(hhh]”(hº)”}”(hŒMisc”h]”hŒMisc”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj…  hžhhŸh³h MÅubhÊ)”}”(hX  Some 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]”hX“  Some 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j–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MÇhj…  hžhubhÊ)”}”(hXb  Finally, 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]”hXd  Finally, 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j¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MÎhj…  hžhubeh}”(h]”Œmisc”ah ]”h"]”Œmisc”ah$]”h&]”uh1h´hjÓ  hžhhŸh³h MÅubeh}”(h]”Œthe-relay-interface-kernel-api”ah ]”h"]”Œthe relay interface kernel api”ah$]”h&]”uh1h´hh¶hžhhŸh³h KŸubhµ)”}”(hhh]”(hº)”}”(hŒ	Resources”h]”hŒ	Resources”…””}”(hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÂ  hžhhŸh³h M×ubhÊ)”}”(hŒLFor news, example code, mailing list, etc. see the relay interface homepage:”h]”hŒLFor news, example code, mailing list, etc. see the relay interface homepage:”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MÙhjÂ  hžhubhŒblock_quote”“”)”}”(hŒ http://relayfs.sourceforge.net

”h]”hÊ)”}”(hŒhttp://relayfs.sourceforge.net”h]”jÐ  )”}”(hjé  h]”hŒhttp://relayfs.sourceforge.net”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jé  uh1jÏ  hjç  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h MÛhjã  ubah}”(h]”h ]”h"]”h$]”h&]”uh1já  hŸh³h MÛhjÂ  hžhubeh}”(h]”Œ	resources”ah ]”h"]”Œ	resources”ah$]”h&]”uh1h´hh¶hžhhŸh³h M×ubhµ)”}”(hhh]”(hº)”}”(hŒCredits”h]”hŒCredits”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h MßubhÊ)”}”(hŒuThe ideas and specs for the relay interface came about as a result of
discussions on tracing involving the following:”h]”hŒuThe ideas and specs for the relay interface came about as a result of
discussions on tracing involving the following:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Máhj  hžhubhÊ)”}”(hŒîMichel Dagenais         <michel.dagenais@polymtl.ca>
Richard Moore           <richardj_moore@uk.ibm.com>
Bob Wisniewski          <bob@watson.ibm.com>
Karim Yaghmour          <karim@opersys.com>
Tom Zanussi             <zanussi@us.ibm.com>”h]”(hŒMichel Dagenais         <”…””}”(hj,  hžhhŸNh NubjÐ  )”}”(hŒmichel.dagenais@polymtl.ca”h]”hŒmichel.dagenais@polymtl.ca”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œ!mailto:michel.dagenais@polymtl.ca”uh1jÏ  hj,  ubhŒ>
Richard Moore           <”…””}”(hj,  hžhhŸNh NubjÐ  )”}”(hŒrichardj_moore@uk.ibm.com”h]”hŒrichardj_moore@uk.ibm.com”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œ mailto:richardj_moore@uk.ibm.com”uh1jÏ  hj,  ubhŒ>
Bob Wisniewski          <”…””}”(hj,  hžhhŸNh NubjÐ  )”}”(hŒbob@watson.ibm.com”h]”hŒbob@watson.ibm.com”…””}”(hj\  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:bob@watson.ibm.com”uh1jÏ  hj,  ubhŒ>
Karim Yaghmour          <”…””}”(hj,  hžhhŸNh NubjÐ  )”}”(hŒkarim@opersys.com”h]”hŒkarim@opersys.com”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:karim@opersys.com”uh1jÏ  hj,  ubhŒ>
Tom Zanussi             <”…””}”(hj,  hžhhŸNh NubjÐ  )”}”(hŒzanussi@us.ibm.com”h]”hŒzanussi@us.ibm.com”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:zanussi@us.ibm.com”uh1jÏ  hj,  ubhŒ>”…””}”(hj,  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mähj  hžhubhÊ)”}”(hŒOAlso thanks to Hubertus Franke for a lot of useful suggestions and bug
reports.”h]”hŒOAlso thanks to Hubertus Franke for a lot of useful suggestions and bug
reports.”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Mêhj  hžhubeh}”(h]”Œcredits”ah ]”h"]”Œcredits”ah$]”h&]”uh1h´hh¶hžhhŸh³h Mßubeh}”(h]”Œ relay-interface-formerly-relayfs”ah ]”h"]”Œ"relay interface (formerly relayfs)”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”j7  Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÞ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j¹  j¶  j{  jx  jë  jè  jÐ  jÍ  j¿  j¼  j`  j]  j  j  j[  jX  j‚  j  j·  j´  j
  j  j±  j®  uŒ	nametypes”}”(j¹  ‰j{  ‰jë  ‰jÐ  ‰j¿  ‰j`  ‰j  ‰j[  ‰j‚  ‰j·  ‰j
  ‰j±  ‰uh}”(j¶  h¶jx  j  jè  j~  jÍ  jî  j¼  jÓ  j]  j°  j  jc  jX  j  j  j^  j´  j…  j  jÂ  j®  j  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.