p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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.ch
Reviewed-by: Thierry Reding <treding@nvidia.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
This commit is contained in:
Daniel Vetter 2015-12-08 09:49:19 +01:00
parent 07bad49ea8
commit d55f5320c7
2 changed files with 18 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
Documentation/DocBook/gpu.tmpl
View File

@ -986,10 +986,7 @@ int max_width, max_height;</synopsis>
!Idrivers/gpu/drm/drm_atomic.c
</sect2>
<sect2>
<title>Frame Buffer Creation</title>
<synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
struct drm_file *file_priv,
struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
<title>Frame Buffer Abstraction</title>
<para>
Frame buffers are abstract memory objects that provide a source of
pixels to scanout to a CRTC. Applications explicitly request the
@ -1007,73 +1004,6 @@ int max_width, max_height;</synopsis>
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
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>
The lifetime of a drm framebuffer is controlled with a reference count,
drivers can grab additional references with

18
include/drm/drm_crtc.h
View File

@ -172,7 +172,9 @@ struct drm_framebuffer_funcs {
* Clean up framebuffer resources, specifically also unreference the
* backing storage. The core guarantees to call this function for every
* 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);
@ -187,6 +189,9 @@ struct drm_framebuffer_funcs {
* copying the current screen contents to a private buffer and blending
* between that and the new contents.
*
* GEM based drivers should call drm_gem_handle_create() to create the
* handle.
*
* RETURNS:
*
* 0 on success or a negative error code on failure.
@ -1731,6 +1736,17 @@ struct drm_mode_config_funcs {
* requested metadata, but most of that is left to the driver. See
* 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:
*
* A new framebuffer with an initial reference count of 1 or a negative