Documentation/firmware-guide/acpi/non-d0-probe.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ========================================
   4 Probing devices in other D states than 0
   5 ========================================
   6
   7 Introduction
   8 ============
   9
  10 In some cases it may be preferred to leave certain devices powered off for the
  11 entire system bootup if powering on these devices has adverse side effects,
  12 beyond just powering on the said device.
  13
  14 How it works
  15 ============
  16
  17 The _DSC (Device State for Configuration) object that evaluates to an integer
  18 may be used to tell Linux the highest allowed D state for a device during
  19 probe. The support for _DSC requires support from the kernel bus type if the
  20 bus driver normally sets the device in D0 state for probe.
  21
  22 The downside of using _DSC is that as the device is not powered on, even if
  23 there's a problem with the device, the driver likely probes just fine but the
  24 first user will find out the device doesn't work, instead of a failure at probe
  25 time. This feature should thus be used sparingly.
  26
  27 I²C
  28 ---
  29
  30 If an I²C driver indicates its support for this by setting the
  31 I2C_DRV_ACPI_WAIVE_D0_PROBE flag in struct i2c_driver.flags field and the
  32 _DSC object evaluates to integer higher than the D state of the device,
  33 the device will not be powered on (put in D0 state) for probe.
  34
  35 D states
  36 --------
  37
  38 The D states and thus also the allowed values for _DSC are listed below. Refer
  39 to [1] for more information on device power states.
  40
  41 .. code-block:: text
  42
  43         Number  State   Description
  44         0       D0      Device fully powered on
  45         1       D1
  46         2       D2
  47         3       D3hot
  48         4       D3cold  Off
  49
  50 References
  51 ==========
  52
  53 [1] https://uefi.org/specifications/ACPI/6.4/02_Definition_of_Terms/Definition_of_Terms.html#device-power-state-definitions
  54
  55 Example
  56 =======
  57
  58 An ASL example describing an ACPI device using _DSC object to tell Operating
  59 System the device should remain powered off during probe looks like this. Some
  60 objects not relevant from the example point of view have been omitted.
  61
  62 .. code-block:: text
  63
  64         Device (CAM0)
  65         {
  66                 Name (_HID, "SONY319A")
  67                 Name (_UID, Zero)
  68                 Name (_CRS, ResourceTemplate ()
  69                 {
  70                         I2cSerialBus(0x0020, ControllerInitiated, 0x00061A80,
  71                                      AddressingMode7Bit, "\\_SB.PCI0.I2C0",
  72                                      0x00, ResourceConsumer)
  73                 })
  74                 Method (_DSC, 0, NotSerialized)
  75                 {
  76                         Return (0x4)
  77                 }
  78         }