Fuchsia.gpu.magma

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 Device 通訊協定，用戶端可以執行查詢 (例如裝置和廠商 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

Primary

定義於 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

啟用 OnNotifyMessagesConsumed 和 OnNotifyMemoryImported。

要求

<EMPTY>

EnablePerformanceCounterAccess

嘗試啟用效能計數器 FIDL 訊息。如要成功，

要求

名稱	類型
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)。這項軟性限制旨在防止記憶體用量過大，但用戶端如果傳送大型訊息，可能會超過限制。伺服器會盡快匯入記憶體，但只有在耗用的位元組數量達到上限的一半時，才會傳送這個事件；因此，如果用戶端的傳輸位元組數少於上限/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	資源中的起始偏移。	無預設

ENUMS

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 基本功能的旗標，包括 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

序數	Variant	類型	說明
1	simple_result	uint64
2	buffer_result	handle<vmo>

Device_Query_Result 嚴格 資源

定義於 fuchsia.gpu.magma/magma.fidl

序數	Variant	類型	說明
1	response	Device_Query_Response
2	err	zx/Status

物件彈性 資源

定義於 fuchsia.gpu.magma/magma.fidl

序數	Variant	類型	說明
1	semaphore	handle<event>
2	buffer	handle<vmo>
3	vmo_semaphore	handle<vmo>

帳單

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