]>
Commit | Line | Data |
---|---|---|
ca00c2b9 JN |
1 | Introduction |
2 | ============ | |
3 | ||
4 | The Linux DRM layer contains code intended to support the needs of | |
5 | complex graphics devices, usually containing programmable pipelines well | |
6 | suited to 3D graphics acceleration. Graphics drivers in the kernel may | |
7 | make use of DRM functions to make tasks like memory management, | |
8 | interrupt handling and DMA easier, and provide a uniform interface to | |
9 | applications. | |
10 | ||
11 | A note on versions: this guide covers features found in the DRM tree, | |
12 | including the TTM memory manager, output configuration and mode setting, | |
13 | and the new vblank internals, in addition to all the regular features | |
14 | found in current kernels. | |
15 | ||
16 | [Insert diagram of typical DRM stack here] | |
17 | ||
18 | Style Guidelines | |
19 | ---------------- | |
20 | ||
21 | For consistency this documentation uses American English. Abbreviations | |
22 | are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so | |
23 | on. To aid in reading, documentations make full use of the markup | |
24 | characters kerneldoc provides: @parameter for function parameters, | |
25 | @member for structure members, &structure to reference structures and | |
26 | function() for functions. These all get automatically hyperlinked if | |
27 | kerneldoc for the referenced objects exists. When referencing entries in | |
28 | function vtables please use ->vfunc(). Note that kerneldoc does not | |
29 | support referencing struct members directly, so please add a reference | |
30 | to the vtable struct somewhere in the same paragraph or at least | |
31 | section. | |
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. |