Commit d55f5320 authored by Daniel Vetter's avatar Daniel Vetter

drm: Move more framebuffer doc from docbook to kerneldoc

I missed a few paragraphs in the docbook that need to be pulled into
the fbdev vfunc docs.

v2: Spelling fixes from Thierry.

Cc: Thierry Reding <treding@nvidia.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-3-git-send-email-daniel.vetter@ffwll.chReviewed-by: default avatarThierry Reding <treding@nvidia.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
parent 07bad49e
...@@ -986,10 +986,7 @@ int max_width, max_height;</synopsis> ...@@ -986,10 +986,7 @@ int max_width, max_height;</synopsis>
!Idrivers/gpu/drm/drm_atomic.c !Idrivers/gpu/drm/drm_atomic.c
</sect2> </sect2>
<sect2> <sect2>
<title>Frame Buffer Creation</title> <title>Frame Buffer Abstraction</title>
<synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
struct drm_file *file_priv,
struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
<para> <para>
Frame buffers are abstract memory objects that provide a source of Frame buffers are abstract memory objects that provide a source of
pixels to scanout to a CRTC. Applications explicitly request the pixels to scanout to a CRTC. Applications explicitly request the
...@@ -1007,73 +1004,6 @@ int max_width, max_height;</synopsis> ...@@ -1007,73 +1004,6 @@ int max_width, max_height;</synopsis>
handles, e.g. vmwgfx directly exposes special TTM handles to userspace handles, e.g. vmwgfx directly exposes special TTM handles to userspace
and so expects TTM handles in the create ioctl and not GEM handles. and so expects TTM handles in the create ioctl and not GEM handles.
</para> </para>
<para>
Drivers must first validate the requested frame buffer parameters passed
through the mode_cmd argument. In particular this is where invalid
sizes, pixel formats or pitches can be caught.
</para>
<para>
If the parameters are deemed valid, drivers then create, initialize and
return an instance of struct <structname>drm_framebuffer</structname>.
If desired the instance can be embedded in a larger driver-specific
structure. Drivers must fill its <structfield>width</structfield>,
<structfield>height</structfield>, <structfield>pitches</structfield>,
<structfield>offsets</structfield>, <structfield>depth</structfield>,
<structfield>bits_per_pixel</structfield> and
<structfield>pixel_format</structfield> fields from the values passed
through the <parameter>drm_mode_fb_cmd2</parameter> argument. They
should call the <function>drm_helper_mode_fill_fb_struct</function>
helper function to do so.
</para>
<para>
The initialization 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
publishes the framebuffer and so from this point on it can be accessed
concurrently from other threads. Hence it must be the last step in the
driver's framebuffer initialization sequence. Frame buffer operations
are
<itemizedlist>
<listitem>
<synopsis>int (*create_handle)(struct drm_framebuffer *fb,
struct drm_file *file_priv, unsigned int *handle);</synopsis>
<para>
Create a handle to the frame buffer underlying memory object. If
the frame buffer uses a multi-plane format, the handle will
reference the memory object associated with the first plane.
</para>
<para>
Drivers call <function>drm_gem_handle_create</function> to create
the handle.
</para>
</listitem>
<listitem>
<synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis>
<para>
Destroy the frame buffer object and frees all associated
resources. Drivers must call
<function>drm_framebuffer_cleanup</function> to free resources
allocated by the DRM core for the frame buffer object, and must
make sure to unreference all memory objects associated with the
frame buffer. Handles created by the
<methodname>create_handle</methodname> operation are released by
the DRM core.
</para>
</listitem>
<listitem>
<synopsis>int (*dirty)(struct drm_framebuffer *framebuffer,
struct drm_file *file_priv, unsigned flags, unsigned color,
struct drm_clip_rect *clips, unsigned num_clips);</synopsis>
<para>
This optional operation notifies the driver that a region of the
frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB
ioctl call.
</para>
</listitem>
</itemizedlist>
</para>
<para> <para>
The lifetime of a drm framebuffer is controlled with a reference count, The lifetime of a drm framebuffer is controlled with a reference count,
drivers can grab additional references with drivers can grab additional references with
......
...@@ -172,7 +172,9 @@ struct drm_framebuffer_funcs { ...@@ -172,7 +172,9 @@ struct drm_framebuffer_funcs {
* Clean up framebuffer resources, specifically also unreference the * Clean up framebuffer resources, specifically also unreference the
* backing storage. The core guarantees to call this function for every * backing storage. The core guarantees to call this function for every
* framebuffer successfully created by ->fb_create() in * framebuffer successfully created by ->fb_create() in
* &drm_mode_config_funcs. * &drm_mode_config_funcs. Drivers must also call
* drm_framebuffer_cleanup() to release DRM core resources for this
* framebuffer.
*/ */
void (*destroy)(struct drm_framebuffer *framebuffer); void (*destroy)(struct drm_framebuffer *framebuffer);
...@@ -187,6 +189,9 @@ struct drm_framebuffer_funcs { ...@@ -187,6 +189,9 @@ struct drm_framebuffer_funcs {
* copying the current screen contents to a private buffer and blending * copying the current screen contents to a private buffer and blending
* between that and the new contents. * between that and the new contents.
* *
* GEM based drivers should call drm_gem_handle_create() to create the
* handle.
*
* RETURNS: * RETURNS:
* *
* 0 on success or a negative error code on failure. * 0 on success or a negative error code on failure.
...@@ -1731,6 +1736,17 @@ struct drm_mode_config_funcs { ...@@ -1731,6 +1736,17 @@ struct drm_mode_config_funcs {
* requested metadata, but most of that is left to the driver. See * requested metadata, but most of that is left to the driver. See
* struct &drm_mode_fb_cmd2 for details. * struct &drm_mode_fb_cmd2 for details.
* *
* If the parameters are deemed valid and the backing storage objects in
* the underlying memory manager all exist, then the driver allocates
* a new &drm_framebuffer structure, subclassed to contain
* driver-specific information (like the internal native buffer object
* references). It also needs to fill out all relevant metadata, which
* should be done by calling drm_helper_mode_fill_fb_struct().
*
* The initialization is finalized by calling drm_framebuffer_init(),
* which registers the framebuffer and makes it accessible to other
* threads.
*
* RETURNS: * RETURNS:
* *
* A new framebuffer with an initial reference count of 1 or a negative * A new framebuffer with an initial reference count of 1 or a negative
......
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