GPU user annotations (GpuUserAnnotationEvent)

Android.bp

@@ -3672,6 +3672,7 @@ filegroup {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -8506,6 +8507,7 @@ genrule {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -9938,6 +9940,7 @@ filegroup {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
     ],
@@ -9961,6 +9964,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.gen.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.gen.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.gen.cc",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.gen.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.gen.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.gen.cc",
     ],
@@ -9984,6 +9988,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.gen.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.gen.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.gen.h",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.gen.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.gen.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.gen.h",
     ],
@@ -10037,6 +10042,7 @@ genrule {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -10244,6 +10250,7 @@ filegroup {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
     ],
@@ -10266,6 +10273,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.pb.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.pb.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.pb.cc",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.pb.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.pb.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.pb.cc",
     ],
@@ -10288,6 +10296,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.pb.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.pb.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.pb.h",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.pb.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.pb.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.pb.h",
     ],
@@ -10305,6 +10314,7 @@ filegroup {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
     ],
@@ -10328,6 +10338,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.pbzero.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.pbzero.cc",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.pbzero.cc",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.pbzero.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.pbzero.cc",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.pbzero.cc",
     ],
@@ -10351,6 +10362,7 @@ genrule {
         "external/perfetto/protos/perfetto/trace/gpu/gpu_log.pbzero.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_mem_event.pbzero.h",
         "external/perfetto/protos/perfetto/trace/gpu/gpu_render_stage_event.pbzero.h",
+        "external/perfetto/protos/perfetto/trace/gpu/gpu_user_annotation_event.pbzero.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_api_event.pbzero.h",
         "external/perfetto/protos/perfetto/trace/gpu/vulkan_memory_event.pbzero.h",
     ],
@@ -11420,6 +11432,7 @@ filegroup {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -13813,6 +13826,7 @@ genrule {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -22946,6 +22960,7 @@ java_library {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",
@@ -23419,6 +23434,7 @@ python_library_host {
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
         "protos/perfetto/trace/interned_data/interned_data.proto",

BUILD

@@ -9205,6 +9205,7 @@ perfetto_proto_library(
         "protos/perfetto/trace/gpu/gpu_log.proto",
         "protos/perfetto/trace/gpu/gpu_mem_event.proto",
         "protos/perfetto/trace/gpu/gpu_render_stage_event.proto",
+        "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto",
         "protos/perfetto/trace/gpu/vulkan_api_event.proto",
         "protos/perfetto/trace/gpu/vulkan_memory_event.proto",
     ],

include/perfetto/public/protos/trace/trace_packet.pzc.h

@@ -57,6 +57,7 @@ PERFETTO_PB_MSG_DECL(perfetto_protos_GpuInfo);
 PERFETTO_PB_MSG_DECL(perfetto_protos_GpuLog);
 PERFETTO_PB_MSG_DECL(perfetto_protos_GpuMemTotalEvent);
 PERFETTO_PB_MSG_DECL(perfetto_protos_GpuRenderStageEvent);
+PERFETTO_PB_MSG_DECL(perfetto_protos_GpuUserAnnotationEvent);
 PERFETTO_PB_MSG_DECL(perfetto_protos_GraphicsFrameEvent);
 PERFETTO_PB_MSG_DECL(perfetto_protos_InitialDisplayState);
 PERFETTO_PB_MSG_DECL(perfetto_protos_InodeFileMap);
@@ -316,6 +317,11 @@ PERFETTO_PB_FIELD(perfetto_protos_TracePacket,
                   perfetto_protos_GpuRenderStageEvent,
                   gpu_render_stage_event,
                   53);
+PERFETTO_PB_FIELD(perfetto_protos_TracePacket,
+                  MSG,
+                  perfetto_protos_GpuUserAnnotationEvent,
+                  gpu_user_annotation_event,
+                  136);
 PERFETTO_PB_FIELD(perfetto_protos_TracePacket,
                   MSG,
                   perfetto_protos_StreamingProfilePacket,

protos/perfetto/trace/gpu/BUILD.gn

@@ -21,6 +21,7 @@ perfetto_proto_library("@TYPE@") {
     "gpu_log.proto",
     "gpu_mem_event.proto",
     "gpu_render_stage_event.proto",
+    "gpu_user_annotation_event.proto",
     "vulkan_api_event.proto",
     "vulkan_memory_event.proto",
   ]

protos/perfetto/trace/gpu/gpu_user_annotation_event.proto

@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+syntax = "proto2";
+
+package perfetto.protos;
+
+// A user-defined annotation describing a named span on the GPU timeline.
+// next id: 9
+message GpuUserAnnotationEvent {
+  // optional. Unique ID for the event, used to correlate host and GPU work.
+  optional uint64 event_id = 1;
+
+  // optional. Duration of the annotation in nanoseconds. If unset, this is a
+  // single time point event.
+  optional uint64 duration = 2;
+
+  // optional. Name for this annotation.
+  oneof name_field {
+    string name = 3;
+    // Interned annotation name. Refers to EventName in InternedData.
+    uint64 name_iid = 4;
+  }
+
+  // optional. Identifier for GPU in a multi-gpu device.
+  optional int32 gpu_id = 5;
+
+  // required. Graphics context for the annotation.
+  optional uint64 context = 6;
+
+  // optional. ID to a hardware queue description in the specifications.
+  // InternedGpuRenderStageSpecification
+  optional uint64 hw_queue_iid = 7;
+
+  // Typed key/value argument for extending an annotation with custom data.
+  message ExtraArg {
+    // Name of the argument.
+    oneof name_field {
+      // Interned name. Refers to DebugAnnotationName in InternedData.
+      uint64 name_iid = 1;
+      string name = 2;
+    }
+    // Value of the argument.
+    oneof value {
+      int64 int_value = 3;
+      uint64 uint_value = 4;
+      double double_value = 5;
+      string string_value = 6;
+      // Interned string. Refers to InternedString in
+      // debug_annotation_string_values.
+      uint64 string_value_iid = 7;
+    }
+  }
+
+  // Additional typed arguments for the annotation.
+  repeated ExtraArg args = 8;
+}

protos/perfetto/trace/perfetto_trace.proto

@@ -13553,6 +13553,61 @@ message InternedComputeArgName {
 
 // End of protos/perfetto/trace/gpu/gpu_render_stage_event.proto
 
+// Begin of protos/perfetto/trace/gpu/gpu_user_annotation_event.proto
+
+// A user-defined annotation describing a named span on the GPU timeline.
+// next id: 9
+message GpuUserAnnotationEvent {
+  // optional. Unique ID for the event, used to correlate host and GPU work.
+  optional uint64 event_id = 1;
+
+  // optional. Duration of the annotation in nanoseconds. If unset, this is a
+  // single time point event.
+  optional uint64 duration = 2;
+
+  // optional. Name for this annotation.
+  oneof name_field {
+    string name = 3;
+    // Interned annotation name. Refers to EventName in InternedData.
+    uint64 name_iid = 4;
+  }
+
+  // optional. Identifier for GPU in a multi-gpu device.
+  optional int32 gpu_id = 5;
+
+  // required. Graphics context for the annotation.
+  optional uint64 context = 6;
+
+  // optional. ID to a hardware queue description in the specifications.
+  // InternedGpuRenderStageSpecification
+  optional uint64 hw_queue_iid = 7;
+
+  // Typed key/value argument for extending an annotation with custom data.
+  message ExtraArg {
+    // Name of the argument.
+    oneof name_field {
+      // Interned name. Refers to DebugAnnotationName in InternedData.
+      uint64 name_iid = 1;
+      string name = 2;
+    }
+    // Value of the argument.
+    oneof value {
+      int64 int_value = 3;
+      uint64 uint_value = 4;
+      double double_value = 5;
+      string string_value = 6;
+      // Interned string. Refers to InternedString in
+      // debug_annotation_string_values.
+      uint64 string_value_iid = 7;
+    }
+  }
+
+  // Additional typed arguments for the annotation.
+  repeated ExtraArg args = 8;
+}
+
+// End of protos/perfetto/trace/gpu/gpu_user_annotation_event.proto
+
 // Begin of protos/perfetto/trace/gpu/vulkan_api_event.proto
 
 // Message for recording the Vulkan call.
@@ -18160,7 +18215,7 @@ message UiState {
 // See the [Buffers and Dataflow](/docs/concepts/buffers.md) doc for details.
 //
 // Next reserved id: 14 (up to 15).
-// Next id: 136.
+// Next id: 137.
 message TracePacket {
   // Encapsulates the state and configuration of the ProtoVM instances running
   // when the trace was snapshotted. This allows TP to re-instantiate the VMs
@@ -18248,6 +18303,7 @@ message TracePacket {
     ChromeMetadataPacket chrome_metadata = 51;
     GpuCounterEvent gpu_counter_event = 52;
     GpuRenderStageEvent gpu_render_stage_event = 53;
+    GpuUserAnnotationEvent gpu_user_annotation_event = 136;
     StreamingProfilePacket streaming_profile_packet = 54;
     ArtProcessMetadata art_process_metadata = 131;
     GraphicsFrameEvent graphics_frame_event = 57;

protos/perfetto/trace/trace_packet.proto

@@ -51,6 +51,7 @@ import "protos/perfetto/trace/generic_kernel/generic_task.proto";
 import "protos/perfetto/trace/gpu/gpu_counter_event.proto";
 import "protos/perfetto/trace/gpu/gpu_log.proto";
 import "protos/perfetto/trace/gpu/gpu_render_stage_event.proto";
+import "protos/perfetto/trace/gpu/gpu_user_annotation_event.proto";
 import "protos/perfetto/trace/gpu/vulkan_memory_event.proto";
 import "protos/perfetto/trace/gpu/vulkan_api_event.proto";
 import "protos/perfetto/trace/interned_data/interned_data.proto";
@@ -111,7 +112,7 @@ package perfetto.protos;
 // See the [Buffers and Dataflow](/docs/concepts/buffers.md) doc for details.
 //
 // Next reserved id: 14 (up to 15).
-// Next id: 136.
+// Next id: 137.
 message TracePacket {
   // Encapsulates the state and configuration of the ProtoVM instances running
   // when the trace was snapshotted. This allows TP to re-instantiate the VMs
@@ -199,6 +200,7 @@ message TracePacket {
     ChromeMetadataPacket chrome_metadata = 51;
     GpuCounterEvent gpu_counter_event = 52;
     GpuRenderStageEvent gpu_render_stage_event = 53;
+    GpuUserAnnotationEvent gpu_user_annotation_event = 136;
     StreamingProfilePacket streaming_profile_packet = 54;
     ArtProcessMetadata art_process_metadata = 131;
     GraphicsFrameEvent graphics_frame_event = 57;