1DRM-KMS(7) Direct Rendering Manager DRM-KMS(7)
2
6 drm-kms - Kernel Mode-Setting
7
9 #include <xf86drm.h>
10 #include <xf86drmMode.h>
12
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 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 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 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 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 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 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 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 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 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 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 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 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 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
143 Some examples of how basic mode-setting can be done. See the man-page
144 of each DRM function for more information.
145 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 static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
158 {
159 drmModeEncoder *enc;
160 unsigned int i, j;
161 /* 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 /* 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 /* 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 drmModeFreeEncoder(enc);
190 }
191 /* cannot find a suitable CRTC */
193 return -ENOENT;
194 }
195
197 Bugs in this manual should be reported to
198 https://gitlab.freedesktop.org/mesa/drm/-/issues
199
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 September 2012 DRM-KMS(7)