aboutsummaryrefslogtreecommitdiff
path: root/include/linux/backlight.h
blob: 614653e07e3a860fdf4de9f7e355508783d3f64c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
/* SPDX-License-Identifier: GPL-2.0 */
/*
 * Backlight Lowlevel Control Abstraction
 *
 * Copyright (C) 2003,2004 Hewlett-Packard Company
 *
 */

#ifndef _LINUX_BACKLIGHT_H
#define _LINUX_BACKLIGHT_H

#include <linux/device.h>
#include <linux/fb.h>
#include <linux/mutex.h>
#include <linux/notifier.h>

/**
 * enum backlight_update_reason - what method was used to update backlight
 *
 * A driver indicates the method (reason) used for updating the backlight
 * when calling backlight_force_update().
 */
enum backlight_update_reason {
	/**
	 * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key.
	 */
	BACKLIGHT_UPDATE_HOTKEY,

	/**
	 * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs.
	 */
	BACKLIGHT_UPDATE_SYSFS,
};

/**
 * enum backlight_type - the type of backlight control
 *
 * The type of interface used to control the backlight.
 */
enum backlight_type {
	/**
	 * @BACKLIGHT_RAW:
	 *
	 * The backlight is controlled using hardware registers.
	 */
	BACKLIGHT_RAW = 1,

	/**
	 * @BACKLIGHT_PLATFORM:
	 *
	 * The backlight is controlled using a platform-specific interface.
	 */
	BACKLIGHT_PLATFORM,

	/**
	 * @BACKLIGHT_FIRMWARE:
	 *
	 * The backlight is controlled using a standard firmware interface.
	 */
	BACKLIGHT_FIRMWARE,

	/**
	 * @BACKLIGHT_TYPE_MAX: Number of entries.
	 */
	BACKLIGHT_TYPE_MAX,
};

/**
 * enum backlight_notification - the type of notification
 *
 * The notifications that is used for notification sent to the receiver
 * that registered notifications using backlight_register_notifier().
 */
enum backlight_notification {
	/**
	 * @BACKLIGHT_REGISTERED: The backlight device is registered.
	 */
	BACKLIGHT_REGISTERED,

	/**
	 * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered.
	 */
	BACKLIGHT_UNREGISTERED,
};

/** enum backlight_scale - the type of scale used for brightness values
 *
 * The type of scale used for brightness values.
 */
enum backlight_scale {
	/**
	 * @BACKLIGHT_SCALE_UNKNOWN: The scale is unknown.
	 */
	BACKLIGHT_SCALE_UNKNOWN = 0,

	/**
	 * @BACKLIGHT_SCALE_LINEAR: The scale is linear.
	 *
	 * The linear scale will increase brightness the same for each step.
	 */
	BACKLIGHT_SCALE_LINEAR,

	/**
	 * @BACKLIGHT_SCALE_NON_LINEAR: The scale is not linear.
	 *
	 * This is often used when the brightness values tries to adjust to
	 * the relative perception of the eye demanding a non-linear scale.
	 */
	BACKLIGHT_SCALE_NON_LINEAR,
};

struct backlight_device;
struct fb_info;

/**
 * struct backlight_ops - backlight operations
 *
 * The backlight operations are specified when the backlight device is registered.
 */
struct backlight_ops {
	/**
	 * @options: Configure how operations are called from the core.
	 *
	 * 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)

	/**
	 * @update_status: Operation called when properties have changed.
	 *
	 * 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 success, negative error code if any failure occurred.
	 */
	int (*update_status)(struct backlight_device *);

	/**
	 * @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 number.
	 * On failure a negative error code is returned.
	 */
	int (*get_brightness)(struct backlight_device *);

	/**
	 * @check_fb: Check the framebuffer device.
	 *
	 * 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);
};

/**
 * struct backlight_properties - backlight properties
 *
 * This structure defines all the properties of a backlight.
 */
struct backlight_properties {
	/**
	 * @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.
	 */
	int brightness;

	/**
	 * @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.
	 */
	int max_brightness;

	/**
	 * @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.
	 */
	int power;

	/**
	 * @fb_blank: The power state from the FBIOBLANK ioctl.
	 *
	 * 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.
	 */
	int fb_blank;

	/**
	 * @type: The type of backlight supported.
	 *
	 * The backlight type allows userspace to make appropriate
	 * policy decisions based on the backlight type.
	 *
	 * This value must be set in the backlight_properties
	 * passed to devm_backlight_device_register().
	 */
	enum backlight_type type;

	/**
	 * @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 expected 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.
	 */
	unsigned int state;

#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 - backlight device data
 *
 * This structure holds all data required by a backlight device.
 */
struct backlight_device {
	/**
	 * @props: Backlight properties
	 */
	struct backlight_properties props;

	/**
	 * @update_lock: The lock used when calling the update_status() operation.
	 *
	 * update_lock is an internal backlight lock that serialise access
	 * to the update_status() operation. The backlight core holds the update_lock
	 * when calling the update_status() operation. The update_lock shall not
	 * be used by backlight drivers.
	 */
	struct mutex update_lock;

	/**
	 * @ops_lock: The lock used around everything related to backlight_ops.
	 *
	 * ops_lock is an internal backlight lock that protects the ops pointer
	 * and is used around all accesses to ops and when the operations are
	 * invoked. The ops_lock shall not be used by backlight drivers.
	 */
	struct mutex ops_lock;

	/**
	 * @ops: Pointer to the backlight operations.
	 *
	 * If ops is NULL, the driver that registered this device has been unloaded,
	 * and if class_get_devdata() points to something in the body of that driver,
	 * it is also invalid.
	 */
	const struct backlight_ops *ops;

	/**
	 * @fb_notif: The framebuffer notifier block
	 */
	struct notifier_block fb_notif;

	/**
	 * @entry: List entry of all registered backlight devices
	 */
	struct list_head entry;

	/**
	 * @dev: Parent device.
	 */
	struct device dev;

	/**
	 * @fb_bl_on: The state of individual fbdev's.
	 *
	 * Multiple fbdev's may share one backlight device. The fb_bl_on
	 * records the state of the individual fbdev.
	 */
	bool fb_bl_on[FB_MAX];

	/**
	 * @use_count: The number of uses of fb_bl_on.
	 */
	int use_count;
};

/**
 * backlight_update_status - force an update of the backlight device status
 * @bd: the backlight device
 */
static inline int backlight_update_status(struct backlight_device *bd)
{
	int ret = -ENOENT;

	mutex_lock(&bd->update_lock);
	if (bd->ops && bd->ops->update_status)
		ret = bd->ops->update_status(bd);
	mutex_unlock(&bd->update_lock);

	return ret;
}

/**
 * backlight_enable - Enable backlight
 * @bd: the backlight device to enable
 */
static inline int backlight_enable(struct backlight_device *bd)
{
	if (!bd)
		return 0;

	bd->props.power = FB_BLANK_UNBLANK;
	bd->props.fb_blank = FB_BLANK_UNBLANK;
	bd->props.state &= ~BL_CORE_FBBLANK;

	return backlight_update_status(bd);
}

/**
 * backlight_disable - Disable backlight
 * @bd: the backlight device to disable
 */
static inline int backlight_disable(struct backlight_device *bd)
{
	if (!bd)
		return 0;

	bd->props.power = FB_BLANK_POWERDOWN;
	bd->props.fb_blank = FB_BLANK_POWERDOWN;
	bd->props.state |= BL_CORE_FBBLANK;

	return backlight_update_status(bd);
}

/**
 * backlight_is_blank - Return true if display is expected to be blank
 * @bd: the backlight device
 *
 * Display is expected to be blank if any of these is true::
 *
 *   1) if power in not UNBLANK
 *   2) if fb_blank is not UNBLANK
 *   3) if state indicate BLANK or SUSPENDED
 *
 * Returns true if display is expected to be blank, false otherwise.
 */
static inline bool backlight_is_blank(const struct backlight_device *bd)
{
	return bd->props.power != FB_BLANK_UNBLANK ||
	       bd->props.fb_blank != FB_BLANK_UNBLANK ||
	       bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK);
}

/**
 * backlight_get_brightness - Returns the current brightness value
 * @bd: the backlight device
 *
 * Returns the current brightness value, taking in consideration the current
 * state. If backlight_is_blank() returns true then return 0 as brightness
 * otherwise return the current brightness property value.
 *
 * Backlight drivers are expected to use this function in their update_status()
 * operation to get the brightness value.
 */
static inline int backlight_get_brightness(const struct backlight_device *bd)
{
	if (backlight_is_blank(bd))
		return 0;
	else
		return bd->props.brightness;
}

struct backlight_device *
backlight_device_register(const char *name, struct device *dev, void *devdata,
			  const struct backlight_ops *ops,
			  const struct backlight_properties *props);
struct backlight_device *
devm_backlight_device_register(struct device *dev, const char *name,
			       struct device *parent, void *devdata,
			       const struct backlight_ops *ops,
			       const struct backlight_properties *props);
void backlight_device_unregister(struct backlight_device *bd);
void devm_backlight_device_unregister(struct device *dev,
				      struct backlight_device *bd);
void backlight_force_update(struct backlight_device *bd,
			    enum backlight_update_reason reason);
int backlight_register_notifier(struct notifier_block *nb);
int backlight_unregister_notifier(struct notifier_block *nb);
struct backlight_device *backlight_device_get_by_name(const char *name);
struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
int backlight_device_set_brightness(struct backlight_device *bd,
				    unsigned long brightness);

#define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)

/**
 * bl_get_data - access devdata
 * @bl_dev: pointer to backlight device
 *
 * When a backlight device is registered the driver has the possibility
 * to supply a void * devdata. bl_get_data() return a pointer to the
 * devdata.
 *
 * RETURNS:
 *
 * pointer to devdata stored while registering the backlight device.
 */
static inline void * bl_get_data(struct backlight_device *bl_dev)
{
	return dev_get_drvdata(&bl_dev->dev);
}

#ifdef CONFIG_OF
struct backlight_device *of_find_backlight_by_node(struct device_node *node);
#else
static inline struct backlight_device *
of_find_backlight_by_node(struct device_node *node)
{
	return NULL;
}
#endif

#if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
struct backlight_device *devm_of_find_backlight(struct device *dev);
#else
static inline struct backlight_device *
devm_of_find_backlight(struct device *dev)
{
	return NULL;
}
#endif

#endif