On Sun, May 17, 2020 at 09:01:27PM +0200, Sam Ravnborg wrote:
> Improve the documentation for backlight_ops and
> adapt it to kernel-doc style.
>
> Signed-off-by: Sam Ravnborg <sam@xxxxxxxxxxxx>
> Cc: Lee Jones <lee.jones@xxxxxxxxxx>
> Cc: Daniel Thompson <daniel.thompson@xxxxxxxxxx>
> Cc: Jingoo Han <jingoohan1@xxxxxxxxx>
Reviewed-by: Daniel Thompson <daniel.thompson@xxxxxxxxxx>
> ---
> include/linux/backlight.h | 60 +++++++++++++++++++++++++++++++++++----
> 1 file changed, 54 insertions(+), 6 deletions(-)
>
> diff --git a/include/linux/backlight.h b/include/linux/backlight.h
> index a0a083b35c47..519dc61ce7e4 100644
> --- a/include/linux/backlight.h
> +++ b/include/linux/backlight.h
> @@ -55,19 +55,67 @@ enum backlight_scale {
> struct backlight_device;
> struct fb_info;
>
> +/**
> + * struct backlight_ops - backlight operations
> + *
> + * The backlight operations are specifed when the backlight device is registered.
> + */
> struct backlight_ops {
> + /**
> + * @options:
> + *
> + * The options parameter is used to adjust the behaviour of the core.
> + * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called
> + * upon suspend and resume.
> + */
> unsigned int options;
>
> #define BL_CORE_SUSPENDRESUME (1 << 0)
>
> - /* Notify the backlight driver some property has changed */
> + /**
> + * @update_status:
> + *
> + * Notify the backlight driver some property has changed.
> + * The update_status operation is protected by the update_lock.
> + *
> + * The backlight driver is expected to use backlight_is_blank()
> + * to check if the display is blanked and set brightness accordingly.
> + * update_status() is called when any of the properties has changed.
> + *
> + * RETURNS:
> + *
> + * 0 on sucees, negative error code if any failure occured.
> + */
> int (*update_status)(struct backlight_device *);
> - /* Return the current backlight brightness (accounting for power,
> - fb_blank etc.) */
> +
> + /**
> + * @get_brightness:
> + *
> + * Return the current backlight brightness.
> + * The driver may implement this as a readback from the HW.
> + * This operation is optional and if not present then the current brightness
> + * property value is used.
> + *
> + * RETURNS:
> + *
> + * A brightness value which is 0 or a positive numer.
> + * On failure a negative error code is returned.
> + */
> int (*get_brightness)(struct backlight_device *);
> - /* Check if given framebuffer device is the one bound to this backlight;
> - return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */
> - int (*check_fb)(struct backlight_device *, struct fb_info *);
> +
> + /**
> + * @check_fb:
> + *
> + * Check if given framebuffer device is the one bound to this backlight.
> + * This operation is optional and if not implemented it is assumed that the
> + * fbdev is always the one bound to the backlight.
> + *
> + * RETURNS:
> + *
> + * If info is NULL or the info matches the fbdev bound to the backlight return true.
> + * If info does not match the fbdev bound to the backlight return false.
> + */
> + int (*check_fb)(struct backlight_device *bd, struct fb_info *info);
> };
>
> /* This structure defines all the properties of a backlight */
> --
> 2.25.1
>
