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