[linux-2.6-block.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 (within the same structure), &struct 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 (and structure members in general) please use
&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the
member, only the structure.

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.

Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.

Getting Started
===============

Developers interested in helping out with the DRM subsystem are very welcome.
Often people will resort to sending in patches for various issues reported by
checkpatch or sparse. We welcome such contributions.

Anyone looking to kick it up a notch can find a list of janitorial tasks on
the :ref:`TODO list <todo>`.

Contribution Process
====================

Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the
main process guidelines and documentation <process_index>` for how things work.
Here we just document some of the specialities of the GPU subsystem.

Feature Merge Deadlines
-----------------------

All feature work must be in the linux-next tree by the -rc6 release of the
current release cycle, otherwise they must be postponed and can't reach the next
merge window. All patches must have landed in the drm-next tree by latest -rc7,
but if your branch is not in linux-next then this must have happened by -rc6
already.

After that point only bugfixes (like after the upstream merge window has closed
with the -rc1 release) are allowed. No new platform enabling or new drivers are
allowed.

This means that there's a blackout-period of about one month where feature work
can't be merged. The recommended way to deal with that is having a -next tree
that's always open, but making sure to not feed it into linux-next during the
blackout period. As an example, drm-misc works like that.

Code of Conduct
---------------

As a freedesktop.org project, dri-devel, and the DRM community, follows the
Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct

Please conduct yourself in a respectful and civilised manner when
interacting with community members on mailing lists, IRC, or bug
trackers. The community represents the project as a whole, and abusive
or bullying behaviour is not tolerated by the project.
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
ae774e2c DV	52	Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
0e70dad0 TR	53
	54	Getting Started
	55	===============
	56
	57	Developers interested in helping out with the DRM subsystem are very welcome.
	58	Often people will resort to sending in patches for various issues reported by
	59	checkpatch or sparse. We welcome such contributions.
	60
	61	Anyone looking to kick it up a notch can find a list of janitorial tasks on
	62	the :ref:`TODO list <todo>`.
eadf71cd DV	63
	64	Contribution Process
	65	====================
	66
	67	Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the
	68	main process guidelines and documentation <process_index>` for how things work.
	69	Here we just document some of the specialities of the GPU subsystem.
	70
	71	Feature Merge Deadlines
	72	-----------------------
	73
	74	All feature work must be in the linux-next tree by the -rc6 release of the
	75	current release cycle, otherwise they must be postponed and can't reach the next
	76	merge window. All patches must have landed in the drm-next tree by latest -rc7,
	77	but if your branch is not in linux-next then this must have happened by -rc6
	78	already.
	79
	80	After that point only bugfixes (like after the upstream merge window has closed
	81	with the -rc1 release) are allowed. No new platform enabling or new drivers are
	82	allowed.
	83
	84	This means that there's a blackout-period of about one month where feature work
	85	can't be merged. The recommended way to deal with that is having a -next tree
	86	that's always open, but making sure to not feed it into linux-next during the
	87	blackout period. As an example, drm-misc works like that.
8676df50 DV	88
	89	Code of Conduct
	90	---------------
	91
	92	As a freedesktop.org project, dri-devel, and the DRM community, follows the
	93	Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
	94
	95	Please conduct yourself in a respectful and civilised manner when
	96	interacting with community members on mailing lists, IRC, or bug
	97	trackers. The community represents the project as a whole, and abusive
	98	or bullying behaviour is not tolerated by the project.