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>`. |