1.. SPDX-License-Identifier: GPL-2.0
2
3=====================
4Chrome OS ACPI Device
5=====================
6
7Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device.
8The plug and play ID of a Chrome OS ACPI device is GGL0001. GGL is a valid PNP ID of Google.
9PNP ID can be used with the ACPI devices according to the guidelines. The following ACPI
10objects 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
49CHSW (Chrome OS switch positions)
50=================================
51This control method returns the switch positions for Chrome OS specific hardware switches.
52
53Arguments:
54----------
55None
56
57Result code:
58------------
59An 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
78All other bits are reserved and should be set to 0.
79
80HWID (Chrome OS hardware ID)
81============================
82This control method returns the hardware ID for the Chromebook.
83
84Arguments:
85----------
86None
87
88Result code:
89------------
90A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of
91EEPROM.
92
93Note that the hardware ID can be up to 256 characters long, including the terminating null.
94
95FWID (Chrome OS firmware version)
96=================================
97This control method returns the firmware version for the rewritable portion of the main
98processor firmware.
99
100Arguments:
101----------
102None
103
104Result code:
105------------
106A null-terminated ASCII string containing the complete firmware version for the rewritable
107portion of the main processor firmware.
108
109FRID (Chrome OS read-only firmware version)
110===========================================
111This control method returns the firmware version for the read-only portion of the main
112processor firmware.
113
114Arguments:
115----------
116None
117
118Result code:
119------------
120A null-terminated ASCII string containing the complete firmware version for the read-only
121(bootstrap + recovery ) portion of the main processor firmware.
122
123BINF (Chrome OS boot information)
124=================================
125This control method returns information about the current boot.
126
127Arguments:
128----------
129None
130
131Result 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
184GPIO (Chrome OS GPIO assignments)
185=================================
186This control method returns information about Chrome OS specific GPIO assignments for
187Chrome OS hardware, so the kernel can directly control that hardware.
188
189Arguments:
190----------
191None
192
193Result 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
215Where 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
257VBNV (Chrome OS NVRAM locations)
258================================
259This control method returns information about the NVRAM (CMOS) locations used to
260communicate with the BIOS.
261
262Arguments:
263----------
264None
265
266Result 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
293FMAP (Chrome OS flashmap address)
294=================================
295This control method returns the physical memory address of the start of the main processor
296firmware flashmap.
297
298Arguments:
299----------
300None
301
302NoneResult code:
303----------------
304A DWORD containing the physical memory address of the start of the main processor firmware
305flashmap.
306
307VDTA (Chrome OS verified boot data)
308===================================
309This control method returns the verified boot data block shared between the firmware
310verification step and the kernel verification step.
311
312Arguments:
313----------
314None
315
316Result code:
317------------
318A buffer containing the verified boot data block.
319
320MECK (Management Engine Checksum)
321=================================
322This control method returns the SHA-1 or SHA-256 hash that is read out of the Management
323Engine extended registers during boot. The hash is exported via ACPI so the OS can verify that
324the ME firmware has not changed. If Management Engine is not present, or if the firmware was
325unable to read the extended registers, this buffer can be zero.
326
327Arguments:
328----------
329None
330
331Result code:
332------------
333A buffer containing the ME hash.
334
335MLST (Chrome OS method list)
336============================
337This control method returns a list of the other control methods supported by the Chrome OS
338hardware device.
339
340Arguments:
341----------
342None
343
344Result code:
345------------
346A package containing a list of null-terminated ASCII strings, one for each control method
347supported by the Chrome OS hardware device, not including the MLST method itself.
348For 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        }
364