1 ============
2 Introduction
3 ============
4
5 The Linux DRM layer contains code intended to
6 complex graphics devices, usually containing p
7 suited to 3D graphics acceleration. Graphics d
8 make use of DRM functions to make tasks like m
9 interrupt handling and DMA easier, and provide
10 applications.
11
12 A note on versions: this guide covers features
13 including the TTM memory manager, output confi
14 and the new vblank internals, in addition to a
15 found in current kernels.
16
17 [Insert diagram of typical DRM stack here]
18
19 Style Guidelines
20 ================
21
22 For consistency this documentation uses Americ
23 are written as all-uppercase, for example: DRM
24 on. To aid in reading, documentations make ful
25 characters kerneldoc provides: @parameter for
26 @member for structure members (within the same
27 reference structures and function() for functi
28 hyperlinked if kerneldoc for the referenced ob
29 entries in function vtables (and structure mem
30 &vtable_name.vfunc. Unfortunately this does no
31 member, only the structure.
32
33 Except in special situations (to separate lock
34 locking requirements for functions aren't docu
35 Instead locking should be check at runtime usi
36 ``WARN_ON(!mutex_is_locked(...));``. Since it'
37 documentation than runtime noise this provides
38 that runtime checks do need to be updated when
39 increasing the chances that they're correct. W
40 the locking rules should be explained in the r
41 in the comment for the lock explaining what it
42 need a note about which lock protects them, or
43
44 Functions which have a non-\ ``void`` return v
45 called "Returns" explaining the expected retur
46 cases and their meanings. Currently there's no
47 section name should be all upper-case or not,
48 in a colon or not. Go with the file-local styl
49 names are "Notes" with information for dangero
50 and "FIXME" where the interface could be clean
51
52 Also read the :ref:`guidelines for the kernel
53
54 Documentation Requirements for kAPI
55 -----------------------------------
56
57 All kernel APIs exported to other modules must
58 datastructures and at least a short introducto
59 concepts. Documentation should be put into the
60 as much as reasonable.
61
62 Do not blindly document everything, but docume
63 authors: Internal functions of drm.ko and defi
64 have formal kerneldoc comments. Use normal C c
65 is warranted. You may use kerneldoc syntax in
66 start with a /** kerneldoc marker. Similar for
67 anything entirely private with ``/* private: *
68 documentation guide.
69
70 Getting Started
71 ===============
72
73 Developers interested in helping out with the
74 Often people will resort to sending in patches
75 checkpatch or sparse. We welcome such contribu
76
77 Anyone looking to kick it up a notch can find
78 the :ref:`TODO list <todo>`.
79
80 Contribution Process
81 ====================
82
83 Mostly the DRM subsystem works like any other
84 main process guidelines and documentation <pro
85 Here we just document some of the specialities
86
87 Feature Merge Deadlines
88 -----------------------
89
90 All feature work must be in the linux-next tre
91 current release cycle, otherwise they must be
92 merge window. All patches must have landed in
93 but if your branch is not in linux-next then t
94 already.
95
96 After that point only bugfixes (like after the
97 with the -rc1 release) are allowed. No new pla
98 allowed.
99
100 This means that there's a blackout-period of a
101 can't be merged. The recommended way to deal w
102 that's always open, but making sure to not fee
103 blackout period. As an example, drm-misc works
104
105 Code of Conduct
106 ---------------
107
108 As a freedesktop.org project, dri-devel, and t
109 Contributor Covenant, found at: https://www.fr
110
111 Please conduct yourself in a respectful and ci
112 interacting with community members on mailing
113 trackers. The community represents the project
114 or bullying behaviour is not tolerated by the
115
116 Simple DRM drivers to use as examples
117 =====================================
118
119 The DRM subsystem contains a lot of helper fun
120 simple graphic devices. For example, the `driv
121 set of drivers that are simple enough to be im
122
123 These drivers make use of the `struct drm_simp
124 any complexity of the DRM subsystem and just r
125 functions needed to operate the device. This c
126 need a display pipeline with one full-screen s
127
128 The tiny DRM drivers are good examples to unde
129 like. Since are just a few hundreds lines of c
130
131 External References
132 ===================
133
134 Delving into a Linux kernel subsystem for the
135 experience, one needs to get familiar with all
136 subsystem's internals, among other details.
137
138 To shallow the learning curve, this section co
139 and documents that can be used to learn about
140
141 There are different reasons why someone might
142 existing fbdev driver, write a DRM driver for
143 could face when working on the graphics user-s
144 the learning material covers many aspects of t
145 overview of the kernel and user-space stacks t
146
147 The list is sorted in reverse chronological or
148 material at the top. But all of them contain u
149 valuable to go through older material to under
150 in which the changes to the DRM subsystem were
151
152 Conference talks
153 ----------------
154
155 * `An Overview of the Linux and Userspace Grap
156 * `Getting pixels on screen on Linux: introduc
157 * `Everything Great about Upstream Graphics <h
158 * `An introduction to the Linux DRM subsystem
159 * `Embrace the Atomic (Display) Age <https://w
160 * `Anatomy of an Atomic KMS Driver <https://ww
161 * `Atomic Modesetting for Drivers <https://www
162 * `Anatomy of an Embedded KMS Driver <https://
163
164 Slides and articles
165 -------------------
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
170 * `DRM KMS overview <https://wiki.st.com/stm32
171 * `Linux graphic stack <https://studiopixl.com
172 * `Atomic mode setting design overview, part 1
173 * `Atomic mode setting design overview, part 2
174 * `The DRM/KMS subsystem from a newbie’s poi
175 * `A brief introduction to the Linux graphics
176 * `The Linux Graphics Stack <https://blog.mech
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.