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 */ 22 enum 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 */ 39 enum 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 */ 71 enum 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 93 struct backlight_device; 94 95 /** 96 * struct backlight_ops - backlight operations 97 * 98 * The backlight operations are specified when the backlight device is registered. 99 */ 100 struct 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 */ 162 struct 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 */ 245 struct 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 */ 299 static 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 */ 315 static 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 */ 330 static 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 */ 352 static 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 */ 369 static 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 377 struct backlight_device * 378 backlight_device_register(const char *name, struct device *dev, void *devdata, 379 const struct backlight_ops *ops, 380 const struct backlight_properties *props); 381 struct backlight_device * 382 devm_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); 386 void backlight_device_unregister(struct backlight_device *bd); 387 void devm_backlight_device_unregister(struct device *dev, 388 struct backlight_device *bd); 389 void backlight_force_update(struct backlight_device *bd, 390 enum backlight_update_reason reason); 391 struct backlight_device *backlight_device_get_by_name(const char *name); 392 struct backlight_device *backlight_device_get_by_type(enum backlight_type type); 393 int backlight_device_set_brightness(struct backlight_device *bd, 394 unsigned long brightness); 395 396 #if IS_REACHABLE(CONFIG_BACKLIGHT_CLASS_DEVICE) 397 void backlight_notify_blank(struct backlight_device *bd, 398 struct device *display_dev, 399 bool fb_on, bool prev_fb_on); 400 void backlight_notify_blank_all(struct device *display_dev, 401 bool fb_on, bool prev_fb_on); 402 #else 403 static inline void backlight_notify_blank(struct backlight_device *bd, 404 struct device *display_dev, 405 bool fb_on, bool prev_fb_on) 406 { } 407 static 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 */ 426 static 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 432 struct backlight_device *of_find_backlight_by_node(struct device_node *node); 433 #else 434 static inline struct backlight_device * 435 of_find_backlight_by_node(struct device_node *node) 436 { 437 return NULL; 438 } 439 #endif 440 441 #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE) 442 struct backlight_device *devm_of_find_backlight(struct device *dev); 443 #else 444 static inline struct backlight_device * 445 devm_of_find_backlight(struct device *dev) 446 { 447 return NULL; 448 } 449 #endif 450 451 #endif 452