PROTOCOLS
Device
Defined in fuchsia.gpu.magma/magma.fidl
Connect
Get the magma ipc channels.
Request
| Name | Type |
|---|---|
client_id |
uint64
|
Response
| Name | Type |
|---|---|
primary_channel |
handle<channel>
|
notification_channel |
handle<channel>
|
DumpState
Dumps driver and hardware state.
Request
| Name | Type |
|---|---|
dump_type |
uint32
|
GetIcdList
Gets a list of ICDs that can be used with this magma device. The list is sorted in descending order of preference.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
icd_list |
vector<IcdInfo>[8]
|
GetUnitTestStatus
For testing only - on non-test drivers this will close the channel.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
zx/status
|
Query2
Returns a parameter, or an error.
Request
| Name | Type |
|---|---|
query_id |
uint64
|
Response
| Name | Type |
|---|---|
result |
Device_Query2_Result
|
QueryReturnsBuffer
Returns a buffer, or an error.
Request
| Name | Type |
|---|---|
query_id |
uint64
|
Response
| Name | Type |
|---|---|
result |
Device_QueryReturnsBuffer_Result
|
TestRestart
For testing only.
Request
| Name | Type |
|---|
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
| Name | Type |
|---|
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 |
|---|---|
trigger_id |
uint32
|
buffer_id |
zx/koid
|
buffer_offset |
uint32
|
timestamp |
zx/time
|
flags |
ResultFlags
|
Primary
Defined in fuchsia.gpu.magma/magma.fidl
If a system driver error occurs, the connection will be closed and a Status sent via epitaph. If negative, the Epitaph represents a Zircon error.
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
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
pool |
PerfCountPoolId
|
offsets |
vector<BufferOffset>[64]
|
BufferRangeOp
Perform an operation on a range of the buffer, starting at start_bytes and length bytes
long.
Request
| Name | Type |
|---|---|
buffer_id |
zx/koid
|
op |
BufferOp
|
start_bytes |
uint64
|
length |
uint64
|
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
| Name | Type |
|---|---|
counters |
vector<uint64>[64]
|
CommitBuffer
DEPRECATED and replaced by BufferOp.POPULATE_TABLES. Ensures that page_count pages
starting at page_offset from the beginning of the buffer are backed by physical memory.
Request
| Name | Type |
|---|---|
buffer_id |
zx/koid
|
page_offset |
uint64
|
page_count |
uint64
|
CreateContext
Creates context context_id.
Request
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
pool |
PerfCountPoolId
|
event_channel |
request<PerformanceCounterEvents>
|
DestroyContext
Destroys context context_id.
Request
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
pool |
PerfCountPoolId
|
trigger_id |
uint32
|
EnableFlowControl
Enables the events OnNotifyMessagesConsumed and OnNotifyMemoryImported.
Request
| Name | Type |
|---|
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
| Name | Type |
|---|---|
counters |
vector<uint64>[64]
|
ExecuteCommandBufferWithResources
Submits a command buffer for execution on the GPU, with associated resources.
Request
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
context_id |
uint32
|
command_data |
vector<uint8>[2048]
|
semaphores |
vector<uint64>
|
GetError
Deprecated: Retrieve the current magma error status.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
magma_status |
int32
|
ImportBuffer
Imports a buffer for use in the system driver.
Request
| Name | Type |
|---|---|
buffer |
handle<vmo>
|
ImportObject
Imports an object for use in the system driver.
Request
| Name | Type |
|---|---|
object |
handle<handle>
|
object_type |
uint32
|
IsPerformanceCounterAccessEnabled
Returns true if any AccessPerformanceCounters message has succeeded.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
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
| 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) <= 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
| Name | Type |
|---|---|
count |
uint64
|
ReleaseBuffer
Destroys the buffer with buffer_id within this connection.
Request
| Name | Type |
|---|---|
buffer_id |
zx/koid
|
ReleaseObject
Destroys the object with object_id within this connection.
Request
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
pool |
PerfCountPoolId
|
buffer_id |
zx/koid
|
Sync
Incurs a round-trip to the system driver, used to ensure all previous messages are seen.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|
UnmapBufferGpu
Releases the mapping at gpu_va from the GPU.
Buffers will also be implicitly unmapped when released.
Request
| Name | Type |
|---|---|
buffer_id |
zx/koid
|
gpu_va |
uint64
|
STRUCTS
BufferOffset
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description | Default |
|---|---|---|---|
buffer_id |
zx/koid
|
No default | |
offset |
uint64
|
No default | |
size |
uint64
|
No default |
CommandBuffer
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description | Default |
|---|---|---|---|
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
| Name | Type | Description | Default |
|---|---|---|---|
result |
uint64
|
No default |
Device_QueryReturnsBuffer_Response
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description | Default |
|---|---|---|---|
buffer |
handle<vmo>
|
No default |
Resource
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description | Default |
|---|---|---|---|
buffer |
zx/koid
|
No default | |
offset |
uint64
|
No default | |
length |
uint64
|
No default |
ENUMS
BufferOp
Type: uint32
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Value | Description |
|---|---|---|
POPULATE_TABLES |
1 |
Eagerly populate GPU page tables with the pages mapping in this range, committing pages as needed. This is not needed for MAGMA_GPU_MAP_FLAG_GROWABLE allocations, since the page tables will be populated on demand. |
DEPOPULATE_TABLES |
2 |
Depopulate GPU page table mappings for this range. This prevents the GPU from accessing pages in that range, but the pages retain their contents. |
QueryId
Type: uint32
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Value | Description |
|---|---|---|
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
| Name | Value | Description |
|---|---|---|
INTERNAL_ERROR |
1 |
|
INVALID_ARGS |
2 |
|
ACCESS_DENIED |
3 |
|
MEMORY_ERROR |
4 |
|
CONTEXT_KILLED |
5 |
|
CONNECTION_LOST |
6 |
|
TIMED_OUT |
7 |
|
UNIMPLEMENTED |
8 |
|
BAD_STATE |
9 |
An object was not in the right state for an operation on it. |
TABLES
IcdInfo
Defined in fuchsia.gpu.magma/magma.fidl
Information about an ICD implementation that can be used with a magma device.
| Ordinal | Name | 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. |
UNIONS
Device_Query2_Result
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description |
|---|---|---|
response |
Device_Query2_Response
|
|
err |
Status
|
Device_QueryReturnsBuffer_Result
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Type | Description |
|---|---|---|
response |
Device_QueryReturnsBuffer_Response
|
|
err |
Status
|
BITS
IcdFlags
Type: uint32
Defined in fuchsia.gpu.magma/magma.fidl
| Name | Value | Description |
|---|---|---|
| SUPPORTS_VULKAN | 1 |
ResultFlags
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 GPU being in protected mode for part of the time. |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| MAX_ICD_COUNT |
8
|
uint64 |
|
| MAX_IMMEDIATE_COMMANDS_DATA_SIZE |
2048
|
uint32 |
The batch size used to send multiple immediate commands in a single message. |
TYPE ALIASES
| Name | Value | Description |
|---|---|---|
| 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. |