1 /* 2 * Copyright (C) 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_HL_ABI_H_ 18 #define INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_HL_ABI_H_ 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #include "perfetto/public/abi/track_event_abi.h" 24 25 // High level ABI to emit track events. 26 // 27 // For each tracepoint, the user must call PerfettoTeHlEmitImpl() once and pass 28 // it all the required data for the event. The function will iterate all enabled 29 // data source instances and serialize the tracing data as protobuf messages. 30 // 31 // This tries to cover the most common cases of track event. When hitting these 32 // we minimize binary size at the trace-event call site, but we trade off the 33 // ability to serialize custom protobuf messages. 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 // The type of the proto field. 40 enum PerfettoTeHlProtoFieldType { 41 PERFETTO_TE_HL_PROTO_TYPE_CSTR = 0, 42 PERFETTO_TE_HL_PROTO_TYPE_BYTES = 1, 43 PERFETTO_TE_HL_PROTO_TYPE_NESTED = 2, 44 PERFETTO_TE_HL_PROTO_TYPE_VARINT = 3, 45 PERFETTO_TE_HL_PROTO_TYPE_FIXED64 = 4, 46 PERFETTO_TE_HL_PROTO_TYPE_FIXED32 = 5, 47 PERFETTO_TE_HL_PROTO_TYPE_DOUBLE = 6, 48 PERFETTO_TE_HL_PROTO_TYPE_FLOAT = 7, 49 }; 50 51 // Common header for all the proto fields. 52 struct PerfettoTeHlProtoField { 53 enum PerfettoTeHlProtoFieldType type; 54 // Proto field id. 55 uint32_t id; 56 }; 57 58 // PERFETTO_TE_HL_PROTO_TYPE_CSTR 59 struct PerfettoTeHlProtoFieldCstr { 60 struct PerfettoTeHlProtoField header; 61 // Null terminated string. 62 const char* str; 63 }; 64 65 // PERFETTO_TE_HL_PROTO_TYPE_BYTES 66 struct PerfettoTeHlProtoFieldBytes { 67 struct PerfettoTeHlProtoField header; 68 const void* buf; 69 size_t len; 70 }; 71 72 // PERFETTO_TE_HL_PROTO_TYPE_NESTED 73 struct PerfettoTeHlProtoFieldNested { 74 struct PerfettoTeHlProtoField header; 75 // Array of pointers to the fields. The last pointer should be NULL. 76 struct PerfettoTeHlProtoField* const* fields; 77 }; 78 79 // PERFETTO_TE_HL_PROTO_TYPE_VARINT 80 struct PerfettoTeHlProtoFieldVarInt { 81 struct PerfettoTeHlProtoField header; 82 uint64_t value; 83 }; 84 85 // PERFETTO_TE_HL_PROTO_TYPE_FIXED64 86 struct PerfettoTeHlProtoFieldFixed64 { 87 struct PerfettoTeHlProtoField header; 88 uint64_t value; 89 }; 90 91 // PERFETTO_TE_HL_PROTO_TYPE_FIXED32 92 struct PerfettoTeHlProtoFieldFixed32 { 93 struct PerfettoTeHlProtoField header; 94 uint32_t value; 95 }; 96 97 // PERFETTO_TE_HL_PROTO_TYPE_DOUBLE 98 struct PerfettoTeHlProtoFieldDouble { 99 struct PerfettoTeHlProtoField header; 100 double value; 101 }; 102 103 // PERFETTO_TE_HL_PROTO_TYPE_FLOAT 104 struct PerfettoTeHlProtoFieldFloat { 105 struct PerfettoTeHlProtoField header; 106 float value; 107 }; 108 109 // The type of an event extra parameter. 110 enum PerfettoTeHlExtraType { 111 PERFETTO_TE_HL_EXTRA_TYPE_REGISTERED_TRACK = 1, 112 PERFETTO_TE_HL_EXTRA_TYPE_NAMED_TRACK = 2, 113 PERFETTO_TE_HL_EXTRA_TYPE_TIMESTAMP = 3, 114 PERFETTO_TE_HL_EXTRA_TYPE_DYNAMIC_CATEGORY = 4, 115 PERFETTO_TE_HL_EXTRA_TYPE_COUNTER_INT64 = 5, 116 PERFETTO_TE_HL_EXTRA_TYPE_COUNTER_DOUBLE = 6, 117 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_BOOL = 7, 118 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_UINT64 = 8, 119 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_INT64 = 9, 120 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_DOUBLE = 10, 121 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_STRING = 11, 122 PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_POINTER = 12, 123 PERFETTO_TE_HL_EXTRA_TYPE_FLOW = 13, 124 PERFETTO_TE_HL_EXTRA_TYPE_TERMINATING_FLOW = 14, 125 PERFETTO_TE_HL_EXTRA_TYPE_FLUSH = 15, 126 PERFETTO_TE_HL_EXTRA_TYPE_NO_INTERN = 16, 127 PERFETTO_TE_HL_EXTRA_TYPE_PROTO_FIELDS = 17, 128 PERFETTO_TE_HL_EXTRA_TYPE_PROTO_TRACK = 18, 129 }; 130 131 // An extra event parameter. Each type of parameter should embed this as its 132 // first member. 133 struct PerfettoTeHlExtra { 134 // enum PerfettoTeHlExtraType. Identifies the exact type of this. 135 uint32_t type; 136 }; 137 138 // PERFETTO_TE_HL_EXTRA_TYPE_REGISTERED_TRACK 139 struct PerfettoTeHlExtraRegisteredTrack { 140 struct PerfettoTeHlExtra header; 141 // Pointer to a registered track. 142 const struct PerfettoTeRegisteredTrackImpl* track; 143 }; 144 145 // PERFETTO_TE_HL_EXTRA_TYPE_NAMED_TRACK 146 struct PerfettoTeHlExtraNamedTrack { 147 struct PerfettoTeHlExtra header; 148 // The name of the track 149 const char* name; 150 uint64_t id; 151 uint64_t parent_uuid; 152 }; 153 154 // PERFETTO_TE_HL_EXTRA_TYPE_TIMESTAMP 155 struct PerfettoTeHlExtraTimestamp { 156 struct PerfettoTeHlExtra header; 157 // The timestamp for this event. 158 struct PerfettoTeTimestamp timestamp; 159 }; 160 161 // PERFETTO_TE_HL_EXTRA_TYPE_DYNAMIC_CATEGORY 162 struct PerfettoTeHlExtraDynamicCategory { 163 struct PerfettoTeHlExtra header; 164 // Pointer to a category descriptor. The descriptor will be evaluated against 165 // the configuration. If the descriptor is considered disabled, the trace 166 // point will be skipped. 167 const struct PerfettoTeCategoryDescriptor* desc; 168 }; 169 170 // PERFETTO_TE_HL_EXTRA_TYPE_COUNTER_INT64 171 struct PerfettoTeHlExtraCounterInt64 { 172 struct PerfettoTeHlExtra header; 173 // The counter value. 174 int64_t value; 175 }; 176 177 // PERFETTO_TE_HL_EXTRA_TYPE_COUNTER_DOUBLE 178 struct PerfettoTeHlExtraCounterDouble { 179 struct PerfettoTeHlExtra header; 180 // The counter value. 181 double value; 182 }; 183 184 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_BOOL 185 struct PerfettoTeHlExtraDebugArgBool { 186 struct PerfettoTeHlExtra header; 187 // Pointer to the name of this debug annotation. 188 const char* name; 189 // The value of this debug annotation. 190 bool value; 191 }; 192 193 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_UINT64 194 struct PerfettoTeHlExtraDebugArgUint64 { 195 struct PerfettoTeHlExtra header; 196 // Pointer to the name of this debug annotation. 197 const char* name; 198 // The value of this debug annotation. 199 uint64_t value; 200 }; 201 202 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_INT64 203 struct PerfettoTeHlExtraDebugArgInt64 { 204 struct PerfettoTeHlExtra header; 205 // Pointer to the name of this debug annotation. 206 const char* name; 207 // The value of this debug annotation. 208 int64_t value; 209 }; 210 211 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_DOUBLE 212 struct PerfettoTeHlExtraDebugArgDouble { 213 struct PerfettoTeHlExtra header; 214 // Pointer to the name of this debug annotation. 215 const char* name; 216 // The value of this debug annotation. 217 double value; 218 }; 219 220 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_STRING 221 struct PerfettoTeHlExtraDebugArgString { 222 struct PerfettoTeHlExtra header; 223 // Pointer to the name of this debug annotation. 224 const char* name; 225 // The value of this debug annotation. 226 const char* value; 227 }; 228 229 // PERFETTO_TE_HL_EXTRA_TYPE_DEBUG_ARG_POINTER 230 struct PerfettoTeHlExtraDebugArgPointer { 231 struct PerfettoTeHlExtra header; 232 // Pointer to the name of this debug annotation. 233 const char* name; 234 // The value of this debug annotation. 235 uintptr_t value; 236 }; 237 238 // PERFETTO_TE_HL_EXTRA_TYPE_FLOW 239 // PERFETTO_TE_HL_EXTRA_TYPE_TERMINATING_FLOW 240 struct PerfettoTeHlExtraFlow { 241 struct PerfettoTeHlExtra header; 242 // Specifies that this event starts (or terminates) a flow (i.e. a link 243 // between two events) identified by this id. 244 uint64_t id; 245 }; 246 247 // PERFETTO_TE_HL_EXTRA_TYPE_PROTO_FIELDS 248 struct PerfettoTeHlExtraProtoFields { 249 struct PerfettoTeHlExtra header; 250 // Array of pointers to the fields. The last pointer should be NULL. 251 struct PerfettoTeHlProtoField* const* fields; 252 }; 253 254 // PERFETTO_TE_HL_EXTRA_TYPE_PROTO_TRACK 255 struct PerfettoTeHlExtraProtoTrack { 256 struct PerfettoTeHlExtra header; 257 uint64_t uuid; 258 // Array of pointers to the fields. The last pointer should be NULL. 259 struct PerfettoTeHlProtoField* const* fields; 260 }; 261 262 // Emits an event on all active instances of the track event data source. 263 // * `cat`: The registered category of the event, it knows on which data source 264 // instances the event should be emitted. Use 265 // `perfetto_te_all_categories` for dynamic categories. 266 // * `type`: the event type (slice begin, slice end, ...). See `enum 267 // PerfettoTeType`. 268 // * `name`: All events (except when PERFETTO_TE_TYPE_SLICE_END) can have an 269 // associated name. It can be nullptr. 270 // * `extra_data`: Optional parameters associated with the events. Array of 271 // pointers to each event. The last pointer should be NULL. 272 PERFETTO_SDK_EXPORT void PerfettoTeHlEmitImpl( 273 struct PerfettoTeCategoryImpl* cat, 274 int32_t type, 275 const char* name, 276 struct PerfettoTeHlExtra* const* extra_data); 277 278 #ifdef __cplusplus 279 } 280 #endif 281 282 #endif // INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_HL_ABI_H_ 283