| Message ID | 20200517190139.740249-5-sam@ravnborg.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | backlight updates | expand |
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@ravnborg.org> > Cc: Lee Jones <lee.jones@linaro.org> > Cc: Daniel Thompson <daniel.thompson@linaro.org> > Cc: Jingoo Han <jingoohan1@gmail.com> Reviewed-by: Daniel Thompson <daniel.thompson@linaro.org> > --- > 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 >
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 */
Improve the documentation for backlight_ops and adapt it to kernel-doc style. Signed-off-by: Sam Ravnborg <sam@ravnborg.org> Cc: Lee Jones <lee.jones@linaro.org> Cc: Daniel Thompson <daniel.thompson@linaro.org> Cc: Jingoo Han <jingoohan1@gmail.com> --- include/linux/backlight.h | 60 +++++++++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 6 deletions(-)