On Sat, 31 Jan 2026 13:28:34 +0000
Vincent Donnefort <vdonnefort@google.com> wrote:
> Add documentation about the newly introduced tracing remotes framework.
>
> Signed-off-by: Vincent Donnefort <vdonnefort@google.com>
>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
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 <vdonnefort@google.com>
> +
> +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