On Mon, Jun 01, 2020 at 08:51:58AM +0200, Sam Ravnborg wrote:
Improve the documentation for backlight_properties and adapt it to kernel-doc style.
v2:
- Added into for each field (Daniel)
- Re-written some parts to explain what to do, rather than what not to do. Partly based on suggestions from the review (Daniel)
Signed-off-by: Sam Ravnborg sam@ravnborg.org
Reviewed-by: Daniel Thompson daniel.thompson@linaro.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 | 96 ++++++++++++++++++++++++++++++++++----- 1 file changed, 85 insertions(+), 11 deletions(-)
diff --git a/include/linux/backlight.h b/include/linux/backlight.h index b6c1ab6c922a..69a20da03035 100644 --- a/include/linux/backlight.h +++ b/include/linux/backlight.h @@ -117,28 +117,102 @@ struct backlight_ops { int (*check_fb)(struct backlight_device *bd, struct fb_info *info); };
-/* This structure defines all the properties of a backlight */ +/**
- struct backlight_properties - backlight properties
- This structure defines all the properties of a backlight.
- */
struct backlight_properties {
- /* Current User requested brightness (0 - max_brightness) */
- /**
* @brightness: The current brightness requested by the user.** The backlight core makes sure the range is (0 to max_brightness)* when the brightness is set via the sysfs attribute:* /sys/class/backlight/<backlight>/brightness.** This value can be set in the backlight_properties passed* to devm_backlight_device_register() to set a default brightness* value.*/
- /* Maximal value for brightness (read-only) */
- /**
* @max_brightness: The maximum brightness value.** This value must be set in the backlight_properties passed to* devm_backlight_device_register() and shall not be modified by the* driver after registration.*/
- /* Current FB Power mode (0: full on, 1..3: power saving
modes; 4: full off), see FB_BLANK_XXX */
- /**
* @power: The current power mode.** User space can configure the power mode using the sysfs* attribute: /sys/class/backlight/<backlight>/bl_power* When the power property is updated update_status() is called.** The possible values are: (0: full on, 1 to 3: power saving* modes; 4: full off), see FB_BLANK_XXX.** When the backlight device is enabled @power is set* to FB_BLANK_UNBLANK. When the backlight device is disabled* @power is set to FB_BLANK_POWERDOWN.*/
- /* FB Blanking active? (values as for power) */
- /* Due to be removed, please use (state & BL_CORE_FBBLANK) */
- /**
* @fb_blank: The power state from the FBIOBLANK ioclt.** When the FBIOBLANK ioctl is called fb_blank is set to the* blank parameter and the update_status() operation is called.** When the backlight device is enabled @fb_blank is set* to FB_BLANK_UNBLANK. When the backlight device is disabled* @fb_blank is set to FB_BLANK_POWERDOWN.** Backlight drivers should avoid using this property. It has been* replaced by state & BL_CORE_FBLANK (although most drivers should* use backlight_is_blank() as the preferred means to get the blank* state).** fb_blank is deprecated and will be removed.*/
- /* Backlight type */
- /**
* @type: The type of backlight supported.** The backlight type allows userspace to make appropriate* policy desicions based on the backlight type.** This value must be set in the backlight_properties* passed to devm_backlight_device_register().*/
- /* Flags used to signal drivers of state changes */
- /**
* @state: The state of the backlight core.** The state is a bitmask. BL_CORE_FBBLANK is set when the display* is expected to be blank. BL_CORE_SUSPENDED is set when the* driver is suspended.** backlight drivers are excpected to use backlight_is_blank()* in their update_status() operation rather than reading the* state property.** The state is maintained by the core and drivers may not modify it.*/
- /* Type of the brightness scale (linear, non-linear, ...) */
- enum backlight_scale scale;
#define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */
- /**
* @scale: The type of the brightness scale.*/- enum backlight_scale scale;
};
struct backlight_device {
2.25.1