1 /* 2 * Copyright (C) 2017 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_TRACING_CORE_SERVICE_H_ 18 #define INCLUDE_PERFETTO_TRACING_CORE_SERVICE_H_ 19 20 #include <stdint.h> 21 22 #include <functional> 23 #include <memory> 24 #include <vector> 25 26 #include "perfetto/base/export.h" 27 #include "perfetto/base/scoped_file.h" 28 #include "perfetto/tracing/core/basic_types.h" 29 #include "perfetto/tracing/core/shared_memory.h" 30 31 namespace perfetto { 32 33 namespace base { 34 class TaskRunner; 35 } // namespace base 36 37 class CommitDataRequest; 38 class Consumer; 39 class DataSourceDescriptor; 40 class Producer; 41 class TraceConfig; 42 class TraceWriter; 43 44 // TODO: for the moment this assumes that all the calls hapen on the same 45 // thread/sequence. Not sure this will be the case long term in Chrome. 46 47 // The public API of the tracing Service business logic. 48 // 49 // Exposed to: 50 // 1. The transport layer (e.g., src/unix_rpc/unix_service_host.cc), 51 // which forwards commands received from a remote producer or consumer to 52 // the actual service implementation. 53 // 2. Tests. 54 // 55 // Subclassed by: 56 // The service business logic in src/core/service_impl.cc. 57 class PERFETTO_EXPORT Service { 58 public: 59 // The API for the Producer port of the Service. 60 // Subclassed by: 61 // 1. The service_impl.cc business logic when returning it in response to 62 // the ConnectProducer() method. 63 // 2. The transport layer (e.g., src/ipc) when the producer and 64 // the service don't talk locally but via some IPC mechanism. 65 class ProducerEndpoint { 66 public: 67 virtual ~ProducerEndpoint(); 68 69 // Called by the Producer to (un)register data sources. Data sources are 70 // identified by their name (i.e. DataSourceDescriptor.name) 71 virtual void RegisterDataSource(const DataSourceDescriptor&) = 0; 72 virtual void UnregisterDataSource(const std::string& name) = 0; 73 74 // Called by the Producer to signal that some pages in the shared memory 75 // buffer (shared between Service and Producer) have changed. 76 using CommitDataCallback = std::function<void()>; 77 virtual void CommitData(const CommitDataRequest&, 78 CommitDataCallback callback = {}) = 0; 79 80 virtual SharedMemory* shared_memory() const = 0; 81 82 // Size of shared memory buffer pages. It's always a multiple of 4K. 83 // See shared_memory_abi.h 84 virtual size_t shared_buffer_page_size_kb() const = 0; 85 86 // Creates a trace writer, which allows to create events, handling the 87 // underying shared memory buffer and signalling to the Service. This method 88 // is thread-safe but the returned object is not. A TraceWriter should be 89 // used only from a single thread, or the caller has to handle sequencing 90 // via a mutex or equivalent. 91 // Args: 92 // |target_buffer| is the target buffer ID where the data produced by the 93 // writer should be stored by the tracing service. This value is passed 94 // upon creation of the data source (CreateDataSourceInstance()) in the 95 // DataSourceConfig.target_buffer(). 96 virtual std::unique_ptr<TraceWriter> CreateTraceWriter( 97 BufferID target_buffer) = 0; 98 99 // Called in response to a Producer::Flush(request_id) call after all data 100 // for the flush request has been committed. 101 virtual void NotifyFlushComplete(FlushRequestID) = 0; 102 }; // class ProducerEndpoint. 103 104 // The API for the Consumer port of the Service. 105 // Subclassed by: 106 // 1. The service_impl.cc business logic when returning it in response to 107 // the ConnectConsumer() method. 108 // 2. The transport layer (e.g., src/ipc) when the consumer and 109 // the service don't talk locally but via some IPC mechanism. 110 class ConsumerEndpoint { 111 public: 112 virtual ~ConsumerEndpoint(); 113 114 // Enables tracing with the given TraceConfig. The ScopedFile argument is 115 // used only when TraceConfig.write_into_file == true. 116 virtual void EnableTracing(const TraceConfig&, 117 base::ScopedFile = base::ScopedFile()) = 0; 118 virtual void DisableTracing() = 0; 119 120 // Requests all data sources to flush their data immediately and invokes the 121 // passed callback once all of them have acked the flush (in which case 122 // the callback argument |success| will be true) or |timeout_ms| are elapsed 123 // (in which case |success| will be false). 124 using FlushCallback = std::function<void(bool /*success*/)>; 125 virtual void Flush(uint32_t timeout_ms, FlushCallback) = 0; 126 127 // Tracing data will be delivered invoking Consumer::OnTraceData(). 128 virtual void ReadBuffers() = 0; 129 130 virtual void FreeBuffers() = 0; 131 }; // class ConsumerEndpoint. 132 133 // Implemented in src/core/service_impl.cc . 134 static std::unique_ptr<Service> CreateInstance( 135 std::unique_ptr<SharedMemory::Factory>, 136 base::TaskRunner*); 137 138 virtual ~Service(); 139 140 // Connects a Producer instance and obtains a ProducerEndpoint, which is 141 // essentially a 1:1 channel between one Producer and the Service. 142 // The caller has to guarantee that the passed Producer will be alive as long 143 // as the returned ProducerEndpoint is alive. 144 // To disconnect just destroy the returned ProducerEndpoint object. It is safe 145 // to destroy the Producer once the Producer::OnDisconnect() has been invoked. 146 // |uid| is the trusted user id of the producer process, used by the consumers 147 // for validating the origin of trace data. 148 // |shared_memory_size_hint_bytes| is an optional hint on the size of the 149 // shared memory buffer. The service can ignore the hint (e.g., if the hint 150 // is unreasonably large). 151 // Can return null in the unlikely event that service has too many producers 152 // connected. 153 virtual std::unique_ptr<ProducerEndpoint> ConnectProducer( 154 Producer*, 155 uid_t uid, 156 const std::string& name, 157 size_t shared_memory_size_hint_bytes = 0) = 0; 158 159 // Coonects a Consumer instance and obtains a ConsumerEndpoint, which is 160 // essentially a 1:1 channel between one Consumer and the Service. 161 // The caller has to guarantee that the passed Consumer will be alive as long 162 // as the returned ConsumerEndpoint is alive. 163 // To disconnect just destroy the returned ConsumerEndpoint object. It is safe 164 // to destroy the Consumer once the Consumer::OnDisconnect() has been invoked. 165 virtual std::unique_ptr<ConsumerEndpoint> ConnectConsumer(Consumer*) = 0; 166 }; 167 168 } // namespace perfetto 169 170 #endif // INCLUDE_PERFETTO_TRACING_CORE_SERVICE_H_ 171