[PATCH libdrm 2/4] man: add man/drm.7 overview page

[Jesse Barnes]

On Sun, 23 Sep 2012 16:40:05 +0200
David Herrmann <dh.herrmann at googlemail.com> 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 at googlemail.com>
> ---
>  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 at virtuousgeek.org>

-- 
Jesse Barnes, Intel Open Source Technology Center