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