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