summaryrefslogtreecommitdiff
path: root/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst
blob: f37fc90ce340e4366961a2174a8462f28e6f1e6b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
.. SPDX-License-Identifier: GPL-2.0

=====================
Chrome OS ACPI Device
=====================

Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device.
The plug and play ID of a Chrome OS ACPI device is GGL0001. GGL is a valid PNP ID of Google.
PNP ID can be used with the ACPI devices according to the guidelines. The following ACPI
objects are supported:

.. flat-table:: Supported ACPI Objects
   :widths: 1 2
   :header-rows: 1

   * - Object
     - Description

   * - CHSW
     - Chrome OS switch positions

   * - HWID
     - Chrome OS hardware ID

   * - FWID
     - Chrome OS firmware version

   * - FRID
     - Chrome OS read-only firmware version

   * - BINF
     - Chrome OS boot information

   * - GPIO
     - Chrome OS GPIO assignments

   * - VBNV
     - Chrome OS NVRAM locations

   * - VDTA
     - Chrome OS verified boot data

   * - FMAP
     - Chrome OS flashmap base address

   * - MLST
     - Chrome OS method list

CHSW (Chrome OS switch positions)
=================================
This control method returns the switch positions for Chrome OS specific hardware switches.

Arguments:
----------
None

Result code:
------------
An integer containing the switch positions as bitfields:

.. flat-table::
   :widths: 1 2

   * - 0x00000002
     - Recovery button was pressed when x86 firmware booted.

   * - 0x00000004
     - Recovery button was pressed when EC firmware booted. (required if EC EEPROM is
       rewritable; otherwise optional)

   * - 0x00000020
     - Developer switch was enabled when x86 firmware booted.

   * - 0x00000200
     - Firmware write protection was disabled when x86 firmware booted. (required if
       firmware write protection is controlled through x86 BIOS; otherwise optional)

All other bits are reserved and should be set to 0.

HWID (Chrome OS hardware ID)
============================
This control method returns the hardware ID for the Chromebook.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of
EEPROM.

Note that the hardware ID can be up to 256 characters long, including the terminating null.

FWID (Chrome OS firmware version)
=================================
This control method returns the firmware version for the rewritable portion of the main
processor firmware.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the complete firmware version for the rewritable
portion of the main processor firmware.

FRID (Chrome OS read-only firmware version)
===========================================
This control method returns the firmware version for the read-only portion of the main
processor firmware.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the complete firmware version for the read-only
(bootstrap + recovery ) portion of the main processor firmware.

BINF (Chrome OS boot information)
=================================
This control method returns information about the current boot.

Arguments:
----------
None

Result code:
------------

.. code-block::

   Package {
           Reserved1
           Reserved2
           Active EC Firmware
           Active Main Firmware Type
           Reserved5
   }

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - Reserved1
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

   * - Reserved2
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

   * - Active EC firmware
     - DWORD
     - The EC firmware which was used during boot.

       - 0 - Read-only (recovery) firmware
       - 1 - Rewritable firmware.

       Set to 0 if EC firmware is always read-only.

   * - Active Main Firmware Type
     - DWORD
     - The main firmware type which was used during boot.

       - 0 - Recovery
       - 1 - Normal
       - 2 - Developer
       - 3 - netboot (factory installation only)

       Other values are reserved.

   * - Reserved5
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

GPIO (Chrome OS GPIO assignments)
=================================
This control method returns information about Chrome OS specific GPIO assignments for
Chrome OS hardware, so the kernel can directly control that hardware.

Arguments:
----------
None

Result code:
------------
.. code-block::

        Package {
                Package {
                        // First GPIO assignment
                        Signal Type        //DWORD
                        Attributes         //DWORD
                        Controller Offset  //DWORD
                        Controller Name    //ASCIIZ
                },
                ...
                Package {
                        // Last GPIO assignment
                        Signal Type        //DWORD
                        Attributes         //DWORD
                        Controller Offset  //DWORD
                        Controller Name    //ASCIIZ
                }
        }

Where ASCIIZ means a null-terminated ASCII string.

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - Signal Type
     - DWORD
     - Type of GPIO signal

       - 0x00000001 - Recovery button
       - 0x00000002 - Developer mode switch
       - 0x00000003 - Firmware write protection switch
       - 0x00000100 - Debug header GPIO 0
       - ...
       - 0x000001FF - Debug header GPIO 255

       Other values are reserved.

   * - Attributes
     - DWORD
     - Signal attributes as bitfields:

       - 0x00000001 - Signal is active-high (for button, a GPIO value
         of 1 means the button is pressed; for switches, a GPIO value
         of 1 means the switch is enabled). If this bit is 0, the signal
         is active low. Set to 0 for debug header GPIOs.

   * - Controller Offset
     - DWORD
     - GPIO number on the specified controller.

   * - Controller Name
     - ASCIIZ
     - Name of the controller for the GPIO.
       Currently supported names:
       "NM10" - Intel NM10 chip

VBNV (Chrome OS NVRAM locations)
================================
This control method returns information about the NVRAM (CMOS) locations used to
communicate with the BIOS.

Arguments:
----------
None

Result code:
------------
.. code-block::

        Package {
                NV Storage Block Offset  //DWORD
                NV Storage Block Size    //DWORD
        }

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - NV Storage Block Offset
     - DWORD
     - Offset in CMOS bank 0 of the verified boot non-volatile storage block, counting from
       the first writable CMOS byte (that is, offset=0 is the byte following the 14 bytes of
       clock data).

   * - NV Storage Block Size
     - DWORD
     - Size in bytes of the verified boot non-volatile storage block.

FMAP (Chrome OS flashmap address)
=================================
This control method returns the physical memory address of the start of the main processor
firmware flashmap.

Arguments:
----------
None

NoneResult code:
----------------
A DWORD containing the physical memory address of the start of the main processor firmware
flashmap.

VDTA (Chrome OS verified boot data)
===================================
This control method returns the verified boot data block shared between the firmware
verification step and the kernel verification step.

Arguments:
----------
None

Result code:
------------
A buffer containing the verified boot data block.

MECK (Management Engine Checksum)
=================================
This control method returns the SHA-1 or SHA-256 hash that is read out of the Management
Engine extended registers during boot. The hash is exported via ACPI so the OS can verify that
the ME firmware has not changed. If Management Engine is not present, or if the firmware was
unable to read the extended registers, this buffer can be zero.

Arguments:
----------
None

Result code:
------------
A buffer containing the ME hash.

MLST (Chrome OS method list)
============================
This control method returns a list of the other control methods supported by the Chrome OS
hardware device.

Arguments:
----------
None

Result code:
------------
A package containing a list of null-terminated ASCII strings, one for each control method
supported by the Chrome OS hardware device, not including the MLST method itself.
For this version of the specification, the result is:

.. code-block::

        Package {
                "CHSW",
                "FWID",
                "HWID",
                "FRID",
                "BINF",
                "GPIO",
                "VBNV",
                "FMAP",
                "VDTA",
                "MECK"
        }