Sakari, On 10/18/21 8:17 PM, Sakari Ailus wrote: > Document the use of the _DSC object for setting desirable power state > during probe. > > Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx> > Reviewed-by: Tomasz Figa <tfiga@xxxxxxxxxxxx> > --- > Documentation/firmware-guide/acpi/index.rst | 1 + > .../firmware-guide/acpi/non-d0-probe.rst | 78 +++++++++++++++++++ > 2 files changed, 79 insertions(+) > create mode 100644 Documentation/firmware-guide/acpi/non-d0-probe.rst > > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst > index a99ee402b212b..b053b0c3d6969 100644 > --- a/Documentation/firmware-guide/acpi/index.rst > +++ b/Documentation/firmware-guide/acpi/index.rst > @@ -26,5 +26,6 @@ ACPI Support > acpi-lid > lpit > video_extension > + non-d0-probe > extcon-intel-int3496 > intel-pmc-mux > diff --git a/Documentation/firmware-guide/acpi/non-d0-probe.rst b/Documentation/firmware-guide/acpi/non-d0-probe.rst > new file mode 100644 > index 0000000000000..78781e1ab6a3d > --- /dev/null > +++ b/Documentation/firmware-guide/acpi/non-d0-probe.rst > @@ -0,0 +1,78 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +======================================== > +Probing devices in other D states than 0 > +======================================== > + > +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 _DSC (Device State for Configuration) object that evaluates to an integer > +may be used to tell Linux the highest allowed D state for a device during > +probe. The support for _DSC requires support from the kernel bus type if the > +bus driver normally sets the device in D0 state for probe. > + > +The downside of using _DSC 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. > + > +I²C > +--- > + > +If an I²C driver indicates its support for this by setting the > +I2C_DRV_ACPI_WAIVE_D0_PROBE flag in struct i2c_driver.flags field and the > +_DSC 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. > + > +D states > +-------- > + > +The D states and thus also the allowed values for _DSC 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 > + > +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 _DSC 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 (_DSC, 0, NotSerialized) > + { > + Return (0x4) > + } One question here: Is the value of _DSC object evaluated from 'Method' or 'Name' ? > + } > -- Best regards, Bingbu Cao
