From mboxrd@z Thu Jan 1 00:00:00 1970 From: Laurent Pinchart Subject: Re: [PATCH] drm/doc: Clarify the dumb object interfaces Date: Sun, 26 Jan 2014 23:59:35 +0100 Message-ID: <4294422.vk2YjHdLWO@avalon> References: <8133797.MaFuyckv2B@avalon> <1390582720-19733-1-git-send-email-daniel.vetter@ffwll.ch> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [95.142.166.194]) by gabe.freedesktop.org (Postfix) with ESMTP id 90CC0FA9C5 for ; Sun, 26 Jan 2014 14:58:47 -0800 (PST) In-Reply-To: <1390582720-19733-1-git-send-email-daniel.vetter@ffwll.ch> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: dri-devel-bounces@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org To: Daniel Vetter Cc: DRI Development List-Id: dri-devel@lists.freedesktop.org Hi Daniel, Thank you for the patch. On Friday 24 January 2014 17:58:40 Daniel Vetter wrote: > - 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. > > v2: Clarify that the documentation doesn't just apply to GEM-based > drivers only but is now generally valid, as suggested by David. > > v3: Polish the intro sentence a bit and one s/objects/handles/ for > clarification, both suggested by Laurent. > > v4: More text polish from Laurent's review. > > Cc: David Herrmann > Cc: Laurent Pinchart > Signed-off-by: Daniel Vetter Acked-by: Laurent Pinchart > --- > Documentation/DocBook/drm.tmpl | 131 ++++++++++++++++++++------------------ > 1 file changed, 71 insertions(+), 60 deletions(-) > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl > index ed1d6d289022..67cfe184749c 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 @@ -968,9 +912,11 @@ int max_width, max_height; > Frame buffers rely on the underneath memory manager for low-level > memory operations. When creating a frame buffer applications pass a memory > 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. > + the drm_mode_fb_cmd2 argument. For drivers using > + GEM as their userspace buffer management interface this would be a GEM > + handle. Drivers are however 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 handles. > > > Drivers must first validate the requested frame buffer parameters > passed @@ -992,7 +938,7 @@ int max_width, max_height; > > > > - The initailization of the new framebuffer instance is finalized with a > + The initilization of the new framebuffer instance is finalized with a > call to drm_framebuffer_init which takes a pointer > to DRM frame buffer operations (struct > drm_framebuffer_funcs). Note that this function > @@ -1052,6 +998,71 @@ int max_width, max_height; > drm_framebuffer_unregister_private. > > > + Dumb Buffer 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) 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 buffer objects. > + > + > + > Output Polling > void (*output_poll_changed)(struct drm_device > *dev); -- Regards, Laurent Pinchart