The drm.xml file compiles to drm.7 and is meant as a global overview page for libdrm. It is targeted to new users of libdrm and redirects to all other main man-pages. Signed-off-by: David Herrmann <dh.herrmann@xxxxxxxxxxxxxx> Reviewed-by: Jesse Barnes <jbarnes@xxxxxxxxxxxxxxxx> --- man/Makefile.am | 1 + man/drm.xml | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 man/drm.xml diff --git a/man/Makefile.am b/man/Makefile.am index 3030e5f..d55f444 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -5,6 +5,7 @@ # MANPAGES = \ + drm.7 \ drmAvailable.3 \ drmHandleEvent.3 \ drmModeGetResources.3 diff --git a/man/drm.xml b/man/drm.xml new file mode 100644 index 0000000..5a49fe1 --- /dev/null +++ b/man/drm.xml @@ -0,0 +1,137 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";> + +<!-- + Written 2012 by David Herrmann <dh.herrmann@xxxxxxxxxxxxxx> + Dedicated to the Public Domain +--> + +<refentry id="drm"> + <refentryinfo> + <title>Direct Rendering Manager</title> + <productname>libdrm</productname> + <date>September 2012</date> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Herrmann</surname> + <email>dh.herrmann@xxxxxxxxxxxxxx</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>drm</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>drm</refname> + <refpurpose>Direct Rendering Manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para>The <emphasis>Direct Rendering Manager</emphasis> (DRM) is a framework + to manage <emphasis>Graphics Processing Units</emphasis> (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.</para> + + <para>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 + <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + commands on the DRM character device. The <emphasis>libdrm</emphasis> + library provides wrappers for these system-calls and many helpers to + simplify the API.</para> + + <para>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 + <filename>/dev/dri/card0</filename> and can be accessed with + <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + 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 <literal>EINVAL</literal>.</para> + + <refsect2> + <title>Authentication</title> + <para>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 + <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for information on how to become DRM-Master and what the limitations + are. Other DRM users can be authenticated to the DRM-Master via + <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry> + so they can perform buffer allocations and rendering.</para> + </refsect2> + + <refsect2> + <title>Mode-Setting</title> + <para>Managing connected monitors and displays and changing the current + modes is called <emphasis>Mode-Setting</emphasis>. 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 + <emphasis>Kernel Mode Setting</emphasis> (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 + <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more.</para> + </refsect2> + + <refsect2> + <title>Memory Management</title> + <para>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 <emphasis>Translation Table Manager</emphasis> (TTM) and the + <emphasis>Graphics Execution Manager</emphasis> (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 + <emphasis>libgbm</emphasis> (Graphics Buffer Manager) from the + <emphasis>mesa-project</emphasis>. For more information on DRM + memory-management, see + <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Reporting Bugs</title> + <para>Bugs in this manual should be reported to + http://bugs.freedesktop.org under the "Mesa" product, with "Other" or + "libdrm" as the component.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> -- 1.7.12.1 _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/dri-devel
