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
18 drivers now provide the KMS kernel API to do this in the kernel,
19 however, many non-open-source binary drivers from different vendors
20 still do not support this. You can use drmModeSettingSupported(3) to
21 check whether your driver supports this. To understand how KMS works,
22 we need to introduce 5 objects: CRTCs, Planes, Encoders, Connectors and
23 Framebuffers.
24 CRTCs
26 A CRTC short for CRT Controller is an abstraction representing a
27 part of the chip that contains a pointer to a scanout buffer.
28 Therefore, the number of CRTCs available determines how many
29 independent scanout buffers can be active at any given time. The
30 CRTC structure contains several fields to support this: a pointer
31 to some video memory (abstracted as a frame-buffer object), a list
32 of driven connectors, a display mode and an (x, y) offset into the
33 video memory to support panning or configurations where one piece
34 of video memory spans multiple CRTCs. A CRTC is the central point
35 where configuration of displays happens. You select which objects
36 to use, which modes and which parameters and then configure each
37 CRTC via drmModeCrtcSet(3) to drive the display devices.
38 Planes
40 A plane respresents an image source that can be blended with or
41 overlayed on top of a CRTC during the scanout process. Planes are
42 associated with a frame-buffer to crop a portion of the image
43 memory (source) and optionally scale it to a destination size. The
44 result is then blended with or overlayed on top of a CRTC. Planes
45 are not provided by all hardware and the number of available planes
46 is limited. If planes are not available or if not enough planes are
47 available, the user should fall back to normal software blending
48 (via GPU or CPU).
49 Encoders
51 An encoder takes pixel data from a CRTC and converts it to a format
52 suitable for any attached connectors. On some devices, it may be
53 possible to have a CRTC send data to more than one encoder. In that
54 case, both encoders would receive data from the same scanout
55 buffer, resulting in a cloned display configuration across the
56 connectors attached to each encoder.
57 Connectors
59 A connector is the final destination of pixel-data on a device, and
60 usually connects directly to an external display device like a
61 monitor or laptop panel. A connector can only be attached to one
62 encoder at a time. The connector is also the structure where
63 information about the attached display is kept, so it contains
64 fields for display data, EDID data, DPMS and connection status, and
65 information about modes supported on the attached displays.
66 Framebuffers
68 Framebuffers are abstract memory objects that provide a source of
69 pixel data to scanout to a CRTC. Applications explicitly request
70 the creation of framebuffers and can control their behavior.
71 Framebuffers rely on the underneath memory manager for low-level
72 memory operations. When creating a framebuffer, applications pass a
73 memory handle through the API which is used as backing storage. The
74 framebuffer itself is only an abstract object with no data. It just
75 refers to memory buffers that must be created with the drm-
76 memory(7) API.
77 Mode-Setting
79 Before mode-setting can be performed, an application needs to call
80 drmSetMaster(3) to become DRM-Master. It then has exclusive access to
81 the KMS API. A call to drmModeGetResources(3) returns a list of CRTCs,
82 Connectors, Encoders and Planes.
83 Normal procedure now includes: First, you select which connectors you
85 want to use. Users are mostly interested in which monitor or
86 display-panel is active so you need to make sure to arrange them in the
87 correct logical order and select the correct ones to use. For each
88 connector, you need to find a CRTC to drive this connector. If you want
89 to clone output to two or more connectors, you may use a single CRTC
90 for all cloned connectors (if the hardware supports this). To find a
91 suitable CRTC, you need to iterate over the list of encoders that are
92 available for each connector. Each encoder contains a list of CRTCs
93 that it can work with and you simply select one of these CRTCs. If you
94 later program the CRTC to control a connector, it automatically selects
95 the best encoder. However, this procedure is needed so your CRTC has at
96 least one working encoder for the selected connector. See the Examples
97 section below for more information.
98 All valid modes for a connector can be retrieved with a call to
100 drmModeGetConnector(3) You need to select the mode you want to use and
101 save it. The first mode in the list is the default mode with the
102 highest resolution possible and often a suitable choice.
103 After you have a working connector+CRTC+mode combination, you need to
105 create a framebuffer that is used for scanout. Memory buffer allocation
106 is driver-depedent and described in drm-memory(7). You need to create a
107 buffer big enough for your selected mode. Now you can create a
108 framebuffer object that uses your memory-buffer as scanout buffer. You
109 can do this with drmModeAddFB(3) and drmModeAddFB2(3).
110 As a last step, you want to program your CRTC to drive your selected
112 connector. You can do this with a call to drmModeSetCrtc(3).
113 Page-Flipping
115 A call to drmModeSetCrtc(3) is executed immediately and forces the CRTC
116 to use the new scanout buffer. If you want smooth-transitions without
117 tearing, you probably use double-buffering. You need to create one
118 framebuffer object for each buffer you use. You can then call
119 drmModeSetCrtc(3) on the next buffer to flip. If you want to
120 synchronize your flips with vertical-blanks, you can use
121 drmModePageFlip(3) which schedules your page-flip for the next vblank.
122 Planes
124 Planes are controlled independently from CRTCs. That is, a call to
125 drmModeSetCrtc(3) does not affect planes. Instead, you need to call
126 drmModeSetPlane(3) to configure a plane. This requires the plane ID, a
127 CRTC, a framebuffer and offsets into the plane-framebuffer and the
128 CRTC-framebuffer. The CRTC then blends the content from the plane over
129 the CRTC framebuffer buffer during scanout. As this does not involve
130 any software-blending, it is way faster than traditional blending.
131 However, plane resources are limited. See drmModeGetPlaneResources(3)
132 for more information.
133 Cursors
135 Similar to planes, many hardware also supports cursors. A cursor is a
136 very small buffer with an image that is blended over the CRTC
137 framebuffer. You can set a different cursor for each CRTC with
138 drmModeSetCursor(3) and move it on the screen with
139 drmModeMoveCursor(3). This allows to move the cursor on the screen
140 without rerendering. If no hardware cursors are supported, you need to
141 rerender for each frame the cursor is moved.
142
144 Some examples of how basic mode-setting can be done. See the man-page
145 of each DRM function for more information.
146 CRTC/Encoder Selection
148 If you retrieved all display configuration information via
149 drmModeGetResources(3) as drmModeRes *res, selected a connector from
150 the list in res->connectors and retrieved the connector-information as
151 drmModeConnector *conn via drmModeGetConnector(3) then this example
152 shows, how you can find a suitable CRTC id to drive this connector.
153 This function takes a file-descriptor to the DRM device (see
154 drmOpen(3)) as fd, a pointer to the retrieved resources as res and a
155 pointer to the selected connector as conn. It returns an integer
156 smaller than 0 on failure, otherwise, a valid CRTC id is returned.
157 static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
159 {
160 drmModeEncoder *enc;
161 unsigned int i, j;
162 /* iterate all encoders of this connector */
164 for (i = 0; i < conn->count_encoders; ++i) {
165 enc = drmModeGetEncoder(fd, conn->encoders[i]);
166 if (!enc) {
167 /* cannot retrieve encoder, ignoring... */
168 continue;
169 }
170 /* iterate all global CRTCs */
172 for (j = 0; j < res->count_crtcs; ++j) {
173 /* check whether this CRTC works with the encoder */
174 if (!(enc->possible_crtcs & (1 << j)))
175 continue;
176 /* Here you need to check that no other connector
179 * currently uses the CRTC with id "crtc". If you intend
180 * to drive one connector only, then you can skip this
181 * step. Otherwise, simply scan your list of configured
182 * connectors and CRTCs whether this CRTC is already
183 * used. If it is, then simply continue the search here. */
184 if (res->crtcs[j] "is unused") {
185 drmModeFreeEncoder(enc);
186 return res->crtcs[j];
187 }
188 }
189 drmModeFreeEncoder(enc);
191 }
192 /* cannot find a suitable CRTC */
194 return -ENOENT;
195 }
196
198 Bugs in this manual should be reported to
199 https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
200 under the "DRI" product, component "libdrm"
201
203 drm(7), drm-memory(7), drmModeGetResources(3), drmModeGetConnector(3),
204 drmModeGetEncoder(3), drmModeGetCrtc(3), drmModeSetCrtc(3),
205 drmModeGetFB(3), drmModeAddFB(3), drmModeAddFB2(3), drmModeRmFB(3),
206 drmModePageFlip(3), drmModeGetPlaneResources(3), drmModeGetPlane(3),
207 drmModeSetPlane(3), drmModeSetCursor(3), drmModeMoveCursor(3),
208 drmSetMaster(3), drmAvailable(3), drmCheckModesettingSupported(3),
209 drmOpen(3)
210libdrm September 2012 DRM-KMS(7)