1 /* 2 * Copyright (C) 2022 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_TRACING_SESSION_ABI_H_ 18 #define INCLUDE_PERFETTO_PUBLIC_ABI_TRACING_SESSION_ABI_H_ 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 24 #include "perfetto/public/abi/export.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 // Opaque pointer to the internal representation of a tracing session. 31 struct PerfettoTracingSessionImpl; 32 33 PERFETTO_SDK_EXPORT struct PerfettoTracingSessionImpl* 34 PerfettoTracingSessionSystemCreate(void); 35 36 PERFETTO_SDK_EXPORT struct PerfettoTracingSessionImpl* 37 PerfettoTracingSessionInProcessCreate(void); 38 39 PERFETTO_SDK_EXPORT void PerfettoTracingSessionSetup( 40 struct PerfettoTracingSessionImpl*, 41 void* cfg_begin, 42 size_t cfg_len); 43 44 typedef void (*PerfettoTracingSessionStopCb)(struct PerfettoTracingSessionImpl*, 45 void* user_arg); 46 47 // Calls `*cb` with `user_arg` when the tracing session is stopped. 48 PERFETTO_SDK_EXPORT void PerfettoTracingSessionSetStopCb( 49 struct PerfettoTracingSessionImpl*, 50 PerfettoTracingSessionStopCb cb, 51 void* user_arg); 52 53 PERFETTO_SDK_EXPORT void PerfettoTracingSessionStartAsync( 54 struct PerfettoTracingSessionImpl*); 55 56 PERFETTO_SDK_EXPORT void PerfettoTracingSessionStartBlocking( 57 struct PerfettoTracingSessionImpl*); 58 59 PERFETTO_SDK_EXPORT void PerfettoTracingSessionStopAsync( 60 struct PerfettoTracingSessionImpl*); 61 62 PERFETTO_SDK_EXPORT void PerfettoTracingSessionStopBlocking( 63 struct PerfettoTracingSessionImpl*); 64 65 // Called back to signal that a previous flush request has completed. `success` 66 // is true if every data source has acknowledged the flush request, false if the 67 // timeout has expired or there was an error. 68 typedef void (*PerfettoTracingSessionFlushCb)( 69 struct PerfettoTracingSessionImpl*, 70 bool success, 71 void* user_arg); 72 73 // Issues a flush request, asking all data sources to ack the request, within 74 // the specified timeout. A "flush" is a fence to ensure visibility of data in 75 // the async tracing pipeline. It guarantees that all data written before the 76 // call will be visible in the trace buffer and hence by the 77 // PerfettoTracingSessionReadTraceBlocking() function. Returns immediately and 78 // invokes a callback when the flush request is complete. 79 // Args: 80 // `cb`: will be invoked on an internal perfetto thread when all data 81 // sources have acked, or the timeout is reached. 82 // `user_arg`: passed as is to `cb`. 83 // `timeout_ms`: how much time the service will wait for data source acks. If 84 // 0, the global timeout specified in the TraceConfig (flush_timeout_ms) 85 // will be used. If flush_timeout_ms is also unspecified, a default value 86 // of 5s will be used. 87 PERFETTO_SDK_EXPORT void PerfettoTracingSessionFlushAsync( 88 struct PerfettoTracingSessionImpl*, 89 uint32_t timeout_ms, 90 PerfettoTracingSessionFlushCb cb, 91 void* user_arg); 92 93 // Like PerfettoTracingSessionFlushAsync(), but blocks until the flush is 94 // complete (i.e. every data source has acknowledged or the timeout has 95 // expired). 96 PERFETTO_SDK_EXPORT bool PerfettoTracingSessionFlushBlocking( 97 struct PerfettoTracingSessionImpl*, 98 uint32_t timeout_ms); 99 100 // Called back to read pieces of tracing data. `data` points to a chunk of trace 101 // data, `size` bytes long. `has_more` is true if there is more tracing data and 102 // the callback will be invoked again. 103 typedef void (*PerfettoTracingSessionReadCb)(struct PerfettoTracingSessionImpl*, 104 const void* data, 105 size_t size, 106 bool has_more, 107 void* user_arg); 108 109 // Repeatedly calls cb with data from the tracing session. `user_arg` is passed 110 // as is to the callback. 111 PERFETTO_SDK_EXPORT void PerfettoTracingSessionReadTraceBlocking( 112 struct PerfettoTracingSessionImpl*, 113 PerfettoTracingSessionReadCb cb, 114 void* user_arg); 115 116 PERFETTO_SDK_EXPORT void PerfettoTracingSessionDestroy( 117 struct PerfettoTracingSessionImpl*); 118 119 #ifdef __cplusplus 120 } 121 #endif 122 123 #endif // INCLUDE_PERFETTO_PUBLIC_ABI_TRACING_SESSION_ABI_H_ 124