Hi On Thu, Jan 23, 2014 at 9:52 AM, Daniel Vetter <daniel.vetter@xxxxxxxx> 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. > > Cc: Laurent Pinchart laurent.pinchart@xxxxxxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxx> > --- > 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;</synopsis> > </para> > </sect3> > <sect3> > - <title>Dumb GEM Objects</title> > - <para> > - 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. > - </para> > - <para> > - 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. > - </para> > - <para> > - To support dumb GEM objects drivers must implement the > - <methodname>dumb_create</methodname>, > - <methodname>dumb_destroy</methodname> and > - <methodname>dumb_map_offset</methodname> operations. > - </para> > - <itemizedlist> > - <listitem> > - <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, > - struct drm_mode_create_dumb *args);</synopsis> > - <para> > - The <methodname>dumb_create</methodname> operation creates a GEM > - object suitable for scanout based on the width, height and depth > - from the struct <structname>drm_mode_create_dumb</structname> > - argument. It fills the argument's <structfield>handle</structfield>, > - <structfield>pitch</structfield> and <structfield>size</structfield> > - fields with a handle for the newly created GEM object and its line > - pitch and size in bytes. > - </para> > - </listitem> > - <listitem> > - <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, > - uint32_t handle);</synopsis> > - <para> > - The <methodname>dumb_destroy</methodname> operation destroys a dumb > - GEM object created by <methodname>dumb_create</methodname>. > - </para> > - </listitem> > - <listitem> > - <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, > - uint32_t handle, uint64_t *offset);</synopsis> > - <para> > - The <methodname>dumb_map_offset</methodname> operation associates an > - mmap fake offset with the GEM object given by the handle and returns > - it. Drivers must use the > - <function>drm_gem_create_mmap_offset</function> function to > - associate the fake offset as described in > - <xref linkend="drm-gem-objects-mapping"/>. > - </para> > - </listitem> > - </itemizedlist> > - </sect3> > - <sect3> > <title>Memory Coherency</title> > <para> > When mapped to the device or used in a command buffer, backing pages > @@ -970,7 +914,9 @@ int max_width, max_height;</synopsis> > handle (or a list of memory handles for multi-planar formats) through > the <parameter>drm_mode_fb_cmd2</parameter> 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. Maybe remove the sentence saying "this document assumes that the driver uses GEM". I don't see where we explicitly do that. Otherwise the patch looks fine. Thanks David > </para> > <para> > Drivers must first validate the requested frame buffer parameters passed > @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis> > <function>drm_framebuffer_unregister_private</function>. > </sect2> > <sect2> > + <title>Dumb GEM Objects</title> > + <para> > + 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. > + </para> > + <para> > + 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. > + </para> > + <para> > + To support dumb objects drivers must implement the > + <methodname>dumb_create</methodname>, > + <methodname>dumb_destroy</methodname> and > + <methodname>dumb_map_offset</methodname> operations. > + </para> > + <itemizedlist> > + <listitem> > + <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, > + struct drm_mode_create_dumb *args);</synopsis> > + <para> > + The <methodname>dumb_create</methodname> operation creates a driver > + object (GEM or TTM handle) object suitable for scanout based on the > + width, height and depth from the struct > + <structname>drm_mode_create_dumb</structname> argument. It fills the > + argument's <structfield>handle</structfield>, > + <structfield>pitch</structfield> and <structfield>size</structfield> > + fields with a handle for the newly created object and its line > + pitch and size in bytes. > + </para> > + </listitem> > + <listitem> > + <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, > + uint32_t handle);</synopsis> > + <para> > + The <methodname>dumb_destroy</methodname> operation destroys a dumb > + object created by <methodname>dumb_create</methodname>. > + </para> > + </listitem> > + <listitem> > + <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, > + uint32_t handle, uint64_t *offset);</synopsis> > + <para> > + The <methodname>dumb_map_offset</methodname> operation associates an > + mmap fake offset with the object given by the handle and returns > + it. Drivers must use the > + <function>drm_gem_create_mmap_offset</function> function to > + associate the fake offset as described in > + <xref linkend="drm-gem-objects-mapping"/>. > + </para> > + </listitem> > + </itemizedlist> > + <para> > + 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. > + </para> > + </sect2> > + <sect2> > <title>Output Polling</title> > <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis> > <para> > -- > 1.8.5.2 > > _______________________________________________ > dri-devel mailing list > dri-devel@xxxxxxxxxxxxxxxxxxxxx > http://lists.freedesktop.org/mailman/listinfo/dri-devel _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/dri-devel
