Branch data     Line data    Source code

       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                 :          0 : static inline int backlight_update_status(struct backlight_device *bd)
     125                 :            : {
     126                 :          0 :         int ret = -ENOENT;
     127                 :            : 
     128                 :          0 :         mutex_lock(&bd->update_lock);
     129   [ #  #  #  # ]:          0 :         if (bd->ops && bd->ops->update_status)
     130                 :          0 :                 ret = bd->ops->update_status(bd);
     131                 :          0 :         mutex_unlock(&bd->update_lock);
     132                 :            : 
     133                 :          0 :         return ret;
     134                 :            : }
     135                 :            : 
     136                 :            : /**
     137                 :            :  * backlight_enable - Enable backlight
     138                 :            :  * @bd: the backlight device to enable
     139                 :            :  */
     140                 :          0 : static inline int backlight_enable(struct backlight_device *bd)
     141                 :            : {
     142         [ #  # ]:          0 :         if (!bd)
     143                 :            :                 return 0;
     144                 :            : 
     145                 :          0 :         bd->props.power = FB_BLANK_UNBLANK;
     146                 :          0 :         bd->props.fb_blank = FB_BLANK_UNBLANK;
     147                 :          0 :         bd->props.state &= ~BL_CORE_FBBLANK;
     148                 :            : 
     149                 :          0 :         return backlight_update_status(bd);
     150                 :            : }
     151                 :            : 
     152                 :            : /**
     153                 :            :  * backlight_disable - Disable backlight
     154                 :            :  * @bd: the backlight device to disable
     155                 :            :  */
     156                 :          0 : static inline int backlight_disable(struct backlight_device *bd)
     157                 :            : {
     158         [ #  # ]:          0 :         if (!bd)
     159                 :            :                 return 0;
     160                 :            : 
     161                 :          0 :         bd->props.power = FB_BLANK_POWERDOWN;
     162                 :          0 :         bd->props.fb_blank = FB_BLANK_POWERDOWN;
     163                 :          0 :         bd->props.state |= BL_CORE_FBBLANK;
     164                 :            : 
     165                 :          0 :         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                 :            : extern struct backlight_device *backlight_device_register(const char *name,
     179                 :            :         struct device *dev, void *devdata, const struct backlight_ops *ops,
     180                 :            :         const struct backlight_properties *props);
     181                 :            : extern struct backlight_device *devm_backlight_device_register(
     182                 :            :         struct device *dev, const char *name, struct device *parent,
     183                 :            :         void *devdata, const struct backlight_ops *ops,
     184                 :            :         const struct backlight_properties *props);
     185                 :            : extern void backlight_device_unregister(struct backlight_device *bd);
     186                 :            : extern void devm_backlight_device_unregister(struct device *dev,
     187                 :            :                                         struct backlight_device *bd);
     188                 :            : extern void backlight_force_update(struct backlight_device *bd,
     189                 :            :                                    enum backlight_update_reason reason);
     190                 :            : extern int backlight_register_notifier(struct notifier_block *nb);
     191                 :            : extern int backlight_unregister_notifier(struct notifier_block *nb);
     192                 :            : extern struct backlight_device *backlight_device_get_by_type(enum backlight_type type);
     193                 :            : extern int backlight_device_set_brightness(struct backlight_device *bd, unsigned long brightness);
     194                 :            : 
     195                 :            : #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)
     196                 :            : 
     197                 :          0 : static inline void * bl_get_data(struct backlight_device *bl_dev)
     198                 :            : {
     199                 :          0 :         return dev_get_drvdata(&bl_dev->dev);
     200                 :            : }
     201                 :            : 
     202                 :            : struct generic_bl_info {
     203                 :            :         const char *name;
     204                 :            :         int max_intensity;
     205                 :            :         int default_intensity;
     206                 :            :         int limit_mask;
     207                 :            :         void (*set_bl_intensity)(int intensity);
     208                 :            :         void (*kick_battery)(void);
     209                 :            : };
     210                 :            : 
     211                 :            : #ifdef CONFIG_OF
     212                 :            : struct backlight_device *of_find_backlight_by_node(struct device_node *node);
     213                 :            : #else
     214                 :            : static inline struct backlight_device *
     215                 :            : of_find_backlight_by_node(struct device_node *node)
     216                 :            : {
     217                 :            :         return NULL;
     218                 :            : }
     219                 :            : #endif
     220                 :            : 
     221                 :            : #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
     222                 :            : struct backlight_device *of_find_backlight(struct device *dev);
     223                 :            : struct backlight_device *devm_of_find_backlight(struct device *dev);
     224                 :            : #else
     225                 :            : static inline struct backlight_device *of_find_backlight(struct device *dev)
     226                 :            : {
     227                 :            :         return NULL;
     228                 :            : }
     229                 :            : 
     230                 :            : static inline struct backlight_device *
     231                 :            : devm_of_find_backlight(struct device *dev)
     232                 :            : {
     233                 :            :         return NULL;
     234                 :            : }
     235                 :            : #endif
     236                 :            : 
     237                 :            : #endif