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

Commit 264d6970 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

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: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-2-git-send-email-daniel.vetter@ffwll.ch


Reviewed-by: default avatarThierry Reding <treding@nvidia.com>
parent e876b41a

include/drm/drm_fb_helper.h

+81 −15
Original line number Diff line number Diff line
@@ -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

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



	/**