From patchwork Fri Sep 28 21:44:20 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Herrmann X-Patchwork-Id: 1526641 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork1.kernel.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by patchwork1.kernel.org (Postfix) with ESMTP id AF55F3FE80 for ; Fri, 28 Sep 2012 21:44:11 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 9E76DA0F51 for ; Fri, 28 Sep 2012 14:44:11 -0700 (PDT) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wi0-f169.google.com (mail-wi0-f169.google.com [209.85.212.169]) by gabe.freedesktop.org (Postfix) with ESMTP id 0D5949E7FF for ; Fri, 28 Sep 2012 14:42:14 -0700 (PDT) Received: by mail-wi0-f169.google.com with SMTP id hq4so183268wib.0 for ; Fri, 28 Sep 2012 14:42:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; bh=AuoZeKWrbRiMDmtCHyStO3Wg5BskKp1Kog6VEgQVJNA=; b=fzrh945YwVJPlVeOUYtMuywfBsHgvJRrIKgsLcNEo1Ypdsb4DUP3DREk/nMi/cfu4d jQgcI9p+V3euncV7/JjWl5UZXexQwzAfqV54R6WT3z80l2TjbZMAfylsmixl3o5JGlut QsSv10ZyQvQTIN/GUWFeU7rj1hKMTEMt3+i2hAcAUWcnd1/AsGTSLM/vl0sJnGXd0dSv 2EaqPci+8S0XZWmFD7e+vDJti3q+IwtchxJH69P5KuHd9/R5mX9Delr4MGhxKA+zFq3H e3LEMD6VeSEVnELDlf5CZXai9CFATmaqpVrB7rZkbbp5BS4lHScOzZtBo/GaXztSHVk8 1rZQ== Received: by 10.216.74.21 with SMTP id w21mr4205844wed.77.1348868534102; Fri, 28 Sep 2012 14:42:14 -0700 (PDT) Received: from localhost.localdomain (stgt-5f71bfba.pool.mediaWays.net. [95.113.191.186]) by mx.google.com with ESMTPS id cw4sm1718346wib.4.2012.09.28.14.42.13 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 28 Sep 2012 14:42:13 -0700 (PDT) From: David Herrmann To: dri-devel@lists.freedesktop.org Subject: [PATCH libdrm 2/4] man: add drm.7 overview page Date: Fri, 28 Sep 2012 23:44:20 +0200 Message-Id: <1348868662-25509-3-git-send-email-dh.herrmann@googlemail.com> X-Mailer: git-send-email 1.7.12.1 In-Reply-To: <1348868662-25509-1-git-send-email-dh.herrmann@googlemail.com> References: <1348868662-25509-1-git-send-email-dh.herrmann@googlemail.com> X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: dri-devel-bounces+patchwork-dri-devel=patchwork.kernel.org@lists.freedesktop.org Errors-To: dri-devel-bounces+patchwork-dri-devel=patchwork.kernel.org@lists.freedesktop.org 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 Reviewed-by: Jesse Barnes --- 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 @@ + + + + + + + + Direct Rendering Manager + libdrm + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + drm + 7 + + + + drm + Direct Rendering Manager + + + + + #include <xf86drm.h> + + + + + Description + The Direct Rendering Manager (DRM) is a framework + to manage 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 + ioctl2 + commands on the DRM character device. The 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 + /dev/dri/card0 and can be accessed with + open2 + and + close2. + 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. + + + 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 + drmSetMaster3 + for information on how to become DRM-Master and what the limitations + are. Other DRM users can be authenticated to the DRM-Master via + drmAuthMagic3 + so they can perform buffer allocations and rendering. + + + + Mode-Setting + Managing connected monitors and displays and changing the current + modes is called 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 + 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 + drm-kms7 + for more. + + + + 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 Translation Table Manager (TTM) and the + 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 + libgbm (Graphics Buffer Manager) from the + mesa-project. For more information on DRM + memory-management, see + drm-memory7. + + + + + 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. + + + + See Also + + drm-kms7, + drm-memory7, + drmSetMaster3, + drmAuthMagic3, + drmAvailable3, + drmOpen3 + + +