[PATCH 4/4] perf docs: Describe multi-record thread maps

[Leo Yan <leo.yan@arm.com>]

Document the PERF_RECORD_THREAD_MAP layout using the structure names
and flexible array declaration from the code.

Describe the continuation flag and ordered assembly of split maps.
Explain that readers must collect the complete map before allocating
per-thread counters or processing statistics, and that split maps
require updated readers.

Signed-off-by: Leo Yan <leo.yan@arm.com>
---
 tools/perf/Documentation/perf.data-file-format.txt | 24 ++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/tools/perf/Documentation/perf.data-file-format.txt b/tools/perf/Documentation/perf.data-file-format.txt
index 1f8e7d8e9ae21d732df698c9d2560377dea5f03f..6b59404ef0ff92102aeb63fc0d1da283536a4add 100644
--- a/tools/perf/Documentation/perf.data-file-format.txt
+++ b/tools/perf/Documentation/perf.data-file-format.txt
@@ -651,6 +651,30 @@ struct auxtrace_error_event {
 	char msg[MAX_AUXTRACE_ERROR_MSG];
 };
 
+	PERF_RECORD_THREAD_MAP			= 73,
+
+Lists thread IDs and command names.
+
+struct perf_record_thread_map_entry {
+	uint64_t pid;
+	char comm[16];
+};
+
+struct perf_record_thread_map {
+	struct perf_event_header header;
+	uint64_t nr;
+	struct perf_record_thread_map_entry entries[];
+};
+
+Large maps are split into records that fit in the 16-bit header.size field.
+PERF_RECORD_MISC_THREAD_MAP_MORE (1 << 0) in header.misc is set when another
+record follows and clear for the final record. Each record's nr counts only
+its own entries. Concatenate entries in record order, preserving their
+positions, until a record with MORE clear completes the map. Consumers must
+assemble the complete map before allocating per-thread counters or processing
+statistics. Split maps require readers that support this convention; maps
+that fit in one record are unchanged.
+
 	PERF_RECORD_HEADER_FEATURE		= 80,
 
 Describes a header feature. These are records used in pipe-mode that

-- 
2.34.1