producer_port.proto

/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto2";
option optimize_for = LITE_RUNTIME;

import "perfetto/config/data_source_config.proto";
import "perfetto/config/data_source_descriptor.proto";
import "perfetto/common/commit_data_request.proto";

package perfetto.protos;

// IPC interface definition for the producer port of the tracing service.
service ProducerPort {
  // Called once only after establishing the connection with the Service.
  // The service replies sending the shared memory file descriptor in reply.
  rpc InitializeConnection(InitializeConnectionRequest)
      returns (InitializeConnectionResponse) {}

  // Advertises a data source.
  rpc RegisterDataSource(RegisterDataSourceRequest)
      returns (RegisterDataSourceResponse) {}

  // Unregisters a previously registered data source.
  rpc UnregisterDataSource(UnregisterDataSourceRequest)
      returns (UnregisterDataSourceResponse) {}

  // Sent by the client to request the service to:
  // 1) Move some chunks from the shmem buffer into the logging buffer.
  // 2) Patch the content of some chunks previously moved.
  rpc CommitData(protos.CommitDataRequest) returns (CommitDataResponse) {}

  // This is a backchannel to get asynchronous commands / notifications back
  // from the Service.
  rpc GetAsyncCommand(GetAsyncCommandRequest)
      returns (stream GetAsyncCommandResponse) {}
}

// Arguments for rpc InitializeConnection().
message InitializeConnectionRequest {
  // Defines the granularity of the tracing pages. Must be an integer multiple
  // of 4096. See tradeoff considerations in shared_memory_abi.h.
  optional uint32 shared_buffer_page_size_bytes = 1;

  // Optional. Provides a hint to the tracing service about the suggested size
  // of the shared memory buffer. The service is not required to respect this
  // and might return a smaller buffer.
  optional uint32 shared_memory_size_hint_bytes = 2;

  // Required to match the producer config set by the service to the correct
  // producer.
  optional string producer_name = 3;
}

message InitializeConnectionResponse {
  // This message provides the shared memory buffer FD (not a proto field).
}

// Arguments for rpc RegisterDataSource().

message RegisterDataSourceRequest {
  optional protos.DataSourceDescriptor data_source_descriptor = 1;
}

message RegisterDataSourceResponse {
  // Only set in case of errors, when |data_source_id| == 0.
  optional string error = 1;
};

// Arguments for rpc UnregisterDataSource().

message UnregisterDataSourceRequest {
  // The name of the data source to unregister, as previously passed in
  // |RegisterDataSourceRequest.name|.
  optional string data_source_name = 1;
}

message UnregisterDataSourceResponse {}

// Arguments for rpc CommitData().
// See commit_data_request.proto for CommitDataRequest. That has its own file
// because it is used also as input to generate the C++ classes in tracing/core
// via tools/gen_tracing_cpp_headers_from_protos.py.

message CommitDataResponse {}

// Arguments for rpc GetAsyncCommand().

message GetAsyncCommandRequest {}

message GetAsyncCommandResponse {
  message StartDataSource {
    optional uint64 new_instance_id = 1;
    optional protos.DataSourceConfig config = 2;
  }

  message StopDataSource { optional uint64 instance_id = 1; }

  // This message also transports the file descriptor for the shared memory
  // buffer.
  message SetupTracing { optional uint32 shared_buffer_page_size_kb = 1; }

  message Flush {
    // The instance id (i.e. StartDataSource.new_instance_id) of the data
    // sources to flush.
    repeated uint64 data_source_ids = 1;

    // A monotonic counter generated by the service. The producer is simply
    // expected to copy this value back into the CommitDataRequest, so the
    // service can tell when the data for this flush has been committed.
    optional uint64 request_id = 2;
  }

  oneof cmd {
    StartDataSource start_data_source = 1;
    StopDataSource stop_data_source = 2;
    SetupTracing setup_tracing = 3;
    // id == 4 was teardown_tracing, never implemented.
    Flush flush = 5;
  }
}