<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Introduction — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="DRM Internals" href="drm-internals.html" />
<link rel="prev" title="GPU Driver Developer’s Guide" href="index.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../input/index.html">Input Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hid/index.html">Human Interface Devices (HID)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../sound/index.html">Sound Subsystem Documentation</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">GPU Driver Developer’s Guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../fb/index.html">Frame Buffer</a></li>
<li class="toctree-l3"><a class="reference internal" href="../leds/index.html">LEDs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/gpu/introduction.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h1>
<p>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.</p>
<p>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.</p>
<p>[Insert diagram of typical DRM stack here]</p>
<section id="style-guidelines">
<h2>Style Guidelines<a class="headerlink" href="#style-guidelines" title="Link to this heading">¶</a></h2>
<p>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), &<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">structure</span></code> to
reference structures and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">function()</span></code> 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.</p>
<p>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.
<code class="docutils literal notranslate"><span class="pre">WARN_ON(!mutex_is_locked(...));</span></code>. 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.</p>
<p>Functions which have a non-<code class="docutils literal notranslate"><span class="pre">void</span></code> 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.</p>
<p>Also read the <a class="reference internal" href="../doc-guide/index.html#doc-guide"><span class="std std-ref">guidelines for the kernel documentation at large</span></a>.</p>
<section id="documentation-requirements-for-kapi">
<h3>Documentation Requirements for kAPI<a class="headerlink" href="#documentation-requirements-for-kapi" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">/*</span> <span class="pre">private:</span> <span class="pre">*/</span></code> comments as per the
documentation guide.</p>
</section>
</section>
<section id="getting-started">
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Link to this heading">¶</a></h2>
<p>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.</p>
<p>Anyone looking to kick it up a notch can find a list of janitorial tasks on
the <a class="reference internal" href="todo.html#todo"><span class="std std-ref">TODO list</span></a>.</p>
</section>
<section id="contribution-process">
<h2>Contribution Process<a class="headerlink" href="#contribution-process" title="Link to this heading">¶</a></h2>
<p>Mostly the DRM subsystem works like any other kernel subsystem, see <a class="reference internal" href="../process/index.html#process-index"><span class="std std-ref">the
main process guidelines and documentation</span></a> for how things work.
Here we just document some of the specialities of the GPU subsystem.</p>
<section id="feature-merge-deadlines">
<h3>Feature Merge Deadlines<a class="headerlink" href="#feature-merge-deadlines" title="Link to this heading">¶</a></h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section id="code-of-conduct">
<h3>Code of Conduct<a class="headerlink" href="#code-of-conduct" title="Link to this heading">¶</a></h3>
<p>As a freedesktop.org project, dri-devel, and the DRM community, follows the
Contributor Covenant, found at: <a class="reference external" href="https://www.freedesktop.org/wiki/CodeOfConduct">https://www.freedesktop.org/wiki/CodeOfConduct</a></p>
<p>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.</p>
</section>
</section>
<section id="simple-drm-drivers-to-use-as-examples">
<h2>Simple DRM drivers to use as examples<a class="headerlink" href="#simple-drm-drivers-to-use-as-examples" title="Link to this heading">¶</a></h2>
<p>The DRM subsystem contains a lot of helper functions to ease writing drivers for
simple graphic devices. For example, the <cite>drivers/gpu/drm/tiny/</cite> directory has a
set of drivers that are simple enough to be implemented in a single source file.</p>
<p>These drivers make use of the <cite><a class="reference internal" href="drm-kms-helpers.html#c.drm_simple_display_pipe_funcs" title="drm_simple_display_pipe_funcs"><code class="xref c c-struct docutils literal notranslate"><span class="pre">struct</span> <span class="pre">drm_simple_display_pipe_funcs</span></code></a></cite>, 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.</p>
<p>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.</p>
</section>
<section id="external-references">
<h2>External References<a class="headerlink" href="#external-references" title="Link to this heading">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<section id="conference-talks">
<h3>Conference talks<a class="headerlink" href="#conference-talks" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=wjAJmqwg47k">An Overview of the Linux and Userspace Graphics Stack</a> - Paul Kocialkowski (2020)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=haes4_Xnc5Q">Getting pixels on screen on Linux: introduction to Kernel Mode Setting</a> - Simon Ser (2020)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=kVzHOgt6WGE">Everything Great about Upstream Graphics</a> - Simona Vetter (2019)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=LbDOCJcDRoo">An introduction to the Linux DRM subsystem</a> - Maxime Ripard (2017)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=LjiB_JeDn2M">Embrace the Atomic (Display) Age</a> - Simona Vetter (2016)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=lihqR9sENpc">Anatomy of an Atomic KMS Driver</a> - Laurent Pinchart (2015)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=kl9suFgbTc8">Atomic Modesetting for Drivers</a> - Simona Vetter (2015)</p></li>
<li><p><a class="reference external" href="https://www.youtube.com/watch?v=Ja8fM7rTae4">Anatomy of an Embedded KMS Driver</a> - Laurent Pinchart (2013)</p></li>
</ul>
</section>
<section id="slides-and-articles">
<h3>Slides and articles<a class="headerlink" href="#slides-and-articles" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://lwn.net/Articles/955376/">The Linux graphics stack in a nutshell, part 1</a> - Thomas Zimmermann (2023)</p></li>
<li><p><a class="reference external" href="https://lwn.net/Articles/955708/">The Linux graphics stack in a nutshell, part 2</a> - Thomas Zimmermann (2023)</p></li>
<li><p><a class="reference external" href="https://bootlin.com/doc/training/graphics/graphics-slides.pdf">Understanding the Linux Graphics Stack</a> - Bootlin (2022)</p></li>
<li><p><a class="reference external" href="https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview">DRM KMS overview</a> - STMicroelectronics (2021)</p></li>
<li><p><a class="reference external" href="https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview">Linux graphic stack</a> - Nathan Gauër (2017)</p></li>
<li><p><a class="reference external" href="https://lwn.net/Articles/653071/">Atomic mode setting design overview, part 1</a> - Simona Vetter (2015)</p></li>
<li><p><a class="reference external" href="https://lwn.net/Articles/653466/">Atomic mode setting design overview, part 2</a> - Simona Vetter (2015)</p></li>
<li><p><a class="reference external" href="https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf">The DRM/KMS subsystem from a newbie’s point of view</a> - Boris Brezillon (2014)</p></li>
<li><p><a class="reference external" href="https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/">A brief introduction to the Linux graphics stack</a> - Iago Toral (2014)</p></li>
<li><p><a class="reference external" href="https://blog.mecheye.net/2012/06/the-linux-graphics-stack/">The Linux Graphics Stack</a> - Jasper St. Pierre (2012)</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/gpu/introduction.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>