drm: Polish fbdev helper struct docs

Mostly this is just adding extensive docs for the callbacks, but also
a few other additions.

v2: Use FIXME comments to annotate helper hooks that should be
replaced.

v3: Small nits (Thierry).

Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-2-git-send-email-daniel.vetter@ffwll.ch
Reviewed-by: Thierry Reding <treding@nvidia.com>

diff --git a/include/drm/drm_fb_helper.h b/include/drm/drm_fb_helper.h
index 87b090c4b7306556dfe2096b2040890736632fab..d2d4ad1918ac34b998558fc08b997b720e773209 100644 (file)
--- a/include/drm/drm_fb_helper.h
+++ b/include/drm/drm_fb_helper.h
@@ -74,25 +74,76 @@ struct drm_fb_helper_surface_size {
 
 /**
  * struct drm_fb_helper_funcs - driver callbacks for the fbdev emulation library
- * @gamma_set: Set the given gamma lut register on the given crtc.
- * @gamma_get: Read the given gamma lut register on the given crtc, used to
- *             save the current lut when force-restoring the fbdev for e.g.
- *             kdbg.
- * @fb_probe: Driver callback to allocate and initialize the fbdev info
- *            structure. Furthermore it also needs to allocate the drm
- *            framebuffer used to back the fbdev.
- * @initial_config: Setup an initial fbdev display configuration
  *
  * Driver callbacks used by the fbdev emulation helper library.
  */
 struct drm_fb_helper_funcs {
+       /**
+        * @gamma_set:
+        *
+        * Set the given gamma LUT register on the given CRTC.
+        *
+        * This callback is optional.
+        *
+        * FIXME:
+        *
+        * This callback is functionally redundant with the core gamma table
+        * support and simply exists because the fbdev hasn't yet been
+        * refactored to use the core gamma table interfaces.
+        */
        void (*gamma_set)(struct drm_crtc *crtc, u16 red, u16 green,
                          u16 blue, int regno);
+       /**
+        * @gamma_get:
+        *
+        * Read the given gamma LUT register on the given CRTC, used to save the
+        * current LUT when force-restoring the fbdev for e.g. kdbg.
+        *
+        * This callback is optional.
+        *
+        * FIXME:
+        *
+        * This callback is functionally redundant with the core gamma table
+        * support and simply exists because the fbdev hasn't yet been
+        * refactored to use the core gamma table interfaces.
+        */
        void (*gamma_get)(struct drm_crtc *crtc, u16 *red, u16 *green,
                          u16 *blue, int regno);
 
+       /**
+        * @fb_probe:
+        *
+        * Driver callback to allocate and initialize the fbdev info structure.
+        * Furthermore it also needs to allocate the DRM framebuffer used to
+        * back the fbdev.
+        *
+        * This callback is mandatory.
+        *
+        * RETURNS:
+        *
+        * The driver should return 0 on success and a negative error code on
+        * failure.
+        */
        int (*fb_probe)(struct drm_fb_helper *helper,
                        struct drm_fb_helper_surface_size *sizes);
+
+       /**
+        * @initial_config:
+        *
+        * Driver callback to setup an initial fbdev display configuration.
+        * Drivers can use this callback to tell the fbdev emulation what the
+        * preferred initial configuration is. This is useful to implement
+        * smooth booting where the fbdev (and subsequently all userspace) never
+        * changes the mode, but always inherits the existing configuration.
+        *
+        * This callback is optional.
+        *
+        * RETURNS:
+        *
+        * The driver should return true if a suitable initial configuration has
+        * been filled out and false when the fbdev helper should fall back to
+        * the default probing logic.
+        */
        bool (*initial_config)(struct drm_fb_helper *fb_helper,
                               struct drm_fb_helper_crtc **crtcs,
                               struct drm_display_mode **modes,
@@ -105,18 +156,22 @@ struct drm_fb_helper_connector {
 };
 
 /**
- * struct drm_fb_helper - helper to emulate fbdev on top of kms
- * @fb:  Scanout framebuffer object
- * @dev:  DRM device
+ * struct drm_fb_helper - main structure to emulate fbdev on top of KMS
+ * @fb: Scanout framebuffer object
+ * @dev: DRM device
  * @crtc_count: number of possible CRTCs
  * @crtc_info: per-CRTC helper state (mode, x/y offset, etc)
  * @connector_count: number of connected connectors
  * @connector_info_alloc_count: size of connector_info
+ * @connector_info: array of per-connector information
  * @funcs: driver callbacks for fb helper
  * @fbdev: emulated fbdev device info struct
  * @pseudo_palette: fake palette of 16 colors
- * @kernel_fb_list: list_head in kernel_fb_helper_list
- * @delayed_hotplug: was there a hotplug while kms master active?
+ *
+ * This is the main structure used by the fbdev helpers. Drivers supporting
+ * fbdev emulation should embedded this into their overall driver structure.
+ * Drivers must also fill out a struct &drm_fb_helper_funcs with a few
+ * operations.
  */
 struct drm_fb_helper {
        struct drm_framebuffer *fb;
@@ -129,10 +184,21 @@ struct drm_fb_helper {
        const struct drm_fb_helper_funcs *funcs;
        struct fb_info *fbdev;
        u32 pseudo_palette[17];
+
+       /**
+        * @kernel_fb_list:
+        *
+        * Entry on the global kernel_fb_helper_list, used for kgdb entry/exit.
+        */
        struct list_head kernel_fb_list;
 
-       /* we got a hotplug but fbdev wasn't running the console
-          delay until next set_par */
+       /**
+        * @delayed_hotplug:
+        *
+        * A hotplug was received while fbdev wasn't in control of the DRM
+        * device, i.e. another KMS master was active. The output configuration
+        * needs to be reprobe when fbdev is in control again.
+        */
        bool delayed_hotplug;
 
        /**