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.

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

Name	Type
client_id	uint64
primary_channel	server_end:Primary
notification_channel	server_end:Notification

DumpState

Dumps driver and hardware state to the log.

Request

Name	Type
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

Name	Type
icd_list	vector<IcdInfo>:8

Query

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

Request

Name	Type
query_id	QueryId

Response

Name	Type
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

Name	Type
provider	client_end: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

Name	Type
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

Name	Type
query_id	QueryId

Response

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
payload	PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest

PowerElementProvider

Defined in fuchsia.gpu.magma/magma.fidl

This protocol is used to retrieve information on the power levels that this driver provides.

GetClockSpeedLevel

Get a power level that represents the GPU clock being set to at least a target frequency. The power level may allow the GPU to idle or turn off, as long as the clock frequency remains the same.

Request

Name	Type
payload	PowerElementProviderGetClockSpeedLevelRequest

Response

Name	Type
payload	PowerElementProvider_GetClockSpeedLevel_Result

GetPowerGoals

Retrieve a list of power goals that the hardware can attempt to achieve.

Request

<EMPTY>

Response

Name	Type
payload	PowerElementProvider_GetPowerGoals_Result

SetClockLimit

Limit the clock to at most a specific frequency.

Request

Name	Type
payload	PowerElementProviderSetClockLimitRequest

Response

Name	Type
payload	PowerElementProvider_SetClockLimit_Result

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

Name	Type
pool_id	PerformanceCounterPoolId
offsets	vector<BufferRange>:64

BufferRangeOp2

Perform an operation on a range of the buffer.

Request

Name	Type
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

Name	Type
counters	PerformanceCounterSet

CreateContext

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

Request

Name	Type
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

Name	Type
pool_id	PerformanceCounterPoolId
event_channel	server_end:PerformanceCounterEvents

DestroyContext

Destroys context context_id.

Request

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
context_id	ContextId
resources	vector<BufferRange>
command_buffers	vector<CommandBuffer>
wait_semaphores	vector<ObjectId>
signal_semaphores	vector<ObjectId>
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

Name	Type
context_id	ContextId
command_data	vector<uint8>:2048
semaphores	vector<ObjectId>

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.

Request

Name	Type
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.

Request

Name	Type
payload	PrimaryImportObjectRequest

ImportObject2

Request

Name	Type
object	handle<handle>
object_type	ObjectType
object_id	ObjectId

IsPerformanceCounterAccessAllowed

Returns true if any EnablePerformanceCounterAccess message has succeeded.

Request

<EMPTY>

Response

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
count	uint64

ReleaseObject

Destroys the object with object_id within this connection.

Request

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
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

Name	Type
client_id	uint64
primary_channel	server_end:Primary
notification_channel	server_end:Notification

DumpState

Dumps driver and hardware state to the log.

Request

Name	Type
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

Name	Type
icd_list	vector<IcdInfo>:8

GetUnitTestStatus

Request

<EMPTY>

Response

Name	Type
status	zx/Status

Query

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

Request

Name	Type
query_id	QueryId

Response

Name	Type
payload	Device_Query_Result

STRUCTS

BufferRange

Defined in fuchsia.gpu.magma/magma.fidl

Field	Type	Description	Default
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).

Field	Type	Description	Default
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

PowerElementProvider_GetPowerGoals_Response resource

Defined in fuchsia.gpu.magma/magma.fidl

Field	Type	Description	Default
goals	vector<PowerGoal>		No default

ENUMS

BufferOp flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
POPULATE_TABLES	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.
DEPOPULATE_TABLES	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

Name	Value	Description
EVENT	10	Removed: 18 Deprecated: 17
BUFFER	11	A memory object backeed by a Zircon VMO.
SEMAPHORE	12	A sync object backed by a Zircon event or VMO. Added: 13

PowerGoalType flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Each element of this enum represents a high-level goal of a specific power state.

Name	Value	Description
ON_READY_FOR_WORK	1	The hardware is powered on, but idle and ready to immediately process work.
HIGH_PERFORMANCE	2	The hardware is in a high-performance state for gaming or other intensive activities.
SUSTAINED_PERFORMANCE	3	The hardware is in a mode that provides a consistent level of performance for a long period of time.

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.

Name	Value	Description
VENDOR_ID	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.
DEVICE_ID	1	Returns the hardware device ID (simple result)
VENDOR_VERSION	2	Returns the version of the vendor interfaces supported by the system driver. Added: 12
IS_TOTAL_TIME_SUPPORTED	3	Returns true if MAGMA_QUERY_TOTAL_TIME is supported (simple result)
MAXIMUM_INFLIGHT_PARAMS	5	Upper 32bits: max inflight messages, lower 32bits: max inflight memory (MB) (simple result)
MAGMA_QUERY_TOTAL_TIME	500	Returns a struct magma_total_time_query_result (buffer result); see: src/graphics/lib/magma/include/magma/magma_common_defs.h
VENDOR_QUERY_0	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.

Ordinal	Field	Type	Description
1	component_url	fuchsia.url/Url	URL of the component implementation that provides the ICD.
2	flags	IcdFlags	Flags describing the basic capabilities of the ICD, including what APIs it supports.

InlineCommand

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	data	vector<uint8>
2	semaphores	vector<ObjectId>

PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	trigger_id	PerformanceCounterTriggerId	Required.
2	buffer_id	ObjectId	Required.
3	buffer_offset	uint32	Required.
4	timestamp	zx/Time	Required.
5	flags	ResultFlags	Required.

PowerElementProviderGetClockSpeedLevelRequest

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	hz	uint64	Required. The target frequency.
2	allow_max	bool	If true and hz is greater than the maximum clock frequency, then the level corresponding to the greatest supported frequency will be returned. If not true (or not specified), this call will return ZX_ERR_OUT_OF_RANGE if hz is greater than the maximum clock frequency.

PowerElementProviderSetClockLimitRequest

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	hz	uint64	Required. The target frequency

PowerElementProvider_GetClockSpeedLevel_Response resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	token	handle<event>	Required. The fuchsia.power.broker.DependencyToken that must be leased.
2	level	uint8	Required. The level to lease token at.
3	actual_hz	uint64	Required. The target frequency that the level represents. If allow_max==false' (or allow_max isn't set) then this must be >= hz; otherwise, it can be any value relative to hz`.

PowerElementProvider_SetClockLimit_Response resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	handle	handle<eventpair>	Required. A handle representing this request; the clock limit will be honored as long as the handle is open.
2	actual_hz	uint64	Required. The actual frequency the clock is limited to. This may be more or less than hz.

PowerGoal resource

Defined in fuchsia.gpu.magma/magma.fidl

This table represents a specific power goal. The client must acquire a lease on the token to activate the state.

Ordinal	Field	Type	Description
1	type	PowerGoalType	Required.
2	token	handle<event>	Required. The fuchsia.power.broker.DependencyToken that must be leased at level 1 to achieve the goal.

PrimaryImportObjectRequest resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	object	Object	Required.
2	object_type	ObjectType	Required.
3	object_id	ObjectId	Required.
4	flags	ImportFlags	Optional

PrimaryMapBufferRequest

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	hw_va	uint64	Required.
2	range	BufferRange	Required.
3	flags	MapFlags

PrimaryUnmapBufferRequest

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Field	Type	Description
1	hw_va	uint64	Required.
2	buffer_id	ObjectId	Required.

UNIONS

Device_Query_Response strict resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	simple_result	uint64
2	buffer_result	handle<vmo>

Device_Query_Result strict resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	response	Device_Query_Response
2	err	zx/Status

Object flexible resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	semaphore	handle<event>
2	buffer	handle<vmo>
3	vmo_semaphore	handle<vmo>

PowerElementProvider_GetClockSpeedLevel_Result strict resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	response	PowerElementProvider_GetClockSpeedLevel_Response
2	err	zx/Status
3	framework_err	internal

PowerElementProvider_GetPowerGoals_Result strict resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	response	PowerElementProvider_GetPowerGoals_Response
3	framework_err	internal

PowerElementProvider_SetClockLimit_Result strict resource

Defined in fuchsia.gpu.magma/magma.fidl

Ordinal	Variant	Type	Description
1	response	PowerElementProvider_SetClockLimit_Response
2	err	zx/Status
3	framework_err	internal

BITS

CommandBufferFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
VENDOR_FLAG_0	65536	Vendor specific definitions start here

IcdFlags flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
SUPPORTS_VULKAN	1
SUPPORTS_OPENCL	2
SUPPORTS_MEDIA_CODEC_FACTORY	4

ImportFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
SEMAPHORE_ONE_SHOT	1

MapFlags flexible

Type: uint64

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
READ	1
WRITE	2
EXECUTE	4
GROWABLE	8	Uncommitted pages may be comitted on a hardware fault. If this flag is not set, access faults should cause an error.
VENDOR_FLAG_0	65536	Vendor specific definitions start here

ResultFlags flexible

Type: uint32

Defined in fuchsia.gpu.magma/magma.fidl

Name	Value	Description
DISCONTINUITY	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

Name	Value	Type	Description
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

Name	Value	Description
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

SERVICES

Service

Defined in fuchsia.gpu.magma/magma.fidl

Name	Type	Transport
device	fuchsia.gpu.magma/Device	Channel
power_element_provider	fuchsia.gpu.magma/PowerElementProvider	Channel