Add a description for each tracefs file available in a trace remote instance.
Signed-off-by: Vincent Donnefort <[email protected]> diff --git a/Documentation/trace/remotes.rst b/Documentation/trace/remotes.rst index 1f9d764f69aa..b02ebed4a03f 100644 --- a/Documentation/trace/remotes.rst +++ b/Documentation/trace/remotes.rst @@ -19,8 +19,8 @@ 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 +A remote must provide a set of callbacks `struct trace_remote_callbacks` whose +description can be found below. Those callbacks allow 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. @@ -28,8 +28,66 @@ 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**. +directory **remotes/**. The files within this directory allow configuring +and reading the remote buffer (see `The File System` below). + +The File System +=============== +A remote tracing instance is represented by a directory in Tracefs under +**remotes/**. The layout and files within it are very similar to standard ftrace +instances. Inside the remote directory, the following files and directories are +available: + + tracing_on + This file allows enabling or disabling the remote tracing. + + buffer_size_kb + This file displays and allows changing the size of the per-CPU ring + buffers used by the remote. It also shows if the buffer is **loaded** or + **unloaded**. To change the size, the remote buffers must be unloaded + first. Remote buffers are automatically unloaded when **tracing_on** is + off, no one is reading the buffer (either by accessing **trace_pipe** or + when **dmesg** is on) and no events remain in the buffer. + + trace + Display the human-readable content of the remote buffers. Reading this + file is non-consuming. Writing to this file clears the ring buffers. + + trace_pipe + Similar to **trace** but reading it consumes the events from the ring + buffers (consuming read). It blocks if there are no new events. + + dmesg + When enabled, all events from the remote are redirected to the kernel + dmesg. This is similar to the **tp_printk** option for in-kernel events. + It counts as a reader of the remote buffers and prevents unloading. + + dump_on_panic + When enabled, the remote tracing buffer is dumped to the console when a + kernel panic occurs. + + poll_ms + Modifies the polling interval for the trace_remote. + + per_cpu/ + This directory contains subdirectories for each possible CPU (e.g., + **cpu0/**, **cpu1/** ...) + + per_cpu/cpuX/trace + This is similar to the **trace** file, but it will only display the data + specific for the CPU. If written to, it only clears the specific CPU + buffer. + + per_cpu/cpuX/trace_pipe + This is similar to the **trace_pipe** file, and is a consuming read, but + it will only display (and consume) the data specific to the CPU. + + events/ + This directory contains remote events that can be enabled or disabled. + + events/enable + Allows enabling or disabling all the remote events. + Declare a remote event ====================== -- 2.54.0.1032.g2f8565e1d1-goog
