177 lines · plain
1============2Introduction3============4 5The Linux DRM layer contains code intended to support the needs of6complex graphics devices, usually containing programmable pipelines well7suited to 3D graphics acceleration. Graphics drivers in the kernel may8make use of DRM functions to make tasks like memory management,9interrupt handling and DMA easier, and provide a uniform interface to10applications.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 features15found in current kernels.16 17[Insert diagram of typical DRM stack here]18 19Style Guidelines20================21 22For consistency this documentation uses American English. Abbreviations23are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so24on. To aid in reading, documentations make full use of the markup25characters kerneldoc provides: @parameter for function parameters,26@member for structure members (within the same structure), &struct structure to27reference structures and function() for functions. These all get automatically28hyperlinked if kerneldoc for the referenced objects exists. When referencing29entries in function vtables (and structure members in general) please use30&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the31member, 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 ignore37documentation than runtime noise this provides more value. And on top of38that runtime checks do need to be updated when the locking rules change,39increasing the chances that they're correct. Within the documentation40the locking rules should be explained in the relevant structures: Either41in the comment for the lock explaining what it protects, or data fields42need a note about which lock protects them, or both.43 44Functions which have a non-\ ``void`` return value should have a section45called "Returns" explaining the expected return values in different46cases and their meanings. Currently there's no consensus whether that47section name should be all upper-case or not, and whether it should end48in a colon or not. Go with the file-local style. Other common section49names 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 kAPI55-----------------------------------56 57All kernel APIs exported to other modules must be documented, including their58datastructures and at least a short introductory section explaining the overall59concepts. Documentation should be put into the code itself as kerneldoc comments60as much as reasonable.61 62Do not blindly document everything, but document only what's relevant for driver63authors: Internal functions of drm.ko and definitely static functions should not64have formal kerneldoc comments. Use normal C comments if you feel like a comment65is warranted. You may use kerneldoc syntax in the comment, but it shall not66start with a /** kerneldoc marker. Similar for data structures, annotate67anything entirely private with ``/* private: */`` comments as per the68documentation guide.69 70Getting Started71===============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 by75checkpatch or sparse. We welcome such contributions.76 77Anyone looking to kick it up a notch can find a list of janitorial tasks on78the :ref:`TODO list <todo>`.79 80Contribution Process81====================82 83Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the84main 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 Deadlines88-----------------------89 90All feature work must be in the linux-next tree by the -rc6 release of the91current release cycle, otherwise they must be postponed and can't reach the next92merge 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 -rc694already.95 96After that point only bugfixes (like after the upstream merge window has closed97with the -rc1 release) are allowed. No new platform enabling or new drivers are98allowed.99 100This means that there's a blackout-period of about one month where feature work101can't be merged. The recommended way to deal with that is having a -next tree102that's always open, but making sure to not feed it into linux-next during the103blackout period. As an example, drm-misc works like that.104 105Code of Conduct106---------------107 108As a freedesktop.org project, dri-devel, and the DRM community, follows the109Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct110 111Please conduct yourself in a respectful and civilised manner when112interacting with community members on mailing lists, IRC, or bug113trackers. The community represents the project as a whole, and abusive114or bullying behaviour is not tolerated by the project.115 116Simple DRM drivers to use as examples117=====================================118 119The DRM subsystem contains a lot of helper functions to ease writing drivers for120simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a121set of drivers that are simple enough to be implemented in a single source file.122 123These drivers make use of the `struct drm_simple_display_pipe_funcs`, that hides124any complexity of the DRM subsystem and just requires drivers to implement a few125functions needed to operate the device. This could be used for devices that just126need a display pipeline with one full-screen scanout buffer feeding one output.127 128The tiny DRM drivers are good examples to understand how DRM drivers should look129like. Since are just a few hundreds lines of code, they are quite easy to read.130 131External References132===================133 134Delving into a Linux kernel subsystem for the first time can be an overwhelming135experience, one needs to get familiar with all the concepts and learn about the136subsystem's internals, among other details.137 138To shallow the learning curve, this section contains a list of presentations139and documents that can be used to learn about DRM/KMS and graphics in general.140 141There are different reasons why someone might want to get into DRM: porting an142existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that143could face when working on the graphics user-space stack, etc. For this reason,144the learning material covers many aspects of the Linux graphics stack. From an145overview of the kernel and user-space stacks to very specific topics.146 147The list is sorted in reverse chronological order, to keep the most up-to-date148material at the top. But all of them contain useful information, and it can be149valuable to go through older material to understand the rationale and context150in which the changes to the DRM subsystem were made.151 152Conference talks153----------------154 155* `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020)156* `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020)157* `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Simona Vetter (2019)158* `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017)159* `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Simona Vetter (2016)160* `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015)161* `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Simona Vetter (2015)162* `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013)163 164Slides and articles165-------------------166 167* `The Linux graphics stack in a nutshell, part 1 <https://lwn.net/Articles/955376/>`_ - Thomas Zimmermann (2023)168* `The Linux graphics stack in a nutshell, part 2 <https://lwn.net/Articles/955708/>`_ - Thomas Zimmermann (2023)169* `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022)170* `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021)171* `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017)172* `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Simona Vetter (2015)173* `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Simona Vetter (2015)174* `The DRM/KMS subsystem from a newbie’s point of view <https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf>`_ - Boris Brezillon (2014)175* `A brief introduction to the Linux graphics stack <https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/>`_ - Iago Toral (2014)176* `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012)177