gapid/service/service.go

// Copyright (C) 2016 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.

//go:generate protoc --proto_path . --go_out . service.proto

// Package service is the definition of the RPC GPU debugger service exposed by the server.
//
// It is not the actual implementation of the service functionality.
package service

import (
	"android.googlesource.com/platform/tools/gpu/framework/binary"
	"android.googlesource.com/platform/tools/gpu/framework/binary/schema"
	"android.googlesource.com/platform/tools/gpu/framework/id"
	"android.googlesource.com/platform/tools/gpu/framework/log"
	"android.googlesource.com/platform/tools/gpu/framework/stringtable"
	"android.googlesource.com/platform/tools/gpu/gapid/atom"
	"android.googlesource.com/platform/tools/gpu/gapid/memory"
	"android.googlesource.com/platform/tools/gpu/gapid/service/path"
)

// binary: java.source = adt/idea/android/src
// binary: java.package = com.android.tools.idea.editors.gfxtrace.service
// binary: java.indent = "  "
// binary: java.member_prefix = my
// binary: java.service.disable = Debug
// binary: service = Service, Debug

// Service is the interface provided by the GAPIS server.
type Service interface {
	path.Service

	// GetSchema returns the type and constant schema descriptions for all objects
	// used in the api.
	// This includes all the types included in or referenced from the atom stream.
	GetSchema(ctx log.Context) (schema.Message, error)

	// GetAvailableStringTables returns list of available string table descriptions.
	GetAvailableStringTables(ctx log.Context) ([]stringtable.Info, error)

	// GetStringTable returns the requested string table.
	GetStringTable(ctx log.Context, info stringtable.Info) (*stringtable.StringTable, error)

	// GetFeatures returns 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.
	GetFeatures(ctx log.Context) ([]string, error)

	// ImportCapture imports capture data emitted by the graphics spy, returning
	// the new capture identifier.
	ImportCapture(ctx log.Context, name string, Data []uint8) (*path.Capture, error)

	// LoadCapture imports capture data from a file, returning the new capture
	// identifier.
	LoadCapture(ctx log.Context, path string) (*path.Capture, error)

	// GetCaptures returns the full list of capture identifiers avaliable on the
	// server.
	GetCaptures(ctx log.Context) ([]*path.Capture, error)

	// 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.
	GetDevices(ctx log.Context) ([]*path.Device, error)

	// GetFramebufferColor returns the ImageInfo identifier describing the bound
	// color buffer for the given device, immediately following the atom after.
	// The provided RenderSettings structure can be used to adjust maximum desired
	// dimensions of the image, as well as applying debug visualizations.
	GetFramebufferColor(ctx log.Context, device *path.Device, after *path.Atom, settings RenderSettings) (*path.ImageInfo, error)

	// GetFramebufferDepth returns the ImageInfo identifier describing the bound
	// depth buffer for the given device, immediately following the atom after.
	GetFramebufferDepth(ctx log.Context, device *path.Device, after *path.Atom) (*path.ImageInfo, error)

	// GetTimingInfo performs timings of the given capture on the given device,
	// returning an identifier to the results.
	// This function is experimental and will change signature.
	GetTimingInfo(ctx log.Context, device *path.Device, capture *path.Capture, flags TimingFlags) (*path.TimingInfo, error)
}

// Debug is the collection of additional service methods used for debugging.
type Debug interface {
	// BeginCPUProfile starts CPU self-profiling of the server.
	// If the CPU is already being profiled then this function will return an
	// error.
	// This is a debug API, and may be removed in the future.
	BeginCPUProfile(ctx log.Context) error

	// EndCPUProfile ends the CPU profile, returning the pprof samples.
	// This is a debug API, and may be removed in the future.
	EndCPUProfile(ctx log.Context) ([]byte, error)
}

// ApiID is an identifier for an API.
type ApiID id.ID

// AtomsID is an identifier of an atom stream.
type AtomsID id.ID

// TimingFlags is a bitfield describing what should be timed.
// This is experimental and will change in the near future.
// binary: java.bitfield.TimingFlags = true
type TimingFlags int

const (
	TimingCPU         TimingFlags = 0 // Time using CPU timers (default).
	TimingGPU         TimingFlags = 1 // Time using GPU timers
	TimingPerCommand  TimingFlags = 2 // Time individual commands.
	TimingPerDrawCall TimingFlags = 4 // Time each draw call.
	TimingPerFrame    TimingFlags = 8 // Time each frame.
)

// Capture describes single capture file held by the server.
type Capture struct {
	binary.Generate
	Name  string  // Name given to the capture. e.g. "KittyWorld"
	Atoms AtomsID // The path to the stream of atoms in this capture.
	Apis  []ApiID // List of graphics APIs used by this capture.
}

// Report describes all warnings and errors found by a capture.
type Report struct {
	binary.Generate
	Items []ReportItem
}

// ReportItem represents an entry in a report.
type ReportItem struct {
	binary.Generate
	Severity log.Severity // The severity of the report item.
	Message  string       // The message for the item.
	Atom     uint64       // The index of the atom the item refers to.
}

// MemoryInfo describes the state of a range of memory at a specific point in
// the atom stream.
type MemoryInfo struct {
	binary.Generate
	Data     []uint8          // The memory values for the span.
	Reads    memory.RangeList // The Data-relative ranges that were read-from at the specified atom.
	Writes   memory.RangeList // The Data-relative ranges that were written-to at the specified atom.
	Observed memory.RangeList // The Data-relative ranges that have been observed.
}

// TimingInfo holds the results of a resolved GetTimingInfo request.
// This is experimental and will change in the near future.
type TimingInfo struct {
	binary.Generate
	PerCommand  []AtomTimer      // The timing results of each command.
	PerDrawCall []AtomRangeTimer // The timing results of each draw call.
	PerFrame    []AtomRangeTimer // The timing results of each frame.
}

// AtomTimer holds the timing information for a single atom.
// This is experimental and will change in the near future.
type AtomTimer struct {
	binary.Generate
	AtomIndex   uint64 // The atom that was timed.
	Nanoseconds uint64 // The time taken for that atom.
}

// AtomRangeTimer holds the timing information for a range of contiguous atoms.
// This is experimental and will change in the near future.
type AtomRangeTimer struct {
	binary.Generate
	FromAtomIndex uint64 // The first atom in the range that was timed.
	ToAtomIndex   uint64 // The last atom in the range that was timed.
	Nanoseconds   uint64 // The time taken for all atoms in the range.
}

// RenderSettings contains settings and flags to be used in replaying and
// returning a bound render target's color buffer.
type RenderSettings struct {
	binary.Generate
	MaxWidth      uint32        // The desired maximum width of the image. The returned image may be larger than this.
	MaxHeight     uint32        // The desired minimum height of the image. The returned image may be larger than this.
	WireframeMode WireframeMode // The wireframe mode to use when rendering.
}

// Resources contains the full list of resources used by a capture.
type Resources struct {
	binary.Generate
	Textures1D []ResourceInfo
	Textures2D []ResourceInfo
	Textures3D []ResourceInfo
	Cubemaps   []ResourceInfo
}

// ResourceInfo describes a single resource.
type ResourceInfo struct {
	binary.Generate
	ID       path.ResourceID // The resource instance unique identifier.
	Name     string          // The resource name.
	Accesses []uint64        // The list of atom indices where the resource was used.
}

// Context represents a single rendering context in the capture.
type Context struct {
	binary.Generate
	ID     path.ContextID // The context instance unique identifier.
	Name   string         // The context name.
	Api    ApiID          // The API that this context belongs to.
	Ranges atom.RangeList // The range of atoms that belong to this context.
}

// ContextList represents all the contexts used in the capture.
type ContextList struct {
	binary.Generate
	Contexts []Context
}

// Find returns the context in the list with the identifier id, or nil if no
// matching context was found.
func (l ContextList) Find(id path.ContextID) *Context {
	for _, c := range l.Contexts {
		if c.ID == id {
			return &c
		}
	}
	return nil
}

// Hierarchy represents a single atom hierarchy.
type Hierarchy struct {
	binary.Generate
	Name    string         // Name of the hierarchy.
	Context path.ContextID // Context identifier.
	Root    atom.Group     // The root of the hierarchy.
}

// HierarchyList represents all the hierarchies available for a capture.
type HierarchyList struct {
	binary.Generate
	Hierarchies []Hierarchy
}