Documentation/drivers/dt_entries.md

   1 # Driver Devicetree Entries
   2
   3 Let's take a look at an example entry from
   4 ``src/mainboard/google/hatch/variants/hatch/overridetree.cb``:
   5
   6 ```
   7 device pci 15.0 on
   8         chip drivers/i2c/generic
   9                 register "hid" = ""ELAN0000""
  10                 register "desc" = ""ELAN Touchpad""
  11                 register "irq" = "ACPI_IRQ_WAKE_LEVEL_LOW(GPP_A21_IRQ)"
  12                 register "detect" = "1"
  13                 register "wake" = "GPE0_DW0_21"
  14                 device i2c 15 on end
  15         end
  16 end # I2C #0
  17 ```
  18
  19 When this entry is processed during ramstage, it will create a device in the
  20 ACPI SSDT table (all devices in devicetrees end up in the SSDT table).  The ACPI
  21 generation routines in coreboot actually generate the raw bytecode that
  22 represents the device's structure, but looking at ASL code is easier to
  23 understand; see below for what the disassembled bytecode looks like:
  24
  25 ```
  26 Scope (\_SB.PCI0.I2C0)
  27 {
  28     Device (D015)
  29     {
  30         Name (_HID, "ELAN0000")  // _HID: Hardware ID
  31         Name (_UID, Zero)  // _UID: Unique ID
  32         Name (_DDN, "ELAN Touchpad")  // _DDN: DOS Device Name
  33         Method (_STA, 0, NotSerialized)  // _STA: Status
  34         {
  35             Return (0x0F)
  36         }
  37         Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
  38         {
  39             I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
  40                 AddressingMode7Bit, "\\_SB.PCI0.I2C0",
  41                 0x00, ResourceConsumer, , Exclusive, )
  42             Interrupt (ResourceConsumer, Level, ActiveLow, ExclusiveAndWake, ,, )
  43             {
  44                 0x0000002D,
  45             }
  46         })
  47         Name (_S0W, ACPI_DEVICE_SLEEP_D3_HOT)  // _S0W: S0 Device Wake State
  48         Name (_PRW, Package (0x02)  // _PRW: Power Resources for Wake
  49         {
  50             0x15, // GPE #21
  51             0x03  // Sleep state S3
  52         })
  53     }
  54 }
  55 ```
  56
  57 You can see it generates _HID, _UID, _DDN, _STA, _CRS, _S0W, and _PRW
  58 names/methods in the Device's scope.
  59
  60 ## Utilizing a device driver
  61
  62 The device driver must be enabled for your build.  There will be a CONFIG option
  63 in the Kconfig file in the directory that the driver is in (e.g.,
  64 ``src/drivers/i2c/generic`` contains a Kconfig file; the option here is named
  65 CONFIG_DRIVERS_I2C_GENERIC).  The config option will need to be added to your
  66 mainboard's Kconfig file (e.g., ``src/mainboard/google/hatch/Kconfig``) in order
  67 to be compiled into your build.
  68
  69 ## Diving into the above example:
  70
  71 Let's take a look at how the devicetree language corresponds to the generated
  72 ASL.
  73
  74 First, note this:
  75
  76 ```
  77     chip drivers/i2c/generic
  78 ```
  79
  80 This means that the device driver we're using has a corresponding structure,
  81 located at ``src/drivers/i2c/generic/chip.h``, named **struct
  82 drivers_i2c_generic_config** and it contains many properties you can specify to
  83 be included in the ACPI table.
  84
  85 ### hid
  86
  87 ```
  88     register "hid" = ""ELAN0000""
  89 ```
  90
  91 This corresponds to **const char *hid** in the struct.  In the ACPI ASL, it
  92 translates to:
  93
  94 ```
  95     Name (_HID, "ELAN0000") // _HID: Hardware ID
  96 ```
  97
  98 under the device.  **This property is used to match the device to its driver
  99 during enumeration in the OS.**
 100
 101 ### desc
 102
 103 ```
 104     register "desc" = ""ELAN Touchpad""
 105 ```
 106
 107 corresponds to **const char *desc** and in ASL:
 108
 109 ```
 110     Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
 111 ```
 112
 113 ### irq
 114
 115 It also adds the interrupt,
 116
 117 ```
 118     Interrupt (ResourceConsumer, Level, ActiveLow, ExclusiveAndWake, ,, )
 119     {
 120         0x0000002D,
 121     }
 122 ```
 123
 124 which comes from:
 125
 126 ```
 127     register "irq" = "ACPI_IRQ_WAKE_LEVEL_LOW(GPP_A21_IRQ)"
 128 ```
 129
 130 The GPIO pin IRQ settings control the "Level", "ActiveLow", and
 131 "ExclusiveAndWake" settings seen above (level means it is a level-triggered
 132 interrupt as opposed to edge-triggered; active low means the interrupt is
 133 triggered when the signal is low).
 134
 135 Note that the ACPI_IRQ_WAKE_LEVEL_LOW macro informs the platform that the GPIO
 136 will be routed through SCI (ACPI's System Control Interrupt) for use as a wake
 137 source.  Also note that the IRQ names are SoC-specific, and you will need to
 138 find the names in your SoC's header file.  The ACPI_* macros are defined in
 139 ``src/arch/x86/include/acpi/acpi_device.h``.
 140
 141 Using a GPIO as an IRQ requires that it is configured in coreboot correctly.
 142 This is often done in a mainboard-specific file named ``gpio.c``.
 143
 144 ### detect
 145
 146 The next register is:
 147
 148 ```
 149     register "detect" = "1"
 150 ```
 151
 152 This flag tells the I2C driver that it should attempt to detect the presence of
 153 the device (using an I2C zero-byte write), and only generate a SSDT entry if the
 154 device is actually present. This alleviates the OS from having to determine if
 155 a device is present or not (ChromeOS/Linux) and prevents resource conflict/
 156 driver issues (Windows).
 157
 158 Currently, the detect feature works and is hooked up for all I2C touchpads,
 159 and should be used any time a board has multiple touchpad options.
 160 I2C audio devices should also work without issue.
 161
 162 Touchscreens can use this feature as well, but special care is needed to
 163 implement the proper power sequencing for the device to be detected. Generally,
 164 this means driving the enable GPIO high and holding the reset GPIO low in early
 165 GPIO init (bootblock/romstage), then releasing reset in ramstage. The first
 166 mainboards in the tree to implement this are google/skyrim and google/guybrush.
 167 This feature has also been used in downstream forks without issue for some time
 168 now on several other boards.
 169
 170 ### wake
 171
 172 The last register is:
 173
 174 ```
 175     register "wake" = "GPE0_DW0_21"
 176 ```
 177
 178 which indicates that the method of waking the system using the touchpad will be
 179 through a GPE, #21 associated with DW0, which is set up in devicetree.cb from
 180 this example.  The "21" indicates GPP_X21, where GPP_X is mapped onto DW0
 181 elsewhere in the devicetree.
 182
 183 The last bit of the definition of that device includes:
 184
 185 ```
 186     device i2c 15 on end
 187 ```
 188
 189 which means it's an I2C device, with 7-bit address 0x15, and the device is "on",
 190 meaning it will be exposed in the ACPI table.  The PCI device that the
 191 controller is located in determines which I2C bus the device is expected to be
 192 found on.  In this example, this is I2C bus 0.  This also determines the ACPI
 193 "Scope" that the device names and methods will live under, in this case
 194 "\_SB.PCI0.I2C0".
 195
 196 ## Other auto-generated names
 197
 198 (see [ACPI specification
 199 6.3](https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf)
 200 for more details on ACPI methods)
 201
 202 ### _S0W (S0 Device Wake State)
 203 _S0W indicates the deepest S0 sleep state this device can wake itself from,
 204 which in this case is ACPI_DEVICE_SLEEP_D3_HOT, representing _D3hot_.
 205
 206 ### _PRW (Power Resources for Wake)
 207 _PRW indicates the power resources and events required for wake.  There are no
 208 dependent power resources, but the GPE (GPE0_DW0_21) is mentioned here (0x15),
 209 as well as the deepest sleep state supporting waking the system (3), which is
 210 S3.
 211
 212 ### _STA (Status)
 213 The _STA method is generated automatically, and its values, 0xF, indicates the
 214 following:
 215
 216     Bit [0] – Set if the device is present.
 217     Bit [1] – Set if the device is enabled and decoding its resources.
 218     Bit [2] – Set if the device should be shown in the UI.
 219     Bit [3] – Set if the device is functioning properly (cleared if device failed its diagnostics).
 220
 221 ### _CRS (Current resource settings)
 222 The _CRS method is generated automatically, as the driver knows it is an I2C
 223 controller, and so specifies how to configure the controller for proper
 224 operation with the touchpad.
 225
 226 ```
 227 Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
 228 {
 229     I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
 230                     AddressingMode7Bit, "\\_SB.PCI0.I2C0",
 231                     0x00, ResourceConsumer, , Exclusive, )
 232 ```
 233
 234 ## Notes
 235
 236  - **All device driver entries in devicetrees end up in the SSDT table, and are
 237    generated in coreboot's ramstage**
 238    (The lone exception to this rule is i2c touchpads with the 'detect' flag set;
 239     in this case, devices not present will not be added to the SSDT)