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 #ifndef INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_LL_ABI_H_ 17 #define INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_LL_ABI_H_ 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #include "perfetto/public/abi/data_source_abi.h" 24 #include "perfetto/public/abi/track_event_abi.h" 25 26 // Low level ABI to emit track events. 27 // 28 // The library provides functions to iterate the active data source instances 29 // (PerfettoTeLlImplBegin and PerfettoTeLlImplNext). The app is responsible for 30 // serializing the "track event" protobuf messages on each instance. 31 // In contrast to the high-level ABI (see track_event_hl_abi.h) this gives the 32 // developer more flexibility and exposes more tracing features, at the cost of 33 // more machine-code per event. 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 // Thread local incremental data of a track event data source instance. Opaque 40 // type. 41 struct PerfettoTeLlImplIncr; 42 43 // Thread local data of a track event data source instance. Opaque type. 44 struct PerfettoTeLlImplTls; 45 46 // Iterator for all the active instances (on this thread) of the track event 47 // data source. 48 struct PerfettoTeLlImplIterator { 49 struct PerfettoDsImplTracerIterator ds; 50 struct PerfettoTeLlImplIncr* incr; 51 struct PerfettoTeLlImplTls* tls; 52 }; 53 54 // Starts the iteration of all the active track event data source instances for 55 // the category `cat`. 56 // 57 // Returns an iterator. If the returned value `ds.tracer` is NULL, there are no 58 // active data source instances. 59 PERFETTO_SDK_EXPORT struct PerfettoTeLlImplIterator PerfettoTeLlImplBegin( 60 struct PerfettoTeCategoryImpl* cat, 61 struct PerfettoTeTimestamp ts); 62 63 // Advances the iterator over the next active track event data source instance 64 // for the category `cat`. 65 // 66 // If iterator->ds.tracer is NULL, there are no more active data source 67 // instances. 68 PERFETTO_SDK_EXPORT void PerfettoTeLlImplNext( 69 struct PerfettoTeCategoryImpl* cat, 70 struct PerfettoTeTimestamp ts, 71 struct PerfettoTeLlImplIterator* iterator); 72 73 // Prematurely terminates an iteration started by PerfettoTeLlImplBegin(). 74 PERFETTO_SDK_EXPORT void PerfettoTeLlImplBreak( 75 struct PerfettoTeCategoryImpl*, 76 struct PerfettoTeLlImplIterator*); 77 78 // Returns true if the category desc `dyn_cat` (which does not need to be 79 // previously registered) is enabled for the track event instance represented by 80 // `tracer` and `inst_id` (from `struct PerfettoTeLlImplIterator`). 81 PERFETTO_SDK_EXPORT bool PerfettoTeLlImplDynCatEnabled( 82 struct PerfettoDsTracerImpl* tracer, 83 PerfettoDsInstanceIndex inst_id, 84 const struct PerfettoTeCategoryDescriptor* dyn_cat); 85 86 // Returns true if the track event incremental state has already seen in the 87 // past the given track UUID. 88 PERFETTO_SDK_EXPORT bool PerfettoTeLlImplTrackSeen(struct PerfettoTeLlImplIncr*, 89 uint64_t uuid); 90 91 // Interning: 92 // 93 // it's possible to avoid repeating the same data over and over in a trace by 94 // using "interning". 95 // 96 // `type` is a field id in the `perfetto.protos.InternedData` protobuf message. 97 // `data` and `data_size` point to the raw data that is potentially repeated. 98 // The buffer pointed by `data` can be anything (e.g. a serialized protobuf 99 // message, or a small integer) that uniquely identifies the potentially 100 // repeated data. 101 // 102 // The function returns an integer (the iid) that can be used instead of 103 // serializing the data directly in the packet. `*seen` is set to false if this 104 // is the first time the library observed this data for this specific type 105 // (therefore it allocated a new iid). 106 PERFETTO_SDK_EXPORT uint64_t 107 PerfettoTeLlImplIntern(struct PerfettoTeLlImplIncr* incr, 108 int32_t type, 109 const void* data, 110 size_t data_size, 111 bool* seen); 112 113 #ifdef __cplusplus 114 } 115 #endif 116 117 #endif // INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_LL_ABI_H_ 118