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 statetheupdate_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

SeeABI file 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 theget_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().

Display drives can control the backlight device’s status usingbacklight_notify_blank() andbacklight_notify_blank_all(). If thisresults in a change in the backlight state the functions call theupdate_status() operation.

enumbacklight_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().

enumbacklight_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.

structbacklight_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 *);    bool (*controls_device)(struct backlight_device *bd, struct device *display_dev);};

Members

options

Configure 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 theupdate_status() operation calledupon suspend and resume.

update_status

Operation 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 usebacklight_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_brightness

Return 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.

controls_device

Check against the display device

Check if the backlight controls the given display device. Thisoperation is optional and if not implemented it is assumed thatthe display is always the one controlled by the backlight.

RETURNS:

If display_dev is NULL or display_dev matches the device controlled bythe backlight, return true. Otherwise return false.

Description

The backlight operations are specified when the backlight device is registered.

structbacklight_properties¶: backlight properties

Definition:

struct backlight_properties {    int brightness;    int max_brightness;    int power;#define BACKLIGHT_POWER_ON              (0);#define BACKLIGHT_POWER_OFF             (4);#define BACKLIGHT_POWER_REDUCED         (1);    enum backlight_type type;    unsigned int state;#define BL_CORE_SUSPENDED       (1 << 0);#define BL_CORE_FBBLANK         (1 << 1);    enum backlight_scale scale;};

Members

brightness

The 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 passedtodevm_backlight_device_register() to set a default brightnessvalue.

max_brightness

The maximum brightness value.

This value must be set in the backlight_properties passed todevm_backlight_device_register() and shall not be modified by thedriver after registration.

power

The current power mode.

User space can configure the power mode using the sysfsattribute: /sys/class/backlight/<backlight>/bl_powerWhen the power property is updatedupdate_status() is called.

The possible values are: (0: full on, 4: full off), seeBACKLIGHT_POWER constants.

When the backlight device is enabled,power is set toBACKLIGHT_POWER_ON. When the backlight device is disabled,power is set to BACKLIGHT_POWER_OFF.

type

The 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 todevm_backlight_device_register().

state

The 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 usebacklight_is_blank()in theirupdate_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.

structbacklight_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 list_head entry;    struct device dev;    int use_count;};

Members

props

Backlight properties

update_lock

The lock used when calling theupdate_status() operation.

update_lock is an internal backlight lock that serialise accessto theupdate_status() operation. The backlight core holds the update_lockwhen calling theupdate_status() operation. The update_lock shall notbe used by backlight drivers.

ops_lock

The 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.

ops

Pointer to the backlight operations.

If ops is NULL, the driver that registered this device has been unloaded,and ifclass_get_devdata() points to something in the body of that driver,it is also invalid.

entry

List entry of all registered backlight devices

dev

Parent device.

use_count

The number of unblanked displays.

Description

This structure holds all data required by a backlight device.

intbacklight_update_status(structbacklight_device*bd)¶: force an update of the backlight device status

Parameters

structbacklight_device*bd: the backlight device

intbacklight_enable(structbacklight_device*bd)¶: Enable backlight

Parameters

structbacklight_device*bd: the backlight device to enable

intbacklight_disable(structbacklight_device*bd)¶: Disable backlight

Parameters

structbacklight_device*bd: the backlight device to disable

boolbacklight_is_blank(conststructbacklight_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 state indicate BLANK or SUSPENDED

Returns true if display is expected to be blank, false otherwise.

intbacklight_get_brightness(conststructbacklight_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 theirupdate_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.

voidbacklight_force_update(structbacklight_device*bd,enumbacklight_update_reasonreason)¶: 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 usingget_brightness() and thebrightness value is reported using an uevent.

structbacklight_device*backlight_device_get_by_name(constchar*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 callingput_device().

Return

A pointer to the backlight device if found, otherwise NULL.

structbacklight_device*devm_backlight_device_register(structdevice*dev,constchar*name,structdevice*parent,void*devdata,conststructbacklight_ops*ops,conststructbacklight_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.

structbacklight on success, or an ERR_PTR on error

voiddevm_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(structdevice_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.

Movatterモバイル変換

Backlight support¶