1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | /* |
3 | * Backlight Lowlevel Control Abstraction |
4 | * |
5 | * Copyright (C) 2003,2004 Hewlett-Packard Company |
6 | * |
7 | */ |
8 | |
9 | #ifndef _LINUX_BACKLIGHT_H |
10 | #define _LINUX_BACKLIGHT_H |
11 | |
12 | #include <linux/device.h> |
13 | #include <linux/fb.h> |
14 | #include <linux/mutex.h> |
15 | #include <linux/notifier.h> |
16 | |
17 | /** |
18 | * enum backlight_update_reason - what method was used to update backlight |
19 | * |
20 | * A driver indicates the method (reason) used for updating the backlight |
21 | * when calling backlight_force_update(). |
22 | */ |
23 | enum backlight_update_reason { |
24 | /** |
25 | * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key. |
26 | */ |
27 | BACKLIGHT_UPDATE_HOTKEY, |
28 | |
29 | /** |
30 | * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs. |
31 | */ |
32 | BACKLIGHT_UPDATE_SYSFS, |
33 | }; |
34 | |
35 | /** |
36 | * enum backlight_type - the type of backlight control |
37 | * |
38 | * The type of interface used to control the backlight. |
39 | */ |
40 | enum backlight_type { |
41 | /** |
42 | * @BACKLIGHT_RAW: |
43 | * |
44 | * The backlight is controlled using hardware registers. |
45 | */ |
46 | BACKLIGHT_RAW = 1, |
47 | |
48 | /** |
49 | * @BACKLIGHT_PLATFORM: |
50 | * |
51 | * The backlight is controlled using a platform-specific interface. |
52 | */ |
53 | BACKLIGHT_PLATFORM, |
54 | |
55 | /** |
56 | * @BACKLIGHT_FIRMWARE: |
57 | * |
58 | * The backlight is controlled using a standard firmware interface. |
59 | */ |
60 | BACKLIGHT_FIRMWARE, |
61 | |
62 | /** |
63 | * @BACKLIGHT_TYPE_MAX: Number of entries. |
64 | */ |
65 | BACKLIGHT_TYPE_MAX, |
66 | }; |
67 | |
68 | /** |
69 | * enum backlight_notification - the type of notification |
70 | * |
71 | * The notifications that is used for notification sent to the receiver |
72 | * that registered notifications using backlight_register_notifier(). |
73 | */ |
74 | enum backlight_notification { |
75 | /** |
76 | * @BACKLIGHT_REGISTERED: The backlight device is registered. |
77 | */ |
78 | BACKLIGHT_REGISTERED, |
79 | |
80 | /** |
81 | * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered. |
82 | */ |
83 | BACKLIGHT_UNREGISTERED, |
84 | }; |
85 | |
86 | /** enum backlight_scale - the type of scale used for brightness values |
87 | * |
88 | * The type of scale used for brightness values. |
89 | */ |
90 | enum backlight_scale { |
91 | /** |
92 | * @BACKLIGHT_SCALE_UNKNOWN: The scale is unknown. |
93 | */ |
94 | BACKLIGHT_SCALE_UNKNOWN = 0, |
95 | |
96 | /** |
97 | * @BACKLIGHT_SCALE_LINEAR: The scale is linear. |
98 | * |
99 | * The linear scale will increase brightness the same for each step. |
100 | */ |
101 | BACKLIGHT_SCALE_LINEAR, |
102 | |
103 | /** |
104 | * @BACKLIGHT_SCALE_NON_LINEAR: The scale is not linear. |
105 | * |
106 | * This is often used when the brightness values tries to adjust to |
107 | * the relative perception of the eye demanding a non-linear scale. |
108 | */ |
109 | BACKLIGHT_SCALE_NON_LINEAR, |
110 | }; |
111 | |
112 | struct backlight_device; |
113 | struct fb_info; |
114 | |
115 | /** |
116 | * struct backlight_ops - backlight operations |
117 | * |
118 | * The backlight operations are specified when the backlight device is registered. |
119 | */ |
120 | struct backlight_ops { |
121 | /** |
122 | * @options: Configure how operations are called from the core. |
123 | * |
124 | * The options parameter is used to adjust the behaviour of the core. |
125 | * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called |
126 | * upon suspend and resume. |
127 | */ |
128 | unsigned int options; |
129 | |
130 | #define BL_CORE_SUSPENDRESUME (1 << 0) |
131 | |
132 | /** |
133 | * @update_status: Operation called when properties have changed. |
134 | * |
135 | * Notify the backlight driver some property has changed. |
136 | * The update_status operation is protected by the update_lock. |
137 | * |
138 | * The backlight driver is expected to use backlight_is_blank() |
139 | * to check if the display is blanked and set brightness accordingly. |
140 | * update_status() is called when any of the properties has changed. |
141 | * |
142 | * RETURNS: |
143 | * |
144 | * 0 on success, negative error code if any failure occurred. |
145 | */ |
146 | int (*update_status)(struct backlight_device *); |
147 | |
148 | /** |
149 | * @get_brightness: Return the current backlight brightness. |
150 | * |
151 | * The driver may implement this as a readback from the HW. |
152 | * This operation is optional and if not present then the current |
153 | * brightness property value is used. |
154 | * |
155 | * RETURNS: |
156 | * |
157 | * A brightness value which is 0 or a positive number. |
158 | * On failure a negative error code is returned. |
159 | */ |
160 | int (*get_brightness)(struct backlight_device *); |
161 | |
162 | /** |
163 | * @check_fb: Check the framebuffer device. |
164 | * |
165 | * Check if given framebuffer device is the one bound to this backlight. |
166 | * This operation is optional and if not implemented it is assumed that the |
167 | * fbdev is always the one bound to the backlight. |
168 | * |
169 | * RETURNS: |
170 | * |
171 | * If info is NULL or the info matches the fbdev bound to the backlight return true. |
172 | * If info does not match the fbdev bound to the backlight return false. |
173 | */ |
174 | int (*check_fb)(struct backlight_device *bd, struct fb_info *info); |
175 | }; |
176 | |
177 | /** |
178 | * struct backlight_properties - backlight properties |
179 | * |
180 | * This structure defines all the properties of a backlight. |
181 | */ |
182 | struct backlight_properties { |
183 | /** |
184 | * @brightness: The current brightness requested by the user. |
185 | * |
186 | * The backlight core makes sure the range is (0 to max_brightness) |
187 | * when the brightness is set via the sysfs attribute: |
188 | * /sys/class/backlight/<backlight>/brightness. |
189 | * |
190 | * This value can be set in the backlight_properties passed |
191 | * to devm_backlight_device_register() to set a default brightness |
192 | * value. |
193 | */ |
194 | int brightness; |
195 | |
196 | /** |
197 | * @max_brightness: The maximum brightness value. |
198 | * |
199 | * This value must be set in the backlight_properties passed to |
200 | * devm_backlight_device_register() and shall not be modified by the |
201 | * driver after registration. |
202 | */ |
203 | int max_brightness; |
204 | |
205 | /** |
206 | * @power: The current power mode. |
207 | * |
208 | * User space can configure the power mode using the sysfs |
209 | * attribute: /sys/class/backlight/<backlight>/bl_power |
210 | * When the power property is updated update_status() is called. |
211 | * |
212 | * The possible values are: (0: full on, 1 to 3: power saving |
213 | * modes; 4: full off), see FB_BLANK_XXX. |
214 | * |
215 | * When the backlight device is enabled @power is set |
216 | * to FB_BLANK_UNBLANK. When the backlight device is disabled |
217 | * @power is set to FB_BLANK_POWERDOWN. |
218 | */ |
219 | int power; |
220 | |
221 | /** |
222 | * @fb_blank: The power state from the FBIOBLANK ioctl. |
223 | * |
224 | * When the FBIOBLANK ioctl is called @fb_blank is set to the |
225 | * blank parameter and the update_status() operation is called. |
226 | * |
227 | * When the backlight device is enabled @fb_blank is set |
228 | * to FB_BLANK_UNBLANK. When the backlight device is disabled |
229 | * @fb_blank is set to FB_BLANK_POWERDOWN. |
230 | * |
231 | * Backlight drivers should avoid using this property. It has been |
232 | * replaced by state & BL_CORE_FBLANK (although most drivers should |
233 | * use backlight_is_blank() as the preferred means to get the blank |
234 | * state). |
235 | * |
236 | * fb_blank is deprecated and will be removed. |
237 | */ |
238 | int fb_blank; |
239 | |
240 | /** |
241 | * @type: The type of backlight supported. |
242 | * |
243 | * The backlight type allows userspace to make appropriate |
244 | * policy decisions based on the backlight type. |
245 | * |
246 | * This value must be set in the backlight_properties |
247 | * passed to devm_backlight_device_register(). |
248 | */ |
249 | enum backlight_type type; |
250 | |
251 | /** |
252 | * @state: The state of the backlight core. |
253 | * |
254 | * The state is a bitmask. BL_CORE_FBBLANK is set when the display |
255 | * is expected to be blank. BL_CORE_SUSPENDED is set when the |
256 | * driver is suspended. |
257 | * |
258 | * backlight drivers are expected to use backlight_is_blank() |
259 | * in their update_status() operation rather than reading the |
260 | * state property. |
261 | * |
262 | * The state is maintained by the core and drivers may not modify it. |
263 | */ |
264 | unsigned int state; |
265 | |
266 | #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ |
267 | #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */ |
268 | |
269 | /** |
270 | * @scale: The type of the brightness scale. |
271 | */ |
272 | enum backlight_scale scale; |
273 | }; |
274 | |
275 | /** |
276 | * struct backlight_device - backlight device data |
277 | * |
278 | * This structure holds all data required by a backlight device. |
279 | */ |
280 | struct backlight_device { |
281 | /** |
282 | * @props: Backlight properties |
283 | */ |
284 | struct backlight_properties props; |
285 | |
286 | /** |
287 | * @update_lock: The lock used when calling the update_status() operation. |
288 | * |
289 | * update_lock is an internal backlight lock that serialise access |
290 | * to the update_status() operation. The backlight core holds the update_lock |
291 | * when calling the update_status() operation. The update_lock shall not |
292 | * be used by backlight drivers. |
293 | */ |
294 | struct mutex update_lock; |
295 | |
296 | /** |
297 | * @ops_lock: The lock used around everything related to backlight_ops. |
298 | * |
299 | * ops_lock is an internal backlight lock that protects the ops pointer |
300 | * and is used around all accesses to ops and when the operations are |
301 | * invoked. The ops_lock shall not be used by backlight drivers. |
302 | */ |
303 | struct mutex ops_lock; |
304 | |
305 | /** |
306 | * @ops: Pointer to the backlight operations. |
307 | * |
308 | * If ops is NULL, the driver that registered this device has been unloaded, |
309 | * and if class_get_devdata() points to something in the body of that driver, |
310 | * it is also invalid. |
311 | */ |
312 | const struct backlight_ops *ops; |
313 | |
314 | /** |
315 | * @fb_notif: The framebuffer notifier block |
316 | */ |
317 | struct notifier_block fb_notif; |
318 | |
319 | /** |
320 | * @entry: List entry of all registered backlight devices |
321 | */ |
322 | struct list_head entry; |
323 | |
324 | /** |
325 | * @dev: Parent device. |
326 | */ |
327 | struct device dev; |
328 | |
329 | /** |
330 | * @fb_bl_on: The state of individual fbdev's. |
331 | * |
332 | * Multiple fbdev's may share one backlight device. The fb_bl_on |
333 | * records the state of the individual fbdev. |
334 | */ |
335 | bool fb_bl_on[FB_MAX]; |
336 | |
337 | /** |
338 | * @use_count: The number of uses of fb_bl_on. |
339 | */ |
340 | int use_count; |
341 | }; |
342 | |
343 | /** |
344 | * backlight_update_status - force an update of the backlight device status |
345 | * @bd: the backlight device |
346 | */ |
347 | static inline int backlight_update_status(struct backlight_device *bd) |
348 | { |
349 | int ret = -ENOENT; |
350 | |
351 | mutex_lock(&bd->update_lock); |
352 | if (bd->ops && bd->ops->update_status) |
353 | ret = bd->ops->update_status(bd); |
354 | mutex_unlock(lock: &bd->update_lock); |
355 | |
356 | return ret; |
357 | } |
358 | |
359 | /** |
360 | * backlight_enable - Enable backlight |
361 | * @bd: the backlight device to enable |
362 | */ |
363 | static inline int backlight_enable(struct backlight_device *bd) |
364 | { |
365 | if (!bd) |
366 | return 0; |
367 | |
368 | bd->props.power = FB_BLANK_UNBLANK; |
369 | bd->props.fb_blank = FB_BLANK_UNBLANK; |
370 | bd->props.state &= ~BL_CORE_FBBLANK; |
371 | |
372 | return backlight_update_status(bd); |
373 | } |
374 | |
375 | /** |
376 | * backlight_disable - Disable backlight |
377 | * @bd: the backlight device to disable |
378 | */ |
379 | static inline int backlight_disable(struct backlight_device *bd) |
380 | { |
381 | if (!bd) |
382 | return 0; |
383 | |
384 | bd->props.power = FB_BLANK_POWERDOWN; |
385 | bd->props.fb_blank = FB_BLANK_POWERDOWN; |
386 | bd->props.state |= BL_CORE_FBBLANK; |
387 | |
388 | return backlight_update_status(bd); |
389 | } |
390 | |
391 | /** |
392 | * backlight_is_blank - Return true if display is expected to be blank |
393 | * @bd: the backlight device |
394 | * |
395 | * Display is expected to be blank if any of these is true:: |
396 | * |
397 | * 1) if power in not UNBLANK |
398 | * 2) if fb_blank is not UNBLANK |
399 | * 3) if state indicate BLANK or SUSPENDED |
400 | * |
401 | * Returns true if display is expected to be blank, false otherwise. |
402 | */ |
403 | static inline bool backlight_is_blank(const struct backlight_device *bd) |
404 | { |
405 | return bd->props.power != FB_BLANK_UNBLANK || |
406 | bd->props.fb_blank != FB_BLANK_UNBLANK || |
407 | bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK); |
408 | } |
409 | |
410 | /** |
411 | * backlight_get_brightness - Returns the current brightness value |
412 | * @bd: the backlight device |
413 | * |
414 | * Returns the current brightness value, taking in consideration the current |
415 | * state. If backlight_is_blank() returns true then return 0 as brightness |
416 | * otherwise return the current brightness property value. |
417 | * |
418 | * Backlight drivers are expected to use this function in their update_status() |
419 | * operation to get the brightness value. |
420 | */ |
421 | static inline int backlight_get_brightness(const struct backlight_device *bd) |
422 | { |
423 | if (backlight_is_blank(bd)) |
424 | return 0; |
425 | else |
426 | return bd->props.brightness; |
427 | } |
428 | |
429 | struct backlight_device * |
430 | backlight_device_register(const char *name, struct device *dev, void *devdata, |
431 | const struct backlight_ops *ops, |
432 | const struct backlight_properties *props); |
433 | struct backlight_device * |
434 | devm_backlight_device_register(struct device *dev, const char *name, |
435 | struct device *parent, void *devdata, |
436 | const struct backlight_ops *ops, |
437 | const struct backlight_properties *props); |
438 | void backlight_device_unregister(struct backlight_device *bd); |
439 | void devm_backlight_device_unregister(struct device *dev, |
440 | struct backlight_device *bd); |
441 | void backlight_force_update(struct backlight_device *bd, |
442 | enum backlight_update_reason reason); |
443 | int backlight_register_notifier(struct notifier_block *nb); |
444 | int backlight_unregister_notifier(struct notifier_block *nb); |
445 | struct backlight_device *backlight_device_get_by_name(const char *name); |
446 | struct backlight_device *backlight_device_get_by_type(enum backlight_type type); |
447 | int backlight_device_set_brightness(struct backlight_device *bd, |
448 | unsigned long brightness); |
449 | |
450 | #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev) |
451 | |
452 | /** |
453 | * bl_get_data - access devdata |
454 | * @bl_dev: pointer to backlight device |
455 | * |
456 | * When a backlight device is registered the driver has the possibility |
457 | * to supply a void * devdata. bl_get_data() return a pointer to the |
458 | * devdata. |
459 | * |
460 | * RETURNS: |
461 | * |
462 | * pointer to devdata stored while registering the backlight device. |
463 | */ |
464 | static inline void * bl_get_data(struct backlight_device *bl_dev) |
465 | { |
466 | return dev_get_drvdata(dev: &bl_dev->dev); |
467 | } |
468 | |
469 | #ifdef CONFIG_OF |
470 | struct backlight_device *of_find_backlight_by_node(struct device_node *node); |
471 | #else |
472 | static inline struct backlight_device * |
473 | of_find_backlight_by_node(struct device_node *node) |
474 | { |
475 | return NULL; |
476 | } |
477 | #endif |
478 | |
479 | #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE) |
480 | struct backlight_device *devm_of_find_backlight(struct device *dev); |
481 | #else |
482 | static inline struct backlight_device * |
483 | devm_of_find_backlight(struct device *dev) |
484 | { |
485 | return NULL; |
486 | } |
487 | #endif |
488 | |
489 | #endif |
490 | |