Sync headers with drm-next
[drm/libdrm.git] / man / drm-memory.7.rst
blob7d09eeb14e439fdd58b6d561a651652868249437
1 ==========
2 drm-memory
3 ==========
5 ---------------------
6 DRM Memory Management
7 ---------------------
9 :Date: September 2012
10 :Manual section: 7
11 :Manual group: Direct Rendering Manager
13 Synopsis
14 ========
16 ``#include <xf86drm.h>``
18 Description
19 ===========
21 Many modern high-end GPUs come with their own memory managers. They even
22 include several different caches that need to be synchronized during access.
23 Textures, framebuffers, command buffers and more need to be stored in memory
24 that can be accessed quickly by the GPU. Therefore, memory management on GPUs
25 is highly driver- and hardware-dependent.
27 However, there are several frameworks in the kernel that are used by more than
28 one driver. These can be used for trivial mode-setting without requiring
29 driver-dependent code. But for hardware-accelerated rendering you need to read
30 the manual pages for the driver you want to work with.
32 Dumb-Buffers
33 ------------
35 Almost all in-kernel DRM hardware drivers support an API called *Dumb-Buffers*.
36 This API allows to create buffers of arbitrary size that can be used for
37 scanout. These buffers can be memory mapped via **mmap**\ (2) so you can render
38 into them on the CPU. However, GPU access to these buffers is often not
39 possible. Therefore, they are fine for simple tasks but not suitable for
40 complex compositions and renderings.
42 The ``DRM_IOCTL_MODE_CREATE_DUMB`` ioctl can be used to create a dumb buffer.
43 The kernel will return a 32-bit handle that can be used to manage the buffer
44 with the DRM API. You can create framebuffers with **drmModeAddFB**\ (3) and
45 use it for mode-setting and scanout. To access the buffer, you first need to
46 retrieve the offset of the buffer. The ``DRM_IOCTL_MODE_MAP_DUMB`` ioctl
47 requests the DRM subsystem to prepare the buffer for memory-mapping and returns
48 a fake-offset that can be used with **mmap**\ (2).
50 The ``DRM_IOCTL_MODE_CREATE_DUMB`` ioctl takes as argument a structure of type
51 ``struct drm_mode_create_dumb``:
55    struct drm_mode_create_dumb {
56        __u32 height;
57        __u32 width;
58        __u32 bpp;
59        __u32 flags;
61        __u32 handle;
62        __u32 pitch;
63        __u64 size;
64    };
66 The fields *height*, *width*, *bpp* and *flags* have to be provided by the
67 caller. The other fields are filled by the kernel with the return values.
68 *height* and *width* are the dimensions of the rectangular buffer that is
69 created. *bpp* is the number of bits-per-pixel and must be a multiple of 8. You
70 most commonly want to pass 32 here. The flags field is currently unused and
71 must be zeroed. Different flags to modify the behavior may be added in the
72 future. After calling the ioctl, the handle, pitch and size fields are filled
73 by the kernel. *handle* is a 32-bit gem handle that identifies the buffer. This
74 is used by several other calls that take a gem-handle or memory-buffer as
75 argument. The *pitch* field is the pitch (or stride) of the new buffer. Most
76 drivers use 32-bit or 64-bit aligned stride-values. The size field contains the
77 absolute size in bytes of the buffer. This can normally also be computed with
78 ``(height * pitch + width) * bpp / 4``.
80 To prepare the buffer for **mmap**\ (2) you need to use the
81 ``DRM_IOCTL_MODE_MAP_DUMB`` ioctl. It takes as argument a structure of type
82 ``struct drm_mode_map_dumb``:
86    struct drm_mode_map_dumb {
87        __u32 handle;
88        __u32 pad;
90        __u64 offset;
91    };
93 You need to put the gem-handle that was previously retrieved via
94 ``DRM_IOCTL_MODE_CREATE_DUMB`` into the *handle* field. The *pad* field is
95 unused padding and must be zeroed. After completion, the *offset* field will
96 contain an offset that can be used with **mmap**\ (2) on the DRM
97 file-descriptor.
99 If you don't need your dumb-buffer, anymore, you have to destroy it with
100 ``DRM_IOCTL_MODE_DESTROY_DUMB``. If you close the DRM file-descriptor, all open
101 dumb-buffers are automatically destroyed. This ioctl takes as argument a
102 structure of type ``struct drm_mode_destroy_dumb``:
106    struct drm_mode_destroy_dumb {
107        __u32 handle;
108    };
110 You only need to put your handle into the *handle* field. After this call, the
111 handle is invalid and may be reused for new buffers by the dumb-API.
116 *TTM* stands for *Translation Table Manager* and is a generic memory-manager
117 provided by the kernel. It does not provide a common user-space API so you need
118 to look at each driver interface if you want to use it. See for instance the
119 radeon man pages for more information on memory-management with radeon and TTM.
124 *GEM* stands for *Graphics Execution Manager* and is a generic DRM
125 memory-management framework in the kernel, that is used by many different
126 drivers. GEM is designed to manage graphics memory, control access to the
127 graphics device execution context and handle essentially NUMA environment
128 unique to modern graphics hardware. GEM allows multiple applications to share
129 graphics device resources without the need to constantly reload the entire
130 graphics card. Data may be shared between multiple applications with gem
131 ensuring that the correct memory synchronization occurs.
133 GEM provides simple mechanisms to manage graphics data and control execution
134 flow within the linux DRM subsystem. However, GEM is not a complete framework
135 that is fully driver independent. Instead, if provides many functions that are
136 shared between many drivers, but each driver has to implement most of
137 memory-management with driver-dependent ioctls. This manpage tries to describe
138 the semantics (and if it applies, the syntax) that is shared between all
139 drivers that use GEM.
141 All GEM APIs are defined as **ioctl**\ (2) on the DRM file descriptor. An
142 application must be authorized via **drmAuthMagic**\ (3) to the current
143 DRM-Master to access the GEM subsystem. A driver that does not support GEM will
144 return ``ENODEV`` for all these ioctls. Invalid object handles return
145 ``EINVAL`` and invalid object names return ``ENOENT``.
147 Gem provides explicit memory management primitives. System pages are allocated
148 when the object is created, either as the fundamental storage for hardware
149 where system memory is used by the graphics processor directly, or as backing
150 store for graphics-processor resident memory.
152 Objects are referenced from user-space using handles. These are, for all
153 intents and purposes, equivalent to file descriptors but avoid the overhead.
154 Newer kernel drivers also support the **drm-prime** (7) infrastructure which
155 can return real file-descriptor for GEM-handles using the linux DMA-BUF API.
156 Objects may be published with a name so that other applications and processes
157 can access them. The name remains valid as long as the object exists.
158 GEM-objects are reference counted in the kernel. The object is only destroyed
159 when all handles from user-space were closed.
161 GEM-buffers cannot be created with a generic API. Each driver provides its own
162 API to create GEM-buffers. See for example ``DRM_I915_GEM_CREATE``,
163 ``DRM_NOUVEAU_GEM_NEW`` or ``DRM_RADEON_GEM_CREATE``. Each of these ioctls
164 returns a GEM-handle that can be passed to different generic ioctls. The
165 *libgbm* library from the *mesa3D* distribution tries to provide a
166 driver-independent API to create GBM buffers and retrieve a GBM-handle to them.
167 It allows to create buffers for different use-cases including scanout,
168 rendering, cursors and CPU-access. See the libgbm library for more information
169 or look at the driver-dependent man-pages (for example **drm-intel**\ (7) or
170 **drm-radeon**\ (7)).
172 GEM-buffers can be closed with **drmCloseBufferHandle**\ (3). It takes as
173 argument the GEM-handle to be closed. After this call the GEM handle cannot be
174 used by this process anymore and may be reused for new GEM objects by the GEM
175 API.
177 If you want to share GEM-objects between different processes, you can create a
178 name for them and pass this name to other processes which can then open this
179 GEM-object. Names are currently 32-bit integer IDs and have no special
180 protection. That is, if you put a name on your GEM-object, every other client
181 that has access to the DRM device and is authenticated via
182 **drmAuthMagic**\ (3) to the current DRM-Master, can *guess* the name and open
183 or access the GEM-object. If you want more fine-grained access control, you can
184 use the new **drm-prime**\ (7) API to retrieve file-descriptors for
185 GEM-handles. To create a name for a GEM-handle, you use the
186 ``DRM_IOCTL_GEM_FLINK`` ioctl. It takes as argument a structure of type
187 ``struct drm_gem_flink``:
191    struct drm_gem_flink {
192        __u32 handle;
193        __u32 name;
194    };
196 You have to put your handle into the *handle* field. After completion, the
197 kernel has put the new unique name into the name field. You can now pass
198 this name to other processes which can then import the name with the
199 ``DRM_IOCTL_GEM_OPEN`` ioctl. It takes as argument a structure of type
200 ``struct drm_gem_open``:
204    struct drm_gem_open {
205        __u32 name;
207        __u32 handle;
208        __u32 size;
209    };
211 You have to fill in the *name* field with the name of the GEM-object that you
212 want to open. The kernel will fill in the *handle* and *size* fields with the
213 new handle and size of the GEM-object. You can now access the GEM-object via
214 the handle as if you created it with the GEM API.
216 Besides generic buffer management, the GEM API does not provide any generic
217 access. Each driver implements its own functionality on top of this API. This
218 includes execution-buffers, GTT management, context creation, CPU access, GPU
219 I/O and more. The next higher-level API is *OpenGL*. So if you want to use more
220 GPU features, you should use the *mesa3D* library to create OpenGL contexts on
221 DRM devices. This does *not* require any windowing-system like X11, but can
222 also be done on raw DRM devices. However, this is beyond the scope of this
223 man-page. You may have a look at other mesa3D man pages, including libgbm and
224 libEGL. 2D software-rendering (rendering with the CPU) can be achieved with the
225 dumb-buffer-API in a driver-independent fashion, however, for
226 hardware-accelerated 2D or 3D rendering you must use OpenGL. Any other API that
227 tries to abstract the driver-internals to access GEM-execution-buffers and
228 other GPU internals, would simply reinvent OpenGL so it is not provided. But if
229 you need more detailed information for a specific driver, you may have a look
230 into the driver-manpages, including **drm-intel**\ (7), **drm-radeon**\ (7) and
231 **drm-nouveau**\ (7). However, the **drm-prime**\ (7) infrastructure and the
232 generic GEM API as described here allow display-managers to handle
233 graphics-buffers and render-clients without any deeper knowledge of the GPU
234 that is used. Moreover, it allows to move objects between GPUs and implement
235 complex display-servers that don't do any rendering on their own. See its
236 man-page for more information.
238 Examples
239 ========
241 This section includes examples for basic memory-management tasks.
243 Dumb-Buffers
244 ------------
246 This examples shows how to create a dumb-buffer via the generic DRM API.
247 This is driver-independent (as long as the driver supports dumb-buffers)
248 and provides memory-mapped buffers that can be used for scanout. This
249 example creates a full-HD 1920x1080 buffer with 32 bits-per-pixel and a
250 color-depth of 24 bits. The buffer is then bound to a framebuffer which
251 can be used for scanout with the KMS API (see **drm-kms**\ (7)).
255    struct drm_mode_create_dumb creq;
256    struct drm_mode_destroy_dumb dreq;
257    struct drm_mode_map_dumb mreq;
258    uint32_t fb;
259    int ret;
260    void *map;
262    /* create dumb buffer */
263    memset(&creq, 0, sizeof(creq));
264    creq.width = 1920;
265    creq.height = 1080;
266    creq.bpp = 32;
267    ret = drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &creq);
268    if (ret < 0) {
269        /* buffer creation failed; see "errno" for more error codes */
270        ...
271    }
272    /* creq.pitch, creq.handle and creq.size are filled by this ioctl with
273     * the requested values and can be used now. */
275    /* create framebuffer object for the dumb-buffer */
276    ret = drmModeAddFB(fd, 1920, 1080, 24, 32, creq.pitch, creq.handle, &fb);
277    if (ret) {
278        /* frame buffer creation failed; see "errno" */
279        ...
280    }
281    /* the framebuffer "fb" can now used for scanout with KMS */
283    /* prepare buffer for memory mapping */
284    memset(&mreq, 0, sizeof(mreq));
285    mreq.handle = creq.handle;
286    ret = drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &mreq);
287    if (ret) {
288        /* DRM buffer preparation failed; see "errno" */
289        ...
290    }
291    /* mreq.offset now contains the new offset that can be used with mmap() */
293    /* perform actual memory mapping */
294    map = mmap(0, creq.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, mreq.offset);
295    if (map == MAP_FAILED) {
296        /* memory-mapping failed; see "errno" */
297        ...
298    }
300    /* clear the framebuffer to 0 */
301    memset(map, 0, creq.size);
303 Reporting Bugs
304 ==============
306 Bugs in this manual should be reported to
307 https://gitlab.freedesktop.org/mesa/drm/-/issues
309 See Also
310 ========
312 **drm**\ (7), **drm-kms**\ (7), **drm-prime**\ (7), **drmAvailable**\ (3),
313 **drmOpen**\ (3), **drm-intel**\ (7), **drm-radeon**\ (7), **drm-nouveau**\ (7)