[llvm] [memprof] Update comments for writeMemProf and its helpers (PR #92446)

[Kazu Hirata via llvm-commits]

https://github.com/kazutakahirata created https://github.com/llvm/llvm-project/pull/92446

This patch adds comments for writeMemProf{V0,V1,V2} in a
version-specific manner.  The mostly repetitive nature of the comments
is somewhat unfortunate but intentional to make it easy to retire
older versions.

Without this patch, the comment just before writeMemProf documents the
Version1 format, which is very confusing.

>From b2cbe3c9c3eac4a296d243f579ed1cee34368a03 Mon Sep 17 00:00:00 2001
From: Kazu Hirata <kazu at google.com>
Date: Thu, 16 May 2024 12:32:16 -0700
Subject: [PATCH] [memprof] Update comments for writeMemProf and its helpers

This patch adds comments for writeMemProf{V0,V1,V2} in a
version-specific manner.  The mostly repetitive nature of the comments
is somewhat unfortunate but intentional to make it easy to retire
older versions.

Without this patch, the comment just before writeMemProf documents the
Version1 format, which is very confusing.
---
 llvm/lib/ProfileData/InstrProfWriter.cpp | 52 ++++++++++++++++++------
 1 file changed, 39 insertions(+), 13 deletions(-)

diff --git a/llvm/lib/ProfileData/InstrProfWriter.cpp b/llvm/lib/ProfileData/InstrProfWriter.cpp
index aeafd429e8bad..4a16332226f16 100644
--- a/llvm/lib/ProfileData/InstrProfWriter.cpp
+++ b/llvm/lib/ProfileData/InstrProfWriter.cpp
@@ -499,6 +499,17 @@ static uint64_t writeMemProfCallStacks(
   return CallStackTableGenerator.Emit(OS.OS);
 }
 
+// Write out MemProf Version0 as follows:
+// uint64_t RecordTableOffset = RecordTableGenerator.Emit
+// uint64_t FramePayloadOffset = Offset for the frame payload
+// uint64_t FrameTableOffset = FrameTableGenerator.Emit
+// uint64_t Num schema entries
+// uint64_t Schema entry 0
+// uint64_t Schema entry 1
+// ....
+// uint64_t Schema entry N - 1
+// OnDiskChainedHashTable MemProfRecordData
+// OnDiskChainedHashTable MemProfFrameData
 static Error writeMemProfV0(ProfOStream &OS,
                             memprof::IndexedMemProfData &MemProfData) {
   uint64_t HeaderUpdatePos = OS.tell();
@@ -521,6 +532,18 @@ static Error writeMemProfV0(ProfOStream &OS,
   return Error::success();
 }
 
+// Write out MemProf Version1 as follows:
+// uint64_t Version
+// uint64_t RecordTableOffset = RecordTableGenerator.Emit
+// uint64_t FramePayloadOffset = Offset for the frame payload
+// uint64_t FrameTableOffset = FrameTableGenerator.Emit
+// uint64_t Num schema entries
+// uint64_t Schema entry 0
+// uint64_t Schema entry 1
+// ....
+// uint64_t Schema entry N - 1
+// OnDiskChainedHashTable MemProfRecordData
+// OnDiskChainedHashTable MemProfFrameData
 static Error writeMemProfV1(ProfOStream &OS,
                             memprof::IndexedMemProfData &MemProfData) {
   OS.write(memprof::Version1);
@@ -544,6 +567,21 @@ static Error writeMemProfV1(ProfOStream &OS,
   return Error::success();
 }
 
+// Write out MemProf Version2 as follows:
+// uint64_t Version
+// uint64_t RecordTableOffset = RecordTableGenerator.Emit
+// uint64_t FramePayloadOffset = Offset for the frame payload
+// uint64_t FrameTableOffset = FrameTableGenerator.Emit
+// uint64_t CallStackPayloadOffset = Offset for the call stack payload
+// uint64_t CallStackTableOffset = CallStackTableGenerator.Emit
+// uint64_t Num schema entries
+// uint64_t Schema entry 0
+// uint64_t Schema entry 1
+// ....
+// uint64_t Schema entry N - 1
+// OnDiskChainedHashTable MemProfRecordData
+// OnDiskChainedHashTable MemProfFrameData
+// OnDiskChainedHashTable MemProfCallStackData
 static Error writeMemProfV2(ProfOStream &OS,
                             memprof::IndexedMemProfData &MemProfData,
                             bool MemProfFullSchema) {
@@ -579,19 +617,7 @@ static Error writeMemProfV2(ProfOStream &OS,
   return Error::success();
 }
 
-// The MemProf profile data includes a simple schema
-// with the format described below followed by the hashtable:
-// uint64_t Version
-// uint64_t RecordTableOffset = RecordTableGenerator.Emit
-// uint64_t FramePayloadOffset = Stream offset before emitting the frame table
-// uint64_t FrameTableOffset = FrameTableGenerator.Emit
-// uint64_t Num schema entries
-// uint64_t Schema entry 0
-// uint64_t Schema entry 1
-// ....
-// uint64_t Schema entry N - 1
-// OnDiskChainedHashTable MemProfRecordData
-// OnDiskChainedHashTable MemProfFrameData
+// Write out the MemProf data in a requested version.
 static Error writeMemProf(ProfOStream &OS,
                           memprof::IndexedMemProfData &MemProfData,
                           memprof::IndexedVersion MemProfVersionRequested,