1 ============ 1 ============
2 Introduction 2 Introduction
3 ============ 3 ============
4 4
5 The Linux DRM layer contains code intended to 5 The Linux DRM layer contains code intended to support the needs of
6 complex graphics devices, usually containing p 6 complex graphics devices, usually containing programmable pipelines well
7 suited to 3D graphics acceleration. Graphics d 7 suited to 3D graphics acceleration. Graphics drivers in the kernel may
8 make use of DRM functions to make tasks like m 8 make use of DRM functions to make tasks like memory management,
9 interrupt handling and DMA easier, and provide 9 interrupt handling and DMA easier, and provide a uniform interface to
10 applications. 10 applications.
11 11
12 A note on versions: this guide covers features 12 A note on versions: this guide covers features found in the DRM tree,
13 including the TTM memory manager, output confi 13 including the TTM memory manager, output configuration and mode setting,
14 and the new vblank internals, in addition to a 14 and the new vblank internals, in addition to all the regular features
15 found in current kernels. 15 found in current kernels.
16 16
17 [Insert diagram of typical DRM stack here] 17 [Insert diagram of typical DRM stack here]
18 18
19 Style Guidelines 19 Style Guidelines
20 ================ 20 ================
21 21
22 For consistency this documentation uses Americ 22 For consistency this documentation uses American English. Abbreviations
23 are written as all-uppercase, for example: DRM 23 are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
24 on. To aid in reading, documentations make ful 24 on. To aid in reading, documentations make full use of the markup
25 characters kerneldoc provides: @parameter for 25 characters kerneldoc provides: @parameter for function parameters,
26 @member for structure members (within the same 26 @member for structure members (within the same structure), &struct structure to
27 reference structures and function() for functi 27 reference structures and function() for functions. These all get automatically
28 hyperlinked if kerneldoc for the referenced ob 28 hyperlinked if kerneldoc for the referenced objects exists. When referencing
29 entries in function vtables (and structure mem 29 entries in function vtables (and structure members in general) please use
30 &vtable_name.vfunc. Unfortunately this does no 30 &vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the
31 member, only the structure. 31 member, only the structure.
32 32
33 Except in special situations (to separate lock 33 Except in special situations (to separate locked from unlocked variants)
34 locking requirements for functions aren't docu 34 locking requirements for functions aren't documented in the kerneldoc.
35 Instead locking should be check at runtime usi 35 Instead locking should be check at runtime using e.g.
36 ``WARN_ON(!mutex_is_locked(...));``. Since it' 36 ``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
37 documentation than runtime noise this provides 37 documentation than runtime noise this provides more value. And on top of
38 that runtime checks do need to be updated when 38 that runtime checks do need to be updated when the locking rules change,
39 increasing the chances that they're correct. W 39 increasing the chances that they're correct. Within the documentation
40 the locking rules should be explained in the r 40 the locking rules should be explained in the relevant structures: Either
41 in the comment for the lock explaining what it 41 in the comment for the lock explaining what it protects, or data fields
42 need a note about which lock protects them, or 42 need a note about which lock protects them, or both.
43 43
44 Functions which have a non-\ ``void`` return v 44 Functions which have a non-\ ``void`` return value should have a section
45 called "Returns" explaining the expected retur 45 called "Returns" explaining the expected return values in different
46 cases and their meanings. Currently there's no 46 cases and their meanings. Currently there's no consensus whether that
47 section name should be all upper-case or not, 47 section name should be all upper-case or not, and whether it should end
48 in a colon or not. Go with the file-local styl 48 in a colon or not. Go with the file-local style. Other common section
49 names are "Notes" with information for dangero 49 names are "Notes" with information for dangerous or tricky corner cases,
50 and "FIXME" where the interface could be clean 50 and "FIXME" where the interface could be cleaned up.
51 51
52 Also read the :ref:`guidelines for the kernel 52 Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
53 53
54 Documentation Requirements for kAPI 54 Documentation Requirements for kAPI
55 ----------------------------------- 55 -----------------------------------
56 56
57 All kernel APIs exported to other modules must 57 All kernel APIs exported to other modules must be documented, including their
58 datastructures and at least a short introducto 58 datastructures and at least a short introductory section explaining the overall
59 concepts. Documentation should be put into the 59 concepts. Documentation should be put into the code itself as kerneldoc comments
60 as much as reasonable. 60 as much as reasonable.
61 61
62 Do not blindly document everything, but docume 62 Do not blindly document everything, but document only what's relevant for driver
63 authors: Internal functions of drm.ko and defi 63 authors: Internal functions of drm.ko and definitely static functions should not
64 have formal kerneldoc comments. Use normal C c 64 have formal kerneldoc comments. Use normal C comments if you feel like a comment
65 is warranted. You may use kerneldoc syntax in 65 is warranted. You may use kerneldoc syntax in the comment, but it shall not
66 start with a /** kerneldoc marker. Similar for 66 start with a /** kerneldoc marker. Similar for data structures, annotate
67 anything entirely private with ``/* private: * 67 anything entirely private with ``/* private: */`` comments as per the
68 documentation guide. 68 documentation guide.
69 69
70 Getting Started 70 Getting Started
71 =============== 71 ===============
72 72
73 Developers interested in helping out with the 73 Developers interested in helping out with the DRM subsystem are very welcome.
74 Often people will resort to sending in patches 74 Often people will resort to sending in patches for various issues reported by
75 checkpatch or sparse. We welcome such contribu 75 checkpatch or sparse. We welcome such contributions.
76 76
77 Anyone looking to kick it up a notch can find 77 Anyone looking to kick it up a notch can find a list of janitorial tasks on
78 the :ref:`TODO list <todo>`. 78 the :ref:`TODO list <todo>`.
79 79
80 Contribution Process 80 Contribution Process
81 ==================== 81 ====================
82 82
83 Mostly the DRM subsystem works like any other 83 Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the
84 main process guidelines and documentation <pro 84 main process guidelines and documentation <process_index>` for how things work.
85 Here we just document some of the specialities 85 Here we just document some of the specialities of the GPU subsystem.
86 86
87 Feature Merge Deadlines 87 Feature Merge Deadlines
88 ----------------------- 88 -----------------------
89 89
90 All feature work must be in the linux-next tre 90 All feature work must be in the linux-next tree by the -rc6 release of the
91 current release cycle, otherwise they must be 91 current release cycle, otherwise they must be postponed and can't reach the next
92 merge window. All patches must have landed in 92 merge window. All patches must have landed in the drm-next tree by latest -rc7,
93 but if your branch is not in linux-next then t 93 but if your branch is not in linux-next then this must have happened by -rc6
94 already. 94 already.
95 95
96 After that point only bugfixes (like after the 96 After that point only bugfixes (like after the upstream merge window has closed
97 with the -rc1 release) are allowed. No new pla 97 with the -rc1 release) are allowed. No new platform enabling or new drivers are
98 allowed. 98 allowed.
99 99
100 This means that there's a blackout-period of a 100 This means that there's a blackout-period of about one month where feature work
101 can't be merged. The recommended way to deal w 101 can't be merged. The recommended way to deal with that is having a -next tree
102 that's always open, but making sure to not fee 102 that's always open, but making sure to not feed it into linux-next during the
103 blackout period. As an example, drm-misc works 103 blackout period. As an example, drm-misc works like that.
104 104
105 Code of Conduct 105 Code of Conduct
106 --------------- 106 ---------------
107 107
108 As a freedesktop.org project, dri-devel, and t 108 As a freedesktop.org project, dri-devel, and the DRM community, follows the
109 Contributor Covenant, found at: https://www.fr 109 Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
110 110
111 Please conduct yourself in a respectful and ci 111 Please conduct yourself in a respectful and civilised manner when
112 interacting with community members on mailing 112 interacting with community members on mailing lists, IRC, or bug
113 trackers. The community represents the project 113 trackers. The community represents the project as a whole, and abusive
114 or bullying behaviour is not tolerated by the 114 or bullying behaviour is not tolerated by the project.
115 115
116 Simple DRM drivers to use as examples 116 Simple DRM drivers to use as examples
117 ===================================== 117 =====================================
118 118
119 The DRM subsystem contains a lot of helper fun 119 The DRM subsystem contains a lot of helper functions to ease writing drivers for
120 simple graphic devices. For example, the `driv 120 simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a
121 set of drivers that are simple enough to be im 121 set of drivers that are simple enough to be implemented in a single source file.
122 122
123 These drivers make use of the `struct drm_simp 123 These drivers make use of the `struct drm_simple_display_pipe_funcs`, that hides
124 any complexity of the DRM subsystem and just r 124 any complexity of the DRM subsystem and just requires drivers to implement a few
125 functions needed to operate the device. This c 125 functions needed to operate the device. This could be used for devices that just
126 need a display pipeline with one full-screen s 126 need a display pipeline with one full-screen scanout buffer feeding one output.
127 127
128 The tiny DRM drivers are good examples to unde 128 The tiny DRM drivers are good examples to understand how DRM drivers should look
129 like. Since are just a few hundreds lines of c 129 like. Since are just a few hundreds lines of code, they are quite easy to read.
130 130
131 External References 131 External References
132 =================== 132 ===================
133 133
134 Delving into a Linux kernel subsystem for the 134 Delving into a Linux kernel subsystem for the first time can be an overwhelming
135 experience, one needs to get familiar with all 135 experience, one needs to get familiar with all the concepts and learn about the
136 subsystem's internals, among other details. 136 subsystem's internals, among other details.
137 137
138 To shallow the learning curve, this section co 138 To shallow the learning curve, this section contains a list of presentations
139 and documents that can be used to learn about 139 and documents that can be used to learn about DRM/KMS and graphics in general.
140 140
141 There are different reasons why someone might 141 There are different reasons why someone might want to get into DRM: porting an
142 existing fbdev driver, write a DRM driver for 142 existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that
143 could face when working on the graphics user-s 143 could face when working on the graphics user-space stack, etc. For this reason,
144 the learning material covers many aspects of t 144 the learning material covers many aspects of the Linux graphics stack. From an
145 overview of the kernel and user-space stacks t 145 overview of the kernel and user-space stacks to very specific topics.
146 146
147 The list is sorted in reverse chronological or 147 The list is sorted in reverse chronological order, to keep the most up-to-date
148 material at the top. But all of them contain u 148 material at the top. But all of them contain useful information, and it can be
149 valuable to go through older material to under 149 valuable to go through older material to understand the rationale and context
150 in which the changes to the DRM subsystem were 150 in which the changes to the DRM subsystem were made.
151 151
152 Conference talks 152 Conference talks
153 ---------------- 153 ----------------
154 154
155 * `An Overview of the Linux and Userspace Grap 155 * `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020)
156 * `Getting pixels on screen on Linux: introduc 156 * `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020)
157 * `Everything Great about Upstream Graphics <h 157 * `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Daniel Vetter (2019)
158 * `An introduction to the Linux DRM subsystem 158 * `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017)
159 * `Embrace the Atomic (Display) Age <https://w 159 * `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Daniel Vetter (2016)
160 * `Anatomy of an Atomic KMS Driver <https://ww 160 * `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015)
161 * `Atomic Modesetting for Drivers <https://www 161 * `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Daniel Vetter (2015)
162 * `Anatomy of an Embedded KMS Driver <https:// 162 * `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013)
163 163
164 Slides and articles 164 Slides and articles
165 ------------------- 165 -------------------
166 166
167 * `The Linux graphics stack in a nutshell, par <<
168 * `The Linux graphics stack in a nutshell, par <<
169 * `Understanding the Linux Graphics Stack <htt 167 * `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022)
170 * `DRM KMS overview <https://wiki.st.com/stm32 168 * `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021)
171 * `Linux graphic stack <https://studiopixl.com 169 * `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017)
172 * `Atomic mode setting design overview, part 1 170 * `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Daniel Vetter (2015)
173 * `Atomic mode setting design overview, part 2 171 * `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Daniel Vetter (2015)
174 * `The DRM/KMS subsystem from a newbie’s poi 172 * `The DRM/KMS subsystem from a newbie’s point of view <https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf>`_ - Boris Brezillon (2014)
175 * `A brief introduction to the Linux graphics 173 * `A brief introduction to the Linux graphics stack <https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/>`_ - Iago Toral (2014)
176 * `The Linux Graphics Stack <https://blog.mech 174 * `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.