Magma：移植指南

如需 Magma 的總覽，包括背景、硬體需求和 架構說明，請參閱 Magma：總覽。

本文件提供驅動程式庫開發人員可遵循的程序，以轉移 Vulkan Fuchsia 的驅動程式庫。

需求條件

如要將 Vulkan 驅動程式庫轉移至 Fuchsia，您必須符合以下條件：

  • 硬體說明文件 (註冊規格、作業理論)。
  • 使用 Vulkan 實作 (Linux) 的參考資源。
  • 用戶端驅動程式庫庫程式庫 (ICD) 應提供符合規範的實作方式 。

硬體必須通過啟動，網路存取權、磁碟儲存空間 和 fx pave 函式。

Magma 目前只支援 UMA 裝置，但如果您使用意願， 可能會嘗試移植到具有獨立記憶體的 GPU。

建立虛設常式系統驅動程式庫

Magma 系統驅動程式庫 (MSD) 與另一個 以及作業系統此時，請考慮是否要移植現有的核心 從其他作業系統驅動程式庫，或從頭開始編寫。

在此階段，請務必詳閱「驅動因素」一節， 我們須瞭解 Fuchsia 驅動程式庫模型

這個選擇取決於現有核心驅動程式庫程式碼的許多層面。 請考量以下事項：

  • 驅動程式庫是否有平台抽象層，還是是否依附於 Linux 核心介面？
  • 授權。
  • 其 ioctl 介面與 Magma 進入點有何相似之處？

程式設計第一步是建立基本的 MSD。MSD 所在位置 位於驅動程式庫目錄中。這些資料庫是以 fuchsia_drivers 的身分建構 建構應用程式Magma 系統驅動程式庫必須是開放原始碼 而非 GPL，託管在 fuchsia.googlesource.com 上。

Fuchsia 驅動程式是正常的使用者空間處理程序。也就是說，這些使用者可以存取 大部分 c 程式庫以及部分 POSIX API。取消喜歡 ，不允許任何檔案系統存取。

Magma 目前支援兩種不同類型的裝置：平台裝置 以及 PCI 裝置

  • SoC 通常有平台裝置。這些並不是隨插即用 需要主機驅動程式才能委派適當的資源
  • PCI 裝置位於 PCI 匯流排，為委派資源 使用 PCI 匯流排驅動程式

兩者皆受到 Fuchsia 驅動程式庫程式架構支援，因此 建立並繫結至一般 Fuchsia 驅動程式。

或是劃分責任？(SoC 版本)

在 SoC 上，GPU 硬體通常會是獨立的 IP 區塊 按照 SoC 廠商自訂的內容視自訂的程度而定 有幾個方法或許能達成這個目標。

  • 整合 MSD，但先前曾載入一個 SoC 專用驅動程式庫。
  • 請為每個 SoC 或 SoC 廠商建立個別的 MSD。

如果自訂 SoC 的自訂尺寸較小，最好 MSD.供應商專屬的驅動程式庫會先繫結，並匯出 banjo 可讓 MSD 開啟/關閉 GPU、變更時鐘等。 簡單來說，將 MSD 移植到新硬體上。 以實作新的供應商專屬驅動程式庫來修改。詳情請見 msd-arm-mali 和 aml-gpu 為例 。

為每個 SoC 使用不同的 MSD，可讓您擁有更多彈性，可能 或是 GPU IP 供應商允許對 SoC 中的 IP 區塊進行多項自訂。 不同 SoC 實作的 MSD 可能會共用獨立 SoC 的資料庫 但會成為獨立驅動程式

或是劃分責任？(PCI 版本)

PCI GPU 通常包含顯示控制器硬體。顯示控制器 驅動程式庫在理想情況下 應與 GPU 硬體分開實作 因此這些資料可儲存在 啟動 也能啟用啟動 Pod 才有機會存取磁碟螢幕控制器應會公開 硬體專屬的 banjo 介面，而 MSD 可以繫結至 顯示驅動程式庫。

請參閱 msd-intel-gen 和 intel-display，以瞭解 一個 PCI 驅動程式庫程式，分成兩個部分

開機中

現在建構 MSD 後，下一步就是編寫程式碼來重設裝置 再進入作業模式這類資訊可能包括：

駕駛人也應視需要存取 MMIO 範圍，並應該啟動 處理中斷針對 SoC，主機板驅動程式必須 以便將這些資源傳遞至 MSD 或 SoC 專用的驅動程式庫，且必須 為 MSD 新增繫結的裝置。

在此階段測試：

  • 在驅動程式庫啟動時記錄 MMIO 登錄。

實作 MSD

以下是驅動程式庫可實作的主要函式清單：

  • 初始化硬體
    • msd_driver_create
    • msd_driver_configure
    • msd_driver_destroy
    • msd_driver_create_device
    • msd_device_destroy
  • 支援參數查詢
    • msd_device_query
  • 支援狀態傾印
    • msd_device_dump_status
  • 建立連線
    • msd_device_open
    • msd_connection_close
  • 建立緩衝區
    • msd_buffer_import
    • msd_buffer_destroy
  • 設定記憶體空間和緩衝區對應
    • msd_connection_map_buffer_gpu
    • msd_connection_unmap_buffer_gpu
    • msd_connection_commit_buffer
    • msd_connection_release_buffer
  • 設定硬體結構定義
    • msd_connection_create_context
    • msd_context_destroy
  • 指令緩衝區排程
    • msd_context_execute_command_buffer
    • msd_context_execute_immediate_commands
    • msd_connection_set_notification_callback
  • 建立季節性變化
    • msd_semaphore_import
    • msd_semaphore_destroy
  • 錯誤處理
  • 電源管理

硬體順利開機後，下一步就是決定 將現有的橢圓形對應至 MSD 進入點。

在大多數情況下，linux DRI ioctls 和 MSD 函式的對應比較是 第一個主要難題是無法以直接簡單的方式 評估負責任的 AI 技術做法成效唯一的例外是記憶體管理 在 Magma 中 是配置和對應記憶體的 ICD，而非 MSD (或核心驅動程式庫)。 這可能會改變分配 VMO 的部分指令流程，因為 MSD 必須將既有的緩衝區匯入 GPU 硬體。

如果這個方法不適用於某些類型的記憶體，驅動程式庫可能會 使用 Sysmem 堆積來處理該記憶體的配置。用戶端 使用 Sysmem 配置記憶體，並使用一般 Magma 匯入控點 存取 API接著，MSD 可以與 sysmem 通訊以取得更多資訊 對記憶有某種概念

驅動程式可能不會要求實作所有函式。建議做法 視需要根據 ICD 逐步實作 MSD 函式。這可讓您 瞭解實作 MSD 函式時的背景資訊，有助於避免浪費心力。 不需要用到函式

在此階段測試：

  • 驅動程式庫專屬的單元測試 (非硬體專用)
  • 硬體專屬驅動程式庫測試 (請參閱範例)。這些測試 應該盡量精簡地使用 GPU，例如寫入暫存器或 這可讓 GPU 修改記憶體位置
  • 使用 Magma 介面的驅動程式庫專屬整合測試。
  • 磁性符合性測試 (Magma L0 的一部分)。
  • magma-info-test (Magma L0 的一部分)。

建立 ICD

IHV ICD 必須移植到富奇西亞。應使用 Bazel 建構 ICD SDK。ICD 建構作業可以移植至 Bazel 使用 Bazel 建構作業rules_foreign_cc 說明瞭如何 納入現有建構作業

基於 ICD abi 限制，ICD 必須以靜態方式連結 ICD 並依據所有依附元件使用者只能參照以下共用程式庫：

  • libc.so
  • libzircon.so

這會限制 ICD 可使用的依附元件。以下列舉 程式庫和可能的替換項目：

在這個階段，您可以視需求找到所有其他參照。ICD 必須 也可連結至 SDK 中提供的 Magma 執行階段程式庫 @fuchsia_pkg//pkg/magma_client.

Vulkan 載入器服務會從套件擷取 ICD 並通告 Vulkan 用戶端。ICD 必須包含在含有中繼資料的 Fuchsia 套件中， 資訊清單 JSON 檔案 (如載入器服務中所述) 說明文件。系統可透過以下方式，向裝置提供這個套件： Bazel SDK 存放區指令

如果 ICD 套件包含在宇宙內 透過執行 fx shell killall vulkan_loader.cm 重新載入。已發布的元件 之後就會收到新的 ICD 套件，舊版組件則會在 建立 Vulkan 例項

ICD 必須匯出一組特定符號，詳情請參閱 Vulkan ABI 定義您應該在這個階段實作這些方法。

在此階段測試：

  • 共用程式庫的 readelf -d，確保除了依附元件之外 libc.so和libzircon.so。
  • 使用 fx shell cat /svc/fuchsia.vulkan.loader.Loader 啟動 vulkan 載入器，並檢查 ffx inspect show core/vulkan_loader，確認是否已載入。錯誤會歸入 Syslog。
  • 執行 vulkan_icd_load 測試。這項測試會檢查是否有 系統支援 ICD，所以在運作之前，請確保系統沒有其他 ICD 沒有問題

將 ICD 連線至 Magma

此時 ICD 會連線至 /loader-gpu-devices/class/gpu 並透過提供給 Cloud Shell 的回呼 vk_icdInitializeOpenInNamespaceCallback。ICD 可以列出 透過 fuchsia.io.Directory FIDL 通訊協定提交的內容。這個目錄包含 系統中所有 MSD 的裝置節點，每個節點都以專屬的三位數代表 號碼。數據在開機時可保持穩定，但只要 MSD 更新時， 已重新載入，例如裝置重新啟動。

每個 Magma 裝置路徑都能透過 vk_icdInitializeOpenInNamespaceCallback，而產生的 Zircon 管道可以 透過 magma_device_import 提供給 libmagma。如果有 系統上有多部 Magma 裝置，則驅動程式庫必須使用 magma_query 使用 MAGMA_QUERY_VENDOR_ID 決定要使用的裝置。

在此階段後，magma_* 函式就能正常運作，因此 ioctl() 回呼可逐漸轉換成對等的 Magma 呼叫。

在此階段測試：

  • vkreadback (繪製顏色，然後讀取 framebuffer) )。這是 Magma L0 的一部分。
  • Vulkan 一致性測試。理想情況下，合格進度為 100% 因此模型會檢查完成詳情請參閱 Magma 測試策略。

移除不允許的符號

連結 ICD 時，請使用版本指令碼，確保指令碼 只能公開 Fuchsia 系統 ABI 允許的符號。

只有在符號許可清單中所列的符號才能使用 ICD。如要進行檢查，請比較許可清單與執行指令碼時取得的清單 ICD 共用資料庫中的 llvm-nm -gD。

某些不支援的檔案作業可能會替換為對 OpenInNamespace 回呼會提供給 vk_icdInitializeOpenInNamespaceCallback。

在此階段測試：

導入 Fuchsia 擴充功能

目前 ICD 無法搭配Scenic 使用，也無法 視窗系統整合驅動程式必須實作 Fuchsia 專用的 Vulkan 。用戶端驅動程式庫應提供符合 。

VK_FUCHSIA_external_memory

這個擴充功能類似於 VK_KHR_external_memory_fd，並允許 將 VkDeviceMemory 匯入/匯出至 VMO。這項擴充功能已上游符合 Vulkan 規格。

在此階段測試：

  • vkext --gtest_filter=VulkanExtension.* (Magma L0 的一部分)。

VK_FUCHSIA_external_semaphore

這個擴充功能類似於 VK_KHR_external_semaphore_fd，因此允許 將二進位 semaphores 匯入/匯出到 zircon 事件。這項擴充功能已上游符合 Vulkan 規格。

在此階段測試：

  • vkext --gtest_filter=VulkanExtension.* (Magma L0 的一部分)。
  • vulkan-cts-zircon (Vulkan CTS 的一部分)。

VK_FUCHSIA_buffer_collection

這項擴充功能會與 sysmem 互動，並可讓用戶端協議圖片 以及配置記憶體詳情請參閱 sysmem 說明文件。

這項擴充功能目前為 WIP，日後可能會變動，請前往 Fuchsia 內部 Vulkan 標頭。

在此階段測試：

驗證

以上各子章節中列出的所有測試都必須通過。請參閱測試 策略說明文件，以取得詳細資訊和完整清單 測試案例

長期支援

MSD 和 ICD 皆須更新，以配合硬體廠商更換的新程式碼。 在理想情況下，程式碼會向上串流，GPU 廠商會供應並維護 使用 Zircon DDK 中的系統驅動程式庫。