Document the use of the _DSE object for setting desirable power state during probe.
Signed-off-by: Sakari Ailus <[email protected]> Reviewed-by: Tomasz Figa <[email protected]> --- Documentation/firmware-guide/acpi/index.rst | 1 + .../firmware-guide/acpi/low-power-probe.rst | 69 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 Documentation/firmware-guide/acpi/low-power-probe.rst diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index f72b5f1769fb2..d02712acccbc0 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -25,5 +25,6 @@ ACPI Support acpi-lid lpit video_extension + low-power-probe extcon-intel-int3496 intel-pmc-mux diff --git a/Documentation/firmware-guide/acpi/low-power-probe.rst b/Documentation/firmware-guide/acpi/low-power-probe.rst new file mode 100644 index 0000000000000..b96804d959a6c --- /dev/null +++ b/Documentation/firmware-guide/acpi/low-power-probe.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +Probing I²C devices in low power state +====================================== + +Introduction +============ + +In some cases it may be preferred to leave certain devices powered off for the +entire system bootup if powering on these devices has adverse side effects, +beyond just powering on the said device. + +How it works +============ + +The _DSE (Device State for Enumeration) object that evaluates to integer 0 may +be used to tell Linux the highest allowed D state for a device during probe. If +the driver indicates its support for this by setting the +I2C_DRV_FL_ALLOW_LOW_POWER_PROBE flag in struct i2c_driver.flags field and the +_DSE object evaluates to integer higher than the D state of the device, the +device will not be powered on (put in D0 state) for probe. + +The D states and thus also the allowed values for _DSE are listed below. Refer +to [1] for more information on device power states. + +.. code-block:: text + + Number State Description + 0 D0 Device fully powered on + 1 D1 + 2 D2 + 3 D3hot + 4 D3cold Off + +The downside is that as the device is not powered on, even if there's a problem +with the device, the driver likely probes just fine but the first user will +find out the device doesn't work, instead of a failure at probe time. This +feature should thus be used sparingly. + +References +========== + +[1] https://uefi.org/specifications/ACPI/6.4/02_Definition_of_Terms/Definition_of_Terms.html#device-power-state-definitions + +Example +======= + +An ASL example describing an ACPI device using _DSE object to tell Operating +System the device should remain powered off during probe looks like this. Some +objects not relevant from the example point of view have been omitted. + +.. code-block:: text + + Device (CAM0) + { + Name (_HID, "SONY319A") + Name (_UID, Zero) + Name (_CRS, ResourceTemplate () + { + I2cSerialBus(0x0020, ControllerInitiated, 0x00061A80, + AddressingMode7Bit, "\\_SB.PCI0.I2C0", + 0x00, ResourceConsumer) + }) + Name (_DSE, 0, NotSerialized) + { + Return (0x4) + } + } -- 2.20.1
