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 19.. contents:: 20 21Style Guidelines 22================ 23 24For consistency this documentation uses American English. Abbreviations 25are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so 26on. To aid in reading, documentations make full use of the markup 27characters kerneldoc provides: @parameter for function parameters, 28@member for structure members (within the same structure), &struct structure to 29reference structures and function() for functions. These all get automatically 30hyperlinked if kerneldoc for the referenced objects exists. When referencing 31entries in function vtables (and structure members in general) please use 32&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the 33member, only the structure. 34 35Except in special situations (to separate locked from unlocked variants) 36locking requirements for functions aren't documented in the kerneldoc. 37Instead locking should be check at runtime using e.g. 38``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore 39documentation than runtime noise this provides more value. And on top of 40that runtime checks do need to be updated when the locking rules change, 41increasing the chances that they're correct. Within the documentation 42the locking rules should be explained in the relevant structures: Either 43in the comment for the lock explaining what it protects, or data fields 44need a note about which lock protects them, or both. 45 46Functions which have a non-\ ``void`` return value should have a section 47called "Returns" explaining the expected return values in different 48cases and their meanings. Currently there's no consensus whether that 49section name should be all upper-case or not, and whether it should end 50in a colon or not. Go with the file-local style. Other common section 51names are "Notes" with information for dangerous or tricky corner cases, 52and "FIXME" where the interface could be cleaned up. 53 54Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. 55 56Documentation Requirements for kAPI 57----------------------------------- 58 59All kernel APIs exported to other modules must be documented, including their 60datastructures and at least a short introductory section explaining the overall 61concepts. Documentation should be put into the code itself as kerneldoc comments 62as much as reasonable. 63 64Do not blindly document everything, but document only what's relevant for driver 65authors: Internal functions of drm.ko and definitely static functions should not 66have formal kerneldoc comments. Use normal C comments if you feel like a comment 67is warranted. You may use kerneldoc syntax in the comment, but it shall not 68start with a /** kerneldoc marker. Similar for data structures, annotate 69anything entirely private with ``/* private: */`` comments as per the 70documentation guide. 71 72Getting Started 73=============== 74 75Developers interested in helping out with the DRM subsystem are very welcome. 76Often people will resort to sending in patches for various issues reported by 77checkpatch or sparse. We welcome such contributions. 78 79Anyone looking to kick it up a notch can find a list of janitorial tasks on 80the :ref:`TODO list <todo>`. 81 82Contribution Process 83==================== 84 85Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the 86main process guidelines and documentation <process_index>` for how things work. 87Here we just document some of the specialities of the GPU subsystem. 88 89Feature Merge Deadlines 90----------------------- 91 92All feature work must be in the linux-next tree by the -rc6 release of the 93current release cycle, otherwise they must be postponed and can't reach the next 94merge window. All patches must have landed in the drm-next tree by latest -rc7, 95but if your branch is not in linux-next then this must have happened by -rc6 96already. 97 98After that point only bugfixes (like after the upstream merge window has closed 99with the -rc1 release) are allowed. No new platform enabling or new drivers are 100allowed. 101 102This means that there's a blackout-period of about one month where feature work 103can't be merged. The recommended way to deal with that is having a -next tree 104that's always open, but making sure to not feed it into linux-next during the 105blackout period. As an example, drm-misc works like that. 106 107Code of Conduct 108--------------- 109 110As a freedesktop.org project, dri-devel, and the DRM community, follows the 111Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct 112 113Please conduct yourself in a respectful and civilised manner when 114interacting with community members on mailing lists, IRC, or bug 115trackers. The community represents the project as a whole, and abusive 116or bullying behaviour is not tolerated by the project. 117 118Simple DRM drivers to use as examples 119===================================== 120 121The DRM subsystem contains a lot of helper functions to ease writing drivers for 122simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a 123set of drivers that are simple enough to be implemented in a single source file. 124The tiny DRM drivers are good examples to understand how DRM drivers should look 125like. Since are just a few hundreds lines of code, they are quite easy to read. 126 127External References 128=================== 129 130Delving into a Linux kernel subsystem for the first time can be an overwhelming 131experience, one needs to get familiar with all the concepts and learn about the 132subsystem's internals, among other details. 133 134To shallow the learning curve, this section contains a list of presentations 135and documents that can be used to learn about DRM/KMS and graphics in general. 136 137There are different reasons why someone might want to get into DRM: porting an 138existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that 139could face when working on the graphics user-space stack, etc. For this reason, 140the learning material covers many aspects of the Linux graphics stack. From an 141overview of the kernel and user-space stacks to very specific topics. 142 143The list is sorted in reverse chronological order, to keep the most up-to-date 144material at the top. But all of them contain useful information, and it can be 145valuable to go through older material to understand the rationale and context 146in which the changes to the DRM subsystem were made. 147 148Conference talks 149---------------- 150 151* `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020) 152* `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020) 153* `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Simona Vetter (2019) 154* `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017) 155* `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Simona Vetter (2016) 156* `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015) 157* `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Simona Vetter (2015) 158* `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013) 159 160Slides and articles 161------------------- 162 163* `The Linux graphics stack in a nutshell, part 1 <https://lwn.net/Articles/955376/>`_ - Thomas Zimmermann (2023) 164* `The Linux graphics stack in a nutshell, part 2 <https://lwn.net/Articles/955708/>`_ - Thomas Zimmermann (2023) 165* `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022) 166* `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021) 167* `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017) 168* `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Simona Vetter (2015) 169* `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Simona Vetter (2015) 170* `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) 171* `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) 172* `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012) 173