install libdrm manual pages; feedback and OK jsg@ matthieu@

1 files changed, 110 insertions, 0 deletions

diff --git a/lib/libdrm/man/drm.7 b/lib/libdrm/man/drm.7
new file mode 100644
index 000000000..bbd3b40ef
--- /dev/null
+++ b/lib/libdrm/man/drm.7
@@ -0,0 +1,110 @@
+.\" automatically generated with
+.\" docbook2mdoc drm.xml > drm.7
+.Dd September 2012
+.Dt DRM 7
+.Os
+.Sh NAME
+.Nm drm
+.Nd Direct Rendering Manager
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Sh DESCRIPTION
+The
+.Em Direct Rendering Manager
+(DRM) is a framework
+to manage
+.Em 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.
+.Pp
+In earlier days, the kernel framework was solely used to provide raw
+hardware access to privileged user-space processes which implement
+all the hardware abstraction layers. But more and more tasks were
+moved into the kernel. All these interfaces are based on
+.Xr ioctl 2
+commands on the DRM character device. The
+.Em libdrm
+library provides wrappers for these system-calls and many helpers to
+simplify the API.
+.Pp
+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
+.Pa /dev/dri/card0
+and can be accessed with
+.Xr open 2
+and
+.Xr close 2 .
+However, it still depends on the graphics driver which interfaces are
+available on these devices. If an interface is not available, the
+syscalls will fail with
+.Ql 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
+.Xr 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
+.Xr 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
+.Em 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
+.Em 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
+.Xr 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. All
+memory management is hardware driver dependent. However, two generic
+frameworks are available that are used by most DRM drivers. These
+are the
+.Em Translation Table Manager
+(TTM) and the
+.Em 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
+.Em libgbm
+(Graphics Buffer Manager) from the
+.Em mesa-project .
+For more information on DRM
+memory-management, see
+.Xr drm-memory 7 .
+.Sh REPORTING BUGS
+Bugs in this manual should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm-kms 7 ,
+.Xr drm-memory 7 ,
+.Xr drmSetMaster 3 ,
+.Xr drmAuthMagic 3 ,
+.Xr drmAvailable 3 ,
+.Xr drmOpen 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com