1DRM-KMS(7)                 Direct Rendering Manager                 DRM-KMS(7)
2
3
4

NAME

6       drm-kms - Kernel Mode-Setting
7

SYNOPSIS

9       #include <xf86drm.h>
10
11       #include <xf86drmMode.h>
12

DESCRIPTION

14       Each  DRM  device provides access to manage which monitors and displays
15       are currently used and what frames to be displayed. This task is called
16       Kernel  Mode-Setting  (KMS).  Historically, this was done in user-space
17       and called User-space Mode-Setting (UMS). Almost all open-source  driv‐
18       ers  now  provide the KMS kernel API to do this in the kernel, however,
19       many non-open-source binary drivers from different vendors still do not
20       support  this.  You can use drmModeSettingSupported(3) to check whether
21       your driver supports this. To understand how KMS works, we need to  in‐
22       troduce  5  objects:  CRTCs,  Planes,  Encoders,  Connectors and Frame‐
23       buffers.
24
25       CRTCs  A CRTC short for CRT Controller is an abstraction representing a
26              part  of  the  chip that contains a pointer to a scanout buffer.
27              Therefore, the number of CRTCs available determines how many in‐
28              dependent  scanout  buffers can be active at any given time. The
29              CRTC structure  contains  several  fields  to  support  this:  a
30              pointer  to  some video memory (abstracted as a frame-buffer ob‐
31              ject), a list of driven connectors, a display mode and an (x, y)
32              offset  into  the  video memory to support panning or configura‐
33              tions where one piece of video memory spans  multiple  CRTCs.  A
34              CRTC  is  the central point where configuration of displays hap‐
35              pens. You select which objects to use, which modes and which pa‐
36              rameters  and  then configure each CRTC via drmModeCrtcSet(3) to
37              drive the display devices.
38
39       Planes A plane respresents an image source that can be blended with  or
40              overlayed  on  top  of a CRTC during the scanout process. Planes
41              are associated with a frame-buffer to crop a portion of the  im‐
42              age  memory  (source)  and  optionally scale it to a destination
43              size. The result is then blended with or overlayed on top  of  a
44              CRTC.  Planes are not provided by all hardware and the number of
45              available planes is limited. If planes are not available  or  if
46              not  enough  planes  are available, the user should fall back to
47              normal software blending (via GPU or CPU).
48
49       Encoders
50              An encoder takes pixel data from a CRTC and  converts  it  to  a
51              format suitable for any attached connectors. On some devices, it
52              may be possible to have a CRTC send data to more  than  one  en‐
53              coder.  In  that case, both encoders would receive data from the
54              same scanout buffer, resulting in a cloned display configuration
55              across the connectors attached to each encoder.
56
57       Connectors
58              A  connector is the final destination of pixel-data on a device,
59              and usually connects directly to an external display device like
60              a  monitor  or laptop panel. A connector can only be attached to
61              one encoder at a time. The connector is also the structure where
62              information  about  the attached display is kept, so it contains
63              fields for display data, EDID data, DPMS and connection  status,
64              and information about modes supported on the attached displays.
65
66       Framebuffers
67              Framebuffers  are  abstract memory objects that provide a source
68              of pixel data to scanout to a CRTC. Applications explicitly  re‐
69              quest  the creation of framebuffers and can control their behav‐
70              ior. Framebuffers rely on  the  underneath  memory  manager  for
71              low-level memory operations. When creating a framebuffer, appli‐
72              cations pass a memory handle through the API which  is  used  as
73              backing  storage. The framebuffer itself is only an abstract ob‐
74              ject with no data. It just refers to memory buffers that must be
75              created with the drm-memory(7) API.
76
77   Mode-Setting
78       Before mode-setting can be performed, an application needs to call drm‐
79       SetMaster(3) to become DRM-Master. It then has exclusive access to  the
80       KMS API. A call to drmModeGetResources(3) returns a list of CRTCs, Con‐
81       nectors, Encoders and Planes.
82
83       Normal procedure now includes: First, you select which  connectors  you
84       want  to  use.  Users  are  mostly  interested in which monitor or dis‐
85       play-panel is active so you need to make sure to arrange  them  in  the
86       correct logical order and select the correct ones to use. For each con‐
87       nector, you need to find a CRTC to drive this connector. If you want to
88       clone  output  to two or more connectors, you may use a single CRTC for
89       all cloned connectors (if the hardware supports this). To find a  suit‐
90       able  CRTC,  you  need  to  iterate  over the list of encoders that are
91       available for each connector. Each encoder contains  a  list  of  CRTCs
92       that  it can work with and you simply select one of these CRTCs. If you
93       later program the CRTC to control a connector, it automatically selects
94       the  best  encoder.  However, this procedure is needed so your CRTC has
95       at least one working encoder for the selected connector. See the  Exam‐
96       ples section below for more information.
97
98       All valid modes for a connector can be retrieved with a call to drmMod‐
99       eGetConnector3 You need to select the mode you want to use and save it.
100       The first mode in the list is the default mode with the highest resolu‐
101       tion possible and often a suitable choice.
102
103       After you have a working connector+CRTC+mode combination, you  need  to
104       create a framebuffer that is used for scanout. Memory buffer allocation
105       is driver-depedent and described in drm-memory(7). You need to create a
106       buffer  big  enough for your selected mode. Now you can create a frame‐
107       buffer object that uses your memory-buffer as scanout buffer.  You  can
108       do this with drmModeAddFB(3) and drmModeAddFB2(3).
109
110       As  a  last  step, you want to program your CRTC to drive your selected
111       connector.  You can do this with a call to drmModeSetCrtc(3).
112
113   Page-Flipping
114       A call to drmModeSetCrtc(3) is executed immediately and forces the CRTC
115       to  use  the new scanout buffer. If you want smooth-transitions without
116       tearing, you probably use double-buffering.  You  need  to  create  one
117       framebuffer  object for each buffer you use. You can then call drmMode‐
118       SetCrtc(3) on the next buffer to flip. If you want to synchronize  your
119       flips with vertical-blanks, you can use drmModePageFlip(3) which sched‐
120       ules your page-flip for the next vblank.
121
122   Planes
123       Planes are controlled independently from CRTCs. That is, a call to drm‐
124       ModeSetCrtc(3)  does  not affect planes. Instead, you need to call drm‐
125       ModeSetPlane(3) to configure a plane. This requires  the  plane  ID,  a
126       CRTC,  a  framebuffer  and  offsets  into the plane-framebuffer and the
127       CRTC-framebuffer. The CRTC then blends the content from the plane  over
128       the  CRTC  framebuffer  buffer during scanout. As this does not involve
129       any software-blending, it is way faster than traditional blending. How‐
130       ever,  plane resources are limited. See drmModeGetPlaneResources(3) for
131       more information.
132
133   Cursors
134       Similar to planes, many hardware also supports cursors. A cursor  is  a
135       very  small  buffer  with an image that is blended over the CRTC frame‐
136       buffer. You can set a different cursor  for  each  CRTC  with  drmMode‐
137       SetCursor(3) and move it on the screen with drmModeMoveCursor(3).  This
138       allows to move the cursor on the  screen  without  rerendering.  If  no
139       hardware cursors are supported, you need to rerender for each frame the
140       cursor is moved.
141

EXAMPLES

143       Some examples of how basic mode-setting can be done. See  the  man-page
144       of each DRM function for more information.
145
146   CRTC/Encoder Selection
147       If  you  retrieved all display configuration information via drmModeGe‐
148       tResources(3) as drmModeRes *res, selected a connector from the list in
149       res->connectors  and retrieved the connector-information as drmModeCon‐
150       nector *conn via drmModeGetConnector(3) then this  example  shows,  how
151       you  can find a suitable CRTC id to drive this connector. This function
152       takes a file-descriptor to the DRM device (see  drmOpen(3))  as  fd,  a
153       pointer to the retrieved resources as res and a pointer to the selected
154       connector as conn. It returns an integer smaller  than  0  on  failure,
155       otherwise, a valid CRTC id is returned.
156
157          static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
158          {
159              drmModeEncoder *enc;
160              unsigned int i, j;
161
162              /* iterate all encoders of this connector */
163              for (i = 0; i < conn->count_encoders; ++i) {
164                  enc = drmModeGetEncoder(fd, conn->encoders[i]);
165                  if (!enc) {
166                      /* cannot retrieve encoder, ignoring... */
167                      continue;
168                  }
169
170                  /* iterate all global CRTCs */
171                  for (j = 0; j < res->count_crtcs; ++j) {
172                      /* check whether this CRTC works with the encoder */
173                      if (!(enc->possible_crtcs & (1 << j)))
174                          continue;
175
176
177                      /* Here you need to check that no other connector
178                       * currently uses the CRTC with id "crtc". If you intend
179                       * to drive one connector only, then you can skip this
180                       * step. Otherwise, simply scan your list of configured
181                       * connectors and CRTCs whether this CRTC is already
182                       * used. If it is, then simply continue the search here. */
183                      if (res->crtcs[j] "is unused") {
184                          drmModeFreeEncoder(enc);
185                          return res->crtcs[j];
186                      }
187                  }
188
189                  drmModeFreeEncoder(enc);
190              }
191
192              /* cannot find a suitable CRTC */
193              return -ENOENT;
194          }
195

REPORTING BUGS

197       Bugs      in      this     manual     should     be     reported     to
198       https://gitlab.freedesktop.org/mesa/drm/-/issues
199

SEE ALSO

201       drm(7), drm-memory(7), drmModeGetResources(3),  drmModeGetConnector(3),
202       drmModeGetEncoder(3),   drmModeGetCrtc(3),  drmModeSetCrtc(3),  drmMod‐
203       eGetFB(3), drmModeAddFB(3), drmModeAddFB2(3), drmModeRmFB(3),  drmMode‐
204       PageFlip(3),  drmModeGetPlaneResources(3), drmModeGetPlane(3), drmMode‐
205       SetPlane(3),  drmModeSetCursor(3),   drmModeMoveCursor(3),   drmSetMas‐
206       ter(3), drmAvailable(3), drmCheckModesettingSupported(3), drmOpen(3)
207
208
209
210
211                                September 2012                      DRM-KMS(7)
Impressum