On Thu, 3 Sep 2026 21:24:09 +0800
Pengfei Li <[email protected]> wrote:
> Add supporting files for the ftrace stackmap feature:
>
Could you decouple tools/docs/tests in independent patches?
> Documentation/trace/ftrace-stackmap.rst:
> Documentation covering design, usage, tracefs interface, binary
> format, and performance characteristics. Added to the 'Core Tracing
> Frameworks' toctree in Documentation/trace/index.rst. Documents:
> - Reset clears the map and nothing else: the trace buffer is left
> untouched and tracing does not have to be stopped, so <stack_id N>
> records in an already-collected trace can stop resolving after a
> reset. Read the trace out first if the ids need to stay meaningful
> - Boot-time activation via trace_options=stackmap: events use the
> full-stack fallback until the map and required resolver are created
> and the map is published to global_trace.stackmap
> - bits parameter range [10, 18] and worst-case memory usage
> - tracefs file modes (0640 / 0440), with stack_map required and
> stack_map_stat / stack_map_bin treated as auxiliary observability
> nodes whose creation failure does not disable deduplication
> - Best-effort snapshot semantics for stack_map_bin, serialized
> against reset via the reader_sem
> - Counter definitions and stable output: successes counts map operations
> that return a stack ID; drops counts capacity or probe-limit
> failures; success_rate excludes bypasses that never call the map
> and remains present as 0% when both counters are zero
> - Gravestone amplification when the pool is exhausted
>
> tools/testing/selftests/ftrace/test.d/ftrace/stackmap-basic.tc:
> Functional selftest verifying:
> - required stackmap tracefs nodes exist; tests that consume auxiliary
> nodes declare them in '# requires:' and skip if unavailable
> - enabling stackmap + stacktrace produces stack_id events
> - stack_map_stat shows non-zero successes; a nonzero drops count is
> a legitimate by-design fallback and is not treated as failure
> - reset succeeds while tracing is active, since it clears the map
> only and leaves the ring buffer alone
> - reset also clears the map when tracing is stopped
> The test starts and exits with a map reset so a failed run cannot
> leak entries or counters into the next case. It reads trace contents
> BEFORE switching back to the nop tracer (tracer_init()
> unconditionally resets the ring buffer). The function:tracer
> dependency is declared in '# requires:' so ftracetest skips on
> kernels without CONFIG_FUNCTION_TRACER instead of failing spuriously.
If each test has this volume description, it is enough to split those
tests in independent patches.
[...]
> +def main():
> + parser = argparse.ArgumentParser(description='Parse ftrace
> stack_map_bin')
> + parser.add_argument('file', help='Path to stack_map_bin file')
> + parser.add_argument('--vmlinux', help='Path to vmlinux for symbol
> resolution')
> + parser.add_argument('--json', action='store_true', help='JSON output')
> + parser.add_argument('--top', type=int, default=0,
> + help='Show only top N stacks by ref_count')
> + args = parser.parse_args()
> +
> + with open(args.file, 'rb') as f:
> + data = f.read()
nit: Can this support input from stdin? If we use this on android,
user may want to do:
adb shell cat /sys/.../stack_map_bin | python3 stackmap_dump.py
instead of pulling the file.
Thanks,
--
Masami Hiramatsu (Google) <[email protected]>
