| Message ID | 1348411208-3943-5-git-send-email-dh.herrmann@googlemail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Son, 2012-09-23 at 16:40 +0200, David Herrmann wrote: > + > +.SS TTM > +.B TTM > +stands for > +.B Translation Table Manager > +and is another generic memory-manager provided by the kernel. Only the radeon > +driver uses it. See the radeon manpages for more information on > +memory-management with radeon and TTM. What made you think only radeon uses TTM? nouveau, vmwgfx, ast, cirrus and mgag200 also use it. I suspect the emerging openchrome KMS support does as well.
Hi Michel On Mon, Sep 24, 2012 at 9:45 AM, Michel Dänzer <michel@daenzer.net> wrote: > On Son, 2012-09-23 at 16:40 +0200, David Herrmann wrote: >> + >> +.SS TTM >> +.B TTM >> +stands for >> +.B Translation Table Manager >> +and is another generic memory-manager provided by the kernel. Only the radeon >> +driver uses it. See the radeon manpages for more information on >> +memory-management with radeon and TTM. > > What made you think only radeon uses TTM? nouveau, vmwgfx, ast, cirrus > and mgag200 also use it. I suspect the emerging openchrome KMS support > does as well. Whoops, that was my first conception, but I forgot to fix that. Anyway, I didn't know of any generic API that I could write about here either so I think I will leave the "TTM" section pretty short. Or any ideas what could be included here? Thanks for reviewing! Will be fixed in the next revision. David
On Sun, 23 Sep 2012 16:40:07 +0200 David Herrmann <dh.herrmann@googlemail.com> wrote: > The drm-memory man-page (aliased as drm-gem, drm-mm and drm-ttm) describes > the high-level overview of different memory-management frameworks used in > the DRM subsystem. It is really targeted at driver-independent semantics > (and where it applies, syntax). It links to all other man-pages if more > driver-dependent information is needed. > > Signed-off-by: David Herrmann <dh.herrmann@googlemail.com> > --- > man/Makefile.am | 4 + > man/drm-gem.7 | 1 + > man/drm-memory.7 | 412 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ > man/drm-mm.7 | 1 + > man/drm-ttm.7 | 1 + > 5 files changed, 419 insertions(+) > create mode 100644 man/drm-gem.7 > create mode 100644 man/drm-memory.7 > create mode 100644 man/drm-mm.7 > create mode 100644 man/drm-ttm.7 > > diff --git a/man/Makefile.am b/man/Makefile.am > index 7ce7ac4..ded3b4a 100644 > --- a/man/Makefile.am > +++ b/man/Makefile.am > @@ -1,6 +1,10 @@ > man_MANS = \ > drm.7 \ > drm-kms.7 \ > + drm-memory.7 \ > + drm-mm.7 \ > + drm-gem.7 \ > + drm-ttm.7 \ > drmAvailable.3 \ > drmHandleEvent.3 \ > drmModeGetResources.3 > diff --git a/man/drm-gem.7 b/man/drm-gem.7 > new file mode 100644 > index 0000000..258b5a3 > --- /dev/null > +++ b/man/drm-gem.7 > @@ -0,0 +1 @@ > +.so man7/drm-memory.7 > diff --git a/man/drm-memory.7 b/man/drm-memory.7 > new file mode 100644 > index 0000000..1eff38a > --- /dev/null > +++ b/man/drm-memory.7 > @@ -0,0 +1,412 @@ > +.\" > +.\" Written 2012 by David Herrmann > +.\" Dedicated to the Public Domain > +.\" > +.TH "DRM-MEMORY" 7 "September 2012" "libdrm" "Direct Rendering Manager" > +.SH NAME > +DRM-Memory \- DRM Memory Management > + > +.SH SYNOPSIS > +.B #include <xf86drm.h> > + > +.SH DESCRIPTION > +Many modern high-end GPUs come with their own memory managers. They even include > +several different caches that need to be synchronized during access. Textures, > +framebuffers, command buffers and more need to be stored in memory that can be > +accessed quickly by the GPU. Therefore, memory management on GPUs is highly > +driver\- and hardware\-dependent. > + > +However, there are several frameworks in the kernel that are used by more than > +one driver. These can be used for trivial mode-setting without requiring > +driver-dependent code. But for hardware-accelerated rendering you need to read > +the manual pages for the driver you want to work with. > + > +.SS Dumb-Buffers > +Almost all in-kernel DRM hardware drivers support an API called > +.BR "Dumb-Buffers" "." > +This API allows to create buffers of arbitrary size that can be used for > +scanout. These buffers can be memory mapped via > +.BR mmap (2) > +so you can render into them on the CPU. However, GPU access to these buffers is > +often not possible. Therefore, they are fine for simple tasks but not suitable > +for complex compositions and renderings. > + > +The > +.B DRM_IOCTL_MODE_CREATE_DUMB > +ioctl can be used to create a dumb buffer. The kernel will return a 32bit handle > +that can be used to manage the buffer with the DRM API. You can create > +framebuffers with > +.BR drmModeAddFB (3) > +and use it for mode-setting and scanout. > +.br > +To access the buffer, you first need to retrieve the offset of the buffer. The > +.B DRM_IOCTL_MODE_MAP_DUMB > +ioctl requests the DRM subsystem to prepare the buffer for memory-mapping and > +returns a fake-offset that can be used with > +.BR mmap "(2)." > + > +The > +.B DRM_IOCTL_MODE_CREATE_DUMB > +ioctl takes as argument a structure of type > +.IR "struct drm_mode_create_dumb" : > + > +.in +4n > +.nf > +struct drm_mode_create_dumb { > + __u32 height; > + __u32 width; > + __u32 bpp; > + __u32 flags; > + > + __u32 handle; > + __u32 pitch; > + __u64 size; > +}; > +.fi > +.in > + > +The fields > +.IR "height" ", " "width" ", " "bpp" " and " "flags" > +have to be provided by the caller. The other fields are filled by the kernel > +with the return values. > +.IR "height" " and " "width" > +are the dimensions of the rectangular buffer that is created. > +.I "bpp" > +is the number of bits-per-pixel and must be a multiple of > +.IR 8 "." > +You most commonly want to pass > +.I 32 > +here. The > +.I "flags" > +field is currently unused and must be zeroed. Different flags to modify the > +behavior may be added in the future. > +.br > +After calling the ioctl, the > +.IR "handle" ", " "pitch" " and " "size" > +fields are filled by the kernel. > +.I "handle" > +is a 32bit gem handle that identifies the buffer. This is used by several other > +calls that take a gem-handle or memory-buffer as argument. The > +.I "pitch" > +field is the > +.IR pitch " or " stride > +of the new buffer. Most drivers use 32bit or 64bit aligned stride-values. The > +.I "size" > +field contains the absolute size in bytes of the buffer. This can normally also > +be computed with > +"(height * pitch + width) * bpp / 4". > + > +To prepare the buffer for > +.BR mmap (2) > +you need to use the > +.B DRM_IOCTL_MODE_MAP_DUMB > +ioctl. It takes as argument a structure of type > +.IR "struct drm_mode_map_dumb" : > + > +.in +4n > +.nf > +struct drm_mode_map_dumb { > + __u32 handle; > + __u32 pad; > + > + __u64 offset; > +}; > +.fi > +.in > + > +You need to put the gem-handle that was previously retrieved via > +.B DRM_IOCTL_MODE_CREATE_DUMB > +into the > +.I "handle" > +field. The > +.I "pad" > +field is unused padding and must be zeroed. After completion, the > +.I offset > +field will contain an offset that can be used with > +.BR mmap (2) > +on the DRM file-descriptor. > + > +If you don't need your dumb-buffer, anymore, you have to destroy it with > +.BR DRM_IOCTL_MODE_DESTROY_DUMB "." > +If you close the DRM file-descriptor, all open dumb-buffers are automatically > +destroyed. > +.br > +This ioctl takes as argument a structure of type > +.IR "struct drm_mode_destroy_dumb" : > + > +.in +4n > +.nf > +struct drm_mode_destroy_dumb { > + __u32 handle; > +}; > +.fi > +.in > + > +You only need to put your handle into the > +.I handle > +field. After this call, the handle is invalid and may be reused for new buffers > +by the dumb-API. > + > +.SS TTM > +.B TTM > +stands for > +.B Translation Table Manager > +and is another generic memory-manager provided by the kernel. Only the radeon > +driver uses it. See the radeon manpages for more information on > +memory-management with radeon and TTM. > + > +.SS GEM > +.B GEM > +stands for > +.B Graphics Execution Manager > +and is a generic DRM memory-management framework in the kernel, that is used by > +many different drivers. Gem is designed to manage graphics memory, control > +access to the graphics device execution context and handle essentially NUMA > +environment unique to modern graphics hardware. Gem allows multiple applications > +to share graphics device resources without the need to constantly reload the > +entire graphics card. Data may be shared between multiple applications with gem > +ensuring that the correct memory synchronization occurs. > + > +Gem provides simple mechanisms to manage graphics data and control execution > +flow within the linux DRM subsystem. However, gem is not a complete framework > +that is fully driver independent. Instead, if provides many functions that are > +shared between many drivers, but each driver has to implement most of > +memory-management with driver-dependent ioctls. This manpage tries to describe > +the semantics (and if it applies, the syntax) that is shared between all drivers > +that use gem. > + > +All GEM APIs are defined as > +.BR ioctl (2) > +on the DRM file descriptor. An application must be authorized via > +.BR drmAuthMagic (2) > +to the current DRM-Master to access the GEM subsystem. A driver that does not > +support gem will return > +.I ENODEV > +for all these ioctls. Invalid object handles return > +.I EINVAL > +and invalid object names return > +.IR ENOENT "." > + > +Gem provides explicit memory management primitives. System pages are allocated > +when the object is created, either as the fundamental storage for hardware where > +system memory is used by the graphics processor directly, or as backing store > +for graphics-processor resident memory. > + > +Objects are referenced from user-space using handles. These are, for all intents > +and purposes, equivalent to file descriptors but avoid the overhead. Newer > +kernel drivers also support the > +.BR drm-prime (7) > +infrastructure which can return real file-descriptor for gem-handles using the > +linux dma-buf API. > +.br > +Objects may be published with a name so that other applications and processes > +can access them. The name remains valid as long as the object exists. > +.br > +Gem-objects are reference counted in the kernel. The object is only destroyed > +when all handles from user-space were closed. > + > +Gem-buffers cannot be created with a generic API. Each driver provides its own > +API to create gem-buffers. See for example > +.BR DRM_I915_GEM_CREATE ", " DRM_NOUVEAU_GEM_NEW " or " DRM_RADEON_GEM_CREATE . > +Each of these ioctls returns a gem-handle that can be passed to different > +generic ioctls. > +.br > +The > +.I libgbm > +library from the > +.I mesa3D > +distribution tries to provide a driver-independent API to create gbm buffers and > +retrieve a gbm-handle to them. It allows to create buffers for different > +use-cases including scanout, rendering, cursors and CPU-access. See the libgbm > +library for more information or look at the driver-dependent man-pages > +.RI "(for example " drm-intel "(7) or " drm-radeon "(7))." > + > +Gem-buffers can be closed with the > +.B DRM_IOCTL_GEM_CLOSE > +ioctl. It takes as argument a structure of type > +.IR "struct drm_gem_close" : > + > +.in +4n > +.nf > +struct drm_gem_close { > + __u32 handle; > + __u32 pad; > +}; > +.fi > +.in > + > +The > +.I handle > +field is the gem-handle to be closed. The > +.I pad > +field is unused padding. It must be zeroed. After this call the gem handle > +cannot be used by this process anymore and may be reused for new gem objects by > +the gem API. > + > +If you want to share gem-objects between different processes, you can create a > +name for them and pass this name to other processes which can then open this > +gem-object. Names are currently 32bit integer IDs and have no special > +protection. That is, if you put a name on your gem-object, every other client > +that has access to the DRM device and is authenticated via > +.BR drmAuthMagic (3) > +to the current DRM-Master, can > +.I guess > +the name and open or access the gem-object. If you want more fine-grained access > +control, you can use the new > +.BR drm-prime (7) > +API to retrieve file-descriptors for gem-handles. > +.br > +To create a name for a gem-handle, you use the > +.B DRM_IOCTL_GEM_FLINK > +ioctl. It takes as argument a structure of type > +.IR "struct drm_gem_flink" : > + > +.in +4n > +.nf > +struct drm_gem_flink { > + __u32 handle; > + __u32 name; > +}; > +.fi > +.in > + > +You have to put your handle into the > +.I handle > +field. After completion, the kernel has put the new unique name into the > +.I name > +field. You can now pass this name to other processes which can then import the > +name with the > +.B DRM_IOCTL_GEM_OPEN > +ioctl. It takes as argument a structure of type > +.IR "struct drm_gem_open" : > + > +.in +4n > +.nf > +struct drm_gem_open { > + __u32 name; > + > + __u32 handle; > + __u32 size; > +}; > +.fi > +.in > + > +You have to fill in the > +.I name > +field with the name of the gem-object that you want to open. The kernel will > +fill in the > +.I handle > +and > +.I size > +fields with the new handle and size of the gem-object. You can now access the > +gem-object via the handle as if you created it with the gem API. > + > +Besides generic buffer management, the GEM API does not provide any generic > +access. Each driver implements its own functionality on top of this API. This > +includes execution-buffers, GTT management, context creation, CPU access, GPU > +I/O and more. > +.br > +The next higher-level API is > +.BR OpenGL . > +So if you want to use more GPU features, you should use the > +.I mesa3D > +library to create OpenGL contexts on DRM devices. This does > +.I not > +require any windowing-system like X11, but can also be done on raw DRM devices. > +However, this is beyond the scope of this man-page. You may have a look at other > +mesa3D manpages, including libgbm and libEGL. > +2D software-rendering (rendering with the CPU) can be achieved with the > +dumb-buffer-API in a driver-independent fashion, however, for > +hardware-accelerated 2D or 3D rendering you must use OpenGL. Any other API that > +tries to abstract the driver-internals to access GEM-execution-buffers and other > +GPU internals, would simply reinvent OpenGL so it is not provided. But if you > +need more detailed information for a specific driver, you may have a look into > +the driver-manpages, including > +.BR drm-intel "(7), " drm-radeon "(7) and " drm-nouveau (7). > +.br > +However, the > +.BR drm-prime (7) > +infrastructure and the generic gem API as described here allow display-managers > +to handle graphics-buffers and render-clients without any deeper knowledge of > +the GPU that is used. Moreover, it allows to move objects between GPUs and > +implement complex display-servers that don't do any rendering on their own. See > +its man-page for more information. > + > +.SH EXAMPLES > +This section includes examples for basic memory-management tasks. > + > +.SS Dumb-Buffers > +This examples shows how to create a dumb-buffer via the generic DRM API. This is > +driver-independent (as long as the driver supports dumb-buffers) and provides > +memory-mapped buffers that can be used for scanout. > +.br > +This example creates a full-HD 1920x1080 buffer with 32 bits-per-pixel and a > +color-depth of 24 bits. The buffer is then bound to a framebuffer which can be > +used for scanout with the KMS API > +.RB "(see " drm-kms "(7))." > + > +.in +4n > +.nf > + struct drm_mode_create_dumb creq; > + struct drm_mode_destroy_dumb dreq; > + struct drm_mode_map_dumb mreq; > + uint32_t fb; > + int ret; > + void *map; > + > + /* create dumb buffer */ > + memset(&creq, 0, sizeof(creq)); > + creq.width = 1920; > + creq.height = 1080; > + creq.bpp = 32; > + ret = drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &creq); > + if (ret < 0) { > + /* buffer creation failed; see "errno" for more error codes */ > + ... > + } > + /* creq.pitch, creq.handle and creq.size are filled by this ioctl with > + * the requested values and can be used now. */ > + > + /* create framebuffer object for the dumb-buffer */ > + ret = drmModeAddFB(fd, 1920, 1080, 24, 32, creq.pitch, creq.handle, &fb); > + if (ret) { > + /* frame buffer creation failed; see "errno" */ > + ... > + } > + /* the framebuffer "fb" can now used for scanout with KMS */ > + > + /* prepare buffer for memory mapping */ > + memset(&mreq, 0, sizeof(mreq)); > + mreq.handle = creq.handle; > + ret = drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &mreq); > + if (ret) { > + /* DRM buffer preparation failed; see "errno" */ > + ... > + } > + /* mreq.offset now contains the new offset that can be used with mmap() */ > + > + /* perform actual memory mapping */ > + map = mmap(0, creq.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, mreq.offset); > + if (map == MAP_FAILED) { > + /* memory-mapping failed; see "errno" */ > + ... > + } > + > + /* clear the framebuffer to 0 */ > + memset(map, 0, creq.size); > +.fi > +.in > + > +.SH REPORTING BUGS > +Bugs in this manual should be reported to http://bugs.freedesktop.org under > +the "Mesa" product, with "Other" or "libdrm" as the component. > + > +.SH "SEE ALSO" > +.BR drm (7), > +.BR drm-kms (7), > +.BR drmAvailable (3), > +.BR drmOpen (3), > +.BR drm-intel (7), > +.BR drm-radeon (7), > +.BR drm-nouveau (7), > +.BR drm-prime (7) > diff --git a/man/drm-mm.7 b/man/drm-mm.7 > new file mode 100644 > index 0000000..258b5a3 > --- /dev/null > +++ b/man/drm-mm.7 > @@ -0,0 +1 @@ > +.so man7/drm-memory.7 > diff --git a/man/drm-ttm.7 b/man/drm-ttm.7 > new file mode 100644 > index 0000000..258b5a3 > --- /dev/null > +++ b/man/drm-ttm.7 > @@ -0,0 +1 @@ > +.so man7/drm-memory.7 Heh, this one highlights the lack of documentation we have for other libs like Mesa and libgbm. :) Reviewed-by: Jesse Barnes <jbarnes@virtuousgeek.org>
diff --git a/man/Makefile.am b/man/Makefile.am index 7ce7ac4..ded3b4a 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,6 +1,10 @@ man_MANS = \ drm.7 \ drm-kms.7 \ + drm-memory.7 \ + drm-mm.7 \ + drm-gem.7 \ + drm-ttm.7 \ drmAvailable.3 \ drmHandleEvent.3 \ drmModeGetResources.3 diff --git a/man/drm-gem.7 b/man/drm-gem.7 new file mode 100644 index 0000000..258b5a3 --- /dev/null +++ b/man/drm-gem.7 @@ -0,0 +1 @@ +.so man7/drm-memory.7 diff --git a/man/drm-memory.7 b/man/drm-memory.7 new file mode 100644 index 0000000..1eff38a --- /dev/null +++ b/man/drm-memory.7 @@ -0,0 +1,412 @@ +.\" +.\" Written 2012 by David Herrmann +.\" Dedicated to the Public Domain +.\" +.TH "DRM-MEMORY" 7 "September 2012" "libdrm" "Direct Rendering Manager" +.SH NAME +DRM-Memory \- DRM Memory Management + +.SH SYNOPSIS +.B #include <xf86drm.h> + +.SH DESCRIPTION +Many modern high-end GPUs come with their own memory managers. They even include +several different caches that need to be synchronized during access. Textures, +framebuffers, command buffers and more need to be stored in memory that can be +accessed quickly by the GPU. Therefore, memory management on GPUs is highly +driver\- and hardware\-dependent. + +However, there are several frameworks in the kernel that are used by more than +one driver. These can be used for trivial mode-setting without requiring +driver-dependent code. But for hardware-accelerated rendering you need to read +the manual pages for the driver you want to work with. + +.SS Dumb-Buffers +Almost all in-kernel DRM hardware drivers support an API called +.BR "Dumb-Buffers" "." +This API allows to create buffers of arbitrary size that can be used for +scanout. These buffers can be memory mapped via +.BR mmap (2) +so you can render into them on the CPU. However, GPU access to these buffers is +often not possible. Therefore, they are fine for simple tasks but not suitable +for complex compositions and renderings. + +The +.B DRM_IOCTL_MODE_CREATE_DUMB +ioctl can be used to create a dumb buffer. The kernel will return a 32bit handle +that can be used to manage the buffer with the DRM API. You can create +framebuffers with +.BR drmModeAddFB (3) +and use it for mode-setting and scanout. +.br +To access the buffer, you first need to retrieve the offset of the buffer. The +.B DRM_IOCTL_MODE_MAP_DUMB +ioctl requests the DRM subsystem to prepare the buffer for memory-mapping and +returns a fake-offset that can be used with +.BR mmap "(2)." + +The +.B DRM_IOCTL_MODE_CREATE_DUMB +ioctl takes as argument a structure of type +.IR "struct drm_mode_create_dumb" : + +.in +4n +.nf +struct drm_mode_create_dumb { + __u32 height; + __u32 width; + __u32 bpp; + __u32 flags; + + __u32 handle; + __u32 pitch; + __u64 size; +}; +.fi +.in + +The fields +.IR "height" ", " "width" ", " "bpp" " and " "flags" +have to be provided by the caller. The other fields are filled by the kernel +with the return values. +.IR "height" " and " "width" +are the dimensions of the rectangular buffer that is created. +.I "bpp" +is the number of bits-per-pixel and must be a multiple of +.IR 8 "." +You most commonly want to pass +.I 32 +here. The +.I "flags" +field is currently unused and must be zeroed. Different flags to modify the +behavior may be added in the future. +.br +After calling the ioctl, the +.IR "handle" ", " "pitch" " and " "size" +fields are filled by the kernel. +.I "handle" +is a 32bit gem handle that identifies the buffer. This is used by several other +calls that take a gem-handle or memory-buffer as argument. The +.I "pitch" +field is the +.IR pitch " or " stride +of the new buffer. Most drivers use 32bit or 64bit aligned stride-values. The +.I "size" +field contains the absolute size in bytes of the buffer. This can normally also +be computed with +"(height * pitch + width) * bpp / 4". + +To prepare the buffer for +.BR mmap (2) +you need to use the +.B DRM_IOCTL_MODE_MAP_DUMB +ioctl. It takes as argument a structure of type +.IR "struct drm_mode_map_dumb" : + +.in +4n +.nf +struct drm_mode_map_dumb { + __u32 handle; + __u32 pad; + + __u64 offset; +}; +.fi +.in + +You need to put the gem-handle that was previously retrieved via +.B DRM_IOCTL_MODE_CREATE_DUMB +into the +.I "handle" +field. The +.I "pad" +field is unused padding and must be zeroed. After completion, the +.I offset +field will contain an offset that can be used with +.BR mmap (2) +on the DRM file-descriptor. + +If you don't need your dumb-buffer, anymore, you have to destroy it with +.BR DRM_IOCTL_MODE_DESTROY_DUMB "." +If you close the DRM file-descriptor, all open dumb-buffers are automatically +destroyed. +.br +This ioctl takes as argument a structure of type +.IR "struct drm_mode_destroy_dumb" : + +.in +4n +.nf +struct drm_mode_destroy_dumb { + __u32 handle; +}; +.fi +.in + +You only need to put your handle into the +.I handle +field. After this call, the handle is invalid and may be reused for new buffers +by the dumb-API. + +.SS TTM +.B TTM +stands for +.B Translation Table Manager +and is another generic memory-manager provided by the kernel. Only the radeon +driver uses it. See the radeon manpages for more information on +memory-management with radeon and TTM. + +.SS GEM +.B GEM +stands for +.B Graphics Execution Manager +and is a generic DRM memory-management framework in the kernel, that is used by +many different drivers. Gem is designed to manage graphics memory, control +access to the graphics device execution context and handle essentially NUMA +environment unique to modern graphics hardware. Gem allows multiple applications +to share graphics device resources without the need to constantly reload the +entire graphics card. Data may be shared between multiple applications with gem +ensuring that the correct memory synchronization occurs. + +Gem provides simple mechanisms to manage graphics data and control execution +flow within the linux DRM subsystem. However, gem is not a complete framework +that is fully driver independent. Instead, if provides many functions that are +shared between many drivers, but each driver has to implement most of +memory-management with driver-dependent ioctls. This manpage tries to describe +the semantics (and if it applies, the syntax) that is shared between all drivers +that use gem. + +All GEM APIs are defined as +.BR ioctl (2) +on the DRM file descriptor. An application must be authorized via +.BR drmAuthMagic (2) +to the current DRM-Master to access the GEM subsystem. A driver that does not +support gem will return +.I ENODEV +for all these ioctls. Invalid object handles return +.I EINVAL +and invalid object names return +.IR ENOENT "." + +Gem provides explicit memory management primitives. System pages are allocated +when the object is created, either as the fundamental storage for hardware where +system memory is used by the graphics processor directly, or as backing store +for graphics-processor resident memory. + +Objects are referenced from user-space using handles. These are, for all intents +and purposes, equivalent to file descriptors but avoid the overhead. Newer +kernel drivers also support the +.BR drm-prime (7) +infrastructure which can return real file-descriptor for gem-handles using the +linux dma-buf API. +.br +Objects may be published with a name so that other applications and processes +can access them. The name remains valid as long as the object exists. +.br +Gem-objects are reference counted in the kernel. The object is only destroyed +when all handles from user-space were closed. + +Gem-buffers cannot be created with a generic API. Each driver provides its own +API to create gem-buffers. See for example +.BR DRM_I915_GEM_CREATE ", " DRM_NOUVEAU_GEM_NEW " or " DRM_RADEON_GEM_CREATE . +Each of these ioctls returns a gem-handle that can be passed to different +generic ioctls. +.br +The +.I libgbm +library from the +.I mesa3D +distribution tries to provide a driver-independent API to create gbm buffers and +retrieve a gbm-handle to them. It allows to create buffers for different +use-cases including scanout, rendering, cursors and CPU-access. See the libgbm +library for more information or look at the driver-dependent man-pages +.RI "(for example " drm-intel "(7) or " drm-radeon "(7))." + +Gem-buffers can be closed with the +.B DRM_IOCTL_GEM_CLOSE +ioctl. It takes as argument a structure of type +.IR "struct drm_gem_close" : + +.in +4n +.nf +struct drm_gem_close { + __u32 handle; + __u32 pad; +}; +.fi +.in + +The +.I handle +field is the gem-handle to be closed. The +.I pad +field is unused padding. It must be zeroed. After this call the gem handle +cannot be used by this process anymore and may be reused for new gem objects by +the gem API. + +If you want to share gem-objects between different processes, you can create a +name for them and pass this name to other processes which can then open this +gem-object. Names are currently 32bit integer IDs and have no special +protection. That is, if you put a name on your gem-object, every other client +that has access to the DRM device and is authenticated via +.BR drmAuthMagic (3) +to the current DRM-Master, can +.I guess +the name and open or access the gem-object. If you want more fine-grained access +control, you can use the new +.BR drm-prime (7) +API to retrieve file-descriptors for gem-handles. +.br +To create a name for a gem-handle, you use the +.B DRM_IOCTL_GEM_FLINK +ioctl. It takes as argument a structure of type +.IR "struct drm_gem_flink" : + +.in +4n +.nf +struct drm_gem_flink { + __u32 handle; + __u32 name; +}; +.fi +.in + +You have to put your handle into the +.I handle +field. After completion, the kernel has put the new unique name into the +.I name +field. You can now pass this name to other processes which can then import the +name with the +.B DRM_IOCTL_GEM_OPEN +ioctl. It takes as argument a structure of type +.IR "struct drm_gem_open" : + +.in +4n +.nf +struct drm_gem_open { + __u32 name; + + __u32 handle; + __u32 size; +}; +.fi +.in + +You have to fill in the +.I name +field with the name of the gem-object that you want to open. The kernel will +fill in the +.I handle +and +.I size +fields with the new handle and size of the gem-object. You can now access the +gem-object via the handle as if you created it with the gem API. + +Besides generic buffer management, the GEM API does not provide any generic +access. Each driver implements its own functionality on top of this API. This +includes execution-buffers, GTT management, context creation, CPU access, GPU +I/O and more. +.br +The next higher-level API is +.BR OpenGL . +So if you want to use more GPU features, you should use the +.I mesa3D +library to create OpenGL contexts on DRM devices. This does +.I not +require any windowing-system like X11, but can also be done on raw DRM devices. +However, this is beyond the scope of this man-page. You may have a look at other +mesa3D manpages, including libgbm and libEGL. +2D software-rendering (rendering with the CPU) can be achieved with the +dumb-buffer-API in a driver-independent fashion, however, for +hardware-accelerated 2D or 3D rendering you must use OpenGL. Any other API that +tries to abstract the driver-internals to access GEM-execution-buffers and other +GPU internals, would simply reinvent OpenGL so it is not provided. But if you +need more detailed information for a specific driver, you may have a look into +the driver-manpages, including +.BR drm-intel "(7), " drm-radeon "(7) and " drm-nouveau (7). +.br +However, the +.BR drm-prime (7) +infrastructure and the generic gem API as described here allow display-managers +to handle graphics-buffers and render-clients without any deeper knowledge of +the GPU that is used. Moreover, it allows to move objects between GPUs and +implement complex display-servers that don't do any rendering on their own. See +its man-page for more information. + +.SH EXAMPLES +This section includes examples for basic memory-management tasks. + +.SS Dumb-Buffers +This examples shows how to create a dumb-buffer via the generic DRM API. This is +driver-independent (as long as the driver supports dumb-buffers) and provides +memory-mapped buffers that can be used for scanout. +.br +This example creates a full-HD 1920x1080 buffer with 32 bits-per-pixel and a +color-depth of 24 bits. The buffer is then bound to a framebuffer which can be +used for scanout with the KMS API +.RB "(see " drm-kms "(7))." + +.in +4n +.nf + struct drm_mode_create_dumb creq; + struct drm_mode_destroy_dumb dreq; + struct drm_mode_map_dumb mreq; + uint32_t fb; + int ret; + void *map; + + /* create dumb buffer */ + memset(&creq, 0, sizeof(creq)); + creq.width = 1920; + creq.height = 1080; + creq.bpp = 32; + ret = drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &creq); + if (ret < 0) { + /* buffer creation failed; see "errno" for more error codes */ + ... + } + /* creq.pitch, creq.handle and creq.size are filled by this ioctl with + * the requested values and can be used now. */ + + /* create framebuffer object for the dumb-buffer */ + ret = drmModeAddFB(fd, 1920, 1080, 24, 32, creq.pitch, creq.handle, &fb); + if (ret) { + /* frame buffer creation failed; see "errno" */ + ... + } + /* the framebuffer "fb" can now used for scanout with KMS */ + + /* prepare buffer for memory mapping */ + memset(&mreq, 0, sizeof(mreq)); + mreq.handle = creq.handle; + ret = drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &mreq); + if (ret) { + /* DRM buffer preparation failed; see "errno" */ + ... + } + /* mreq.offset now contains the new offset that can be used with mmap() */ + + /* perform actual memory mapping */ + map = mmap(0, creq.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, mreq.offset); + if (map == MAP_FAILED) { + /* memory-mapping failed; see "errno" */ + ... + } + + /* clear the framebuffer to 0 */ + memset(map, 0, creq.size); +.fi +.in + +.SH REPORTING BUGS +Bugs in this manual should be reported to http://bugs.freedesktop.org under +the "Mesa" product, with "Other" or "libdrm" as the component. + +.SH "SEE ALSO" +.BR drm (7), +.BR drm-kms (7), +.BR drmAvailable (3), +.BR drmOpen (3), +.BR drm-intel (7), +.BR drm-radeon (7), +.BR drm-nouveau (7), +.BR drm-prime (7) diff --git a/man/drm-mm.7 b/man/drm-mm.7 new file mode 100644 index 0000000..258b5a3 --- /dev/null +++ b/man/drm-mm.7 @@ -0,0 +1 @@ +.so man7/drm-memory.7 diff --git a/man/drm-ttm.7 b/man/drm-ttm.7 new file mode 100644 index 0000000..258b5a3 --- /dev/null +++ b/man/drm-ttm.7 @@ -0,0 +1 @@ +.so man7/drm-memory.7
The drm-memory man-page (aliased as drm-gem, drm-mm and drm-ttm) describes the high-level overview of different memory-management frameworks used in the DRM subsystem. It is really targeted at driver-independent semantics (and where it applies, syntax). It links to all other man-pages if more driver-dependent information is needed. Signed-off-by: David Herrmann <dh.herrmann@googlemail.com> --- man/Makefile.am | 4 + man/drm-gem.7 | 1 + man/drm-memory.7 | 412 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ man/drm-mm.7 | 1 + man/drm-ttm.7 | 1 + 5 files changed, 419 insertions(+) create mode 100644 man/drm-gem.7 create mode 100644 man/drm-memory.7 create mode 100644 man/drm-mm.7 create mode 100644 man/drm-ttm.7