blob: 78289e017f0b6595d7162ce9e3254e80bc0ca90d [file] [log] [blame]
// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.gpu.magma;
using zx;
enum QueryId {
VENDOR_ID = 0;
DEVICE_ID = 1;
IS_TEST_RESTART_SUPPORTED = 2;
IS_TOTAL_TIME_SUPPORTED = 3;
MINIMUM_MAPPABLE_ADDRESS = 4;
/// Upper 32bits: max inflight messages, lower 32bits: max inflight memory (MB)
MAXIMUM_INFLIGHT_PARAMS = 5;
};
enum Status {
INTERNAL_ERROR = 1;
INVALID_ARGS = 2;
ACCESS_DENIED = 3;
MEMORY_ERROR = 4;
CONTEXT_KILLED = 5;
CONNECTION_LOST = 6;
TIMED_OUT = 7;
UNIMPLEMENTED = 8;
};
protocol Device {
/// Deprecated(fxbug.dev/54105)
Query(uint64 query_id) -> (uint64 result);
/// Returns a parameter, or an error.
Query2(uint64 query_id) -> (uint64 result) error Status;
/// Returns a buffer, or an error.
QueryReturnsBuffer(uint64 query_id) -> (zx.handle:VMO buffer) error Status;
/// Get the magma ipc channels.
Connect(uint64 client_id) -> (zx.handle:CHANNEL primary_channel, zx.handle:CHANNEL notification_channel);
/// Dumps driver and hardware state.
DumpState(uint32 dump_type);
/// For testing only.
TestRestart();
/// For testing only - on non-test drivers this will close the channel.
GetUnitTestStatus() -> (zx.status status);
};
/// Primary declarations.
const uint32 kReceiveBufferSize = 2048;
struct Resource {
zx.koid buffer;
uint64 offset;
uint64 length;
};
struct CommandBuffer {
/// Index of the resource containing instructions to start the command buffer.
uint32 batch_buffer_resource_index;
/// Starting offset within the resource.
uint64 batch_start_offset;
};
/// Performance counter pools contain byte ranges of buffers. Whenever a performance counter dump is
/// triggered, the driver removes a range from the pool, writes the performance counter values from
/// the hardware into it, then signals the client using OnPerformanceCounterReadCompleted. Pool IDs
/// are arbitrary uint64 values that are allocated by the client.
using PerfCountPoolId = uint64;
bits ResultFlags {
/// This bit is set in result_flags if the performance counters missed some samples, e.g. due to
/// the GPU being in protected mode for part of the time.
DISCONTINUITY = 1;
};
struct BufferOffset {
zx.koid buffer_id;
uint64 offset;
uint64 size;
};
protocol Primary {
/// Imports a buffer for use in the system driver.
ImportBuffer(zx.handle:VMO buffer);
/// Destroys the buffer with `buffer_id` within this connection.
ReleaseBuffer(zx.koid buffer_id);
/// Imports an object for use in the system driver.
ImportObject(handle object, uint32 object_type);
/// Destroys the object with `object_id` within this connection.
ReleaseObject(zx.koid object_id, uint32 object_type);
/// Creates context `context_id`.
CreateContext(uint32 context_id);
/// Destroys context `context_id`.
DestroyContext(uint32 context_id);
/// Submits a command buffer for execution on the GPU, with associated resources.
ExecuteCommandBufferWithResources(
uint32 context_id,
CommandBuffer command_buffer,
vector<Resource> resources,
vector<zx.koid> wait_semaphores,
vector<zx.koid> signal_semaphores);
/// Submits a series of commands for execution on the GPU without using a command buffer.
ExecuteImmediateCommands(uint32 context_id,
bytes:kReceiveBufferSize command_data,
vector<zx.koid> semaphores);
/// Retrieve the current magma error status.
GetError() -> (int32 magma_status);
/// Maps `page_count` pages of `buffer` from `page_offset` onto the GPU in the connection's
/// address space at `gpu_va`. `flags` is a set of flags from `MAGMA_GPU_MAP_FLAGS` that
/// specify how the GPU can access the buffer.
MapBufferGpu(zx.koid buffer_id, uint64 gpu_va, uint64 page_offset,
uint64 page_count, uint64 flags);
/// Releases the mapping at `gpu_va` from the GPU.
/// Buffers will also be implicitly unmapped when released.
UnmapBufferGpu(zx.koid buffer_id, uint64 gpu_va);
/// Ensures that `page_count` pages starting at `page_offset` from the beginning of the
/// buffer are backed by physical memory.
CommitBuffer(zx.koid buffer_id, uint64 page_offset, uint64 page_count);
/// Tries to enable performance counter FIDL messages. To be successful, |access_token| must
/// have been returned by PerformanceCounterAccess.GetPerformanceCountToken() from the matching
/// device.
AccessPerformanceCounters(zx.handle:EVENT access_token);
/// Returns true if any AccessPerformanceCounters message has succeeded.
IsPerformanceCounterAccessEnabled() -> (bool enabled);
/// Enables the events OnNotifyMessagesConsumed and OnNotifyMemoryImported.
EnableFlowControl();
/// Indicates the given number of messages were consumed by the server.
/// The caller should limit the number of inflight messages:
/// (messages sent - server consumed) <= Max (see QueryId::MAXIMUM_INFLIGHT_PARAMS).
/// Messages are actually consumed by the server as quickly as possible, however this event
/// is sent by the server only when the consumed count reaches half the maximum.
-> OnNotifyMessagesConsumed(uint64 count);
/// Indicates the given number of buffer memory bytes were imported by the server.
/// The caller should limit the amount of memory from inflight ImportBuffer messages:
/// (bytes sent - server imported) <= Max (see QueryId::MAXIMUM_INFLIGHT_PARAMS).
/// This is a soft limit designed to prevent excessive memory consumption, but for large
/// messages the client may exceed the limit.
/// Memory is imported by the server as quickly as possible, however this event
/// is sent only when the consumed byte count reaches half the maximum; therefore,
/// if the client's count of inflight bytes is less than max/2, the client should send the
/// ImportBuffer message regardless of its size.
-> OnNotifyMemoryImported(uint64 bytes);
/// Enables a set of performance counters (the precise definition depends on the GPU driver).
/// Disables enabled performance counters that are not in the new set. Performance counters will
/// also be automatically disabled on connection close. Performance counter access must have
/// been enabled using AccessPerformanceCounters before calling this method.
EnablePerformanceCounters(vector<uint64>:64 counters);
/// Creates a pool of buffers that performance counters can be dumped into. |pool| can be an
/// arbitrary integer that's currently not in use. Performance counter access must have been
/// enabled using AccessPerformanceCounters before calling this method.
CreatePerformanceCounterBufferPool(
PerfCountPoolId pool, request<PerformanceCounterEvents> event_channel);
/// Releases a pool of performance counter buffers. Performance counter access must have been
/// enabled using AccessPerformanceCounters before calling this method.
ReleasePerformanceCounterBufferPool(PerfCountPoolId pool);
/// Adds set of a offsets into buffers to the pool. |offsets[n].buffer_id| is the koid of a
/// buffer that was previously imported using ImportBuffer(). The same buffer may be added to
/// multiple pools. The pool will hold on to a reference to the buffer even after ReleaseBuffer
/// is called. When dumped into this entry, counters will be written starting at
/// |buffer_offset| bytes into the buffer, and up to |offsets[n].buffer_offset| +
/// |offsets[n].buffer_size|. |offsets[n].buffer_size| must be large enough to fit all enabled
/// counters. Performance counter access must have been enabled using AccessPerformanceCounters
/// before calling this method.
AddPerformanceCounterBufferOffsetsToPool(
PerfCountPoolId pool, vector<BufferOffset>:64 offsets);
/// Removes every offset of a buffer from the pool. Once this is method is finished being
/// handled on the server, no more dumps will be processed into this buffer. In-flight dumps
/// into this buffer may be lost. Performance counter access must have been enabled using
/// AccessPerformanceCounters before calling this method.
RemovePerformanceCounterBufferFromPool(PerfCountPoolId pool, zx.koid buffer_id);
/// Triggers dumping of the performance counters into a buffer pool. May fail silently if there
/// are no buffers in the pool. |trigger_id| is an arbitrary ID assigned by the client that can
/// be returned in OnPerformanceCounterReadCompleted. Performance counter access must have been
/// enabled using AccessPerformanceCounters before calling this method.
DumpPerformanceCounters(PerfCountPoolId pool, uint32 trigger_id);
/// Sets the values of all listed performance counters to 0. May not be supported by some
/// hardware. Performance counter access must have been enabled using AccessPerformanceCounters
/// before calling this method.
ClearPerformanceCounters(vector<uint64>:64 counters);
};
/// This protocol is implemented by ZX_PROTOCOL_GPU_PERFORMANCE_COUNTERS devices.
protocol PerformanceCounterAccess {
/// This access token is not used as an event, but is instead passed to
/// Primary.EnablePerformanceCounterAccess.
GetPerformanceCountToken() -> (zx.handle:EVENT access_token);
};
protocol PerformanceCounterEvents {
/// Signals that a performance counter buffer has data. These will be output in the order of
/// when the reads are completed.
-> OnPerformanceCounterReadCompleted(uint32 trigger_id, zx.koid buffer_id, uint32 buffer_offset,
zx.time timestamp, ResultFlags flags);
};