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 (within the same structure), &struct structure to
 27reference structures and function() for functions. These all get automatically
 28hyperlinked if kerneldoc for the referenced objects exists. When referencing
 29entries 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
 31member, only the structure.
 32
 33Except in special situations (to separate locked from unlocked variants)
 34locking requirements for functions aren't documented in the kerneldoc.
 35Instead locking should be check at runtime using e.g.
 36``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
 37documentation than runtime noise this provides more value. And on top of
 38that runtime checks do need to be updated when the locking rules change,
 39increasing the chances that they're correct. Within the documentation
 40the locking rules should be explained in the relevant structures: Either
 41in the comment for the lock explaining what it protects, or data fields
 42need a note about which lock protects them, or both.
 43
 44Functions which have a non-\ ``void`` return value should have a section
 45called "Returns" explaining the expected return values in different
 46cases and their meanings. Currently there's no consensus whether that
 47section name should be all upper-case or not, and whether it should end
 48in a colon or not. Go with the file-local style. Other common section
 49names are "Notes" with information for dangerous or tricky corner cases,
 50and "FIXME" where the interface could be cleaned up.
 51
 52Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
 53
 54Documentation Requirements for kAPI
 55-----------------------------------
 56
 57All kernel APIs exported to other modules must be documented, including their
 58datastructures and at least a short introductory section explaining the overall
 59concepts. Documentation should be put into the code itself as kerneldoc comments
 60as much as reasonable.
 61
 62Do not blindly document everything, but document only what's relevant for driver
 63authors: Internal functions of drm.ko and definitely static functions should not
 64have formal kerneldoc comments. Use normal C comments if you feel like a comment
 65is warranted. You may use kerneldoc syntax in the comment, but it shall not
 66start with a /** kerneldoc marker. Similar for data structures, annotate
 67anything entirely private with ``/* private: */`` comments as per the
 68documentation guide.
 69
 70Getting Started
 71===============
 72
 73Developers interested in helping out with the DRM subsystem are very welcome.
 74Often people will resort to sending in patches for various issues reported by
 75checkpatch or sparse. We welcome such contributions.
 76
 77Anyone looking to kick it up a notch can find a list of janitorial tasks on
 78the :ref:`TODO list <todo>`.
 79
 80Contribution Process
 81====================
 82
 83Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the
 84main process guidelines and documentation <process_index>` for how things work.
 85Here we just document some of the specialities of the GPU subsystem.
 86
 87Feature Merge Deadlines
 88-----------------------
 89
 90All feature work must be in the linux-next tree by the -rc6 release of the
 91current release cycle, otherwise they must be postponed and can't reach the next
 92merge window. All patches must have landed in the drm-next tree by latest -rc7,
 93but if your branch is not in linux-next then this must have happened by -rc6
 94already.
 95
 96After that point only bugfixes (like after the upstream merge window has closed
 97with the -rc1 release) are allowed. No new platform enabling or new drivers are
 98allowed.
 99
100This means that there's a blackout-period of about one month where feature work
101can't be merged. The recommended way to deal with that is having a -next tree
102that's always open, but making sure to not feed it into linux-next during the
103blackout period. As an example, drm-misc works like that.
104
105Code of Conduct
106---------------
107
108As a freedesktop.org project, dri-devel, and the DRM community, follows the
109Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
110
111Please conduct yourself in a respectful and civilised manner when
112interacting with community members on mailing lists, IRC, or bug
113trackers. The community represents the project as a whole, and abusive
114or bullying behaviour is not tolerated by the project.