linux-kernel - Re: [PATCH v10 16/30] Documentation: tracing: Add tracing remotes

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20260129121629.25d2c0e7@gandalf.local.home>
Date: Thu, 29 Jan 2026 12:16:29 -0500
From: Steven Rostedt <rostedt@...dmis.org>
To: Vincent Donnefort <vdonnefort@...gle.com>
Cc: mhiramat@...nel.org, mathieu.desnoyers@...icios.com,
 linux-trace-kernel@...r.kernel.org, maz@...nel.org, oliver.upton@...ux.dev,
 joey.gouly@....com, suzuki.poulose@....com, yuzenghui@...wei.com,
 kvmarm@...ts.linux.dev, linux-arm-kernel@...ts.infradead.org,
 jstultz@...gle.com, qperret@...gle.com, will@...nel.org,
 aneesh.kumar@...nel.org, kernel-team@...roid.com,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH v10 16/30] Documentation: tracing: Add tracing remotes

On Mon, 26 Jan 2026 10:44:05 +0000
Vincent Donnefort <vdonnefort@...gle.com> wrote:

> Add documentation about the newly introduced tracing remotes framework.
> 
> Signed-off-by: Vincent Donnefort <vdonnefort@...gle.com>
> 
> 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..e7fb3ee96c30
> --- /dev/null
> +++ b/Documentation/trace/remotes.rst
> @@ -0,0 +1,59 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============
> +Tracing Remotes
> +===============
> +
> +:Author: Vincent Donnefort <vdonnefort@...gle.com>
> +
> +Overview
> +========

Probably should start off with the rationale for remotes. Perhaps start
with something like:

  Firmware and pkvm 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.

But we can expand on this later. The above should be the minimum added to
allow people to understand why this is being created.

-- Steve

> +A trace remote relies on ring-buffer remotes to read and control compatible
> +tracing buffers, written by entity such as firmware or hypervisor.
> +
> +Once registered, a tracefs instance will appear for this remote in the Tracefs
> +directory **remotes/**. This remote can be read and controlled using the same
> +files as regular Tracefs instances such as **trace_pipe**, **tracing_on** or
> +**trace**.
> +
> +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
> +
> +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`.
> +
> +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