diff mbox series

[v2,04/16] backlight: improve backlight_ops documentation

Message ID 20200517190139.740249-5-sam@ravnborg.org (mailing list archive)
State New, archived
Headers show
Series backlight updates | expand

Commit Message

Sam Ravnborg May 17, 2020, 7:01 p.m. UTC
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(-)

Comments

Daniel Thompson May 18, 2020, 3:02 p.m. UTC | #1
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 mbox series

Patch

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