Backlight support¶
The backlight core supports implementing backlight drivers.
A backlight driver registers a driver usingdevm_backlight_device_register(). The properties of the backlightdriver such as type and max_brightness must be specified.When the core detect changes in for example brightness or power statethe update_status() operation is called. The backlight driver shallimplement this operation and use it to adjust backlight.
Several sysfs attributes are provided by the backlight core:
- brightness R/W, set the requested brightness level- actual_brightness RO, the brightness level used by the HW- max_brightness RO, the maximum brightness level supported
See Documentation/ABI/stable/sysfs-class-backlight for the full list.
The backlight can be adjusted using the sysfs interface, andthe backlight driver may also support adjusting backlight usinga hot-key or some other platform or firmware specific way.
The driver must implement the get_brightness() operation ifthe HW do not support all the levels that can be specified inbrightness, thus providing user-space access to the actual levelvia the actual_brightness attribute.
When the backlight changes this is reported to user-space usingan uevent connected to the actual_brightness attribute.When brightness is set by platform specific means, for examplea hot-key to adjust backlight, the driver must notify the backlightcore that brightness has changed usingbacklight_force_update().
The backlight driver core receives notifications from fbdev andif the event is FB_EVENT_BLANK and if the value of blank, from theFBIOBLANK ioctrl, results in a change in the backlight state theupdate_status() operation is called.
- enum
backlight_update_reason¶ what method was used to update backlight
Constants
BACKLIGHT_UPDATE_HOTKEY- The backlight was updated using a hot-key.
BACKLIGHT_UPDATE_SYSFS- The backlight was updated using sysfs.
Description
A driver indicates the method (reason) used for updating the backlightwhen callingbacklight_force_update().
- enum
backlight_type¶ the type of backlight control
Constants
BACKLIGHT_RAW- The backlight is controlled using hardware registers.
BACKLIGHT_PLATFORM- The backlight is controlled using a platform-specific interface.
BACKLIGHT_FIRMWARE- The backlight is controlled using a standard firmware interface.
BACKLIGHT_TYPE_MAX- Number of entries.
Description
The type of interface used to control the backlight.
- enum
backlight_notification¶ the type of notification
Constants
BACKLIGHT_REGISTERED- The backlight device is registered.
BACKLIGHT_UNREGISTERED- The backlight revice is unregistered.
Description
The notifications that is used for notification sent to the receiverthat registered notifications usingbacklight_register_notifier().
- struct
backlight_ops¶ backlight operations
Definition
struct backlight_ops { unsigned int options;#define BL_CORE_SUSPENDRESUME (1 << 0); int (*update_status)(struct backlight_device *); int (*get_brightness)(struct backlight_device *); int (*check_fb)(struct backlight_device *bd, struct fb_info *info);};Members
optionsConfigure how operations are called from the core.
The options parameter is used to adjust the behaviour of the core.Set BL_CORE_SUSPENDRESUME to get the update_status() operation calledupon suspend and resume.
update_statusOperation called when properties have changed.
Notify the backlight driver some property has changed.The update_status operation is protected by the update_lock.
The backlight driver is expected to use
backlight_is_blank()to check if the display is blanked and set brightness accordingly.update_status() is called when any of the properties has changed.RETURNS:
0 on success, negative error code if any failure occurred.
get_brightnessReturn the current backlight brightness.
The driver may implement this as a readback from the HW.This operation is optional and if not present then the currentbrightness property value is used.
RETURNS:
A brightness value which is 0 or a positive number.On failure a negative error code is returned.
check_fbCheck the framebuffer device.
Check if given framebuffer device is the one bound to this backlight.This operation is optional and if not implemented it is assumed that thefbdev is always the one bound to the backlight.
RETURNS:
If info is NULL or the info matches the fbdev bound to the backlight return true.If info does not match the fbdev bound to the backlight return false.
Description
The backlight operations are specified when the backlight device is registered.
- struct
backlight_properties¶ backlight properties
Definition
struct backlight_properties { int brightness; int max_brightness; int power; int fb_blank; enum backlight_type type; unsigned int state;#define BL_CORE_SUSPENDED (1 << 0) ;#define BL_CORE_FBBLANK (1 << 1) ; enum backlight_scale scale;};Members
brightnessThe current brightness requested by the user.
The backlight core makes sure the range is (0 to max_brightness)when the brightness is set via the sysfs attribute:/sys/class/backlight/<backlight>/brightness.
This value can be set in the backlight_properties passedto
devm_backlight_device_register()to set a default brightnessvalue.max_brightnessThe maximum brightness value.
This value must be set in the backlight_properties passed to
devm_backlight_device_register()and shall not be modified by thedriver after registration.powerThe current power mode.
User space can configure the power mode using the sysfsattribute: /sys/class/backlight/<backlight>/bl_powerWhen the power property is updated update_status() is called.
The possible values are: (0: full on, 1 to 3: power savingmodes; 4: full off), see FB_BLANK_XXX.
When the backlight device is enabledpower is setto FB_BLANK_UNBLANK. When the backlight device is disabledpower is set to FB_BLANK_POWERDOWN.
fb_blankThe power state from the FBIOBLANK ioctl.
When the FBIOBLANK ioctl is calledfb_blank is set to theblank parameter and the update_status() operation is called.
When the backlight device is enabledfb_blank is setto FB_BLANK_UNBLANK. When the backlight device is disabledfb_blank is set to FB_BLANK_POWERDOWN.
Backlight drivers should avoid using this property. It has beenreplaced by state & BL_CORE_FBLANK (although most drivers shoulduse
backlight_is_blank()as the preferred means to get the blankstate).fb_blank is deprecated and will be removed.
typeThe type of backlight supported.
The backlight type allows userspace to make appropriatepolicy decisions based on the backlight type.
This value must be set in the backlight_propertiespassed to
devm_backlight_device_register().stateThe state of the backlight core.
The state is a bitmask. BL_CORE_FBBLANK is set when the displayis expected to be blank. BL_CORE_SUSPENDED is set when thedriver is suspended.
backlight drivers are expected to use
backlight_is_blank()in their update_status() operation rather than reading thestate property.The state is maintained by the core and drivers may not modify it.
scale- The type of the brightness scale.
Description
This structure defines all the properties of a backlight.
- struct
backlight_device¶ backlight device data
Definition
struct backlight_device { struct backlight_properties props; struct mutex update_lock; struct mutex ops_lock; const struct backlight_ops *ops; struct notifier_block fb_notif; struct list_head entry; struct device dev; bool fb_bl_on[FB_MAX]; int use_count;};Members
props- Backlight properties
update_lockThe lock used when calling the update_status() operation.
update_lock is an internal backlight lock that serialise accessto the update_status() operation. The backlight core holds the update_lockwhen calling the update_status() operation. The update_lock shall notbe used by backlight drivers.
ops_lockThe lock used around everything related to backlight_ops.
ops_lock is an internal backlight lock that protects the ops pointerand is used around all accesses to ops and when the operations areinvoked. The ops_lock shall not be used by backlight drivers.
opsPointer to the backlight operations.
If ops is NULL, the driver that registered this device has been unloaded,and if class_get_devdata() points to something in the body of that driver,it is also invalid.
fb_notif- The framebuffer notifier block
entry- List entry of all registered backlight devices
dev- Parent device.
fb_bl_onThe state of individual fbdev’s.
Multiple fbdev’s may share one backlight device. The fb_bl_onrecords the state of the individual fbdev.
use_count- The number of uses of fb_bl_on.
Description
This structure holds all data required by a backlight device.
- int
backlight_update_status(structbacklight_device * bd)¶ force an update of the backlight device status
Parameters
structbacklight_device*bd- the backlight device
- int
backlight_enable(structbacklight_device * bd)¶ Enable backlight
Parameters
structbacklight_device*bd- the backlight device to enable
- int
backlight_disable(structbacklight_device * bd)¶ Disable backlight
Parameters
structbacklight_device*bd- the backlight device to disable
- bool
backlight_is_blank(const structbacklight_device * bd)¶ Return true if display is expected to be blank
Parameters
conststructbacklight_device*bd- the backlight device
Description
Display is expected to be blank if any of these is true:
1) if power in not UNBLANK2) if fb_blank is not UNBLANK3) if state indicate BLANK or SUSPENDED
Returns true if display is expected to be blank, false otherwise.
- int
backlight_get_brightness(const structbacklight_device * bd)¶ Returns the current brightness value
Parameters
conststructbacklight_device*bd- the backlight device
Description
Returns the current brightness value, taking in consideration the currentstate. Ifbacklight_is_blank() returns true then return 0 as brightnessotherwise return the current brightness property value.
Backlight drivers are expected to use this function in their update_status()operation to get the brightness value.
- void *
bl_get_data(structbacklight_device * bl_dev)¶ access devdata
Parameters
structbacklight_device*bl_dev- pointer to backlight device
Description
When a backlight device is registered the driver has the possibilityto supply a void * devdata.bl_get_data() return a pointer to thedevdata.
pointer to devdata stored while registering the backlight device.
Return
- void
backlight_force_update(structbacklight_device * bd, enumbacklight_update_reason reason)¶ tell the backlight subsystem that hardware state has changed
Parameters
structbacklight_device*bd- the backlight device to update
enumbacklight_update_reasonreason- reason for update
Description
Updates the internal state of the backlight in response to a hardware event,and generates an uevent to notify userspace. A backlight driver shall callbacklight_force_update() when the backlight is changed using, for example,a hot-key. The updated brightness is read using get_brightness() and thebrightness value is reported using an uevent.
- structbacklight_device *
backlight_device_get_by_name(const char * name)¶ Get backlight device by name
Parameters
constchar*name- Device name
Description
This function looks up a backlight device by its name. It obtains a referenceon the backlight device and it is the caller’s responsibility to drop thereference by calling backlight_put().
Return
A pointer to the backlight device if found, otherwise NULL.
- int
backlight_register_notifier(struct notifier_block * nb)¶ get notified of backlight (un)registration
Parameters
structnotifier_block*nb- notifier block with the notifier to call on backlight (un)registration
Description
Register a notifier to get notified when backlight devices get registeredor unregistered.
0 on success, otherwise a negative error code
Return
- int
backlight_unregister_notifier(struct notifier_block * nb)¶ unregister a backlight notifier
Parameters
structnotifier_block*nb- notifier block to unregister
Description
Register a notifier to get notified when backlight devices get registeredor unregistered.
0 on success, otherwise a negative error code
Return
- structbacklight_device *
devm_backlight_device_register(structdevice * dev, const char * name, structdevice * parent, void * devdata, const structbacklight_ops * ops, const structbacklight_properties * props)¶ register a new backlight device
Parameters
structdevice*dev- the device to register
constchar*name- the name of the device
structdevice*parent- a pointer to the parent device (often the same asdev)
void*devdata- an optional pointer to be stored for private driver use
conststructbacklight_ops*ops- the backlight operations structure
conststructbacklight_properties*props- the backlight properties
Description
Creates and registers new backlight device. When a backlight deviceis registered the configuration must be specified in thepropsparameter. See description ofbacklight_properties.
struct backlight on success, or an ERR_PTR on error
Return
- void
devm_backlight_device_unregister(structdevice * dev, structbacklight_device * bd)¶ unregister backlight device
Parameters
structdevice*dev- the device to unregister
structbacklight_device*bd- the backlight device to unregister
Description
Deallocates a backlight allocated withdevm_backlight_device_register().Normally this function will not need to be called and the resource managementcode will ensure that the resources are freed.
- structbacklight_device *
of_find_backlight_by_node(struct device_node * node)¶ find backlight device by device-tree node
Parameters
structdevice_node*node- device-tree node of the backlight device
Description
Returns a pointer to the backlight device corresponding to the given DTnode or NULL if no such backlight device exists or if the device hasn’tbeen probed yet.
This function obtains a reference on the backlight device and it is thecaller’s responsibility to drop the reference by callingput_device() onthe backlight device’s .dev field.
- structbacklight_device *
devm_of_find_backlight(structdevice * dev)¶ find backlight for a device
Parameters
structdevice*dev- the device
Description
This function looks for a property named ‘backlight’ on the DT nodeconnected todev and looks up the backlight device. The lookup isdevice managed so the reference to the backlight device is automaticallydropped on driver detach.
A pointer to the backlight device if found.Error pointer -EPROBE_DEFER if the DT property is set, but no backlightdevice is found. NULL if there’s no backlight property.
Return