Documentation/gpu/introduction.rst

   1 ============
   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
  20 ================
  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.