Commit | Line | Data |
---|---|---|
b2441318 | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
1da177e4 LT |
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> | |
a55944ca | 13 | #include <linux/fb.h> |
28ee086d | 14 | #include <linux/mutex.h> |
1da177e4 | 15 | #include <linux/notifier.h> |
0a4be726 | 16 | #include <linux/types.h> |
1da177e4 | 17 | |
2d15bb47 SR |
18 | /** |
19 | * enum backlight_update_reason - what method was used to update backlight | |
20 | * | |
21 | * A driver indicates the method (reason) used for updating the backlight | |
22 | * when calling backlight_force_update(). | |
23 | */ | |
325253a6 | 24 | enum backlight_update_reason { |
2d15bb47 SR |
25 | /** |
26 | * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key. | |
27 | */ | |
325253a6 | 28 | BACKLIGHT_UPDATE_HOTKEY, |
2d15bb47 SR |
29 | |
30 | /** | |
31 | * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs. | |
32 | */ | |
325253a6 MG |
33 | BACKLIGHT_UPDATE_SYSFS, |
34 | }; | |
35 | ||
2d15bb47 SR |
36 | /** |
37 | * enum backlight_type - the type of backlight control | |
38 | * | |
39 | * The type of interface used to control the backlight. | |
40 | */ | |
bb7ca747 | 41 | enum backlight_type { |
2d15bb47 SR |
42 | /** |
43 | * @BACKLIGHT_RAW: | |
44 | * | |
45 | * The backlight is controlled using hardware registers. | |
46 | */ | |
bb7ca747 | 47 | BACKLIGHT_RAW = 1, |
2d15bb47 SR |
48 | |
49 | /** | |
50 | * @BACKLIGHT_PLATFORM: | |
51 | * | |
52 | * The backlight is controlled using a platform-specific interface. | |
53 | */ | |
bb7ca747 | 54 | BACKLIGHT_PLATFORM, |
2d15bb47 SR |
55 | |
56 | /** | |
57 | * @BACKLIGHT_FIRMWARE: | |
58 | * | |
59 | * The backlight is controlled using a standard firmware interface. | |
60 | */ | |
bb7ca747 | 61 | BACKLIGHT_FIRMWARE, |
2d15bb47 SR |
62 | |
63 | /** | |
64 | * @BACKLIGHT_TYPE_MAX: Number of entries. | |
65 | */ | |
bb7ca747 MG |
66 | BACKLIGHT_TYPE_MAX, |
67 | }; | |
68 | ||
2d15bb47 SR |
69 | /** |
70 | * enum backlight_notification - the type of notification | |
71 | * | |
72 | * The notifications that is used for notification sent to the receiver | |
73 | * that registered notifications using backlight_register_notifier(). | |
74 | */ | |
3cc6919b | 75 | enum backlight_notification { |
2d15bb47 SR |
76 | /** |
77 | * @BACKLIGHT_REGISTERED: The backlight device is registered. | |
78 | */ | |
3cc6919b | 79 | BACKLIGHT_REGISTERED, |
2d15bb47 SR |
80 | |
81 | /** | |
82 | * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered. | |
83 | */ | |
3cc6919b HG |
84 | BACKLIGHT_UNREGISTERED, |
85 | }; | |
86 | ||
2d15bb47 SR |
87 | /** enum backlight_scale - the type of scale used for brightness values |
88 | * | |
89 | * The type of scale used for brightness values. | |
90 | */ | |
d55c028f | 91 | enum backlight_scale { |
2d15bb47 SR |
92 | /** |
93 | * @BACKLIGHT_SCALE_UNKNOWN: The scale is unknown. | |
94 | */ | |
d55c028f | 95 | BACKLIGHT_SCALE_UNKNOWN = 0, |
2d15bb47 SR |
96 | |
97 | /** | |
98 | * @BACKLIGHT_SCALE_LINEAR: The scale is linear. | |
99 | * | |
100 | * The linear scale will increase brightness the same for each step. | |
101 | */ | |
d55c028f | 102 | BACKLIGHT_SCALE_LINEAR, |
2d15bb47 SR |
103 | |
104 | /** | |
105 | * @BACKLIGHT_SCALE_NON_LINEAR: The scale is not linear. | |
106 | * | |
107 | * This is often used when the brightness values tries to adjust to | |
108 | * the relative perception of the eye demanding a non-linear scale. | |
109 | */ | |
d55c028f MK |
110 | BACKLIGHT_SCALE_NON_LINEAR, |
111 | }; | |
112 | ||
1da177e4 | 113 | struct backlight_device; |
1da177e4 | 114 | |
ca7c20b2 SR |
115 | /** |
116 | * struct backlight_ops - backlight operations | |
117 | * | |
118 | * The backlight operations are specified when the backlight device is registered. | |
119 | */ | |
599a52d1 | 120 | struct backlight_ops { |
ca7c20b2 SR |
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 | */ | |
b4144e4f | 128 | unsigned int options; |
c835ee7f RP |
129 | |
130 | #define BL_CORE_SUSPENDRESUME (1 << 0) | |
131 | ||
ca7c20b2 SR |
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 | */ | |
b4144e4f | 146 | int (*update_status)(struct backlight_device *); |
ca7c20b2 SR |
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 | */ | |
b4144e4f | 160 | int (*get_brightness)(struct backlight_device *); |
ca7c20b2 SR |
161 | |
162 | /** | |
0a4be726 | 163 | * @controls_device: Check against the display device |
ca7c20b2 | 164 | * |
0a4be726 TZ |
165 | * Check if the backlight controls the given display device. This |
166 | * operation is optional and if not implemented it is assumed that | |
167 | * the display is always the one controlled by the backlight. | |
ca7c20b2 SR |
168 | * |
169 | * RETURNS: | |
170 | * | |
0a4be726 TZ |
171 | * If display_dev is NULL or display_dev matches the device controlled by |
172 | * the backlight, return true. Otherwise return false. | |
ca7c20b2 | 173 | */ |
0a4be726 | 174 | bool (*controls_device)(struct backlight_device *bd, struct device *display_dev); |
599a52d1 | 175 | }; |
6ca01765 | 176 | |
cabf1613 SR |
177 | /** |
178 | * struct backlight_properties - backlight properties | |
179 | * | |
180 | * This structure defines all the properties of a backlight. | |
181 | */ | |
599a52d1 | 182 | struct backlight_properties { |
cabf1613 SR |
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 | */ | |
6ca01765 | 194 | int brightness; |
cabf1613 SR |
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 | */ | |
6ca01765 | 203 | int max_brightness; |
cabf1613 SR |
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 | */ | |
6ca01765 | 219 | int power; |
cabf1613 | 220 | |
cabf1613 SR |
221 | /** |
222 | * @type: The type of backlight supported. | |
223 | * | |
224 | * The backlight type allows userspace to make appropriate | |
225 | * policy decisions based on the backlight type. | |
226 | * | |
227 | * This value must be set in the backlight_properties | |
228 | * passed to devm_backlight_device_register(). | |
229 | */ | |
bb7ca747 | 230 | enum backlight_type type; |
cabf1613 SR |
231 | |
232 | /** | |
233 | * @state: The state of the backlight core. | |
234 | * | |
235 | * The state is a bitmask. BL_CORE_FBBLANK is set when the display | |
236 | * is expected to be blank. BL_CORE_SUSPENDED is set when the | |
237 | * driver is suspended. | |
238 | * | |
239 | * backlight drivers are expected to use backlight_is_blank() | |
240 | * in their update_status() operation rather than reading the | |
241 | * state property. | |
242 | * | |
243 | * The state is maintained by the core and drivers may not modify it. | |
244 | */ | |
c835ee7f RP |
245 | unsigned int state; |
246 | ||
247 | #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ | |
248 | #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */ | |
c835ee7f | 249 | |
cabf1613 SR |
250 | /** |
251 | * @scale: The type of the brightness scale. | |
252 | */ | |
253 | enum backlight_scale scale; | |
1da177e4 LT |
254 | }; |
255 | ||
6f10cd12 SR |
256 | /** |
257 | * struct backlight_device - backlight device data | |
258 | * | |
259 | * This structure holds all data required by a backlight device. | |
260 | */ | |
1da177e4 | 261 | struct backlight_device { |
6f10cd12 SR |
262 | /** |
263 | * @props: Backlight properties | |
264 | */ | |
599a52d1 RP |
265 | struct backlight_properties props; |
266 | ||
6f10cd12 SR |
267 | /** |
268 | * @update_lock: The lock used when calling the update_status() operation. | |
269 | * | |
270 | * update_lock is an internal backlight lock that serialise access | |
271 | * to the update_status() operation. The backlight core holds the update_lock | |
272 | * when calling the update_status() operation. The update_lock shall not | |
273 | * be used by backlight drivers. | |
274 | */ | |
28ee086d | 275 | struct mutex update_lock; |
599a52d1 | 276 | |
6f10cd12 SR |
277 | /** |
278 | * @ops_lock: The lock used around everything related to backlight_ops. | |
279 | * | |
280 | * ops_lock is an internal backlight lock that protects the ops pointer | |
281 | * and is used around all accesses to ops and when the operations are | |
282 | * invoked. The ops_lock shall not be used by backlight drivers. | |
283 | */ | |
599a52d1 | 284 | struct mutex ops_lock; |
6f10cd12 SR |
285 | |
286 | /** | |
287 | * @ops: Pointer to the backlight operations. | |
288 | * | |
289 | * If ops is NULL, the driver that registered this device has been unloaded, | |
290 | * and if class_get_devdata() points to something in the body of that driver, | |
291 | * it is also invalid. | |
292 | */ | |
9905a43b | 293 | const struct backlight_ops *ops; |
599a52d1 | 294 | |
6f10cd12 SR |
295 | /** |
296 | * @fb_notif: The framebuffer notifier block | |
297 | */ | |
1da177e4 | 298 | struct notifier_block fb_notif; |
655bfd7a | 299 | |
6f10cd12 SR |
300 | /** |
301 | * @entry: List entry of all registered backlight devices | |
302 | */ | |
5915a3db AL |
303 | struct list_head entry; |
304 | ||
6f10cd12 SR |
305 | /** |
306 | * @dev: Parent device. | |
307 | */ | |
655bfd7a | 308 | struct device dev; |
a55944ca | 309 | |
6f10cd12 SR |
310 | /** |
311 | * @fb_bl_on: The state of individual fbdev's. | |
312 | * | |
313 | * Multiple fbdev's may share one backlight device. The fb_bl_on | |
314 | * records the state of the individual fbdev. | |
315 | */ | |
a55944ca LY |
316 | bool fb_bl_on[FB_MAX]; |
317 | ||
6f10cd12 SR |
318 | /** |
319 | * @use_count: The number of uses of fb_bl_on. | |
320 | */ | |
a55944ca | 321 | int use_count; |
1da177e4 LT |
322 | }; |
323 | ||
d160fd4e SR |
324 | /** |
325 | * backlight_update_status - force an update of the backlight device status | |
326 | * @bd: the backlight device | |
327 | */ | |
cca0ba2d | 328 | static inline int backlight_update_status(struct backlight_device *bd) |
28ee086d | 329 | { |
cca0ba2d HH |
330 | int ret = -ENOENT; |
331 | ||
28ee086d | 332 | mutex_lock(&bd->update_lock); |
599a52d1 | 333 | if (bd->ops && bd->ops->update_status) |
cca0ba2d | 334 | ret = bd->ops->update_status(bd); |
28ee086d | 335 | mutex_unlock(&bd->update_lock); |
cca0ba2d HH |
336 | |
337 | return ret; | |
28ee086d RP |
338 | } |
339 | ||
5b698be0 MM |
340 | /** |
341 | * backlight_enable - Enable backlight | |
342 | * @bd: the backlight device to enable | |
343 | */ | |
344 | static inline int backlight_enable(struct backlight_device *bd) | |
345 | { | |
346 | if (!bd) | |
347 | return 0; | |
348 | ||
349 | bd->props.power = FB_BLANK_UNBLANK; | |
5b698be0 MM |
350 | bd->props.state &= ~BL_CORE_FBBLANK; |
351 | ||
352 | return backlight_update_status(bd); | |
353 | } | |
354 | ||
355 | /** | |
356 | * backlight_disable - Disable backlight | |
357 | * @bd: the backlight device to disable | |
358 | */ | |
359 | static inline int backlight_disable(struct backlight_device *bd) | |
360 | { | |
361 | if (!bd) | |
362 | return 0; | |
363 | ||
364 | bd->props.power = FB_BLANK_POWERDOWN; | |
5b698be0 MM |
365 | bd->props.state |= BL_CORE_FBBLANK; |
366 | ||
367 | return backlight_update_status(bd); | |
368 | } | |
369 | ||
1c91b465 SR |
370 | /** |
371 | * backlight_is_blank - Return true if display is expected to be blank | |
372 | * @bd: the backlight device | |
373 | * | |
374 | * Display is expected to be blank if any of these is true:: | |
375 | * | |
376 | * 1) if power in not UNBLANK | |
4551978b | 377 | * 2) if state indicate BLANK or SUSPENDED |
1c91b465 SR |
378 | * |
379 | * Returns true if display is expected to be blank, false otherwise. | |
380 | */ | |
381 | static inline bool backlight_is_blank(const struct backlight_device *bd) | |
382 | { | |
383 | return bd->props.power != FB_BLANK_UNBLANK || | |
1c91b465 SR |
384 | bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK); |
385 | } | |
386 | ||
2144d00e SR |
387 | /** |
388 | * backlight_get_brightness - Returns the current brightness value | |
389 | * @bd: the backlight device | |
390 | * | |
391 | * Returns the current brightness value, taking in consideration the current | |
392 | * state. If backlight_is_blank() returns true then return 0 as brightness | |
393 | * otherwise return the current brightness property value. | |
394 | * | |
395 | * Backlight drivers are expected to use this function in their update_status() | |
396 | * operation to get the brightness value. | |
397 | */ | |
398 | static inline int backlight_get_brightness(const struct backlight_device *bd) | |
399 | { | |
400 | if (backlight_is_blank(bd)) | |
401 | return 0; | |
402 | else | |
403 | return bd->props.brightness; | |
404 | } | |
405 | ||
9c4aa311 SR |
406 | struct backlight_device * |
407 | backlight_device_register(const char *name, struct device *dev, void *devdata, | |
408 | const struct backlight_ops *ops, | |
409 | const struct backlight_properties *props); | |
410 | struct backlight_device * | |
411 | devm_backlight_device_register(struct device *dev, const char *name, | |
412 | struct device *parent, void *devdata, | |
413 | const struct backlight_ops *ops, | |
414 | const struct backlight_properties *props); | |
415 | void backlight_device_unregister(struct backlight_device *bd); | |
416 | void devm_backlight_device_unregister(struct device *dev, | |
417 | struct backlight_device *bd); | |
418 | void backlight_force_update(struct backlight_device *bd, | |
419 | enum backlight_update_reason reason); | |
420 | int backlight_register_notifier(struct notifier_block *nb); | |
421 | int backlight_unregister_notifier(struct notifier_block *nb); | |
479da1f5 | 422 | struct backlight_device *backlight_device_get_by_name(const char *name); |
9c4aa311 SR |
423 | struct backlight_device *backlight_device_get_by_type(enum backlight_type type); |
424 | int backlight_device_set_brightness(struct backlight_device *bd, | |
425 | unsigned long brightness); | |
1da177e4 | 426 | |
655bfd7a RP |
427 | #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev) |
428 | ||
d160fd4e SR |
429 | /** |
430 | * bl_get_data - access devdata | |
431 | * @bl_dev: pointer to backlight device | |
432 | * | |
433 | * When a backlight device is registered the driver has the possibility | |
434 | * to supply a void * devdata. bl_get_data() return a pointer to the | |
435 | * devdata. | |
436 | * | |
437 | * RETURNS: | |
438 | * | |
439 | * pointer to devdata stored while registering the backlight device. | |
440 | */ | |
655bfd7a RP |
441 | static inline void * bl_get_data(struct backlight_device *bl_dev) |
442 | { | |
443 | return dev_get_drvdata(&bl_dev->dev); | |
444 | } | |
1da177e4 | 445 | |
762a936f TR |
446 | #ifdef CONFIG_OF |
447 | struct backlight_device *of_find_backlight_by_node(struct device_node *node); | |
448 | #else | |
449 | static inline struct backlight_device * | |
450 | of_find_backlight_by_node(struct device_node *node) | |
451 | { | |
452 | return NULL; | |
453 | } | |
454 | #endif | |
455 | ||
c2adda27 | 456 | #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE) |
2e4ef334 | 457 | struct backlight_device *devm_of_find_backlight(struct device *dev); |
c2adda27 | 458 | #else |
2e4ef334 MM |
459 | static inline struct backlight_device * |
460 | devm_of_find_backlight(struct device *dev) | |
461 | { | |
462 | return NULL; | |
463 | } | |
c2adda27 MM |
464 | #endif |
465 | ||
1da177e4 | 466 | #endif |