[ConSan] Improve comments in TritonInstrumentOps.td (#7907)

Add the description of auxiliary tensors and improve description of ops
to tell how the checks are actually performed.

Author: pawelszczerbuk

include/triton/Dialect/TritonInstrument/IR/TritonInstrumentOps.td

@@ -8,6 +8,25 @@ include "mlir/IR/OpBase.td"
 include "mlir/Interfaces/SideEffectInterfaces.td"
 include "triton/Dialect/TritonInstrument/IR/TritonInstrumentAttrDefs.td"
 
+// Concurrency Sanitizer data structures:
+// ConSan keeps auxilary data requied for tracking memory accesses in tensors.
+// These tensors are stored as a distributed tensor or in global scratch memory.
+//
+// Tensor name   | Storage | Type     | Description
+// ------------- | ------- | -------- | -----------
+// buffers       | tensor  | <Bxi64>  | List of base pointers of all the buffers and sub-buffers in the program
+// barriers      | tensor  | <Mxi64>  | List of pointers to all individual mbarriers in the program
+// writeState    | scratch | <Mxi8>   | Marks which buffers are being written to.
+//               |         |          | Entries in this tensor are set when write operation is issued. Entries are bitfields, where:
+//               |         |          | - bit 0: 1 if the buffer is being written to
+//               |         |          | - bit 1: 1 if the write is *not* hwPipelined
+// writeBars     | scratch | <BxMxi8> | Which barriers track writes to which buffers.
+//               |         |          | Entries in this tensor are set when commit with barrier is called.
+// readBars      | scratch | <BxMxi8> | Which barriers track reads from which buffers.
+//               |         |          | Entries in this tensor are set when read operation with barrier is issued.
+// asyncCpCommits | scratch | <Bxi8>  | Tracks number of outstanding commits for buffers written with cp-async.
+// wgmmaCommits  | scratch | <Bxi8>  | Tracks number of outstanding commits for buffers being read by wgmma.
+
 //
 // Interfaces
 //
@@ -52,10 +71,6 @@ def TTI_ExperimentalCheckWriteStateOp : TTI_Op<"experimental_check_write_state",
   let description = [{
     Check if the writeState tensor has non-zero value associated with the buffer.
 
-    `writeState` is a tensor of 8b bitfields, where:
-    - bit 0: 1 if the buffer is being written to
-    - bit 1: 1 if the write is *not* hwPipelined
-
     If hwPipelined is true, shift the bitfield by 1 to check the second bit - this
     means that the error won't be triggered if another pipelined write is outstanding.
   }];
@@ -79,7 +94,7 @@ def TTI_ExperimentalCheckWriteStateOp : TTI_Op<"experimental_check_write_state",
 def TTI_ExperimentalCheckReadBarriersOp : TTI_Op<"experimental_check_read_barriers", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "check if there are outstanding reads from a buffer guarded by a mbar";
   let description = [{
-    Check if there are outstanding reads from a buffer guarded by a mbar.
+    Check if any of the entries in readBars in the row corresponding to the buffer is non-zero.
   }];
   let arguments = (ins
     TTG_MemDescType:$buf,
@@ -100,11 +115,7 @@ def TTI_ExperimentalSetWriteStateOp : TTI_Op<"experimental_set_write_state", [Me
   let description = [{
     Mark a buffer as being written to. It is not yet tracked by a barrier, until
     `commit_write_with_barrier` is called, at which point all the buffers being written
-    to are marked as tracked by the barrier.
-
-    `writeState` is a tensor of 8b bitfields, where:
-    - bit 0: 1 if the buffer is being written to
-    - bit 1: 1 if the write is *not* hwPipelined
+    to are marked as tracked by the barrier in writeBars tensor.
 
     If hwPipelined is true, the write won't trigger an error if another pipelined
     write is executed later without waiting for the barrier.
@@ -149,7 +160,7 @@ def TTI_ExperimentalCommitWriteWithBarrierOp : TTI_Op<"experimental_commit_write
 def TTI_ExperimentalSetReadBarrierOp : TTI_Op<"experimental_set_read_barrier", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "mark a buffer as being read from using mbar as a guard";
   let description = [{
-    Mark a buffer as being read from using mbar as a guard.
+    Set the entry under [buffer, mbar] in readBars tensor to 1, marking the buffer as tracked by the barrier.
   }];
   let arguments = (ins
     TTG_MemDescType:$buf,
@@ -170,7 +181,8 @@ def TTI_ExperimentalSetReadBarrierOp : TTI_Op<"experimental_set_read_barrier", [
 def TTI_ExperimentalClearWriteBarrierOp : TTI_Op<"experimental_clear_write_barrier", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "clear the write state for buffers being guarded by an mbar";
   let description = [{
-    Clear the write state for buffers being guarded by an mbar.
+    For each buffer that has [buffer, mbar] entry in writeBars tensor, set the corresponding entry in writeState tensor to 0.
+    Also, set the corresponding entry in writeBars tensor to 0.
   }];
   let arguments = (ins
     TTG_MemDescType:$mbar,
@@ -191,7 +203,7 @@ def TTI_ExperimentalClearWriteBarrierOp : TTI_Op<"experimental_clear_write_barri
 def TTI_ExperimentalClearReadBarrierOp : TTI_Op<"experimental_clear_read_barrier", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "clear the read state for buffers being guarded by an mbar";
   let description = [{
-    Clear the read state for buffers being guarded by an mbar.
+    Set all the entries in the column corresponding to the mbar in readBars tensor to 0.
   }];
   let arguments = (ins
     TTG_MemDescType:$mbar,
@@ -210,7 +222,7 @@ def TTI_ExperimentalClearReadBarrierOp : TTI_Op<"experimental_clear_read_barrier
 def TTI_ExperimentalCheckBarrierWritesClearedOp : TTI_Op<"experimental_check_barrier_writes_cleared", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "verify that the barrier is not used to track any writes";
   let description = [{
-    Verify that the barrier is not used to track any writes.
+    Verify that the column corresponding to the mbar in writeBars tensor is all 0.
   }];
   let arguments = (ins
     TTG_MemDescType:$mbar,
@@ -248,7 +260,8 @@ def TTI_ExperimentalStageAccessForCommitOp : TTI_Op<"experimental_stage_access_f
 def TTI_ExperimentalCommitAccessesOp : TTI_Op<"experimental_commit_accesses", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "Commit all the staged accesses for all the buffers.";
   let description = [{
-    Commit all the staged accesses for all the buffers.
+    Increment the value in outstandingCommits tensor for each entry greater than 0.
+    Change all the `-1` entries in outstandingCommits tensor to 1, signifying 1 outstanding commit.
   }];
   let arguments = (ins
     TT_PtrLike:$outstandingCommits,
@@ -277,7 +290,7 @@ def TTI_ExperimentalClearOutstandingCommitsOp : TTI_Op<"experimental_clear_outst
 def TTI_ExperimentalCheckOutstandingCommitsOp : TTI_Op<"experimental_check_outstanding_commits", [MemoryEffects<[MemWrite<GlobalMemory>]>]> {
   let summary = "Check if the buffer has an outstanding commit.";
   let description = [{
-    Check if the buffer has an outstanding commit.
+    Verify that the entry corresponding to the buffer in outstandingCommits tensor is 0.
   }];
   let arguments = (ins
     TTG_MemDescType:$buf,