From patchwork Sun Sep 23 14:40:05 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Herrmann X-Patchwork-Id: 1495591 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 434B13FC71 for ; Sun, 23 Sep 2012 14:39:58 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 49B819F31C for ; Sun, 23 Sep 2012 07:39:58 -0700 (PDT) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wi0-f171.google.com (mail-wi0-f171.google.com [209.85.212.171]) by gabe.freedesktop.org (Postfix) with ESMTP id 635959EEA5 for ; Sun, 23 Sep 2012 07:38:06 -0700 (PDT) Received: by wibhq4 with SMTP id hq4so3255829wib.12 for ; Sun, 23 Sep 2012 07:38:05 -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=JY7d+QJuX7LdW0xGCt6WM38eZBf+lN5MAigqKBTxgEs=; b=poRj1oPHRcdpruSGo69qMHo+r1JaobH6uZH+4BZWEgHZSmKed215InhDTliwpO6aPx ls1AXLwiSle1LkHy98CqJ41Iiu1E/Z/c7t9AGZewBwc1qE1rP0Fxzj1BIotSrv1BeTdI xGC10wVfpL5lGJPlqbEEyr9wS3eS/gPXb0RvNwYy3+W2VIAFr1F3oFo+3neRSkW918p3 THz1ua67vEFa0Ukmm7rLSAdLG5ksZd58UAzqbpeHAZv2Z1fN4/hAAxq7Hx7sUu8U5nlK x6usPlQ2LDizNdPPPYFfMrEn7KEKLih+fTkgn4AhumLWn/YzvH+rgF3/vuZWPom3Ta0e B3qg== Received: by 10.180.100.101 with SMTP id ex5mr5240518wib.16.1348411085426; Sun, 23 Sep 2012 07:38:05 -0700 (PDT) Received: from localhost.localdomain (stgt-5f71ab6d.pool.mediaWays.net. [95.113.171.109]) by mx.google.com with ESMTPS id dm3sm10865329wib.3.2012.09.23.07.38.04 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 23 Sep 2012 07:38:04 -0700 (PDT) From: David Herrmann To: dri-devel@lists.freedesktop.org Subject: [PATCH libdrm 2/4] man: add man/drm.7 overview page Date: Sun, 23 Sep 2012 16:40:05 +0200 Message-Id: <1348411208-3943-3-git-send-email-dh.herrmann@googlemail.com> X-Mailer: git-send-email 1.7.12.1 In-Reply-To: <1348411208-3943-1-git-send-email-dh.herrmann@googlemail.com> References: <1348411208-3943-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 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 Reviewed-by: Jesse Barnes --- 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 + +.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)