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>

diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index a27bdf9eaab5055625c9cce4a12f40dd841ac079..6c6e81a9eaf474937a64311ec07795f003dce777 100644 (file)
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -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

diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index c2f98ba2bb9869f127395b8094d515e61f3c5eac..3b040b3554726e25132b8c11b42588743816e576 100644 (file)
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -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