| Message ID | 1390582720-19733-1-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Am 24.01.2014 17:58, schrieb Daniel Vetter:
Just two typos ('said' my spellchecker...;-)
Regards,
Dieter
> - 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 <dh.herrmann@gmail.com>
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> ---
> 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;</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. 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.
> </para>
> <para>
> Drivers must first validate the requested frame buffer
> parameters passed
> @@ -992,7 +938,7 @@ int max_width, max_height;</synopsis>
> </para>
>
> <para>
> - The initailization of the new framebuffer instance is finalized with
> a
> + The initilization of the new framebuffer instance is finalized with a
=> initialization ;-)
> call to <function>drm_framebuffer_init</function> which takes a
> pointer
> to DRM frame buffer operations (struct
> <structname>drm_framebuffer_funcs</structname>). Note that this
> function
> @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis>
> <function>drm_framebuffer_unregister_private</function>.
> </sect2>
> <sect2>
> + <title>Dumb Buffer 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) 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,
=> acceleration
> as has been
> + attempted on some ARM embedded platforms. Such drivers really must
> have
> + a hardware-specific ioctl to allocate suitable buffer objects.
> + </para>
> + </sect2>
> + <sect2>
> <title>Output Polling</title>
> <synopsis>void (*output_poll_changed)(struct drm_device
> *dev);</synopsis>
> <para>
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 <dh.herrmann@gmail.com> > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > --- > 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;</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. 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. > </para> > <para> > Drivers must first validate the requested frame buffer parameters > passed @@ -992,7 +938,7 @@ int max_width, max_height;</synopsis> > </para> > > <para> > - The initailization of the new framebuffer instance is finalized with a > + The initilization of the new framebuffer instance is finalized with a > call to <function>drm_framebuffer_init</function> which takes a pointer > to DRM frame buffer operations (struct > <structname>drm_framebuffer_funcs</structname>). Note that this function > @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis> > <function>drm_framebuffer_unregister_private</function>. > </sect2> > <sect2> > + <title>Dumb Buffer 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) 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 buffer 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..67cfe184749c 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. 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. </para> <para> Drivers must first validate the requested frame buffer parameters passed @@ -992,7 +938,7 @@ int max_width, max_height;</synopsis> </para> <para> - The initailization of the new framebuffer instance is finalized with a + The initilization of the new framebuffer instance is finalized with a call to <function>drm_framebuffer_init</function> which takes a pointer to DRM frame buffer operations (struct <structname>drm_framebuffer_funcs</structname>). Note that this function @@ -1052,6 +998,71 @@ int max_width, max_height;</synopsis> <function>drm_framebuffer_unregister_private</function>. </sect2> <sect2> + <title>Dumb Buffer 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) 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 buffer 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. 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 <dh.herrmann@gmail.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> --- Documentation/DocBook/drm.tmpl | 131 ++++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 60 deletions(-)