DRM 驅動 uAPI

drm/i915 uAPI

i915 在其裝置節點上生成的 uevent

I915_L3_PARITY_UEVENT - 驅動程式收到奇偶校驗不匹配時生成

來自 GPU L3 快取的事件。 提供的額外資訊是受影響快取行的 ROW、BANK、SUBBANK、SLICE。 使用者空間應跟蹤這些事件，如果特定的快取行似乎存在持續錯誤，請使用 intel-gpu-tools 中提供的 L3 重對映工具對其進行重對映。 與該事件一起提供的值始終為 1。

I915_ERROR_UEVENT - 在檢測到錯誤時生成，目前僅透過

hangcheck。 錯誤檢測事件很好地指示了何時開始出現問題。 事件提供的值在檢測到錯誤時為 1，在重置完成時為 0，表示不再存在錯誤。 注意：透過模組引數停用 hangcheck 或重置將導致看不到相關事件。

I915_RESET_UEVENT - 事件在嘗試重置之前生成

GPU。 與該事件一起提供的值始終為 1。 注意：透過模組引數停用重置將導致看不到此事件。

struct i915_user_extension

用於定義擴充套件鏈的基類

定義:

struct i915_user_extension {
    __u64 next_extension;
    __u32 name;
    __u32 flags;
    __u32 rsvd[4];
};

成員

next_extension

指向下一個 struct i915_user_extension 的指標，如果結束，則為零。

name

擴充套件的名稱。

請注意，此處的名稱只是一個整數。

另請注意，此名稱空間不是整個驅動程式的全域性名稱空間，而是其範圍/含義僅限於嵌入 struct i915_user_extension 的 uAPI 的特定部分。

flags

MBZ

所有未定義的位必須為零。

rsvd

MBZ

保留供將來使用；必須為零。

描述

許多介面需要隨著時間的推移而增長。 在大多數情況下，我們可以簡單地擴充套件結構並讓使用者空間傳入更多資料。 另一種選擇，如 Vulkan 為前向和後向相容性提供擴充套件的方法所證明的那樣，是使用可選結構的列表來提供這些額外的詳細資訊。

使用擴充套件鏈的關鍵優勢在於，與不斷增長的複雜結構相比，它可以讓我們更輕鬆地重新定義介面，並且該介面的大部分是完全可選的。 缺點是更多的指標追逐； 使用 u64 內部封裝的指標跨 __user 邊界進行追逐。

示例連結

struct i915_user_extension ext3 {
        .next_extension = 0, // end
        .name = ...,
};
struct i915_user_extension ext2 {
        .next_extension = (uintptr_t)&ext3,
        .name = ...,
};
struct i915_user_extension ext1 {
        .next_extension = (uintptr_t)&ext2,
        .name = ...,
};

通常，struct i915_user_extension 將嵌入到某個 uAPI 結構中，在這種情況下，我們將向其提供鏈的頭部（即 ext1），然後它將應用上述所有擴充套件。

enum drm_i915_gem_engine_class

uapi 引擎型別列舉

常量

I915_ENGINE_CLASS_RENDER

渲染引擎支援用於 3D、計算 (GPGPU) 和可程式設計媒體工作負載的指令。 這些指令獲取資料並將單個工作項分派到並行執行的執行緒。 執行緒在 GPU 的執行單元 (EU) 上執行小型程式（稱為“核心”或“著色器”）。

I915_ENGINE_CLASS_COPY

複製引擎（也稱為“blitters”）支援將資料塊從記憶體中的一個位置移動到另一個位置的指令，或者使用固定資料填充記憶體的指定位置。 複製引擎可以對源資料、目標資料或模式資料執行預定義的邏輯或按位運算。

I915_ENGINE_CLASS_VIDEO

影片引擎（也稱為“位流解碼” (BSD) 或“vdbox”）支援執行固定功能媒體解碼和編碼的指令。

I915_ENGINE_CLASS_VIDEO_ENHANCE

影片增強引擎（也稱為“vebox”）支援與影像增強相關的指令。

I915_ENGINE_CLASS_COMPUTE

計算引擎支援渲染引擎上可用指令的子集：計算引擎支援計算 (GPGPU) 和可程式設計媒體工作負載，但不支援 3D 管道。

I915_ENGINE_CLASS_INVALID

用於表示無效引擎類分配的佔位符值。

描述

不同的引擎服務於不同的角色，並且可能存在多個引擎服務於每個角色。 此列舉提供了引擎角色的分類，該分類可用於請求在引擎的某個子集上執行操作，或用於提供有關該組的資訊。

struct i915_engine_class_instance

引擎類/例項識別符號

定義:

struct i915_engine_class_instance {
    __u16 engine_class;
#define I915_ENGINE_CLASS_INVALID_NONE -1;
#define I915_ENGINE_CLASS_INVALID_VIRTUAL -2;
    __u16 engine_instance;
};

成員

engine_class

來自 enum drm_i915_gem_engine_class 的引擎類

engine_instance

引擎例項。

描述

在系統中，可能有多個引擎履行任何角色。 類中的每個引擎都分配有一個唯一的例項編號，因此，任何引擎都可以透過其類：例項元組來指定。 允許訪問系統中任何引擎的 API 將使用 struct i915_engine_class_instance 進行此標識。

i915 透過 /sys/bus/event_sources/drivers/i915 公開的 perf_events

struct drm_i915_getparam

驅動程式引數查詢結構。

定義:

struct drm_i915_getparam {
    __s32 param;
    int __user *value;
};

成員

param

要查詢的驅動程式引數。

value

應放置查詢值的記憶體地址。

警告：使用指標而不是固定大小的 u64 意味著我們需要編寫 compat32 程式碼。 不要重蹈覆轍。

type drm_i915_getparam_t

驅動程式引數查詢結構。 請參閱 struct drm_i915_getparam。

struct drm_i915_gem_mmap_offset

檢索偏移量，以便我們可以 mmap 此緩衝區物件。

定義:

struct drm_i915_gem_mmap_offset {
    __u32 handle;
    __u32 pad;
    __u64 offset;
    __u64 flags;
#define I915_MMAP_OFFSET_GTT    0;
#define I915_MMAP_OFFSET_WC     1;
#define I915_MMAP_OFFSET_WB     2;
#define I915_MMAP_OFFSET_UC     3;
#define I915_MMAP_OFFSET_FIXED  4;
    __u64 extensions;
};

成員

handle

要對映的物件的控制代碼。

pad

必須為零

offset

用於後續 mmap 呼叫的虛假偏移量

這是一個用於 32/64 相容性的固定大小型別。

flags

擴充套件行為的標誌。

必須包含 MMAP_OFFSET 型別之一

  • I915_MMAP_OFFSET_GTT：將 mmap 與繫結到 GTT 的物件一起使用。 （寫組合）

  • I915_MMAP_OFFSET_WC：使用寫組合快取。

  • I915_MMAP_OFFSET_WB：使用寫回快取。

  • I915_MMAP_OFFSET_FIXED：使用物件放置來確定快取。

在具有本地記憶體的裝置上，I915_MMAP_OFFSET_FIXED 是唯一有效的型別。 在沒有本地記憶體的裝置上，此快取模式無效。

作為指定 I915_MMAP_OFFSET_FIXED 時的快取模式，將使用 WC 或 WB，具體取決於建立時的物件放置。 當物件只能存在於系統記憶體中時，將使用 WB，否則將使用 WC。

extensions

以零結尾的擴充套件鏈。

未定義當前擴充套件； mbz。

描述

此結構作為引數傳遞給 DRM_IOCTL_I915_GEM_MMAP_OFFSET ioctl，用於檢索虛擬偏移量以 mmap 由 handle 指定的物件。

在 gen12+ 上刪除了使用 DRM_IOCTL_I915_GEM_MMAP 的舊方法。 DRM_IOCTL_I915_GEM_MMAP_GTT 是對此結構的舊版支援的別名，但其行為類似於將 extensions 設定為 0，並將 flags 設定為 I915_MMAP_OFFSET_GTT。

struct drm_i915_gem_set_domain

調整物件的寫入或讀取域，以準備透過某些 CPU 域訪問頁面。

定義:

struct drm_i915_gem_set_domain {
    __u32 handle;
    __u32 read_domains;
    __u32 write_domain;
};

成員

handle

物件的控制代碼。

read_domains

新的讀取域。

write_domain

新的寫入域。

請注意，在寫入域中擁有某些內容意味著它位於讀取域中，並且僅位於該讀取域中。

描述

指定新的寫入或讀取域將在更新物件的域跟蹤之前，將物件從之前的域中重新整理（如果需要）。

請注意，如果物件仍在 GPU 上處於活動狀態，這可能首先涉及等待物件。

read_domains 和 write_domain 的支援值

  • I915_GEM_DOMAIN_WC：未快取的寫組合域

  • I915_GEM_DOMAIN_CPU：CPU 快取域

  • I915_GEM_DOMAIN_GTT：可對映孔徑域

所有其他域均被拒絕。

請注意，對於獨立顯示卡，從 DG1 開始，不再支援此功能，而是被拒絕。 在此類平臺上，CPU 域實際上是靜態的，我們還僅支援單個 drm_i915_gem_mmap_offset 快取模式，該模式無法顯式設定，而是取決於物件放置，如下所示。

從 DG1 開始的隱式快取規則

  • 如果任何物件放置（請參閱 drm_i915_gem_create_ext_memory_regions）包含 I915_MEMORY_CLASS_DEVICE，則物件將僅分配和對映為寫組合。

  • 其他所有內容始終分配和對映為寫回，並保證所有內容也與 GPU 一致。

請注意，將來這很可能會再次更改，我們可能需要在將來的裝置上獲得更大的靈活性，因此很可能會將所有這些內容顯式化為新的 drm_i915_gem_create_ext 擴充套件的一部分。

struct drm_i915_gem_exec_fence

execbuf ioctl 的輸入或輸出柵欄。

定義:

struct drm_i915_gem_exec_fence {
    __u32 handle;
    __u32 flags;
#define I915_EXEC_FENCE_WAIT            (1<<0);
#define I915_EXEC_FENCE_SIGNAL          (1<<1);
#define __I915_EXEC_FENCE_UNKNOWN_FLAGS (-(I915_EXEC_FENCE_SIGNAL << 1));
};

成員

handle

使用者用於等待或發出訊號的 drm_syncobj 的控制代碼。

flags

支援的標誌有

I915_EXEC_FENCE_WAIT：在請求提交之前等待輸入柵欄發出訊號。

I915_EXEC_FENCE_SIGNAL：將請求完成柵欄作為輸出返回

描述

請求將在提交之前等待輸入柵欄發出訊號。

返回的輸出柵欄將在請求完成後發出訊號。

struct drm_i915_gem_execbuffer_ext_timeline_fences

execbuf ioctl 的時間線柵欄。

定義:

struct drm_i915_gem_execbuffer_ext_timeline_fences {
#define DRM_I915_GEM_EXECBUFFER_EXT_TIMELINE_FENCES 0;
    struct i915_user_extension base;
    __u64 fence_count;
    __u64 handles_ptr;
    __u64 values_ptr;
};

成員

base

擴充套件連結。 請參閱 struct i915_user_extension。

fence_count

handles_ptr 和 value_ptr 陣列中的元素數。

handles_ptr

指向長度為 fence_count 的 struct drm_i915_gem_exec_fence 陣列的指標。

values_ptr

指向長度為 fence_count 的 u64 值陣列的指標。 二進位制 drm_syncobj 的值必須為 0。 時間線 drm_syncobj 的值為 0 無效，因為它會將 drm_syncobj 轉換為二進位制 drm_syncobj。

描述

此結構描述了 drm_syncobj 陣列和時間線變體的 drm_syncobj 的關聯點。 如果設定了 I915_EXEC_FENCE_ARRAY，則將此結構附加到 execbuf 無效。

struct drm_i915_gem_execbuffer2

DRM_I915_GEM_EXECBUFFER2 ioctl 的結構。

定義:

struct drm_i915_gem_execbuffer2 {
    __u64 buffers_ptr;
    __u32 buffer_count;
    __u32 batch_start_offset;
    __u32 batch_len;
    __u32 DR1;
    __u32 DR4;
    __u32 num_cliprects;
    __u64 cliprects_ptr;
    __u64 flags;
#define I915_EXEC_RING_MASK              (0x3f);
#define I915_EXEC_DEFAULT                (0<<0);
#define I915_EXEC_RENDER                 (1<<0);
#define I915_EXEC_BSD                    (2<<0);
#define I915_EXEC_BLT                    (3<<0);
#define I915_EXEC_VEBOX                  (4<<0);
#define I915_EXEC_CONSTANTS_MASK        (3<<6);
#define I915_EXEC_CONSTANTS_REL_GENERAL (0<<6) ;
#define I915_EXEC_CONSTANTS_ABSOLUTE    (1<<6);
#define I915_EXEC_CONSTANTS_REL_SURFACE (2<<6) ;
#define I915_EXEC_GEN7_SOL_RESET        (1<<8);
#define I915_EXEC_SECURE                (1<<9);
#define I915_EXEC_IS_PINNED             (1<<10);
#define I915_EXEC_NO_RELOC              (1<<11);
#define I915_EXEC_HANDLE_LUT            (1<<12);
#define I915_EXEC_BSD_SHIFT      (13);
#define I915_EXEC_BSD_MASK       (3 << I915_EXEC_BSD_SHIFT);
#define I915_EXEC_BSD_DEFAULT    (0 << I915_EXEC_BSD_SHIFT);
#define I915_EXEC_BSD_RING1      (1 << I915_EXEC_BSD_SHIFT);
#define I915_EXEC_BSD_RING2      (2 << I915_EXEC_BSD_SHIFT);
#define I915_EXEC_RESOURCE_STREAMER     (1<<15);
#define I915_EXEC_FENCE_IN              (1<<16);
#define I915_EXEC_FENCE_OUT             (1<<17);
#define I915_EXEC_BATCH_FIRST           (1<<18);
#define I915_EXEC_FENCE_ARRAY   (1<<19);
#define I915_EXEC_FENCE_SUBMIT          (1 << 20);
#define I915_EXEC_USE_EXTENSIONS        (1 << 21);
#define __I915_EXEC_UNKNOWN_FLAGS (-(I915_EXEC_USE_EXTENSIONS << 1));
    __u64 rsvd1;
    __u64 rsvd2;
};

成員

buffers_ptr

指向 gem_exec_object2 結構列表的指標

buffer_count

buffers_ptr 陣列中的元素數

batch_start_offset

從其開始執行的批處理緩衝區中的偏移量。

batch_len

批處理緩衝區的位元組長度，從 batch_start_offset 開始。 如果為 0，則假定長度為批處理緩衝區物件大小。

DR1

已棄用

DR4

已棄用

num_cliprects

請參閱 cliprects_ptr

cliprects_ptr

核心剪裁是 DRI1 的一個錯誤功能。

如果未設定 I915_EXEC_FENCE_ARRAY 或 I915_EXEC_USE_EXTENSIONS 標誌，則使用此欄位無效。

如果設定了 I915_EXEC_FENCE_ARRAY，則這是指向 drm_i915_gem_exec_fence 陣列的指標，num_cliprects 是陣列的長度。

如果設定了 I915_EXEC_USE_EXTENSIONS，則這是指向單個 i915_user_extension 的指標，num_cliprects 為 0。

flags

Execbuf 標誌

rsvd1

上下文 ID

rsvd2

輸入和輸出 sync_file 檔案描述符。

當設定了 I915_EXEC_FENCE_IN 或 I915_EXEC_FENCE_SUBMIT 標誌時，此欄位的低 32 位將具有輸入 sync_file fd。

當設定了 I915_EXEC_FENCE_OUT 標誌時，此欄位的高 32 位將具有輸出 sync_file fd。

struct drm_i915_gem_caching

設定或獲取給定物件控制代碼的快取。

定義:

struct drm_i915_gem_caching {
    __u32 handle;
#define I915_CACHING_NONE               0;
#define I915_CACHING_CACHED             1;
#define I915_CACHING_DISPLAY            2;
    __u32 caching;
};

成員

handle

用於設定/獲取快取級別的緩衝區的控制代碼。

caching

要應用的 GTT 快取級別或可能的返回值。

支援的 caching 值

I915_CACHING_NONE

GPU 訪問與 CPU 快取不一致。 沒有 LLC 的計算機的預設設定。 這意味著如果我們要使 GPU 訪問一致，則可能需要手動重新整理。

I915_CACHING_CACHED

GPU 訪問與 CPU 快取一致，此外，資料快取在 CPU 核心和 GPU GT 之間共享的最後一級快取中。

I915_CACHING_DISPLAY

特殊的 GPU 快取模式，該模式與掃描輸出引擎一致。 在沒有特殊快取模式（如直寫或 gfdt 重新整理）的平臺上，透明地回退到 I915_CACHING_NONE。 當使用緩衝區作為掃描輸出目標時，核心會自動設定此模式。 使用者空間可以手動設定此模式，以避免在繪製第一幀的熱路徑中出現代價高昂的停頓和 clflush。

描述

允許使用者空間在以後透過 ppGTT 對映物件時（或在缺少 ppGTT 支援的舊平臺上，或如果該物件用於掃描輸出），控制給定物件的 GTT 快取位。 請注意，如果其當前快取值不匹配，這可能需要首先從 GTT 中解除繫結該物件。

請注意，從 DG1 開始，所有這些都在獨立顯示卡平臺上發生了變化，不再支援設定/獲取快取，現在已被拒絕。 相反，CPU 快取屬性（WB 與 WC）將成為物件的一個不可變建立時屬性，以及 GTT 快取級別。 目前，我們沒有為此公開任何新的 uAPI，而是在 DG1 上，所有這些都是隱式的，儘管這在很大程度上無關緊要，因為預設情況下 DG1 是一致的（沒有任何控制方式）。

從 DG1 開始的隱式快取規則

  • 如果任何物件放置（請參閱 drm_i915_gem_create_ext_memory_regions）包含 I915_MEMORY_CLASS_DEVICE，則物件將僅分配和對映為寫組合。

  • 其他所有內容始終分配和對映為寫回，並保證所有內容也與 GPU 一致。

請注意，將來這很可能會再次更改，我們可能需要在將來的裝置上獲得更大的靈活性，因此很可能會將所有這些內容顯式化為新的 drm_i915_gem_create_ext 擴充套件的一部分。

附註：部分原因是，如果我們需要以後使用不同的快取屬性對頁面進行 CPU 對映，則可能需要（且代價高昂）更改頁面的分配時 CPU 快取屬性。 這種不一致的快取行為雖然在 x86 上受支援，但在其他架構上並非普遍受支援。 因此，為了簡單起見，我們選擇在獨立顯示卡平臺上在建立時設定所有內容，同時使其不可變。

struct drm_i915_gem_context_create_ext

用於建立上下文的結構。

定義:

struct drm_i915_gem_context_create_ext {
    __u32 ctx_id;
    __u32 flags;
#define I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS        (1u << 0);
#define I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE       (1u << 1);
#define I915_CONTEXT_CREATE_FLAGS_UNKNOWN         (-(I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE << 1));
    __u64 extensions;
#define I915_CONTEXT_CREATE_EXT_SETPARAM 0;
#define I915_CONTEXT_CREATE_EXT_CLONE 1;
};

成員

ctx_id

建立的上下文的 ID（輸出）

flags

支援的標誌有

I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS

擴充套件可以附加到此結構，並且驅動程式必須檢查這些擴充套件。 請參閱 extensions。

I915_CONTEXT_CREATE_FLAGS_SINGLE_TIMELINE

建立的上下文將具有單個時間線。

extensions

以零結尾的擴充套件鏈。

I915_CONTEXT_CREATE_EXT_SETPARAM：在上下文建立期間要設定或查詢的上下文引數。 請參閱 struct drm_i915_gem_context_create_ext_setparam。

I915_CONTEXT_CREATE_EXT_CLONE：此擴充套件已被刪除。 即使有人曾經嘗試使用它，也永遠不要重新使用此擴充套件號。

struct drm_i915_gem_context_param

要設定或查詢的上下文引數。

定義:

struct drm_i915_gem_context_param {
    __u32 ctx_id;
    __u32 size;
    __u64 param;
#define I915_CONTEXT_PARAM_BAN_PERIOD   0x1;
#define I915_CONTEXT_PARAM_NO_ZEROMAP   0x2;
#define I915_CONTEXT_PARAM_GTT_SIZE     0x3;
#define I915_CONTEXT_PARAM_NO_ERROR_CAPTURE     0x4;
#define I915_CONTEXT_PARAM_BANNABLE     0x5;
#define I915_CONTEXT_PARAM_PRIORITY     0x6;
#define I915_CONTEXT_MAX_USER_PRIORITY        1023 ;
#define I915_CONTEXT_DEFAULT_PRIORITY         0;
#define I915_CONTEXT_MIN_USER_PRIORITY        -1023 ;
#define I915_CONTEXT_PARAM_SSEU         0x7;
#define I915_CONTEXT_PARAM_RECOVERABLE  0x8;
#define I915_CONTEXT_PARAM_VM           0x9;
#define I915_CONTEXT_PARAM_ENGINES      0xa;
#define I915_CONTEXT_PARAM_PERSISTENCE  0xb;
#define I915_CONTEXT_PARAM_RINGSIZE     0xc;
#define I915_CONTEXT_PARAM_PROTECTED_CONTENT    0xd;
#define I915_CONTEXT_PARAM_LOW_LATENCY          0xe;
#define I915_CONTEXT_PARAM_CONTEXT_IMAGE        0xf;
    __u64 value;
};

成員

ctx_id

上下文 ID

size

引數 value 的大小

param

要設定或查詢的引數

value

要設定或查詢的上下文引數值

虛擬引擎 uAPI

虛擬引擎是一種概念，使用者空間可以配置一組物理引擎，提交批處理緩衝區，並讓驅動程式根據自己的判斷在集合中的任何引擎上執行它。

這主要在具有同一類引擎的多個例項的部件上很有用，例如具有兩個 VCS 引擎的 GT3+ Skylake 部件。

例如，使用者空間可以使用先前描述的 引擎發現 uAPI 列舉某個類的所有引擎。 之後，使用者空間可以使用虛擬引擎的佔位符槽建立 GEM 上下文（分別使用類和例項的 I915_ENGINE_CLASS_INVALID 和 I915_ENGINE_CLASS_INVALID_NONE），最後使用 I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE 擴充套件將虛擬引擎放置在同一保留槽中。

建立虛擬引擎並向其提交批處理緩衝區的示例

I915_DEFINE_CONTEXT_ENGINES_LOAD_BALANCE(virtual, 2) = {
        .base.name = I915_CONTEXT_ENGINES_EXT_LOAD_BALANCE,
        .engine_index = 0, // Place this virtual engine into engine map slot 0
        .num_siblings = 2,
        .engines = { { I915_ENGINE_CLASS_VIDEO, 0 },
                     { I915_ENGINE_CLASS_VIDEO, 1 }, },
};
I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 1) = {
        .engines = { { I915_ENGINE_CLASS_INVALID,
                       I915_ENGINE_CLASS_INVALID_NONE } },
        .extensions = to_user_pointer(&virtual), // Chains after load_balance extension
};
struct drm_i915_gem_context_create_ext_setparam p_engines = {
        .base = {
                .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
        },
        .param = {
                .param = I915_CONTEXT_PARAM_ENGINES,
                .value = to_user_pointer(&engines),
                .size = sizeof(engines),
        },
};
struct drm_i915_gem_context_create_ext create = {
        .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
        .extensions = to_user_pointer(&p_engines);
};

ctx_id = gem_context_create_ext(drm_fd, &create);

// Now we have created a GEM context with its engine map containing a
// single virtual engine. Submissions to this slot can go either to
// vcs0 or vcs1, depending on the load balancing algorithm used inside
// the driver. The load balancing is dynamic from one batch buffer to
// another and transparent to userspace.

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 0; // Submits to index 0 which is the virtual engine
gem_execbuf(drm_fd, &execbuf);
struct i915_context_engines_parallel_submit

配置引擎以進行並行提交。

定義:

struct i915_context_engines_parallel_submit {
    struct i915_user_extension base;
    __u16 engine_index;
    __u16 width;
    __u16 num_siblings;
    __u16 mbz16;
    __u64 flags;
    __u64 mbz64[3];
    struct i915_engine_class_instance engines[];
};

成員

base

基本使用者擴充套件。

engine_index

並行引擎的槽

width

每個並行引擎的上下文數，或者換句話說，每次提交的批次數

num_siblings

每個上下文的同級數，或者換句話說，每次提交的可能放置數

mbz16

保留供將來使用；必須為零

flags

所有未定義的標誌必須為零，當前未定義標誌

mbz64

保留供將來使用；必須為零

engines

用於配置並行引擎的引擎例項的二維陣列

length = width (i) * num_siblings (j) index = j + i * num_siblings

描述

在上下文引擎對映中設定一個槽，以允許在單個 execbuf IOCTL 中提交多個 BB。 然後，這些 BB 將被安排在 GPU 上並行執行。 在 i915 中內部建立多個硬體上下文來執行這些 BB。 一旦為 N 個 BB 配置了一個槽，則每次 execbuf IOCTL 中只能提交 N 個 BB，這是隱式行為，例如，使用者不會告訴 execbuf IOCTL 有 N 個 BB，execbuf IOCTL 會根據該槽的配置知道有多少 BB。 N 個 BB 是最後 N 個緩衝區物件，如果設定了 I915_EXEC_BATCH_FIRST，則為前 N 個。

預設放置行為是在每個上下文中建立隱式繫結（如果每個上下文對映到多個物理引擎）（例如，上下文是一個虛擬引擎）。 此外，我們只允許具有相同引擎類的上下文，並且這些上下文必須按邏輯連續順序排列。 下面描述了放置行為的示例。 最後，預設設定是不允許 BB 在批處理中被搶佔。 而是在每組 BB 之間在所有硬體上下文中插入協調的搶佔點。 將來可以新增標誌來更改這兩種預設行為。

如果硬體上下文放置配置無效，或者平臺/提交介面不支援放置配置，則返回 -EINVAL。 如果平臺/提交介面不支援擴充套件，則返回 -ENODEV。

Examples syntax:
CS[X] = generic engine of same class, logical instance X
INVALID = I915_ENGINE_CLASS_INVALID, I915_ENGINE_CLASS_INVALID_NONE

Example 1 pseudo code:
set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=1,
             engines=CS[0],CS[1])

Results in the following valid placement:
CS[0], CS[1]

Example 2 pseudo code:
set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=2,
             engines=CS[0],CS[2],CS[1],CS[3])

Results in the following valid placements:
CS[0], CS[1]
CS[2], CS[3]

This can be thought of as two virtual engines, each containing two
engines thereby making a 2D array. However, there are bonds tying the
entries together and placing restrictions on how they can be scheduled.
Specifically, the scheduler can choose only vertical columns from the 2D
array. That is, CS[0] is bonded to CS[1] and CS[2] to CS[3]. So if the
scheduler wants to submit to CS[0], it must also choose CS[1] and vice
versa. Same for CS[2] requires also using CS[3].
VE[0] = CS[0], CS[2]
VE[1] = CS[1], CS[3]

Example 3 pseudo code:
set_engines(INVALID)
set_parallel(engine_index=0, width=2, num_siblings=2,
             engines=CS[0],CS[1],CS[1],CS[3])

Results in the following valid and invalid placements:
CS[0], CS[1]
CS[1], CS[3] - Not logically contiguous, return -EINVAL

上下文引擎對映 uAPI

上下文引擎對映是在提交批處理緩衝區時定址引擎的新方法，取代了使用 I915_EXEC_BLT 等識別符號的現有方式（在 struct drm_i915_gem_execbuffer2 的標誌欄位中）。

要使用它，需要使用使用者打算提交到的引擎列表來配置建立的 GEM 上下文。 這是使用 I915_CONTEXT_PARAM_ENGINES 引數和 struct i915_context_param_engines 來完成的。

對於此類上下文，I915_EXEC_RING_MASK 欄位變為已配置對映的索引。

建立此類上下文並針對其進行提交的示例

I915_DEFINE_CONTEXT_PARAM_ENGINES(engines, 2) = {
        .engines = { { I915_ENGINE_CLASS_RENDER, 0 },
                     { I915_ENGINE_CLASS_COPY, 0 } }
};
struct drm_i915_gem_context_create_ext_setparam p_engines = {
        .base = {
                .name = I915_CONTEXT_CREATE_EXT_SETPARAM,
        },
        .param = {
                .param = I915_CONTEXT_PARAM_ENGINES,
                .value = to_user_pointer(&engines),
                .size = sizeof(engines),
        },
};
struct drm_i915_gem_context_create_ext create = {
        .flags = I915_CONTEXT_CREATE_FLAGS_USE_EXTENSIONS,
        .extensions = to_user_pointer(&p_engines);
};

ctx_id = gem_context_create_ext(drm_fd, &create);

// We have now created a GEM context with two engines in the map:
// Index 0 points to rcs0 while index 1 points to bcs0. Other engines
// will not be accessible from this context.

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 0; // Submits to index 0, which is rcs0 for this context
gem_execbuf(drm_fd, &execbuf);

...
execbuf.rsvd1 = ctx_id;
execbuf.flags = 1; // Submits to index 0, which is bcs0 for this context
gem_execbuf(drm_fd, &execbuf);
struct drm_i915_gem_context_create_ext_setparam

在上下文建立期間要設定或查詢的上下文引數。

定義:

struct drm_i915_gem_context_create_ext_setparam {
    struct i915_user_extension base;
    struct drm_i915_gem_context_param param;
};

成員

base

擴充套件連結。 請參閱 struct i915_user_extension。

param

要設定或查詢的上下文引數。 請參閱 struct drm_i915_gem_context_param。

struct drm_i915_gem_vm_control

用於建立或銷燬 VM 的結構。

定義:

struct drm_i915_gem_vm_control {
    __u64 extensions;
    __u32 flags;
    __u32 vm_id;
};

成員

extensions

以零結尾的擴充套件鏈。

flags

保留供將來使用，目前 MBZ

vm_id

要建立或銷燬的 VM 的 ID

描述

DRM_I915_GEM_VM_CREATE -

建立一個新的虛擬記憶體地址空間 (ppGTT)，以在同一檔案上的上下文中使用。 可以提供擴充套件來配置在建立時如何設定地址空間。

新 VM 的 ID（繫結到 fd）用於 I915_CONTEXT_PARAM_VM 在 outparam id 中返回。

可以提供擴充套件鏈，從 extensions 開始，以 next_extension 為 0 結束。目前，未定義擴充套件。

DRM_I915_GEM_VM_DESTROY -

銷燬先前建立的 VM ID，該 ID 在 vm_id 中指定。

當前不允許任何擴充套件或標誌，因此必須為零。

struct drm_i915_gem_userptr

從使用者分配的記憶體建立 GEM 物件。

定義:

struct drm_i915_gem_userptr {
    __u64 user_ptr;
    __u64 user_size;
    __u32 flags;
#define I915_USERPTR_READ_ONLY 0x1;
#define I915_USERPTR_PROBE 0x2;
#define I915_USERPTR_UNSYNCHRONIZED 0x80000000;
    __u32 handle;
};

成員

user_ptr

指向分配的記憶體的指標。

需要與 PAGE_SIZE 對齊。

user_size

分配的記憶體的大小（以位元組為單位）。 這也將成為物件大小。

需要與 PAGE_SIZE 對齊，並且應至少為 PAGE_SIZE 或更大。

flags

支援的標誌

I915_USERPTR_READ_ONLY

將物件標記為只讀，這也意味著 GPU 訪問只能是隻讀的。 這僅在支援透過 GTT 進行只讀訪問的硬體上受支援。 如果硬體不支援只讀訪問，則會返回錯誤。

I915_USERPTR_PROBE

探測提供的 user_ptr 範圍並驗證 user_ptr 確實指向正常記憶體，並且該範圍也有效。 例如，如果將一些垃圾地址提供給核心，則應該會發出警告。

如果探測失敗，則返回 -EFAULT。

請注意，這不會填充後備頁，也不能保證物件在最終使用時仍然有效。

如果 I915_PARAM_HAS_USERPTR_PROBE 返回非零值，則核心支援此功能。

I915_USERPTR_UNSYNCHRONIZED

未使用。 設定此標誌將導致錯誤。

handle

返回的物件的控制代碼。

物件控制代碼為非零。

描述

Userptr 物件對可以與物件控制代碼一起使用的 ioctl 有一些限制。

struct drm_i915_perf_oa_config

定義:

struct drm_i915_perf_oa_config {
    char uuid[36];
    __u32 n_mux_regs;
    __u32 n_boolean_regs;
    __u32 n_flex_regs;
    __u64 mux_regs_ptr;
    __u64 boolean_regs_ptr;
    __u64 flex_regs_ptr;
};

成員

uuid

字串格式為“%08x-%04x-%04x-%04x-%012x”

n_mux_regs

mux_regs_ptr 中的多路複用暫存器數。

n_boolean_regs

boolean_regs_ptr 中的布林暫存器數。

n_flex_regs

flex_regs_ptr 中的彈性暫存器數。

mux_regs_ptr

指向多路複用暫存器的 u32 值（暫存器地址、值）元組的指標。 緩衝區的預期長度為 (2 * sizeof(u32) * n_mux_regs)。

boolean_regs_ptr

指向多路複用暫存器的 u32 值（暫存器地址、值）元組的指標。 緩衝區的預期長度為 (2 * sizeof(u32) * n_boolean_regs)。

flex_regs_ptr

指向多路複用暫存器的 u32 值（暫存器地址、值）元組的指標。 緩衝區的預期長度為 (2 * sizeof(u32) * n_flex_regs)。

描述

用於將 perf 動態配置上傳到核心的結構。

struct drm_i915_query_item

核心要處理的單個查詢。

定義:

struct drm_i915_query_item {
    __u64 query_id;
#define DRM_I915_QUERY_TOPOLOGY_INFO            1;
#define DRM_I915_QUERY_ENGINE_INFO              2;
#define DRM_I915_QUERY_PERF_CONFIG              3;
#define DRM_I915_QUERY_MEMORY_REGIONS           4;
#define DRM_I915_QUERY_HWCONFIG_BLOB            5;
#define DRM_I915_QUERY_GEOMETRY_SUBSLICES       6;
#define DRM_I915_QUERY_GUC_SUBMISSION_VERSION   7;
    __s32 length;
    __u32 flags;
#define DRM_I915_QUERY_PERF_CONFIG_LIST          1;
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2;
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID   3;
    __u64 data_ptr;
};

成員

query_id
此查詢的 ID。 當前接受的查詢 ID 有
length

當用戶空間設定為零時，此欄位將填充要寫入 data_ptr 指標處的資料大小。核心會將此值設定為負值，以指示特定查詢項上的錯誤。

flags

當 query_id == DRM_I915_QUERY_TOPOLOGY_INFO 時，必須為 0。

當 query_id == DRM_I915_QUERY_PERF_CONFIG 時，必須為以下值之一

  • DRM_I915_QUERY_PERF_CONFIG_LIST

  • DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID

  • DRM_I915_QUERY_PERF_CONFIG_FOR_UUID

當 query_id == DRM_I915_QUERY_GEOMETRY_SUBSLICES 時，必須包含一個引用渲染引擎的 struct i915_engine_class_instance。

data_ptr

當 length 的值與核心要寫入的資料長度匹配時，資料將寫入 data_ptr 指向的位置。

描述

行為由 query_id 確定。請注意，具體的 data_ptr 也取決於特定的 query_id。

struct drm_i915_query

提供一個 struct drm_i915_query_item 陣列，供核心填充。

定義:

struct drm_i915_query {
    __u32 num_items;
    __u32 flags;
    __u64 items_ptr;
};

成員

num_items

items_ptr 陣列中的元素數量

flags

目前未使用。必須清零。

items_ptr

指向 struct drm_i915_query_item 陣列的指標。陣列元素的數量為 num_items。

描述

請注意，對於陣列中的每個 struct drm_i915_query_item，這通常是一個兩步過程

  1. 呼叫 DRM_IOCTL_I915_QUERY，提供我們的 struct drm_i915_query_item 陣列，並將 drm_i915_query_item.length 設定為零。然後，核心將填充大小（以位元組為單位），以告知使用者空間需要為 blob 分配多少記憶體（例如，用於屬性陣列）。

  2. 接下來，我們再次呼叫 DRM_IOCTL_I915_QUERY，這次將 drm_i915_query_item.data_ptr 設定為我們新分配的 blob。請注意，drm_i915_query_item.length 仍應與核心先前設定的值相同。此時，核心可以填充 blob。

請注意，對於某些查詢項，使用者空間只需傳入等於或大於所需大小的緩衝區/blob 是有意義的。在這種情況下，只需要一個 ioctl 呼叫。對於某些較小的查詢項，這可能效果很好。

struct drm_i915_query_topology_info

定義:

struct drm_i915_query_topology_info {
    __u16 flags;
    __u16 max_slices;
    __u16 max_subslices;
    __u16 max_eus_per_subslice;
    __u16 subslice_offset;
    __u16 subslice_stride;
    __u16 eu_offset;
    __u16 eu_stride;
    __u8 data[];
};

成員

flags

目前未使用。必須清零。

max_slices

用於表示 slice mask 的位數。

max_subslices

用於表示 subslice mask 的位數。

max_eus_per_subslice

EU mask 中對應於單個 subslice EU 的位數。

subslice_offset

儲存 subslice mask 的 data[] 中的偏移量。

subslice_stride

儲存每個 slice 的每個 subslice mask 的步長。

eu_offset

儲存 EU mask 的 data[] 中的偏移量。

eu_stride

儲存每個 subslice 的每個 EU mask 的步長。

data

包含 3 個資訊

  • slice mask，每個 slice 對應一位，指示 slice 是否可用。可以使用以下公式查詢 slice X 的可用性

    (data[X / 8] >> (X % 8)) & 1

    從 Xe_HP 平臺開始，英特爾硬體不再具有傳統的 slice，因此 i915 將始終報告單個 slice（硬編碼 slicemask = 0x1），其中包含平臺的所有 subslice。也就是說，此處的 mask 不反映任何較新的硬體概念，例如“gslices”或“cslices”，因為使用者空間能夠從 subslice mask 中推斷出這些概念。

  • 每個 slice 的 subslice mask，每個 subslice 對應一位，指示 subslice 是否可用。從 Gen12 開始，我們使用術語“subslice”來指代硬體文件中描述的“dual-subslices”。可以使用以下公式查詢 slice X 中 subslice Y 的可用性

    (data[subslice_offset + X * subslice_stride + Y / 8] >> (Y % 8)) & 1

  • 每個 slice 中每個 subslice 的 EU mask，每個 EU 對應一位，指示 EU 是否可用。可以使用以下公式查詢 slice X 中 subslice Y 中 EU Z 的可用性

    (data[eu_offset +
      (X * max_subslices + Y) * eu_stride +
      Z / 8
 ] >> (Z % 8)) & 1

描述

描述由 DRM_I915_QUERY_TOPOLOGY_INFO 查詢的 slice/subslice/EU 資訊

引擎發現 uAPI

引擎發現 uAPI 是一種列舉與開啟的 i915 DRM 檔案描述符關聯的 GPU 中存在的物理引擎的方式。這取代了使用 DRM_IOCTL_I915_GETPARAM 和引擎識別符號（如 I915_PARAM_HAS_BLT）的舊方法。

從 Icelake 和更新的 GPU 開始出現對該介面的需求，這些 GPU 開始建立一種模式，即具有同一類的多個引擎，其中並非所有例項在功能上總是完全等效的。

此 uapi 的入口點是 DRM_IOCTL_I915_QUERY，其中 DRM_I915_QUERY_ENGINE_INFO 作為查詢的 item id。

獲取引擎列表的示例

struct drm_i915_query_engine_info *info;
struct drm_i915_query_item item = {
        .query_id = DRM_I915_QUERY_ENGINE_INFO;
};
struct drm_i915_query query = {
        .num_items = 1,
        .items_ptr = (uintptr_t)&item,
};
int err, i;

// First query the size of the blob we need, this needs to be large
// enough to hold our array of engines. The kernel will fill out the
// item.length for us, which is the number of bytes we need.
//
// Alternatively a large buffer can be allocated straightaway enabling
// querying in one pass, in which case item.length should contain the
// length of the provided buffer.
err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
if (err) ...

info = calloc(1, item.length);
// Now that we allocated the required number of bytes, we call the ioctl
// again, this time with the data_ptr pointing to our newly allocated
// blob, which the kernel can then populate with info on all engines.
item.data_ptr = (uintptr_t)&info;

err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
if (err) ...

// We can now access each engine in the array
for (i = 0; i < info->num_engines; i++) {
        struct drm_i915_engine_info einfo = info->engines[i];
        u16 class = einfo.engine.class;
        u16 instance = einfo.engine.instance;
        ....
}

free(info);

除了由其類和例項定義（請參閱 struct i915_engine_class_instance）之外，每個列舉的引擎還可以具有 i915_drm.h 中記錄的標誌和功能。

例如，支援 HEVC 編碼的影片引擎將設定 I915_VIDEO_CLASS_CAPABILITY_HEVC 功能位。

僅當與使用配置了引擎對映的上下文提交批處理緩衝區時的新引擎定址方式結合使用時，引擎發現才能完全發揮其作用。

struct drm_i915_engine_info

定義:

struct drm_i915_engine_info {
    struct i915_engine_class_instance engine;
    __u32 rsvd0;
    __u64 flags;
#define I915_ENGINE_INFO_HAS_LOGICAL_INSTANCE           (1 << 0);
    __u64 capabilities;
#define I915_VIDEO_CLASS_CAPABILITY_HEVC                (1 << 0);
#define I915_VIDEO_AND_ENHANCE_CLASS_CAPABILITY_SFC     (1 << 1);
    __u16 logical_instance;
    __u16 rsvd1[3];
    __u64 rsvd2[3];
};

成員

engine

引擎類和例項。

rsvd0

保留欄位。

flags

引擎標誌。

capabilities

此引擎的功能。

logical_instance

引擎的邏輯例項

rsvd1

保留欄位。

rsvd2

保留欄位。

描述

描述驅動程式已知的一個引擎及其功能。

struct drm_i915_query_engine_info

定義:

struct drm_i915_query_engine_info {
    __u32 num_engines;
    __u32 rsvd[3];
    struct drm_i915_engine_info engines[];
};

成員

num_engines

以下 struct drm_i915_engine_info 結構的數目。

rsvd

MBZ

engines

drm_i915_engine_info 結構的標記。

描述

引擎資訊查詢透過填充 struct drm_i915_engine_info 結構的陣列來列舉驅動程式已知的所有引擎。

struct drm_i915_query_perf_config

定義:

struct drm_i915_query_perf_config {
    union {
        __u64 n_configs;
        __u64 config;
        char uuid[36];
    };
    __u32 flags;
    __u8 data[];
};

成員

{unnamed_union}

anonymous

n_configs

當 drm_i915_query_item.flags == DRM_I915_QUERY_PERF_CONFIG_LIST 時，i915 會將此欄位設定為可用配置的數量。

config

當 drm_i915_query_item.flags == DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 時，i915 將使用此欄位中的值作為配置識別符號，以決定要將哪些資料寫入 config_ptr。

uuid

當 drm_i915_query_item.flags == DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 時，i915 將使用此欄位中的值作為配置識別符號，以決定要將哪些資料寫入 config_ptr。

格式化為“08x-````04x-````04x-````04x-````012x”的字串

flags

目前未使用。必須清零。

data

當 drm_i915_query_item.flags == DRM_I915_QUERY_PERF_CONFIG_LIST 時，i915 將寫入一個配置識別符號的 __u64 陣列。

當 drm_i915_query_item.flags == DRM_I915_QUERY_PERF_CONFIG_DATA 時，i915 將寫入一個 struct drm_i915_perf_oa_config。如果 struct drm_i915_perf_oa_config 的以下欄位未設定為 0，則 i915 將把提交配置時提交的值寫入關聯的指標

描述

核心使用查詢 DRM_I915_QUERY_PERF_CONFIG 和 DRM_I915_QUERY_GEOMETRY_SUBSLICES 寫入的資料。

enum drm_i915_gem_memory_class

支援的記憶體類

常量

I915_MEMORY_CLASS_SYSTEM

系統記憶體

I915_MEMORY_CLASS_DEVICE

裝置本地記憶體

struct drm_i915_gem_memory_class_instance

標識特定的記憶體區域

定義:

struct drm_i915_gem_memory_class_instance {
    __u16 memory_class;
    __u16 memory_instance;
};

成員

memory_class

參見 enum drm_i915_gem_memory_class

memory_instance

哪個例項

struct drm_i915_memory_region_info

描述驅動程式已知的一個區域。

定義:

struct drm_i915_memory_region_info {
    struct drm_i915_gem_memory_class_instance region;
    __u32 rsvd0;
    __u64 probed_size;
    __u64 unallocated_size;
    union {
        __u64 rsvd1[8];
        struct {
            __u64 probed_cpu_visible_size;
            __u64 unallocated_cpu_visible_size;
        };
    };
};

成員

region

class:instance 對編碼

rsvd0

MBZ

probed_size

驅動程式探測到的記憶體

請注意，這裡不應該出現零值，並且請注意，當前沒有區域型別會在此處返回 -1。儘管對於未來的區域型別，這可能是一種可能性。同樣的也適用於其他大小欄位。

unallocated_size

剩餘記憶體的估計值

需要 CAP_PERFMON 或 CAP_SYS_ADMIN 才能獲得可靠的帳戶。如果沒有此許可權（或者如果這是一個較舊的核心），則此處的值將始終等於 probed_size。請注意，這目前僅針對 I915_MEMORY_CLASS_DEVICE 區域進行跟蹤（對於其他型別，此處的值將始終等於 probed_size）。

{unnamed_union}

anonymous

rsvd1

MBZ

{unnamed_struct}

anonymous

probed_cpu_visible_size

驅動程式探測到的 CPU 可訪問的記憶體。

這將始終 <= probed_size，剩餘部分（如果有）將無法透過 CPU 訪問。

在沒有小 BAR 的系統上，probed_size 將始終等於 probed_cpu_visible_size，因為所有這些都將是 CPU 可訪問的。

請注意，這僅針對 I915_MEMORY_CLASS_DEVICE 區域進行跟蹤（對於其他型別，此處的值將始終等於 probed_size）。

請注意，如果此處返回的值為零，則這必須是一個缺少相關的小型 bar uAPI 支援的舊核心（包括 I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS），但是在這樣的系統上，我們實際上不應該最終得到一個小型的 BAR 配置，假設我們能夠載入核心模組。因此，將其視為 probed_cpu_visible_size == probed_size 時是安全的。

unallocated_cpu_visible_size

剩餘 CPU 可見記憶體的估計值。

請注意，這僅針對 I915_MEMORY_CLASS_DEVICE 區域進行跟蹤（對於其他型別，此處的值將始終等於 probed_cpu_visible_size）。

需要 CAP_PERFMON 或 CAP_SYS_ADMIN 才能獲得可靠的帳戶。如果沒有此許可權，則此處的值將始終等於 probed_cpu_visible_size。請注意，這目前僅針對 I915_MEMORY_CLASS_DEVICE 區域進行跟蹤（對於其他型別，此處的值也將始終等於 probed_cpu_visible_size）。

如果這是一個較舊的核心，則此處的數值將為零，另請參見 probed_cpu_visible_size。

描述

請注意，這同時使用了 struct drm_i915_query_item 和 struct drm_i915_query。對於這個新的查詢，我們在 drm_i915_query_item.query_id 處添加了新的查詢 id DRM_I915_QUERY_MEMORY_REGIONS。

struct drm_i915_query_memory_regions

定義:

struct drm_i915_query_memory_regions {
    __u32 num_regions;
    __u32 rsvd[3];
    struct drm_i915_memory_region_info regions[];
};

成員

num_regions

支援的區域數量

rsvd

MBZ

regions

關於每個支援的區域的資訊

描述

區域資訊查詢透過填充 struct drm_i915_memory_region_info 結構的陣列來列舉驅動程式已知的所有區域。

獲取支援區域列表的示例

struct drm_i915_query_memory_regions *info;
struct drm_i915_query_item item = {
        .query_id = DRM_I915_QUERY_MEMORY_REGIONS;
};
struct drm_i915_query query = {
        .num_items = 1,
        .items_ptr = (uintptr_t)&item,
};
int err, i;

// First query the size of the blob we need, this needs to be large
// enough to hold our array of regions. The kernel will fill out the
// item.length for us, which is the number of bytes we need.
err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
if (err) ...

info = calloc(1, item.length);
// Now that we allocated the required number of bytes, we call the ioctl
// again, this time with the data_ptr pointing to our newly allocated
// blob, which the kernel can then populate with the all the region info.
item.data_ptr = (uintptr_t)&info,

err = ioctl(fd, DRM_IOCTL_I915_QUERY, &query);
if (err) ...

// We can now access each region in the array
for (i = 0; i < info->num_regions; i++) {
        struct drm_i915_memory_region_info mr = info->regions[i];
        u16 class = mr.region.class;
        u16 instance = mr.region.instance;

        ....
}

free(info);
struct drm_i915_query_guc_submission_version

查詢 GuC 提交介面版本

定義:

struct drm_i915_query_guc_submission_version {
    __u32 branch;
    __u32 major;
    __u32 minor;
    __u32 patch;
};

成員

branch

韌體分支版本。

major

韌體主版本。

minor

韌體次版本。

patch

韌體補丁版本。

GuC HWCONFIG blob uAPI

GuC 生成一個包含當前裝置資訊的 blob。 i915 從 GuC 讀取此 blob 並透過此 uAPI 使其可用。

blob 內容的格式和含義記錄在程式設計師參考手冊中。

struct drm_i915_gem_create_ext

現有的 gem_create 行為，使用 struct i915_user_extension 添加了擴充套件支援。

定義:

struct drm_i915_gem_create_ext {
    __u64 size;
    __u32 handle;
#define I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS (1 << 0);
    __u32 flags;
#define I915_GEM_CREATE_EXT_MEMORY_REGIONS 0;
#define I915_GEM_CREATE_EXT_PROTECTED_CONTENT 1;
#define I915_GEM_CREATE_EXT_SET_PAT 2;
    __u64 extensions;
};

成員

size

物件請求的大小。

將返回物件的（頁面對齊）分配大小。

在像 DG2/ATS 這樣的平臺上，核心將始終對 I915_MEMORY_CLASS_DEVICE 使用 64K 或更大的頁面。核心還要求此類物件至少 64K GTT 對齊。

注意：由於硬體如何實現 64K GTT 頁面支援，以前此處的 ABI 要求 DG2/ATS 上至少 2M 的 GTT 對齊，在硬體支援中我們遇到了以下複雜情況

1) 整個 PDE（覆蓋 2MB 的虛擬地址範圍）必須僅包含 64K PTE，即禁止在同一 PDE 中混合 4K 和 64K PTE。

2) 我們仍然需要支援 I915_MEMORY_CLASS_SYSTEM 物件的 4K PTE。

但是，在實際的生產 HW 上，這已完全更改為現在允許在 PTE 級別設定 TLB 提示（請參閱 PS64），這比上述方法靈活得多。有了這個，2M 限制被取消，我們現在只需要 64K。

handle

返回的物件的控制代碼。

物件控制代碼為非零。

flags

可選標誌。

支援的值

I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS - 向核心發出訊號，表明該物件需要透過 CPU 訪問。

僅在將物件放置在 I915_MEMORY_CLASS_DEVICE 中時有效，並且僅嚴格要求在裝置記憶體的某些子集可以透過 CPU 直接可見/對映的配置中（我們也稱之為小 BAR），例如在某些 DG2+ 系統上。請注意，這是非常不受歡迎的，但是由於客戶端 CPU、BIOS 等各種因素，我們可以預期會在實際應用中看到這種情況。有關如何確定此係統是否適用的資訊，請參見 drm_i915_memory_region_info.probed_cpu_visible_size。

請注意，其中一個位置必須是 I915_MEMORY_CLASS_SYSTEM，以確保如果無法在 I915_MEMORY_CLASS_DEVICE 的可對映部分中分配物件，則核心始終可以將分配溢位到系統記憶體。

還要注意，由於核心僅支援可以僅放置在 I915_MEMORY_CLASS_DEVICE 中的物件的平面 CCS，因此我們不支援 I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS 與平面 CCS 一起使用。

如果沒有此提示，核心將假定對於此物件，首選不可對映的 I915_MEMORY_CLASS_DEVICE。請注意，如果使用者空間對該物件發生 CPU 故障，核心仍然可以將該物件遷移到可對映部分，作為最後的手段，但這可能會很昂貴，因此理想情況下應避免這種情況。

在缺少相關小型 bar uAPI 支援的舊核心上（另請參見 drm_i915_memory_region_info.probed_cpu_visible_size），使用該標誌會導致錯誤，但假設我們也可以成功載入 i915 核心模組，則永遠不可能最終得到小型 BAR 配置。在這種情況下，整個 I915_MEMORY_CLASS_DEVICE 區域將可以被 CPU 訪問，因此對物件可以放置的位置沒有任何限制。

extensions

要應用於此物件的擴充套件鏈。

當我們需要支援幾個不同的擴充套件時，並且我們需要在建立物件時應用多個擴充套件，這將很有用。請參見 struct i915_user_extension。

如果我們不提供任何擴充套件，那麼我們將獲得相同的舊 gem_create 行為。

有關 I915_GEM_CREATE_EXT_MEMORY_REGIONS 的用法，請參見 struct drm_i915_gem_create_ext_memory_regions。

有關 I915_GEM_CREATE_EXT_PROTECTED_CONTENT 的用法，請參見 struct drm_i915_gem_create_ext_protected_content。

有關 I915_GEM_CREATE_EXT_SET_PAT 的用法，請參見 struct drm_i915_gem_create_ext_set_pat。

描述

請注意，新的緩衝區標誌應該至少為不可變內容新增在此處。以前，我們將有兩個 ioctl，一個使用 gem_create 建立物件，另一個應用各種引數，但是這為被認為是不可變的引數建立了一些歧義。通常，我們正在逐步淘汰各種 SET/GET ioctl。

struct drm_i915_gem_create_ext_memory_regions

I915_GEM_CREATE_EXT_MEMORY_REGIONS 擴充套件。

定義:

struct drm_i915_gem_create_ext_memory_regions {
    struct i915_user_extension base;
    __u32 pad;
    __u32 num_regions;
    __u64 regions;
};

成員

base

擴充套件連結。 請參閱 struct i915_user_extension。

pad

MBZ

num_regions

regions 陣列中元素的數量。

regions

regions/placements 陣列。

struct drm_i915_gem_memory_class_instance 的陣列。

描述

使用優先順序順序的所需放置/區域集來設定物件。每個條目必須是唯一的並且受裝置支援。

這以 struct drm_i915_gem_memory_class_instance 的陣列或 class:instance 對編碼的等效佈局形式提供。有關如何查詢裝置支援的區域，請參見 struct drm_i915_query_memory_regions 和 DRM_I915_QUERY_MEMORY_REGIONS。

例如，在獨立裝置上，如果我們希望將放置設定為裝置本地記憶體，我們可以執行以下操作

struct drm_i915_gem_memory_class_instance region_lmem = {
        .memory_class = I915_MEMORY_CLASS_DEVICE,
        .memory_instance = 0,
};
struct drm_i915_gem_create_ext_memory_regions regions = {
        .base = { .name = I915_GEM_CREATE_EXT_MEMORY_REGIONS },
        .regions = (uintptr_t)&region_lmem,
        .num_regions = 1,
};
struct drm_i915_gem_create_ext create_ext = {
        .size = 16 * PAGE_SIZE,
        .extensions = (uintptr_t)&regions,
};

int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
if (err) ...

此時，我們可以在 drm_i915_gem_create_ext.handle 中獲取物件控制代碼，以及 drm_i915_gem_create_ext.size 中的最終物件大小，這應該考慮到任何舍入（如果需要）。

請注意，使用者空間無法知道 num_regions 大於 1 的物件的當前後備區域。核心將僅確保 regions 陣列的優先順序順序受到尊重，無論是在最初放置物件時還是由於記憶體壓力而移動記憶體時

在支援平面 CCS 的 HW 上，支援壓縮位於 I915_MEMORY_CLASS_DEVICE 中的物件。當此類物件（壓縮）在 regions 中具有其他記憶體類並遷移到（由於記憶體約束）非 I915_MEMORY_CLASS_DEVICE 區域時，則 i915 需要解壓縮內容。但是 i915 沒有解壓縮使用者空間壓縮物件所需的資訊。

因此 i915 支援平面 CCS，在只能駐留在 I915_MEMORY_CLASS_DEVICE 區域中的物件上。

struct drm_i915_gem_create_ext_protected_content

I915_OBJECT_PARAM_PROTECTED_CONTENT 擴充套件。

定義:

struct drm_i915_gem_create_ext_protected_content {
    struct i915_user_extension base;
    __u32 flags;
};

成員

base

擴充套件連結。 請參閱 struct i915_user_extension。

flags

保留供將來使用，目前 MBZ

描述

如果提供了此擴充套件，則期望緩衝區內容受到 PXP 加密的保護，並且需要解密才能進行掃描和處理。這僅在啟用了 PXP 的平臺上才有可能，在所有其他情況下使用此擴充套件將導致 ioctl 失敗並返回 -ENODEV。 flags 引數保留供將來擴充套件使用，目前必須設定為零。

在 PXP 會話拆除後，緩衝區內容被視為無效。

僅當使用使用 I915_CONTEXT_PARAM_PROTECTED_CONTENT 標誌建立的上下文提交物件時，才能保證加密得到正確處理。這還將在提交時對所涉及物件的有效性啟用額外的檢查。

以下是如何建立受保護物件的示例

struct drm_i915_gem_create_ext_protected_content protected_ext = {
        .base = { .name = I915_GEM_CREATE_EXT_PROTECTED_CONTENT },
        .flags = 0,
};
struct drm_i915_gem_create_ext create_ext = {
        .size = PAGE_SIZE,
        .extensions = (uintptr_t)&protected_ext,
};

int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
if (err) ...
struct drm_i915_gem_create_ext_set_pat

I915_GEM_CREATE_EXT_SET_PAT 擴充套件。

定義:

struct drm_i915_gem_create_ext_set_pat {
    struct i915_user_extension base;
    __u32 pat_index;
    __u32 rsvd;
};

成員

base

擴充套件連結。 請參閱 struct i915_user_extension。

pat_index

要設定的 PAT 索引 PAT 索引是頁表條目中的一個位欄位，用於控制 GPU 訪問的快取行為。 PAT 索引的定義與平臺相關，可以在硬體規範中找到。

rsvd

保留供將來使用

描述

如果提供了此擴充套件，則指定的快取策略（PAT 索引）將應用於緩衝區物件。

以下是如何使用特定快取策略建立物件的示例

struct drm_i915_gem_create_ext_set_pat set_pat_ext = {
        .base = { .name = I915_GEM_CREATE_EXT_SET_PAT },
        .pat_index = 0,
};
struct drm_i915_gem_create_ext create_ext = {
        .size = PAGE_SIZE,
        .extensions = (uintptr_t)&set_pat_ext,
};

int err = ioctl(fd, DRM_IOCTL_I915_GEM_CREATE_EXT, &create_ext);
if (err) ...

drm/nouveau uAPI

VM_BIND / EXEC uAPI

Nouveau 的 VM_BIND / EXEC UAPI 由三個 ioctl 組成：DRM_NOUVEAU_VM_INIT、DRM_NOUVEAU_VM_BIND 和 DRM_NOUVEAU_EXEC。

為了使用 UAPI，使用者客戶端首先必須使用 DRM_NOUVEAU_VM_INIT ioctl 初始化 VA 空間，指定 VA 空間的哪個區域應由核心管理，哪個區域應由 UMD 管理。

DRM_NOUVEAU_VM_BIND ioctl 為客戶端提供了一個介面來管理 VA 空間中使用者空間可管理的部分。它提供了對映和取消對映記憶體的操作。對映可以標記為稀疏。稀疏對映不受 GEM 物件支援，並且核心將忽略與稀疏對映一起提供的 GEM 控制代碼。

使用者空間可以在先前對映的稀疏對映的邊界內或邊界外（但不跨越那些邊界）請求記憶體支援的對映。隨後在稀疏對映中請求的記憶體支援的對映將優先於稀疏對映的相應範圍。如果取消對映此類記憶體支援的對映，核心將確保相應的稀疏對映再次代替它們。對仍然包含記憶體支援的對映的稀疏對映的取消對映請求將導致首先取消對映這些記憶體支援的對映。

取消對映請求不受現有對映範圍的限制，甚至可以與稀疏對映的邊界重疊。對於這樣的請求，核心將確保取消對映給定範圍內的所有記憶體支援的對映，從而拆分僅部分包含在給定範圍內的記憶體支援的對映。具有稀疏標誌集的取消對映請求必須完全匹配先前對映的稀疏對映的範圍。

雖然核心通常允許在單個或多個 VM_BIND ioctl 呼叫中對映和取消對映記憶體支援的對映的任意序列和範圍，但對稀疏對映存在一些限制。

核心不允許

  • 取消對映不存在的稀疏對映

  • 在同一 VM_BIND ioctl 中取消對映稀疏對映並對映一個新的稀疏對映，該對映與先前取消對映的稀疏對映的範圍重疊

  • 在同一 VM_BIND ioctl 中取消對映稀疏對映並對映與先前取消對映的稀疏對映的範圍重疊的新記憶體支援的對映

當使用 VM_BIND ioctl 請求核心將記憶體對映到 GPU 的 VA 空間中的給定虛擬地址時，不能保證實際的對映是在 GPU 的 MMU 中建立的。如果在執行繫結操作時給定的記憶體被交換出去，核心會將對映詳細資訊隱藏到其內部分配器中，並在記憶體交換回後建立實際的 MMU 對映。雖然這對使用者空間是透明的，但可以保證所有後備記憶體都被交換回來，並且一旦呼叫 DRM_NOUVEAU_EXEC ioctl 來提交 exec 作業，所有使用者空間先前請求的記憶體對映都實際上被對映。

可以同步或非同步執行 VM_BIND 作業。如果非同步執行，使用者空間可以提供此作業將等待的 syncobj 列表和/或核心將在 VM_BIND 作業完成執行後發出訊號的 syncobj 列表。如果同步執行，則 ioctl 將阻塞，直到繫結作業完成。對於同步作業，核心將不允許提交任何 syncobj 到核心。

為了執行推送緩衝區，UAPI 提供了 DRM_NOUVEAU_EXEC ioctl。 EXEC 作業始終是非同步執行的，並且與 VM_BIND 作業一樣，提供使用 syncobj 同步它們的選項。

除此之外，可以排程 EXEC 作業在指定的通道上執行。

由於 VM_BIND 作業會在作業提交時更新 GPU 的 VA 空間，因此 EXEC 作業具有最新的 VA 空間檢視。但是，實際對映可能仍在等待中。因此，EXEC 作業需要具有特定的 fence - 它們所依賴的相應 VM_BIND 作業的 fence - 連線到它們。

struct drm_nouveau_sync

同步物件

定義:

struct drm_nouveau_sync {
    __u32 flags;
#define DRM_NOUVEAU_SYNC_SYNCOBJ 0x0;
#define DRM_NOUVEAU_SYNC_TIMELINE_SYNCOBJ 0x1;
#define DRM_NOUVEAU_SYNC_TYPE_MASK 0xf;
    __u32 handle;
    __u64 timeline_value;
};

成員

flags

同步物件的標誌

前 8 位用於確定同步物件的型別。

handle

同步物件的控制代碼

timeline_value

如果 syncobj 的型別為 DRM_NOUVEAU_SYNC_TIMELINE_SYNCOBJ，則同步物件的時間線點。

描述

此結構用作（可能）非同步操作（例如 EXEC 或 VM_BIND）的同步機制。

struct drm_nouveau_vm_init

GPU VA 空間初始化結構

定義:

struct drm_nouveau_vm_init {
    __u64 kernel_managed_addr;
    __u64 kernel_managed_size;
};

成員

kernel_managed_addr

核心管理的 VA 空間區域的起始地址

kernel_managed_size

核心管理的 VA 空間區域的大小（以位元組為單位）

描述

用於初始化使用者客戶端的 GPU VA 空間，告知核心 VA 空間的哪個部分分別由 UMD 和核心管理。

為了讓 UMD 使用 VM_BIND uAPI，必須在建立任何 BO 或通道之前呼叫此方法；如果在之後呼叫，DRM_IOCTL_NOUVEAU_VM_INIT 將失敗，並顯示 -ENOSYS。

struct drm_nouveau_vm_bind_op

VM_BIND 操作

定義:

struct drm_nouveau_vm_bind_op {
    __u32 op;
#define DRM_NOUVEAU_VM_BIND_OP_MAP 0x0;
#define DRM_NOUVEAU_VM_BIND_OP_UNMAP 0x1;
    __u32 flags;
#define DRM_NOUVEAU_VM_BIND_SPARSE (1 << 8);
    __u32 handle;
    __u32 pad;
    __u64 addr;
    __u64 bo_offset;
    __u64 range;
};

成員

op

操作型別

支援的值

DRM_NOUVEAU_VM_BIND_OP_MAP - 將 GEM 物件對映到 GPU 的 VA 空間。可選地，可以傳遞 DRM_NOUVEAU_VM_BIND_SPARSE 標誌，以指示核心為給定範圍建立稀疏對映。

DRM_NOUVEAU_VM_BIND_OP_UNMAP - 取消對映 GPU VA 空間中的現有對映。如果對映所在的區域是稀疏區域，則在先前對映取消對映（記憶體支援）對映的位置建立新的稀疏對映。要刪除稀疏區域，必須設定 DRM_NOUVEAU_VM_BIND_SPARSE。

flags

drm_nouveau_vm_bind_op 的標誌

支援的值

DRM_NOUVEAU_VM_BIND_SPARSE - 指示分配的 VA 空間區域應為稀疏。

handle

要對映的 DRM GEM 物件的控制代碼

pad

32 位填充，應為 0

addr

VA 空間區域或（記憶體支援）對映應對映到的地址

bo_offset

支援對映的 BO 中的偏移量

range

請求對映的大小（以位元組為單位）

描述

此結構表示單個 VM_BIND 操作。 UMD 應透過 struct drm_nouveau_vm_bind 的 op_ptr 欄位傳遞此結構的陣列。

struct drm_nouveau_vm_bind

DRM_IOCTL_NOUVEAU_VM_BIND 的結構

定義:

struct drm_nouveau_vm_bind {
    __u32 op_count;
    __u32 flags;
#define DRM_NOUVEAU_VM_BIND_RUN_ASYNC 0x1;
    __u32 wait_count;
    __u32 sig_count;
    __u64 wait_ptr;
    __u64 sig_ptr;
    __u64 op_ptr;
};

成員

op_count

drm_nouveau_vm_bind_op 的數量

flags

drm_nouveau_vm_bind ioctl 的標誌

支援的值

DRM_NOUVEAU_VM_BIND_RUN_ASYNC - 指示核心應非同步執行給定的 VM_BIND 操作。

如果未提供此標誌，則核心會同步執行關聯的操作，並且不接受任何 drm_nouveau_sync 物件。

wait_count

等待 drm_nouveau_syncs 的數量

sig_count

完成時要發出訊號的 drm_nouveau_syncs 的數量

wait_ptr

指向要等待的 drm_nouveau_syncs 的指標

sig_ptr

指向完成時要發出訊號的 drm_nouveau_syncs 的指標

op_ptr

指向要執行的 drm_nouveau_vm_bind_ops 的指標

struct drm_nouveau_exec_push

EXEC 推送操作

定義:

struct drm_nouveau_exec_push {
    __u64 va;
    __u32 va_len;
    __u32 flags;
#define DRM_NOUVEAU_EXEC_PUSH_NO_PREFETCH 0x1;
};

成員

va

推送緩衝區對映的虛擬地址

va_len

推送緩衝區對映的長度

flags

此推送緩衝區對映的標誌

描述

此結構表示單個 EXEC 推送操作。 UMD 應透過 struct drm_nouveau_exec 的 push_ptr 欄位傳遞此結構的陣列。

struct drm_nouveau_exec

DRM_IOCTL_NOUVEAU_EXEC 的結構

定義:

struct drm_nouveau_exec {
    __u32 channel;
    __u32 push_count;
    __u32 wait_count;
    __u32 sig_count;
    __u64 wait_ptr;
    __u64 sig_ptr;
    __u64 push_ptr;
};

成員

channel

在其中執行推送緩衝區的通道

push_count

drm_nouveau_exec_push 操作的數量

wait_count

等待 drm_nouveau_syncs 的數量

sig_count

完成時要發出訊號的 drm_nouveau_syncs 的數量

wait_ptr

指向要等待的 drm_nouveau_syncs 的指標

sig_ptr

指向完成時要發出訊號的 drm_nouveau_syncs 的指標

push_ptr

指向 drm_nouveau_exec_push 操作的指標

drm/panthor uAPI

簡介

此文件描述了 Panthor IOCTL。

關於傳遞給 Panthor IOCTL 的資料的幾個通用規則

  • 結構體必須按 64 位/8 位元組對齊。如果物件不是自然對齊的，則必須新增填充欄位。

  • 欄位必須與其自然型別對齊對齊，使用 pad[0..N] 欄位。

  • 所有填充欄位都將由驅動程式檢查以確保它們已清零。

  • 可以新增標誌，但不能刪除/替換。

  • 可以將新欄位新增到主結構體（直接傳遞給 ioctl 的結構體）。這些欄位可以新增到結構體的末尾，也可以替換現有的填充欄位。任何新增的新欄位都必須保留新增這些欄位之前存在的行為，當傳遞零值時。

  • 可以將新欄位新增到間接物件（主結構體指向的物件），前提是這些物件傳遞一個大小以反映 userspace 驅動程式已知的大小（請參閱 drm_panthor_obj_array::stride 或 drm_panthor_dev_query::size）。

  • 如果核心驅動程式太舊而無法識別某些欄位，則如果它們為零將被忽略，否則將被拒絕（因此在輸出時將為零）。

  • 如果 userspace 太舊而無法識別某些欄位，則在核心驅動程式解析結構體之前，這些欄位將被清零（輸入）。

  • 每個新標誌/欄位的新增都必須帶有驅動程式版本更新，因此 userspace 驅動程式不必透過試錯來了解哪些標誌受支援。

  • 結構體不應包含 unions，因為這會破壞此類結構體的可擴充套件性。

  • IOCTL 不能被刪除或替換。新的 IOCTL ID 應放置在 drm_panthor_ioctl_id 列舉的末尾。

暴露給 userspace 的 MMIO 區域。

DRM_PANTHOR_USER_MMIO_OFFSET

暴露給 userspace 的所有 MMIO 區域的檔案偏移量。不要直接使用此值，而是使用 DRM_PANTHOR_USER_<name>_OFFSET 值。傳遞給 mmap2() 的 pgoffset 是一個無符號長整型，這迫使我們在 32 位和 64 位系統上使用不同的偏移量。

DRM_PANTHOR_USER_FLUSH_ID_MMIO_OFFSET

LATEST_FLUSH_ID 暫存器的檔案偏移量。 Userspace 驅動程式透過 CS 指令控制 GPU 快取重新整理，但重新整理減少機制需要 flush_id。可以使用 ioctl 查詢此 flush_id，但 Arm 提供了一個隔離良好的暫存器頁面，其中僅包含此只讀暫存器，因此讓我們透過靜態 mmap 偏移量暴露此頁面，並允許直接對映此 MMIO 區域，以便我們可以避免使用者 <-> 核心往返。

IOCTL ID

enum drm_panthor_ioctl_id - IOCTL ID

將新的 ioctl 放置在末尾，不要重新排序，不要替換或刪除條目。

這些 ID 不應直接使用。請改用 DRM_IOCTL_PANTHOR_xxx 定義。

IOCTL 引數

struct drm_panthor_obj_array

物件陣列。

定義:

struct drm_panthor_obj_array {
    __u32 stride;
    __u32 count;
    __u64 array;
};

成員

stride

物件結構體的步幅。用於版本控制。

count

陣列中物件的數量。

array

指向物件陣列的使用者指標。

描述

此物件用於傳遞一個物件陣列，其大小可能會在驅動程式的未來版本中更改。為了支援這種可變性，我們傳遞一個步幅，描述 userspace 已知的物件大小。

你不應該直接填充 drm_panthor_obj_array 欄位。你應該使用 DRM_PANTHOR_OBJ_ARRAY() 宏，它負責將步幅初始化為物件大小。

DRM_PANTHOR_OBJ_ARRAY

DRM_PANTHOR_OBJ_ARRAY (cnt, ptr)

初始化 drm_panthor_obj_array 欄位。

引數

cnt

陣列中元素的數量。

ptr

指向要傳遞給核心的陣列的指標。

描述

宏，根據 userspace 已知的物件大小初始化 drm_panthor_obj_array。

enum drm_panthor_sync_op_flags

同步操作標誌。

常量

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK

同步控制代碼型別掩碼。

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_SYNCOBJ

同步物件型別。

DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ

時間線同步物件型別。

DRM_PANTHOR_SYNC_OP_WAIT

等待操作。

DRM_PANTHOR_SYNC_OP_SIGNAL

訊號操作。

struct drm_panthor_sync_op

同步操作。

定義:

struct drm_panthor_sync_op {
    __u32 flags;
    __u32 handle;
    __u64 timeline_value;
};

成員

flags

同步操作標誌。 DRM_PANTHOR_SYNC_OP 值的組合。

handle

同步控制代碼。

timeline_value

如果 (flags & DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_MASK) != DRM_PANTHOR_SYNC_OP_HANDLE_TYPE_TIMELINE_SYNCOBJ，則 MBZ。

enum drm_panthor_dev_query_type

查詢型別

常量

DRM_PANTHOR_DEV_QUERY_GPU_INFO

查詢 GPU 資訊。

DRM_PANTHOR_DEV_QUERY_CSIF_INFO

查詢命令流介面資訊。

DRM_PANTHOR_DEV_QUERY_TIMESTAMP_INFO

查詢時間戳資訊。

DRM_PANTHOR_DEV_QUERY_GROUP_PRIORITIES_INFO

查詢允許的組優先順序資訊。

描述

將新的型別放置在末尾，不要重新排序，不要刪除或替換。

struct drm_panthor_gpu_info

GPU 資訊

定義:

struct drm_panthor_gpu_info {
    __u32 gpu_id;
#define DRM_PANTHOR_ARCH_MAJOR(x)               ((x) >> 28);
#define DRM_PANTHOR_ARCH_MINOR(x)               (((x) >> 24) & 0xf);
#define DRM_PANTHOR_ARCH_REV(x)                 (((x) >> 20) & 0xf);
#define DRM_PANTHOR_PRODUCT_MAJOR(x)            (((x) >> 16) & 0xf);
#define DRM_PANTHOR_VERSION_MAJOR(x)            (((x) >> 12) & 0xf);
#define DRM_PANTHOR_VERSION_MINOR(x)            (((x) >> 4) & 0xff);
#define DRM_PANTHOR_VERSION_STATUS(x)           ((x) & 0xf);
    __u32 gpu_rev;
    __u32 csf_id;
#define DRM_PANTHOR_CSHW_MAJOR(x)               (((x) >> 26) & 0x3f);
#define DRM_PANTHOR_CSHW_MINOR(x)               (((x) >> 20) & 0x3f);
#define DRM_PANTHOR_CSHW_REV(x)                 (((x) >> 16) & 0xf);
#define DRM_PANTHOR_MCU_MAJOR(x)                (((x) >> 10) & 0x3f);
#define DRM_PANTHOR_MCU_MINOR(x)                (((x) >> 4) & 0x3f);
#define DRM_PANTHOR_MCU_REV(x)                  ((x) & 0xf);
    __u32 l2_features;
    __u32 tiler_features;
    __u32 mem_features;
    __u32 mmu_features;
#define DRM_PANTHOR_MMU_VA_BITS(x)              ((x) & 0xff);
    __u32 thread_features;
    __u32 max_threads;
    __u32 thread_max_workgroup_size;
    __u32 thread_max_barrier_size;
    __u32 coherency_features;
    __u32 texture_features[4];
    __u32 as_present;
    __u64 shader_present;
    __u64 l2_present;
    __u64 tiler_present;
    __u32 core_features;
    __u32 pad;
};

成員

gpu_id

GPU ID。

gpu_rev

GPU 修訂版。

csf_id

命令流前端 ID。

l2_features

L2 快取功能。

tiler_features

Tiler 功能。

mem_features

記憶體功能。

mmu_features

MMU 功能。

thread_features

執行緒功能。

max_threads

最大執行緒數。

thread_max_workgroup_size

最大工作組大小。

thread_max_barrier_size

可以在屏障上同時等待的最大執行緒數。

coherency_features

一致性功能。

texture_features

紋理功能。

as_present

位掩碼編碼 MMU 暴露的地址空間數量。

shader_present

位掩碼編碼 GPU 暴露的著色器核心。

l2_present

位掩碼編碼 GPU 暴露的 L2 快取。

tiler_present

位掩碼編碼 GPU 暴露的平鋪單元。

core_features

用於區分核心變體（如果存在）。

pad

MBZ。

描述

結構體，分組所有與 GPU 相關的可查詢資訊。

struct drm_panthor_csif_info

命令流介面資訊

定義:

struct drm_panthor_csif_info {
    __u32 csg_slot_count;
    __u32 cs_slot_count;
    __u32 cs_reg_count;
    __u32 scoreboard_slot_count;
    __u32 unpreserved_cs_reg_count;
    __u32 pad;
};

成員

csg_slot_count

韌體暴露的命令流組槽的數量。

cs_slot_count

每組命令流槽的數量。

cs_reg_count

命令流暫存器的數量。

scoreboard_slot_count

記分板槽的數量。

unpreserved_cs_reg_count

核心驅動程式保留的命令流暫存器的數量，用於呼叫 userspace 命令流。

所有暫存器都可以被 userspace 命令流使用，但是當呼叫 DRM_PANTHOR_IOCTL_GROUP_SUBMIT 時，核心會使用 [cs_slot_count - unpreserved_cs_reg_count .. cs_slot_count] 暫存器。

pad

填充欄位，設定為零。

描述

結構體，分組所有與命令流介面相關的可查詢資訊。

struct drm_panthor_timestamp_info

時間戳資訊

定義:

struct drm_panthor_timestamp_info {
    __u64 timestamp_frequency;
    __u64 current_timestamp;
    __u64 timestamp_offset;
};

成員

timestamp_frequency

時間戳定時器的頻率，如果未知則為 0。

current_timestamp

當前時間戳。

timestamp_offset

時間戳定時器的偏移量。

描述

結構體，分組所有與 GPU 時間戳相關的可查詢資訊。

struct drm_panthor_group_priorities_info

組優先順序資訊

定義:

struct drm_panthor_group_priorities_info {
    __u8 allowed_mask;
    __u8 pad[3];
};

成員

allowed_mask

允許的組優先順序的位掩碼。

每個位代表 enum drm_panthor_group_priority 的一個變體。

pad

填充欄位，MBZ。

描述

結構體，分組所有與允許的組優先順序相關的可查詢資訊。

struct drm_panthor_dev_query

傳遞給 DRM_PANTHOR_IOCTL_DEV_QUERY 的引數

定義:

struct drm_panthor_dev_query {
    __u32 type;
    __u32 size;
    __u64 pointer;
};

成員

type

查詢型別（請參閱 drm_panthor_dev_query_type）。

size

正在查詢的型別的大小。

如果 pointer 為 NULL，則 size 由驅動程式更新以提供輸出結構體大小。如果 pointer 不為 NULL，則驅動程式只會將 min(size, actual_structure_size) 位元組複製到 pointer，並相應地更新 size。這允許我們在不破壞 userspace 的情況下擴充套件查詢型別。

pointer

指向查詢型別結構體的使用者指標。

Pointer 可以為 NULL，在這種情況下，不會複製任何內容，但會返回實際的結構體大小。如果不為 NULL，則它必須指向一個足夠大的位置來儲存 size 位元組。

struct drm_panthor_vm_create

傳遞給 DRM_PANTHOR_IOCTL_VM_CREATE 的引數

定義:

struct drm_panthor_vm_create {
    __u32 flags;
    __u32 id;
    __u64 user_va_range;
};

成員

flags

VM 標誌，MBZ。

id

返回的 VM ID。

user_va_range

為使用者物件保留的 VA 空間的大小。

核心將選擇剩餘空間，將僅限核心的物件對映到 VM（堆塊、堆上下文、環形緩衝區、核心同步物件等）。如果留給核心物件的空間太小，核心物件的分配將在後續失敗。可以使用 drm_panthor_gpu_info::mmu_features 來提取總虛擬地址範圍，並選擇一個 user_va_range，為核心留出一些空間。

如果 user_va_range 為零，核心將根據 TASK_SIZE 和 GPU MMU 支援的虛擬範圍選擇一個合理的值（核心/使用者拆分應為 userspace 程序留下足夠的 VA 空間來支援 SVM，同時仍然允許核心將一些核心物件對映到核心 VA 範圍中）。驅動程式選擇的值將在 user_va_range 中返回。

使用者 VA 空間始終從 0x0 開始，核心 VA 空間始終放置在使用者 VA 範圍之後。

struct drm_panthor_vm_destroy

傳遞給 DRM_PANTHOR_IOCTL_VM_DESTROY 的引數

定義:

struct drm_panthor_vm_destroy {
    __u32 id;
    __u32 pad;
};

成員

id

要銷燬的 VM 的 ID。

pad

MBZ。

enum drm_panthor_vm_bind_op_flags

VM 繫結操作標誌

常量

DRM_PANTHOR_VM_BIND_OP_MAP_READONLY

將記憶體對映為只讀。

僅對 DRM_PANTHOR_VM_BIND_OP_TYPE_MAP 有效。

DRM_PANTHOR_VM_BIND_OP_MAP_NOEXEC

將記憶體對映為不可執行。

僅對 DRM_PANTHOR_VM_BIND_OP_TYPE_MAP 有效。

DRM_PANTHOR_VM_BIND_OP_MAP_UNCACHED

將記憶體對映為非快取。

僅對 DRM_PANTHOR_VM_BIND_OP_TYPE_MAP 有效。

DRM_PANTHOR_VM_BIND_OP_TYPE_MASK

用於確定操作型別的掩碼。

DRM_PANTHOR_VM_BIND_OP_TYPE_MAP

對映操作。

DRM_PANTHOR_VM_BIND_OP_TYPE_UNMAP

取消對映操作。

DRM_PANTHOR_VM_BIND_OP_TYPE_SYNC_ONLY

無 VM 操作。

僅作為 VM 佇列上的同步點。

僅當 drm_panthor_vm_bind::flags 中設定了 DRM_PANTHOR_VM_BIND_ASYNC，並且 drm_panthor_vm_bind_op::syncs 至少包含一個元素時才有效。

struct drm_panthor_vm_bind_op

VM 繫結操作

定義:

struct drm_panthor_vm_bind_op {
    __u32 flags;
    __u32 bo_handle;
    __u64 bo_offset;
    __u64 va;
    __u64 size;
    struct drm_panthor_obj_array syncs;
};

成員

flags

drm_panthor_vm_bind_op_flags 標誌的組合。

bo_handle

要對映的緩衝區物件的控制代碼。取消對映或僅同步操作的 MBZ。

bo_offset

緩衝區物件偏移量。取消對映或僅同步操作的 MBZ。

va

要對映/取消對映的虛擬地址。僅同步操作的 MBZ。

size

要對映/取消對映的大小。僅同步操作的 MBZ。

syncs

struct drm_panthor_sync_op 同步運算元組。

如果在包含此 VM 繫結操作的 drm_panthor_vm_bind 物件上未設定 DRM_PANTHOR_VM_BIND_ASYNC，則此陣列必須為空。

對於僅同步操作，此陣列不得為空。

enum drm_panthor_vm_bind_flags

VM 繫結標誌

常量

DRM_PANTHOR_VM_BIND_ASYNC

VM 繫結操作排隊到 VM 佇列，而不是同步執行。

struct drm_panthor_vm_bind

傳遞給 DRM_IOCTL_PANTHOR_VM_BIND 的引數

定義:

struct drm_panthor_vm_bind {
    __u32 vm_id;
    __u32 flags;
    struct drm_panthor_obj_array ops;
};

成員

vm_id

繫結請求的目標 VM。

flags

drm_panthor_vm_bind_flags 標誌的組合。

ops

struct drm_panthor_vm_bind_op 繫結運算元組。

enum drm_panthor_vm_state

VM 狀態。

常量

DRM_PANTHOR_VM_STATE_USABLE

VM 可用。

將在此 VM 上接受新的 VM 操作。

DRM_PANTHOR_VM_STATE_UNUSABLE

VM 不可用。

某些操作將 VM 置於不可用狀態（例如，由於任何原因非同步 VM_BIND 請求失敗）。

一旦 VM 處於此狀態，所有新的 MAP 操作將被拒絕，並且任何以該 VM 為目標的 GPU 作業將失敗。仍然接受 UNMAP 操作。

從不可用的 VM 恢復的唯一方法是建立一個新的 VM，然後銷燬舊的 VM。

struct drm_panthor_vm_get_state

獲取 VM 狀態。

定義:

struct drm_panthor_vm_get_state {
    __u32 vm_id;
    __u32 state;
};

成員

vm_id

get_state 請求的目標 VM。

state

驅動程式返回的狀態。

必須是 enum drm_panthor_vm_state 值之一。

enum drm_panthor_bo_flags

緩衝區物件標誌，在建立時傳遞。

常量

DRM_PANTHOR_BO_NO_MMAP

緩衝區物件永遠不會在 userspace 中進行 CPU 對映。

struct drm_panthor_bo_create

傳遞給 DRM_IOCTL_PANTHOR_BO_CREATE 的引數。

定義:

struct drm_panthor_bo_create {
    __u64 size;
    __u32 flags;
    __u32 exclusive_vm_id;
    __u32 handle;
    __u32 pad;
};

成員

size

物件請求的大小

將返回物件的（頁面對齊）分配大小。

flags

標誌。必須是 drm_panthor_bo_flags 標誌的組合。

exclusive_vm_id

此緩衝區物件將對映到的獨佔 VM。

如果不為零，則該欄位必須引用有效的 VM ID，並暗示

  • 緩衝區物件將僅繫結到該 VM

  • 不能作為 PRIME fd 匯出

handle

返回的物件的控制代碼。

物件控制代碼為非零。

pad

MBZ。

struct drm_panthor_bo_mmap_offset

傳遞給 DRM_IOCTL_PANTHOR_BO_MMAP_OFFSET 的引數。

定義:

struct drm_panthor_bo_mmap_offset {
    __u32 handle;
    __u32 pad;
    __u64 offset;
};

成員

handle

我們想要 mmap 偏移量的物件的控制代碼。

pad

MBZ。

offset

用於後續 mmap 呼叫的虛假偏移量。

struct drm_panthor_queue_create

佇列建立引數。

定義:

struct drm_panthor_queue_create {
    __u8 priority;
    __u8 pad[3];
    __u32 ringbuf_size;
};

成員

priority

定義組內佇列的優先順序。範圍從 0 到 15，15 是最高優先順序。

pad

填充欄位，MBZ。

ringbuf_size

要為此佇列分配的環形緩衝區的大小。

enum drm_panthor_group_priority

排程組優先順序

常量

PANTHOR_GROUP_PRIORITY_LOW

低優先順序組。

PANTHOR_GROUP_PRIORITY_MEDIUM

中優先順序組。

PANTHOR_GROUP_PRIORITY_HIGH

高優先順序組。

需要 CAP_SYS_NICE 或 DRM_MASTER。

PANTHOR_GROUP_PRIORITY_REALTIME

即時優先順序組。

需要 CAP_SYS_NICE 或 DRM_MASTER。

struct drm_panthor_group_create

傳遞給 DRM_IOCTL_PANTHOR_GROUP_CREATE 的引數

定義:

struct drm_panthor_group_create {
    struct drm_panthor_obj_array queues;
    __u8 max_compute_cores;
    __u8 max_fragment_cores;
    __u8 max_tiler_cores;
    __u8 priority;
    __u32 pad;
    __u64 compute_core_mask;
    __u64 fragment_core_mask;
    __u64 tiler_core_mask;
    __u32 vm_id;
    __u32 group_handle;
};

成員

queues

drm_panthor_queue_create 元素的陣列。

max_compute_cores

可用於繫結到此組的 CS 佇列的計算作業的最大核心數。

必須小於或等於 compute_core_mask 中設定的位數。

max_fragment_cores

可用於繫結到此組的 CS 佇列的片段作業的最大核心數。

必須小於或等於 fragment_core_mask 中設定的位數。

max_tiler_cores

可用於繫結到此組的 CS 佇列的平鋪器作業的最大平鋪器數。

必須小於或等於 tiler_core_mask 中設定的位數。

priority

組優先順序（請參閱 enum drm_panthor_group_priority）。

pad

填充欄位，MBZ。

compute_core_mask

編碼可用於計算作業的核心的掩碼。

此欄位必須至少設定 max_compute_cores 位。

此處設定的位也應在 drm_panthor_gpu_info::shader_present 中設定。

fragment_core_mask

編碼可用於片段作業的核心的掩碼。

此欄位必須至少設定 max_fragment_cores 位。

此處設定的位也應在 drm_panthor_gpu_info::shader_present 中設定。

tiler_core_mask

編碼可用於平鋪器作業的核心的掩碼。

此欄位必須至少設定 max_tiler_cores 位。

此處設定的位也應在 drm_panthor_gpu_info::tiler_present 中設定。

vm_id

用於繫結此組的 VM ID。

提交到繫結到此組的佇列的所有內容都將使用此 VM。

group_handle

返回的組控制代碼。提交作業或銷燬組時返回。

struct drm_panthor_group_destroy

傳遞給 DRM_IOCTL_PANTHOR_GROUP_DESTROY 的引數

定義:

struct drm_panthor_group_destroy {
    __u32 group_handle;
    __u32 pad;
};

成員

group_handle

要銷燬的組

pad

填充欄位，MBZ。

struct drm_panthor_queue_submit

作業提交引數。

定義:

struct drm_panthor_queue_submit {
    __u32 queue_index;
    __u32 stream_size;
    __u64 stream_addr;
    __u32 latest_flush;
    __u32 pad;
    struct drm_panthor_obj_array syncs;
};

成員

queue_index

組內佇列的索引。

stream_size

要執行的命令流的大小。

必須按 64 位/8 位元組對齊（CS 指令的大小）

如果 stream_addr 也為零，則可以為零。

當流大小為零時，佇列提交充當同步點。

stream_addr

要執行的命令流的 GPU 地址。

必須按 64 位元組對齊。

如果 stream_size 也為零，則可以為零。

latest_flush

在構建流時讀取的 FLUSH_ID。

這允許為在提交時完成的自動重新整理+使無效（全部）消除快取重新整理，這是確保 GPU 在讀取間接命令流緩衝區時不會獲得垃圾所必需的。如果希望無條件地進行快取重新整理，請在此處傳遞零。

當 stream_size 為零時忽略。

pad

MBZ。

syncs

struct drm_panthor_sync_op 同步運算元組。

描述

這描述了要從核心命令流環形緩衝區呼叫的 userspace 命令流。佇列提交始終是組提交的一部分，採用一個或多個作業以提交到基礎佇列。

struct drm_panthor_group_submit

傳遞給 DRM_IOCTL_PANTHOR_GROUP_SUBMIT 的引數

定義:

struct drm_panthor_group_submit {
    __u32 group_handle;
    __u32 pad;
    struct drm_panthor_obj_array queue_submits;
};

成員

group_handle

要將作業排隊的組的控制代碼。

pad

MBZ。

queue_submits

drm_panthor_queue_submit 物件的陣列。

enum drm_panthor_group_state_flags

組狀態標誌

常量

DRM_PANTHOR_GROUP_STATE_TIMEDOUT

組有未完成的作業。

當組最終設定此標誌時，無法將作業提交到其佇列。

DRM_PANTHOR_GROUP_STATE_FATAL_FAULT

組有致命錯誤。

當組最終設定此標誌時，無法將作業提交到其佇列。

DRM_PANTHOR_GROUP_STATE_INNOCENT

組在由其他組引起的重置期間被終止。

只有在設定了 DRM_PANTHOR_GROUP_STATE_TIMEDOUT 並且未設定 DRM_PANTHOR_GROUP_STATE_FATAL_FAULT 時才能設定此標誌。

struct drm_panthor_group_get_state

傳遞給 DRM_IOCTL_PANTHOR_GROUP_GET_STATE 的引數

定義:

struct drm_panthor_group_get_state {
    __u32 group_handle;
    __u32 state;
    __u32 fatal_queues;
    __u32 pad;
};

成員

group_handle

查詢狀態的組的控制代碼

state

編碼組狀態的 DRM_PANTHOR_GROUP_STATE_* 標誌的組合。

fatal_queues

面臨致命錯誤的佇列的位掩碼。

pad

MBZ

描述

用於查詢組的狀態並確定是否應建立新組以替換它。

struct drm_panthor_tiler_heap_create

傳遞給 DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE 的引數

定義:

struct drm_panthor_tiler_heap_create {
    __u32 vm_id;
    __u32 initial_chunk_count;
    __u32 chunk_size;
    __u32 max_chunks;
    __u32 target_in_flight;
    __u32 handle;
    __u64 tiler_heap_ctx_gpu_va;
    __u64 first_heap_chunk_gpu_va;
};

成員

vm_id

平鋪器堆應對映到的 VM ID

initial_chunk_count

要分配的初始塊數。必須至少為一個。

chunk_size

塊大小。

必須按頁面對齊，並且位於 [128k:8M] 範圍內。

max_chunks

可以分配的最大塊數。

必須至少為 initial_chunk_count。

target_in_flight

最大飛行中渲染過程數。

如果堆中有超過平鋪器作業在飛行中，FW 將等待渲染過程完成，然後再將新的平鋪器作業排隊。

handle

返回的堆控制代碼。傳遞迴 DESTROY_TILER_HEAP。

tiler_heap_ctx_gpu_va

返回的堆 GPU 虛擬地址

first_heap_chunk_gpu_va

第一個堆塊。

平鋪器堆由形成單鏈表的堆塊組成。這是列表中的第一個元素。

struct drm_panthor_tiler_heap_destroy

傳遞給 DRM_IOCTL_PANTHOR_TILER_HEAP_DESTROY 的引數

定義:

struct drm_panthor_tiler_heap_destroy {
    __u32 handle;
    __u32 pad;
};

成員

handle

要銷燬的平鋪器堆的控制代碼。

必須是由 DRM_IOCTL_PANTHOR_TILER_HEAP_CREATE 返回的有效堆控制代碼。

pad

填充欄位，MBZ。

struct drm_panthor_bo_set_label

傳遞給 DRM_IOCTL_PANTHOR_BO_SET_LABEL 的引數

定義:

struct drm_panthor_bo_set_label {
    __u32 handle;
    __u32 pad;
    __u64 label;
};

成員

handle

要標記的緩衝區物件的控制代碼。

pad

MBZ。

label

指向以 NUL 結尾的字串的使用者指標

長度不能大於 4096

DRM_IOCTL_PANTHOR

DRM_IOCTL_PANTHOR (__access, __id, __type)

構建 Panthor IOCTL 數字

引數

__access

訪問型別。必須是 R、W 或 RW。

__id

DRM_PANTHOR_xxx id 之一。

__type

傳遞給 IOCTL 的型別的字尾。

描述

不要直接使用此宏，請改用 DRM_IOCTL_PANTHOR_xxx 值。

Return

要從 userspace 傳遞給 ioctl() 的 IOCTL 數字。

drm/xe uAPI

Xe 裝置框圖

下圖表示 Xe 驅動程式支援的離散 GPU 的高階簡化圖。它顯示了一些理解此 API 所必需的裝置元件，以及它們之間的相互關係。此圖不代表真實的硬體

┌──────────────────────────────────────────────────────────────────┐
│ ┌──────────────────────────────────────────────────┐ ┌─────────┐ │
│ │        ┌───────────────────────┐   ┌─────┐       │ │ ┌─────┐ │ │
│ │        │         VRAM0         ├───┤ ... │       │ │ │VRAM1│ │ │
│ │        └───────────┬───────────┘   └─GT1─┘       │ │ └──┬──┘ │ │
│ │ ┌──────────────────┴───────────────────────────┐ │ │ ┌──┴──┐ │ │
│ │ │ ┌─────────────────────┐  ┌─────────────────┐ │ │ │ │     │ │ │
│ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
│ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │RCS0 │ │BCS0 │ │ │ │ │ │     │ │ │
│ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
│ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
│ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │VCS0 │ │VCS1 │ │ │ │ │ │     │ │ │
│ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
│ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
│ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │VECS0│ │VECS1│ │ │ │ │ │ ... │ │ │
│ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
│ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
│ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │CCS0 │ │CCS1 │ │ │ │ │ │     │ │ │
│ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
│ │ │ └─────────DSS─────────┘  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
│ │ │                          │ │CCS2 │ │CCS3 │ │ │ │ │ │     │ │ │
│ │ │ ┌─────┐ ┌─────┐ ┌─────┐  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
│ │ │ │ ... │ │ ... │ │ ... │  │                 │ │ │ │ │     │ │ │
│ │ │ └─DSS─┘ └─DSS─┘ └─DSS─┘  └─────Engines─────┘ │ │ │ │     │ │ │
│ │ └───────────────────────────GT0────────────────┘ │ │ └─GT2─┘ │ │
│ └────────────────────────────Tile0─────────────────┘ └─ Tile1──┘ │
└─────────────────────────────Device0───────┬──────────────────────┘
                                            │
                     ───────────────────────┴────────── PCI bus

Xe uAPI 概述

本節旨在描述 Xe 的 IOCTL 條目、其結構以及其他與 Xe 相關的 uAPI，例如 uevent 和 PMU（平臺監控單元）相關的條目和用法。

支援的 IOCTL 列表

  • DRM_IOCTL_XE_DEVICE_QUERY

  • DRM_IOCTL_XE_GEM_CREATE

  • DRM_IOCTL_XE_GEM_MMAP_OFFSET

  • DRM_IOCTL_XE_VM_CREATE

  • DRM_IOCTL_XE_VM_DESTROY

  • DRM_IOCTL_XE_VM_BIND

  • DRM_IOCTL_XE_EXEC_QUEUE_CREATE

  • DRM_IOCTL_XE_EXEC_QUEUE_DESTROY

  • DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY

  • DRM_IOCTL_XE_EXEC

  • DRM_IOCTL_XE_WAIT_USER_FENCE

  • DRM_IOCTL_XE_OBSERVATION

Xe IOCTL 擴充套件

在詳細介紹 IOCTL 及其結構之前，重要的是要強調 Xe 中的每個 IOCTL 都是可擴充套件的。

許多介面需要隨著時間的推移而增長。 在大多數情況下，我們可以簡單地擴充套件結構並讓使用者空間傳入更多資料。 另一種選擇，如 Vulkan 為前向和後向相容性提供擴充套件的方法所證明的那樣，是使用可選結構的列表來提供這些額外的詳細資訊。

使用擴充套件鏈的關鍵優勢在於，與不斷增長的複雜結構相比，它可以讓我們更輕鬆地重新定義介面，並且該介面的大部分是完全可選的。 缺點是更多的指標追逐； 使用 u64 內部封裝的指標跨 __user 邊界進行追逐。

示例連結

struct drm_xe_user_extension ext3 {
        .next_extension = 0, // end
        .name = ...,
};
struct drm_xe_user_extension ext2 {
        .next_extension = (uintptr_t)&ext3,
        .name = ...,
};
struct drm_xe_user_extension ext1 {
        .next_extension = (uintptr_t)&ext2,
        .name = ...,
};

通常 struct drm_xe_user_extension 會嵌入到某些 uAPI 結構中，在這種情況下，我們會將鏈的頭部（即 ext1）提供給它，然後它會應用上述所有擴充套件。

struct drm_xe_user_extension

用於定義擴充套件鏈的基類

定義:

struct drm_xe_user_extension {
    __u64 next_extension;
    __u32 name;
    __u32 pad;
};

成員

next_extension

指向下一個 struct drm_xe_user_extension 的指標，如果到達末尾則為零。

name

擴充套件的名稱。

請注意，此處的名稱只是一個整數。

另請注意，此名稱空間不是整個驅動程式的全域性名稱空間，而是其範圍/含義僅限於嵌入 struct drm_xe_user_extension 的特定 uAPI 部分。

pad

MBZ

所有未定義的位必須為零。

struct drm_xe_ext_set_property

通用設定屬性擴充套件

定義:

struct drm_xe_ext_set_property {
    struct drm_xe_user_extension base;
    __u32 property;
    __u32 pad;
    __u64 value;
    __u64 reserved[2];
};

成員

base

基本使用者擴充套件

屬性

要設定的屬性

pad

MBZ

value

屬性值

保留

保留

描述

一個通用結構，允許使用 set_property 操作擴充套件任何 Xe 的 IOCTL。

struct drm_xe_engine_class_instance

引擎類的例項

定義:

struct drm_xe_engine_class_instance {
#define DRM_XE_ENGINE_CLASS_RENDER              0;
#define DRM_XE_ENGINE_CLASS_COPY                1;
#define DRM_XE_ENGINE_CLASS_VIDEO_DECODE        2;
#define DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE       3;
#define DRM_XE_ENGINE_CLASS_COMPUTE             4;
#define DRM_XE_ENGINE_CLASS_VM_BIND             5;
    __u16 engine_class;
    __u16 engine_instance;
    __u16 gt_id;
    __u16 pad;
};

成員

engine_class

引擎類 ID

engine_instance

引擎例項 ID

gt_id

此 GT 在 PCI 裝置中的唯一 ID

pad

MBZ

描述

它作為 drm_xe_engine 的一部分返回，但也用作 drm_xe_exec_queue_create 和 drm_xe_query_engine_cycles 的引擎選擇的輸入

engine_class 可以是

  • DRM_XE_ENGINE_CLASS_RENDER

  • DRM_XE_ENGINE_CLASS_COPY

  • DRM_XE_ENGINE_CLASS_VIDEO_DECODE

  • DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE

  • DRM_XE_ENGINE_CLASS_COMPUTE

  • DRM_XE_ENGINE_CLASS_VM_BIND - 僅核心類（不是實際的硬體引擎類）。用於建立 VM 繫結操作的有序佇列。

struct drm_xe_engine

描述硬體引擎

定義:

struct drm_xe_engine {
    struct drm_xe_engine_class_instance instance;
    __u64 reserved[3];
};

成員

例項

drm_xe_engine_class_instance

保留

保留

struct drm_xe_query_engines

描述引擎

定義:

struct drm_xe_query_engines {
    __u32 num_engines;
    __u32 pad;
    struct drm_xe_engine engines[];
};

成員

num_engines

在 engines 中返回的引擎數量

pad

MBZ

engines

為此裝置返回的引擎

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_ENGINES 的結構 drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_engines 陣列。

enum drm_xe_memory_class

支援的記憶體類。

常量

DRM_XE_MEM_REGION_CLASS_SYSMEM

表示系統記憶體。

DRM_XE_MEM_REGION_CLASS_VRAM

在離散平臺上，這表示裝置本地的記憶體，我們稱之為 VRAM。在整合平臺上無效。

struct drm_xe_mem_region

將某個區域描述為驅動程式已知。

定義:

struct drm_xe_mem_region {
    __u16 mem_class;
    __u16 instance;
    __u32 min_page_size;
    __u64 total_size;
    __u64 used;
    __u64 cpu_visible_size;
    __u64 cpu_visible_used;
    __u64 reserved[6];
};

成員

mem_class

描述此區域的記憶體類。

有關支援的值，請參見 enum drm_xe_memory_class。

例項

此區域的唯一 ID，用作 DRM_IOCTL_XE_GEM_CREATE 引數的放置位掩碼中的索引

min_page_size

此區域的最小頁大小（以位元組為單位）。

當核心為此區域分配記憶體時，底層頁面的大小將至少為 min_page_size。允許放置在此區域中的緩衝區物件必須使用與此值對齊的大小建立。 GPU 虛擬地址對映（部分）也可能放置在此區域中的緩衝區物件必須使其 GPU 虛擬地址和範圍與此值對齊。如果未滿足對齊限制，受影響的 IOCTLS 將返回 -EINVAL。

total_size

此區域的可用大小（以位元組為單位）。

used

此區域中使用的記憶體估計值（以位元組為單位）。

需要 CAP_PERFMON 或 CAP_SYS_ADMIN 才能獲得可靠的記帳。如果沒有此許可權，此處的值將始終等於零。

cpu_visible_size

此區域有多少可以由 CPU 訪問（以位元組為單位）。

這將始終 <= total_size，其餘部分（如果有）將無法透過 CPU 訪問。如果 CPU 可訪問部分小於 total_size，則稱為小 BAR 系統。

在沒有小 BAR（全 BAR）的系統上，probed_size 將始終等於 total_size，因為所有這些都將可以透過 CPU 訪問。

請注意，這僅針對 DRM_XE_MEM_REGION_CLASS_VRAM 區域進行跟蹤（對於其他型別，此處的值將始終等於零）。

cpu_visible_used

使用的 CPU 可見記憶體的估計值（以位元組為單位）。

需要 CAP_PERFMON 或 CAP_SYS_ADMIN 才能獲得可靠的記帳。如果沒有此許可權，此處的值將始終等於零。請注意，這僅針對 DRM_XE_MEM_REGION_CLASS_VRAM 區域進行跟蹤（對於其他型別，此處的值將始終為零）。

保留

保留

struct drm_xe_query_mem_regions

描述記憶體區域

定義:

struct drm_xe_query_mem_regions {
    __u32 num_mem_regions;
    __u32 pad;
    struct drm_xe_mem_region mem_regions[];
};

成員

num_mem_regions

mem_regions 中返回的記憶體區域數

pad

MBZ

mem_regions

為此裝置返回的記憶體區域

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_MEM_REGIONS 的 struct drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_mem_regions。

struct drm_xe_query_config

描述裝置配置

定義:

struct drm_xe_query_config {
    __u32 num_params;
    __u32 pad;
#define DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID   0;
#define DRM_XE_QUERY_CONFIG_FLAGS                       1;
#define DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM       (1 << 0);
#define DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY        (1 << 1);
#define DRM_XE_QUERY_CONFIG_FLAG_HAS_CPU_ADDR_MIRROR    (1 << 2);
#define DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT               2;
#define DRM_XE_QUERY_CONFIG_VA_BITS                     3;
#define DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY     4;
    __u64 info[];
};

成員

num_params

在資訊中返回的引數數量

pad

MBZ

info

包含配置資訊的元素陣列

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_CONFIG 的 struct drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_config。

info 中的索引可以是

  • DRM_XE_QUERY_CONFIG_REV_AND_DEVICE_ID - 裝置 ID（低 16 位）和裝置修訂版（接下來的 8 位）

  • DRM_XE_QUERY_CONFIG_FLAGS - 描述裝置配置的標誌，請參見下面的列表

    • DRM_XE_QUERY_CONFIG_FLAG_HAS_VRAM - 如果裝置具有可用的 VRAM，則設定標誌

    • DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY - 如果裝置支援低延遲提示，則設定標誌

    • DRM_XE_QUERY_CONFIG_FLAG_HAS_CPU_ADDR_MIRROR - 如果裝置具有 CPU 地址映象支援，則設定標誌

  • DRM_XE_QUERY_CONFIG_MIN_ALIGNMENT - 此裝置所需的最小記憶體對齊，通常為 SZ_4K 或 SZ_64K

  • DRM_XE_QUERY_CONFIG_VA_BITS - 虛擬地址的最大位數

  • DRM_XE_QUERY_CONFIG_MAX_EXEC_QUEUE_PRIORITY - 最高可用執行佇列優先順序的value

struct drm_xe_gt

描述單個 GT。

定義:

struct drm_xe_gt {
#define DRM_XE_QUERY_GT_TYPE_MAIN               0;
#define DRM_XE_QUERY_GT_TYPE_MEDIA              1;
    __u16 type;
    __u16 tile_id;
    __u16 gt_id;
    __u16 pad[3];
    __u32 reference_clock;
    __u64 near_mem_regions;
    __u64 far_mem_regions;
    __u16 ip_ver_major;
    __u16 ip_ver_minor;
    __u16 ip_ver_rev;
    __u16 pad2;
    __u64 reserved[7];
};

成員

type

GT 型別：主或媒體

tile_id

此 GT 所在的瓦片 ID（僅限資訊）

gt_id

此 GT 在 PCI 裝置中的唯一 ID

pad

MBZ

reference_clock

時間戳的時鐘頻率

near_mem_regions

來自 drm_xe_query_mem_regions 的例項的位掩碼，這些例項最接近此 GT 的當前引擎。此掩碼中的每個索引直接引用 struct drm_xe_query_mem_regions 的例項，不應對順序做任何假設。每個區域的型別由 struct drm_xe_query_mem_regions 的 mem_class 描述。

far_mem_regions

來自 drm_xe_query_mem_regions 的例項的位掩碼，這些例項遠離此 GT 的引擎。一般來說，與 near_mem_regions 相比，它們具有額外的間接性。對於離散裝置，這可能意味著系統記憶體和駐留在不同瓦片中的記憶體。此掩碼中的每個索引直接引用 struct drm_xe_query_mem_regions 的例項，不應對順序做任何假設。每個區域的型別由 struct drm_xe_query_mem_regions 的 mem_class 描述。

ip_ver_major

GMD_ID 平臺上的圖形/媒體 IP 主版本

ip_ver_minor

GMD_ID 平臺上的圖形/媒體 IP 次版本

ip_ver_rev

GMD_ID 平臺上的圖形/媒體 IP 修訂版

pad2

MBZ

保留

保留

描述

與 drm_xe_query_gt_list 一起使用，它將返回包含所有現有 GT 單個描述的列表。圖形技術 (GT) 是 GPU/瓦片的子集，負責實現圖形和/或媒體操作。

type 中的索引可以是

  • DRM_XE_QUERY_GT_TYPE_MAIN

  • DRM_XE_QUERY_GT_TYPE_MEDIA

struct drm_xe_query_gt_list

包含 GT 描述項的列表。

定義:

struct drm_xe_query_gt_list {
    __u32 num_gt;
    __u32 pad;
    struct drm_xe_gt gt_list[];
};

成員

num_gt

在 gt_list 中返回的 GT 項數

pad

MBZ

gt_list

為此裝置返回的 GT 列表

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_GT_LIST 的 struct drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_gt_list。

struct drm_xe_query_topology_mask

描述 GT 的拓撲掩碼

定義:

struct drm_xe_query_topology_mask {
    __u16 gt_id;
#define DRM_XE_TOPO_DSS_GEOMETRY        1;
#define DRM_XE_TOPO_DSS_COMPUTE         2;
#define DRM_XE_TOPO_L3_BANK             3;
#define DRM_XE_TOPO_EU_PER_DSS          4;
#define DRM_XE_TOPO_SIMD16_EU_PER_DSS   5;
    __u16 type;
    __u32 num_bytes;
    __u8 mask[];
};

成員

gt_id

gt_id

type

掩碼與之關聯的 GT ID

type

掩碼型別

num_bytes

請求的掩碼中的位元組數

描述

mask

num_bytes 的小端掩碼

這是硬體拓撲，它反映了 GPU 的內部物理結構。

  • 如果使用 .query 等於 DRM_XE_DEVICE_QUERY_GT_TOPOLOGY 的 struct drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_topology_mask。

  • type 可以是

  • DRM_XE_TOPO_DSS_GEOMETRY - 用於查詢可用於幾何運算的雙子切片 (DSS) 的掩碼。例如，查詢響應在掩碼中包含以下內容：DSS_GEOMETRY    ff ff ff ff 00 00 00 00 表示 32 個 DSS 可用於幾何運算。

  • DRM_XE_TOPO_DSS_COMPUTE - 用於查詢可用於計算運算的雙子切片 (DSS) 的掩碼。例如，查詢響應在掩碼中包含以下內容：DSS_COMPUTE    ff ff ff ff 00 00 00 00 表示 32 個 DSS 可用於計算。

  • DRM_XE_TOPO_L3_BANK - 用於查詢已啟用的 L3 儲存體的掩碼。如果驅動程式無法從硬體查詢掩碼，則可以省略此型別。

DRM_XE_TOPO_EU_PER_DSS - 用於查詢每個雙子切片 (DSS) 可用的執行單元 (EU) 的掩碼。例如，查詢響應在掩碼中包含以下內容：EU_PER_DSS    ff ff 00 00 00 00 00 00 表示每個 DSS 具有 16 個 SIMD8 EU。如果裝置沒有 SIMD8 EU，則可以省略此型別。

DRM_XE_TOPO_SIMD16_EU_PER_DSS - 用於查詢每個雙子切片 (DSS) 可用的 SIMD16 執行單元 (EU) 的掩碼。例如，查詢響應在掩碼中包含以下內容：SIMD16_EU_PER_DSS    ff ff 00 00 00 00 00 00 表示每個 DSS 具有 16 個 SIMD16 EU。如果裝置沒有 SIMD16 EU，則可以省略此型別。

定義:

struct drm_xe_query_engine_cycles {
    struct drm_xe_engine_class_instance eci;
    __s32 clockid;
    __u32 width;
    __u64 engine_cycles;
    __u64 cpu_timestamp;
    __u64 cpu_delta;
};

成員

struct drm_xe_query_engine_cycles

關聯 CPU 和 GPU 時間戳

eci

這是使用者輸入的，是要查詢命令流式傳輸器週期的引擎。

width

clockid

這是使用者輸入的，是 CPU 時間戳的參考時鐘 ID。有關定義，請參見 clock_gettime(2) 和 perf_event_open(2)。支援的時鐘 ID 為 CLOCK_MONOTONIC、CLOCK_MONOTONIC_RAW、CLOCK_REALTIME、CLOCK_BOOTTIME、CLOCK_TAI。

以位為單位的引擎週期計數器的寬度。

engine_cycles

從其在 0x358 偏移量處的暫存器讀取的引擎週期。

cpu_timestamp

CPU 時間戳（以納秒為單位）。在使用使用者設定的參考 clockid 讀取 engine_cycles 暫存器之前捕獲時間戳。

描述

cpu_delta

在讀取 engine_cycles 暫存器的低位雙字附近捕獲的時間增量（以納秒為單位）。

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_ENGINE_CYCLES 的 struct drm_xe_device_query 進行查詢，則答覆會在 .data 中使用 struct drm_xe_query_engine_cycles。 struct drm_xe_query_engine_cycles 由使用者分配，並且 .data 指向此已分配的結構。

該查詢返回引擎週期，該週期與 GT 的 reference_clock 一起可用於計算引擎時間戳。此外，該查詢還返回一組 CPU 時間戳，指示捕獲命令流式傳輸器週期計數的時間。

定義:

struct drm_xe_query_uc_fw_version {
#define XE_QUERY_UC_TYPE_GUC_SUBMISSION 0;
#define XE_QUERY_UC_TYPE_HUC 1;
    __u16 uc_type;
    __u16 pad;
    __u32 branch_ver;
    __u32 major_ver;
    __u32 minor_ver;
    __u32 patch_ver;
    __u32 pad2;
    __u64 reserved;
};

成員

struct drm_xe_query_uc_fw_version

查詢微控制器韌體版本

pad

MBZ

uc_type

要查詢韌體版本的微控制器型別

branch_ver

分支 uc 韌體版本

major_ver

主要 uc 韌體版本

minor_ver

次要 uc 韌體版本

pad2

MBZ

保留

保留

描述

patch_ver

修補 uc 韌體版本

給定 uc_type，這將返回微控制器韌體的分支、主要、次要和修補程式版本。

定義:

struct drm_xe_query_pxp_status {
    __u32 status;
    __u32 supported_session_types;
};

成員

struct drm_xe_query_pxp_status

查詢 PXP 是否已準備就緒

status

當前 PXP 狀態

描述

supported_session_types

支援的 PXP 會話型別的位掩碼

如果 PXP 已啟用且未發生嚴重錯誤，則狀態將設定為以下值之一：0：PXP 初始化仍在進行中 1：PXP 初始化完成

如果 PXP 未啟用或出現問題，則查詢將失敗，並顯示以下錯誤程式碼之一：-ENODEV：不支援或已停用 PXP；-EIO：初始化期間發生嚴重錯誤，因此永遠不會啟用 PXP；-EINVAL：作為查詢的一部分提供的 value 不正確；-EFAULT：核心和使用者空間之間複製記憶體時出錯。

狀態只有在驅動程式載入後的前幾秒鐘內才能為 0。如果一切按預期執行，則狀態將在不到 1 秒的時間內轉換為初始化完成，而在出現錯誤的情況下，驅動程式可能需要更長的時間才能開始返回錯誤程式碼，但它仍然應該少於 10 秒。

支援的會話型別位掩碼基於 enum drm_xe_pxp_session_type 中的值。 TYPE_NONE 始終受支援，因此不會在位掩碼中報告。

定義:

struct drm_xe_device_query {
    __u64 extensions;
#define DRM_XE_DEVICE_QUERY_ENGINES             0;
#define DRM_XE_DEVICE_QUERY_MEM_REGIONS         1;
#define DRM_XE_DEVICE_QUERY_CONFIG              2;
#define DRM_XE_DEVICE_QUERY_GT_LIST             3;
#define DRM_XE_DEVICE_QUERY_HWCONFIG            4;
#define DRM_XE_DEVICE_QUERY_GT_TOPOLOGY         5;
#define DRM_XE_DEVICE_QUERY_ENGINE_CYCLES       6;
#define DRM_XE_DEVICE_QUERY_UC_FW_VERSION       7;
#define DRM_XE_DEVICE_QUERY_OA_UNITS            8;
#define DRM_XE_DEVICE_QUERY_PXP_STATUS          9;
#define DRM_XE_DEVICE_QUERY_EU_STALL            10;
    __u32 query;
    __u32 size;
    __u64 data;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

DRM_IOCTL_XE_DEVICE_QUERY 的輸入 - 查詢裝置資訊的主要結構

ext

size

指向第一個擴充套件結構的指標（如果有）

data

query

保留

保留

描述

要查詢的資料型別

size

  • 查詢資料的大小

  • data

  • 查詢的資料放置在此處

  • 使用者在 DRM_XE_DEVICE_QUERY_* 中選擇要查詢的資料型別，並在查詢成員中設定 value。這決定了驅動程式在資料中提供的結構的型別，在 struct drm_xe_query_* 中。

  • query 可以是

  • DRM_XE_DEVICE_QUERY_ENGINES

  • DRM_XE_DEVICE_QUERY_MEM_REGIONS

  • DRM_XE_DEVICE_QUERY_CONFIG

DRM_XE_DEVICE_QUERY_GT_LIST

DRM_XE_DEVICE_QUERY_HWCONFIG - 查詢型別以檢索裝置的硬體配置，例如有關切片、記憶體、快取等的資訊。它作為鍵/值屬性的表提供。

struct drm_xe_query_engines *engines;
struct drm_xe_device_query query = {
    .extensions = 0,
    .query = DRM_XE_DEVICE_QUERY_ENGINES,
    .size = 0,
    .data = 0,
};
ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, &query);
engines = malloc(query.size);
query.data = (uintptr_t)engines;
ioctl(fd, DRM_IOCTL_XE_DEVICE_QUERY, &query);
for (int i = 0; i < engines->num_engines; i++) {
    printf("Engine %d: %s\n", i,
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_RENDER ? "RENDER":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_COPY ? "COPY":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_VIDEO_DECODE ? "VIDEO_DECODE":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_VIDEO_ENHANCE ? "VIDEO_ENHANCE":
        engines->engines[i].instance.engine_class ==
            DRM_XE_ENGINE_CLASS_COMPUTE ? "COMPUTE":
        "UNKNOWN");
}
free(engines);
DRM_XE_DEVICE_QUERY_GT_TOPOLOGY

DRM_XE_DEVICE_QUERY_ENGINE_CYCLES

定義:

struct drm_xe_gem_create {
#define DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY        0;
#define DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE       0;
    __u64 extensions;
    __u64 size;
    __u32 placement;
#define DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING            (1 << 0);
#define DRM_XE_GEM_CREATE_FLAG_SCANOUT                  (1 << 1);
#define DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM       (1 << 2);
    __u32 flags;
    __u32 vm_id;
    __u32 handle;
#define DRM_XE_GEM_CPU_CACHING_WB                      1;
#define DRM_XE_GEM_CPU_CACHING_WC                      2;
    __u16 cpu_caching;
    __u16 pad[3];
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

size

DRM_XE_DEVICE_QUERY_PXP_STATUS

如果 size 設定為 0，則驅動程式會將其填充為請求資料型別所需的 size。如果 size 等於所需 size，則查詢的資訊將複製到資料中。如果 size 設定為與 0 不同且與所需 size 不同的 value，則 IOCTL 呼叫將返回 -EINVAL。

例如，以下程式碼段允許檢索和列印有關帶有 DRM_XE_DEVICE_QUERY_ENGINES 的裝置引擎的資訊

flags

struct drm_xe_gem_create

vm_id

DRM_IOCTL_XE_GEM_CREATE 的輸入 - 用於 gem 建立的結構

size

  1. 要建立的物件的大小，必須與區域（系統或 vram）最小對齊 (min_page_size) 匹配。

  2. placement

handle

返回的物件的控制代碼。

物件控制代碼為非零。

BO 可以放置在其中的記憶體例項的掩碼。此掩碼中的每個索引直接引用 struct drm_xe_query_mem_regions 的例項，不應對順序做任何假設。每個區域的型別由 struct drm_xe_query_mem_regions 的 mem_class 描述。

flags

pad

MBZ

保留

保留

描述

標誌，當前 BO 可以放置在其中的記憶體例項的掩碼

  • vm_id

  • 附加的 VM（如果有）

  • 如果指定了 VM，則此 BO 必須

只能繫結到該 VM。

  • 無法匯出為 PRIME fd。

  • cpu_caching

為此物件選擇的 CPU 快取模式。如果 mmaping 物件，則還將使用此處選擇的模式。唯一的例外是在離散 GPU 上對映系統記憶體（包括驅逐到系統的資料）時。然後，所選快取模式將被覆蓋為 DRM_XE_GEM_CPU_CACHING_WB，並保證 GPU 和 CPU 之間的連貫性。現有 CPU 對映的快取模式將透明地更新為使用者空間客戶端。

  • flags 可以是

DRM_XE_GEM_CREATE_FLAG_DEFER_BACKING

DRM_XE_GEM_CREATE_FLAG_SCANOUT

定義:

struct drm_xe_gem_mmap_offset {
    __u64 extensions;
    __u32 handle;
#define DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER     (1 << 0);
    __u32 flags;
    __u64 offset;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

handle

要對映的物件的控制代碼。

flags

DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - 使用 VRAM 作為可能的放置時，請確保相應的 VRAM 分配將始終使用 VRAM 的 CPU 可訪問部分。這對於小條系統很重要（在全條系統上，這會變成空操作）。注意 1：如果核心應將分配溢位到系統記憶體，則可以將系統記憶體用作額外的放置，如果在 VRAM 的 CPU 可訪問部分中無法提供空間（提供與 i915 介面相同的行為，請參見 I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS）。注意 2：對於清除顏色 CCS 圖面，核心需要讀取儲存在緩衝區中的清除顏色 value，並且在離散平臺上，我們需要使用 VRAM 進行顯示圖面，因此核心需要為此類物件設定此標誌，否則將在小條系統上引發錯誤。

offset

用於後續 mmap 呼叫的虛假偏移量

保留

保留

描述

標誌，當前 BO 可以放置在其中的記憶體例項的掩碼

  • cpu_caching 支援以下值

DRM_XE_GEM_CPU_CACHING_WB - 使用回寫快取分配頁面。在 iGPU 上，這不能用於掃描輸出圖面。當前不允許放置在 VRAM 中的物件。

struct drm_xe_gem_mmap_offset mmo = {
    .handle = 0, // must be set to 0
    .flags = DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER,
};

err = ioctl(fd, DRM_IOCTL_XE_GEM_MMAP_OFFSET, &mmo);
map = mmap(NULL, size, PROT_WRITE, MAP_SHARED, fd, mmo.offset);
map[i] = 0xdeadbeaf; // issue barrier

DRM_XE_GEM_CPU_CACHING_WC - 將頁面分配為寫組合。這是未快取的。掃描輸出圖面應可能使用此設定。可以放置在 VRAM 中的所有物件必須使用此設定。

此 ioctl 支援透過 DRM_XE_GEM_CREATE_EXTENSION_SET_PROPERTY 擴充套件設定以下屬性，該擴充套件使用通用 drm_xe_ext_set_property 結構

DRM_XE_GEM_CREATE_SET_PROPERTY_PXP_TYPE - 設定此物件將使用的 PXP 會話型別。有效值在 enum drm_xe_pxp_session_type 中列出。 DRM_XE_PXP_TYPE_NONE 是預設行為，因此無需顯式設定。與 DRM_XE_PXP_TYPE_HWDRM 型別的會話一起使用的物件將在其建立後發生 PXP 失效事件時標記為無效。嘗試翻轉無效物件將導致顯示黑幀。將拒絕在 VM 中映射了無效物件的提交。

struct drm_xe_gem_mmap_offset

定義:

struct drm_xe_vm_create {
    __u64 extensions;
#define DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE      (1 << 0);
#define DRM_XE_VM_CREATE_FLAG_LR_MODE           (1 << 1);
#define DRM_XE_VM_CREATE_FLAG_FAULT_MODE        (1 << 2);
    __u32 flags;
    __u32 vm_id;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

flags

DRM_XE_GEM_CREATE_FLAG_NEEDS_VISIBLE_VRAM - 使用 VRAM 作為可能的放置時，請確保相應的 VRAM 分配將始終使用 VRAM 的 CPU 可訪問部分。這對於小條系統很重要（在全條系統上，這會變成空操作）。注意 1：如果核心應將分配溢位到系統記憶體，則可以將系統記憶體用作額外的放置，如果在 VRAM 的 CPU 可訪問部分中無法提供空間（提供與 i915 介面相同的行為，請參見 I915_GEM_CREATE_EXT_FLAG_NEEDS_CPU_ACCESS）。注意 2：對於清除顏色 CCS 圖面，核心需要讀取儲存在緩衝區中的清除顏色 value，並且在離散平臺上，我們需要使用 VRAM 進行顯示圖面，因此核心需要為此類物件設定此標誌，否則將在小條系統上引發錯誤。

vm_id

DRM_IOCTL_XE_GEM_MMAP_OFFSET 的輸入

保留

保留

描述

標誌，當前 BO 可以放置在其中的記憶體例項的掩碼

  • flags

  • DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER - 對於使用者，用於查詢在 mmap ioctl 中使用的特殊偏移量。寫入返回的 mmap 地址將生成一個低開銷的 PCI 記憶體屏障（避免 IOCTL 呼叫以及寫入也會增加開銷的 VRAM），就像 MI_MEM_FENCE 指令一樣。

  • 大致用法如下

注意

由於硬體限制，mmap 大小最多為 4K。因此，僅在支援 4K 頁面大小的 CPU 架構上支援此介面。 mmap_offset ioctl 將檢測到這一點並優雅地返回錯誤，其中使用者空間應具有用於觸發屏障的不同回退方法。

定義:

struct drm_xe_vm_destroy {
    __u32 vm_id;
    __u32 pad;
    __u64 reserved[2];
};

成員

vm_id

struct drm_xe_vm_create

pad

MBZ

保留

保留

DRM_IOCTL_XE_VM_CREATE 的輸入

vm_id

定義:

struct drm_xe_vm_bind_op {
    __u64 extensions;
    __u32 obj;
    __u16 pat_index;
    __u16 pad;
    union {
        __u64 obj_offset;
        __u64 userptr;
        __s64 cpu_addr_mirror_offset;
    };
    __u64 range;
    __u64 addr;
#define DRM_XE_VM_BIND_OP_MAP           0x0;
#define DRM_XE_VM_BIND_OP_UNMAP         0x1;
#define DRM_XE_VM_BIND_OP_MAP_USERPTR   0x2;
#define DRM_XE_VM_BIND_OP_UNMAP_ALL     0x3;
#define DRM_XE_VM_BIND_OP_PREFETCH      0x4;
    __u32 op;
#define DRM_XE_VM_BIND_FLAG_READONLY    (1 << 0);
#define DRM_XE_VM_BIND_FLAG_IMMEDIATE   (1 << 1);
#define DRM_XE_VM_BIND_FLAG_NULL        (1 << 2);
#define DRM_XE_VM_BIND_FLAG_DUMPABLE    (1 << 3);
#define DRM_XE_VM_BIND_FLAG_CHECK_PXP   (1 << 4);
#define DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR     (1 << 5);
    __u32 flags;
    __u32 prefetch_mem_region_instance;
    __u32 pad2;
    __u64 reserved[3];
};

成員

extensions

struct drm_xe_device_query

返回的 VM ID

flags

pat_index

DRM_XE_VM_CREATE_FLAG_SCRATCH_PAGE - 將 VM 的整個虛擬地址空間對映到暫存頁面。 vm_bind 會覆蓋暫存頁面對映。此標誌與 DRM_XE_VM_CREATE_FLAG_FAULT_MODE 標誌互斥，但在 x2 和 xe3 平臺上除外。

DRM_XE_VM_CREATE_FLAG_LR_MODE - LR 或長時間執行的 VM 接受對其 exec_queues 的 exec 提交，這些提交對作業執行時間沒有上限。但對這些 exec 的提交不允許任何標誌 DRM_XE_SYNC_FLAG_SYNCOBJ、DRM_XE_SYNC_FLAG_TIMELINE_SYNCOBJ、DRM_XE_SYNC_FLAG_DMA_BUF 用作 out-syncobjs，即與 DRM_XE_SYNC_FLAG_SIGNAL 一起使用。如果裝置支援，則可以使用 DRM_XE_VM_CREATE_FLAG_FAULT_MODE 在可恢復頁面錯誤模式下建立 LR VM。如果省略該標誌，則 UMD 不能依賴於 DRM_XE_VM_CREATE_FLAG_FAULT_MODE 啟用的略微不同的按 VM 過度提交語義（參見下文），但如果裝置支援，KMD 仍然可以啟用可恢復頁面錯誤。

DRM_XE_VM_CREATE_FLAG_FAULT_MODE - 還需要 DRM_XE_VM_CREATE_FLAG_LR_MODE。它允許在訪問時按需分配記憶體，並且還允許按 VM 過度提交記憶體。 xe 驅動程式在內部使用可恢復頁面錯誤來實現此目的。

struct drm_xe_vm_destroy

DRM_IOCTL_XE_VM_DESTROY 的輸入

vm_id

對於 DRM_XE_VM_BIND_FLAG_NULL 繫結，KMD 對 pat_index 沒有限制。對於此類對映，沒有實際的記憶體被對映（PTE 中的地址無效），因此各種 PAT 記憶體屬性可能不適用。簡單地將其保留為零是一個選項（仍然是一個有效的 pat_index）。 DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR 繫結也適用，因為對於此類對映，沒有實際的記憶體被對映。

pad

MBZ

{unnamed_union}

anonymous

obj_offset

物件中的偏移量，對於 CLEAR_RANGE 必須為零，對於取消繫結將被忽略

userptr

要繫結的使用者指標

cpu_addr_mirror_offset

從 GPU addr 建立 CPU 地址映象對映的偏移量。當前支援級別必須為零（例如，僅支援 GPU 和 CPU 對映之間的 1 對 1 對映）。

range

要繫結到 addr 的物件中的位元組數，對於 UNMAP_ALL 必須為零

addr

要操作的地址，對於 UNMAP_ALL 必須為零

op

要執行的繫結操作

flags

繫結標誌

prefetch_mem_region_instance

要將 VMA 預取的記憶體區域。這是一個區域例項，而不是掩碼。只能與 DRM_XE_VM_BIND_OP_PREFETCH 操作一起使用。

pad2

MBZ

保留

保留

描述

op 可以是

  • DRM_XE_VM_BIND_OP_MAP

  • DRM_XE_VM_BIND_OP_UNMAP

  • DRM_XE_VM_BIND_OP_MAP_USERPTR

  • DRM_XE_VM_BIND_OP_UNMAP_ALL

  • DRM_XE_VM_BIND_OP_PREFETCH

並且 flags 可以是

  • DRM_XE_VM_BIND_FLAG_READONLY - 將頁表設定為只讀以確保防寫

  • DRM_XE_VM_BIND_FLAG_IMMEDIATE - 在發生錯誤的 VM 上，立即執行 MAP 操作，而不是將 MAP 推遲到頁面錯誤處理程式。這在非錯誤 VM 上是隱含的，因為沒有錯誤處理程式可以推遲。

  • DRM_XE_VM_BIND_FLAG_NULL - 設定 NULL 標誌後，頁表將使用一個特殊位進行設定，該位指示寫入被丟棄並且所有讀取都返回零。將來，NULL 標誌僅對 DRM_XE_VM_BIND_OP_MAP 操作有效，BO 控制代碼必須為零，並且 BO 偏移量必須為零。此標誌旨在實現 VK 稀疏繫結。

  • DRM_XE_VM_BIND_FLAG_CHECK_PXP - 如果物件透過 PXP 加密，如果加密金鑰不再有效，則拒絕繫結。此標誌對未標記為使用 PXP 的 BO 無效。

  • DRM_XE_VM_BIND_FLAG_CPU_ADDR_MIRROR - 設定 CPU 地址映象標誌後，不會建立任何對映，而是為 CPU 地址映象保留該範圍，該映象將在 GPU 頁面錯誤或預取時填充。僅對設定了 DRM_XE_VM_CREATE_FLAG_FAULT_MODE 的 VM 有效。CPU 地址映象標誌僅對 DRM_XE_VM_BIND_OP_MAP 操作有效，BO 控制代碼必須為零，並且 BO 偏移量必須為零。

struct drm_xe_vm_bind

DRM_IOCTL_XE_VM_BIND 的輸入

定義:

struct drm_xe_vm_bind {
    __u64 extensions;
    __u32 vm_id;
    __u32 exec_queue_id;
    __u32 pad;
    __u32 num_binds;
    union {
        struct drm_xe_vm_bind_op bind;
        __u64 vector_of_binds;
    };
    __u32 pad2;
    __u32 num_syncs;
    __u64 syncs;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

vm_id

要繫結的 VM 的 ID

exec_queue_id

exec_queue_id，必須屬於 DRM_XE_ENGINE_CLASS_VM_BIND 類，並且執行佇列必須具有相同的 vm_id。如果為零，則使用預設的 VM 繫結引擎。

pad

MBZ

num_binds

此 IOCTL 中的繫結數

{unnamed_union}

anonymous

bind

如果 num_binds == 1 則使用

vector_of_binds

如果 num_binds > 1，則指向 struct drm_xe_vm_bind_op 陣列的使用者指標

pad2

MBZ

num_syncs

要等待的同步量

syncs

指向 struct drm_xe_sync 陣列的指標

保留

保留

描述

以下是 drm_xe_vm_bind 的最小用例示例，用於非同步繫結地址 BIND_ADDRESS 處的緩衝區 data，以說明 userptr。可以使用為 drm_xe_sync 提供的示例進行同步。

data = aligned_alloc(ALIGNMENT, BO_SIZE);
struct drm_xe_vm_bind bind = {
    .vm_id = vm,
    .num_binds = 1,
    .bind.obj = 0,
    .bind.obj_offset = to_user_pointer(data),
    .bind.range = BO_SIZE,
    .bind.addr = BIND_ADDRESS,
    .bind.op = DRM_XE_VM_BIND_OP_MAP_USERPTR,
    .bind.flags = 0,
    .num_syncs = 1,
    .syncs = &sync,
    .exec_queue_id = 0,
};
ioctl(fd, DRM_IOCTL_XE_VM_BIND, &bind);
struct drm_xe_exec_queue_create

DRM_IOCTL_XE_EXEC_QUEUE_CREATE 的輸入

定義:

struct drm_xe_exec_queue_create {
#define DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY                0;
#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY               0;
#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE              1;
#define DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE               2;
    __u64 extensions;
    __u16 width;
    __u16 num_placements;
    __u32 vm_id;
#define DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT      (1 << 0);
    __u32 flags;
    __u32 exec_queue_id;
    __u64 instances;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

width

此執行佇列的提交寬度（每個執行的 BB 數量）

num_placements

此執行佇列的有效位置數

vm_id

此執行佇列要使用的 VM

flags

此執行佇列要使用的標誌

exec_queue_id

返回的執行佇列 ID

instances

指向 struct drm_xe_engine_class_instance 的二維陣列的使用者指標

長度 = 寬度 (i) * 位置數 (j) 索引 = j + i * 寬度

保留

保留

描述

此 ioctl 支援透過 DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY 擴充套件設定以下屬性，該擴充套件使用通用的 drm_xe_ext_set_property 結構

  • DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY - 設定佇列優先順序。需要 CAP_SYS_NICE 才能設定高於正常的值。

  • DRM_XE_EXEC_QUEUE_SET_PROPERTY_TIMESLICE - 設定佇列時間片持續時間，以微秒為單位。

  • DRM_XE_EXEC_QUEUE_SET_PROPERTY_PXP_TYPE - 設定此佇列將使用的 PXP 會話的型別。有效值在 enum drm_xe_pxp_session_type 中列出。DRM_XE_PXP_TYPE_NONE 是預設行為，因此無需顯式設定它。建立 DRM_XE_PXP_TYPE_HWDRM 型別的佇列時，將啟動 PXP 預設 HWDRM 會話（XE_PXP_HWDRM_DEFAULT_SESSION），如果尚未執行。使用者應透過查詢 ioctl 查詢 PXP 狀態（請參閱 DRM_XE_DEVICE_QUERY_PXP_STATUS）並等待 PXP 準備就緒，然後再嘗試建立具有此屬性的佇列。如果在 PXP 準備就緒之前建立佇列，則如果初始化仍在進行中，ioctl 將返回 -EBUSY；如果初始化失敗，則返回 -EIO。鑑於進入省電狀態會終止 PXP HWDRM 會話，因此在此型別的佇列處於活動狀態時，將阻止執行時 PM。如果發生 PXP 失效事件，所有 PXP 佇列都將被終止。

下面的示例展示瞭如何使用 drm_xe_exec_queue_create 建立 DRM_XE_ENGINE_CLASS_RENDER 類的簡單 exec_queue（無並行提交）。

struct drm_xe_engine_class_instance instance = {
    .engine_class = DRM_XE_ENGINE_CLASS_RENDER,
};
struct drm_xe_exec_queue_create exec_queue_create = {
     .extensions = 0,
     .vm_id = vm,
     .num_bb_per_exec = 1,
     .num_eng_per_bb = 1,
     .instances = to_user_pointer(&instance),
};
ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, &exec_queue_create);

Allow users to provide a hint to kernel for cases demanding low latency
profile. Please note it will have impact on power consumption. User can
indicate low latency hint with flag while creating exec queue as
mentioned below,

struct drm_xe_exec_queue_create exec_queue_create = {
     .flags = DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT,
     .extensions = 0,
     .vm_id = vm,
     .num_bb_per_exec = 1,
     .num_eng_per_bb = 1,
     .instances = to_user_pointer(&instance),
};
ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, &exec_queue_create);
struct drm_xe_exec_queue_destroy

DRM_IOCTL_XE_EXEC_QUEUE_DESTROY 的輸入

定義:

struct drm_xe_exec_queue_destroy {
    __u32 exec_queue_id;
    __u32 pad;
    __u64 reserved[2];
};

成員

exec_queue_id

執行佇列 ID

pad

MBZ

保留

保留

struct drm_xe_exec_queue_get_property

DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY 的輸入

定義:

struct drm_xe_exec_queue_get_property {
    __u64 extensions;
    __u32 exec_queue_id;
#define DRM_XE_EXEC_QUEUE_GET_PROPERTY_BAN      0;
    __u32 property;
    __u64 value;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

exec_queue_id

執行佇列 ID

屬性

要獲取的屬性

value

屬性值

保留

保留

描述

property 可以是

  • DRM_XE_EXEC_QUEUE_GET_PROPERTY_BAN

struct drm_xe_sync

同步物件

定義:

struct drm_xe_sync {
    __u64 extensions;
#define DRM_XE_SYNC_TYPE_SYNCOBJ                0x0;
#define DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ       0x1;
#define DRM_XE_SYNC_TYPE_USER_FENCE             0x2;
    __u32 type;
#define DRM_XE_SYNC_FLAG_SIGNAL (1 << 0);
    __u32 flags;
    union {
        __u32 handle;
        __u64 addr;
    };
    __u64 timeline_value;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

type

此同步物件的型別

flags

同步標誌

{unnamed_union}

anonymous

handle

物件的控制代碼

addr

使用者柵欄的地址。透過 exec IOCTL 傳入同步時，這是 VM 中的 GPU 地址。透過 VM 繫結 IOCTL 傳入同步時，這是一個使用者指標。在任何一種情況下，使用者都有責任確保在發出使用者柵欄訊號時此地址存在並且已對映。必須是四字對齊的。

timeline_value

時間線同步物件的輸入。與 DRM_XE_SYNC_FLAG_TIMELINE_SYNCOBJ 一起使用時，需要與 0 不同。

保留

保留

描述

這是硬體拓撲，它反映了 GPU 的內部物理結構。

  • DRM_XE_SYNC_TYPE_SYNCOBJ

  • DRM_XE_SYNC_TYPE_TIMELINE_SYNCOBJ

  • DRM_XE_SYNC_TYPE_USER_FENCE

並且 flags 可以是

  • DRM_XE_SYNC_FLAG_SIGNAL

drm_xe_sync 的最小用例如下所示

struct drm_xe_sync sync = {
    .flags = DRM_XE_SYNC_FLAG_SIGNAL,
    .type = DRM_XE_SYNC_TYPE_SYNCOBJ,
};
struct drm_syncobj_create syncobj_create = { 0 };
ioctl(fd, DRM_IOCTL_SYNCOBJ_CREATE, &syncobj_create);
sync.handle = syncobj_create.handle;
    ...
    use of &sync in drm_xe_exec or drm_xe_vm_bind
    ...
struct drm_syncobj_wait wait = {
    .handles = &sync.handle,
    .timeout_nsec = INT64_MAX,
    .count_handles = 1,
    .flags = 0,
    .first_signaled = 0,
    .pad = 0,
};
ioctl(fd, DRM_IOCTL_SYNCOBJ_WAIT, &wait);
struct drm_xe_exec

DRM_IOCTL_XE_EXEC 的輸入

定義:

struct drm_xe_exec {
    __u64 extensions;
    __u32 exec_queue_id;
    __u32 num_syncs;
    __u64 syncs;
    __u64 address;
    __u16 num_batch_buffer;
    __u16 pad[3];
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

exec_queue_id

批處理緩衝區的執行佇列 ID

num_syncs

陣列中 struct drm_xe_sync 的數量。

syncs

指向 struct drm_xe_sync 陣列的指標。

address

如果 num_batch_buffer == 1，則為批處理緩衝區的地址，或者批處理緩衝區地址的陣列

num_batch_buffer

此執行中的批處理緩衝區數，必須與引擎的寬度匹配

pad

MBZ

保留

保留

描述

以下示例展示瞭如何使用 drm_xe_exec 透過 exec_queue（請參閱 drm_xe_exec_queue_create 中的示例）執行 BIND_ADDRESS 處的物件（請參閱 drm_xe_vm_bind 中的示例）。可以使用為 drm_xe_sync 提供的示例進行同步。

struct drm_xe_exec exec = {
    .exec_queue_id = exec_queue,
    .syncs = &sync,
    .num_syncs = 1,
    .address = BIND_ADDRESS,
    .num_batch_buffer = 1,
};
ioctl(fd, DRM_IOCTL_XE_EXEC, &exec);
struct drm_xe_wait_user_fence

DRM_IOCTL_XE_WAIT_USER_FENCE 的輸入

定義:

struct drm_xe_wait_user_fence {
    __u64 extensions;
    __u64 addr;
#define DRM_XE_UFENCE_WAIT_OP_EQ        0x0;
#define DRM_XE_UFENCE_WAIT_OP_NEQ       0x1;
#define DRM_XE_UFENCE_WAIT_OP_GT        0x2;
#define DRM_XE_UFENCE_WAIT_OP_GTE       0x3;
#define DRM_XE_UFENCE_WAIT_OP_LT        0x4;
#define DRM_XE_UFENCE_WAIT_OP_LTE       0x5;
    __u16 op;
#define DRM_XE_UFENCE_WAIT_FLAG_ABSTIME (1 << 0);
    __u16 flags;
    __u32 pad;
    __u64 value;
    __u64 mask;
    __s64 timeout;
    __u32 exec_queue_id;
    __u32 pad2;
    __u64 reserved[2];
};

成員

extensions

struct drm_xe_device_query

addr

要等待的使用者指標地址，必須是四字對齊的

op

等待操作（比較型別）

flags

等待標誌

pad

MBZ

value

比較值

num_bytes

比較掩碼

timeout

放棄等待前的等待時間，以納秒為單位。如果不設定 DRM_XE_UFENCE_WAIT_FLAG_ABSTIME 標誌（相對超時），則它包含以納秒為單位的超時時間（柵欄將在 now() + 超時時過期）。如果設定了 DRM_XE_UFENCE_WAIT_FLAG_ABSTIME 標誌（絕對超時），則等待將在超時時結束（使用系統 MONOTONIC_CLOCK）。傳遞負超時時間會導致永無止境的等待。

在相對超時時，此值會使用剩餘的超時時間進行更新（以防訊號傳遞時重新啟動呼叫）。在絕對超時時，此值保持不變（重新啟動的呼叫仍然會在同一時間點過期）。

exec_queue_id

從 xe_exec_queue_create_ioctl 返回的 exec_queue_id

pad2

MBZ

保留

保留

描述

等待使用者柵欄，XE 將在例項列表中的每個 HW 引擎中斷時喚醒，並檢查使用者柵欄是否完成

(*addr & MASK) OP (VALUE & MASK)

使用者柵欄完成或超時時返回給使用者。

op 可以是

  • DRM_XE_UFENCE_WAIT_OP_EQ

  • DRM_XE_UFENCE_WAIT_OP_NEQ

  • DRM_XE_UFENCE_WAIT_OP_GT

  • DRM_XE_UFENCE_WAIT_OP_GTE

  • DRM_XE_UFENCE_WAIT_OP_LT

  • DRM_XE_UFENCE_WAIT_OP_LTE

並且 flags 可以是

  • DRM_XE_UFENCE_WAIT_FLAG_ABSTIME

  • DRM_XE_UFENCE_WAIT_FLAG_SOFT_OP

mask 值可以是例如

  • u8 為 0xffu

  • u16 為 0xffffu

  • u32 為 0xffffffffu

  • u64 為 0xffffffffffffffffu

enum drm_xe_observation_type

觀察流型別

常量

DRM_XE_OBSERVATION_TYPE_OA

OA 觀察流型別

DRM_XE_OBSERVATION_TYPE_EU_STALL

EU 停頓取樣觀察流型別

enum drm_xe_observation_op

觀察流操作

常量

DRM_XE_OBSERVATION_OP_STREAM_OPEN

開啟一個觀察流

DRM_XE_OBSERVATION_OP_ADD_CONFIG

新增觀察流配置

DRM_XE_OBSERVATION_OP_REMOVE_CONFIG

刪除觀察流配置

struct drm_xe_observation_param

DRM_XE_OBSERVATION 的輸入

定義:

struct drm_xe_observation_param {
    __u64 extensions;
    __u64 observation_type;
    __u64 observation_op;
    __u64 param;
};

成員

extensions

struct drm_xe_device_query

observation_type

觀察流型別，屬於列舉 drm_xe_observation_type

observation_op

觀察流操作，屬於列舉 drm_xe_observation_op

param

指向實際流引數的指標

描述

觀察層支援多型別觀察流的多路複用。特定流操作的實際引數透過 param 指標提供（使用 __copy_from_user 獲取這些引數）。

enum drm_xe_observation_ioctls

觀察流 fd ioctl

常量

DRM_XE_OBSERVATION_IOCTL_ENABLE

啟用觀察流的資料捕獲

DRM_XE_OBSERVATION_IOCTL_DISABLE

停用觀察流的資料捕獲

DRM_XE_OBSERVATION_IOCTL_CONFIG

更改觀察流配置

DRM_XE_OBSERVATION_IOCTL_STATUS

返回觀察流狀態

DRM_XE_OBSERVATION_IOCTL_INFO

返回觀察流資訊

描述

用於觀察 fd ioctl 的使用者空間和核心之間交換的資訊是特定於流型別的

enum drm_xe_oa_unit_type

OA 單元型別

常量

DRM_XE_OA_UNIT_TYPE_OAG

OAG OA 單元。OAR/OAC 被認為是 OAG 的子型別。對於 OAR/OAC，請使用 OAG。

DRM_XE_OA_UNIT_TYPE_OAM

OAM OA 單元

struct drm_xe_oa_unit

描述 OA 單元

定義:

struct drm_xe_oa_unit {
    __u64 extensions;
    __u32 oa_unit_id;
    __u32 oa_unit_type;
    __u64 capabilities;
#define DRM_XE_OA_CAPS_BASE             (1 << 0);
#define DRM_XE_OA_CAPS_SYNCS            (1 << 1);
#define DRM_XE_OA_CAPS_OA_BUFFER_SIZE   (1 << 2);
#define DRM_XE_OA_CAPS_WAIT_NUM_REPORTS (1 << 3);
    __u64 oa_timestamp_freq;
    __u64 reserved[4];
    __u64 num_engines;
    struct drm_xe_engine_class_instance eci[];
};

成員

extensions

struct drm_xe_device_query

oa_unit_id

OA 單元 ID

oa_unit_type

drm_xe_oa_unit_type 的 OA 單元型別

capabilities

OA 功能位掩碼

oa_timestamp_freq

OA 時間戳頻率

保留

MBZ

num_engines

eci 陣列中的引擎數量

struct drm_xe_query_engine_cycles

附加到此 OA 單元的引擎

struct drm_xe_query_oa_units

描述 OA 單元

定義:

struct drm_xe_query_oa_units {
    __u64 extensions;
    __u32 num_oa_units;
    __u32 pad;
    __u64 oa_units[];
};

成員

extensions

struct drm_xe_device_query

num_oa_units

在 oau[] 中返回的 OA 單元數

pad

MBZ

oa_units

為此裝置返回的 struct drm_xe_oa_unit 陣列。下面寫成 u64 陣列以避免某些編譯器中巢狀的靈活陣列出現問題

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_OA_UNITS 的 struct drm_xe_device_query 進行查詢，則回覆使用 struct drm_xe_query_oa_units 在 .data 中。

可以使用下面的程式碼塊訪問所有 OA 單元的 OA 單元屬性

struct drm_xe_query_oa_units *qoa;
struct drm_xe_oa_unit *oau;
u8 *poau;

// malloc qoa and issue DRM_XE_DEVICE_QUERY_OA_UNITS. Then:
poau = (u8 *)&qoa->oa_units[0];
for (int i = 0; i < qoa->num_oa_units; i++) {
        oau = (struct drm_xe_oa_unit *)poau;
        // Access 'struct drm_xe_oa_unit' fields here
        poau += sizeof(*oau) + oau->num_engines * sizeof(oau->eci[0]);
}
enum drm_xe_oa_format_type

PRM/Bspec 52198/60942 中指定的 OA 格式型別

常量

DRM_XE_OA_FMT_TYPE_OAG

OAG 報告格式

DRM_XE_OA_FMT_TYPE_OAR

OAR 報告格式

DRM_XE_OA_FMT_TYPE_OAM

OAM 報告格式

DRM_XE_OA_FMT_TYPE_OAC

OAC 報告格式

DRM_XE_OA_FMT_TYPE_OAM_MPEC

OAM SAMEDIA 或 OAM MPEC 報告格式

DRM_XE_OA_FMT_TYPE_PEC

PEC 報告格式

enum drm_xe_oa_property_id

OA 流屬性 ID

常量

DRM_XE_OA_PROPERTY_OA_UNIT_ID

要在其上開啟 OA 流的 OA 單元的 ID，請參閱“struct drm_xe_query_oa_units”中的 oa_unit_id。如果未提供，則預設為 0。

DRM_XE_OA_PROPERTY_SAMPLE_OA

值為 1 表示請求在附加到 OA 單元的全域性緩衝區中包含原始 OA 單元報告或流樣本。

DRM_XE_OA_PROPERTY_OA_METRIC_SET

OA 指標定義 OA 報告的內容，之前透過 DRM_XE_OBSERVATION_OP_ADD_CONFIG 新增。

DRM_XE_OA_PROPERTY_OA_FORMAT

OA 計數器報告格式

DRM_XE_OA_PROPERTY_OA_PERIOD_EXPONENT

請求定期 OA 單元取樣，取樣頻率與 2^(period_exponent + 1) 成正比

DRM_XE_OA_PROPERTY_OA_DISABLED

值為 1 將以 DISABLED 狀態開啟 OA 流（請參閱 DRM_XE_OBSERVATION_IOCTL_ENABLE）。

DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID

為特定的 exec_queue_id 開啟流。可以在此執行佇列上執行 OA 查詢。

DRM_XE_OA_PROPERTY_OA_ENGINE_INSTANCE

與 DRM_XE_OA_PROPERTY_EXEC_QUEUE_ID 一起傳遞的可選引擎例項，否則將預設為 0。

DRM_XE_OA_PROPERTY_NO_PREEMPT

允許為流執行佇列停用搶佔和時間分片。

DRM_XE_OA_PROPERTY_NUM_SYNCS

DRM_XE_OA_PROPERTY_SYNCS 中指定的同步陣列中的同步數

DRM_XE_OA_PROPERTY_SYNCS

指向 struct drm_xe_sync 陣列的指標，陣列大小透過 DRM_XE_OA_PROPERTY_NUM_SYNCS 指定。OA 配置將等待輸入柵欄發出訊號。在新的 OA 配置生效後，輸出柵欄將發出訊號。對於 DRM_XE_SYNC_TYPE_USER_FENCE，addr 是一個使用者指標，類似於 VM 繫結情況。

DRM_XE_OA_PROPERTY_OA_BUFFER_SIZE

驅動程式要分配的 OA 緩衝區的大小，以位元組為單位。支援的大小是 2 的冪，從 128 KiB 到 128 MiB。如果未指定，預設情況下將分配 16 MiB OA 緩衝區。

DRM_XE_OA_PROPERTY_WAIT_NUM_REPORTS

取消阻止輪詢或讀取之前要等待的報告數

描述

流引數指定為 drm_xe_ext_set_property 結構的鏈，其中 property 值來自列舉 drm_xe_oa_property_id 並且 drm_xe_user_extension base.name 設定為 DRM_XE_OA_EXTENSION_SET_PROPERTY。struct drm_xe_observation_param 中的 param 欄位指向第一個 drm_xe_ext_set_property 結構。

使用 DRM_XE_OBSERVATION_IOCTL_CONFIG 觀察流 fd ioctl 進行流重新配置也使用完全相同的機制，儘管只能為流重新配置指定以下屬性的子集。

struct drm_xe_oa_config

OA 指標配置

定義:

struct drm_xe_oa_config {
    __u64 extensions;
    char uuid[36];
    __u32 n_regs;
    __u64 regs_ptr;
};

成員

extensions

struct drm_xe_device_query

uuid

字串格式為“%08x-%04x-%04x-%04x-%012x”

n_regs

regs_ptr 中的 regs 數

regs_ptr

指向 OA 配置暫存器的（暫存器地址，值）對的指標。緩衝區的預期長度為：（2 * sizeof(u32) * n_regs）。

描述

可以使用 DRM_XE_OBSERVATION_OP_ADD_CONFIG 新增多個 OA 配置。使用 DRM_XE_OA_PROPERTY_OA_METRIC_SET 屬性開啟 OA 流時，可以指定特定配置。

struct drm_xe_oa_stream_status

從 DRM_XE_OBSERVATION_IOCTL_STATUS 觀察流 fd ioctl 返回的 OA 流狀態。使用者空間可以呼叫 ioctl 以響應來自觀察 fd read() 的 EIO errno 查詢流狀態。

定義:

struct drm_xe_oa_stream_status {
    __u64 extensions;
    __u64 oa_status;
#define DRM_XE_OASTATUS_MMIO_TRG_Q_FULL         (1 << 3);
#define DRM_XE_OASTATUS_COUNTER_OVERFLOW        (1 << 2);
#define DRM_XE_OASTATUS_BUFFER_OVERFLOW         (1 << 1);
#define DRM_XE_OASTATUS_REPORT_LOST             (1 << 0);
    __u64 reserved[3];
};

成員

extensions

struct drm_xe_device_query

oa_status

OA 流狀態（請參閱 Bspec 46717/61226）

保留

保留供將來使用

struct drm_xe_oa_stream_info

從 DRM_XE_OBSERVATION_IOCTL_INFO 觀察流 fd ioctl 返回的 OA 流資訊

定義:

struct drm_xe_oa_stream_info {
    __u64 extensions;
    __u64 oa_buf_size;
    __u64 reserved[3];
};

成員

extensions

struct drm_xe_device_query

oa_buf_size

OA 緩衝區大小

保留

保留供將來使用

enum drm_xe_pxp_session_type

支援的 PXP 會話型別。

常量

DRM_XE_PXP_TYPE_NONE

未使用 PXP

DRM_XE_PXP_TYPE_HWDRM

HWDRM 會話用於最終顯示的內容。

描述

我們目前僅支援 HWDRM 會話，該會話用於最終被顯示的受保護內容，但 HW 支援多種型別，因此我們可能會在將來擴充套件支援。

enum drm_xe_eu_stall_property_id

EU 停頓取樣輸入屬性 ID。

常量

DRM_XE_EU_STALL_PROP_GT_ID

將在其上捕獲 EU 停頓資料的 GT 的 gt_id。

DRM_XE_EU_STALL_PROP_SAMPLE_RATE

來自 struct drm_xe_query_eu_stall 中 sampling_rates 的 GPU 週期中的取樣率

DRM_XE_EU_STALL_PROP_WAIT_NUM_REPORTS

在取消阻止阻塞的輪詢或讀取之前，核心緩衝區中存在的最小 EU 停頓資料報告數。

描述

這些屬性在開啟時作為 drm_xe_ext_set_property 結構的鏈傳遞給驅動程式，其中 property 設定為這些屬性的列舉，value 設定為這些屬性的相應值。drm_xe_user_extension base.name 應設定為 DRM_XE_EU_STALL_EXTENSION_SET_PROPERTY。

使用從開啟獲得的 檔案描述符，使用者空間必須在使用 read() 之前使用 DRM_XE_OBSERVATION_IOCTL_ENABLE 啟用 EU 停頓流 fd。來自 read() 的 EIO errno 指示由於緩衝區已滿，HW 丟棄了資料。

struct drm_xe_query_eu_stall

有關 EU 停頓取樣的資訊。

定義:

struct drm_xe_query_eu_stall {
    __u64 extensions;
    __u64 capabilities;
#define DRM_XE_EU_STALL_CAPS_BASE               (1 << 0);
    __u64 record_size;
    __u64 per_xecore_buf_size;
    __u64 reserved[5];
    __u64 num_sampling_rates;
    __u64 sampling_rates[];
};

成員

extensions

struct drm_xe_device_query

capabilities

EU 停頓功能位掩碼

record_size

每個 EU 停頓資料記錄的大小

per_xecore_buf_size

內部每個 XeCore 緩衝區大小

保留

保留

num_sampling_rates

sampling_rates 陣列中的取樣率數

sampling_rates

取樣率的靈活陣列，按最快到最慢的順序排序。取樣率以 GPU 時鐘週期指定。

描述

如果使用 .query 等於 DRM_XE_DEVICE_QUERY_EU_STALL 的 struct drm_xe_device_query 進行查詢，則回覆在 .data 中使用 struct drm_xe_query_eu_stall。

drm/asahi uAPI

Asahi UAPI 簡介

本文件介紹了 Asahi IOCTL。

關於傳遞給 Asahi IOCTL 的資料的一些通用規則（從 Panthor 抄來的）

  • 結構體必須按 64 位/8 位元組對齊。如果物件不是自然對齊的，則必須新增填充欄位。

  • 欄位必須與其自然型別對齊對齊，使用 pad[0..N] 欄位。

  • 所有填充欄位都將由驅動程式檢查以確保它們已清零。

  • 可以新增標誌，但不能刪除/替換。

  • 可以將新欄位新增到主結構體（直接傳遞給 ioctl 的結構體）。這些欄位可以新增到結構體的末尾，也可以替換現有的填充欄位。任何新增的新欄位都必須保留新增這些欄位之前存在的行為，當傳遞零值時。

  • 如果傳遞了大小以反映使用者空間驅動程式已知的大小（請參閱 drm_asahi_cmd_header::size），則可以將新欄位新增到間接物件（主結構指向的物件）。

  • 如果核心驅動程式太舊而無法識別某些欄位，則如果它們為零將被忽略，否則將被拒絕（因此在輸出時將為零）。

  • 如果 userspace 太舊而無法識別某些欄位，則在核心驅動程式解析結構體之前，這些欄位將被清零（輸入）。

  • 每個新的標誌/欄位新增都必須附帶驅動程式版本更新，以便使用者空間驅動程式不必猜測支援哪些標誌。

  • 結構體不應包含 unions，因為這會破壞此類結構體的可擴充套件性。

  • IOCTL 不能被刪除或替換。新的 IOCTL ID 應放在 drm_asahi_ioctl_id 列舉的末尾。

enum drm_asahi_ioctl_id

IOCTL ID

常量

DRM_ASAHI_GET_PARAMS

查詢裝置屬性。

DRM_ASAHI_GET_TIME

查詢裝置時間。

DRM_ASAHI_VM_CREATE

建立 GPU VM 地址空間。

DRM_ASAHI_VM_DESTROY

銷燬 VM。

DRM_ASAHI_VM_BIND

將記憶體繫結/解除繫結到 VM。

DRM_ASAHI_GEM_CREATE

建立緩衝區物件。

DRM_ASAHI_GEM_MMAP_OFFSET

獲取要傳遞給 mmap() 以對映給定 GEM 控制代碼的偏移量。

DRM_ASAHI_GEM_BIND_OBJECT

將記憶體繫結為特殊物件

DRM_ASAHI_QUEUE_CREATE

建立排程佇列。

DRM_ASAHI_QUEUE_DESTROY

銷燬排程佇列。

DRM_ASAHI_SUBMIT

將命令提交到佇列。

描述

將新的 ioctl 放置在末尾，不要重新排序，不要替換或刪除條目。

這些 ID 不應直接使用。請改用 DRM_IOCTL_ASAHI_xxx 定義。

struct drm_asahi_params_global

全域性引數。

定義:

struct drm_asahi_params_global {
    __u64 features;
    __u32 gpu_generation;
    __u32 gpu_variant;
    __u32 gpu_revision;
    __u32 chip_id;
    __u32 num_dies;
    __u32 num_clusters_total;
    __u32 num_cores_per_cluster;
    __u32 max_frequency_khz;
    __u64 core_masks[DRM_ASAHI_MAX_CLUSTERS];
    __u64 vm_start;
    __u64 vm_end;
    __u64 vm_kernel_min_size;
    __u32 max_commands_per_submission;
    __u32 max_attachments;
    __u64 command_timestamp_frequency_hz;
};

成員

features

來自 drm_asahi_feature 的功能位

gpu_generation

GPU 代數，例如 G13G 為 13

gpu_variant

GPU 變體，例如 G13C 的“C”

gpu_revision

BCD 中的 GPU 修訂版，例如 “A0” 為 0x00 或 “C1” 為 0x21

chip_id

BCD 中的晶片 ID，例如 T8103 為 0x8103

num_dies

SoC 中的晶片數量

num_clusters_total

GPU 叢集數量（跨所有晶片）

num_cores_per_cluster

每個叢集的邏輯核心數（包括非活動/不存在的）

max_frequency_khz

最大 GPU 核心時鐘頻率

core_masks

每個叢集中存在的/啟用的核心的位掩碼

vm_start

VM 範圍起始 VMA。與 vm_end 一起，這定義了有效 GPU VA 的視窗。使用者空間應從此視窗中細分 VA。

此視窗包含使用者空間需要了解的所有虛擬地址。此範圍之外可能存在核心內部 GPU VA，但此細節不相關。

vm_end

VM 範圍結束 VMA

vm_kernel_min_size

最小核心 VMA 視窗大小。

建立 VM 時，使用者空間需要劃分一個虛擬地址部分（在 vm_start 和 vm_end 給出的範圍內）。核心將在指定的 VA 範圍內分配各種內部結構。

允許使用者空間選擇核心的 VA 範圍，而不是核心保留 VA 並要求使用者空間處理，這有助於實現 SVM。

max_commands_per_submission

每次提交支援的最大命令數。這反映了韌體限制。使用者空間必須拆分更大的命令緩衝區，這可能需要插入額外的同步。

max_attachments

每個命令的最大 drm_asahi_attachment 數

command_timestamp_frequency_hz

命令執行期間寫入的時間戳的時基頻率，透過 drm_asahi_timestamp 結構指定。由於此速率由韌體控制，因此它是一個可查詢的引數。

使用者空間必須除以此頻率才能將時間戳轉換為秒，而不是硬編碼特定韌體的速率。

描述

此結構可以透過 drm_asahi_get_params 查詢。

enum drm_asahi_feature

功能位

常量

DRM_ASAHI_FEATURE_SOFT_FAULTS

GPU 啟用了 “軟故障”。對未對映記憶體的著色器載入將返回零。對未對映記憶體的著色器儲存將被靜默丟棄。請注意，只有著色器載入/儲存受到影響。其他硬體單元不受影響，特別是包括紋理取樣。

軟故障在初始化 GPU 時設定，不能在執行時切換。因此，它作為功能位公開，而不是 VM 上的使用者空間可設定標誌。啟用軟故障後，使用者空間可以更積極地推測記憶體訪問。

描述

這僅涵蓋使用者空間無法從架構版本推斷的功能。大多數功能不需要在此處。

struct drm_asahi_get_params

傳遞給 DRM_IOCTL_ASAHI_GET_PARAMS 的引數

定義:

struct drm_asahi_get_params {
    __u32 param_group;
    __u32 pad;
    __u64 pointer;
    __u64 size;
};

成員

param_group

要獲取的引數組 (MBZ)

pad

MBZ

pointer

用於寫入引數結構的使用者指標

size

使用者緩衝區的大小。對於舊的使用者空間，這個值可能小於 sizeof(struct drm_asahi_params_global)。核心不會寫入超過此處指定的長度，從而允許擴充套件。

struct drm_asahi_vm_create

傳遞給 DRM_IOCTL_ASAHI_VM_CREATE 的引數

定義:

struct drm_asahi_vm_create {
    __u64 kernel_start;
    __u64 kernel_end;
    __u32 vm_id;
    __u32 pad;
};

成員

kernel_start

核心保留地址範圍的起始位置。請參閱 drm_asahi_params_global::vm_kernel_min_size。

kernel_start 和 kernel_end 都必須在 drm_asahi_params_global::vm_start 和 drm_asahi_params_global::vm_end 給出的有效 VA 範圍內。核心範圍的大小 (kernel_end - kernel_start) 必須至少為 drm_asahi_params_global::vm_kernel_min_size。

使用者空間不得將任何記憶體繫結到此 VM 的此保留範圍內，此範圍僅供核心使用。

kernel_end

核心保留地址範圍的結束位置。請參閱 kernel_start。

vm_id

DRM_IOCTL_XE_GEM_MMAP_OFFSET 的輸入

pad

MBZ

struct drm_asahi_vm_destroy

傳遞給 DRM_IOCTL_ASAHI_VM_DESTROY 的引數

定義:

struct drm_asahi_vm_destroy {
    __u32 vm_id;
    __u32 pad;
};

成員

vm_id

要銷燬的 VM ID

pad

MBZ

enum drm_asahi_gem_flags

GEM 建立的標誌

常量

DRM_ASAHI_GEM_WRITEBACK

BO 應該以寫回方式對映到 CPU。

以寫回而不是寫組合方式對映。這樣可以最佳化 CPU 讀取。

DRM_ASAHI_GEM_VM_PRIVATE

BO 是此 GPU VM 私有的（沒有匯出）。

struct drm_asahi_gem_create

傳遞給 DRM_IOCTL_ASAHI_GEM_CREATE 的引數

定義:

struct drm_asahi_gem_create {
    __u64 size;
    __u32 flags;
    __u32 vm_id;
    __u32 handle;
    __u32 pad;
};

成員

size

BO 的大小

flags

drm_asahi_gem_flags 標誌的組合。

vm_id

如果設定了 DRM_ASAHI_GEM_VM_PRIVATE，則要分配給 BO 的 VM ID

handle

BO 的返回 GEM 控制代碼

pad

MBZ

struct drm_asahi_gem_mmap_offset

傳遞給 DRM_IOCTL_ASAHI_GEM_MMAP_OFFSET 的引數

定義:

struct drm_asahi_gem_mmap_offset {
    __u32 handle;
    __u32 flags;
    __u64 offset;
};

成員

handle

要對映的物件的控制代碼。

flags

必須為零

offset

用於後續 mmap 呼叫的虛假偏移量

enum drm_asahi_bind_flags

GEM 繫結的標誌

常量

DRM_ASAHI_BIND_UNBIND

不是將 GEM 物件繫結到該範圍，而是簡單地解除 GPU VMA 範圍的繫結。

DRM_ASAHI_BIND_READ

使用 GPU 讀取許可權對映 BO

DRM_ASAHI_BIND_WRITE

使用 GPU 寫入許可權對映 BO

DRM_ASAHI_BIND_SINGLE_PAGE

在 VA 範圍內重複對映 BO 的單個頁面。

這對於用暫存頁或零頁填充 VA 範圍很有用。它旨在加速稀疏。

struct drm_asahi_gem_bind_op

單個 GEM 繫結操作的描述。

定義:

struct drm_asahi_gem_bind_op {
    __u32 flags;
    __u32 handle;
    __u64 offset;
    __u64 range;
    __u64 addr;
};

成員

flags

drm_asahi_bind_flags 標誌的組合。

handle

要繫結的 GEM 物件（UNBIND 除外）

offset

物件中的偏移量（UNBIND 除外）。

對於常規繫結，這是要繫結的 GEM 物件區域的開始位置。

對於單頁繫結，這是將重複繫結的單個頁面的偏移量。

必須按頁面大小對齊。

range

要繫結/解除繫結到 addr 的位元組數。

必須按頁面大小對齊。

addr

要繫結到的地址。

必須按頁面大小對齊。

struct drm_asahi_vm_bind

傳遞給 DRM_IOCTL_ASAHI_VM_BIND 的引數

定義:

struct drm_asahi_vm_bind {
    __u32 vm_id;
    __u32 num_binds;
    __u32 stride;
    __u32 pad;
    __u64 userptr;
};

成員

vm_id

要繫結的 VM 的 ID

num_binds

此 IOCTL 中的繫結數。

stride

連續繫結之間的位元組步幅。這允許擴充套件 drm_asahi_gem_bind_op。

pad

MBZ

userptr

指向型別為 drm_asahi_gem_bind_op 且大小為 stride 位元組的 num_binds 個結構的陣列的使用者指標。

enum drm_asahi_bind_object_op

特殊物件繫結操作

常量

DRM_ASAHI_BIND_OBJECT_OP_BIND

將 BO 繫結為特殊的 GPU 物件

DRM_ASAHI_BIND_OBJECT_OP_UNBIND

解除繫結特殊的 GPU 物件

enum drm_asahi_bind_object_flags

特殊物件繫結標誌

常量

DRM_ASAHI_BIND_OBJECT_USAGE_TIMESTAMPS

將 BO 對映為時間戳緩衝區。

struct drm_asahi_gem_bind_object

傳遞給 DRM_IOCTL_ASAHI_GEM_BIND_OBJECT 的引數

定義:

struct drm_asahi_gem_bind_object {
    __u32 op;
    __u32 flags;
    __u32 handle;
    __u32 vm_id;
    __u64 offset;
    __u64 range;
    __u32 object_handle;
    __u32 pad;
};

成員

op

繫結操作 (enum drm_asahi_bind_object_op)

flags

drm_asahi_bind_object_flags 標誌的組合。

handle

要繫結/解除繫結的 GEM 物件 (BIND)

vm_id

要操作的 VM 的 ID（目前 MBZ）

offset

物件中的偏移量（僅限 BIND）

range

要繫結/解除繫結的位元組數（僅限 BIND）

object_handle

物件控制代碼（BIND 的輸出，UNBIND 的輸入）

pad

MBZ

enum drm_asahi_cmd_type

命令型別

常量

DRM_ASAHI_CMD_RENDER

渲染命令，在渲染子佇列上執行。組合頂點和片段操作。

後跟一個 drm_asahi_cmd_render 負載。

DRM_ASAHI_CMD_COMPUTE

計算子佇列上的計算命令。

後跟一個 drm_asahi_cmd_compute 負載。

DRM_ASAHI_SET_VERTEX_ATTACHMENTS

軟體命令，用於設定同一提交中後續頂點著色器的附件。

後跟（可能多個）drm_asahi_attachment 負載。

DRM_ASAHI_SET_FRAGMENT_ATTACHMENTS

軟體命令，用於設定同一提交中後續片段著色器的附件。

後跟（可能多個）drm_asahi_attachment 負載。

DRM_ASAHI_SET_COMPUTE_ATTACHMENTS

軟體命令，用於設定同一提交中後續計算著色器的附件。

後跟（可能多個）drm_asahi_attachment 負載。

enum drm_asahi_priority

排程佇列優先順序。

常量

DRM_ASAHI_PRIORITY_LOW

低優先順序佇列。

DRM_ASAHI_PRIORITY_MEDIUM

中優先順序佇列。

DRM_ASAHI_PRIORITY_HIGH

高優先順序佇列。

保留供將來擴充套件使用。

DRM_ASAHI_PRIORITY_REALTIME

即時優先順序佇列。

保留供將來擴充套件使用。

描述

這些優先順序會轉發到韌體，以影響韌體排程。確切的策略最終由韌體決定，但這些列舉允許使用者空間通訊意圖。

struct drm_asahi_queue_create

傳遞給 DRM_IOCTL_ASAHI_QUEUE_CREATE 的引數

定義:

struct drm_asahi_queue_create {
    __u32 flags;
    __u32 vm_id;
    __u32 priority;
    __u32 queue_id;
    __u64 usc_exec_base;
};

成員

flags

MBZ

vm_id

此佇列繫結到的 VM 的 ID

priority

drm_asahi_priority 之一

queue_id

返回的佇列 ID

usc_exec_base

此佇列上所有 USC 二進位制檔案（著色器）的 GPU 基本地址。USC 地址是相對於此 64 位基址的 32 位地址。

這會在所有佇列命令上設定以下暫存器

USC_EXEC_BASE_TA（頂點）USC_EXEC_BASE_ISP（片段）USC_EXEC_BASE_CP（計算）

雖然硬體允許我們為每個命令獨立配置這些暫存器，但我們沒有用例。相反，我們希望使用者空間為 USC 記憶體修復一個 4GiB VA 劃分，並在此處傳遞其基本地址。

struct drm_asahi_queue_destroy

傳遞給 DRM_IOCTL_ASAHI_QUEUE_DESTROY 的引數

定義:

struct drm_asahi_queue_destroy {
    __u32 queue_id;
    __u32 pad;
};

成員

queue_id

要銷燬的佇列 ID

pad

MBZ

enum drm_asahi_sync_type

同步專案型別

常量

DRM_ASAHI_SYNC_SYNCOBJ

二進位制同步物件

DRM_ASAHI_SYNC_TIMELINE_SYNCOBJ

時間線同步物件

struct drm_asahi_sync

同步專案

定義:

struct drm_asahi_sync {
    __u32 sync_type;
    __u32 handle;
    __u64 timeline_value;
};

成員

sync_type

drm_asahi_sync_type 之一

handle

同步物件控制代碼

timeline_value

時間線同步物件的時間線值

DRM_ASAHI_BARRIER_NONE

DRM_ASAHI_BARRIER_NONE

無屏障的命令索引

描述

此特殊值可以傳遞到 drm_asahi_command::vdm_barrier 或 drm_asahi_command::cdm_barrier，以指示相應的子佇列不應等待任何先前的工作。

struct drm_asahi_cmd_header

頂層命令結構

定義:

struct drm_asahi_cmd_header {
    __u16 cmd_type;
    __u16 size;
    __u16 vdm_barrier;
    __u16 cdm_barrier;
};

成員

cmd_type

drm_asahi_cmd_type 之一

size

此命令的大小，不包括此標頭。

對於硬體命令，這允許擴充套件命令而無需額外的命令型別。為了向後相容，顯式允許傳遞比預期短的命令。截斷的欄位將為零。

對於合成附件設定命令，這隱式編碼附件的數量。這些命令採用多個固定大小的 drm_asahi_attachment 結構作為其負載，因此大小等於附件數 * sizeof(struct drm_asahi_attachment)。

vdm_barrier

要等待的 VDM（渲染）命令索引。

屏障是相對於給定提交的開始位置的索引。屏障 0 等待提交給先前提交 ioctl 中相應子佇列的命令。屏障 N 等待當前提交 ioctl 中子佇列上的 N 個先前命令。作為一種特殊情況，傳遞 DRM_ASAHI_BARRIER_NONE 可避免等待子佇列中的任何命令。

示例

0：這會等待所有先前的工作。

NONE：這不會等待此子佇列上的任何內容。

1：這會等待提交中的第一個渲染命令。這僅在同一提交中有多個渲染命令時才有效。

屏障僅對硬體命令有效。用於設定附件的合成軟體命令必須在此處傳遞 NONE。

cdm_barrier

要等待的 CDM（計算）命令索引。

請參閱 vdm_barrier，並將 VDM/渲染替換為 CDM/計算。

描述

此結構是命令緩衝區定義的核心，因此不可擴充套件。

struct drm_asahi_submit

傳遞給 DRM_IOCTL_ASAHI_SUBMIT 的引數

定義:

struct drm_asahi_submit {
    __u64 syncs;
    __u64 cmdbuf;
    __u32 flags;
    __u32 queue_id;
    __u32 in_sync_count;
    __u32 out_sync_count;
    __u32 cmdbuf_size;
    __u32 pad;
};

成員

syncs

指向 drm_asahi_sync 陣列的可選指標。前 in_sync_count 個元素是輸入同步物件，其餘 out_sync_count 個元素是輸出同步物件。使用具有顯式分割槽的單個數組簡化了處理。

cmdbuf

指向要提交的命令緩衝區的指標。

這是一個平面命令緩衝區。按照設計，它不包含 CPU 指標，這使其適用於 virtgpu 線協議，而無需任何序列化/反序列化步驟。

它由一系列命令組成。每個命令都以固定大小的 drm_asahi_cmd_header 標頭開始，後跟一個根據標頭中的型別和大小而定的可變長度負載。

“真實”硬體命令的組合計數必須非零且最多為 drm_asahi_params_global::max_commands_per_submission。

flags

命令提交的標誌 (MBZ)

queue_id

要提交到的佇列 ID

in_sync_count

在開始此作業之前要等待的同步物件的數量。

out_sync_count

此作業完成後要發出訊號的同步物件的數量。

cmdbuf_size

命令緩衝區大小（以位元組為單位）

pad

MBZ

struct drm_asahi_attachment

描述一個“附件”。

定義:

struct drm_asahi_attachment {
    __u64 pointer;
    __u64 size;
    __u32 pad;
    __u32 flags;
};

成員

pointer

附件的基本地址

size

附件的大小（以位元組為單位）

pad

MBZ

flags

MBZ

描述

附件是由著色器寫入的任何記憶體，尤其包括由圖塊結束程式寫入的渲染目標附件。這純粹是關於已訪問記憶體區域的提示。指定它是可選的，這很幸運，因為無論如何都無法透過無繫結訪問精確地指定它。但是如果可能，使用者空間最好包含這些提示，並將其轉發到韌體。

此結構是隱式大小的，因此不可擴充套件。

struct drm_asahi_zls_buffer

描述深度或模板緩衝區。

定義:

struct drm_asahi_zls_buffer {
    __u64 base;
    __u64 comp_base;
    __u32 stride;
    __u32 comp_stride;
};

成員

base

緩衝區的基本地址

comp_base

如果載入緩衝區已壓縮，則壓縮元資料部分的地址。

stride

如果啟用了分層渲染，則緩衝區每層之間的位元組數。

comp_stride

如果啟用了分層渲染，則壓縮元資料的每層之間的位元組數。

描述

這些欄位分別對應於 ZLS（Z 載入/儲存）單元中的硬體暫存器。每個欄位分別有三個用於載入、儲存和部分渲染的硬體暫存器。在實踐中，將所有值設定為相同的值是有意義的，除非在使用者空間中尚未實現的特殊情況下，因此為了簡單/高效起見，我們在此處不重複。

此結構嵌入在其他結構中，因此不可擴充套件。

struct drm_asahi_timestamp

描述時間戳寫入。

定義:

struct drm_asahi_timestamp {
    __u32 handle;
    __u32 offset;
};

成員

handle

時間戳緩衝區的控制代碼，如果跳過此時間戳，則為 0。如果為非零，則必須等於 drm_asahi_gem_bind_object::object_handle 中返回的值。

offset

寫入時間戳緩衝區的偏移量

描述

韌體可以選擇在渲染過程粒度上寫入 GPU 時間戳，但需要透過 DRM_IOCTL_ASAHI_GEM_BIND_OBJECT 進行特殊對映。因此，此結構描述了要寫入的位置，作為控制代碼偏移量對，而不是像通常那樣的 GPU 地址。

此結構嵌入在其他結構中，因此不可擴充套件。

struct drm_asahi_timestamps

描述時間戳寫入。

定義:

struct drm_asahi_timestamps {
    struct drm_asahi_timestamp start;
    struct drm_asahi_timestamp end;
};

成員

start

在操作開始時記錄的時間戳

end

在操作結束時記錄的時間戳

描述

可以加蓋時間戳的每個操作都可以在開始和結束時加蓋時間戳。因此，drm_asahi_timestamp 結構總是成對出現，捆綁到 drm_asahi_timestamps 中。

此結構嵌入在其他結構中，因此不可擴充套件。

struct drm_asahi_helper_program

描述輔助程式配置。

定義:

struct drm_asahi_helper_program {
    __u32 binary;
    __u32 cfg;
    __u64 data;
};

成員

binary

輔助程式二進位制檔案的 USC 地址。這是一個帶標記的指標，其底部位中包含配置。

cfg

輔助程式的其他配置位。

data

傳遞給輔助程式的資料。此值不會被核心、韌體或硬體以任何方式解釋。它只是使用者空間的側帶，透過提交 ioctl 設定，並透過輔助程式中的特殊暫存器讀取。

在實踐中，使用者空間將在此處傳遞一個 64 位 GPU VA，指向實際引數，這些引數可能不適合 64 位。

描述

輔助程式是各種硬體功能所需的類似計算的核心。其最重要的作用是透過劃分整個裝置共享的靜態分配，為各個子組動態分配暫存/堆疊記憶體。它由使用者空間透過 drm_asahi_helper_program 提供，並由硬體在內部根據需要進行排程。

此結構嵌入在其他結構中，因此不可擴充套件。

struct drm_asahi_bg_eot

描述後臺程式或圖塊結束程式。

定義:

struct drm_asahi_bg_eot {
    __u32 usc;
    __u32 rsrc_spec;
};

成員

usc

硬體 USC 字的 USC 地址，用於繫結資源（包括影像和統一變數）以及程式本身。請注意，與輔助程式相比，這是一個額外的間接層，避免了對資料側帶的需求。這是一個帶標記的指標，其底部位中包含其他配置。

rsrc_spec

程式的資源說明符。這是一個壓縮的硬體資料結構，描述了所需的暫存器、統一變數、繫結紋理和繫結取樣器的數量。

描述

後臺程式和圖塊結束程式由硬體在渲染開始和結束時排程。由於硬體“圖塊緩衝區”只是本地記憶體，因此這些程式對於實現 API 級別的渲染目標是必需的。類似片段的後臺程式負責載入清除顏色或現有的渲染目標內容，而類似計算的圖塊結束程式將圖塊緩衝區內容儲存到記憶體中。

此結構嵌入在其他結構中，因此不可擴充套件。

struct drm_asahi_cmd_render

提交 3D 的命令

定義:

struct drm_asahi_cmd_render {
    __u32 flags;
    __u32 isp_zls_pixels;
    __u64 vdm_ctrl_stream_base;
    struct drm_asahi_helper_program vertex_helper;
    struct drm_asahi_helper_program fragment_helper;
    __u64 isp_scissor_base;
    __u64 isp_dbias_base;
    __u64 isp_oclqry_base;
    struct drm_asahi_zls_buffer depth;
    struct drm_asahi_zls_buffer stencil;
    __u64 zls_ctrl;
    __u64 ppp_multisamplectl;
    __u64 sampler_heap;
    __u32 ppp_ctrl;
    __u16 width_px;
    __u16 height_px;
    __u16 layers;
    __u16 sampler_count;
    __u8 utile_width_px;
    __u8 utile_height_px;
    __u8 samples;
    __u8 sample_size_B;
    __u32 isp_merge_upper_x;
    __u32 isp_merge_upper_y;
    struct drm_asahi_bg_eot bg;
    struct drm_asahi_bg_eot eot;
    struct drm_asahi_bg_eot partial_bg;
    struct drm_asahi_bg_eot partial_eot;
    __u32 isp_bgobjdepth;
    __u32 isp_bgobjvals;
    struct drm_asahi_timestamps ts_vtx;
    struct drm_asahi_timestamps ts_frag;
};

成員

flags

drm_asahi_render_flags 標誌的組合。

isp_zls_pixels

ISP_ZLS_PIXELS 暫存器值。這包含深度/模板寬度/高度，可能與幀緩衝區寬度/高度不同。

vdm_ctrl_stream_base

VDM_CTRL_STREAM_BASE 暫存器值。指向 VDM 控制流開頭的 GPU 地址。

vertex_helper

用於頂點著色器的輔助程式

fragment_helper

用於片段著色器的輔助程式

isp_scissor_base

ISP_SCISSOR_BASE 暫存器值。以渲染過程索引的剪刀描述符陣列的 GPU 地址。

isp_dbias_base

ISP_DBIAS_BASE 暫存器值。以渲染過程索引的深度偏差值陣列的 GPU 地址。

isp_oclqry_base

ISP_OCLQRY_BASE 暫存器值。由渲染過程寫入的遮擋查詢結果陣列的 GPU 地址。

depth

深度緩衝區

stencil

模板緩衝區

zls_ctrl

ZLS_CTRL 暫存器值

ppp_multisamplectl

PPP_MULTISAMPLECTL 暫存器值

sampler_heap

取樣器堆的基本地址。此堆用於頂點著色器和片段著色器。這些暫存器是按階段劃分的，但沒有已知的使用單獨堆的用例。

ppp_ctrl

PPP_CTRL 暫存器值

width_px

幀緩衝區寬度（以畫素為單位）

height_px

幀緩衝區高度（以畫素為單位）

layers

幀緩衝區中的層數

sampler_count

取樣器堆中取樣器的數量。

utile_width_px

邏輯圖塊緩衝區圖塊的寬度（以畫素為單位）

utile_height_px

邏輯圖塊緩衝區圖塊的高度（以畫素為單位）

samples

幀緩衝區中的取樣數。必須為 1、2 或 4。

sample_size_B

每個取樣所需的圖塊緩衝區中的位元組數。

isp_merge_upper_x

用於硬體三角形合併的 32 位浮點數。計算為：tan(60 度) * 寬度。

使這些值成為 UAPI 可避免在熱路徑中要求核心進行浮點計算。

isp_merge_upper_y

32 位浮點數。計算為：tan(60 度) * 高度。請參閱 isp_merge_upper_x。

bg

在開始時為每個圖塊執行的後臺程式

eot

在結束時為每個圖塊執行的圖塊結束程式

partial_bg

在部分渲染期間恢復渲染過程時，在每個圖塊的開始處執行的後臺程式。

partial_eot

在部分渲染期間暫停渲染過程時，在每個圖塊的結尾處執行的圖塊結束程式。

isp_bgobjdepth

ISP_BGOBJDEPTH 暫存器值。這是深度緩衝區清除值，以深度緩衝區的格式編碼：32 位浮點數或 16 位 unorm（高位為零）。

isp_bgobjvals

ISP_BGOBJVALS 暫存器值。底部 8 位包含模板緩衝區清除值。

ts_vtx

渲染的頂點部分的時間戳

ts_frag

渲染的片段部分的時間戳

描述

此命令提交單個渲染過程。硬體控制流可能包括許多繪製和子過程，但在命令中，幀緩衝區尺寸和附件是固定的。

硬體要求韌體在每個渲染 3D 的命令之前設定大量控制暫存器，以在渲染過程粒度上設定狀態。韌體將此狀態捆綁到資料結構中。不幸的是，我們無法將任何這些直接暴露給使用者空間，因為核心韌體 ABI 不穩定。雖然我們可以保證韌體與核心同步更新，但我們無法在升級韌體和核心時中斷舊的使用者空間。因此，我們需要很好地抽象資料結構，以避免用未來的韌體束縛自己。

因此，drm_asahi_cmd_render 的大部分由硬體控制暫存器的值組成，這些值透過韌體介面進行編組。

幀緩衝區/圖塊緩衝區尺寸也在此處指定。除了傳遞給韌體/硬體之外，核心還需要這些尺寸來計算各種基本圖塊相關的資料結構。不幸的是，我們的提交比在具有更健全的硬體-軟體介面的供應商上更重。結果是所有這些資訊都可以透過所有當前的 API 輕鬆地提供給使用者空間。

它看起來很奇怪 - 但它不是過於繁重，並且它確保我們可以與舊的使用者空間保持相容。

struct drm_asahi_cmd_compute

提交計算的命令

定義:

struct drm_asahi_cmd_compute {
    __u32 flags;
    __u32 sampler_count;
    __u64 cdm_ctrl_stream_base;
    __u64 cdm_ctrl_stream_end;
    __u64 sampler_heap;
    struct drm_asahi_helper_program helper;
    struct drm_asahi_timestamps ts;
};

成員

flags

MBZ

sampler_count

取樣器堆中取樣器的數量。

cdm_ctrl_stream_base

CDM_CTRL_STREAM_BASE 暫存器值。指向 CDM 控制流開頭的 GPU 地址。

cdm_ctrl_stream_end

指向硬體控制流末尾的 GPU 基本地址。請注意，這僅考慮了控制流的第一個連續段，因為流可能會跳轉到其他位置。

sampler_heap

取樣器堆的基本地址。

helper

用於此計算命令的輔助程式

ts

計算命令的時間戳

描述

此命令提交由計算排程組成的控制流。單個計算命令中可以包含的計算排程本質上沒有限制，儘管時間戳是在命令粒度上進行的。

struct drm_asahi_get_time

傳遞給 DRM_IOCTL_ASAHI_GET_TIME 的引數

定義:

struct drm_asahi_get_time {
    __u64 flags;
    __u64 gpu_timestamp;
};

成員

flags

MBZ。

gpu_timestamp

返回時，GPU 時間戳（以納秒為單位）。

DRM_IOCTL_ASAHI

DRM_IOCTL_ASAHI (__access, __id, __type)

生成 Asahi IOCTL 編號

引數

__access

訪問型別。必須是 R、W 或 RW。

__id

DRM_ASAHI_xxx id 之一。

__type

傳遞給 IOCTL 的型別的字尾。

描述

不要直接使用此宏，請改用 DRM_IOCTL_ASAHI_xxx 值。

Return

要從 userspace 傳遞給 ioctl() 的 IOCTL 數字。