Magma 是 Fuchsia 上 GPU/NPU 的驱动程序模型。
Magma 有两个驱动程序组件：一个是加载到每个应用地址空间的硬件专用库（“客户端驱动程序”，有时称为“可安装的客户端驱动程序”或“ICD”）；以及一个与硬件进行交互的 Magma 系统驱动程序。此处定义了两个驱动程序部分之间的通信协议。
有些名称带有数字后缀（例如 BufferRangeOp2）；数字后缀是协议演变过程的详细信息，可以忽略。
协议
CombinedDevice
在 fuchsia.gpu.magma/magma.fidl 中定义
所有生产 |Device| 协议的组合。此协议在 Magma 服务端实现，客户端不应使用。
Connect2
创建与由两个 IPC 通道组成的设备连接。 主通道用于连接主要协议（见下文）。通知渠道用于仅以反向（服务器-客户端）方向的供应商特定消息，通常是在响应客户端命令完成时发送。
请求
| 名称 | 类型 |
|---|---|
client_id |
uint64
|
primary_channel |
server_end<Primary>
|
notification_channel |
server_end<Notification>
|
DumpState
将驱动程序和硬件状态转储到日志。
请求
| 名称 | 类型 |
|---|---|
dump_type |
uint32
|
GetIcdList
返回可与此 Magma 设备搭配使用的 ICD 列表。该列表按优先顺序降序排序。
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
icd_list |
vector<IcdInfo>[8]
|
查询
如果成功，则以缓冲区或简单值的形式返回结果。
请求
| 名称 | 类型 |
|---|---|
query_id |
QueryId
|
响应
| 名称 | 类型 |
|---|---|
payload |
Device_Query_Result
|
DependencyInjection
在 fuchsia.gpu.magma/magma.fidl 中定义
此协议由 ZX_PROTOCOL_GPU_DEPENDENCY_INJECTION 设备实现。用于将其他服务的依赖项注入 MSD。它只能由特权进程使用。
SetMemoryPressureProvider
为 MSD 提供 fuchsia.memorypressure.Provider 实现。
请求
| 名称 | 类型 |
|---|---|
provider |
fuchsia.memorypressure/Provider
|
设备
在 fuchsia.gpu.magma/magma.fidl 中定义
Magma 设备协议允许客户端通过进行查询（例如设备和供应商 ID）来了解硬件，以及设备的系统驱动程序支持哪些客户端驱动程序。
为了与设备进一步互动，客户端可以建立由通道对组成的连接：用于发出请求的主通道（请参阅下文的主要协议）和用于接收通知消息的辅助通道（请参阅下面的通知协议）。
Connect2
创建与由两个 IPC 通道组成的设备连接。 主通道用于连接主要协议（见下文）。通知渠道用于仅以反向（服务器-客户端）方向的供应商特定消息，通常是在响应客户端命令完成时发送。
请求
| 名称 | 类型 |
|---|---|
client_id |
uint64
|
primary_channel |
server_end<Primary>
|
notification_channel |
server_end<Notification>
|
查询
如果成功，则以缓冲区或简单值的形式返回结果。
请求
| 名称 | 类型 |
|---|---|
query_id |
QueryId
|
响应
| 名称 | 类型 |
|---|---|
payload |
Device_Query_Result
|
DiagnosticDevice
在 fuchsia.gpu.magma/magma.fidl 中定义
用于公开 Magma 设备诊断的方法。
DumpState
将驱动程序和硬件状态转储到日志。
请求
| 名称 | 类型 |
|---|---|
dump_type |
uint32
|
IcdLoaderDevice
在 fuchsia.gpu.magma/magma.fidl 中定义
由 MSD 实现，且可供使用 ICD 加载程序公开的方法。
GetIcdList
返回可与此 Magma 设备搭配使用的 ICD 列表。该列表按优先顺序降序排序。
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
icd_list |
vector<IcdInfo>[8]
|
通知
在 fuchsia.gpu.magma/magma.fidl 中定义
此协议为空，因为消息内容取决于供应商。
PerformanceCounterAccess
在 fuchsia.gpu.magma/magma.fidl 中定义
此协议由 ZX_PROTOCOL_GPU_PERFORMANCE_COUNTERS 设备实现。
GetPerformanceCountToken
此访问令牌不用作事件，而是传递给 Primary.EnablePerformanceCounterAccess。
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
access_token |
handle<event>
|
PerformanceCounterEvents
在 fuchsia.gpu.magma/magma.fidl 中定义
OnPerformanceCounterReadCompleted
表示性能计数器缓冲区有数据。这些数据将按照读取完成的顺序输出。
响应
| 名称 | 类型 |
|---|---|
payload |
PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest
|
主要
在 fuchsia.gpu.magma/magma.fidl 中定义
如果发生系统驱动程序错误，或者客户端发送一条消息表明客户端应已知无效，则连接将关闭并通过 epitaph 发送 zx.Status。
AddPerformanceCounterBufferOffsetsToPool
向池的缓冲区添加一组偏移量。|offsets[n].buffer_id| 是之前使用 ImportBuffer() 导入的缓冲区的 ID。相同的缓冲区可以添加到多个池中。即使在调用 ReleaseBuffer 之后，该池也会保留对缓冲区的引用。当转储到此条目时，计数器将从 |offsets[n].buffer_offset| 字节开始写入缓冲区，直到 |offsets[n].buffer_offset| + |offsets[n].buffer_size|。|offsets[n].buffer_size| 必须足够大，以容纳所有已启用的计数器。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
pool_id |
PerformanceCounterPoolId
|
offsets |
vector<BufferRange>[64]
|
BufferRangeOp2
对相应缓冲区范围执行操作。
请求
| 名称 | 类型 |
|---|---|
op |
BufferOp
|
range |
BufferRange
|
ClearPerformanceCounters
将列出的所有性能计数器的值设置为 0。某些硬件可能不支持。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
counters |
PerformanceCounterSet
|
CreateContext
创建上下文 context_id，以便在命令执行中使用。上下文可能与硬件状态相关联。
请求
| 名称 | 类型 |
|---|---|
context_id |
ContextId
|
CreatePerformanceCounterBufferPool
创建可将性能计数器转储到的缓冲区池。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
pool_id |
PerformanceCounterPoolId
|
event_channel |
server_end<PerformanceCounterEvents>
|
DestroyContext
销毁上下文 context_id。
请求
| 名称 | 类型 |
|---|---|
context_id |
ContextId
|
DumpPerformanceCounters
触发器将性能计数器转储到缓冲池。如果池中没有缓冲区，则可能会静默失败。|trigger_id| 是由客户端分配的任意 ID，可在 OnPerformanceCounterReadCompleted 中返回。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
pool_id |
PerformanceCounterPoolId
|
trigger_id |
PerformanceCounterTriggerId
|
EnableFlowControl
启用 OnNotificationsMessagesConsumed 和 OnNotificationsMemoryImported 事件。
请求
<EMPTY>
EnablePerformanceCounterAccess
尝试启用性能计数器 FIDL 消息。如要验证成功，PerformanceCounterAccess.GetPerformanceCountToken() 必须已从匹配设备返回 |access_token|。
请求
| 名称 | 类型 |
|---|---|
access_token |
handle<event>
|
EnablePerformanceCounters
启用一组性能计数器。停用不在新集合中的已启用性能计数器。连接关闭时，性能计数器也将自动停用。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
counters |
PerformanceCounterSet
|
ExecuteCommand
通过关联的 resources 提交命令缓冲区以在硬件上执行。
resources 必须引用已导入的缓冲区。wait_semaphores 和 signal_semaphores 必须引用已导入的事件。wait_semaphores 在开始执行之前必须全部收到信号，然后重置。命令缓冲区完成后，signal_semaphores 将收到信号。
请求
| 名称 | 类型 |
|---|---|
context_id |
ContextId
|
resources |
vector<BufferRange>
|
command_buffers |
vector<CommandBuffer>
|
wait_semaphores |
vector<uint64>
|
signal_semaphores |
vector<uint64>
|
flags |
CommandBufferFlags
|
ExecuteImmediateCommands
提交一系列命令，以便在不使用命令缓冲区的情况下在硬件上执行。
semaphores 必须引用已导入的事件，并且将在命令完成后收到信号。
请求
| 名称 | 类型 |
|---|---|
context_id |
ContextId
|
command_data |
vector<uint8>[2048]
|
semaphores |
vector<uint64>
|
ExecuteInlineCommands
提交一系列命令，以便在不使用命令缓冲区的情况下在硬件上执行。 应计算发送的命令数，使总消息大小小于 MAX_INLINE_commandS_DATA_SIZE。
请求
| 名称 | 类型 |
|---|---|
context_id |
ContextId
|
commands |
vector<InlineCommand>
|
清空
引发到系统驱动程序的往返，用于确保所有先前的消息已被观察但不一定已完成。
请求
<EMPTY>
响应
<EMPTY>
ImportObject
导入要在系统驱动程序中使用的对象。
请求
| 名称 | 类型 |
|---|---|
payload |
PrimaryImportObjectRequest
|
ImportObject2
请求
| 名称 | 类型 |
|---|---|
object |
handle<handle>
|
object_type |
ObjectType
|
object_id |
ObjectId
|
IsPerformanceCounterAccessAllowed
如果任何 EnablePerformanceCounterAccess 消息成功，则返回 true。
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
enabled |
bool
|
MapBuffer
将页面范围映射到硬件上的连接地址空间中（地址为 hw_va）。flags 是 MapFlags 中的一组标志，用于指定硬件如何访问缓冲区。
请求
| 名称 | 类型 |
|---|---|
payload |
PrimaryMapBufferRequest
|
OnNotifyMemoryImported
表示服务器导入的给定缓冲区内存字节数。 调用方应限制传输中的 ImportBuffer 消息的内存量：（发送的字节数 - 服务器导入的字节数）<= MaxBytes（请参阅 QueryId::MAXIMUM_INFlight_PARAMS）。这是一个软性限制，旨在防止过多的内存消耗，但对于大型消息，客户端可能会超过该限制。服务器会尽快导入内存，但只有当已用字节数达到上限一半时，系统才会发送此事件；因此，如果客户端的传输字节数小于 max/2，客户端应发送 ImportBuffer 消息（无论其大小如何）。
响应
| 名称 | 类型 |
|---|---|
bytes |
uint64
|
OnNotifyMessagesConsumed
表示服务器使用的指定数量的消息。 调用方应限制传输中消息的数量：（发送的消息 - 消耗的服务器）<= MaxMessages（请参阅 QueryId::MAXIMUM_INFlight_PARAMS）。实际上，消息会尽快被服务器使用，但只有在已使用的数量达到最大值的一半时，服务器才会发送此事件。
响应
| 名称 | 类型 |
|---|---|
count |
uint64
|
ReleaseObject
在此连接内使用 object_id 销毁对象。
请求
| 名称 | 类型 |
|---|---|
object_id |
ObjectId
|
object_type |
ObjectType
|
ReleasePerformanceCounterBufferPool
释放性能计数器缓冲区池。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
pool_id |
PerformanceCounterPoolId
|
RemovePerformanceCounterBufferFromPool
从池中移除缓冲区的每个偏移量。在服务器上完成此方法处理后，不会再将转储发送到此缓冲区。到此缓冲区的正在执行的转储可能会丢失。在调用此方法之前，必须使用 EnablePerformanceCounterAccess 启用性能计数器访问权限。
请求
| 名称 | 类型 |
|---|---|
pool_id |
PerformanceCounterPoolId
|
buffer_id |
ObjectId
|
UnmapBuffer
针对给定 buffer_id 从硬件释放地址 hw_va 的映射。缓冲区在释放时也会隐式取消映射。
请求
| 名称 | 类型 |
|---|---|
payload |
PrimaryUnmapBufferRequest
|
TestDevice
在 fuchsia.gpu.magma/magma.fidl 中定义
用于测试 MSD 的其他设备方法，不应供 ICD 使用。
Connect2
创建与由两个 IPC 通道组成的设备连接。 主通道用于连接主要协议（见下文）。通知渠道用于仅以反向（服务器-客户端）方向的供应商特定消息，通常是在响应客户端命令完成时发送。
请求
| 名称 | 类型 |
|---|---|
client_id |
uint64
|
primary_channel |
server_end<Primary>
|
notification_channel |
server_end<Notification>
|
DumpState
将驱动程序和硬件状态转储到日志。
请求
| 名称 | 类型 |
|---|---|
dump_type |
uint32
|
GetIcdList
返回可与此 Magma 设备搭配使用的 ICD 列表。该列表按优先顺序降序排序。
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
icd_list |
vector<IcdInfo>[8]
|
GetUnitTestStatus
请求
<EMPTY>
响应
| 名称 | 类型 |
|---|---|
status |
zx/Status
|
查询
如果成功，则以缓冲区或简单值的形式返回结果。
请求
| 名称 | 类型 |
|---|---|
query_id |
QueryId
|
响应
| 名称 | 类型 |
|---|---|
payload |
Device_Query_Result
|
结构
BufferRange
在 fuchsia.gpu.magma/magma.fidl 中定义
| 字段 | 类型 | 说明 | 默认 |
|---|---|---|---|
buffer_id |
ObjectId
|
无默认取景方式 | |
offset |
uint64
|
无默认取景方式 | |
size |
uint64
|
无默认取景方式 |
CommandBuffer
在 fuchsia.gpu.magma/magma.fidl 中定义
命令缓冲区可用于在共享缓冲区 (VMO) 中传递硬件指令。
| 字段 | 类型 | 说明 | 默认 |
|---|---|---|---|
resource_index |
uint32
|
包含启动命令缓冲区的指令的资源索引。 |
无默认取景方式 |
start_offset |
uint64
|
资源内的起始偏移量。 |
无默认取景方式 |
枚举
BufferOp 灵活
类型：uint32
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
POPULATE_TABLES |
1 |
使用此范围内映射的页面填充硬件页面表格，根据需要提交页面。映射为 GROWABLE 的分配无需执行此操作，因为页面表格会按需填充。 |
DEPOPULATE_TABLES |
2 |
正在取消填充此范围的网页表格映射。这样可以阻止硬件访问该范围内的页面，但页面会保留其内容。 |
ObjectType 灵活
类型：uint32
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
活动 |
10 |
已移除：18 已弃用：17
|
BUFFER |
11 |
由 Zircon VMO 提供支持的内存对象。 |
屏幕画面 |
12 |
由 Zircon 事件或 VMO 支持的同步对象。 添加数量：13
|
QueryId 灵活
类型：uint64
在 fuchsia.gpu.magma/magma.fidl 中定义
可通过 Magma 系统驱动程序查询的硬件和驱动程序相关信息类型。您也可以使用供应商特定的 ID 号，但这些 ID 会在其他位置列出。
| 名称 | 值 | 说明 |
|---|---|---|
VENDOR_ID |
0 |
返回硬件供应商 ID（简单结果）- 如果可能，应为硬件供应商的 PCI ID，否则应为 Khronos 供应商 ID。 |
DEVICE_ID |
1 |
返回硬件设备 ID（简单结果） |
VENDOR_VERSION |
2 |
返回系统驱动程序支持的供应商接口的版本。 添加数量：12
|
IS_TOTAL_TIME_SUPPORTED |
3 |
如果支持 MAGMA_QUERY_TOTAL_TIME，则返回 true（简单结果） |
MAXIMUM_INFLIGHT_PARAMS |
5 |
高 32 位：最大传输中消息数，低 32 位：最大动态内存 (MB)（简单结果） |
MAGMA_QUERY_TOTAL_TIME |
500 |
返回结构体 magma_total_time_query_result（缓冲区结果）；请参阅：src/graphics/lib/magma/include/magma/magma_common_defs.h |
VENDOR_QUERY_0 |
10000 |
供应商专用查询 ID 从此处开始 |
表
IcdInfo
在 fuchsia.gpu.magma/magma.fidl 中定义
可与 Magma 设备搭配使用的 ICD 实现的信息。
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
component_url |
fuchsia.url/Url
|
提供 ICD 的组件实现的网址。 |
2 |
flags |
IcdFlags
|
用于描述 ICD 基本功能（包括其支持的 API）的标志。 |
InlineCommand
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
data |
vector<uint8>
|
|
2 |
semaphores |
vector<uint64>
|
PerformanceCounterEventsOnPerformanceCounterReadCompletedRequest
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
trigger_id |
PerformanceCounterTriggerId
|
必选。 |
2 |
buffer_id |
ObjectId
|
必选。 |
3 |
buffer_offset |
uint32
|
必选。 |
4 |
timestamp |
zx/Time
|
必选。 |
5 |
flags |
ResultFlags
|
必选。 |
PrimaryImportObjectRequest 资源
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
object |
Object
|
必选。 |
2 |
object_type |
ObjectType
|
必选。 |
3 |
object_id |
ObjectId
|
必选。 |
4 |
flags |
ImportFlags
|
可选 |
PrimaryMapBufferRequest
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
hw_va |
uint64
|
必选。 |
2 |
range |
BufferRange
|
必选。 |
3 |
flags |
MapFlags
|
PrimaryUnmapBufferRequest
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 字段 | 类型 | 说明 |
|---|---|---|---|
1 |
hw_va |
uint64
|
必选。 |
2 |
buffer_id |
ObjectId
|
必选。 |
联合
Device_Query_Response 严格 资源
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 变体 | 类型 | 说明 |
|---|---|---|---|
1 |
simple_result |
uint64
|
|
2 |
buffer_result |
handle<vmo>
|
Device_Query_Result 严格 资源
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 变体 | 类型 | 说明 |
|---|---|---|---|
1 |
response |
Device_Query_Response
|
|
2 |
err |
zx/Status
|
对象灵活 资源
在 fuchsia.gpu.magma/magma.fidl 中定义
| 序数 | 变体 | 类型 | 说明 |
|---|---|---|---|
1 |
semaphore |
handle<event>
|
|
2 |
buffer |
handle<vmo>
|
|
3 |
vmo_semaphore |
handle<vmo>
|
BITS
CommandBufferFlags灵活
类型：uint64
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
VENDOR_FLAG_0 |
65536 | 供应商专用定义从这里开始 |
IcdFlags
类型：uint32
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
SUPPORTS_VULKAN |
1 | |
SUPPORTS_OPENCL |
2 | |
SUPPORTS_MEDIA_CODEC_FACTORY |
4 |
ImportFlags 灵活
类型：uint64
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
SEMAPHORE_ONE_SHOT |
1 |
MapFlags
类型：uint64
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
读取 |
1 | |
写入 |
2 | |
执行 |
4 | |
推动业务增长 |
8 | 出现硬件故障时可能会出现未提交的页面。如果未设置此标志，访问故障应该会导致错误。 |
VENDOR_FLAG_0 |
65536 | 供应商专用定义从这里开始 |
ResultFlags 灵活
类型：uint32
在 fuchsia.gpu.magma/magma.fidl 中定义
| 名称 | 值 | 说明 |
|---|---|---|
不连续 |
1 | 如果性能计数器遗漏了一些样本（例如，由于硬件在一段时间内处于保护模式），则会在 result_flags 中设置该位。 |
常量
| 名称 | 值 | 类型 | 说明 |
|---|---|---|---|
| MAX_ICD_COUNT |
8
|
uint64 |
Magma 系统驱动程序支持的 ICD 数量上限。 |
| MAX_IMMEDIATE_COMMANDS_DATA_SIZE |
2048
|
uint32 |
用于在单个消息中发送多个即时命令的批次大小。 |
| MAX_INLINE_COMMANDS_DATA_SIZE |
2048
|
uint32 |
用于在单个消息中发送多个内嵌命令的批次大小。 添加数量：15
|
别名
| 名称 | 值 | 说明 |
|---|---|---|
| ContextId |
uint32 |
|
| ObjectId |
uint64 |
|
| PerformanceCounterPoolId |
uint64 |
性能计数器池包含缓冲区的字节范围。每当触发性能计数器转储时，驱动程序就会从池中移除一个范围，将性能计数器值从硬件写入其中，然后使用 OnPerformanceCounterReadCompleted 向客户端发出信号。池 ID 是客户端分配的任意 uint64 值。 |
| PerformanceCounterSet |
vector[64] |
描述一组性能计数器。确切含义取决于特定驱动程序，但通常是一个位矢量，表示每个性能计数器是处于启用状态还是处于停用状态。 |
| PerformanceCounterTriggerId |
uint32 |