背光支持

背光核心支持实现背光驱动程序。

背光驱动程序使用 devm_backlight_device_register() 注册一个驱动程序。必须指定背光驱动程序的属性,例如类型和 max_brightness。当核心检测到亮度或电源状态等方面的变化时,会调用 update_status() 操作。背光驱动程序应实现此操作并使用它来调整背光。

背光核心提供多个 sysfs 属性

- 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

有关完整列表,请参阅 ABI 文件 stable/sysfs-class-backlight

可以使用 sysfs 接口调整背光,并且背光驱动程序也可能支持使用热键或一些其他平台或固件特定的方式调整背光。

如果硬件不支持可以在亮度中指定的所有级别,则驱动程序必须实现 get_brightness() 操作,从而通过 actual_brightness 属性向用户空间提供对实际级别的访问。

当背光更改时,这会使用连接到 actual_brightness 属性的 uevent 报告给用户空间。当通过平台特定方式设置亮度时,例如用于调整背光的热键,驱动程序必须使用 backlight_force_update() 通知背光核心亮度已更改。

显示驱动程序可以使用 backlight_notify_blank() 和 backlight_notify_blank_all() 控制背光设备的状态。如果这导致背光状态发生更改,则函数会调用 update_status() 操作。

enum backlight_update_reason

用于更新背光的方法

常量

BACKLIGHT_UPDATE_HOTKEY

背光已使用热键更新。

BACKLIGHT_UPDATE_SYSFS

背光已使用 sysfs 更新。

描述

驱动程序在调用 backlight_force_update() 时指示用于更新背光的方法(原因)。

enum backlight_type

背光控制的类型

常量

BACKLIGHT_RAW

背光使用硬件寄存器控制。

BACKLIGHT_PLATFORM

背光使用平台特定的接口控制。

BACKLIGHT_FIRMWARE

背光使用标准固件接口控制。

BACKLIGHT_TYPE_MAX

条目数。

描述

用于控制背光的接口类型。

struct backlight_ops

背光操作

定义:

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);
};

成员

options

配置如何从核心调用操作。

options 参数用于调整核心的行为。设置 BL_CORE_SUSPENDRESUME 以在暂停和恢复时调用 update_status() 操作。

update_status

当属性发生更改时调用的操作。

通知背光驱动程序某些属性已更改。update_status 操作受 update_lock 的保护。

背光驱动程序应使用 backlight_is_blank() 检查显示是否已消隐并相应地设置亮度。当任何属性发生更改时,都会调用 update_status()。

返回值

成功时为 0,如果发生任何故障,则为负错误代码。

get_brightness

返回当前背光亮度。

驱动程序可以将此实现为从硬件的回读。此操作是可选的,如果不存在,则使用当前亮度属性值。

返回值

亮度值为 0 或正数。失败时,将返回负错误代码。

controls_device

检查显示设备

检查背光是否控制给定的显示设备。此操作是可选的,如果未实现,则假定显示始终是由背光控制的。

返回值

如果 display_dev 为 NULL 或 display_dev 与背光控制的设备匹配,则返回 true。否则,返回 false。

描述

在注册背光设备时指定背光操作。

struct backlight_properties

背光属性

定义:

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;
};

成员

brightness

用户请求的当前亮度。

当通过 sysfs 属性设置亮度时,背光核心确保范围是(0 到 max_brightness):/sys/class/backlight/<backlight>/brightness。

可以在传递给 devm_backlight_device_register() 的 backlight_properties 中设置此值,以设置默认亮度值。

max_brightness

最大亮度值。

必须在传递给 devm_backlight_device_register() 的 backlight_properties 中设置此值,并且驱动程序在注册后不得修改此值。

power

当前电源模式。

用户空间可以使用 sysfs 属性配置电源模式:/sys/class/backlight/<backlight>/bl_power。更新 power 属性时,会调用 update_status()。

可能的值为:(0:完全打开,4:完全关闭),请参阅 BACKLIGHT_POWER 常量。

启用背光设备时,power 设置为 BACKLIGHT_POWER_ON。禁用背光设备时,power 设置为 BACKLIGHT_POWER_OFF。

type

支持的背光类型。

背光类型允许用户空间根据背光类型做出适当的策略决策。

必须在传递给 devm_backlight_device_register() 的 backlight_properties 中设置此值。

state

背光核心的状态。

state 是一个位掩码。当预期显示消隐时,设置 BL_CORE_FBBLANK。当驱动程序暂停时,设置 BL_CORE_SUSPENDED。

背光驱动程序应在其 update_status() 操作中使用 backlight_is_blank(),而不是读取 state 属性。

状态由核心维护,驱动程序不得修改它。

scale

亮度刻度的类型。

描述

此结构定义背光的所有属性。

struct backlight_device

背光设备数据

定义:

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;
};

成员

props

背光属性

update_lock

调用 update_status() 操作时使用的锁。

update_lock 是一个内部背光锁,它序列化对 update_status() 操作的访问。背光核心在调用 update_status() 操作时持有 update_lock。背光驱动程序不得使用 update_lock。

ops_lock

在与 backlight_ops 相关的所有内容周围使用的锁。

ops_lock 是一个内部背光锁,用于保护 ops 指针,并且在所有对 ops 的访问以及调用操作时使用。背光驱动程序不得使用 ops_lock。

ops

指向背光操作的指针。

如果 ops 为 NULL,则注册此设备的驱动程序已卸载,并且如果 class_get_devdata() 指向该驱动程序主体中的某些内容,则它也无效。

entry

所有已注册背光设备的列表条目

dev

父设备。

use_count

未消隐显示的数目。

描述

此结构包含背光设备所需的所有数据。

int backlight_update_status(struct backlight_device *bd)

强制更新背光设备状态

参数

struct backlight_device *bd

背光设备

int backlight_enable(struct backlight_device *bd)

启用背光

参数

struct backlight_device *bd

要启用的背光设备

int backlight_disable(struct backlight_device *bd)

禁用背光

参数

struct backlight_device *bd

要禁用的背光设备

bool backlight_is_blank(const struct backlight_device *bd)

如果预期显示消隐,则返回 true

参数

const struct backlight_device *bd

背光设备

描述

如果以下任何一个为 true,则预期显示消隐

1) if power in not UNBLANK
2) if state indicate BLANK or SUSPENDED

如果预期显示消隐,则返回 true,否则返回 false。

int backlight_get_brightness(const struct backlight_device *bd)

返回当前亮度值

参数

const struct backlight_device *bd

背光设备

描述

返回当前亮度值,同时考虑当前状态。如果 backlight_is_blank() 返回 true,则返回 0 作为亮度,否则返回当前亮度属性值。

背光驱动程序应在其 update_status() 操作中使用此函数来获取亮度值。

void *bl_get_data(struct backlight_device *bl_dev)

访问 devdata

参数

struct backlight_device *bl_dev

指向背光设备的指针

描述

注册背光设备时,驱动程序可以提供 void * devdata。bl_get_data() 返回指向 devdata 的指针。

指向注册背光设备时存储的 devdata 的指针。

void backlight_force_update(struct backlight_device *bd, enum backlight_update_reason reason)

告知背光子系统硬件状态已更改

参数

struct backlight_device *bd

要更新的背光设备

enum backlight_update_reason reason

更新原因

描述

更新背光的内部状态以响应硬件事件,并生成 uevent 以通知用户空间。例如,当使用热键更改背光时,背光驱动程序应调用 backlight_force_update()。更新后的亮度使用 get_brightness() 读取,并且亮度值使用 uevent 报告。

struct backlight_device *backlight_device_get_by_name(const char *name)

按名称获取背光设备

参数

const char *name

设备名称

描述

此函数按名称查找背光设备。它获取对背光设备的引用,并且调用方有责任通过调用 put_device() 来释放引用。

返回值

如果找到,则返回指向背光设备的指针,否则返回 NULL。

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)

注册新的背光设备

参数

struct device *dev

要注册的设备

const char *name

设备的名称

struct device *parent

指向父设备的指针(通常与 dev 相同)

void *devdata

要存储的用于私有驱动程序的可选指针

const struct backlight_ops *ops

背光操作结构

const struct backlight_properties *props

背光属性

描述

创建并注册新的背光设备。注册背光设备时,必须在 props 参数中指定配置。请参阅 backlight_properties 的说明。

成功时返回 struct backlight,出错时返回 ERR_PTR

void devm_backlight_device_unregister(struct device *dev, struct backlight_device *bd)

注销背光设备

参数

struct device *dev

要注销的设备

struct backlight_device *bd

要注销的背光设备

描述

释放使用 devm_backlight_device_register() 分配的背光。通常,不需要调用此函数,资源管理代码将确保释放资源。

struct backlight_device *of_find_backlight_by_node(struct device_node *node)

按设备树节点查找背光设备

参数

struct device_node *node

背光设备的设备树节点

描述

返回指向与给定 DT 节点对应的背光设备的指针,如果不存在此类背光设备,或者如果尚未探测该设备,则返回 NULL。

此函数获取对背光设备的引用,并且调用方有责任通过在背光设备的 .dev 字段上调用 put_device() 来释放引用。

struct backlight_device *devm_of_find_backlight(struct device *dev)

查找设备的背光

参数

struct device *dev

设备

描述

此函数查找连接到 dev 的 DT 节点上的名为“backlight”的属性,并查找背光设备。查找是设备管理的,因此对背光设备的引用在驱动程序分离时会自动释放。

如果找到,则返回指向背光设备的指针。如果设置了 DT 属性,但未找到任何背光设备,则返回错误指针 -EPROBE_DEFER。如果不存在背光属性,则返回 NULL。