Backlight support¶
The backlight core supports implementing backlight drivers.
A backlight driver registers a driver using
devm_backlight_device_register()
. The properties of the backlight
driver such as type and max_brightness must be specified.
When the core detect changes in for example brightness or power state
the update_status() operation is called. The backlight driver shall
implement 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, and the backlight driver may also support adjusting backlight using a hot-key or some other platform or firmware specific way.
The driver must implement the get_brightness() operation if the HW do not support all the levels that can be specified in brightness, thus providing user-space access to the actual level via the actual_brightness attribute.
When the backlight changes this is reported to user-space using
an uevent connected to the actual_brightness attribute.
When brightness is set by platform specific means, for example
a hot-key to adjust backlight, the driver must notify the backlight
core that brightness has changed using backlight_force_update()
.
The backlight driver core receives notifications from fbdev and if the event is FB_EVENT_BLANK and if the value of blank, from the FBIOBLANK ioctrl, results in a change in the backlight state the update_status() operation is called.
-
int
backlight_enable
(struct backlight_device * bd)¶ Enable backlight
Parameters
struct backlight_device * bd
- the backlight device to enable
-
int
backlight_disable
(struct backlight_device * bd)¶ Disable backlight
Parameters
struct backlight_device * bd
- the backlight device to disable
-
void
backlight_put
(struct backlight_device * bd)¶ Drop backlight reference
Parameters
struct backlight_device * bd
- the backlight device to put
-
bool
backlight_is_blank
(const struct backlight_device * bd)¶ Return true if display is expected to be blank
Parameters
const struct backlight_device * bd
- the backlight device
Description
Display is expected to be blank if any of these is true:
1) if power in not UNBLANK
2) if fb_blank is not UNBLANK
3) if state indicate BLANK or SUSPENDED
Returns true if display is expected to be blank, false otherwise.
-
int
backlight_get_brightness
(const struct backlight_device * bd)¶ Returns the current brightness value
Parameters
const struct backlight_device * bd
- the backlight device
Description
Returns the current brightness value, taking in consideration the current
state. If backlight_is_blank()
returns true then return 0 as brightness
otherwise 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
backlight_force_update
(struct backlight_device * bd, enum backlight_update_reason reason)¶ tell the backlight subsystem that hardware state has changed
Parameters
struct backlight_device * bd
- the backlight device to update
enum backlight_update_reason reason
- 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 call
backlight_force_update()
when the backlight is changed using, for example,
a hot-key. The updated brightness is read using get_brightness() and the
brightness value is reported using an uevent.
-
struct backlight_device *
backlight_device_get_by_name
(const char * name)¶ Get backlight device by name
Parameters
const char * name
- Device name
Description
This function looks up a backlight device by its name. It obtains a reference
on the backlight device and it is the caller’s responsibility to drop the
reference 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
struct notifier_block * nb
- notifier block with the notifier to call on backlight (un)registration
Description
Register a notifier to get notified when backlight devices get registered or unregistered.
Return
0 on success, otherwise a negative error code
-
int
backlight_unregister_notifier
(struct notifier_block * nb)¶ unregister a backlight notifier
Parameters
struct notifier_block * nb
- notifier block to unregister
Description
Register a notifier to get notified when backlight devices get registered or unregistered.
Return
0 on success, otherwise a negative error code
-
struct backlight_device *
devm_backlight_device_register
(struct device * dev, const char * name, struct device * parent, void * devdata, const struct backlight_ops * ops, const struct backlight_properties * props)¶ register a new backlight device
Parameters
struct device * dev
- the device to register
const char * name
- the name of the device
struct device * parent
- a pointer to the parent device (often the same as dev)
void * devdata
- an optional pointer to be stored for private driver use
const struct backlight_ops * ops
- the backlight operations structure
const struct backlight_properties * props
- the backlight properties
Description
Creates and registers new backlight device. When a backlight device
is registered the configuration must be specified in the props
parameter. See description of backlight_properties
.
Return
struct backlight on success, or an ERR_PTR on error
-
void
devm_backlight_device_unregister
(struct device * dev, struct backlight_device * bd)¶ unregister backlight device
Parameters
struct device * dev
- the device to unregister
struct backlight_device * bd
- the backlight device to unregister
Description
Deallocates a backlight allocated with devm_backlight_device_register()
.
Normally this function will not need to be called and the resource management
code will ensure that the resources are freed.
-
struct backlight_device *
of_find_backlight_by_node
(struct device_node * node)¶ find backlight device by device-tree node
Parameters
struct device_node * node
- device-tree node of the backlight device
Description
Returns a pointer to the backlight device corresponding to the given DT node or NULL if no such backlight device exists or if the device hasn’t been probed yet.
This function obtains a reference on the backlight device and it is the
caller’s responsibility to drop the reference by calling put_device()
on
the backlight device’s .dev field.
Parameters
struct device * dev
- the device
Description
This function looks for a property named ‘backlight’ on the DT node connected to dev and looks up the backlight device. The lookup is device managed so the reference to the backlight device is automatically dropped on driver detach.
Return
A pointer to the backlight device if found. Error pointer -EPROBE_DEFER if the DT property is set, but no backlight device is found. NULL if there’s no backlight property.