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.

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.

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

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 *);  int (*check_fb)(struct backlight_device *bd, struct fb_info *info);};

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 the update_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.

check_fb

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

structbacklight_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

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

The 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 shouldusebacklight_is_blank() as the preferred means to get the blankstate).

fb_blank is deprecated and will be removed.

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

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

The 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_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 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_on

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

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

intbacklight_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

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

intbacklight_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

intbacklight_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

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