1============
2Introduction
3============
4
5The Linux DRM layer contains code intended to support the needs of
6complex graphics devices, usually containing programmable pipelines well
7suited to 3D graphics acceleration. Graphics drivers in the kernel may
8make use of DRM functions to make tasks like memory management,
9interrupt handling and DMA easier, and provide a uniform interface to
10applications.
11
12A note on versions: this guide covers features found in the DRM tree,
13including the TTM memory manager, output configuration and mode setting,
14and the new vblank internals, in addition to all the regular features
15found in current kernels.
16
17[Insert diagram of typical DRM stack here]
18
19Style Guidelines
20================
21
22For consistency this documentation uses American English. Abbreviations
23are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
24on. To aid in reading, documentations make full use of the markup
25characters kerneldoc provides: @parameter for function parameters,
26@member for structure members, &structure to reference structures and
27function() for functions. These all get automatically hyperlinked if
28kerneldoc for the referenced objects exists. When referencing entries in
29function vtables please use ->vfunc(). Note that kerneldoc does not
30support referencing struct members directly, so please add a reference
31to the vtable struct somewhere in the same paragraph or at least
32section.
33
34Except in special situations (to separate locked from unlocked variants)
35locking requirements for functions aren't documented in the kerneldoc.
36Instead locking should be check at runtime using e.g.
37``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
38documentation than runtime noise this provides more value. And on top of
39that runtime checks do need to be updated when the locking rules change,
40increasing the chances that they're correct. Within the documentation
41the locking rules should be explained in the relevant structures: Either
42in the comment for the lock explaining what it protects, or data fields
43need a note about which lock protects them, or both.
44
45Functions which have a non-\ ``void`` return value should have a section
46called "Returns" explaining the expected return values in different
47cases and their meanings. Currently there's no consensus whether that
48section name should be all upper-case or not, and whether it should end
49in a colon or not. Go with the file-local style. Other common section
50names are "Notes" with information for dangerous or tricky corner cases,
51and "FIXME" where the interface could be cleaned up.
52