backlight.h

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