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

Commit 207fd329 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/fb-helper: improve kerneldoc 



Now that the fbdev helper interface for drivers is trimmed down,
update the kerneldoc for all the remaining exported functions.

I've tried to beat the DocBook a bit by reordering the function
references a bit into a more sensible ordering. But that didn't work
out at all. Hence just extend the in-code DOC: section a bit.

Also remove the LOCKING: sections - especially for the setup functions
they're totally bogus. But that's not a documentation problem, but
simply an artifact of the current rather hazardous locking around drm
init and even more so around fbdev setup ...

v2: Some further improvements:
- Also add documentation for drm_fb_helper_single_add_all_connectors,
  Dave Airlie didn't want me to kill this one from the fb helper
  interface.
- Update docs for drm_fb_helper_fill_var/fix - they should be used
  from the driver's ->fb_probe callback to setup the fbdev info
  structure.
- Clarify what the ->fb_probe callback should all do - it needs to
  setup both the fbdev info and allocate the drm framebuffer used as
  backing storage.
- Add basic documentaation for the drm_fb_helper_funcs driver callback
  vfunc.

v3: Implement clarifications Laurent Pinchart suggested in his review.

v4: Fix another mispelling Laurent spotted.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent cd5428a5

Documentation/DocBook/drm.tmpl

+1 −0
Original line number Diff line number Diff line
@@ -2143,6 +2143,7 @@ void intel_crt_init(struct drm_device *dev) 
      <title>fbdev Helper Functions Reference</title>

!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers

!Edrivers/gpu/drm/drm_fb_helper.c

!Iinclude/drm/drm_fb_helper.h

    </sect2>

    <sect2>

      <title>Display Port Helper Functions Reference</title>

drivers/gpu/drm/drm_fb_helper.c

+133 −15
Original line number Diff line number Diff line
@@ -52,9 +52,36 @@ static LIST_HEAD(kernel_fb_helper_list); 
 * mode setting driver. They can be used mostly independantely from the crtc

 * helper functions used by many drivers to implement the kernel mode setting

 * interfaces.

 *

 * Initialization is done as a three-step process with drm_fb_helper_init(),

 * drm_fb_helper_single_add_all_connectors() and drm_fb_helper_initial_config().

 * Drivers with fancier requirements than the default beheviour can override the

 * second step with their own code.  Teardown is done with drm_fb_helper_fini().

 *

 * At runtime drivers should restore the fbdev console by calling

 * drm_fb_helper_restore_fbdev_mode() from their ->lastclose callback. They

 * should also notify the fb helper code from updates to the output

 * configuration by calling drm_fb_helper_hotplug_event(). For easier

 * integration with the output polling code in drm_crtc_helper.c the modeset

 * code proves a ->output_poll_changed callback.

 *

 * All other functions exported by the fb helper library can be used to

 * implement the fbdev driver interface by the driver.

 */



/* simple single crtc case helper function */

/**

 * drm_fb_helper_single_add_all_connectors() - add all connectors to fbdev

 * 					       emulation helper

 * @fb_helper: fbdev initialized with drm_fb_helper_init

 *

 * This functions adds all the available connectors for use with the given

 * fb_helper. This is a separate step to allow drivers to freely assign

 * connectors to the fbdev, e.g. if some are reserved for special purposes or

 * not adequate to be used for the fbcon.

 *

 * Since this is part of the initial setup before the fbdev is published, no

 * locking is required.

 */

int drm_fb_helper_single_add_all_connectors(struct drm_fb_helper *fb_helper)

{

	struct drm_device *dev = fb_helper->dev;
@@ -163,6 +190,10 @@ static void drm_fb_helper_restore_lut_atomic(struct drm_crtc *crtc) 
	crtc->funcs->gamma_set(crtc, r_base, g_base, b_base, 0, crtc->gamma_size);

}



/**

 * drm_fb_helper_debug_enter - implementation for ->fb_debug_enter

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_debug_enter(struct fb_info *info)

{

	struct drm_fb_helper *helper = info->par;
@@ -208,6 +239,10 @@ static struct drm_framebuffer *drm_mode_config_fb(struct drm_crtc *crtc) 
	return NULL;

}



/**

 * drm_fb_helper_debug_leave - implementation for ->fb_debug_leave

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_debug_leave(struct fb_info *info)

{

	struct drm_fb_helper *helper = info->par;
@@ -243,9 +278,9 @@ EXPORT_SYMBOL(drm_fb_helper_debug_leave); 
 * drm_fb_helper_restore_fbdev_mode - restore fbdev configuration

 * @fb_helper: fbcon to restore

 *

 * This should be called from driver's drm->lastclose callback when implementing

 * an fbcon on top of kms using this helper. This ensures that the user isn't

 * greeted with a black screen when e.g. X dies.

 * This should be called from driver's drm ->lastclose callback

 * when implementing an fbcon on top of kms using this helper. This ensures that

 * the user isn't greeted with a black screen when e.g. X dies.

 */

bool drm_fb_helper_restore_fbdev_mode(struct drm_fb_helper *fb_helper)

{
@@ -381,6 +416,11 @@ static void drm_fb_helper_dpms(struct fb_info *info, int dpms_mode) 
	drm_modeset_unlock_all(dev);

}



/**

 * drm_fb_helper_blank - implementation for ->fb_blank

 * @blank: desired blanking state

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_blank(int blank, struct fb_info *info)

{

	switch (blank) {
@@ -424,6 +464,24 @@ static void drm_fb_helper_crtc_free(struct drm_fb_helper *helper) 
	kfree(helper->crtc_info);

}



/**

 * drm_fb_helper_init - initialize a drm_fb_helper structure

 * @dev: drm device

 * @fb_helper: driver-allocated fbdev helper structure to initialize

 * @crtc_count: maximum number of crtcs to support in this fbdev emulation

 * @max_conn_count: max connector count

 *

 * This allocates the structures for the fbdev helper with the given limits.

 * Note that this won't yet touch the hardware (through the driver interfaces)

 * nor register the fbdev. This is only done in drm_fb_helper_initial_config()

 * to allow driver writes more control over the exact init sequence.

 *

 * Drivers must set fb_helper->funcs before calling

 * drm_fb_helper_initial_config().

 *

 * RETURNS:

 * Zero if everything went ok, nonzero otherwise.

 */

int drm_fb_helper_init(struct drm_device *dev,

		       struct drm_fb_helper *fb_helper,

		       int crtc_count, int max_conn_count)
@@ -552,6 +610,11 @@ static int setcolreg(struct drm_crtc *crtc, u16 red, u16 green, 
	return 0;

}



/**

 * drm_fb_helper_setcmap - implementation for ->fb_setcmap

 * @cmap: cmap to set

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info)

{

	struct drm_fb_helper *fb_helper = info->par;
@@ -591,6 +654,11 @@ int drm_fb_helper_setcmap(struct fb_cmap *cmap, struct fb_info *info) 
}

EXPORT_SYMBOL(drm_fb_helper_setcmap);



/**

 * drm_fb_helper_check_var - implementation for ->fb_check_var

 * @var: screeninfo to check

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_check_var(struct fb_var_screeninfo *var,

			    struct fb_info *info)

{
@@ -683,7 +751,14 @@ int drm_fb_helper_check_var(struct fb_var_screeninfo *var, 
}

EXPORT_SYMBOL(drm_fb_helper_check_var);



/* this will let fbcon do the mode init */

/**

 * drm_fb_helper_set_par - implementation for ->fb_set_par

 * @info: fbdev registered by the helper

 *

 * This will let fbcon do the mode init and is called at initialization time by

 * the fbdev core when registering the driver, and later on through the hotplug

 * callback.

 */

int drm_fb_helper_set_par(struct fb_info *info)

{

	struct drm_fb_helper *fb_helper = info->par;
@@ -715,6 +790,11 @@ int drm_fb_helper_set_par(struct fb_info *info) 
}

EXPORT_SYMBOL(drm_fb_helper_set_par);



/**

 * drm_fb_helper_pan_display - implementation for ->fb_pan_display

 * @var: updated screen information

 * @info: fbdev registered by the helper

 */

int drm_fb_helper_pan_display(struct fb_var_screeninfo *var,

			      struct fb_info *info)

{
@@ -753,8 +833,9 @@ int drm_fb_helper_pan_display(struct fb_var_screeninfo *var, 
EXPORT_SYMBOL(drm_fb_helper_pan_display);



/*

 * Allocates the backing storage through the ->fb_probe callback and then

 * registers the fbdev and sets up the panic notifier.

 * Allocates the backing storage and sets up the fbdev info structure through

 * the ->fb_probe callback and then registers the fbdev and sets up the panic

 * notifier.

 */

static int drm_fb_helper_single_fb_probe(struct drm_fb_helper *fb_helper,

					 int preferred_bpp)
@@ -876,6 +957,19 @@ static int drm_fb_helper_single_fb_probe(struct drm_fb_helper *fb_helper, 
	return 0;

}



/**

 * drm_fb_helper_fill_fix - initializes fixed fbdev information

 * @info: fbdev registered by the helper

 * @pitch: desired pitch

 * @depth: desired depth

 *

 * Helper to fill in the fixed fbdev information useful for a non-accelerated

 * fbdev emulations. Drivers which support acceleration methods which impose

 * additional constraints need to set up their own limits.

 *

 * Drivers should call this (or their equivalent setup code) from their

 * ->fb_probe callback.

 */

void drm_fb_helper_fill_fix(struct fb_info *info, uint32_t pitch,

			    uint32_t depth)

{
@@ -896,6 +990,20 @@ void drm_fb_helper_fill_fix(struct fb_info *info, uint32_t pitch, 
}

EXPORT_SYMBOL(drm_fb_helper_fill_fix);



/**

 * drm_fb_helper_fill_var - initalizes variable fbdev information

 * @info: fbdev instance to set up

 * @fb_helper: fb helper instance to use as template

 * @fb_width: desired fb width

 * @fb_height: desired fb height

 *

 * Sets up the variable fbdev metainformation from the given fb helper instance

 * and the drm framebuffer allocated in fb_helper->fb.

 *

 * Drivers should call this (or their equivalent setup code) from their

 * ->fb_probe callback after having allocated the fbdev backing

 * storage framebuffer.

 */

void drm_fb_helper_fill_var(struct fb_info *info, struct drm_fb_helper *fb_helper,

			    uint32_t fb_width, uint32_t fb_height)

{
@@ -1358,18 +1466,23 @@ static void drm_setup_crtcs(struct drm_fb_helper *fb_helper) 
}



/**

 * drm_helper_initial_config - setup a sane initial connector configuration

 * drm_fb_helper_initial_config - setup a sane initial connector configuration

 * @fb_helper: fb_helper device struct

 * @bpp_sel: bpp value to use for the framebuffer configuration

 *

 * LOCKING:

 * Called at init time by the driver to set up the @fb_helper initial

 * configuration, must take the mode config lock.

 *

 * Scans the CRTCs and connectors and tries to put together an initial setup.

 * At the moment, this is a cloned configuration across all heads with

 * a new framebuffer object as the backing store.

 *

 * Note that this also registers the fbdev and so allows userspace to call into

 * the driver through the fbdev interfaces.

 *

 * This function will call down into the ->fb_probe callback to let

 * the driver allocate and initialize the fbdev info structure and the drm

 * framebuffer used to back the fbdev. drm_fb_helper_fill_var() and

 * drm_fb_helper_fill_fix() are provided as helpers to setup simple default

 * values for the fbdev info structure.

 *

 * RETURNS:

 * Zero if everything went ok, nonzero otherwise.

 */
@@ -1400,12 +1513,17 @@ EXPORT_SYMBOL(drm_fb_helper_initial_config); 
 *                               probing all the outputs attached to the fb

 * @fb_helper: the drm_fb_helper

 *

 * LOCKING:

 * Called at runtime, must take mode config lock.

 *

 * Scan the connectors attached to the fb_helper and try to put together a

 * setup after *notification of a change in output configuration.

 *

 * Called at runtime, takes the mode config locks to be able to check/change the

 * modeset configuration. Must be run from process context (which usually means

 * either the output polling work or a work item launched from the driver's

 * hotplug interrupt).

 *

 * Note that the driver must ensure that this is only called _after_ the fb has

 * been fully set up, i.e. after the call to drm_fb_helper_initial_config.

 *

 * RETURNS:

 * 0 on success and a non-zero error code otherwise.

 */

include/drm/drm_fb_helper.h

+12 −0
Original line number Diff line number Diff line
@@ -48,6 +48,18 @@ struct drm_fb_helper_surface_size { 
	u32 surface_depth;

};



/**

 * 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. Futhermore it also needs to allocate the drm

 * 		framebuffer used to back the fbdev.

 *

 * Driver callbacks used by the fbdev emulation helper library.

 */

struct drm_fb_helper_funcs {

	void (*gamma_set)(struct drm_crtc *crtc, u16 red, u16 green,

			  u16 blue, int regno);