drm/man/drm-kms.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
  Dedicated to the Public Domain
-->

<refentry id="drm-kms">
  <refentryinfo>
    <title>Direct Rendering Manager</title>
    <productname>libdrm</productname>
    <date>September 2012</date>
    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>David</firstname>
        <surname>Herrmann</surname>
        <email>dh.herrmann@googlemail.com</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>drm-kms</refentrytitle>
    <manvolnum>7</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>drm-kms</refname>
    <refpurpose>Kernel Mode-Setting</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;xf86drm.h&gt;</funcsynopsisinfo>
      <funcsynopsisinfo>#include &lt;xf86drmMode.h&gt;</funcsynopsisinfo>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>Each DRM device provides access to manage which monitors and displays
          are currently used and what frames to be displayed. This task is
          called <emphasis>Kernel Mode-Setting</emphasis> (KMS). Historically,
          this was done in user-space and called 
          <emphasis>User-space Mode-Setting</emphasis> (UMS). Almost all
          open-source drivers now provide the KMS kernel API to do this in the
          kernel, however, many non-open-source binary drivers from different
          vendors still do not support this. You can use
          <citerefentry><refentrytitle>drmModeSettingSupported</refentrytitle><manvolnum>3</manvolnum></citerefentry>
          to check whether your driver supports this. To understand how KMS
          works, we need to introduce 5 objects: <emphasis>CRTCs</emphasis>,
          <emphasis>Planes</emphasis>, <emphasis>Encoders</emphasis>,
          <emphasis>Connectors</emphasis> and
          <emphasis>Framebuffers</emphasis>.

      <variablelist>
        <varlistentry>
          <term>CRTCs</term>
          <listitem>
            <para>A <emphasis>CRTC</emphasis> short for
                  <emphasis>CRT Controller</emphasis> is an abstraction
                  representing a part of the chip that contains a pointer to a
                  scanout buffer. Therefore, the number of CRTCs available
                  determines how many independent scanout buffers can be active
                  at any given time. The CRTC structure contains several fields
                  to support this: a pointer to some video memory (abstracted as
                  a frame-buffer object), a list of driven connectors, a display
                  mode and an (x, y) offset into the video memory to support
                  panning or configurations where one piece of video memory
                  spans multiple CRTCs. A CRTC is the central point where
                  configuration of displays happens. You select which objects to
                  use, which modes and which parameters and then configure each
                  CRTC via
                  <citerefentry><refentrytitle>drmModeCrtcSet</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                  to drive the display devices.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Planes</term>
          <listitem>
            <para>A <emphasis>plane</emphasis> respresents an image source that
                  can be blended with or overlayed on top of a CRTC during the
                  scanout process. Planes are associated with a frame-buffer to
                  crop a portion of the image memory (source) and optionally
                  scale it to a destination size. The result is then blended
                  with or overlayed on top of a CRTC. Planes are not provided by
                  all hardware and the number of available planes is limited. If
                  planes are not available or if not enough planes are
                  available, the user should fall back to normal software
                  blending (via GPU or CPU).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Encoders</term>
          <listitem>
            <para>An <emphasis>encoder</emphasis> takes pixel data from a CRTC
                  and converts it to a format suitable for any attached
                  connectors. On some devices, it may be possible to have a CRTC
                  send data to more than one encoder. In that case, both
                  encoders would receive data from the same scanout buffer,
                  resulting in a <emphasis>cloned</emphasis> display
                  configuration across the connectors attached to each
                  encoder.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Connectors</term>
          <listitem>
            <para>A <emphasis>connector</emphasis> is the final destination of
                  pixel-data on a device, and usually connects directly to an
                  external display device like a monitor or laptop panel. A
                  connector can only be attached to one encoder at a time. The
                  connector is also the structure where information about the
                  attached display is kept, so it contains fields for display
                  data, <emphasis>EDID</emphasis> data,
                  <emphasis>DPMS</emphasis> and
                  <emphasis>connection status</emphasis>, and information about
                  modes supported on the attached displays.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Framebuffers</term>
          <listitem>
            <para><emphasis>Framebuffers</emphasis> are abstract memory objects
                  that provide a source of pixel data to scanout to a CRTC.
                  Applications explicitly request the creation of framebuffers
                  and can control their behavior. Framebuffers rely on the
                  underneath memory manager for low-level memory operations.
                  When creating a framebuffer, applications pass a memory handle
                  through the API which is used as backing storage. The
                  framebuffer itself is only an abstract object with no data. It
                  just refers to memory buffers that must be created with the
                  <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                  API.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>

    <refsect2>
      <title>Mode-Setting</title>
      <para>Before mode-setting can be performed, an application needs to call
            <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            to become <emphasis>DRM-Master</emphasis>. It then has exclusive
            access to the KMS API. A call to
            <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            returns a list of <emphasis>CRTCs</emphasis>,
            <emphasis>Connectors</emphasis>, <emphasis>Encoders</emphasis> and
            <emphasis>Planes</emphasis>.</para>

      <para>Normal procedure now includes: First, you select which connectors
            you want to use. Users are mostly interested in which monitor or
            display-panel is active so you need to make sure to arrange them in
            the correct logical order and select the correct ones to use. For
            each connector, you need to find a CRTC to drive this connector. If
            you want to clone output to two or more connectors, you may use a
            single CRTC for all cloned connectors (if the hardware supports
            this). To find a suitable CRTC, you need to iterate over the list of
            encoders that are available for each connector. Each encoder
            contains a list of CRTCs that it can work with and you simply select
            one of these CRTCs. If you later program the CRTC to control a
            connector, it automatically selects the best encoder. However, this
            procedure is needed so your CRTC has at least one working encoder
            for the selected connector. See the <emphasis>Examples</emphasis>
            section below for more information.</para>

      <para>All valid modes for a connector can be retrieved with a call to
            <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            You need to select the mode you want to use and save it. The first
            mode in the list is the default mode with the highest resolution
            possible and often a suitable choice.</para>

      <para>After you have a working connector+CRTC+mode combination, you need
            to create a framebuffer that is used for scanout. Memory buffer
            allocation is driver-depedent and described in
            <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
            You need to create a buffer big enough for your selected mode. Now
            you can create a framebuffer object that uses your memory-buffer as
            scanout buffer. You can do this with
            <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            and
            <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

      <para>As a last step, you want to program your CRTC to drive your selected
            connector. You can do this with a call to
            <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
    </refsect2>

    <refsect2>
      <title>Page-Flipping</title>
      <para>A call to
            <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            is executed immediately and forces the CRTC to use the new scanout
            buffer. If you want smooth-transitions without tearing, you probably
            use double-buffering. You need to create one framebuffer object for
            each buffer you use. You can then call
            <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            on the next buffer to flip. If you want to synchronize your flips
            with <emphasis>vertical-blanks</emphasis>, you can use
            <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            which schedules your page-flip for the next
            <emphasis>vblank</emphasis>.</para>
    </refsect2>

    <refsect2>
      <title>Planes</title>
      <para>Planes are controlled independently from CRTCs. That is, a call to
            <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            does not affect planes. Instead, you need to call
            <citerefentry><refentrytitle>drmModeSetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            to configure a plane. This requires the plane ID, a CRTC, a
            framebuffer and offsets into the plane-framebuffer and the
            CRTC-framebuffer. The CRTC then blends the content from the plane
            over the CRTC framebuffer buffer during scanout. As this does not
            involve any software-blending, it is way faster than traditional
            blending. However, plane resources are limited. See
            <citerefentry><refentrytitle>drmModeGetPlaneResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            for more information.</para>
    </refsect2>

    <refsect2>
      <title>Cursors</title>
      <para>Similar to planes, many hardware also supports cursors. A cursor is
            a very small buffer with an image that is blended over the CRTC
            framebuffer. You can set a different cursor for each CRTC with
            <citerefentry><refentrytitle>drmModeSetCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            and move it on the screen with
            <citerefentry><refentrytitle>drmModeMoveCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
            This allows to move the cursor on the screen without rerendering. If
            no hardware cursors are supported, you need to rerender for each
            frame the cursor is moved.</para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>Some examples of how basic mode-setting can be done. See the man-page
          of each DRM function for more information.</para>

    <refsect2>
      <title>CRTC/Encoder Selection</title>
      <para>If you retrieved all display configuration information via
            <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            as <structname>drmModeRes</structname> *<varname>res</varname>,
            selected a connector from the list in
            <varname>res</varname>-><structfield>connectors</structfield>
            and retrieved the connector-information as
            <structname>drmModeConnector</structname> *<varname>conn</varname>
            via
            <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
            then this example shows, how you can find a suitable CRTC id to
            drive this connector. This function takes a file-descriptor to the
            DRM device (see
            <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
            as <varname>fd</varname>, a pointer to the retrieved resources as
            <varname>res</varname> and a pointer to the selected connector as
            <varname>conn</varname>. It returns an integer smaller than 0 on
            failure, otherwise, a valid CRTC id is returned.</para>

<programlisting>
static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
{
	drmModeEncoder *enc;
	unsigned int i, j;

	/* iterate all encoders of this connector */
	for (i = 0; i &lt; conn->count_encoders; ++i) {
		enc = drmModeGetEncoder(fd, conn->encoders[i]);
		if (!enc) {
			/* cannot retrieve encoder, ignoring... */
			continue;
		}

		/* iterate all global CRTCs */
		for (j = 0; j &lt; res->count_crtcs; ++j) {
			/* check whether this CRTC works with the encoder */
			if (!(enc->possible_crtcs &amp; (1 &lt;&lt; j)))
				continue;


			/* Here you need to check that no other connector
			 * currently uses the CRTC with id "crtc". If you intend
			 * to drive one connector only, then you can skip this
			 * step. Otherwise, simply scan your list of configured
			 * connectors and CRTCs whether this CRTC is already
			 * used. If it is, then simply continue the search here. */
			if (res->crtcs[j] "is unused") {
				drmModeFreeEncoder(enc);
				return res->crtcs[j];
			}
		}

		drmModeFreeEncoder(enc);
	}

	/* cannot find a suitable CRTC */
	return -ENOENT;
}
</programlisting>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Reporting Bugs</title>
    <para>Bugs in this manual should be reported to
      https://gitlab.freedesktop.org/mesa/drm/-/issues</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetEncoder</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeRmFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetPlaneResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeGetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeSetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeSetCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmModeMoveCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmCheckModesettingSupported</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>
</refentry>