mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-11-14 15:54:15 +08:00
2255402040
While splitting the document up, the headings "shifted" from what pandoc generated. Use the following order for headings for consistency: ============== Document title ============== First ===== Second ------ Third ~~~~~ Leave the lower level headings as they are; I think those are less important. Although RST doesn't mandate a specific order ("Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. [I'm sort of kind of writing the recommendation for docs-next in the mean time, but this order seems sensible, and is what I'm proposing.] Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Link: http://patchwork.freedesktop.org/patch/msgid/126f42734defac6cbb8496a481d58db7b38461dd.1466506505.git.jani.nikula@intel.com
52 lines
2.5 KiB
ReStructuredText
52 lines
2.5 KiB
ReStructuredText
============
|
|
Introduction
|
|
============
|
|
|
|
The Linux DRM layer contains code intended to support the needs of
|
|
complex graphics devices, usually containing programmable pipelines well
|
|
suited to 3D graphics acceleration. Graphics drivers in the kernel may
|
|
make use of DRM functions to make tasks like memory management,
|
|
interrupt handling and DMA easier, and provide a uniform interface to
|
|
applications.
|
|
|
|
A note on versions: this guide covers features found in the DRM tree,
|
|
including the TTM memory manager, output configuration and mode setting,
|
|
and the new vblank internals, in addition to all the regular features
|
|
found in current kernels.
|
|
|
|
[Insert diagram of typical DRM stack here]
|
|
|
|
Style Guidelines
|
|
================
|
|
|
|
For consistency this documentation uses American English. Abbreviations
|
|
are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
|
|
on. To aid in reading, documentations make full use of the markup
|
|
characters kerneldoc provides: @parameter for function parameters,
|
|
@member for structure members, &structure to reference structures and
|
|
function() for functions. These all get automatically hyperlinked if
|
|
kerneldoc for the referenced objects exists. When referencing entries in
|
|
function vtables please use ->vfunc(). Note that kerneldoc does not
|
|
support referencing struct members directly, so please add a reference
|
|
to the vtable struct somewhere in the same paragraph or at least
|
|
section.
|
|
|
|
Except in special situations (to separate locked from unlocked variants)
|
|
locking requirements for functions aren't documented in the kerneldoc.
|
|
Instead locking should be check at runtime using e.g.
|
|
``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
|
|
documentation than runtime noise this provides more value. And on top of
|
|
that runtime checks do need to be updated when the locking rules change,
|
|
increasing the chances that they're correct. Within the documentation
|
|
the locking rules should be explained in the relevant structures: Either
|
|
in the comment for the lock explaining what it protects, or data fields
|
|
need a note about which lock protects them, or both.
|
|
|
|
Functions which have a non-\ ``void`` return value should have a section
|
|
called "Returns" explaining the expected return values in different
|
|
cases and their meanings. Currently there's no consensus whether that
|
|
section name should be all upper-case or not, and whether it should end
|
|
in a colon or not. Go with the file-local style. Other common section
|
|
names are "Notes" with information for dangerous or tricky corner cases,
|
|
and "FIXME" where the interface could be cleaned up.
|