backlight.h 6.17 KB
Newer Older
1
/* SPDX-License-Identifier: GPL-2.0 */
Linus Torvalds's avatar
Linus Torvalds committed
2 3 4 5 6 7 8 9 10 11 12
/*
 * Backlight Lowlevel Control Abstraction
 *
 * Copyright (C) 2003,2004 Hewlett-Packard Company
 *
 */

#ifndef _LINUX_BACKLIGHT_H
#define _LINUX_BACKLIGHT_H

#include <linux/device.h>
13
#include <linux/fb.h>
14
#include <linux/mutex.h>
Linus Torvalds's avatar
Linus Torvalds committed
15 16
#include <linux/notifier.h>

17 18
/* Notes on locking:
 *
19 20
 * backlight_device->ops_lock is an internal backlight lock protecting the
 * ops pointer and no code outside the core should need to touch it.
21 22 23 24 25 26 27 28 29 30 31
 *
 * Access to update_status() is serialised by the update_lock mutex since
 * most drivers seem to need this and historically get it wrong.
 *
 * Most drivers don't need locking on their get_brightness() method.
 * If yours does, you need to implement it in the driver. You can use the
 * update_lock mutex if appropriate.
 *
 * Any other use of the locks below is probably wrong.
 */

32 33 34 35 36
enum backlight_update_reason {
	BACKLIGHT_UPDATE_HOTKEY,
	BACKLIGHT_UPDATE_SYSFS,
};

37 38 39 40 41 42 43
enum backlight_type {
	BACKLIGHT_RAW = 1,
	BACKLIGHT_PLATFORM,
	BACKLIGHT_FIRMWARE,
	BACKLIGHT_TYPE_MAX,
};

44 45 46 47 48
enum backlight_notification {
	BACKLIGHT_REGISTERED,
	BACKLIGHT_UNREGISTERED,
};

Linus Torvalds's avatar
Linus Torvalds committed
49 50 51
struct backlight_device;
struct fb_info;

52
struct backlight_ops {
53
	unsigned int options;
54 55 56

#define BL_CORE_SUSPENDRESUME	(1 << 0)

57
	/* Notify the backlight driver some property has changed */
58
	int (*update_status)(struct backlight_device *);
59 60
	/* Return the current backlight brightness (accounting for power,
	   fb_blank etc.) */
61
	int (*get_brightness)(struct backlight_device *);
Linus Torvalds's avatar
Linus Torvalds committed
62 63
	/* Check if given framebuffer device is the one bound to this backlight;
	   return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */
64
	int (*check_fb)(struct backlight_device *, struct fb_info *);
65
};
66

67 68
/* This structure defines all the properties of a backlight */
struct backlight_properties {
69 70 71 72 73 74 75 76
	/* Current User requested brightness (0 - max_brightness) */
	int brightness;
	/* Maximal value for brightness (read-only) */
	int max_brightness;
	/* Current FB Power mode (0: full on, 1..3: power saving
	   modes; 4: full off), see FB_BLANK_XXX */
	int power;
	/* FB Blanking active? (values as for power) */
77
	/* Due to be removed, please use (state & BL_CORE_FBBLANK) */
78
	int fb_blank;
79 80
	/* Backlight type */
	enum backlight_type type;
81 82 83 84 85 86
	/* Flags used to signal drivers of state changes */
	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 */

Linus Torvalds's avatar
Linus Torvalds committed
87 88 89
};

struct backlight_device {
90 91 92
	/* Backlight properties */
	struct backlight_properties props;

93 94
	/* Serialise access to update_status method */
	struct mutex update_lock;
95 96 97 98 99

	/* This protects the 'ops' field. 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. */
	struct mutex ops_lock;
100
	const struct backlight_ops *ops;
101

Linus Torvalds's avatar
Linus Torvalds committed
102 103
	/* The framebuffer notifier block */
	struct notifier_block fb_notif;
104

105 106 107
	/* list entry of all registered backlight devices */
	struct list_head entry;

108
	struct device dev;
109 110 111 112 113

	/* Multiple framebuffers may share one backlight device */
	bool fb_bl_on[FB_MAX];

	int use_count;
Linus Torvalds's avatar
Linus Torvalds committed
114 115
};

116
static inline int backlight_update_status(struct backlight_device *bd)
117
{
118 119
	int ret = -ENOENT;

120
	mutex_lock(&bd->update_lock);
121
	if (bd->ops && bd->ops->update_status)
122
		ret = bd->ops->update_status(bd);
123
	mutex_unlock(&bd->update_lock);
124 125

	return ret;
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
/**
 * 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);
}

160 161 162 163 164 165 166 167 168 169
/**
 * backlight_put - Drop backlight reference
 * @bd: the backlight device to put
 */
static inline void backlight_put(struct backlight_device *bd)
{
	if (bd)
		put_device(&bd->dev);
}

Linus Torvalds's avatar
Linus Torvalds committed
170
extern struct backlight_device *backlight_device_register(const char *name,
171 172
	struct device *dev, void *devdata, const struct backlight_ops *ops,
	const struct backlight_properties *props);
173 174 175 176
extern 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);
Linus Torvalds's avatar
Linus Torvalds committed
177
extern void backlight_device_unregister(struct backlight_device *bd);
178 179
extern void devm_backlight_device_unregister(struct device *dev,
					struct backlight_device *bd);
180 181
extern void backlight_force_update(struct backlight_device *bd,
				   enum backlight_update_reason reason);
182 183
extern int backlight_register_notifier(struct notifier_block *nb);
extern int backlight_unregister_notifier(struct notifier_block *nb);
184 185
extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness);
Linus Torvalds's avatar
Linus Torvalds committed
186

187 188 189 190 191 192
#define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)

static inline void * bl_get_data(struct backlight_device *bl_dev)
{
	return dev_get_drvdata(&bl_dev->dev);
}
Linus Torvalds's avatar
Linus Torvalds committed
193

194 195 196 197 198 199 200 201 202
struct generic_bl_info {
	const char *name;
	int max_intensity;
	int default_intensity;
	int limit_mask;
	void (*set_bl_intensity)(int intensity);
	void (*kick_battery)(void);
};

203 204 205 206 207 208 209 210 211 212
#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

213 214
#if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
struct backlight_device *of_find_backlight(struct device *dev);
215
struct backlight_device *devm_of_find_backlight(struct device *dev);
216 217 218 219 220
#else
static inline struct backlight_device *of_find_backlight(struct device *dev)
{
	return NULL;
}
221 222 223 224 225 226

static inline struct backlight_device *
devm_of_find_backlight(struct device *dev)
{
	return NULL;
}
227 228
#endif

Linus Torvalds's avatar
Linus Torvalds committed
229
#endif