Introduction

The Linux DRM layer contains code intended to support the needs ofcomplex graphics devices, usually containing programmable pipelines wellsuited to 3D graphics acceleration. Graphics drivers in the kernel maymake use of DRM functions to make tasks like memory management,interrupt handling and DMA easier, and provide a uniform interface toapplications.

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 featuresfound in current kernels.

[Insert diagram of typical DRM stack here]

Style Guidelines

For consistency this documentation uses American English. Abbreviationsare written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and soon. To aid in reading, documentations make full use of the markupcharacters kerneldoc provides: @parameter for function parameters,@member for structure members (within the same structure), &structstructure toreference structures andfunction() for functions. These all get automaticallyhyperlinked if kerneldoc for the referenced objects exists. When referencingentries in function vtables (and structure members in general) please use&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to themember, 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 ignoredocumentation than runtime noise this provides more value. And on top ofthat runtime checks do need to be updated when the locking rules change,increasing the chances that they’re correct. Within the documentationthe locking rules should be explained in the relevant structures: Eitherin the comment for the lock explaining what it protects, or data fieldsneed a note about which lock protects them, or both.

Functions which have a non-void return value should have a sectioncalled “Returns” explaining the expected return values in differentcases and their meanings. Currently there’s no consensus whether thatsection name should be all upper-case or not, and whether it should endin a colon or not. Go with the file-local style. Other common sectionnames are “Notes” with information for dangerous or tricky corner cases,and “FIXME” where the interface could be cleaned up.

Also read theguidelines for the kernel documentation at large.

Documentation Requirements for kAPI

All kernel APIs exported to other modules must be documented, including theirdatastructures and at least a short introductory section explaining the overallconcepts. Documentation should be put into the code itself as kerneldoc commentsas much as reasonable.

Do not blindly document everything, but document only what’s relevant for driverauthors: Internal functions of drm.ko and definitely static functions should nothave formal kerneldoc comments. Use normal C comments if you feel like a commentis warranted. You may use kerneldoc syntax in the comment, but it shall notstart with a /** kerneldoc marker. Similar for data structures, annotateanything entirely private with/*private:*/ comments as per thedocumentation 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 bycheckpatch or sparse. We welcome such contributions.

Anyone looking to kick it up a notch can find a list of janitorial tasks ontheTODO list.

Contribution Process

Mostly the DRM subsystem works like any other kernel subsystem, seethemain 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 thecurrent release cycle, otherwise they must be postponed and can’t reach the nextmerge 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 -rc6already.

After that point only bugfixes (like after the upstream merge window has closedwith the -rc1 release) are allowed. No new platform enabling or new drivers areallowed.

This means that there’s a blackout-period of about one month where feature workcan’t be merged. The recommended way to deal with that is having a -next treethat’s always open, but making sure to not feed it into linux-next during theblackout period. As an example, drm-misc works like that.

Code of Conduct

As a freedesktop.org project, dri-devel, and the DRM community, follows theContributor Covenant, found at:https://www.freedesktop.org/wiki/CodeOfConduct

Please conduct yourself in a respectful and civilised manner wheninteracting with community members on mailing lists, IRC, or bugtrackers. The community represents the project as a whole, and abusiveor 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 forsimple graphic devices. For example, thedrivers/gpu/drm/tiny/ directory has aset of drivers that are simple enough to be implemented in a single source file.

These drivers make use of thestructdrm_simple_display_pipe_funcs, that hidesany complexity of the DRM subsystem and just requires drivers to implement a fewfunctions needed to operate the device. This could be used for devices that justneed 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 looklike. 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 overwhelmingexperience, one needs to get familiar with all the concepts and learn about thesubsystem’s internals, among other details.

To shallow the learning curve, this section contains a list of presentationsand 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 anexisting fbdev driver, write a DRM driver for a new hardware, fixing bugs thatcould 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 anoverview 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-datematerial at the top. But all of them contain useful information, and it can bevaluable to go through older material to understand the rationale and contextin which the changes to the DRM subsystem were made.

Conference talks

Slides and articles