forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-05-10 093a6c67005148ae32a5c9e4553491b9f5c2457b 
 kernel/include/linux/backlight.h
....@@ -13,113 +13,337 @@
1313 #include <linux/fb.h>
1414 #include <linux/mutex.h>
1515 #include <linux/notifier.h>
16
-#include <linux/thermal.h>
1716 
18
-/* Notes on locking:
17
+/**
18
+ * enum backlight_update_reason - what method was used to update backlight
1919  *
20
- * backlight_device->ops_lock is an internal backlight lock protecting the
21
- * ops pointer and no code outside the core should need to touch it.
22
- *
23
- * Access to update_status() is serialised by the update_lock mutex since
24
- * most drivers seem to need this and historically get it wrong.
25
- *
26
- * Most drivers don't need locking on their get_brightness() method.
27
- * If yours does, you need to implement it in the driver. You can use the
28
- * update_lock mutex if appropriate.
29
- *
30
- * Any other use of the locks below is probably wrong.
20
+ * A driver indicates the method (reason) used for updating the backlight
21
+ * when calling backlight_force_update().
3122  */
32
-
3323 enum backlight_update_reason {
24
+	/**
25
+	 * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key.
26
+	 */
3427 	BACKLIGHT_UPDATE_HOTKEY,
28
+
29
+	/**
30
+	 * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs.
31
+	 */
3532 	BACKLIGHT_UPDATE_SYSFS,
3633 };
3734 
35
+/**
36
+ * enum backlight_type - the type of backlight control
37
+ *
38
+ * The type of interface used to control the backlight.
39
+ */
3840 enum backlight_type {
41
+	/**
42
+	 * @BACKLIGHT_RAW:
43
+	 *
44
+	 * The backlight is controlled using hardware registers.
45
+	 */
3946 	BACKLIGHT_RAW = 1,
47
+
48
+	/**
49
+	 * @BACKLIGHT_PLATFORM:
50
+	 *
51
+	 * The backlight is controlled using a platform-specific interface.
52
+	 */
4053 	BACKLIGHT_PLATFORM,
54
+
55
+	/**
56
+	 * @BACKLIGHT_FIRMWARE:
57
+	 *
58
+	 * The backlight is controlled using a standard firmware interface.
59
+	 */
4160 	BACKLIGHT_FIRMWARE,
61
+
62
+	/**
63
+	 * @BACKLIGHT_TYPE_MAX: Number of entries.
64
+	 */
4265 	BACKLIGHT_TYPE_MAX,
4366 };
4467 
68
+/**
69
+ * enum backlight_notification - the type of notification
70
+ *
71
+ * The notifications that is used for notification sent to the receiver
72
+ * that registered notifications using backlight_register_notifier().
73
+ */
4574 enum backlight_notification {
75
+	/**
76
+	 * @BACKLIGHT_REGISTERED: The backlight device is registered.
77
+	 */
4678 	BACKLIGHT_REGISTERED,
79
+
80
+	/**
81
+	 * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered.
82
+	 */
4783 	BACKLIGHT_UNREGISTERED,
84
+};
85
+
86
+/** enum backlight_scale - the type of scale used for brightness values
87
+ *
88
+ * The type of scale used for brightness values.
89
+ */
90
+enum backlight_scale {
91
+	/**
92
+	 * @BACKLIGHT_SCALE_UNKNOWN: The scale is unknown.
93
+	 */
94
+	BACKLIGHT_SCALE_UNKNOWN = 0,
95
+
96
+	/**
97
+	 * @BACKLIGHT_SCALE_LINEAR: The scale is linear.
98
+	 *
99
+	 * The linear scale will increase brightness the same for each step.
100
+	 */
101
+	BACKLIGHT_SCALE_LINEAR,
102
+
103
+	/**
104
+	 * @BACKLIGHT_SCALE_NON_LINEAR: The scale is not linear.
105
+	 *
106
+	 * This is often used when the brightness values tries to adjust to
107
+	 * the relative perception of the eye demanding a non-linear scale.
108
+	 */
109
+	BACKLIGHT_SCALE_NON_LINEAR,
48110 };
49111 
50112 struct backlight_device;
51113 struct fb_info;
52114 
115
+/**
116
+ * struct backlight_ops - backlight operations
117
+ *
118
+ * The backlight operations are specified when the backlight device is registered.
119
+ */
53120 struct backlight_ops {
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
+	 */
54128 	unsigned int options;
55129 
56130 #define BL_CORE_SUSPENDRESUME	(1 << 0)
57131 
58
-	/* Notify the backlight driver some property has changed */
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
+	 */
59146 	int (*update_status)(struct backlight_device *);
60
-	/* Return the current backlight brightness (accounting for power,
61
-	   fb_blank etc.) */
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
+	 */
62160 	int (*get_brightness)(struct backlight_device *);
63
-	/* Check if given framebuffer device is the one bound to this backlight;
64
-	   return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */
65
-	int (*check_fb)(struct backlight_device *, struct fb_info *);
161
+
162
+	/**
163
+	 * @check_fb: Check the framebuffer device.
164
+	 *
165
+	 * Check if given framebuffer device is the one bound to this backlight.
166
+	 * This operation is optional and if not implemented it is assumed that the
167
+	 * fbdev is always the one bound to the backlight.
168
+	 *
169
+	 * RETURNS:
170
+	 *
171
+	 * If info is NULL or the info matches the fbdev bound to the backlight return true.
172
+	 * If info does not match the fbdev bound to the backlight return false.
173
+	 */
174
+	int (*check_fb)(struct backlight_device *bd, struct fb_info *info);
66175 };
67176 
68
-/* This structure defines all the properties of a backlight */
177
+/**
178
+ * struct backlight_properties - backlight properties
179
+ *
180
+ * This structure defines all the properties of a backlight.
181
+ */
69182 struct backlight_properties {
70
-	/* Current User requested brightness (0 - max_brightness) */
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
+	 */
71194 	int brightness;
72
-	/* Maximal value for brightness (read-only) */
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
+	 */
73203 	int max_brightness;
74
-	/* Current FB Power mode (0: full on, 1..3: power saving
75
-	   modes; 4: full off), see FB_BLANK_XXX */
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
+	 */
76219 	int power;
77
-	/* FB Blanking active? (values as for power) */
78
-	/* Due to be removed, please use (state & BL_CORE_FBBLANK) */
220
+
221
+	/**
222
+	 * @fb_blank: The power state from the FBIOBLANK ioctl.
223
+	 *
224
+	 * When the FBIOBLANK ioctl is called @fb_blank is set to the
225
+	 * blank parameter and the update_status() operation is called.
226
+	 *
227
+	 * When the backlight device is enabled @fb_blank is set
228
+	 * to FB_BLANK_UNBLANK. When the backlight device is disabled
229
+	 * @fb_blank is set to FB_BLANK_POWERDOWN.
230
+	 *
231
+	 * Backlight drivers should avoid using this property. It has been
232
+	 * replaced by state & BL_CORE_FBLANK (although most drivers should
233
+	 * use backlight_is_blank() as the preferred means to get the blank
234
+	 * state).
235
+	 *
236
+	 * fb_blank is deprecated and will be removed.
237
+	 */
79238 	int fb_blank;
80
-	/* Backlight type */
239
+
240
+	/**
241
+	 * @type: The type of backlight supported.
242
+	 *
243
+	 * The backlight type allows userspace to make appropriate
244
+	 * policy decisions based on the backlight type.
245
+	 *
246
+	 * This value must be set in the backlight_properties
247
+	 * passed to devm_backlight_device_register().
248
+	 */
81249 	enum backlight_type type;
82
-	/* Flags used to signal drivers of state changes */
250
+
251
+	/**
252
+	 * @state: The state of the backlight core.
253
+	 *
254
+	 * The state is a bitmask. BL_CORE_FBBLANK is set when the display
255
+	 * is expected to be blank. BL_CORE_SUSPENDED is set when the
256
+	 * driver is suspended.
257
+	 *
258
+	 * backlight drivers are expected to use backlight_is_blank()
259
+	 * in their update_status() operation rather than reading the
260
+	 * state property.
261
+	 *
262
+	 * The state is maintained by the core and drivers may not modify it.
263
+	 */
83264 	unsigned int state;
84265 
85266 #define BL_CORE_SUSPENDED	(1 << 0)	/* backlight is suspended */
86267 #define BL_CORE_FBBLANK		(1 << 1)	/* backlight is under an fb blank event */
87268 
269
+	/**
270
+	 * @scale: The type of the brightness scale.
271
+	 */
272
+	enum backlight_scale scale;
88273 };
89274 
275
+/**
276
+ * struct backlight_device - backlight device data
277
+ *
278
+ * This structure holds all data required by a backlight device.
279
+ */
90280 struct backlight_device {
91
-	/* Backlight properties */
281
+	/**
282
+	 * @props: Backlight properties
283
+	 */
92284 	struct backlight_properties props;
93285 
94
-	/* Serialise access to update_status method */
286
+	/**
287
+	 * @update_lock: The lock used when calling the update_status() operation.
288
+	 *
289
+	 * update_lock is an internal backlight lock that serialise access
290
+	 * to the update_status() operation. The backlight core holds the update_lock
291
+	 * when calling the update_status() operation. The update_lock shall not
292
+	 * be used by backlight drivers.
293
+	 */
95294 	struct mutex update_lock;
96295 
97
-	/* This protects the 'ops' field. If 'ops' is NULL, the driver that
98
-	   registered this device has been unloaded, and if class_get_devdata()
99
-	   points to something in the body of that driver, it is also invalid. */
296
+	/**
297
+	 * @ops_lock: The lock used around everything related to backlight_ops.
298
+	 *
299
+	 * ops_lock is an internal backlight lock that protects the ops pointer
300
+	 * and is used around all accesses to ops and when the operations are
301
+	 * invoked. The ops_lock shall not be used by backlight drivers.
302
+	 */
100303 	struct mutex ops_lock;
304
+
305
+	/**
306
+	 * @ops: Pointer to the backlight operations.
307
+	 *
308
+	 * If ops is NULL, the driver that registered this device has been unloaded,
309
+	 * and if class_get_devdata() points to something in the body of that driver,
310
+	 * it is also invalid.
311
+	 */
101312 	const struct backlight_ops *ops;
102313 
103
-	/* The framebuffer notifier block */
314
+	/**
315
+	 * @fb_notif: The framebuffer notifier block
316
+	 */
104317 	struct notifier_block fb_notif;
105318 
106
-	/* list entry of all registered backlight devices */
319
+	/**
320
+	 * @entry: List entry of all registered backlight devices
321
+	 */
107322 	struct list_head entry;
108323 
324
+	/**
325
+	 * @dev: Parent device.
326
+	 */
109327 	struct device dev;
110
-	/* Backlight cooling device */
111
-	struct thermal_cooling_device *cdev;
112
-	/* Thermally limited max brightness */
113
-	int thermal_brightness_limit;
114
-	/* User brightness request */
115
-	int usr_brightness_req;
116328 
117
-	/* Multiple framebuffers may share one backlight device */
329
+	/**
330
+	 * @fb_bl_on: The state of individual fbdev's.
331
+	 *
332
+	 * Multiple fbdev's may share one backlight device. The fb_bl_on
333
+	 * records the state of the individual fbdev.
334
+	 */
118335 	bool fb_bl_on[FB_MAX];
119336 
337
+	/**
338
+	 * @use_count: The number of uses of fb_bl_on.
339
+	 */
120340 	int use_count;
121341 };
122342 
343
+/**
344
+ * backlight_update_status - force an update of the backlight device status
345
+ * @bd: the backlight device
346
+ */
123347 static inline int backlight_update_status(struct backlight_device *bd)
124348 {
125349 	int ret = -ENOENT;
....@@ -165,47 +389,82 @@
165389 }
166390 
167391 /**
168
- * backlight_put - Drop backlight reference
169
- * @bd: the backlight device to put
392
+ * backlight_is_blank - Return true if display is expected to be blank
393
+ * @bd: the backlight device
394
+ *
395
+ * Display is expected to be blank if any of these is true::
396
+ *
397
+ *   1) if power in not UNBLANK
398
+ *   2) if fb_blank is not UNBLANK
399
+ *   3) if state indicate BLANK or SUSPENDED
400
+ *
401
+ * Returns true if display is expected to be blank, false otherwise.
170402  */
171
-static inline void backlight_put(struct backlight_device *bd)
403
+static inline bool backlight_is_blank(const struct backlight_device *bd)
172404 {
173
-	if (bd)
174
-		put_device(&bd->dev);
405
+	return bd->props.power != FB_BLANK_UNBLANK ||
406
+	       bd->props.fb_blank != FB_BLANK_UNBLANK ||
407
+	       bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK);
175408 }
176409 
177
-extern struct backlight_device *backlight_device_register(const char *name,
178
-	struct device *dev, void *devdata, const struct backlight_ops *ops,
179
-	const struct backlight_properties *props);
180
-extern struct backlight_device *devm_backlight_device_register(
181
-	struct device *dev, const char *name, struct device *parent,
182
-	void *devdata, const struct backlight_ops *ops,
183
-	const struct backlight_properties *props);
184
-extern void backlight_device_unregister(struct backlight_device *bd);
185
-extern void devm_backlight_device_unregister(struct device *dev,
186
-					struct backlight_device *bd);
187
-extern void backlight_force_update(struct backlight_device *bd,
188
-				   enum backlight_update_reason reason);
189
-extern int backlight_register_notifier(struct notifier_block *nb);
190
-extern int backlight_unregister_notifier(struct notifier_block *nb);
191
-extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
192
-extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness);
410
+/**
411
+ * backlight_get_brightness - Returns the current brightness value
412
+ * @bd: the backlight device
413
+ *
414
+ * Returns the current brightness value, taking in consideration the current
415
+ * state. If backlight_is_blank() returns true then return 0 as brightness
416
+ * otherwise return the current brightness property value.
417
+ *
418
+ * Backlight drivers are expected to use this function in their update_status()
419
+ * operation to get the brightness value.
420
+ */
421
+static inline int backlight_get_brightness(const struct backlight_device *bd)
422
+{
423
+	if (backlight_is_blank(bd))
424
+		return 0;
425
+	else
426
+		return bd->props.brightness;
427
+}
428
+
429
+struct backlight_device *
430
+backlight_device_register(const char *name, struct device *dev, void *devdata,
431
+			  const struct backlight_ops *ops,
432
+			  const struct backlight_properties *props);
433
+struct backlight_device *
434
+devm_backlight_device_register(struct device *dev, const char *name,
435
+			       struct device *parent, void *devdata,
436
+			       const struct backlight_ops *ops,
437
+			       const struct backlight_properties *props);
438
+void backlight_device_unregister(struct backlight_device *bd);
439
+void devm_backlight_device_unregister(struct device *dev,
440
+				      struct backlight_device *bd);
441
+void backlight_force_update(struct backlight_device *bd,
442
+			    enum backlight_update_reason reason);
443
+int backlight_register_notifier(struct notifier_block *nb);
444
+int backlight_unregister_notifier(struct notifier_block *nb);
445
+struct backlight_device *backlight_device_get_by_name(const char *name);
446
+struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
447
+int backlight_device_set_brightness(struct backlight_device *bd,
448
+				    unsigned long brightness);
193449 
194450 #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)
195451 
452
+/**
453
+ * bl_get_data - access devdata
454
+ * @bl_dev: pointer to backlight device
455
+ *
456
+ * When a backlight device is registered the driver has the possibility
457
+ * to supply a void * devdata. bl_get_data() return a pointer to the
458
+ * devdata.
459
+ *
460
+ * RETURNS:
461
+ *
462
+ * pointer to devdata stored while registering the backlight device.
463
+ */
196464 static inline void * bl_get_data(struct backlight_device *bl_dev)
197465 {
198466 	return dev_get_drvdata(&bl_dev->dev);
199467 }
200
-
201
-struct generic_bl_info {
202
-	const char *name;
203
-	int max_intensity;
204
-	int default_intensity;
205
-	int limit_mask;
206
-	void (*set_bl_intensity)(int intensity);
207
-	void (*kick_battery)(void);
208
-};
209468 
210469 #ifdef CONFIG_OF
211470 struct backlight_device *of_find_backlight_by_node(struct device_node *node);
....@@ -218,14 +477,8 @@
218477 #endif
219478 
220479 #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
221
-struct backlight_device *of_find_backlight(struct device *dev);
222480 struct backlight_device *devm_of_find_backlight(struct device *dev);
223481 #else
224
-static inline struct backlight_device *of_find_backlight(struct device *dev)
225
-{
226
-	return NULL;
227
-}
228
-
229482 static inline struct backlight_device *
230483 devm_of_find_backlight(struct device *dev)
231484 {