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