Introduction¶
The Linux DRM layer contains code intended to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics acceleration. Graphics drivers in the kernel may make use of DRM functions to make tasks like memory management, interrupt handling and DMA easier, and provide a uniform interface to applications.
A note on versions: this guide covers features found in the DRM tree, including the TTM memory manager, output configuration and mode setting, and the new vblank internals, in addition to all the regular features found in current kernels.
[Insert diagram of typical DRM stack here]
Style Guidelines¶
For consistency this documentation uses American English. Abbreviations are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so on. To aid in reading, documentations make full use of the markup characters kerneldoc provides: @parameter for function parameters, @member for structure members (within the same structure), &struct structure to reference structures and function() for functions. These all get automatically hyperlinked if kerneldoc for the referenced objects exists. When referencing entries in function vtables (and structure members in general) please use &vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the member, only the structure.
Except in special situations (to separate locked from unlocked variants) locking requirements for functions aren’t documented in the kerneldoc. Instead locking should be check at runtime using e.g. WARN_ON(!mutex_is_locked(. )); . Since it’s much easier to ignore documentation than runtime noise this provides more value. And on top of that runtime checks do need to be updated when the locking rules change, increasing the chances that they’re correct. Within the documentation the locking rules should be explained in the relevant structures: Either in the comment for the lock explaining what it protects, or data fields need a note about which lock protects them, or both.
Functions which have a non- void return value should have a section called «Returns» explaining the expected return values in different cases and their meanings. Currently there’s no consensus whether that section name should be all upper-case or not, and whether it should end in a colon or not. Go with the file-local style. Other common section names are «Notes» with information for dangerous or tricky corner cases, and «FIXME» where the interface could be cleaned up.
Documentation Requirements for kAPI¶
All kernel APIs exported to other modules must be documented, including their datastructures and at least a short introductory section explaining the overall concepts. Documentation should be put into the code itself as kerneldoc comments as much as reasonable.
Do not blindly document everything, but document only what’s relevant for driver authors: Internal functions of drm.ko and definitely static functions should not have formal kerneldoc comments. Use normal C comments if you feel like a comment is warranted. You may use kerneldoc syntax in the comment, but it shall not start with a /** kerneldoc marker. Similar for data structures, annotate anything entirely private with /* private: */ comments as per the documentation guide.
Getting Started¶
Developers interested in helping out with the DRM subsystem are very welcome. Often people will resort to sending in patches for various issues reported by checkpatch or sparse. We welcome such contributions.
Anyone looking to kick it up a notch can find a list of janitorial tasks on the TODO list .
Contribution Process¶
Mostly the DRM subsystem works like any other kernel subsystem, see the main process guidelines and documentation for how things work. Here we just document some of the specialities of the GPU subsystem.
Feature Merge Deadlines¶
All feature work must be in the linux-next tree by the -rc6 release of the current release cycle, otherwise they must be postponed and can’t reach the next merge window. All patches must have landed in the drm-next tree by latest -rc7, but if your branch is not in linux-next then this must have happened by -rc6 already.
After that point only bugfixes (like after the upstream merge window has closed with the -rc1 release) are allowed. No new platform enabling or new drivers are allowed.
This means that there’s a blackout-period of about one month where feature work can’t be merged. The recommended way to deal with that is having a -next tree that’s always open, but making sure to not feed it into linux-next during the blackout period. As an example, drm-misc works like that.
Code of Conduct¶
As a freedesktop.org project, dri-devel, and the DRM community, follows the Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
Please conduct yourself in a respectful and civilised manner when interacting with community members on mailing lists, IRC, or bug trackers. The community represents the project as a whole, and abusive or bullying behaviour is not tolerated by the project.
Simple DRM drivers to use as examples¶
The DRM subsystem contains a lot of helper functions to ease writing drivers for simple graphic devices. For example, the drivers/gpu/drm/tiny/ directory has a set of drivers that are simple enough to be implemented in a single source file.
These drivers make use of the struct drm_simple_display_pipe_funcs , that hides any complexity of the DRM subsystem and just requires drivers to implement a few functions needed to operate the device. This could be used for devices that just need a display pipeline with one full-screen scanout buffer feeding one output.
The tiny DRM drivers are good examples to understand how DRM drivers should look like. Since are just a few hundreds lines of code, they are quite easy to read.
External References¶
Delving into a Linux kernel subsystem for the first time can be an overwhelming experience, one needs to get familiar with all the concepts and learn about the subsystem’s internals, among other details.
To shallow the learning curve, this section contains a list of presentations and documents that can be used to learn about DRM/KMS and graphics in general.
There are different reasons why someone might want to get into DRM: porting an existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that could face when working on the graphics user-space stack, etc. For this reason, the learning material covers many aspects of the Linux graphics stack. From an overview of the kernel and user-space stacks to very specific topics.
The list is sorted in reverse chronological order, to keep the most up-to-date material at the top. But all of them contain useful information, and it can be valuable to go through older material to understand the rationale and context in which the changes to the DRM subsystem were made.
Conference talks¶
- An Overview of the Linux and Userspace Graphics Stack — Paul Kocialkowski (2020)
- Getting pixels on screen on Linux: introduction to Kernel Mode Setting — Simon Ser (2020)
- Everything Great about Upstream Graphics — Daniel Vetter (2019)
- An introduction to the Linux DRM subsystem — Maxime Ripard (2017)
- Embrace the Atomic (Display) Age — Daniel Vetter (2016)
- Anatomy of an Atomic KMS Driver — Laurent Pinchart (2015)
- Atomic Modesetting for Drivers — Daniel Vetter (2015)
- Anatomy of an Embedded KMS Driver — Laurent Pinchart (2013)
Slides and articles¶
- Understanding the Linux Graphics Stack — Bootlin (2022)
- DRM KMS overview — STMicroelectronics (2021)
- Linux graphic stack — Nathan Gauër (2017)
- Atomic mode setting design overview, part 1 — Daniel Vetter (2015)
- Atomic mode setting design overview, part 2 — Daniel Vetter (2015)
- The DRM/KMS subsystem from a newbie’s point of view — Boris Brezillon (2014)
- A brief introduction to the Linux graphics stack — Iago Toral (2014)
- The Linux Graphics Stack — Jasper St. Pierre (2012)
Speeding Up The Linux Kernel With Your GPU
Sponsored in part by NVIDIA, at the University of Utah they are exploring speeding up the Linux kernel by using GPU acceleration. Rather than just allowing user-space applications to utilize the immense power offered by modern graphics processors, they are looking to speed up parts of the Linux kernel by running it directly on the GPU.
From the project page: «The idea behind KGPU is to treat the GPU as a computing co-processor for the operating system, enabling data-parallel computation inside the Linux kernel. This allows us to use SIMD (or SIMT in CUDA) style code to accelerate Linux kernel functionality, and to bring new functionality formerly considered too compute intensive into the kernel. Simply put, KGPU enables vector computing for the kernel.»
Additionally, «it makes the Linux kernel really parallelized: it is not only processing multiple requests concurrently, but can also partition a single large requested computation into tiles and spread them across the large number of cores on a GPU.»
While it sounds like a novel concept, this is more of a research project at this point and there are a few factors that basically rule out this «KGPU» project from making much mainstream adoption for the foreseeable future. The big problem is that none of the open-source graphics drivers living within the Linux kernel DRM (Direct Rendering Manager) sub-system are yet capable of GPGPU support. There is support planned for an OpenCL Gallium3D state tracker with Clover, but that’s far from being ready.
The other problem is that this current work just targets the Linux kernel on calling the GPU using CUDA. This work is sponsored by NVIDIA so the university went with using the Compute Unified Device Architecture, which is only supported on NVIDIA hardware, and when using their latest proprietary driver. A better choice would have been OpenCL, which can run on both AMD and NVIDIA GPUs and is an open industry standard.
At this point in the development of KGPU, they have a GPU-accelerated AES cipher for use by the eCryptfs encrypted file-system, which is showing off promising results considering how well modern GPUs can deal with cryptography.
Those interested in learning more about KGPU to augment the Linux kernel with the GPU, visit the Google Code page. Code is also available on GitHub. It would be interesting to see the Linux kernel begin to take advantage of the processing capabilities offered by modern GPUs, but first the open-source kernel drivers must be improved and be able to handle OpenCL and/or other GPGPU interfaces.