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             : /**
      18             :  * enum backlight_update_reason - what method was used to update backlight
      19             :  *
      20             :  * A driver indicates the method (reason) used for updating the backlight
      21             :  * when calling backlight_force_update().
      22             :  */
      23             : enum backlight_update_reason {
      24             :         /**
      25             :          * @BACKLIGHT_UPDATE_HOTKEY: The backlight was updated using a hot-key.
      26             :          */
      27             :         BACKLIGHT_UPDATE_HOTKEY,
      28             : 
      29             :         /**
      30             :          * @BACKLIGHT_UPDATE_SYSFS: The backlight was updated using sysfs.
      31             :          */
      32             :         BACKLIGHT_UPDATE_SYSFS,
      33             : };
      34             : 
      35             : /**
      36             :  * enum backlight_type - the type of backlight control
      37             :  *
      38             :  * The type of interface used to control the backlight.
      39             :  */
      40             : enum backlight_type {
      41             :         /**
      42             :          * @BACKLIGHT_RAW:
      43             :          *
      44             :          * The backlight is controlled using hardware registers.
      45             :          */
      46             :         BACKLIGHT_RAW = 1,
      47             : 
      48             :         /**
      49             :          * @BACKLIGHT_PLATFORM:
      50             :          *
      51             :          * The backlight is controlled using a platform-specific interface.
      52             :          */
      53             :         BACKLIGHT_PLATFORM,
      54             : 
      55             :         /**
      56             :          * @BACKLIGHT_FIRMWARE:
      57             :          *
      58             :          * The backlight is controlled using a standard firmware interface.
      59             :          */
      60             :         BACKLIGHT_FIRMWARE,
      61             : 
      62             :         /**
      63             :          * @BACKLIGHT_TYPE_MAX: Number of entries.
      64             :          */
      65             :         BACKLIGHT_TYPE_MAX,
      66             : };
      67             : 
      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             :  */
      74             : enum backlight_notification {
      75             :         /**
      76             :          * @BACKLIGHT_REGISTERED: The backlight device is registered.
      77             :          */
      78             :         BACKLIGHT_REGISTERED,
      79             : 
      80             :         /**
      81             :          * @BACKLIGHT_UNREGISTERED: The backlight revice is unregistered.
      82             :          */
      83             :         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,
     110             : };
     111             : 
     112             : struct backlight_device;
     113             : struct fb_info;
     114             : 
     115             : /**
     116             :  * struct backlight_ops - backlight operations
     117             :  *
     118             :  * The backlight operations are specified when the backlight device is registered.
     119             :  */
     120             : 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             :          */
     128             :         unsigned int options;
     129             : 
     130             : #define BL_CORE_SUSPENDRESUME   (1 << 0)
     131             : 
     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             :          */
     146             :         int (*update_status)(struct backlight_device *);
     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             :          */
     160             :         int (*get_brightness)(struct backlight_device *);
     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);
     175             : };
     176             : 
     177             : /**
     178             :  * struct backlight_properties - backlight properties
     179             :  *
     180             :  * This structure defines all the properties of a backlight.
     181             :  */
     182             : struct backlight_properties {
     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             :          */
     194             :         int brightness;
     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             :          */
     203             :         int max_brightness;
     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             :          */
     219             :         int power;
     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             :          */
     238             :         int fb_blank;
     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             :          */
     249             :         enum backlight_type type;
     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             :          */
     264             :         unsigned int state;
     265             : 
     266             : #define BL_CORE_SUSPENDED       (1 << 0)  /* backlight is suspended */
     267             : #define BL_CORE_FBBLANK         (1 << 1)  /* backlight is under an fb blank event */
     268             : 
     269             :         /**
     270             :          * @scale: The type of the brightness scale.
     271             :          */
     272             :         enum backlight_scale scale;
     273             : };
     274             : 
     275             : /**
     276             :  * struct backlight_device - backlight device data
     277             :  *
     278             :  * This structure holds all data required by a backlight device.
     279             :  */
     280             : struct backlight_device {
     281             :         /**
     282             :          * @props: Backlight properties
     283             :          */
     284             :         struct backlight_properties props;
     285             : 
     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             :          */
     294             :         struct mutex update_lock;
     295             : 
     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             :          */
     303             :         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             :          */
     312             :         const struct backlight_ops *ops;
     313             : 
     314             :         /**
     315             :          * @fb_notif: The framebuffer notifier block
     316             :          */
     317             :         struct notifier_block fb_notif;
     318             : 
     319             :         /**
     320             :          * @entry: List entry of all registered backlight devices
     321             :          */
     322             :         struct list_head entry;
     323             : 
     324             :         /**
     325             :          * @dev: Parent device.
     326             :          */
     327             :         struct device dev;
     328             : 
     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             :          */
     335             :         bool fb_bl_on[FB_MAX];
     336             : 
     337             :         /**
     338             :          * @use_count: The number of uses of fb_bl_on.
     339             :          */
     340             :         int use_count;
     341             : };
     342             : 
     343             : /**
     344             :  * backlight_update_status - force an update of the backlight device status
     345             :  * @bd: the backlight device
     346             :  */
     347           0 : static inline int backlight_update_status(struct backlight_device *bd)
     348             : {
     349           0 :         int ret = -ENOENT;
     350             : 
     351           0 :         mutex_lock(&bd->update_lock);
     352           0 :         if (bd->ops && bd->ops->update_status)
     353           0 :                 ret = bd->ops->update_status(bd);
     354           0 :         mutex_unlock(&bd->update_lock);
     355             : 
     356           0 :         return ret;
     357             : }
     358             : 
     359             : /**
     360             :  * backlight_enable - Enable backlight
     361             :  * @bd: the backlight device to enable
     362             :  */
     363             : static inline int backlight_enable(struct backlight_device *bd)
     364             : {
     365           0 :         if (!bd)
     366             :                 return 0;
     367             : 
     368           0 :         bd->props.power = FB_BLANK_UNBLANK;
     369           0 :         bd->props.fb_blank = FB_BLANK_UNBLANK;
     370           0 :         bd->props.state &= ~BL_CORE_FBBLANK;
     371             : 
     372           0 :         return backlight_update_status(bd);
     373             : }
     374             : 
     375             : /**
     376             :  * backlight_disable - Disable backlight
     377             :  * @bd: the backlight device to disable
     378             :  */
     379             : static inline int backlight_disable(struct backlight_device *bd)
     380             : {
     381           0 :         if (!bd)
     382             :                 return 0;
     383             : 
     384           0 :         bd->props.power = FB_BLANK_POWERDOWN;
     385           0 :         bd->props.fb_blank = FB_BLANK_POWERDOWN;
     386           0 :         bd->props.state |= BL_CORE_FBBLANK;
     387             : 
     388           0 :         return backlight_update_status(bd);
     389             : }
     390             : 
     391             : /**
     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.
     402             :  */
     403             : static inline bool backlight_is_blank(const struct backlight_device *bd)
     404             : {
     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);
     408             : }
     409             : 
     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);
     449             : 
     450             : #define to_backlight_device(obj) container_of(obj, struct backlight_device, dev)
     451             : 
     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             :  */
     464             : static inline void * bl_get_data(struct backlight_device *bl_dev)
     465             : {
     466             :         return dev_get_drvdata(&bl_dev->dev);
     467             : }
     468             : 
     469             : #ifdef CONFIG_OF
     470             : struct backlight_device *of_find_backlight_by_node(struct device_node *node);
     471             : #else
     472             : static inline struct backlight_device *
     473             : of_find_backlight_by_node(struct device_node *node)
     474             : {
     475             :         return NULL;
     476             : }
     477             : #endif
     478             : 
     479             : #if IS_ENABLED(CONFIG_BACKLIGHT_CLASS_DEVICE)
     480             : struct backlight_device *devm_of_find_backlight(struct device *dev);
     481             : #else
     482             : static inline struct backlight_device *
     483             : devm_of_find_backlight(struct device *dev)
     484             : {
     485             :         return NULL;
     486             : }
     487             : #endif
     488             : 
     489             : #endif