[mirror_ubuntu-artful-kernel.git] / Documentation / gpu / introduction.rst

============
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.
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,
	26	@member for structure members, &structure to reference structures and
	27	function() for functions. These all get automatically hyperlinked if
	28	kerneldoc for the referenced objects exists. When referencing entries in
	29	function vtables please use ->vfunc(). Note that kerneldoc does not
	30	support referencing struct members directly, so please add a reference
	31	to the vtable struct somewhere in the same paragraph or at least
	32	section.
	33
	34	Except in special situations (to separate locked from unlocked variants)
	35	locking requirements for functions aren't documented in the kerneldoc.
	36	Instead locking should be check at runtime using e.g.
	37	``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
	38	documentation than runtime noise this provides more value. And on top of
	39	that runtime checks do need to be updated when the locking rules change,
	40	increasing the chances that they're correct. Within the documentation
	41	the locking rules should be explained in the relevant structures: Either
	42	in the comment for the lock explaining what it protects, or data fields
	43	need a note about which lock protects them, or both.
	44
	45	Functions which have a non-\ ``void`` return value should have a section
	46	called "Returns" explaining the expected return values in different
	47	cases and their meanings. Currently there's no consensus whether that
	48	section name should be all upper-case or not, and whether it should end
	49	in a colon or not. Go with the file-local style. Other common section
	50	names are "Notes" with information for dangerous or tricky corner cases,
	51	and "FIXME" where the interface could be cleaned up.