Documentation/firmware-guide/acpi/chromeos-acpi-device.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =====================
   4 Chrome OS ACPI Device
   5 =====================
   6
   7 Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device.
   8 The plug and play ID of a Chrome OS ACPI device is GGL0001. GGL is a valid PNP ID of Google.
   9 PNP ID can be used with the ACPI devices according to the guidelines. The following ACPI
  10 objects are supported:
  11
  12 .. flat-table:: Supported ACPI Objects
  13    :widths: 1 2
  14    :header-rows: 1
  15
  16    * - Object
  17      - Description
  18
  19    * - CHSW
  20      - Chrome OS switch positions
  21
  22    * - HWID
  23      - Chrome OS hardware ID
  24
  25    * - FWID
  26      - Chrome OS firmware version
  27
  28    * - FRID
  29      - Chrome OS read-only firmware version
  30
  31    * - BINF
  32      - Chrome OS boot information
  33
  34    * - GPIO
  35      - Chrome OS GPIO assignments
  36
  37    * - VBNV
  38      - Chrome OS NVRAM locations
  39
  40    * - VDTA
  41      - Chrome OS verified boot data
  42
  43    * - FMAP
  44      - Chrome OS flashmap base address
  45
  46    * - MLST
  47      - Chrome OS method list
  48
  49 CHSW (Chrome OS switch positions)
  50 =================================
  51 This control method returns the switch positions for Chrome OS specific hardware switches.
  52
  53 Arguments:
  54 ----------
  55 None
  56
  57 Result code:
  58 ------------
  59 An integer containing the switch positions as bitfields:
  60
  61 .. flat-table::
  62    :widths: 1 2
  63
  64    * - 0x00000002
  65      - Recovery button was pressed when x86 firmware booted.
  66
  67    * - 0x00000004
  68      - Recovery button was pressed when EC firmware booted. (required if EC EEPROM is
  69        rewritable; otherwise optional)
  70
  71    * - 0x00000020
  72      - Developer switch was enabled when x86 firmware booted.
  73
  74    * - 0x00000200
  75      - Firmware write protection was disabled when x86 firmware booted. (required if
  76        firmware write protection is controlled through x86 BIOS; otherwise optional)
  77
  78 All other bits are reserved and should be set to 0.
  79
  80 HWID (Chrome OS hardware ID)
  81 ============================
  82 This control method returns the hardware ID for the Chromebook.
  83
  84 Arguments:
  85 ----------
  86 None
  87
  88 Result code:
  89 ------------
  90 A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of
  91 EEPROM.
  92
  93 Note that the hardware ID can be up to 256 characters long, including the terminating null.
  94
  95 FWID (Chrome OS firmware version)
  96 =================================
  97 This control method returns the firmware version for the rewritable portion of the main
  98 processor firmware.
  99
 100 Arguments:
 101 ----------
 102 None
 103
 104 Result code:
 105 ------------
 106 A null-terminated ASCII string containing the complete firmware version for the rewritable
 107 portion of the main processor firmware.
 108
 109 FRID (Chrome OS read-only firmware version)
 110 ===========================================
 111 This control method returns the firmware version for the read-only portion of the main
 112 processor firmware.
 113
 114 Arguments:
 115 ----------
 116 None
 117
 118 Result code:
 119 ------------
 120 A null-terminated ASCII string containing the complete firmware version for the read-only
 121 (bootstrap + recovery ) portion of the main processor firmware.
 122
 123 BINF (Chrome OS boot information)
 124 =================================
 125 This control method returns information about the current boot.
 126
 127 Arguments:
 128 ----------
 129 None
 130
 131 Result code:
 132 ------------
 133
 134 .. code-block::
 135
 136    Package {
 137            Reserved1
 138            Reserved2
 139            Active EC Firmware
 140            Active Main Firmware Type
 141            Reserved5
 142    }
 143
 144 .. flat-table::
 145    :widths: 1 1 2
 146    :header-rows: 1
 147
 148    * - Field
 149      - Format
 150      - Description
 151
 152    * - Reserved1
 153      - DWORD
 154      - Set to 256 (0x100). This indicates this field is no longer used.
 155
 156    * - Reserved2
 157      - DWORD
 158      - Set to 256 (0x100). This indicates this field is no longer used.
 159
 160    * - Active EC firmware
 161      - DWORD
 162      - The EC firmware which was used during boot.
 163
 164        - 0 - Read-only (recovery) firmware
 165        - 1 - Rewritable firmware.
 166
 167        Set to 0 if EC firmware is always read-only.
 168
 169    * - Active Main Firmware Type
 170      - DWORD
 171      - The main firmware type which was used during boot.
 172
 173        - 0 - Recovery
 174        - 1 - Normal
 175        - 2 - Developer
 176        - 3 - netboot (factory installation only)
 177
 178        Other values are reserved.
 179
 180    * - Reserved5
 181      - DWORD
 182      - Set to 256 (0x100). This indicates this field is no longer used.
 183
 184 GPIO (Chrome OS GPIO assignments)
 185 =================================
 186 This control method returns information about Chrome OS specific GPIO assignments for
 187 Chrome OS hardware, so the kernel can directly control that hardware.
 188
 189 Arguments:
 190 ----------
 191 None
 192
 193 Result code:
 194 ------------
 195 .. code-block::
 196
 197         Package {
 198                 Package {
 199                         // First GPIO assignment
 200                         Signal Type        //DWORD
 201                         Attributes         //DWORD
 202                         Controller Offset  //DWORD
 203                         Controller Name    //ASCIIZ
 204                 },
 205                 ...
 206                 Package {
 207                         // Last GPIO assignment
 208                         Signal Type        //DWORD
 209                         Attributes         //DWORD
 210                         Controller Offset  //DWORD
 211                         Controller Name    //ASCIIZ
 212                 }
 213         }
 214
 215 Where ASCIIZ means a null-terminated ASCII string.
 216
 217 .. flat-table::
 218    :widths: 1 1 2
 219    :header-rows: 1
 220
 221    * - Field
 222      - Format
 223      - Description
 224
 225    * - Signal Type
 226      - DWORD
 227      - Type of GPIO signal
 228
 229        - 0x00000001 - Recovery button
 230        - 0x00000002 - Developer mode switch
 231        - 0x00000003 - Firmware write protection switch
 232        - 0x00000100 - Debug header GPIO 0
 233        - ...
 234        - 0x000001FF - Debug header GPIO 255
 235
 236        Other values are reserved.
 237
 238    * - Attributes
 239      - DWORD
 240      - Signal attributes as bitfields:
 241
 242        - 0x00000001 - Signal is active-high (for button, a GPIO value
 243          of 1 means the button is pressed; for switches, a GPIO value
 244          of 1 means the switch is enabled). If this bit is 0, the signal
 245          is active low. Set to 0 for debug header GPIOs.
 246
 247    * - Controller Offset
 248      - DWORD
 249      - GPIO number on the specified controller.
 250
 251    * - Controller Name
 252      - ASCIIZ
 253      - Name of the controller for the GPIO.
 254        Currently supported names:
 255        "NM10" - Intel NM10 chip
 256
 257 VBNV (Chrome OS NVRAM locations)
 258 ================================
 259 This control method returns information about the NVRAM (CMOS) locations used to
 260 communicate with the BIOS.
 261
 262 Arguments:
 263 ----------
 264 None
 265
 266 Result code:
 267 ------------
 268 .. code-block::
 269
 270         Package {
 271                 NV Storage Block Offset  //DWORD
 272                 NV Storage Block Size    //DWORD
 273         }
 274
 275 .. flat-table::
 276    :widths: 1 1 2
 277    :header-rows: 1
 278
 279    * - Field
 280      - Format
 281      - Description
 282
 283    * - NV Storage Block Offset
 284      - DWORD
 285      - Offset in CMOS bank 0 of the verified boot non-volatile storage block, counting from
 286        the first writable CMOS byte (that is, offset=0 is the byte following the 14 bytes of
 287        clock data).
 288
 289    * - NV Storage Block Size
 290      - DWORD
 291      - Size in bytes of the verified boot non-volatile storage block.
 292
 293 FMAP (Chrome OS flashmap address)
 294 =================================
 295 This control method returns the physical memory address of the start of the main processor
 296 firmware flashmap.
 297
 298 Arguments:
 299 ----------
 300 None
 301
 302 NoneResult code:
 303 ----------------
 304 A DWORD containing the physical memory address of the start of the main processor firmware
 305 flashmap.
 306
 307 VDTA (Chrome OS verified boot data)
 308 ===================================
 309 This control method returns the verified boot data block shared between the firmware
 310 verification step and the kernel verification step.
 311
 312 Arguments:
 313 ----------
 314 None
 315
 316 Result code:
 317 ------------
 318 A buffer containing the verified boot data block.
 319
 320 MECK (Management Engine Checksum)
 321 =================================
 322 This control method returns the SHA-1 or SHA-256 hash that is read out of the Management
 323 Engine extended registers during boot. The hash is exported via ACPI so the OS can verify that
 324 the ME firmware has not changed. If Management Engine is not present, or if the firmware was
 325 unable to read the extended registers, this buffer can be zero.
 326
 327 Arguments:
 328 ----------
 329 None
 330
 331 Result code:
 332 ------------
 333 A buffer containing the ME hash.
 334
 335 MLST (Chrome OS method list)
 336 ============================
 337 This control method returns a list of the other control methods supported by the Chrome OS
 338 hardware device.
 339
 340 Arguments:
 341 ----------
 342 None
 343
 344 Result code:
 345 ------------
 346 A package containing a list of null-terminated ASCII strings, one for each control method
 347 supported by the Chrome OS hardware device, not including the MLST method itself.
 348 For this version of the specification, the result is:
 349
 350 .. code-block::
 351
 352         Package {
 353                 "CHSW",
 354                 "FWID",
 355                 "HWID",
 356                 "FRID",
 357                 "BINF",
 358                 "GPIO",
 359                 "VBNV",
 360                 "FMAP",
 361                 "VDTA",
 362                 "MECK"
 363         }