| Message ID | 1390481297-13638-1-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Hi Daniel, Thank you for the patch. On Thursday 23 January 2014 13:48:17 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. > > Cc: David Herrmann <dh.herrmann@gmail.com> > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > Documentation/DocBook/drm.tmpl | 129 ++++++++++++++++++++------------------ > 1 file changed, 70 insertions(+), 59 deletions(-) > > diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl > index ed1d6d289022..809bf5f7e1c6 100644 > --- a/Documentation/DocBook/drm.tmpl > +++ b/Documentation/DocBook/drm.tmpl [snip] > @@ -968,9 +912,11 @@ int max_width, max_height;</synopsis> > 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 <parameter>drm_mode_fb_cmd2</parameter> argument. This document - > assumes that the driver uses GEM, those handles thus reference GEM - > objects. > + the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using > + GEM as their userspace buffer management interface this would be a GEM > + handle. 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. I'm not sure if the rule also applies to English, but I've always been thought not to start a sentence by "but" in French, so what about the following wording (as proposed in a previous mail that was sent too late for your v2 - you're too fast ;-)) ? "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, not GEM handles." (I've also replaced "GEM objects" by "GEM handles" in the last sentence) > </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> Regarding the location of this section, let's continue the discussion in the mail thread of your first patch. > + <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>
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d289022..809bf5f7e1c6 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 @@ -968,9 +912,11 @@ int max_width, max_height;</synopsis> 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 <parameter>drm_mode_fb_cmd2</parameter> argument. This document - assumes that the driver uses GEM, those handles thus reference GEM - objects. + the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using + GEM as their userspace buffer management interface this would be a GEM + handle. 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. </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>
- 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. Cc: David Herrmann <dh.herrmann@gmail.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> --- Documentation/DocBook/drm.tmpl | 129 ++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 59 deletions(-)