Commit 065a5027 authored by Daniel Vetter's avatar Daniel Vetter

drm/doc: Clarify the dumb object interfaces

- 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.

v5: More typo fixes from Dieter.

Cc: Dieter Nützel <Dieter@nuetzel-hh.de>
Cc: David Herrmann <dh.herrmann@gmail.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 786a7828
...@@ -829,62 +829,6 @@ char *date;</synopsis> ...@@ -829,62 +829,6 @@ char *date;</synopsis>
faults can implement their own mmap file operation handler. faults can implement their own mmap file operation handler.
</para> </para>
</sect3> </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> <sect3>
<title>Memory Coherency</title> <title>Memory Coherency</title>
<para> <para>
...@@ -968,9 +912,11 @@ int max_width, max_height;</synopsis> ...@@ -968,9 +912,11 @@ int max_width, max_height;</synopsis>
Frame buffers rely on the underneath memory manager for low-level memory Frame buffers rely on the underneath memory manager for low-level memory
operations. When creating a frame buffer applications pass a memory operations. When creating a frame buffer applications pass a memory
handle (or a list of memory handles for multi-planar formats) through handle (or a list of memory handles for multi-planar formats) through
the <parameter>drm_mode_fb_cmd2</parameter> argument. This document the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using
assumes that the driver uses GEM, those handles thus reference GEM GEM as their userspace buffer management interface this would be a GEM
objects. 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>
<para> <para>
Drivers must first validate the requested frame buffer parameters passed Drivers must first validate the requested frame buffer parameters passed
...@@ -992,7 +938,7 @@ int max_width, max_height;</synopsis> ...@@ -992,7 +938,7 @@ int max_width, max_height;</synopsis>
</para> </para>
<para> <para>
The initailization of the new framebuffer instance is finalized with a The initialization of the new framebuffer instance is finalized with a
call to <function>drm_framebuffer_init</function> which takes a pointer call to <function>drm_framebuffer_init</function> which takes a pointer
to DRM frame buffer operations (struct to DRM frame buffer operations (struct
<structname>drm_framebuffer_funcs</structname>). Note that this function <structname>drm_framebuffer_funcs</structname>). Note that this function
...@@ -1051,6 +997,71 @@ int max_width, max_height;</synopsis> ...@@ -1051,6 +997,71 @@ int max_width, max_height;</synopsis>
unload time with unload time with
<function>drm_framebuffer_unregister_private</function>. <function>drm_framebuffer_unregister_private</function>.
</sect2> </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 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> <sect2>
<title>Output Polling</title> <title>Output Polling</title>
<synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis> <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
...@@ -2134,7 +2145,7 @@ void intel_crt_init(struct drm_device *dev) ...@@ -2134,7 +2145,7 @@ void intel_crt_init(struct drm_device *dev)
set the <structfield>display_info</structfield> set the <structfield>display_info</structfield>
<structfield>width_mm</structfield> and <structfield>width_mm</structfield> and
<structfield>height_mm</structfield> fields if they haven't been set <structfield>height_mm</structfield> fields if they haven't been set
already (for instance at initilization time when a fixed-size panel is already (for instance at initialization time when a fixed-size panel is
attached to the connector). The mode <structfield>width_mm</structfield> attached to the connector). The mode <structfield>width_mm</structfield>
and <structfield>height_mm</structfield> fields are only used internally and <structfield>height_mm</structfield> fields are only used internally
during EDID parsing and should not be set when creating modes manually. during EDID parsing and should not be set when creating modes manually.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment