Add perfetto support for scratch memory (#303)

* Add perfetto support for scratch memory

* Updated tests and docs.

* Update docs data

* Added underflow check

* Record all free events to 0 bytes

* Add format

* Address review comment

* updated tests for scratch memory

* update scratch-memory tests.

tests/rocprofv3/scratch-memory/validate.py

@@ -74,6 +74,7 @@ def test_scratch_memory(json_input_data, csv_input_data):
         assert "thread_id" in node
         assert "end_timestamp" in node
         assert "start_timestamp" in node
+        assert "allocation_size" in node
 
         assert "queue_id" in node
         assert "agent_id" in node
@@ -88,6 +89,22 @@ def test_scratch_memory(json_input_data, csv_input_data):
         assert node.end_timestamp > 0
         assert node.start_timestamp < node.end_timestamp
 
+        # validation for allocation size based on operation
+        operation = bf_op_names[node["operation"]]
+        if operation == "SCRATCH_MEMORY_FREE":
+            # For free events, allocation size must be exactly 0
+            assert (
+                node["allocation_size"] == 0
+            ), f"Free operation should have allocation_size=0, got {node['allocation_size']}"
+        elif operation == "SCRATCH_MEMORY_ALLOC":
+            # Fixme: For alloc events, must be > 0 and < 32GB
+            assert (
+                node["allocation_size"] > 0
+            ), f"Alloc operation should have allocation_size > 0, got {node['allocation_size']}"
+            assert (
+                node["allocation_size"] < 32000000000
+            ), f"Alloc operation size should be < 32GB, got {node['allocation_size']}"
+
         assert data.strings.buffer_records[node.kind].kind == "SCRATCH_MEMORY"
         assert (
             data.strings.buffer_records[node.kind].operations[node.operation]
@@ -96,6 +113,7 @@ def test_scratch_memory(json_input_data, csv_input_data):
 
         scratch_reported_agent_ids.add(node["agent_id"]["handle"])
 
+    verify_scratch_memory_alternating_pattern(scratch_memory_data, bf_op_names)
     assert 2**64 - 1 not in scratch_reported_agent_ids
     assert scratch_reported_agent_ids == detected_agents_ids
 
@@ -115,6 +133,9 @@ def test_scratch_memory(json_input_data, csv_input_data):
         assert (
             "Thread_Id" in row
         ), "Thread_Id header not present in csv for scratch memory trace."
+        assert (
+            "Allocation_Size" in row
+        ), "Allocation_Size header not present in csv for scratch memory trace."
         assert (
             "Alloc_Flags" in row
         ), "Alloc_Flags header not present in csv for scratch memory trace."
@@ -130,11 +151,62 @@ def test_scratch_memory(json_input_data, csv_input_data):
         assert int(row["Agent_Id"].split(" ")[-1]) >= 0
         assert int(row["Queue_Id"]) > 0
         assert int(row["Thread_Id"]) > 0
+        assert int(row["Allocation_Size"]) >= 0
         assert int(row["Start_Timestamp"]) > 0
         assert int(row["End_Timestamp"]) > 0
         assert int(row["Start_Timestamp"]) < int(row["End_Timestamp"])
 
 
+def verify_scratch_memory_alternating_pattern(scratch_memory_data, bf_op_names):
+    """
+    Verify that operations follow ALLOC→FREE→ALLOC→FREE pattern per (thread, flags) combination.
+    """
+    # Track operations by thread and flags
+    thread_flag_operations = {}
+
+    for node in scratch_memory_data:
+        thread_id = node["thread_id"]
+        operation = node["operation"]  # Numeric (1=ALLOC, 2=FREE)
+        flags = node["flags"]
+        timestamp = node["start_timestamp"]
+
+        key = (thread_id, flags)
+        if key not in thread_flag_operations:
+            thread_flag_operations[key] = []
+
+        thread_flag_operations[key].append((timestamp, operation))
+
+    # Verify proper alternating sequence for each thread+flags combination
+    for (thread_id, flags), operations in thread_flag_operations.items():
+        # Sort by timestamp to ensure chronological order
+        sorted_ops = [op for _, op in sorted(operations)]
+
+        # Must start with ALLOC (operation code 1)
+        if sorted_ops and sorted_ops[0] != 1:
+            raise AssertionError(
+                f"Thread {thread_id}, Flags {flags}: Must start with ALLOC, found operation code {sorted_ops[0]}"
+            )
+
+        # Check for alternating pattern - expected pattern is ALLOC→FREE→ALLOC→FREE
+        for i in range(len(sorted_ops)):
+            expected = 1 if i % 2 == 0 else 2  # 1=ALLOC, 2=FREE
+            if sorted_ops[i] != expected:
+                op_name = (
+                    bf_op_names[sorted_ops[i]]
+                    if sorted_ops[i] < len(bf_op_names)
+                    else f"Unknown({sorted_ops[i]})"
+                )
+                expected_name = (
+                    bf_op_names[expected]
+                    if expected < len(bf_op_names)
+                    else f"Unknown({expected})"
+                )
+
+                raise AssertionError(
+                    f"Thread {thread_id}, Flags {flags}: Operation #{i+1} should be {expected_name} (code {expected}), found {op_name} (code {sorted_ops[i]})"
+                )
+
+
 if __name__ == "__main__":
     exit_code = pytest.main(["-x", __file__] + sys.argv[1:])
     sys.exit(exit_code)