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