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.

// 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/framework/stringtable/msg"
	"android.googlesource.com/platform/tools/gpu/gapid/atom"
	"android.googlesource.com/platform/tools/gpu/gapid/database"
	"android.googlesource.com/platform/tools/gpu/gapid/gfxapi"
	"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)

	// RegisterAndroidDevice registers the local android device with the
	// specified serial and returns a path to this device.
	RegisterAndroidDevice(ctx log.Context, serial string) (*path.Device, 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.
	// DEPRECATED: Use GetFramebufferAttachment
	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.
	// DEPRECATED: Use GetFramebufferAttachment
	GetFramebufferDepth(ctx log.Context, device *path.Device, after *path.Atom) (*path.ImageInfo, error)

	// GetFramebufferAttachment returns the ImageInfo identifier describing the
	// given framebuffer attachment and 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.
	GetFramebufferAttachment(
		ctx log.Context,
		device *path.Device,
		after *path.Atom,
		attachment gfxapi.FramebufferAttachment,
		settings RenderSettings) (*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)

	// GetPerformanceCounters returns the values of all global counters as
	// a JSON blob. This is a debug API, and may be removed in the future.
	GetPerformanceCounters(ctx log.Context) ([]byte, error)

	// GetProfile returns the pprof profile with the given name.
	// The "goroutine", "threadcreate", "heap", and "block" profiles are
	// built-in. This is a debug API, and may be removed in the future.
	GetProfile(ctx log.Context, name string, debug int) ([]byte, error)

	// GetMemProfileRate gets the current value of runtime.MemProfileRate.
	// This is a debug API, and may be removed in the future.
	GetMemProfileRate(ctx log.Context) (int, error)

	// SetMemProfileRate sets runtime.MemProfileRate.
	// This is a debug API, and may be removed in the future.
	SetMemProfileRate(ctx log.Context, rate int) 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).
	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  // Report items for this report.
	Groups         []ReportGroup // Report groups for this report.
	MsgIdentifiers []string      // Array of identifiers for messages.
	MsgArguments   []msg.Arg     // Array of single arguments for messages.
}

// ConstructMessage constructs msg.Msg instance from a reference.
func (report *Report) ConstructMessage(ref *MsgRef) *msg.Msg {
	m := &msg.Msg{
		Identifier: report.MsgIdentifiers[ref.Identifier],
		Arguments:  make(msg.MapType),
	}
	for _, i := range ref.Arguments {
		arg := report.MsgArguments[i]
		m.Arguments[arg.Key] = arg.Value
	}
	return m
}

// MsgRef references message in Report.
type MsgRef struct {
	binary.Generate
	Identifier uint32   // The index of identifier.
	Arguments  []uint32 // The indicies of arguments.
}

// Hash returns unique identifier of MsgRef.
func (ref MsgRef) Hash() (id.ID, error) {
	return database.Hash(append(ref.Arguments, ref.Identifier))
}

// ReportItem represents an entry in a report.
type ReportItem struct {
	binary.Generate
	Severity log.Severity // The severity of the report item.
	Message  *MsgRef      // The message for the item.
	Atom     uint64       // The index of the atom the item refers to.
	Tags     []MsgRef     // The references to tags associated with this item.
}

// ReportGroup represents a group of ReportItem which have the same tag.
type ReportGroup struct {
	binary.Generate
	Name  MsgRef   // The reference to Msg which describes this group.
	Items []uint32 // The indices of report items which belong to this group.
	Tags  []MsgRef // The union of all Items tags. Currently isn't supported and is nil. TODO: Add filtering support for the entire group.
}

// Link returns the link to the atom pointed by a report item.
// If nil, nil is returned then the path cannot be followed.
func (i ReportItem) Link(ctx log.Context, p path.Path, d database.Database) (path.Path, error) {
	if capture := path.FindCapture(p); capture != nil {
		return capture.Atoms().Index(i.Atom), nil
	}
	return nil, nil
}

// 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.
// DEPRECATED: Use ResourceBundles instead.
type Resources struct {
	binary.Generate
	Textures1D []ResourceInfo
	Textures2D []ResourceInfo
	Textures3D []ResourceInfo
	Cubemaps   []ResourceInfo
}

// ResourceBundles contains the full list of resources used by a capture.
type ResourceBundles struct {
	binary.Generate
	Bundles []ResourceBundle
}

// ResourceBundle contains all resources of a spefic type.
type ResourceBundle struct {
	binary.Generate
	Type      gfxapi.ResourceType
	Resources []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
}