fuchsia.gpu.magma

Magma is the driver model for GPUs/NPUs on Fuchsia.

Magma has two driver components: a hardware-specific library loaded into each application’s address space ("client driver", sometimes known as "Installable client driver" or "ICD"); and the Magma system driver that interfaces with the hardware. The communication protocols between the two driver pieces are defined here.

Some names have a numeric suffix (eg, BufferRangeOp2); the number is a detail of how the protocols have evolved, and can be ignored.

Added: 9

PROTOCOLS

CombinedDevice

Defined in fuchsia.gpu.magma/magma.fidl

A combination of all the production |Device| protocols. This protocol is implemented on the Magma service side and should not be used by clients.

Connect2

Creates a connection to the device comprised of two IPC channels. The primary channel is for the Primary protocol (see below). The notification channel is used for vendor-specific messages which are sent only in the reverse (server-client) direction, typically in response to client command completion.

Request

NameType
client_id uint64
primary_channel server_end<Primary>
notification_channel server_end<Notification>

DumpState

Dumps driver and hardware state to the log.

Request

NameType
dump_type uint32

GetIcdList

Returns a list of ICDs that can be used with this Magma device. The list is sorted in descending order of preference.

Request

<EMPTY>

Response

NameType
icd_list vector<IcdInfo>[8]

Query

On success, returns a result either in a buffer or a simple value.

Request

NameType
query_id QueryId

Response

NameType
payload Device_Query_Result

DependencyInjection

Defined in fuchsia.gpu.magma/magma.fidl

This protocol is implemented by ZX_PROTOCOL_GPU_DEPENDENCY_INJECTION devices. It's used to inject dependencies on other services into the MSD. It can be used only by a privileged process.

SetMemoryPressureProvider

Provides a fuchsia.memorypressure.Provider implementation to the MSD.

Request

NameType
provider fuchsia.memorypressure/Provider

Device

Defined in fuchsia.gpu.magma/magma.fidl

The Magma Device protocol allow clients to learn about the hardware by making queries, such as device and vendor IDs, and which client drivers are supported by the device's system driver.
To engage further with the device, clients may establish connections formed of channel pairs: a primary channel for making requests (see Primary protocol below), and a secondary channel for receiving notification messages (see Notification protocol below).

Connect2

Creates a connection to the device comprised of two IPC channels. The primary channel is for the Primary protocol (see below). The notification channel is used for vendor-specific messages which are sent only in the reverse (server-client) direction, typically in response to client command completion.

Request

NameType
client_id uint64
primary_channel server_end<Primary>
notification_channel server_end<Notification>

Query

On success, returns a result either in a buffer or a simple value.

Request

NameType
query_id QueryId

Response

NameType
payload Device_Query_Result

DiagnosticDevice

Defined in fuchsia.gpu.magma/magma.fidl

Methods used to expose diagnostics from the Magma device.

DumpState

Dumps driver and hardware state to the log.

Request

NameType
dump_type uint32

IcdLoaderDevice

Defined in fuchsia.gpu.magma/magma.fidl

Methods implemented by an MSD and exposed for use of an ICD loader.

GetIcdList

Returns a list of ICDs that can be used with this Magma device. The list is sorted in descending order of preference.

Request

<EMPTY>

Response

NameType
icd_list vector<IcdInfo>[8]

Notification

Defined in fuchsia.gpu.magma/magma.fidl

This protocol is empty as the message contents are vendor specific.

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

<EMPTY>

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
payload PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest

Primary

Defined in fuchsia.gpu.magma/magma.fidl

If a system driver error occurs, or if the client sends a message that the client should have known is invalid, the connection will be closed and a zx.Status sent via epitaph.

AddPerformanceCounterBufferOffsetsToPool

Adds a set of offsets into buffers to the pool. |offsets[n].buffer_id| is the id 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 |offsets[n].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 EnablePerformanceCounterAccess before calling this method.

Request

NameType
pool_id PerformanceCounterPoolId
offsets vector<BufferRange>[64]

BufferRangeOp2

Perform an operation on a range of the buffer.

Request

NameType
op BufferOp
range BufferRange

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 EnablePerformanceCounterAccess before calling this method.

Request

NameType
counters PerformanceCounterSet

CreateContext

Creates context context_id for use in command execution. A context may be associated with hardware state.

Request

NameType
context_id ContextId

CreatePerformanceCounterBufferPool

Creates a pool of buffers that performance counters can be dumped into. Performance counter access must have been enabled using EnablePerformanceCounterAccess before calling this method.

Request

NameType
pool_id PerformanceCounterPoolId
event_channel server_end<PerformanceCounterEvents>

DestroyContext

Destroys context context_id.

Request

NameType
context_id ContextId

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 EnablePerformanceCounterAccess before calling this method.

Request

NameType
pool_id PerformanceCounterPoolId
trigger_id PerformanceCounterTriggerId

EnableFlowControl

Enables the events OnNotifyMessagesConsumed and OnNotifyMemoryImported.

Request

<EMPTY>

EnablePerformanceCounterAccess

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>

EnablePerformanceCounters

Enables a set of performance counters. 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 EnablePerformanceCounterAccess before calling this method.

Request

NameType
counters PerformanceCounterSet

ExecuteCommand

Submits command buffers for execution on the hardware, with associated resources. resources must refer to buffers that have been imported. wait_semaphores and signal_semaphores must refer to events that have been imported. wait_semaphores must all be signaled before execution begins, then are reset. signal_semaphores will be signaled after the command buffer is completed.

Request

NameType
context_id ContextId
resources vector<BufferRange>
command_buffers vector<CommandBuffer>
wait_semaphores vector<uint64>
signal_semaphores vector<uint64>
flags CommandBufferFlags

ExecuteImmediateCommands

Submits a series of commands for execution on the hardware without using a command buffer. semaphores must refer to events that have been imported, and will be signaled after the commands are completed.

Request

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

ExecuteInlineCommands

Submits a series of commands for execution on the hardware without using a command buffer. The number of commands sent should be calculated so that the total message size is less than MAX_INLINE_COMMANDS_DATA_SIZE.

Added: 15

Request

NameType
context_id ContextId
commands vector<InlineCommand>

Flush

Incurs a round-trip to the system driver, used to ensure all previous messages have been observed, but not necessarily completed.

Request

<EMPTY>

Response

<EMPTY>

ImportObject

Imports an object for use in the system driver.

Added: 13

Request

NameType
payload PrimaryImportObjectRequest

ImportObject2

Removed: 18 Deprecated: 17

Request

NameType
object handle<handle>
object_type ObjectType
object_id ObjectId

IsPerformanceCounterAccessAllowed

Returns true if any EnablePerformanceCounterAccess message has succeeded.

Request

<EMPTY>

Response

NameType
enabled bool

MapBuffer

Maps a page range onto the hardware in the connection's address space at address hw_va. flags is a set of flags from MapFlags that specify how the hardware can access the buffer.

Request

NameType
payload PrimaryMapBufferRequest

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) <= MaxBytes (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) <= MaxMessages (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

ReleaseObject

Destroys the object with object_id within this connection.

Request

NameType
object_id ObjectId
object_type ObjectType

ReleasePerformanceCounterBufferPool

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

Request

NameType
pool_id PerformanceCounterPoolId

RemovePerformanceCounterBufferFromPool

Removes every offset of a buffer from the pool. Once this 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 EnablePerformanceCounterAccess before calling this method.

Request

NameType
pool_id PerformanceCounterPoolId
buffer_id ObjectId

UnmapBuffer

Releases the mapping at address hw_va from the hardware for the given buffer_id. Buffers will also be implicitly unmapped when released.

Request

NameType
payload PrimaryUnmapBufferRequest

TestDevice

Defined in fuchsia.gpu.magma/magma.fidl

Additional device methods for the purposes of testing the MSD and should not be used by ICDs.

Connect2

Creates a connection to the device comprised of two IPC channels. The primary channel is for the Primary protocol (see below). The notification channel is used for vendor-specific messages which are sent only in the reverse (server-client) direction, typically in response to client command completion.

Request

NameType
client_id uint64
primary_channel server_end<Primary>
notification_channel server_end<Notification>

DumpState

Dumps driver and hardware state to the log.

Request

NameType
dump_type uint32

GetIcdList

Returns a list of ICDs that can be used with this Magma device. The list is sorted in descending order of preference.

Request

<EMPTY>

Response

NameType
icd_list vector<IcdInfo>[8]

GetUnitTestStatus

Request

<EMPTY>

Response

NameType
status zx/Status

Query

On success, returns a result either in a buffer or a simple value.

Request

NameType
query_id QueryId

Response

NameType
payload Device_Query_Result

STRUCTS

BufferRange

Defined in fuchsia.gpu.magma/magma.fidl

FieldTypeDescriptionDefault
buffer_id ObjectId No default
offset uint64 No default
size uint64 No default

CommandBuffer

Defined in fuchsia.gpu.magma/magma.fidl

A command buffer may be used to pass hardware instructions in a shared buffer (VMO).

FieldTypeDescriptionDefault
resource_index uint32

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

No default
start_offset uint64

Starting offset within the resource.

No default

ENUMS

BufferOp flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
1

Populate the hardware page tables with the pages mapped in this range, committing pages as needed. This is not needed for allocations mapped GROWABLE, since the page tables will be populated on demand.

2

Depopulate page table mappings for this range. This prevents the hardware from accessing pages in that range, but the pages retain their contents.

ObjectType flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
10
Removed: 18 Deprecated: 17
11

A memory object backeed by a Zircon VMO.

12

A sync object backed by a Zircon event or VMO.

Added: 13

QueryId flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Types of information about the hardware and driver that can be queried from the Magma system driver. Vendor-specific ID numbers may be used, but those IDs will be listed elsewhere.

NameValueDescription
0

Returns the hardware vendor ID (simple result) - should be the PCI ID of the hardware vendor if possible, or the Khronos vendor ID otherwise.

1

Returns the hardware device ID (simple result)

2

Returns the version of the vendor interfaces supported by the system driver.

Added: 12
3

Returns true if MAGMA_QUERY_TOTAL_TIME is supported (simple result)

5

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

500

Returns a struct magma_total_time_query_result (buffer result); see: src/graphics/lib/magma/include/magma/magma_common_defs.h

10000

Vendor specific query IDs start here

TABLES

IcdInfo

Defined in fuchsia.gpu.magma/magma.fidl

Information about an ICD implementation that can be used with a Magma device.

OrdinalFieldTypeDescription
component_url fuchsia.url/Url

URL of the component implementation that provides the ICD.

flags IcdFlags

Flags describing the basic capabilities of the ICD, including what APIs it supports.

InlineCommand

Defined in fuchsia.gpu.magma/magma.fidl

Added: 15

OrdinalFieldTypeDescription
data vector<uint8>
semaphores vector<uint64>

PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalFieldTypeDescription
trigger_id PerformanceCounterTriggerId

Required.

buffer_id ObjectId

Required.

buffer_offset uint32

Required.

timestamp zx/Time

Required.

flags ResultFlags

Required.

PrimaryImportObjectRequest resource

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalFieldTypeDescription
object Object

Required.

object_type ObjectType

Required.

object_id ObjectId

Required.

flags ImportFlags

Optional

PrimaryMapBufferRequest

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalFieldTypeDescription
hw_va uint64

Required.

range BufferRange

Required.

flags MapFlags

PrimaryUnmapBufferRequest

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalFieldTypeDescription
hw_va uint64

Required.

buffer_id ObjectId

Required.

UNIONS

Device_Query_Response strict resource

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalVariantTypeDescription
simple_result uint64
buffer_result handle<vmo>

Device_Query_Result strict resource

Defined in fuchsia.gpu.magma/magma.fidl

OrdinalVariantTypeDescription
response Device_Query_Response
err zx/Status

Object flexible resource

Defined in fuchsia.gpu.magma/magma.fidl

Added: 13
OrdinalVariantTypeDescription
semaphore handle<event>
buffer handle<vmo>
vmo_semaphore handle<vmo>

BITS

CommandBufferFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
65536

Vendor specific definitions start here

IcdFlags flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
1
2
4

ImportFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Added: 13

NameValueDescription
1

MapFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
1
2
4
8

Uncommitted pages may be comitted on a hardware fault. If this flag is not set, access faults should cause an error.

65536

Vendor specific definitions start here

ResultFlags flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

NameValueDescription
1

This bit is set in result_flags if the performance counters missed some samples, e.g. due to the hardware being in protected mode for part of the time.

CONSTANTS

NameValueTypeDescription
MAX_ICD_COUNT 8 uint64

The maximum number of ICDs supported by a Magma system driver.

MAX_IMMEDIATE_COMMANDS_DATA_SIZE 2048 uint32

The batch size used to send multiple immediate commands in a single message.

MAX_INLINE_COMMANDS_DATA_SIZE 2048 uint32

The batch size used to send multiple inline commands in a single message.

Added: 15

ALIASES

NameValueDescription
ContextId uint32
ObjectId uint64
PerformanceCounterPoolId 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.

PerformanceCounterSet vector[64]

Describes a set of performance counters. The exact meaning depends on the specific driver, but often is a bitvector representing whether each performance counter is enabled or disabled.

PerformanceCounterTriggerId uint32