On Sat, 31 Jan 2026 13:28:34 +0000 Vincent Donnefort <[email protected]> wrote:
> Add documentation about the newly introduced tracing remotes framework. > > Signed-off-by: Vincent Donnefort <[email protected]> > Reviewed-by: Steven Rostedt (Google) <[email protected]> But in the future, this document should probably go into more details about what is expected by each callback. -- Steve > diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst > index b4a429dc4f7a..d77ffb7e2d08 100644 > --- a/Documentation/trace/index.rst > +++ b/Documentation/trace/index.rst > @@ -90,6 +90,17 @@ interactions. > user_events > uprobetracer > > +Remote Tracing > +-------------- > + > +This section covers the framework to read compatible ring-buffers, written by > +entities outside of the kernel (most likely firmware or hypervisor) > + > +.. toctree:: > + :maxdepth: 1 > + > + remotes > + > Additional Resources > -------------------- > > diff --git a/Documentation/trace/remotes.rst b/Documentation/trace/remotes.rst > new file mode 100644 > index 000000000000..1f9d764f69aa > --- /dev/null > +++ b/Documentation/trace/remotes.rst > @@ -0,0 +1,66 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +=============== > +Tracing Remotes > +=============== > + > +:Author: Vincent Donnefort <[email protected]> > + > +Overview > +======== > +Firmware and hypervisors are black boxes to the kernel. Having a way to see > what > +they are doing can be useful to debug both. This is where remote tracing > buffers > +come in. A remote tracing buffer is a ring buffer executed by the firmware or > +hypervisor into memory that is memory mapped to the host kernel. This is > similar > +to how user space memory maps the kernel ring buffer but in this case the > kernel > +is acting like user space and the firmware or hypervisor is the "kernel" > side. > +With a trace remote ring buffer, the firmware and hypervisor can record > events > +for which the host kernel can see and expose to user space. > + > +Register a remote > +================= > +A remote must provide a set of callbacks `struct trace_remote_callbacks` whom > +description can be found below. Those callbacks allows Tracefs to enable and > +disable tracing and events, to load and unload a tracing buffer (a set of > +ring-buffers) and to swap a reader page with the head page, which enables > +consuming reading. > + > +.. kernel-doc:: include/linux/trace_remote.h > + > +Once registered, an instance will appear for this remote in the Tracefs > +directory **remotes/**. Buffers can then be read using the usual Tracefs > files > +**trace_pipe** and **trace**. > + > +Declare a remote event > +====================== > +Macros are provided to ease the declaration of remote events, in a similar > +fashion to in-kernel events. A declaration must provide an ID, a description > of > +the event arguments and how to print the event: > + > +.. code-block:: c > + > + REMOTE_EVENT(foo, EVENT_FOO_ID, > + RE_STRUCT( > + re_field(u64, bar) > + ), > + RE_PRINTK("bar=%lld", __entry->bar) > + ); > + > +Then those events must be declared in a C file with the following: > + > +.. code-block:: c > + > + #define REMOTE_EVENT_INCLUDE_FILE foo_events.h > + #include <trace/define_remote_events.h> > + > +This will provide a `struct remote_event remote_event_foo` that can be given > to > +`trace_remote_register`. > + > +Registered events appear in the remote directory under **events/**. > + > +Simple ring-buffer > +================== > +A simple implementation for a ring-buffer writer can be found in > +kernel/trace/simple_ring_buffer.c. > + > +.. kernel-doc:: include/linux/simple_ring_buffer.h
