Document the APS5_PROFILE_DRAW output and add a log digest

[fisherjoey]

Problem

APS5_PROFILE_DRAW is read at 156 places in 46 files, and its periodic reports are the main way to measure a performance change: [present], [packets], [lock], [dispatch], [recipe], [rescache], [textures], [draw-cache], [dispatch-cache], [buffers] and others. None of it is documented; neither the variable nor any of the line families appear in docs/. What each field means (window length, per queue or total, cumulative or per window) has to be read from the code that prints it.

Pull requests compare these lines by hand. 8 of the 62 perf pull requests quote profiler output in the description or comments (for example #157, #401, #858, #1193), each with its own excerpt and layout. A profiled run of one title in our tests writes 38 to 62 MB of log.

Proposal

1. docs/dev/PROFILING.md:
   • what APS5_PROFILE_DRAW and APS5_PROFILE_GPU turn on and what they cost;
   • one short section per line family: what it counts, over which window, and whether the counter is cumulative;
   • how to compare two runs (same title, same point in the title, more than one run per side);
   • probing the driver with bpftrace: the driver libraries keep their symbols, so probes can be written against names (uprobe:<lib>:AgcDriver::...) and resolved with nm -C instead of hard-coded offsets, which change with every build.
2. Optional, separate pull request: tools/profile_summary.py LOG [LOG2]. It reads a profiled log and prints median, min and max per 10 s window for each family. With two logs it prints them side by side with deltas, as a table that can be pasted into a pull request. Time windows only; it knows nothing about specific titles.

What we have

A parser for these line families (about 700 lines of Python) and summary and diff commands built on it, which we use for every profiled run. It splits runs by markers from one title, so the upstream version would drop that part and keep the parsing and the table.

Questions

• Would you take PROFILING.md as a pull request? If new files under docs/dev/ are not wanted, would a section in BUILD.md or ARCHITECTURE.md work?
• Is the line format stable enough to document, or would you rather the doc describe only the families and leave field details to the code?
• Is a parser in tools/ welcome, given that it has to follow format changes in the driver? A test against a sample log would catch that.

AI-assisted: yes