kernel/linux.git/Documentation/trace, branch v6.19.11

Documentation: tracing: Add PCI tracepoint documentation

2026-02-26T23:01:05+00:00

[ Upstream commit 8236fc613d44e59f6736d6c3e9efffaf26ab7f00 ] The PCI tracing system provides tracepoints to monitor critical hardware events that can impact system performance and reliability. Add documentation about it. Signed-off-by: Shuai Xue [bhelgaas: squash fixes: https://lore.kernel.org/r/20260108013956.14351-2-bagasdotme@gmail.com https://lore.kernel.org/r/20260108013956.14351-3-bagasdotme@gmail.com] Signed-off-by: Bjorn Helgaas Reviewed-by: Ilpo Järvinen Link: https://patch.msgid.link/20251210132907.58799-4-xueshuai@linux.alibaba.com Signed-off-by: Sasha Levin

Merge tag 'trace-v6.19' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace

2025-12-05T17:51:37+00:00

Pull tracing updates from Steven Rostedt: - Extend tracing option mask to 64 bits The trace options were defined by a 32 bit variable. This limits the tracing instances to have a total of 32 different options. As that limit has been hit, and more options are being added, increase the option mask to a 64 bit number, doubling the number of options available. As this is required for the kprobe topic branches as well as the tracing topic branch, a separate branch was created and merged into both. - Make trace_user_fault_read() available for the rest of tracing The function trace_user_fault_read() is used by trace_marker file read to allow reading user space to be done fast and without locking or allocations. Make this available so that the system call trace events can use it too. - Have system call trace events read user space values Now that the system call trace events callbacks are called in a faultable context, take advantage of this and read the user space buffers for various system calls. For example, show the path name of the openat system call instead of just showing the pointer to that path name in user space. Also show the contents of the buffer of the write system call. Several system call trace events are updated to make tracing into a light weight strace tool for all applications in the system. - Update perf system call tracing to do the same - And a config and syscall_user_buf_size file to control the size of the buffer Limit the amount of data that can be read from user space. The default size is 63 bytes but that can be expanded to 165 bytes. - Allow the persistent ring buffer to print system calls normally The persistent ring buffer prints trace events by their type and ignores the print_fmt. This is because the print_fmt may change from kernel to kernel. As the system call output is fixed by the system call ABI itself, there's no reason to limit that. This makes reading the system call events in the persistent ring buffer much nicer and easier to understand. - Add options to show text offset to function profiler The function profiler that counts the number of times a function is hit currently lists all functions by its name and offset. But this becomes ambiguous when there are several functions with the same name. Add a tracing option that changes the output to be that of '_text+offset' instead. Now a user space tool can use this information to map the '_text+offset' to the unique function it is counting. - Report bad dynamic event command If a bad command is passed to the dynamic_events file, report it properly in the error log. - Clean up tracer options Clean up the tracer option code a bit, by removing some useless code and also using switch statements instead of a series of if statements. - Have tracing options be instance specific Tracers can have their own options (function tracer, irqsoff tracer, function graph tracer, etc). But now that the same tracer can be enabled in multiple trace instances, their options are still global. The API is per instance, thus changing one affects other instances. This isn't even consistent, as the option take affect differently depending on when an tracer started in an instance. Make the options for instances only affect the instance it is changed under. - Optimize pid_list lock contention Whenever the pid_list is read, it uses a spin lock. This happens at every sched switch. Taking the lock at sched switch can be removed by instead using a seqlock counter. - Clean up the trace trigger structures The trigger code uses two different structures to implement a single tigger. This was due to trying to reuse code for the two different types of triggers (always on trigger, and count limited trigger). But by adding a single field to one structure, the other structure could be absorbed into the first structure making he code easier to understand. - Create a bulk garbage collector for trace triggers If user space has triggers for several hundreds of events and then removes them, it can take several seconds to complete. This is because each removal calls tracepoint_synchronize_unregister() that can take hundreds of milliseconds to complete. Instead, create a helper thread that will do the clean up. When a trigger is removed, it will create the kthread if it isn't already created, and then add the trigger to a llist. The kthread will take the items off the llist, call tracepoint_synchronize_unregister(), and then remove the items it took off. It will then check if there's more items to free before sleeping. This makes user space removing all these triggers to finish in less than a second. - Allow function tracing of some of the tracing infrastructure code Because the tracing code can cause recursion issues if it is traced by the function tracer the entire tracing directory disables function tracing. But not all of tracing causes issues if it is traced. Namely, the event tracing code. Add a config that enables some of the tracing code to be traced to help in debugging it. Note, when this is enabled, it does add noise to general function tracing, especially if events are enabled as well (which is a common case). - Add boot-time backup instance for persistent buffer The persistent ring buffer is used mostly for kernel crash analysis in the field. One issue is that if there's a crash, the data in the persistent ring buffer must be read before tracing can begin using it. This slows down the boot process. Once tracing starts in the persistent ring buffer, the old data must be freed and the addresses no longer match and old events can't be in the buffer with new events. Create a way to create a backup buffer that copies the persistent ring buffer at boot up. Then after a crash, the always on tracer can begin immediately as well as the normal boot process while the crash analysis tooling uses the backup buffer. After the backup buffer is finished being read, it can be removed. - Enable function graph args and return address options at the same time Currently the when reading of arguments in the function graph tracer is enabled, the option to record the parent function in the entry event can not be enabled. Update the code so that it can. - Add new struct_offset() helper macro Add a new macro that takes a pointer to a structure and a name of one of its members and it will return the offset of that member. This allows the ring buffer code to simplify the following: From: size = struct_size(entry, buf, cnt - sizeof(entry->id)); To: size = struct_offset(entry, id) + cnt; There should be other simplifications that this macro can help out with as well * tag 'trace-v6.19' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace: (42 commits) overflow: Introduce struct_offset() to get offset of member function_graph: Enable funcgraph-args and funcgraph-retaddr to work simultaneously tracing: Add boot-time backup of persistent ring buffer ftrace: Allow tracing of some of the tracing code tracing: Use strim() in trigger_process_regex() instead of skip_spaces() tracing: Add bulk garbage collection of freeing event_trigger_data tracing: Remove unneeded event_mutex lock in event_trigger_regex_release() tracing: Merge struct event_trigger_ops into struct event_command tracing: Remove get_trigger_ops() and add count_func() from trigger ops tracing: Show the tracer options in boot-time created instance ftrace: Avoid redundant initialization in register_ftrace_direct tracing: Remove unused variable in tracing_trace_options_show() fgraph: Make fgraph_no_sleep_time signed tracing: Convert function graph set_flags() to use a switch() statement tracing: Have function graph tracer option sleep-time be per instance tracing: Move graph-time out of function graph options tracing: Have function graph tracer option funcgraph-irqs be per instance trace/pid_list: optimize pid_list->lock contention tracing: Have function graph tracer define options per instance tracing: Have function tracer define options per instance ...

Documentation/trace: Specify exact priority for timerlat

2025-11-05T18:19:20+00:00

The timerlat tracer documentation mentions that threads are created with real-time priority, but does not mention which priority and scheduling class is used. Add the information so that users do not have to look it up in trace_osnoise.c. Signed-off-by: Tomas Glozar Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20251010083338.478961-9-tglozar@redhat.com>

tracing: Add a config and syscall_user_buf_size file to limit amount written

2025-10-29T00:10:59+00:00

When a system call that can copy user space addresses into the ring buffer, it can copy up to 511 bytes of data. This can waste precious ring buffer space if the user isn't interested in the output. Add a new file "syscall_user_buf_size" that gets initialized to a new config CONFIG_SYSCALL_BUF_SIZE_DEFAULT that defaults to 63. The config also is used to limit how much perf can read from user space. Also lower the max down to 165, as this isn't to record everything that a system call may be passing through to the kernel. 165 is more than enough. The reason for 165 is because adding one for the nul terminating byte, as well as possibly needing to append the "..." string turns it into 170 bytes. As this needs to save up to 3 arguments and 3 * 170 is 510 which fits nicely in 512 bytes (a power of 2). Cc: Masami Hiramatsu Cc: Mark Rutland Cc: Mathieu Desnoyers Cc: Andrew Morton Cc: Peter Zijlstra Cc: Namhyung Kim Cc: Takaya Saeki Cc: Tom Zanussi Cc: Thomas Gleixner Cc: Ian Rogers Cc: Douglas Raillard Cc: Arnaldo Carvalho de Melo Cc: Jiri Olsa Cc: Adrian Hunter Cc: Ingo Molnar Link: https://lore.kernel.org/20251028231148.260068913@kernel.org Signed-off-by: Steven Rostedt (Google)

Documentation: trace: histogram: Convert ftrace docs cross-reference

2025-09-18T17:49:26+00:00

In brief "Extended error information" section, details on error condition is referred to ftrace docs, which is written in :file: directive instead of a proper cross-reference. Convert it. Reviewed-by: Tom Zanussi Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-7-bagasdotme@gmail.com>

Documentation: trace: histogram-design: Wrap introductory note in note:: directive

2025-09-18T17:49:26+00:00

Use Sphinx note:: directive for the introductory note at the beginning of docs, instead of aligned-text paragraph that renders as definition list. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-6-bagasdotme@gmail.com>

Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram

2025-09-18T17:49:26+00:00

Section heading for sched_waking histogram is shown as normal paragraph instead due to codeblock marker for the following diagram being in the same line as the section underline. Separate them. Fixes: daceabf1b494 ("tracing/doc: Fix ascii-art in histogram-design.rst") Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-5-bagasdotme@gmail.com>

Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text

2025-09-18T17:49:26+00:00

Diagram explanation text is supposed to be interleaved commentary between diagram parts that are spread out, but it outputs ugly in htmldocs due to trailing vertices as if both the explanation and the diagram are in the same literal code block. Trim trailing vertices. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-4-bagasdotme@gmail.com>

Documentation: trace: histogram: Fix histogram trigger subsection number order

2025-09-18T17:49:26+00:00

Section numbering in subsections of "Histogram Trigger Command" sections is inconsistent in order. In particular, "'hist' trigger examples" is erroneously numbered as 6.2, which is a leftover from b8df4a3634e08a ("tracing: Move hist trigger Documentation to histogram.txt"). Fix the order. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-3-bagasdotme@gmail.com>

tracing: fix grammar error in debugging.rst

2025-09-03T21:31:48+00:00

Signed-off-by: Ryan Chung Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250831101736.11519-3-seokwoo.chung130@gmail.com