service.proto

// Copyright (C) 2017 Google Inc.
//
// 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 = "proto3";

import "core/image/image.proto";
import "core/log/log_pb/log.proto";
import "core/os/device/device.proto";
import "core/os/device/gpu_counter_descriptor.proto";
import "gapis/api/service.proto";
import "gapis/perfetto/service/perfetto.proto";
import "gapis/service/box/box.proto";
import "gapis/service/memory_box/box.proto";
import "gapis/service/path/path.proto";
import "gapis/service/types/types.proto";
import "gapis/service/severity/severity.proto";
import "gapis/stringtable/stringtable.proto";
import "protos/perfetto/config/trace_config.proto";

package service;
option java_package = "com.google.gapid.proto.service";
option java_outer_classname = "Service";
option go_package = "github.com/google/gapid/gapis/service";

/******************************************************************************/
/****                         Service Objects                              ****/
/******************************************************************************/

enum TraceType {
  // A Frame Profiler Vulkan trace.
  Graphics = 0;
  // A System Profiler Perfetto trace.
  Perfetto = 1;
  // A Frame Profiler GLES on ANGLE trace. Note that when opening a trace,
  // GAPIS currently doesn't distinguish between ANGLE and Vulkan and will not
  // report this type (i.e. the Capture message's type field).
  ANGLE = 2;
  // A System Profiler Fuchsia trace.  Note that when opening a trace,
  // GAPIS currently doesn't distinguish between Fuchsia and Perfetto and will
  // not report this type (i.e. the Capture message's type field).
  Fuchsia = 3;
}

message Error {
  oneof err {
    ErrInternal err_internal = 1;
    ErrDataUnavailable err_data_unavailable = 2;
    ErrInvalidPath err_invalid_path = 3;
    ErrInvalidArgument err_invalid_argument = 4;
    ErrPathNotFollowable err_path_not_followable = 5;
    ErrUnsupportedVersion err_unsupported_version = 6;
  }
}

// ErrInternal is the error raised when an internal server error has occurred.
message ErrInternal {
  string message = 1;
}

// ErrDataUnavailable is the error raised when the requested data is
// unavailable. For instance: the error raised when a framebuffer is
// requested at a point in the capture where none is bound.
message ErrDataUnavailable {
  // The reason the data is unavailable.
  stringtable.Msg reason = 1;
  // If true, then making the same request at a later time may result in data.
  bool transient = 2;
}

// ErrInvalidPath is the error raised when the specified path is invalid.
// This type of error is permanent.
message ErrInvalidPath {
  // The description of what's invalid.
  stringtable.Msg reason = 1;
  // The part of the path that was invalid.
  path.Any path = 2;
}

// ErrInvalidArgument is the error raised when one of the parameters to an RPC
// call is invalid.
// This type of error is permanent.
message ErrInvalidArgument {
  // The description of what's invalid.
  stringtable.Msg reason = 1;
}

// ErrPathNotFollowable is the error raised when attempting to follow a path
// that cannot be followed.
message ErrPathNotFollowable {
  path.Any path = 1;
}

// ErrUnsupportedVersion is the error raised attempting to load data with an
// unsupported version.
message ErrUnsupportedVersion {
  // The reason the data is unsupported.
  stringtable.Msg reason = 1;
  // If true, the client should prompt the user to update GAPID.
  bool suggest_update = 2;
}

message Value {
  oneof val {
    Capture capture = 1;
    CommandTree command_tree = 2;
    CommandTreeNode command_tree_node = 3;
    Commands commands = 4;
    ConstantSet constant_set = 7;
    Memory memory = 10;
    Messages messages = 11;
    path.Any path = 12;
    Report report = 13;
    Resources resources = 14;
    StateTree state_tree = 15;
    StateTreeNode state_tree_node = 16;
    Stats stats = 17;
    Thread thread = 18;
    Threads threads = 19;

    device.Instance device = 20;
    DeviceTraceConfiguration traceConfig = 21;

    api.Command command = 30;
    api.ResourceData resource_data = 31;
    api.Mesh mesh = 32;
    api.Metrics metrics = 33;
    MultiResourceData multi_resource_data = 34;
    MultiResourceThumbnail multi_resource_thumbnail = 38;
    FramebufferAttachments framebuffer_attachments = 35;
    FramebufferAttachment framebuffer_attachment = 36;
    api.Framegraph framegraph = 37;
    api.ResourceExtras resource_extras = 39;

    image.Info image_info = 40;

    box.Value box = 50;

    types.Type type = 60;

    memory_box.Value memory_box = 70;
  }
}

// Capture describes single capture file held by the server.
message Capture {
  // The type of this capture. Note that this will not distinguish Vulkan
  // traces from ANGLE traces and report both as "Graphics".
  TraceType type = 7;
  // Name given to the capture. e.g. "KittyWorld"
  string name = 1;
  // Information about the device used to create the capture.
  device.Instance device = 2;
  // Information about the abi used by the traced process.
  device.ABI ABI = 3;
  // Number of commands in this capture.
  uint64 num_commands = 4;
  // List of graphics APIs used by this capture.
  repeated path.API APIs = 5;
  // List of all the memory observations made by the application.
  repeated MemoryRange observations = 6;
}

// CommandTree represents a command tree hierarchy.
message CommandTree {
  path.CommandTreeNode root = 1;
}

// CommandTreeNode is a node in a command tree hierarchy.
message CommandTreeNode {
  // The path to the command that best represents this group. For example the
  // the last draw call in a frame.
  path.Command representation = 1;
  // Number of child nodes.
  uint64 num_children = 2;
  // Group name if this node represents a group of commands.
  string group = 3;
  // Path to the command range represented by this node.
  path.Commands commands = 4;
  // Number of commands encapsulated by this group.
  uint64 num_commands = 5;
  // these commands can be disabled for experiments.
  repeated path.Command experimental_commands = 6;
  // For group nodes, whether it should be expanded by default in the UI.
  bool expand_by_default = 7;
}

message Commands {
  repeated path.Command list = 1;
}

// ConstantSet is a collection on name-value pairs to be used as an enumeration
// of possible values for a field or parameter.
message ConstantSet {
  repeated Constant constants = 1;
  bool is_bitfield = 2;
}

// Constant is a name-value pair that is owned by a ConstantSet.
message Constant {
  // The name of the constant.
  string name = 1;
  // The value of the constant.
  uint64 value = 2;
}

// Memory describes the state of a range of memory at a specific point in
// the command stream.
message Memory {
  // The memory values for the span.
  bytes data = 1;
  // The data-relative ranges that were read-from at the specified command.
  repeated MemoryRange reads = 2;
  // The data-relative ranges that were written-to at the specified command.
  repeated MemoryRange writes = 3;
  // The data-relative ranges that have been observed.
  repeated MemoryRange observed = 4;
  // All types of the reads on this command
  repeated TypedMemoryRange typed_ranges = 5;
}

// MemoryRange represents a contiguous range of memory.
message MemoryRange {
  // The address of the first byte in the memory range.
  uint64 base = 1;
  // The number of bytes that are in the memory range.
  uint64 size = 2;
}

message TypedMemoryRange {
  // The type of the memory observations
  path.Type type = 1;
  MemoryRange range = 2;
  // The root of the memory observation
  uint64 root = 3;
  // The structured value of the typed memory observation.
  memory_box.Value value = 4;
  // Whether this is a write (true) or read (false) observation.
  bool write = 5;
}

message Messages {
  repeated Message list = 1;
}

message Message {
  uint64 timestamp = 1;
  string message = 2;
}

// Report describes all warnings and errors found by a capture.
message Report {
  // Report items for this report.
  repeated ReportItem items = 1;
  // Report groups for this report.
  repeated ReportGroup groups = 2;
  // Array of strings for messages.
  repeated string strings = 3;
  // Array of values for messages.
  repeated stringtable.Value values = 4;
}

// ReportItem represents an entry in a report.
message ReportItem {
  // The severity of the report item.
  severity.Severity severity = 1;
  // The message for the item.
  MsgRef message = 2;
  // The path to the command that reported the issue.
  path.Command command = 3;
  // The references to tags associated with this item.
  repeated MsgRef tags = 4;
}

// MsgRef references a message in a Report.
message MsgRef {
  // The index in Report.strings of the message identifier.
  uint32 identifier = 1;
  // The indexed arguments.
  repeated MsgRefArgument arguments = 2;
}

// MsgRefArgument is an argument formed from two indices into the report.
message MsgRefArgument {
  // The index in Report.strings of the argument identifier.
  uint32 key = 1;
  // The index in Report.values of the argument value.
  uint32 value = 2;
}

// ReportGroup represents a group of ReportItem which have the same tag.
message ReportGroup {
  // The reference to Msg which describes this group.
  MsgRef name = 1;
  // The indices of report items which belong to this group.
  repeated uint32 items = 2;
  // The union of all Items tags. Currently isn't supported and is nil. TODO:
  // Add filtering support for the entire group.
  repeated MsgRef tags = 3;
}

// Resources contains the full list of resources used by a capture.
message Resources {
  repeated ResourcesByType types = 1;
  map<string, path.ResourceType> resourcesToTypes = 2;
}

// ResourcesByType contains all resources of a specific type.
message ResourcesByType {
  path.ResourceType type = 1;
  repeated Resource resources = 2;
}

// Resource describes a single resource.
message Resource {
  // The resource's unique identifier.
  path.ID ID = 1;
  // The resource identifier used for display.
  string handle = 2;
  // The resource label.
  string label = 3;
  // An int used to sort the resources for presentation.
  uint64 order = 4;
  // The list of command indices where the resource was used.
  repeated path.Command accesses = 5;
  // The command at which this resource was deleted/destroyed.
  path.Command deleted = 6;
  // The command at which this resource was created.
  path.Command created = 7;
  // The type of the resource
  path.ResourceType type = 9;
}

// StateTree represents a state tree hierarchy.
message StateTree {
  path.StateTreeNode root = 1;
}

// StateTreeNode is a node in a state tree hierarchy.
message StateTreeNode {
  // Number of child nodes.
  uint64 num_children = 1;
  // The name of the field or group.
  string name = 2;
  // An optional additional label for this group, typically the debug name.
  string label = 7;
  // The path to the value.
  path.Any value_path = 3;
  // The 'preview' value of the field.
  // For simple POD types, this may be the actual value, in which case
  // preview_is_value will be true.
  // For more complex types, this may be a string representation of the value.
  // Long arrays may be truncated.
  box.Value preview = 4;
  // If true then preview is the complete data of the node. In this situation
  // preview is equal to calling Get() on the path.
  bool preview_is_value = 5;
  // The possible alternative named values for the field.
  path.ConstantSet constants = 6;
}

// Stats stores the statistics for a capture
message Stats {
  // The draw calls per frame, if requested in the path.Stats.
  repeated uint64 draw_calls = 1;
  uint64 trace_start = 2;
}

// Thread represents a single thread in the capture.
message Thread {
  string name = 1;
}

message Threads {
  repeated path.Thread list = 1;
}

message DeviceTraceConfiguration {
  // Is the path to the app on this device server-local.
  bool server_local_path = 1;
  // Does it make sense to specify a CWD for the application.
  bool can_specify_cwd = 2;
  // Can we upload an application to trace.
  bool can_upload_application = 3;
  // Can we specify an environment.
  bool can_specify_env = 4;
  // The default URI that should be used for looking at packages.
  string preferred_root_uri = 5;
  // Type and API-specific capabilities.
  repeated TraceTypeCapabilities types = 6;
  // Is there a cache that can be cleared.
  bool has_cache = 7;
}

message TraceTypeCapabilities {
  // The type of trace this describes.
  TraceType type = 5;
  reserved 1;
  reserved 2;
  reserved 3;
  // Whether unsupported extensions can be enabled.
  bool can_enable_unsupported_extensions = 4;
  // Does this trace require starting an application.
  bool requires_application = 6;
  // Can select a specific process name
  bool can_select_process_name = 7;
}

// MultiResourceData represents the state of resources at a single point in a
// capture.
message MultiResourceData {
  message ResourceOrError {
    oneof val {
      api.ResourceData resource = 1;
      Error error = 2;
    }
  }
  map<string, ResourceOrError> resources = 1;
}

// MultiResourceThumbnail represents the thumbnail images of multiple resources.
message MultiResourceThumbnail {
  message ThumbnailOrError {
    oneof val {
      image.Info image = 1;
      Error error = 2;
    }
  }
  map<string, ThumbnailOrError> images = 1;
}

message FramebufferAttachments {
  repeated FramebufferAttachment attachments = 1;
}

message FramebufferAttachment {
  uint32 index = 1;
  api.FramebufferAttachmentType type = 2;
  path.ImageInfo image_info = 3;
  string label = 4;
}

message VulkanHandleMappingItem {
  string handle_type = 1;
  uint64 trace_value = 2;
  uint64 replay_value = 3;
}

/******************************************************************************/
/****                         Service Definition                           ****/
/******************************************************************************/

// Gapid is the RPC service to the GAPIS server.
service Gapid {
  // Ping is a no-op function that returns immediately.
  // It can be used to measure connection latency or to keep the
  // process alive if started with the "idle-timeout" command line flag.
  rpc Ping(PingRequest) returns (PingResponse) {}

  // GetServerInfo returns information about the running server.
  rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse) {}

  // CheckForUpdates checks for a new build of GAPID on the hosting server.
  // Care should be taken to call this infrequently to avoid reaching the
  // server's maximum unauthenticated request limits.
  rpc CheckForUpdates(CheckForUpdatesRequest)
      returns (CheckForUpdatesResponse) {}

  // Get resolves and returns the object, value or memory at the path p.
  rpc Get(GetRequest) returns (GetResponse) {}

  // Set creates a copy of the capture referenced by p, but with the object,
  // value or memory at p replaced with v. The path returned is identical to p,
  // but with the base changed to refer to the new capture.
  rpc Set(SetRequest) returns (SetResponse) {}

  // Delete creates a copy of the capture referenced by p, but without the
  // object, value or memory at p. The path returned is identical to p, but with
  // the base changed to refer to the new capture.
  rpc Delete(DeleteRequest) returns (DeleteResponse) {}

  // Follow returns the path to the object that the value at p links to.
  // If the value at p does not link to anything then nil is returned.
  rpc Follow(FollowRequest) returns (FollowResponse) {}

  // GetAvailableStringTables returns list of available string table
  // descriptions.
  rpc GetAvailableStringTables(GetAvailableStringTablesRequest)
      returns (GetAvailableStringTablesResponse) {}

  // GetStringTable returns the requested string table.
  rpc GetStringTable(GetStringTableRequest) returns (GetStringTableResponse) {}

  // Import imports capture data emitted by the graphics spy, returning the new
  // capture identifier.
  rpc ImportCapture(ImportCaptureRequest) returns (ImportCaptureResponse) {}

  // ExportCapture returns a capture's data that can be consumed by
  // ImportCapture or LoadCapture.
  rpc ExportCapture(ExportCaptureRequest) returns (ExportCaptureResponse) {}

  // LoadCapture imports capture data from a local file, returning the new
  // capture identifier.
  rpc LoadCapture(LoadCaptureRequest) returns (LoadCaptureResponse) {}

  // SaveCapture saves capture to a file.
  rpc SaveCapture(SaveCaptureRequest) returns (SaveCaptureResponse) {}

  // ExportReplay saves replay commands and assets to file.
  rpc ExportReplay(ExportReplayRequest) returns (ExportReplayResponse) {}

  // DCECapture returns a new capture containing only the requested commands
  // and their dependencies.
  rpc DCECapture(DCECaptureRequest) returns (DCECaptureResponse) {}

  // GetGraphVisualization returns a representation of the dependency graph of
  // the requested capture, in the requested format.
  rpc GetGraphVisualization(GraphVisualizationRequest)
      returns (GraphVisualizationResponse) {}
  // GetDevices returns the full list of replay devices avaliable to the server.
  // These include local replay devices and any connected Android devices.
  // This list may change over time, as devices are connected and disconnected.
  // The primary device (usually host) will be first.
  rpc GetDevices(GetDevicesRequest) returns (GetDevicesResponse) {}

  // GetDevicesForReplay returns the list of replay devices avaliable to the
  // server that are capable of replaying the given capture.
  // These include local replay devices and any connected Android devices.
  // This list may change over time, as devices are connected and disconnected.
  // If both connected Android and Local replay devices are found,
  // the local Android devices will be returned first.
  rpc GetDevicesForReplay(GetDevicesForReplayRequest)
      returns (GetDevicesForReplayResponse) {}

  // ValidateDevice checks the GPU profiling capabilities of the requested
  // device
  rpc ValidateDevice(ValidateDeviceRequest) returns (ValidateDeviceResponse) {}

  // InstallApp installs an application to a device.
  rpc InstallApp(InstallAppRequest) returns (InstallAppResponse) {}

  // GetLogStream calls the handler with each log record raised until the
  // context is cancelled.
  rpc GetLogStream(GetLogStreamRequest) returns (stream log.Message) {}

  // Find searches for data, streaming the results.
  rpc Find(FindRequest) returns (stream FindResponse) {}

  // ClientEvent records a client event action, used for analytics.
  // If the user has not opted-in for analytics then this call does nothing.
  rpc ClientEvent(ClientEventRequest) returns (ClientEventResponse) {}

  // FindTraceTargets returns trace targets matching the given search
  // parameters.
  rpc FindTraceTargets(FindTraceTargetsRequest)
      returns (FindTraceTargetsResponse) {}

  // TraceTargetTreeNode returns information about the trace target
  rpc TraceTargetTreeNode(TraceTargetTreeNodeRequest)
      returns (TraceTargetTreeNodeResponse) {}

  // Trace returns a steam that can be used to start and stop
  // a trace
  rpc Trace(stream TraceRequest) returns (stream TraceResponse) {}

  // Updates environment settings.
  rpc UpdateSettings(UpdateSettingsRequest) returns (UpdateSettingsResponse) {}

  // Status returns a stream of Status events that are occuring on the server
  rpc Status(ServerStatusRequest) returns (stream ServerStatusResponse) {}

  // Runs a Perfetto Query. This is done separatly from .Get, because the query
  // results should not be cached, as they can change due to 'update' queries.
  rpc PerfettoQuery(PerfettoQueryRequest) returns (PerfettoQueryResponse) {}

  // GpuProfile starts a perfetto trace of a gfxtrace
  rpc GpuProfile(GpuProfileRequest) returns (GpuProfileResponse) {}

  // SplitCapture creates a new capture containing the requested subset of
  // commands.
  rpc SplitCapture(SplitCaptureRequest) returns (SplitCaptureResponse) {}

  // TrimCaptureInitialState returns a new capture with an initial state trimmed
  // from resources not needed by the capture commands.
  rpc TrimCaptureInitialState(TrimCaptureInitialStateRequest)
      returns (TrimCaptureInitialStateResponse) {}

  ///////////////////////////////////////////////////////////////
  // Below are debugging APIs which may be removed in the future.
  ///////////////////////////////////////////////////////////////

  // Profile starts self-profiling the server.
  rpc Profile(stream ProfileRequest) returns (stream ProfileResponse) {}

  // GetPerformanceCounters returns the values of all global counters as
  // a JSON blob.
  rpc GetPerformanceCounters(GetPerformanceCountersRequest)
      returns (GetPerformanceCountersResponse) {}

  // GetProfile returns the pprof profile with the given name.
  rpc GetProfile(GetProfileRequest) returns (GetProfileResponse) {}

  // GetTimestamps returns a stream contains the timestamps of the begin
  // and end of execution of a command buffer.
  rpc GetTimestamps(GetTimestampsRequest)
      returns (stream GetTimestampsResponse) {}
}

/******************************************************************************/
/****                     Request/Response Messages                        ****/
/******************************************************************************/

message CheckForUpdatesRequest {
  bool include_dev_releases = 1;
}

message CheckForUpdatesResponse {
  oneof res {
    Releases releases = 1;
    Error error = 2;
  }
}

message Releases {
  message AGIRelease {
    string name = 1;
    uint32 version_major = 2;
    uint32 version_minor = 3;
    uint32 version_point = 4;
    uint32 version_dev = 5;
    string browser_url = 6;
  }

  message ANGLERelease {
    uint32 version = 1;
    string arm_32 = 2;
    string arm_64 = 3;
    string x86 = 4;
  }

  AGIRelease AGI = 1;
  ANGLERelease ANGLE = 2;
}

message ClientEventRequest {
  oneof kind {
    ClientInteraction interaction = 1;
  }
}

message ClientEventResponse {}

message ClientInteraction {
  string view = 1;
  ClientAction action = 2;
}

enum ClientAction {
  Undefined = 0;
  Color0 = 1;
  Color1 = 2;
  Color2 = 3;
  Color3 = 4;
  Copy = 5;
  CullOn = 6;
  CullOff = 7;
  Depth = 8;
  Disable = 9;
  Edit = 10;
  Enable = 11;
  Faceted = 12;
  Flat = 13;
  Flip = 14;
  GotoReference = 15;
  HideHistogram = 16;
  Move = 17;
  Normals = 18;
  Open = 19;
  OpenRecent = 20;
  OverlayWireframe = 21;
  Points = 22;
  Save = 23;
  Search = 24;
  Select = 25;
  SelectObservation = 26;
  SelectProgram = 27;
  SelectShader = 28;
  Shaded = 29;
  Show = 30;
  ShowActivityPicker = 31;
  ShowBackground = 32;
  ShowColorChannels = 33;
  ShowEdit = 34;
  ShowError = 35;
  ShowHelp = 36;
  ShowHistogram = 37;
  ShowLogDir = 38;
  ShowReferences = 39;
  ShowTargets = 40;
  Smooth = 41;
  Triangles = 42;
  WindingCCW = 43;
  WindingCW = 44;
  Wireframe = 45;
  YUp = 46;
  ZUp = 47;
  YDown = 48;
  ZDown = 49;
  ZoomActual = 50;
  ZoomFit = 51;
  ZoomIn = 52;
  ZoomOut = 53;
  VertexSemantics = 54;
  Overdraw = 55;
  Pin = 56;
  ClosePinned = 57;
  ShowExperiments = 58;
  UpdateExperiments = 59;
  DisableCommand = 60;
  EnableCommand = 61;
}

message DCECaptureRequest {
  path.Capture capture = 1;
  repeated path.Command commands = 2;
}

message DCECaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message DeleteRequest {
  path.Any path = 1;
  // Config to use when resolving paths.
  path.ResolveConfig config = 2;
}

message DeleteResponse {
  oneof res {
    path.Any path = 1;
    Error error = 2;
  }
}

message ExportCaptureRequest {
  path.Capture capture = 1;
}

message ExportCaptureResponse {
  oneof res {
    bytes data = 1;
    Error error = 2;
  }
}

message ExportReplayRequest {
  path.Capture capture = 1;
  string path = 2;
  path.Device device = 3;
  ExportReplayOptions options = 4;
}

message ExportReplayResponse {
  Error error = 1;
}

message ExportReplayOptions {
  path.Report report = 1;
  repeated path.FramebufferAttachment framebuffer_attachments = 2;
  GetTimestampsRequest get_timestamps_request = 3;
  bool display_to_surface = 4;
  int32 LoopCount = 5;
}

message FindRequest {
  // If true then searching will begin at from and move backwards.
  bool backwards = 1;
  // Maximum number of results to return. 0 means unlimited.
  uint32 max_items = 2;
  // The searching point.
  oneof from {
    path.CommandTreeNode command_tree_node = 5;
    path.StateTreeNode state_tree_node = 6;
  }
  // The text to search for.
  string text = 3;
  // If true then text should be treated as a regular expression.
  bool is_regex = 4;
  // If true the search should be case sensitive.
  bool is_case_sensitive = 7;
  // If true, the search will wrap.
  bool wrap = 8;
  // Config to use when resolving paths.
  path.ResolveConfig config = 9;
}

message FindResponse {
  oneof result {
    path.CommandTreeNode command_tree_node = 1;
    path.StateTreeNode state_tree_node = 2;
  }
}

message FindTraceTargetsRequest {
  path.Device device = 1;
  string uri = 2;
}

message FindTraceTargetsResponse {
  oneof val {
    TraceTargetTreeNodes nodes = 1;
    Error error = 2;
  }
}

message TraceTargetTreeNodes {
  repeated TraceTargetTreeNode nodes = 1;
}

message FollowRequest {
  path.Any path = 1;
  // Config to use when resolving paths.
  path.ResolveConfig config = 2;
}

message FollowResponse {
  oneof res {
    path.Any path = 1;
    Error error = 2;
  }
}

message GetRequest {
  path.Any path = 1;
  // Config to use when resolving paths.
  path.ResolveConfig config = 2;
}

message GetResponse {
  oneof res {
    Value value = 1;
    Error error = 2;
  }
}

message GetAvailableStringTablesRequest {}

message GetAvailableStringTablesResponse {
  oneof res {
    StringTableInfos tables = 1;
    Error error = 2;
  }
}

message StringTableInfos {
  repeated stringtable.Info list = 1;
}

message GetDevicesRequest {}

message GetDevicesResponse {
  oneof res {
    Devices devices = 1;
    Error error = 2;
  }
}

message GetDevicesForReplayRequest {
  path.Capture capture = 1;
}

message GetDevicesForReplayResponse {
  oneof res {
    Devices devices = 1;
    Error error = 2;
  }
}

message Devices {
  repeated path.Device list = 1;
  // compatibilities and reasons are set only in GetDevicesForReplay responses
  repeated bool compatibilities = 2;
  repeated stringtable.Msg reasons = 3;
}

message GetLogStreamRequest {}

// There is no GetLogStreamResponse.

message GetPerformanceCountersRequest {}

message GetPerformanceCountersResponse {
  oneof res {
    string data = 1;
    Error error = 2;
  }
}

message GetProfileRequest {
  string name = 1;
  int32 debug = 2;
}

message GetProfileResponse {
  oneof res {
    bytes data = 1;
    Error error = 2;
  }
}

message GetServerInfoRequest {}

message GetServerInfoResponse {
  oneof res {
    ServerInfo info = 1;
    Error error = 2;
  }
}

message ServerInfo {
  string name = 1;
  uint32 version_major = 2;
  uint32 version_minor = 3;
  uint32 version_point = 4;
  // A string list of features supported by the server. This feature list can be
  // used by the client to determine what new RPCs can be called.
  repeated string features = 5;
  path.Device server_local_device = 6;
}

message GetStringTableRequest {
  stringtable.Info table = 1;
}

message GetStringTableResponse {
  oneof res {
    stringtable.StringTable table = 1;
    Error error = 2;
  }
}

// GetTimestampsRequest is the request send to server to get the timestamps for
// the commands in the capture.
message GetTimestampsRequest {
  path.Capture capture = 1;
  path.Device device = 2;
  int32 LoopCount = 3;
}

// GetTimestampsResponse is the response message server sends back which
// contains the time duratoins for the commands when replay the trace.
message GetTimestampsResponse {
  oneof res {
    Timestamps timestamps = 1;
    Error error = 2;
  }
}

// Timestamps describes the durations of commands execution, each of which
// is specified in a TimestampsItem message.
message Timestamps {
  repeated TimestampsItem timestamps = 1;
}

// TimestampsItem represents one entry in a Timestamps report.
// It describes the duratoin of execution time between the two commands
// specified by "begin" and "end" fields.
message TimestampsItem {
  // The path of the command which begins the time measurement.
  path.Command begin = 1;
  // The path of the command which ends the time measurement.
  path.Command end = 2;
  // The duration in nanoseconds between the two commands specified.
  uint64 time_in_nanoseconds = 3;
}

message GpuProfileRequest {
  path.Capture capture = 1;
  path.Device device = 2;
  ProfileExperiments experiments = 3;
  int32 loopCount = 4;
}

message GpuProfileResponse {
  oneof res {
    ProfilingData profiling_data = 1;
    Error error = 2;
  }
}

message ProfileExperiments {
  repeated path.Command disabledCommands = 1;
  bool disableAnisotropicFiltering = 2;
}

message ProfilingData {
  message Group {
    int32 id = 1;
    string name = 2;
    int32 parent_id = 3;  // references Group.id
    path.Commands link = 4;
  }

  message GpuSlices {
    message Slice {
      message Extra {
        string name = 1;
        oneof value {
          uint64 int_value = 2;
          double double_value = 3;
          string string_value = 4;
        }
      }

      uint64 ts = 1;
      uint64 dur = 2;
      uint64 id = 3;
      string label = 4;
      int32 depth = 5;
      repeated Extra extras = 6;

      int32 track_id = 7;  // references Track.id
      int32 group_id = 8;  // references Group.id
    }

    message Track {
      int32 id = 1;
      string name = 2;
    }

    repeated Slice slices = 1;
    repeated Track tracks = 2;
  }

  message Counter {
    uint32 id = 1;
    string name = 2;
    string description = 3;
    string unit = 4;
    bool default = 5;
    device.GpuCounterDescriptor.GpuCounterSpec spec = 6;
    repeated uint64 timestamps = 7;
    repeated double values = 8;
  }

  message CounterGroup {
    uint32 id = 1;
    string label = 2;
  }

  // GpuCounters contains aggregated GPU performance result, the aggregation
  // happens inside each GPU slices groups, and on multiple metrics.
  message GpuCounters {
    // Metric contains metadata describing an interested GPU performance
    // dimension.
    message Metric {
      enum AggregationOperator {
        Summation = 0;
        TimeWeightedAvg = 1;
      }
      int32 id = 1;
      uint32 counter_id = 2;  // -> Counter.id. Valid for GPU counter metrics.
      string name = 3;
      string unit = 4;
      AggregationOperator op = 5;
      string description = 6;
      bool select_by_default = 7;
      reserved 8;
      repeated uint32 counter_group_ids = 12;  // References CounterGroup.id.
      double average = 9;
      reserved 10;
      enum Type {
        Hardware = 0;
        StaticAnalysisRanged = 1;
        StaticAnalysisSummed = 2;
      }
      Type type = 11;
    }

    // Perf includes a best-guessing performance value and a confidence range.
    message Perf {
      double estimate = 1;
      double min = 2;
      double max = 3;
      map<int32, double> estimate_samples = 4;  // {index} -> {sample weight}
      map<int32, double> min_samples = 5;       // {index} -> {sample weight}
      map<int32, double> max_samples = 6;       // {index} -> {sample weight}
    }

    // Entry contains performance data for a specific command.
    message Entry {
      int32 group_id = 1;                    // references Group.id
      map<int32, Perf> metric_to_value = 2;  // Metric.id -> perf value.
    }

    repeated Metric metrics = 1;
    repeated Entry entries = 2;
  }

  repeated Group groups = 1;
  GpuSlices slices = 2;
  repeated Counter counters = 3;
  GpuCounters gpu_counters = 4;
  repeated CounterGroup counter_groups = 5;
}

message GraphVisualizationRequest {
  path.Capture capture = 1;
  GraphFormat format = 2;
}

message GraphVisualizationResponse {
  oneof res {
    bytes graphVisualization = 1;
    Error error = 2;
  }
}

enum GraphFormat {
  PBTXT = 0;
  DOT = 1;
}

message ImportCaptureRequest {
  string name = 1;
  bytes data = 2;
}

message ImportCaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message InstallAppRequest {
  path.Device device = 1;
  string application = 2;
}

message InstallAppResponse {
  Error error = 1;
}

message LoadCaptureRequest {
  string path = 1;
}

message LoadCaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message PerfettoQueryRequest {
  path.Capture capture = 1;
  string query = 2;
}

message PerfettoQueryResponse {
  oneof res {
    perfetto.QueryResult result = 1;
    Error error = 2;
  }
}

message PingRequest {}

message PingResponse {}

message ProfileRequest {
  // Settings for what profile data the client wants.
  // Set all to false to flush any pending data and disable profiling.
  bool pprof = 1;  // Enable pprof profiling?
  bool trace = 2;  // Enable trace data?

  // Time in seconds between memory snapshots
  uint32 memory_snapshot_interval = 3;
}

message ProfileResponse {
  bytes pprof = 1;  // Streamed pprof data.
  bytes trace = 2;  // Streamed trace data.
  Error error = 3;
}

message ServerStatusRequest {
  float memory_snapshot_interval = 1;
  float status_update_frequency = 2;
}

message ServerStatusResponse {
  oneof res {
    TaskUpdate task = 1;
    MemoryStatus memory = 2;
    ReplayUpdate replay = 3;
  }
}

message TaskUpdate {
  TaskStatus status = 1;
  uint64 id = 2;
  uint64 parent = 3;
  string name = 4;
  int32 complete_percent = 5;
  bool background = 6;
  string event = 7;
}

enum TaskStatus {
  STARTING = 0;
  FINISHED = 1;
  PROGRESS = 2;
  BLOCKED = 3;
  UNBLOCKED = 4;
  EVENT = 5;
}

message MemoryStatus {
  uint64 totalHeap = 1;
}

message ReplayUpdate {
  uint32 replay_id = 1;
  path.Device device = 2;
  ReplayStatus status = 3;
  // Progress information below, sent if status is EXECUTING.
  uint64 label = 4;
  uint32 total_instrs = 5;
  uint32 finished_instrs = 6;
}

enum ReplayStatus {
  REPLAY_QUEUED = 0;
  REPLAY_STARTED = 1;
  REPLAY_EXECUTING = 2;
  REPLAY_FINISHED = 3;
}

message SaveCaptureRequest {
  path.Capture capture = 1;
  string path = 2;
}

message SaveCaptureResponse {
  Error error = 1;
}

message SetRequest {
  path.Any path = 1;
  Value value = 2;
  // Config to use when resolving paths.
  path.ResolveConfig config = 3;
}

message SetResponse {
  oneof res {
    path.Any path = 1;
    Error error = 2;
  }
}

message SplitCaptureRequest {
  path.Commands commands = 1;
}

message SplitCaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message TrimCaptureInitialStateRequest {
  path.Capture capture = 1;
}

message TrimCaptureInitialStateResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message TraceRequest {
  oneof action {
    TraceOptions initialize = 1;
    TraceEvent query_event = 2;
  }
}

message TraceResponse {
  oneof res {
    StatusResponse status = 1;
    Error error = 2;
  }
}

message TraceOptions {
  // The device on which to trace
  path.Device device = 1;
  oneof app {
    // The device-specific uri to trace
    string uri = 2;
    // The application to upload and trace
    bytes upload_application = 3;
    // The server port that should be connected to for tracing
    uint32 port = 4;
  }
  // The type of this trace.
  TraceType type = 23;
  reserved 5;

  // Any additional command-line args to pass to the app
  string additional_command_line_args = 6;
  // What directory should be used for tracing
  string cwd = 7;
  // Additional environment variables to add in the form 'X=Y'
  repeated string environment = 8;
  // How long should we trace for
  float duration = 9;
  // What frames should we insert into the trace
  uint32 observe_frame_frequency = 10;
  reserved 11;
  // What frame should we start tracing.
  uint32 start_frame = 12;
  // How many frames should we capture
  uint32 frames_to_capture = 13;
  // Set whether to ignore the ANDROID_frame_boundary extension
  bool ignore_frame_boundary_delimiters = 14;
  // Insert extra commands to record error state
  bool record_error_state = 15;
  // Wait for an event to start tracing
  bool defer_start = 16;
  // Disable buffering. (In case of a crash)
  bool no_buffer = 17;
  // Clear the application cache
  bool clear_cache = 18;
  // Hide unknown extensions
  bool hide_unknown_extensions = 19;
  // Record trace timing
  bool record_trace_times = 20;
  // Where should we save the capture file.
  string server_local_save_path = 21;
  // Name of the pipe to connect/listen to.
  string pipe_name = 22;
  // Disable coherent_memory_tracking. (Useful if you want to attach a debugger)
  bool disable_coherent_memory_tracker = 25;
  // Make GAPII wait for a debugger to attach
  bool wait_for_debugger = 26;
  // The config to use if doing a Perfetto trace.
  perfetto.protos.TraceConfig perfetto_config = 24;
  // The name of the process to capture (empty for capturing any process).
  string process_name = 27;
  // Load the Vulkan validation layer during capture
  bool load_validation_layer = 28;
  // The config options to use if doing a Fuchsia trace.
  FuchsiaTraceConfig fuchsia_trace_config = 29;
}

enum TraceEvent {
  Begin = 0;   // Begin tracing (only valid if started with MidExecution)
  Stop = 1;    // Flush and stop the trace
  Status = 2;  // Get the status of the trace
}

message StatusResponse {
  int64 bytes_captured = 1;  // How many bytes have been captured so far
  TraceStatus status = 2;    // What state the trace is in
}

enum TraceStatus {
  Uninitialized = 0;
  Initializing = 1;
  Capturing = 2;
  WaitingToStart = 3;
  Done = 4;
}

message TraceTargetTreeNodeRequest {
  path.Device device = 1;
  string uri = 2;
  float density = 3;
}

message TraceTargetTreeNodeResponse {
  oneof val {
    TraceTargetTreeNode node = 1;
    Error error = 2;
  }
}

message TraceTargetTreeNode {
  // The name of the node
  string name = 1;
  // The icon of this node.
  bytes icon = 2;
  // The uri of this node
  string uri = 3;
  // The parent of this node. It will point to
  // this node if there is no parent
  string parent_uri = 4;
  // Child nodes from this tree node
  repeated string children_uris = 5;
  // The uri that should be passed to the TraceOptions to trace this target.
  // If null, this node is not traceable.
  string trace_uri = 6;
  // The friendly application name, if it makes sense.
  string friendly_application = 7;
  // The friendly executable name, if it makes sense.
  string friendly_executable = 8;
}

message UpdateSettingsRequest {
  // Enables or disable anonymous crash reporting.
  // This will override the -crashreport command line flag.
  bool enable_crash_reporting = 1;

  // Enables or disable anonymous analytics reporting.
  // This will override the -analytics command line flag.
  bool enable_analytics = 2;

  // The client identifier to use for analytics reporting.
  // This will override the -analytics command line flag.
  string client_id = 3;

  // The path to the adb executable to use.
  // This will override the -adb command line flag.
  string adb = 4;
}

message UpdateSettingsResponse {
  Error error = 1;
}

message ValidateDeviceRequest {
  path.Device device = 1;
}

message ValidateDeviceResponse {
  reserved 1;
  oneof res {
    DeviceValidationResult result = 2;

    // Internal error from being unable to start validation
    // (doesn't include failure from the validation itself).
    Error error = 3;
  }
}

// Next value: 5
message DeviceValidationResult {
  enum ErrorCode {
    // Default, never set to any actual value.
    INVALID = 0;

    // Passed validation.
    OK = 1;

    // Not supported in some kind of way (e.g. unsupported device, custom
    // build).
    FAILED_PRECONDITION = 2;

    // Validating the Perfetto trace file failed (i.e. mismatched GPU counters).
    FAILED_TRACE_VALIDATION = 3;
  }

  // Includes whether a device passes validation and a reason for failure.
  ErrorCode error_code = 3;

  // Message with details of how the device failed validation (doesn't
  // include internal errors where we somehow failed to start validation).
  string validation_failure_msg = 1;

  // Path to the perfetto trace file to help debug validation issues.
  string trace_path = 2;

  // The specific type of validator that was used.
  enum ValidatorType {
    INVALID_VALIDATOR = 0;

    // Adreno validator checks for specific counters to ensure that the name and
    // id is consistent with hardcoded values. Also has specific check to make
    // sure that the value is within expected ranges.
    ADRENO = 1;

    // Mali validator checks for specific counters to ensure that the name and
    // id is consistent with hardcoded values. Also has specific check to make
    // sure that the value is within expected ranges.
    MALI = 2;

    // The fallback validator that runs a minimal check for the GPU counter,
    // running a trace for all available GPU counters and checking to see that
    // at least one value is non-zero. This is consistent with the CTS test in
    // Android U.
    GENERIC = 3;

    // PowerVR validator checks for specific counters to ensure that the name
    // and id is consistent with hardcoded values. Also has specific check to
    // make sure that the value is within expected ranges.
    POWER_VR = 4;
  }

  ValidatorType validator_type = 4;
}

message FuchsiaTraceConfig {
  // Tracing categories per Fuchsia's ffx tool, tracing type Fuchsia.
  repeated string categories = 1;

  // Global ID of component to trace, tracing type Graphics.
  int32 global_id = 2;
}