drm: Move more framebuffer doc from docbook to kerneldoc

!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

	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

	 * 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);

	 * 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.

	 * 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