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 TR |
53 | |
54 | Getting Started | |
55 | =============== | |
56 | ||
57 | Developers interested in helping out with the DRM subsystem are very welcome. | |
58 | Often people will resort to sending in patches for various issues reported by | |
59 | checkpatch or sparse. We welcome such contributions. | |
60 | ||
61 | Anyone looking to kick it up a notch can find a list of janitorial tasks on | |
62 | the :ref:`TODO list <todo>`. | |
eadf71cd DV |
63 | |
64 | Contribution Process | |
65 | ==================== | |
66 | ||
67 | Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the | |
68 | main process guidelines and documentation <process_index>` for how things work. | |
69 | Here we just document some of the specialities of the GPU subsystem. | |
70 | ||
71 | Feature Merge Deadlines | |
72 | ----------------------- | |
73 | ||
74 | All feature work must be in the linux-next tree by the -rc6 release of the | |
75 | current release cycle, otherwise they must be postponed and can't reach the next | |
76 | merge window. All patches must have landed in the drm-next tree by latest -rc7, | |
77 | but if your branch is not in linux-next then this must have happened by -rc6 | |
78 | already. | |
79 | ||
80 | After that point only bugfixes (like after the upstream merge window has closed | |
81 | with the -rc1 release) are allowed. No new platform enabling or new drivers are | |
82 | allowed. | |
83 | ||
84 | This means that there's a blackout-period of about one month where feature work | |
85 | can't be merged. The recommended way to deal with that is having a -next tree | |
86 | that's always open, but making sure to not feed it into linux-next during the | |
87 | blackout period. As an example, drm-misc works like that. | |
8676df50 DV |
88 | |
89 | Code of Conduct | |
90 | --------------- | |
91 | ||
92 | As a freedesktop.org project, dri-devel, and the DRM community, follows the | |
93 | Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct | |
94 | ||
95 | Please conduct yourself in a respectful and civilised manner when | |
96 | interacting with community members on mailing lists, IRC, or bug | |
97 | trackers. The community represents the project as a whole, and abusive | |
98 | or bullying behaviour is not tolerated by the project. |