簡介

Linux DRM 層包含旨在支援複雜圖形裝置需求的程式碼，這些裝置通常包含非常適合 3D 圖形加速的可程式設計流水線。 核心中的圖形驅動程式可以使用 DRM 函式來簡化記憶體管理、中斷處理和 DMA 等任務，併為應用程式提供統一的介面。

關於版本說明：本指南涵蓋 DRM 樹中發現的功能，包括 TTM 記憶體管理器、輸出配置和模式設定，以及新的 vblank 內部結構，以及當前核心中發現的所有常規功能。

[在此處插入典型 DRM 堆疊的圖表]

風格指南

為了保持一致性，本文件使用美式英語。 縮寫以全部大寫字母書寫，例如：DRM、KMS、IOCTL、CRTC 等。 為了方便閱讀，文件充分利用 kerneldoc 提供的標記字元：@parameter 用於函式引數，@member 用於結構成員（在同一結構內），&struct 結構用於引用結構，function() 用於函式。 如果被引用物件的 kerneldoc 存在，這些都會自動超連結。 引用函式 vtable 中的條目（以及一般的結構成員）時，請使用 &vtable_name.vfunc。 遺憾的是，這尚未產生指向成員的直接連結，僅指向結構。

除非在特殊情況下（將鎖定變體與未鎖定變體分開），否則函式的鎖定要求不會記錄在 kerneldoc 中。 相反，應使用例如 WARN_ON(!mutex_is_locked(...)); 在執行時檢查鎖定。 由於忽略文件比忽略執行時噪音更容易，因此這提供了更大的價值。 最重要的是，執行時檢查確實需要在鎖定規則更改時進行更新，從而增加了它們正確的機會。 在文件中，鎖定規則應在相關結構中解釋：要麼在鎖的註釋中解釋它保護的內容，要麼資料欄位需要一個關於哪個鎖保護它們的註釋，或者兩者都需要。

具有非 void 返回值的函式應具有一個名為“Returns”的部分，解釋不同情況下預期的返回值及其含義。 目前，對於該部分名稱是否應全部大寫，以及是否應以冒號結尾，尚未達成共識。 請使用檔案本地樣式。 其他常見的章節名稱是“Notes”，其中包含危險或棘手的角落情況的資訊，以及“FIXME”，其中可以清理介面。

另請閱讀核心文件的總體指南。

kAPI 的文件要求

所有匯出到其他模組的核心 API 都必須記錄在案，包括其資料結構，以及至少一個簡短的介紹性部分，解釋總體概念。 文件應儘可能多地以 kerneldoc 註釋的形式放入程式碼本身中。

不要盲目地記錄所有內容，而只記錄與驅動程式作者相關的內容：drm.ko 的內部函式以及絕對的靜態函式不應具有正式的 kerneldoc 註釋。 如果您認為有必要添加註釋，請使用普通的 C 註釋。 您可以在註釋中使用 kerneldoc 語法，但它不應以 /** kerneldoc 標記開頭。 對於資料結構，請按照文件指南，使用 /* private: */ 註釋來註釋任何完全私有的內容。

入門

歡迎有興趣幫助 DRM 子系統的開發人員。 通常，人們會選擇提交針對 checkpatch 或 sparse 報告的各種問題的補丁。 我們歡迎此類貢獻。

任何想要更上一層樓的人都可以在TODO 列表上找到一份管理任務清單。

貢獻流程

大多數情況下，DRM 子系統的運作方式與任何其他核心子系統類似，有關其運作方式，請參閱主要流程指南和文件。 在這裡，我們只記錄 GPU 子系統的一些特殊性。

功能合併截止日期

所有功能工作都必須在當前釋出週期的 -rc6 版本之前進入 linux-next 樹，否則必須推遲，並且無法進入下一個合併視窗。 所有補丁都必須在 -rc7 之前最新到達 drm-next 樹，但如果您的分支不在 linux-next 中，則必須已經在 -rc6 之前完成。

在此之後，只允許修復錯誤（就像上游合併視窗以 -rc1 版本關閉之後一樣）。 不允許啟用新平臺或新增新驅動程式。

這意味著大約有一個月的功能工作無法合併的停機期。 建議的處理方法是擁有一個始終開啟的 -next 樹，但要確保在停機期間不要將其饋送到 linux-next 中。 例如，drm-misc 就是這樣運作的。

行為準則

作為 freedesktop.org 專案，dri-devel 和 DRM 社群都遵守貢獻者盟約，可在以下網址找到：https://www.freedesktop.org/wiki/CodeOfConduct

與郵件列表、IRC 或錯誤跟蹤器上的社群成員互動時，請以尊重和文明的方式行事。 社群代表整個專案，專案不容忍辱罵或欺凌行為。

用作示例的簡單 DRM 驅動程式

DRM 子系統包含許多輔助函式，可簡化簡單圖形裝置的驅動程式編寫。 例如，drivers/gpu/drm/tiny/ 目錄包含一組驅動程式，這些驅動程式足夠簡單，可以在單個原始檔中實現。

這些驅動程式使用struct drm_simple_display_pipe_funcs，它隱藏了 DRM 子系統的任何複雜性，只需要驅動程式實現一些操作裝置所需的函式。 這可以用於只需要一個顯示管道，其中一個全屏掃描輸出緩衝區饋送一個輸出的裝置。

微型 DRM 驅動程式是瞭解 DRM 驅動程式應如何設計的良好示例。 由於只有數百行程式碼，因此非常容易閱讀。

外部參考

第一次深入研究 Linux 核心子系統可能是一種令人不知所措的體驗，人們需要熟悉所有概念並瞭解子系統的內部結構以及其他細節。

為了縮短學習曲線，本節包含一個簡報和文件列表，可用於瞭解 DRM/KMS 和一般圖形。

人們可能出於不同的原因而想要進入 DRM：移植現有的 fbdev 驅動程式、為新硬體編寫 DRM 驅動程式、修復在圖形使用者空間堆疊上工作時可能面臨的錯誤等。為此，學習材料涵蓋了 Linux 圖形堆疊的許多方面。 從核心和使用者空間堆疊的概述到非常具體的主題。

該列表按時間倒序排序，以將最新的材料保持在頂部。 但所有這些都包含有用的資訊，並且遍歷舊材料以瞭解 DRM 子系統更改的理由和背景可能很有價值。

會議演講

幻燈片和文章