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_ABI_H_ 18 #define INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_ABI_H_ 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 24 #include "perfetto/public/abi/atomic.h" 25 #include "perfetto/public/abi/data_source_abi.h" 26 #include "perfetto/public/abi/export.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 PERFETTO_SDK_EXPORT void PerfettoTeInit(void); 33 34 // The attributes of a single category. 35 struct PerfettoTeCategoryDescriptor { 36 // The category name. Null terminated string. 37 const char* name; 38 // A human readable string shown by the tracing service when listing the data 39 // sources. Null terminated string. 40 const char* desc; 41 // List of tags, can be null if num_tags is 0. Array of pointers to null 42 // terminated strings. 43 const char** tags; 44 // Number of elements in the `tags` array. 45 size_t num_tags; 46 }; 47 48 // Opaque pointer to a registered category. 49 struct PerfettoTeCategoryImpl; 50 51 // An already registered category that's considered enabled if the track event 52 // data source is enabled. Useful for dynamic categories. 53 extern PERFETTO_SDK_EXPORT struct PerfettoTeCategoryImpl* 54 perfetto_te_any_categories; 55 56 // Points to true if the track event data source is enabled. 57 extern PERFETTO_SDK_EXPORT PERFETTO_ATOMIC(bool) * 58 perfetto_te_any_categories_enabled; 59 60 // Registers a category. 61 // 62 // `desc` (and all the objects pointed by it) need to be alive until 63 // PerfettoTeCategoryImplDestroy() is called. 64 PERFETTO_SDK_EXPORT struct PerfettoTeCategoryImpl* PerfettoTeCategoryImplCreate( 65 struct PerfettoTeCategoryDescriptor* desc); 66 67 // Tells the tracing service about newly registered categories. Must be called 68 // after one or more call to PerfettoTeCategoryImplCreate() or 69 // PerfettoTeCategoryImplDestroy(). 70 PERFETTO_SDK_EXPORT void PerfettoTePublishCategories(void); 71 72 // Returns a pointer to a boolean that tells if the category is enabled or not. 73 // The pointer is valid until the category is destroyed. 74 PERFETTO_SDK_EXPORT PERFETTO_ATOMIC(bool) * 75 PerfettoTeCategoryImplGetEnabled(struct PerfettoTeCategoryImpl*); 76 77 // Called when a data source instance is created (if `created` is true) or 78 // destroyed (if `created` is false) with a registered category enabled. 79 // `global_state_changed` is true if this was the first instance created with 80 // the category enabled or the last instance destroyed with the category 81 // enabled. 82 typedef void (*PerfettoTeCategoryImplCallback)(struct PerfettoTeCategoryImpl*, 83 PerfettoDsInstanceIndex inst_id, 84 bool created, 85 bool global_state_changed, 86 void* user_arg); 87 88 // Registers `cb` to be called every time a data source instance with `cat` 89 // enabled is created or destroyed. `user_arg` will be passed unaltered to `cb`. 90 // 91 // `cb` can be NULL to disable the callback. 92 PERFETTO_SDK_EXPORT void PerfettoTeCategoryImplSetCallback( 93 struct PerfettoTeCategoryImpl* cat, 94 PerfettoTeCategoryImplCallback cb, 95 void* user_arg); 96 97 // Returns the interning id (iid) associated with the registered category `cat`. 98 PERFETTO_SDK_EXPORT uint64_t 99 PerfettoTeCategoryImplGetIid(struct PerfettoTeCategoryImpl* cat); 100 101 // Destroys a previously registered category. The category cannot be used for 102 // tracing anymore after this. 103 PERFETTO_SDK_EXPORT void PerfettoTeCategoryImplDestroy( 104 struct PerfettoTeCategoryImpl*); 105 106 enum PerfettoTeTimestampType { 107 PERFETTO_TE_TIMESTAMP_TYPE_MONOTONIC = 3, 108 PERFETTO_TE_TIMESTAMP_TYPE_BOOT = 6, 109 PERFETTO_TE_TIMESTAMP_TYPE_INCREMENTAL = 64, 110 PERFETTO_TE_TIMESTAMP_TYPE_ABSOLUTE = 65, 111 }; 112 113 enum { 114 #ifdef __linux__ 115 PERFETTO_I_CLOCK_INCREMENTAL_UNDERNEATH = PERFETTO_TE_TIMESTAMP_TYPE_BOOT, 116 #else 117 PERFETTO_I_CLOCK_INCREMENTAL_UNDERNEATH = 118 PERFETTO_TE_TIMESTAMP_TYPE_MONOTONIC, 119 #endif 120 }; 121 122 struct PerfettoTeTimestamp { 123 // PerfettoTeTimestampType 124 uint32_t clock_id; 125 uint64_t value; 126 }; 127 128 // Returns the current timestamp. 129 PERFETTO_SDK_EXPORT struct PerfettoTeTimestamp PerfettoTeGetTimestamp(void); 130 131 struct PerfettoTeRegisteredTrackImpl { 132 void* descriptor; // Owned (malloc). 133 size_t descriptor_size; 134 uint64_t uuid; 135 }; 136 137 // The UUID of the process track for the current process. 138 extern PERFETTO_SDK_EXPORT uint64_t perfetto_te_process_track_uuid; 139 140 // The type of an event. 141 enum PerfettoTeType { 142 PERFETTO_TE_TYPE_SLICE_BEGIN = 1, 143 PERFETTO_TE_TYPE_SLICE_END = 2, 144 PERFETTO_TE_TYPE_INSTANT = 3, 145 PERFETTO_TE_TYPE_COUNTER = 4, 146 }; 147 148 #ifdef __cplusplus 149 } 150 #endif 151 152 #endif // INCLUDE_PERFETTO_PUBLIC_ABI_TRACK_EVENT_ABI_H_ 153