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 enum backlight_scale { 50 BACKLIGHT_SCALE_UNKNOWN = 0, 51 BACKLIGHT_SCALE_LINEAR, 52 BACKLIGHT_SCALE_NON_LINEAR, 53 }; 54 55 struct backlight_device; 56 struct fb_info; 57 58 struct backlight_ops { 59 unsigned int options; 60 61 #define BL_CORE_SUSPENDRESUME (1 << 0) 62 63 /* Notify the backlight driver some property has changed */ 64 int (*update_status)(struct backlight_device *); 65 /* Return the current backlight brightness (accounting for power, 66 fb_blank etc.) */ 67 int (*get_brightness)(struct backlight_device *); 68 /* Check if given framebuffer device is the one bound to this backlight; 69 return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */ 70 int (*check_fb)(struct backlight_device *, struct fb_info *); 71 }; 72 73 /* This structure defines all the properties of a backlight */ 74 struct backlight_properties { 75 /* Current User requested brightness (0 - max_brightness) */ 76 int brightness; 77 /* Maximal value for brightness (read-only) */ 78 int max_brightness; 79 /* Current FB Power mode (0: full on, 1..3: power saving 80 modes; 4: full off), see FB_BLANK_XXX */ 81 int power; 82 /* FB Blanking active? (values as for power) */ 83 /* Due to be removed, please use (state & BL_CORE_FBBLANK) */ 84 int fb_blank; 85 /* Backlight type */ 86 enum backlight_type type; 87 /* Flags used to signal drivers of state changes */ 88 unsigned int state; 89 /* Type of the brightness scale (linear, non-linear, ...) */ 90 enum backlight_scale scale; 91 92 #define BL_CORE_SUSPENDED (1 << 0) /* backlight is suspended */ 93 #define BL_CORE_FBBLANK (1 << 1) /* backlight is under an fb blank event */ 94 95 }; 96 97 struct backlight_device { 98 /* Backlight properties */ 99 struct backlight_properties props; 100 101 /* Serialise access to update_status method */ 102 struct mutex update_lock; 103 104 /* This protects the 'ops' field. If 'ops' is NULL, the driver that 105 registered this device has been unloaded, and if class_get_devdata() 106 points to something in the body of that driver, it is also invalid. */ 107 struct mutex ops_lock; 108 const struct backlight_ops *ops; 109 110 /* The framebuffer notifier block */ 111 struct notifier_block fb_notif; 112 113 /* list entry of all registered backlight devices */ 114 struct list_head entry; 115 116 struct device dev; 117 118 /* Multiple framebuffers may share one backlight device */ 119 bool fb_bl_on[FB_MAX]; 120 121 int use_count; 122 }; 123 124 static inline int backlight_update_status(struct backlight_device *bd) 125 { 126 int ret = -ENOENT; 127 128 mutex_lock(&bd->update_lock); 129 if (bd->ops && bd->ops->update_status) 130 ret = bd->ops->update_status(bd); 131 mutex_unlock(&bd->update_lock); 132 133 return ret; 134 } 135 136 /** 137 * backlight_enable - Enable backlight 138 * @bd: the backlight device to enable 139 */ 140 static inline int backlight_enable(struct backlight_device *bd) 141 { 142 if (!bd) 143 return 0; 144 145 bd->props.power = FB_BLANK_UNBLANK; 146 bd->props.fb_blank = FB_BLANK_UNBLANK; 147 bd->props.state &= ~BL_CORE_FBBLANK; 148 149 return backlight_update_status(bd); 150 } 151 152 /** 153 * backlight_disable - Disable backlight 154 * @bd: the backlight device to disable 155 */ 156 static inline int backlight_disable(struct backlight_device *bd) 157 { 158 if (!bd) 159 return 0; 160 161 bd->props.power = FB_BLANK_POWERDOWN; 162 bd->props.fb_blank = FB_BLANK_POWERDOWN; 163 bd->props.state |= BL_CORE_FBBLANK; 164 165 return backlight_update_status(bd); 166 } 167 168 /** 169 * backlight_put - Drop backlight reference 170 * @bd: the backlight device to put 171 */ 172 static inline void backlight_put(struct backlight_device *bd) 173 { 174 if (bd) 175 put_device(&bd->dev); 176 } 177 178 /** 179 * backlight_is_blank - Return true if display is expected to be blank 180 * @bd: the backlight device 181 * 182 * Display is expected to be blank if any of these is true:: 183 * 184 * 1) if power in not UNBLANK 185 * 2) if fb_blank is not UNBLANK 186 * 3) if state indicate BLANK or SUSPENDED 187 * 188 * Returns true if display is expected to be blank, false otherwise. 189 */ 190 static inline bool backlight_is_blank(const struct backlight_device *bd) 191 { 192 return bd->props.power != FB_BLANK_UNBLANK || 193 bd->props.fb_blank != FB_BLANK_UNBLANK || 194 bd->props.state & (BL_CORE_SUSPENDED | BL_CORE_FBBLANK); 195 } 196 197 extern struct backlight_device *backlight_device_register(const char *name, 198 struct device *dev, void *devdata, const struct backlight_ops *ops, 199 const struct backlight_properties *props); 200 extern struct backlight_device *devm_backlight_device_register( 201 struct device *dev, const char *name, struct device *parent, 202 void *devdata, const struct backlight_ops *ops, 203 const struct backlight_properties *props); 204 extern void backlight_device_unregister(struct backlight_device *bd); 205 extern void devm_backlight_device_unregister(struct device *dev, 206 struct backlight_device *bd); 207 extern void backlight_force_update(struct backlight_device *bd, 208 enum backlight_update_reason reason); 209 extern int backlight_register_notifier(struct notifier_block *nb); 210 extern int backlight_unregister_notifier(struct notifier_block *nb); 211 extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type); 212 struct backlight_device *backlight_device_get_by_name(const char *name); 213 extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness); 214 215 #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev) 216 217 static inline void * bl_get_data(struct backlight_device *bl_dev) 218 { 219 return dev_get_drvdata(&bl_dev->dev); 220 } 221 222 struct generic_bl_info { 223 const char *name; 224 int max_intensity; 225 int default_intensity; 226 int limit_mask; 227 void (*set_bl_intensity)(int intensity); 228 void (*kick_battery)(void); 229 }; 230 231 #ifdef CONFIG_OF 232 struct backlight_device *of_find_backlight_by_node(struct device_node *node); 233 #else 234 static inline struct backlight_device * 235 of_find_backlight_by_node(struct device_node *node) 236 { 237 return NULL; 238 } 239 #endif 240 241 #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE) 242 struct backlight_device *of_find_backlight(struct device *dev); 243 struct backlight_device *devm_of_find_backlight(struct device *dev); 244 #else 245 static inline struct backlight_device *of_find_backlight(struct device *dev) 246 { 247 return NULL; 248 } 249 250 static inline struct backlight_device * 251 devm_of_find_backlight(struct device *dev) 252 { 253 return NULL; 254 } 255 #endif 256 257 #endif 258