drm-kms - Man Page

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-dependent 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).

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 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.

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.

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;
}