redonkable/remarkable-linux
redonkable/remarkable-linux
1
0
Fork 0
Code Releases Activity

drm/doc: updates for new framebuffer lifetime rules

Browse source 
Now that framebuffer are reference-counted for all use-sites, update
the documentation accordingly to stress the new rules for
initialization and teardown.

Also add a short paragraph about the implications for drivers of the
new locking rules.

Reviewed-by: Rob Clark <rob@ti.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
This commit is contained in:
Daniel Vetter 2013-01-04 22:31:20 +01:00
parent 7b24056be6
commit 5d7a951537
1 changed files with 45 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
Documentation/DocBook/drm.tmpl
View file

@ -978,10 +978,25 @@ int max_width, max_height;</synopsis>
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. The new instance is initialized with a call to
<function>drm_framebuffer_init</function> which takes a pointer to DRM
frame buffer operations (struct
<structname>drm_framebuffer_funcs</structname>). Frame buffer operations are
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 initailization 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,
@ -1022,16 +1037,16 @@ int max_width, max_height;</synopsis>
</itemizedlist>
</para>
<para>
After initializing the <structname>drm_framebuffer</structname>
instance 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>
The lifetime of a drm framebuffer is controlled with a reference count,
drivers can grab additional references with
<function>drm_framebuffer_reference</function> </para> and drop them
again with <function>drm_framebuffer_unreference</function>. For
driver-private framebuffers for which the last reference is never
dropped (e.g. for the fbdev framebuffer when the struct
<structname>drm_framebuffer</structname> is embedded into the fbdev
helper struct) drivers can manually clean up a framebuffer at module
unload time with
<function>drm_framebuffer_unregister_private</function>.
</sect2>
<sect2>
<title>Output Polling</title>
@ -1043,6 +1058,22 @@ int max_width, max_height;</synopsis>
operation.
</para>
</sect2>
<sect2>
<title>Locking</title>
<para>
Beside some lookup structures with their own locking (which is hidden
behind the interface functions) most of the modeset state is protected
by the <code>dev-&lt;mode_config.lock</code> mutex and additionally
per-crtc locks to allow cursor updates, pageflips and similar operations
to occur concurrently with background tasks like output detection.
Operations which cross domains like a full modeset always grab all
locks. Drivers there need to protect resources shared between crtcs with
additional locking. They also need to be careful to always grab the
relevant crtc locks if a modset functions touches crtc state, e.g. for
load detection (which does only grab the <code>mode_config.lock</code>
to allow concurrent screen updates on live crtcs).
</para>
</sect2>
</sect1>
<!-- Internals: kms initialization and cleanup -->