Google is committed to advancing racial equity for Black communities. See how.

fuchsia.gpu.magma

PROTOCOLS

Device

Defined in fuchsia.gpu.magma/magma.fidl

Connect

Get the magma ipc channels.

Request

NameType
client_id uint64

Response

NameType
primary_channel handle<channel>
notification_channel handle<channel>

DumpState

Dumps driver and hardware state.

Request

NameType
dump_type uint32

GetUnitTestStatus

For testing only - on non-test drivers this will close the channel.

Request

NameType

Response

NameType
status zx/status

Query

Deprecated(fxbug.dev/54105)

Request

NameType
query_id uint64

Response

NameType
result uint64

Query2

Returns a parameter, or an error.

Request

NameType
query_id uint64

Response

NameType
result Device_Query2_Result

QueryReturnsBuffer

Returns a buffer, or an error.

Request

NameType
query_id uint64

Response

NameType
result Device_QueryReturnsBuffer_Result

TestRestart

For testing only.

Request

NameType

PerformanceCounterAccess

Defined in fuchsia.gpu.magma/magma.fidl

This protocol is implemented by ZX_PROTOCOL_GPU_PERFORMANCE_COUNTERS devices.

GetPerformanceCountToken

This access token is not used as an event, but is instead passed to Primary.EnablePerformanceCounterAccess.

Request

NameType

Response

NameType
access_token handle<event>

PerformanceCounterEvents

Defined in fuchsia.gpu.magma/magma.fidl

OnPerformanceCounterReadCompleted

Signals that a performance counter buffer has data. These will be output in the order of when the reads are completed.

Response

NameType
trigger_id uint32
buffer_id zx/koid
buffer_offset uint32
timestamp zx/time
flags ResultFlags

Primary

Defined in fuchsia.gpu.magma/magma.fidl

AccessPerformanceCounters

Tries to enable performance counter FIDL messages. To be successful, |access_token| must have been returned by PerformanceCounterAccess.GetPerformanceCountToken() from the matching device.

Request

NameType
access_token handle<event>

AddPerformanceCounterBufferOffsetsToPool

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.

Request

NameType
pool PerfCountPoolId
offsets vector<BufferOffset>[64]

ClearPerformanceCounters

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.

Request

NameType
counters vector<uint64>[64]

CommitBuffer

Ensures that page_count pages starting at page_offset from the beginning of the buffer are backed by physical memory.

Request

NameType
buffer_id zx/koid
page_offset uint64
page_count uint64

CreateContext

Creates context context_id.

Request

NameType
context_id uint32

CreatePerformanceCounterBufferPool

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.

Request

NameType
pool PerfCountPoolId
event_channel request<PerformanceCounterEvents>

DestroyContext

Destroys context context_id.

Request

NameType
context_id uint32

DumpPerformanceCounters

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.

Request

NameType
pool PerfCountPoolId
trigger_id uint32

EnableFlowControl

Enables the events OnNotifyMessagesConsumed and OnNotifyMemoryImported.

Request

NameType

EnablePerformanceCounters

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.

Request

NameType
counters vector<uint64>[64]

ExecuteCommandBufferWithResources

Submits a command buffer for execution on the GPU, with associated resources.

Request

NameType
context_id uint32
command_buffer CommandBuffer
resources vector<Resource>
wait_semaphores vector<uint64>
signal_semaphores vector<uint64>

ExecuteImmediateCommands

Submits a series of commands for execution on the GPU without using a command buffer.

Request

NameType
context_id uint32
command_data vector<uint8>[2048]
semaphores vector<uint64>

GetError

Retrieve the current magma error status.

Request

NameType

Response

NameType
magma_status int32

ImportBuffer

Imports a buffer for use in the system driver.

Request

NameType
buffer handle<vmo>

ImportObject

Imports an object for use in the system driver.

Request

NameType
object handle<handle>
object_type uint32

IsPerformanceCounterAccessEnabled

Returns true if any AccessPerformanceCounters message has succeeded.

Request

NameType

Response

NameType
enabled bool

MapBufferGpu

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.

Request

NameType
buffer_id zx/koid
gpu_va uint64
page_offset uint64
page_count uint64
flags uint64

OnNotifyMemoryImported

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.

Response

NameType
bytes uint64

OnNotifyMessagesConsumed

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.

Response

NameType
count uint64

ReleaseBuffer

Destroys the buffer with buffer_id within this connection.

Request

NameType
buffer_id zx/koid

ReleaseObject

Destroys the object with object_id within this connection.

Request

NameType
object_id zx/koid
object_type uint32

ReleasePerformanceCounterBufferPool

Releases a pool of performance counter buffers. Performance counter access must have been enabled using AccessPerformanceCounters before calling this method.

Request

NameType
pool PerfCountPoolId

RemovePerformanceCounterBufferFromPool

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.

Request

NameType
pool PerfCountPoolId
buffer_id zx/koid

UnmapBufferGpu

Releases the mapping at gpu_va from the GPU. Buffers will also be implicitly unmapped when released.

Request

NameType
buffer_id zx/koid
gpu_va uint64

STRUCTS

BufferOffset

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescriptionDefault
buffer_id zx/koid No default
offset uint64 No default
size uint64 No default

CommandBuffer

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescriptionDefault
batch_buffer_resource_index uint32

Index of the resource containing instructions to start the command buffer.

No default
batch_start_offset uint64

Starting offset within the resource.

No default

Device_Query2_Response

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescriptionDefault
result uint64 No default

Device_QueryReturnsBuffer_Response

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescriptionDefault
buffer handle<vmo> No default

Resource

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescriptionDefault
buffer zx/koid No default
offset uint64 No default
length uint64 No default

ENUMS

QueryId

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
VENDOR_ID 0
DEVICE_ID 1
IS_TEST_RESTART_SUPPORTED 2
IS_TOTAL_TIME_SUPPORTED 3
MINIMUM_MAPPABLE_ADDRESS 4
MAXIMUM_INFLIGHT_PARAMS 5

Upper 32bits: max inflight messages, lower 32bits: max inflight memory (MB)

Status

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
INTERNAL_ERROR 1
INVALID_ARGS 2
ACCESS_DENIED 3
MEMORY_ERROR 4
CONTEXT_KILLED 5
CONNECTION_LOST 6
TIMED_OUT 7
UNIMPLEMENTED 8

UNIONS

Device_Query2_Result

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescription
response Device_Query2_Response
err Status

Device_QueryReturnsBuffer_Result

Defined in fuchsia.gpu.magma/magma.fidl

NameTypeDescription
response Device_QueryReturnsBuffer_Response
err Status

BITS

ResultFlags

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
DISCONTINUITY 1

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.

CONSTANTS

NameValueTypeDescription
kReceiveBufferSize 2048 uint32

Primary declarations.

TYPE ALIASES

NameValueDescription
PerfCountPoolId uint64

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.