[llvm-branch-commits] [llvm] [AMDGPU][NewInsertWaitcnt] Event Tracker (2/2) (PR #232344)

[Sameer Sahasrabuddhe via llvm-branch-commits]

================
@@ -63,27 +68,71 @@ struct CounterInfo {
 
 /// Represents a record within the \ref EventTracker's timeline
 /// for one \ref InstCounterType. A record is a pair of \ref MachineInstr
-/// and \ref SingleHWEvent.
+/// and \ref SingleHWEvent with a height in the timeline.
+///
+/// The height is a conservative minimum estimate of *when* the event it
+/// represents occurred. It is used to emit a wait instruction that ensures the
+/// event has completed (e.g. Height = 2 means "wait 2" on the counter ensures
+/// completion of the event across all control-flow paths).
+///
+/// Two examples illustrate how the height works:
+///
+/// If we are iterating a single block where there are no records inherited from
+/// incoming basic blocks, then the height of a record is trivial: if there are
+/// N records, the oldest is at N-1, while the youngest is at 0.
+/// The height of each existing record increases whenever a new one is added.
+///
+/// However, if one record is carried into multiple successor blocks and merged
+/// later (e.g. in a diamond), then the divergence (the same record could be at
+/// a different height depending on the CFG path taken) is reconciled by merging
+/// the records with the same \ref MachineInstr and \ref SingleHWEvent into a
+/// single record whose height is the minimum across the predecessors.
+///
+/// The second example shows that the height is decoupled from a record's
+/// position in the timeline. For example, a timeline could have 4 records, 3
+/// of them at height 0 and the remaining one at height 1.
----------------
ssahasra wrote:

This sentence contradicts the the idea that the height is a property of the event object.

https://github.com/llvm/llvm-project/pull/232344