From patchwork Thu Jan 23 08:52:26 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 3526961 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 91245C02DC for ; Thu, 23 Jan 2014 08:53:41 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 6FE112017A for ; Thu, 23 Jan 2014 08:53:40 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id 5DAF1200F0 for ; Thu, 23 Jan 2014 08:53:39 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id E89BCFB5FC; Thu, 23 Jan 2014 00:53:36 -0800 (PST) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-ee0-f45.google.com (mail-ee0-f45.google.com [74.125.83.45]) by gabe.freedesktop.org (Postfix) with ESMTP id A16EAFB5D9 for ; Thu, 23 Jan 2014 00:53:34 -0800 (PST) Received: by mail-ee0-f45.google.com with SMTP id b15so254457eek.4 for ; Thu, 23 Jan 2014 00:53:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=cnZv8YGy/VCIeB6xghUhBDCEbTt78BoQm0VQKZUgAro=; b=GcgaEL2Ce1QQ84WgCudseaypw4uJQ+GLrj5QGLUbNchGcHt8bGtNN7GaQQ7EgRtmT3 O73cNP8u5tysTr36FSpiNyHvYxxhi6ncLTUicpnxhtyRLWwhBVrsVUlokk0eqTZU7BqX DwMwplYmfSySa+5xUQo0YcW8H5+GZpr3I6Wlg= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=cnZv8YGy/VCIeB6xghUhBDCEbTt78BoQm0VQKZUgAro=; b=SxQ7wk6WIax4yYk8gbNjsKCfDYYOdEkVfqNnfgdRFo2slwPphIXn3h85z0uoNAdxuy 9/rj1ssGffnaqQaul2Ek7pr7lzmDJnvuN+s0RowqB4km/aWF2/3wmiZFK/UurzkBc+iC 5nyeR7WREX4mgRaHtISTejVA2MFxNsa45ytC/WBn3LYz6HLLoSnDXfzhU6andjKqZFa+ fuzXsoF0+Ty6/0pHdEOjCdJY7QcZfu2Dd1iqKb+S+lLktqmbtx0zlqD3umm48NHVv/BH CWWJ9A5UWAdAmN/MeZYDDiRZi7z9xOZX1B9nMBIJ10petyKOr0s2vwVIqFIZlwcykaZg 4FJw== X-Gm-Message-State: ALoCoQlGEIqQPq0srRAsdqBLK5Bdj9x3HOdL9h96yj2QfGbL+2/xE7fiU1jiA2FPl7XFkyymlqr+ X-Received: by 10.14.48.1 with SMTP id u1mr1545157eeb.6.1390467213920; Thu, 23 Jan 2014 00:53:33 -0800 (PST) Received: from phenom.ffwll.local (84-73-67-144.dclient.hispeed.ch. [84.73.67.144]) by mx.google.com with ESMTPSA id z42sm29240100eel.3.2014.01.23.00.53.32 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 23 Jan 2014 00:53:32 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 01/19] drm/doc: Clarify the dumb object interfaces Date: Thu, 23 Jan 2014 09:52:26 +0100 Message-Id: <1390467164-951-2-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1390467164-951-1-git-send-email-daniel.vetter@ffwll.ch> References: <1390467164-951-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Laurent Pinchart 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@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org X-Spam-Status: No, score=-4.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,RP_MATCHES_RCVD,T_DKIM_INVALID,UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP - This is _not_ a generic interface to create gem objects, but just an interface to make early boot services (like boot splash) with a generic KMS userspace driver possible. Hence it's better to move the documentation for this from the GEM section to the KMS section, next to the creation of framebuffer objects. - Make it really clear that the returned handle isn't necessarily a GEM object (it can also be e.g. a TTM handle when running on top of vmwgfx). - Add a paragraph to make it clear that this is just for unaccelarated userspace - gpu drivers need to have their own buffer object creation ioctl which is hardware specific. Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 125 ++++++++++++++++++++++------------------- 1 file changed, 68 insertions(+), 57 deletions(-) diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d289022..9c3fdd59c995 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -830,62 +830,6 @@ char *date; - Dumb GEM Objects - - The GEM API doesn't standardize GEM objects creation and leaves it to - driver-specific ioctls. While not an issue for full-fledged graphics - stacks that include device-specific userspace components (in libdrm for - instance), this limit makes DRM-based early boot graphics unnecessarily - complex. - - - Dumb GEM objects partly alleviate the problem by providing a standard - API to create dumb buffers suitable for scanout, which can then be used - to create KMS frame buffers. - - - To support dumb GEM objects drivers must implement the - dumb_create, - dumb_destroy and - dumb_map_offset operations. - - - - int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, - struct drm_mode_create_dumb *args); - - The dumb_create operation creates a GEM - object suitable for scanout based on the width, height and depth - from the struct drm_mode_create_dumb - argument. It fills the argument's handle, - pitch and size - fields with a handle for the newly created GEM object and its line - pitch and size in bytes. - - - - int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle); - - The dumb_destroy operation destroys a dumb - GEM object created by dumb_create. - - - - int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle, uint64_t *offset); - - The dumb_map_offset operation associates an - mmap fake offset with the GEM object given by the handle and returns - it. Drivers must use the - drm_gem_create_mmap_offset function to - associate the fake offset as described in - . - - - - - Memory Coherency When mapped to the device or used in a command buffer, backing pages @@ -970,7 +914,9 @@ int max_width, max_height; handle (or a list of memory handles for multi-planar formats) through the drm_mode_fb_cmd2 argument. This document assumes that the driver uses GEM, those handles thus reference GEM - objects. + objects. But drivers are free to use their own backing storage object + handles, e.g. vmwgfx directly exposes special TTM handles to userspace + and so expects TTM handles in the create ioctl and not GEM objects. Drivers must first validate the requested frame buffer parameters passed @@ -1052,6 +998,71 @@ int max_width, max_height; drm_framebuffer_unregister_private. + Dumb GEM Objects + + The KMS API doesn't standardize backing storage object creation and + leaves it to driver-specific ioctls. Furthermore actually creating a + buffer object even for GEM-based drivers is done through a + driver-specific ioctl - GEM only has a common userspace interface for + sharing and destroying objects. While not an issue for full-fledged + graphics stacks that include device-specific userspace components (in + libdrm for instance), this limit makes DRM-based early boot graphics + unnecessarily complex. + + + Dumb objects partly alleviate the problem by providing a standard + API to create dumb buffers suitable for scanout, which can then be used + to create KMS frame buffers. + + + To support dumb objects drivers must implement the + dumb_create, + dumb_destroy and + dumb_map_offset operations. + + + + int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args); + + The dumb_create operation creates a driver + object (GEM or TTM handle) object suitable for scanout based on the + width, height and depth from the struct + drm_mode_create_dumb argument. It fills the + argument's handle, + pitch and size + fields with a handle for the newly created object and its line + pitch and size in bytes. + + + + int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle); + + The dumb_destroy operation destroys a dumb + object created by dumb_create. + + + + int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset); + + The dumb_map_offset operation associates an + mmap fake offset with the object given by the handle and returns + it. Drivers must use the + drm_gem_create_mmap_offset function to + associate the fake offset as described in + . + + + + + Note that dumb objects may not be used for gpu accelaration, as has been + attempted on some ARM embedded platforms. Such drivers really must have + a hardware-specific ioctl to allocate suitable objects. + + + Output Polling void (*output_poll_changed)(struct drm_device *dev);