Debian Codegraph @

man/drm-kms.7.rst

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