On Sun, 23 Sep 2012 16:40:05 +0200 David Herrmann <dh.herrmann@xxxxxxxxxxxxxx> wrote: > This man-page is supposed to provide an overview of the whole DRM system. > It is targeted to users that have never worked with DRM and forwards the > reader to the correct other man-pages. > > Detailed information on each system are available in separate man-pages > which are currently under construction. > > Signed-off-by: David Herrmann <dh.herrmann@xxxxxxxxxxxxxx> > --- > man/Makefile.am | 1 + > man/drm.7 | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 100 insertions(+) > create mode 100644 man/drm.7 > > diff --git a/man/Makefile.am b/man/Makefile.am > index f003101..6193a95 100644 > --- a/man/Makefile.am > +++ b/man/Makefile.am > @@ -1,4 +1,5 @@ > man_MANS = \ > + drm.7 \ > drmAvailable.3 \ > drmHandleEvent.3 \ > drmModeGetResources.3 > diff --git a/man/drm.7 b/man/drm.7 > new file mode 100644 > index 0000000..d8d6f38 > --- /dev/null > +++ b/man/drm.7 > @@ -0,0 +1,99 @@ > +.\" > +.\" Written 2012 by David Herrmann > +.\" Dedicated to the Public Domain > +.\" > +.TH "DRM" 7 "September 2012" "libdrm" "Direct Rendering Manager" > +.SH NAME > +DRM \- Direct Rendering Manager > + > +.SH SYNOPSIS > +.B #include <xf86drm.h> > + > +.SH DESCRIPTION > +The > +.B Direct Rendering Manager > +(DRM) is a framework to manage > +.B Graphics Processing Units > +(GPUs). It is designed to support the needs of complex graphics devices, usually > +containing programmable pipelines well suited to 3D graphics acceleration. > +Furthermore, it is responsible for memory management, interrupt handling and DMA > +to provide a uniform interface to applications. > + > +In earlier days, the kernel framework was solely used to provide raw hardware > +access to priviledged user-space processes which implement all the hardware > +abstraction layers. But more and more tasks where moved into the kernel. All > +these interfaces are based on > +.BR ioctl (2) > +commands on the DRM character device. The > +.B libdrm > +library provides wrappers for these system-calls and many helpers to simplify > +the API. > + > +When a GPU is detected, the DRM system loads a driver for the detected hardware > +type. Each connected GPU is then presented to user-space via a character-device > +that is usually available as > +.I /dev/dri/card0 > +and can be accessed with > +.BR open (2) > +and > +.BR close (2). > +However, it still depends on the grapics driver which interfaces are available > +on these devices. If an interface is not available, the syscalls will fail with > +EINVAL. > + > +.SS Authentication > +All DRM devices provide authentication mechanisms. Only a DRM-Master is allowed > +to perform mode-setting or modify core state and only one user can be DRM-Master > +at a time. See > +.BR drmSetMaster (3) > +for information on how to become DRM-Master and what the limitations are. > +Other DRM users can be authenticated to the DRM-Master via > +.BR drmAuthMagic (3) > +so they can perform buffer allocations and rendering. > + > +.SS Mode-Setting > +Managing connected monitors and displays and changing the current modes is > +called > +.BR Mode-Setting . > +This is restricted to the current DRM-Master. Historically, this was implemented > +in user-space, but new DRM drivers implement a kernel interface to perform > +mode-setting called > +.B Kernel Mode Setting > +(KMS). If your hardware-driver supports it, you can use the KMS API provided by > +DRM. This includes allocating framebuffers, selecting modes and managing CRTCs > +and encoders. See > +.BR drm-kms (7) > +for more. > + > +.SS Memory Management > +The most sophisticated tasks for GPUs today is managing memory objects. > +Textures, framebuffers, command-buffers and all other kinds of commands for the > +GPU have to be stored in memory. The DRM driver takes care of managing all > +memory objects, flushing caches, synchronizing access and providing CPU access > +to GPU memory. > +.br > +All memory management is hardware driver dependent. However, two generic > +frameworks are available that are used by most DRM drivers. These are the > +.B Translation Table Manager > +(TTM) and the > +.B Graphics Execution Manager > +(GEM). They provide generic APIs to create, destroy and access buffers from > +user-space. However, there are still many differences between the drivers so > +driver-depedent code is still needed. Many helpers are provided in > +.B libgbm > +(Graphics Buffer Manager) from the > +.IR mesa-project . > +For more information on DRM memory-management, see > +.BR drm-memory (7). > + > +.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-kms (7), > +.BR drm-memory (7), > +.BR drmSetMaster (3), > +.BR drmAuthMagic (3), > +.BR drmAvailable (3), > +.BR drmOpen (3) Nice. Reviewed-by: Jesse Barnes <jbarnes@xxxxxxxxxxxxxxxx> -- Jesse Barnes, Intel Open Source Technology Center _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/dri-devel
