Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5d7a9515 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: updates for new framebuffer lifetime rules 



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: default avatarRob Clark <rob@ti.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 7b24056b

Documentation/DocBook/drm.tmpl

+45 −14
Original line number Diff line number Diff line
@@ -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 -->