| 1 |
========== |
| 2 |
drm-memory |
| 3 |
========== |
| 4 |
|
| 5 |
--------------------- |
| 6 |
DRM Memory Management |
| 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 |
Description |
| 19 |
=========== |
| 20 |
|
| 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. |
| 26 |
|
| 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. |
| 31 |
|
| 32 |
Dumb-Buffers |
| 33 |
------------ |
| 34 |
|
| 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. |
| 41 |
|
| 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). |
| 49 |
|
| 50 |
The ``DRM_IOCTL_MODE_CREATE_DUMB`` ioctl takes as argument a structure of type |
| 51 |
``struct drm_mode_create_dumb``: |
| 52 |
|
| 53 |
:: |
| 54 |
|
| 55 |
struct drm_mode_create_dumb { |
| 56 |
__u32 height; |
| 57 |
__u32 width; |
| 58 |
__u32 bpp; |
| 59 |
__u32 flags; |
| 60 |
|
| 61 |
__u32 handle; |
| 62 |
__u32 pitch; |
| 63 |
__u64 size; |
| 64 |
}; |
| 65 |
|
| 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``. |
| 79 |
|
| 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``: |
| 83 |
|
| 84 |
:: |
| 85 |
|
| 86 |
struct drm_mode_map_dumb { |
| 87 |
__u32 handle; |
| 88 |
__u32 pad; |
| 89 |
|
| 90 |
__u64 offset; |
| 91 |
}; |
| 92 |
|
| 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. |
| 98 |
|
| 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``: |
| 103 |
|
| 104 |
:: |
| 105 |
|
| 106 |
struct drm_mode_destroy_dumb { |
| 107 |
__u32 handle; |
| 108 |
}; |
| 109 |
|
| 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. |
| 112 |
|
| 113 |
TTM |
| 114 |
--- |
| 115 |
|
| 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. |
| 120 |
|
| 121 |
GEM |
| 122 |
--- |
| 123 |
|
| 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. |
| 132 |
|
| 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. |
| 140 |
|
| 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``. |
| 146 |
|
| 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. |
| 151 |
|
| 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. |
| 160 |
|
| 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)). |
| 171 |
|
| 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. |
| 176 |
|
| 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``: |
| 188 |
|
| 189 |
:: |
| 190 |
|
| 191 |
struct drm_gem_flink { |
| 192 |
__u32 handle; |
| 193 |
__u32 name; |
| 194 |
}; |
| 195 |
|
| 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``: |
| 201 |
|
| 202 |
:: |
| 203 |
|
| 204 |
struct drm_gem_open { |
| 205 |
__u32 name; |
| 206 |
|
| 207 |
__u32 handle; |
| 208 |
__u32 size; |
| 209 |
}; |
| 210 |
|
| 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. |
| 215 |
|
| 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. |
| 237 |
|
| 238 |
Examples |
| 239 |
======== |
| 240 |
|
| 241 |
This section includes examples for basic memory-management tasks. |
| 242 |
|
| 243 |
Dumb-Buffers |
| 244 |
------------ |
| 245 |
|
| 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)). |
| 252 |
|
| 253 |
:: |
| 254 |
|
| 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; |
| 261 |
|
| 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. */ |
| 274 |
|
| 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 */ |
| 282 |
|
| 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() */ |
| 292 |
|
| 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 |
} |
| 299 |
|
| 300 |
/* clear the framebuffer to 0 */ |
| 301 |
memset(map, 0, creq.size); |
| 302 |
|
| 303 |
Reporting Bugs |
| 304 |
============== |
| 305 |
|
| 306 |
Bugs in this manual should be reported to |
| 307 |
https://gitlab.freedesktop.org/mesa/libdrm/-/issues |
| 308 |
|
| 309 |
See Also |
| 310 |
======== |
| 311 |
|
| 312 |
**drm**\ (7), **drm-kms**\ (7), **drm-prime**\ (7), **drmAvailable**\ (3), |
| 313 |
**drmOpen**\ (3), **drm-intel**\ (7), **drm-radeon**\ (7), **drm-nouveau**\ (7) |