[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.
----------------
ssahasra wrote:

This doesn't really explain why _minimum_. When two timelines reach the same candidate wait event, and an event E is at position P1 and P2 respectively in those timelines, then what is the property that the merged timeline satisfy? Say P1 is numerically larger than P2, so the new height is P2.  What happens to all the events that exist after P1 on the corresponding timeline?

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