introduction.rst 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. ============
  2. Introduction
  3. ============
  4. The Linux DRM layer contains code intended to support the needs of
  5. complex graphics devices, usually containing programmable pipelines well
  6. suited to 3D graphics acceleration. Graphics drivers in the kernel may
  7. make use of DRM functions to make tasks like memory management,
  8. interrupt handling and DMA easier, and provide a uniform interface to
  9. applications.
  10. A note on versions: this guide covers features found in the DRM tree,
  11. including the TTM memory manager, output configuration and mode setting,
  12. and the new vblank internals, in addition to all the regular features
  13. found in current kernels.
  14. [Insert diagram of typical DRM stack here]
  15. Style Guidelines
  16. ================
  17. For consistency this documentation uses American English. Abbreviations
  18. are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
  19. on. To aid in reading, documentations make full use of the markup
  20. characters kerneldoc provides: @parameter for function parameters,
  21. @member for structure members (within the same structure), &struct structure to
  22. reference structures and function() for functions. These all get automatically
  23. hyperlinked if kerneldoc for the referenced objects exists. When referencing
  24. entries in function vtables (and structure members in general) please use
  25. &vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the
  26. member, only the structure.
  27. Except in special situations (to separate locked from unlocked variants)
  28. locking requirements for functions aren't documented in the kerneldoc.
  29. Instead locking should be check at runtime using e.g.
  30. ``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
  31. documentation than runtime noise this provides more value. And on top of
  32. that runtime checks do need to be updated when the locking rules change,
  33. increasing the chances that they're correct. Within the documentation
  34. the locking rules should be explained in the relevant structures: Either
  35. in the comment for the lock explaining what it protects, or data fields
  36. need a note about which lock protects them, or both.
  37. Functions which have a non-\ ``void`` return value should have a section
  38. called "Returns" explaining the expected return values in different
  39. cases and their meanings. Currently there's no consensus whether that
  40. section name should be all upper-case or not, and whether it should end
  41. in a colon or not. Go with the file-local style. Other common section
  42. names are "Notes" with information for dangerous or tricky corner cases,
  43. and "FIXME" where the interface could be cleaned up.
  44. Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
  45. Documentation Requirements for kAPI
  46. -----------------------------------
  47. All kernel APIs exported to other modules must be documented, including their
  48. datastructures and at least a short introductory section explaining the overall
  49. concepts. Documentation should be put into the code itself as kerneldoc comments
  50. as much as reasonable.
  51. Do not blindly document everything, but document only what's relevant for driver
  52. authors: Internal functions of drm.ko and definitely static functions should not
  53. have formal kerneldoc comments. Use normal C comments if you feel like a comment
  54. is warranted. You may use kerneldoc syntax in the comment, but it shall not
  55. start with a /** kerneldoc marker. Similar for data structures, annotate
  56. anything entirely private with ``/* private: */`` comments as per the
  57. documentation guide.
  58. Getting Started
  59. ===============
  60. Developers interested in helping out with the DRM subsystem are very welcome.
  61. Often people will resort to sending in patches for various issues reported by
  62. checkpatch or sparse. We welcome such contributions.
  63. Anyone looking to kick it up a notch can find a list of janitorial tasks on
  64. the :ref:`TODO list <todo>`.
  65. Contribution Process
  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. Feature Merge Deadlines
  71. -----------------------
  72. All feature work must be in the linux-next tree by the -rc6 release of the
  73. current release cycle, otherwise they must be postponed and can't reach the next
  74. merge window. All patches must have landed in the drm-next tree by latest -rc7,
  75. but if your branch is not in linux-next then this must have happened by -rc6
  76. already.
  77. After that point only bugfixes (like after the upstream merge window has closed
  78. with the -rc1 release) are allowed. No new platform enabling or new drivers are
  79. allowed.
  80. This means that there's a blackout-period of about one month where feature work
  81. can't be merged. The recommended way to deal with that is having a -next tree
  82. that's always open, but making sure to not feed it into linux-next during the
  83. blackout period. As an example, drm-misc works like that.
  84. Code of Conduct
  85. ---------------
  86. As a freedesktop.org project, dri-devel, and the DRM community, follows the
  87. Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
  88. Please conduct yourself in a respectful and civilised manner when
  89. interacting with community members on mailing lists, IRC, or bug
  90. trackers. The community represents the project as a whole, and abusive
  91. or bullying behaviour is not tolerated by the project.