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 | /* Notes on locking: |
18 | * |
19 | * backlight_device->ops_lock is an internal backlight lock protecting the |
20 | * ops pointer and no code outside the core should need to touch it. |
21 | * |
22 | * Access to update_status() is serialised by the update_lock mutex since |
23 | * most drivers seem to need this and historically get it wrong. |
24 | * |
25 | * Most drivers don't need locking on their get_brightness() method. |
26 | * If yours does, you need to implement it in the driver. You can use the |
27 | * update_lock mutex if appropriate. |
28 | * |
29 | * Any other use of the locks below is probably wrong. |
30 | */ |
31 | |
32 | enum backlight_update_reason { |
33 | BACKLIGHT_UPDATE_HOTKEY, |
34 | BACKLIGHT_UPDATE_SYSFS, |
35 | }; |
36 | |
37 | enum backlight_type { |
38 | BACKLIGHT_RAW = 1, |
39 | BACKLIGHT_PLATFORM, |
40 | BACKLIGHT_FIRMWARE, |
41 | BACKLIGHT_TYPE_MAX, |
42 | }; |
43 | |
44 | enum backlight_notification { |
45 | BACKLIGHT_REGISTERED, |
46 | BACKLIGHT_UNREGISTERED, |
47 | }; |
48 | |
49 | struct backlight_device; |
50 | struct fb_info; |
51 | |
52 | struct backlight_ops { |
53 | unsigned int options; |
54 | |
55 | #define BL_CORE_SUSPENDRESUME (1 << 0) |
56 | |
57 | /* Notify the backlight driver some property has changed */ |
58 | int (*update_status)(struct backlight_device *); |
59 | /* Return the current backlight brightness (accounting for power, |
60 | fb_blank etc.) */ |
61 | int (*get_brightness)(struct backlight_device *); |
62 | /* Check if given framebuffer device is the one bound to this backlight; |
63 | 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 | /* This structure defines all the properties of a backlight */ |
68 | struct backlight_properties { |
69 | /* Current User requested brightness (0 - max_brightness) */ |
70 | int brightness; |
71 | /* Maximal value for brightness (read-only) */ |
72 | int max_brightness; |
73 | /* Current FB Power mode (0: full on, 1..3: power saving |
74 | modes; 4: full off), see FB_BLANK_XXX */ |
75 | int power; |
76 | /* FB Blanking active? (values as for power) */ |
77 | /* Due to be removed, please use (state & BL_CORE_FBBLANK) */ |
78 | int fb_blank; |
79 | /* Backlight type */ |
80 | enum backlight_type type; |
81 | /* Flags used to signal drivers of state changes */ |
82 | unsigned int state; |
83 | |
84 | #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ |
85 | #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */ |
86 | |
87 | }; |
88 | |
89 | struct backlight_device { |
90 | /* Backlight properties */ |
91 | struct backlight_properties props; |
92 | |
93 | /* Serialise access to update_status method */ |
94 | struct mutex update_lock; |
95 | |
96 | /* This protects the 'ops' field. If 'ops' is NULL, the driver that |
97 | registered this device has been unloaded, and if class_get_devdata() |
98 | points to something in the body of that driver, it is also invalid. */ |
99 | struct mutex ops_lock; |
100 | const struct backlight_ops *ops; |
101 | |
102 | /* The framebuffer notifier block */ |
103 | struct notifier_block fb_notif; |
104 | |
105 | /* list entry of all registered backlight devices */ |
106 | struct list_head entry; |
107 | |
108 | struct device dev; |
109 | |
110 | /* Multiple framebuffers may share one backlight device */ |
111 | bool fb_bl_on[FB_MAX]; |
112 | |
113 | int use_count; |
114 | }; |
115 | |
116 | static inline int backlight_update_status(struct backlight_device *bd) |
117 | { |
118 | int ret = -ENOENT; |
119 | |
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 | * backlight_enable - Enable backlight |
130 | * @bd: the backlight device to enable |
131 | */ |
132 | static inline int backlight_enable(struct backlight_device *bd) |
133 | { |
134 | if (!bd) |
135 | return 0; |
136 | |
137 | bd->props.power = FB_BLANK_UNBLANK; |
138 | bd->props.fb_blank = FB_BLANK_UNBLANK; |
139 | bd->props.state &= ~BL_CORE_FBBLANK; |
140 | |
141 | return backlight_update_status(bd); |
142 | } |
143 | |
144 | /** |
145 | * backlight_disable - Disable backlight |
146 | * @bd: the backlight device to disable |
147 | */ |
148 | static inline int backlight_disable(struct backlight_device *bd) |
149 | { |
150 | if (!bd) |
151 | return 0; |
152 | |
153 | bd->props.power = FB_BLANK_POWERDOWN; |
154 | bd->props.fb_blank = FB_BLANK_POWERDOWN; |
155 | bd->props.state |= BL_CORE_FBBLANK; |
156 | |
157 | return backlight_update_status(bd); |
158 | } |
159 | |
160 | /** |
161 | * backlight_put - Drop backlight reference |
162 | * @bd: the backlight device to put |
163 | */ |
164 | static inline void backlight_put(struct backlight_device *bd) |
165 | { |
166 | if (bd) |
167 | put_device(&bd->dev); |
168 | } |
169 | |
170 | extern struct backlight_device *backlight_device_register(const char *name, |
171 | struct device *dev, void *devdata, const struct backlight_ops *ops, |
172 | const struct backlight_properties *props); |
173 | extern struct backlight_device *devm_backlight_device_register( |
174 | struct device *dev, const char *name, struct device *parent, |
175 | void *devdata, const struct backlight_ops *ops, |
176 | const struct backlight_properties *props); |
177 | extern void backlight_device_unregister(struct backlight_device *bd); |
178 | extern void devm_backlight_device_unregister(struct device *dev, |
179 | struct backlight_device *bd); |
180 | extern void backlight_force_update(struct backlight_device *bd, |
181 | enum backlight_update_reason reason); |
182 | extern int backlight_register_notifier(struct notifier_block *nb); |
183 | extern int backlight_unregister_notifier(struct notifier_block *nb); |
184 | extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type); |
185 | extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness); |
186 | |
187 | #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev) |
188 | |
189 | static inline void * bl_get_data(struct backlight_device *bl_dev) |
190 | { |
191 | return dev_get_drvdata(&bl_dev->dev); |
192 | } |
193 | |
194 | struct generic_bl_info { |
195 | const char *name; |
196 | int max_intensity; |
197 | int default_intensity; |
198 | int limit_mask; |
199 | void (*set_bl_intensity)(int intensity); |
200 | void (*kick_battery)(void); |
201 | }; |
202 | |
203 | #ifdef CONFIG_OF |
204 | struct backlight_device *of_find_backlight_by_node(struct device_node *node); |
205 | #else |
206 | static inline struct backlight_device * |
207 | of_find_backlight_by_node(struct device_node *node) |
208 | { |
209 | return NULL; |
210 | } |
211 | #endif |
212 | |
213 | #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE) |
214 | struct backlight_device *of_find_backlight(struct device *dev); |
215 | struct backlight_device *devm_of_find_backlight(struct device *dev); |
216 | #else |
217 | static inline struct backlight_device *of_find_backlight(struct device *dev) |
218 | { |
219 | return NULL; |
220 | } |
221 | |
222 | static inline struct backlight_device * |
223 | devm_of_find_backlight(struct device *dev) |
224 | { |
225 | return NULL; |
226 | } |
227 | #endif |
228 | |
229 | #endif |
230 | |