Re: [RFC PATCH v6 3/3] trace: add documentation, selftest and tooling for stackmap

[Masami Hiramatsu (Google) <mhiramat@kernel.org>]

On Thu,  3 Sep 2026 21:24:09 +0800
Pengfei Li <ljdlns1987@gmail.com> 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) <mhiramat@kernel.org>