1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Backlight Lowlevel Control Abstraction
5 * Copyright (C) 2003,2004 Hewlett-Packard Company
9 #ifndef _LINUX_BACKLIGHT_H
10 #define _LINUX_BACKLIGHT_H
12 #include <linux/device.h>
14 #include <linux/mutex.h>
15 #include <linux/notifier.h>
19 * backlight_device->ops_lock is an internal backlight lock protecting the
20 * ops pointer and no code outside the core should need to touch it.
22 * Access to update_status() is serialised by the update_lock mutex since
23 * most drivers seem to need this and historically get it wrong.
25 * Most drivers don't need locking on their get_brightness() method.
26 * If yours does, you need to implement it in the driver. You can use the
27 * update_lock mutex if appropriate.
29 * Any other use of the locks below is probably wrong.
32 enum backlight_update_reason {
33 BACKLIGHT_UPDATE_HOTKEY,
34 BACKLIGHT_UPDATE_SYSFS,
44 enum backlight_notification {
46 BACKLIGHT_UNREGISTERED,
49 enum backlight_scale {
50 BACKLIGHT_SCALE_UNKNOWN = 0,
51 BACKLIGHT_SCALE_LINEAR,
52 BACKLIGHT_SCALE_NON_LINEAR,
55 struct backlight_device;
59 * struct backlight_ops - backlight operations
61 * The backlight operations are specified when the backlight device is registered.
63 struct backlight_ops {
65 * @options: Configure how operations are called from the core.
67 * The options parameter is used to adjust the behaviour of the core.
68 * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called
69 * upon suspend and resume.
73 #define BL_CORE_SUSPENDRESUME (1 << 0)
76 * @update_status: Operation called when properties have changed.
78 * Notify the backlight driver some property has changed.
79 * The update_status operation is protected by the update_lock.
81 * The backlight driver is expected to use backlight_is_blank()
82 * to check if the display is blanked and set brightness accordingly.
83 * update_status() is called when any of the properties has changed.
87 * 0 on success, negative error code if any failure occurred.
89 int (*update_status)(struct backlight_device *);
92 * @get_brightness: Return the current backlight brightness.
94 * The driver may implement this as a readback from the HW.
95 * This operation is optional and if not present then the current
96 * brightness property value is used.
100 * A brightness value which is 0 or a positive number.
101 * On failure a negative error code is returned.
103 int (*get_brightness)(struct backlight_device *);
106 * @check_fb: Check the framebuffer device.
108 * Check if given framebuffer device is the one bound to this backlight.
109 * This operation is optional and if not implemented it is assumed that the
110 * fbdev is always the one bound to the backlight.
114 * If info is NULL or the info matches the fbdev bound to the backlight return true.
115 * If info does not match the fbdev bound to the backlight return false.
117 int (*check_fb)(struct backlight_device *bd, struct fb_info *info);
121 * struct backlight_properties - backlight properties
123 * This structure defines all the properties of a backlight.
125 struct backlight_properties {
127 * @brightness: The current brightness requested by the user.
129 * The backlight core makes sure the range is (0 to max_brightness)
130 * when the brightness is set via the sysfs attribute:
131 * /sys/class/backlight/<backlight>/brightness.
133 * This value can be set in the backlight_properties passed
134 * to devm_backlight_device_register() to set a default brightness
140 * @max_brightness: The maximum brightness value.
142 * This value must be set in the backlight_properties passed to
143 * devm_backlight_device_register() and shall not be modified by the
144 * driver after registration.
149 * @power: The current power mode.
151 * User space can configure the power mode using the sysfs
152 * attribute: /sys/class/backlight/<backlight>/bl_power
153 * When the power property is updated update_status() is called.
155 * The possible values are: (0: full on, 1 to 3: power saving
156 * modes; 4: full off), see FB_BLANK_XXX.
158 * When the backlight device is enabled @power is set
159 * to FB_BLANK_UNBLANK. When the backlight device is disabled
160 * @power is set to FB_BLANK_POWERDOWN.
165 * @fb_blank: The power state from the FBIOBLANK ioctl.
167 * When the FBIOBLANK ioctl is called @fb_blank is set to the
168 * blank parameter and the update_status() operation is called.
170 * When the backlight device is enabled @fb_blank is set
171 * to FB_BLANK_UNBLANK. When the backlight device is disabled
172 * @fb_blank is set to FB_BLANK_POWERDOWN.
174 * Backlight drivers should avoid using this property. It has been
175 * replaced by state & BL_CORE_FBLANK (although most drivers should
176 * use backlight_is_blank() as the preferred means to get the blank
179 * fb_blank is deprecated and will be removed.
184 * @type: The type of backlight supported.
186 * The backlight type allows userspace to make appropriate
187 * policy decisions based on the backlight type.
189 * This value must be set in the backlight_properties
190 * passed to devm_backlight_device_register().
192 enum backlight_type type;
195 * @state: The state of the backlight core.
197 * The state is a bitmask. BL_CORE_FBBLANK is set when the display
198 * is expected to be blank. BL_CORE_SUSPENDED is set when the
199 * driver is suspended.
201 * backlight drivers are expected to use backlight_is_blank()
202 * in their update_status() operation rather than reading the
205 * The state is maintained by the core and drivers may not modify it.
209 #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */
210 #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */
213 * @scale: The type of the brightness scale.
215 enum backlight_scale scale;
218 struct backlight_device {
219 /* Backlight properties */
220 struct backlight_properties props;
222 /* Serialise access to update_status method */
223 struct mutex update_lock;
225 /* This protects the 'ops' field. If 'ops' is NULL, the driver that
226 registered this device has been unloaded, and if class_get_devdata()
227 points to something in the body of that driver, it is also invalid. */
228 struct mutex ops_lock;
229 const struct backlight_ops *ops;
231 /* The framebuffer notifier block */
232 struct notifier_block fb_notif;
234 /* list entry of all registered backlight devices */
235 struct list_head entry;
239 /* Multiple framebuffers may share one backlight device */
240 bool fb_bl_on[FB_MAX];
245 static inline int backlight_update_status(struct backlight_device *bd)
249 mutex_lock(&bd->update_lock);
250 if (bd->ops && bd->ops->update_status)
251 ret = bd->ops->update_status(bd);
252 mutex_unlock(&bd->update_lock);
258 * backlight_enable - Enable backlight
259 * @bd: the backlight device to enable
261 static inline int backlight_enable(struct backlight_device *bd)
266 bd->props.power = FB_BLANK_UNBLANK;
267 bd->props.fb_blank = FB_BLANK_UNBLANK;
268 bd->props.state &= ~BL_CORE_FBBLANK;
270 return backlight_update_status(bd);
274 * backlight_disable - Disable backlight
275 * @bd: the backlight device to disable
277 static inline int backlight_disable(struct backlight_device *bd)
282 bd->props.power = FB_BLANK_POWERDOWN;
283 bd->props.fb_blank = FB_BLANK_POWERDOWN;
284 bd->props.state |= BL_CORE_FBBLANK;
286 return backlight_update_status(bd);
290 * backlight_put - Drop backlight reference
291 * @bd: the backlight device to put
293 static inline void backlight_put(struct backlight_device *bd)
296 put_device(&bd->dev);
300 * backlight_is_blank - Return true if display is expected to be blank
301 * @bd: the backlight device
303 * Display is expected to be blank if any of these is true::
305 * 1) if power in not UNBLANK
306 * 2) if fb_blank is not UNBLANK
307 * 3) if state indicate BLANK or SUSPENDED
309 * Returns true if display is expected to be blank, false otherwise.
311 static inline bool backlight_is_blank(const struct backlight_device *bd)
313 return bd->props.power != FB_BLANK_UNBLANK ||
314 bd->props.fb_blank != FB_BLANK_UNBLANK ||
315 bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK);
318 extern struct backlight_device *backlight_device_register(const char *name,
319 struct device *dev, void *devdata, const struct backlight_ops *ops,
320 const struct backlight_properties *props);
321 extern struct backlight_device *devm_backlight_device_register(
322 struct device *dev, const char *name, struct device *parent,
323 void *devdata, const struct backlight_ops *ops,
324 const struct backlight_properties *props);
325 extern void backlight_device_unregister(struct backlight_device *bd);
326 extern void devm_backlight_device_unregister(struct device *dev,
327 struct backlight_device *bd);
328 extern void backlight_force_update(struct backlight_device *bd,
329 enum backlight_update_reason reason);
330 extern int backlight_register_notifier(struct notifier_block *nb);
331 extern int backlight_unregister_notifier(struct notifier_block *nb);
332 extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
333 struct backlight_device *backlight_device_get_by_name(const char *name);
334 extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness);
336 #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)
338 static inline void * bl_get_data(struct backlight_device *bl_dev)
340 return dev_get_drvdata(&bl_dev->dev);
343 struct generic_bl_info {
346 int default_intensity;
348 void (*set_bl_intensity)(int intensity);
349 void (*kick_battery)(void);
353 struct backlight_device *of_find_backlight_by_node(struct device_node *node);
355 static inline struct backlight_device *
356 of_find_backlight_by_node(struct device_node *node)
362 #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
363 struct backlight_device *of_find_backlight(struct device *dev);
364 struct backlight_device *devm_of_find_backlight(struct device *dev);
366 static inline struct backlight_device *of_find_backlight(struct device *dev)
371 static inline struct backlight_device *
372 devm_of_find_backlight(struct device *dev)