Provided by: libdrm-dev_2.4.101-2~18.04.1_amd64 bug

NAME

       drm-kms - Kernel Mode-Setting

SYNOPSIS

       #include <xf86drm.h>

       #include <xf86drmMode.h>

DESCRIPTION

       Each DRM device provides access to manage which monitors and displays are currently used
       and what frames to be displayed. This task is called Kernel Mode-Setting (KMS).
       Historically, this was done in user-space and called User-space Mode-Setting (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 drmModeSettingSupported(3) to check whether your driver supports this. To
       understand how KMS works, we need to introduce 5 objects: CRTCs, Planes, Encoders,
       Connectors and Framebuffers.

       CRTCs
           A CRTC short for CRT Controller 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 drmModeCrtcSet(3) to drive the
           display devices.

       Planes
           A plane 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).

       Encoders
           An encoder 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 cloned display configuration across the connectors
           attached to each encoder.

       Connectors
           A connector 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, EDID data, DPMS and connection status, and information about modes supported on
           the attached displays.

       Framebuffers
           Framebuffers 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 drm-memory(7) API.

   Mode-Setting
       Before mode-setting can be performed, an application needs to call drmSetMaster(3) to
       become DRM-Master. It then has exclusive access to the KMS API. A call to
       drmModeGetResources(3) returns a list of CRTCs, Connectors, Encoders and Planes.

       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 Examples section below for more information.

       All valid modes for a connector can be retrieved with a call to drmModeGetConnector(3) 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.

       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
       drm-memory(7). 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 drmModeAddFB(3) and drmModeAddFB2(3).

       As a last step, you want to program your CRTC to drive your selected connector. You can do
       this with a call to drmModeSetCrtc(3).

   Page-Flipping
       A call to drmModeSetCrtc(3) 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 drmModeSetCrtc(3) on the next buffer to flip. If you want to synchronize
       your flips with vertical-blanks, you can use drmModePageFlip(3) which schedules your
       page-flip for the next vblank.

   Planes
       Planes are controlled independently from CRTCs. That is, a call to drmModeSetCrtc(3) does
       not affect planes. Instead, you need to call drmModeSetPlane(3) 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
       drmModeGetPlaneResources(3) for more information.

   Cursors
       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 drmModeSetCursor(3) and move it on the screen with
       drmModeMoveCursor(3). 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.

EXAMPLES

       Some examples of how basic mode-setting can be done. See the man-page of each DRM function
       for more information.

   CRTC/Encoder Selection
       If you retrieved all display configuration information via drmModeGetResources(3) as
       drmModeRes *res, selected a connector from the list in res->connectors and retrieved the
       connector-information as drmModeConnector *conn via drmModeGetConnector(3) 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 drmOpen(3)) as fd, a pointer to the
       retrieved resources as res and a pointer to the selected connector as conn. It returns an
       integer smaller than 0 on failure, otherwise, a valid CRTC id is returned.

           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 < 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 < res->count_crtcs; ++j) {
                          /* check whether this CRTC works with the encoder */
                          if (!(enc->possible_crtcs & (1 << 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;
           }

REPORTING BUGS

       Bugs in this manual should be reported to
       https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm under the "DRI"
       product, component "libdrm"

SEE ALSO

       drm(7), drm-memory(7), drmModeGetResources(3), drmModeGetConnector(3),
       drmModeGetEncoder(3), drmModeGetCrtc(3), drmModeSetCrtc(3), drmModeGetFB(3),
       drmModeAddFB(3), drmModeAddFB2(3), drmModeRmFB(3), drmModePageFlip(3),
       drmModeGetPlaneResources(3), drmModeGetPlane(3), drmModeSetPlane(3), drmModeSetCursor(3),
       drmModeMoveCursor(3), drmSetMaster(3), drmAvailable(3), drmCheckModesettingSupported(3),
       drmOpen(3)