DRM database property: privacy-screen hw-state

Back to index

Details

Name

privacy-screen hw-state

Flags

immutable

Type

enum

Attached to

connector

Specification

{"Disabled", "Enabled", "Disabled-locked", "Enabled-locked"}

Documentation

These 2 optional properties can be used to query the state of the
electronic privacy screen that is available on some displays; and in
some cases also control the state. If a driver implements these
properties then both properties must be present.

"privacy-screen hw-state" is read-only and reflects the actual state
of the privacy-screen, possible values: "Enabled", "Disabled,
"Enabled-locked", "Disabled-locked". The locked states indicate
that the state cannot be changed through the DRM API. E.g. there
might be devices where the firmware-setup options, or a hardware
slider-switch, offer always on / off modes.

"privacy-screen sw-state" can be set to change the privacy-screen state
when not locked. In this case the driver must update the hw-state
property to reflect the new state on completion of the commit of the
sw-state property. Setting the sw-state property when the hw-state is
locked must be interpreted by the driver as a request to change the
state to the set state when the hw-state becomes unlocked. E.g. if
"privacy-screen hw-state" is "Enabled-locked" and the sw-state
gets set to "Disabled" followed by the user unlocking the state by
changing the slider-switch position, then the driver must set the
state to "Disabled" upon receiving the unlock event.

In some cases the privacy-screen's actual state might change outside of
control of the DRM code. E.g. there might be a firmware handled hotkey
which toggles the actual state, or the actual state might be changed
through another userspace API such as writing /proc/acpi/ibm/lcdshadow.
In this case the driver must update both the hw-state and the sw-state
to reflect the new value, overwriting any pending state requests in the
sw-state. Any pending sw-state requests are thus discarded.

Note that the ability for the state to change outside of control of
the DRM master process means that userspace must not cache the value
of the sw-state. Caching the sw-state value and including it in later
atomic commits may lead to overriding a state change done through e.g.
a firmware handled hotkey. Therefor userspace must not include the
privacy-screen sw-state in an atomic commit unless it wants to change
its value.

Driver support