From: Daniel Vetter <daniel.vetter@ffwll.ch>
To: DRI Development <dri-devel@lists.freedesktop.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Subject: [PATCH 34/35] drm/doc: updates for new framebuffer lifetime rules
Date: Thu, 10 Jan 2013 21:48:15 +0100 [thread overview]
Message-ID: <1357850897-27102-35-git-send-email-daniel.vetter@ffwll.ch> (raw)
In-Reply-To: <1357850897-27102-1-git-send-email-daniel.vetter@ffwll.ch>
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.
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
---
Documentation/DocBook/drm.tmpl | 59 ++++++++++++++++++++++++++++++----------
1 file changed, 45 insertions(+), 14 deletions(-)
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index caab791..6c11d77 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -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-<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 -->
--
1.7.10.4
next prev parent reply other threads:[~2013-01-10 20:49 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-01-10 20:47 [PATCH 00/36] kms locking rework Daniel Vetter
2013-01-10 20:47 ` [PATCH 01/35] drm: review locking rules in drm_crtc.c Daniel Vetter
2013-01-10 20:47 ` [PATCH 02/35] drm/doc: integrate drm_crtc.c kerneldoc Daniel Vetter
2013-01-10 20:47 ` [PATCH 03/35] drm/<drivers>: reorder framebuffer init sequence Daniel Vetter
2013-01-11 21:06 ` Rob Clark
2013-01-10 20:47 ` [PATCH 04/35] drm/vmwgfx: " Daniel Vetter
2013-01-10 20:47 ` [PATCH 05/35] drm/gma500: move fbcon restore to lastclose Daniel Vetter
2013-01-10 20:47 ` [PATCH 06/35] drm/nouveau: protect evo_wait/evo_kick sections with a channel mutex Daniel Vetter
2013-01-10 20:47 ` [PATCH 07/35] drm/nouveau: try to protect nbo->pin_refcount Daniel Vetter
2013-01-10 20:47 ` [PATCH 08/35] drm/<drivers>: Unified handling of unimplemented fb->create_handle Daniel Vetter
2013-01-18 15:00 ` Thierry Reding
2013-01-18 18:32 ` Daniel Vetter
2013-01-10 20:47 ` [PATCH 09/35] drm: encapsulate crtc->set_config calls Daniel Vetter
2013-01-10 20:47 ` [PATCH 10/35] drm: add drm_modeset_lock|unlock_all Daniel Vetter
2013-01-10 20:47 ` [PATCH 11/35] drm/i915: use drm_modeset_lock_all Daniel Vetter
2013-01-10 20:47 ` [PATCH 12/35] drm/gma500: " Daniel Vetter
2013-01-10 22:36 ` Alan Cox
2013-01-11 13:25 ` Daniel Vetter
2013-01-10 20:47 ` [PATCH 13/35] drm/ast: " Daniel Vetter
2013-01-10 20:47 ` [PATCH 14/35] drm/shmobile: " Daniel Vetter
2013-01-10 20:47 ` [PATCH 15/35] drm/vmgfx: " Daniel Vetter
2013-01-10 20:47 ` [PATCH 16/35] drm: add per-crtc locks Daniel Vetter
2013-01-10 20:47 ` [PATCH 17/35] drm: only take the crtc lock for ->cursor_set Daniel Vetter
2013-01-10 20:47 ` [PATCH 18/35] drm: only take the crtc lock for ->cursor_move Daniel Vetter
2013-01-10 20:48 ` [PATCH 19/35] drm: revamp locking around fb creation/destruction Daniel Vetter
2013-01-10 20:48 ` [PATCH 20/35] drm: create drm_framebuffer_lookup Daniel Vetter
2013-01-10 20:48 ` [PATCH 21/35] drm: revamp framebuffer cleanup interfaces Daniel Vetter
2013-01-10 20:48 ` [PATCH 22/35] drm: reference framebuffers which are on the idr Daniel Vetter
2013-01-10 20:48 ` [PATCH 23/35] drm: nest modeset locks within fpriv->fbs_lock Daniel Vetter
2013-01-10 20:48 ` [PATCH 24/35] drm: push modeset_lock_all into ->fb_create driver callbacks Daniel Vetter
2013-01-10 20:48 ` [PATCH 25/35] drm: don't take modeset locks in getfb ioctl Daniel Vetter
2013-01-10 20:48 ` [PATCH 26/35] drm: fb refcounting for dirtyfb_ioctl Daniel Vetter
2013-01-10 20:48 ` [PATCH 27/35] drm: refcounting for sprite framebuffers Daniel Vetter
2013-01-10 20:48 ` [PATCH 28/35] drm: refcounting for crtc framebuffers Daniel Vetter
2013-01-10 20:48 ` [PATCH 29/35] drm/i915: dump refcount into framebuffer debugfs file Daniel Vetter
2013-01-11 22:20 ` Rob Clark
2013-01-10 20:48 ` [PATCH 30/35] drm/vmwgfx: add proper framebuffer refcounting Daniel Vetter
2013-01-10 20:48 ` [PATCH 31/35] drm: optimize drm_framebuffer_remove Daniel Vetter
2013-01-10 20:48 ` [PATCH 32/35] drm: only grab the crtc lock for pageflips Daniel Vetter
2013-01-10 20:48 ` [PATCH 33/35] drm: don't hold crtc mutexes for connector ->detect callbacks Daniel Vetter
2013-01-10 20:48 ` Daniel Vetter [this message]
2013-01-10 20:48 ` [PATCH 35/35] drm/fb_helper: check whether fbcon is bound Daniel Vetter
2013-01-10 20:48 ` [PATCH 36/36] drm/i915: wake up all pageflip waiters Daniel Vetter
2013-01-10 20:50 ` Daniel Vetter
2013-01-11 23:17 ` [PATCH 00/36] kms locking rework Rob Clark
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1357850897-27102-35-git-send-email-daniel.vetter@ffwll.ch \
--to=daniel.vetter@ffwll.ch \
--cc=dri-devel@lists.freedesktop.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).