1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==========================
4 ACPI _OSI and _REV methods
5 ==========================
6
7 An ACPI BIOS can use the "Operating System Int
8 to find out what the operating system supports
9 AML code includes _OSI("XYZ"), the kernel's AM
10 can evaluate that method, look to see if it su
11 and answer YES or NO to the BIOS.
12
13 The ACPI _REV method returns the "Revision of
14 that OSPM supports"
15
16 This document explains how and why the BIOS an
17 It also explains how and why they are widely m
18
19 How to use _OSI
20 ===============
21
22 Linux runs on two groups of machines -- those
23 to be compatible with Linux, and those that we
24 but where Linux was installed to replace the o
25
26 The larger group is the systems tested to run
27 but many were tested to run with just one spec
28 So even though the BIOS may use _OSI to query
29 only a single path through the BIOS has actual
30 Experience shows that taking untested paths th
31 exposes Linux to an entire category of BIOS bu
32 For this reason, Linux _OSI defaults must cont
33 with all versions of Windows.
34
35 But Linux isn't actually compatible with Windo
36 has also been hurt with regressions when Linux
37 Windows to its list of _OSI strings. So it is
38 will be more thoroughly vetted before shipping
39 But it is likely that they will all eventually
40
41 What should an OEM do if they want to support
42 using the same BIOS image? Often they need to
43 for Linux to deal with how Linux is different
44
45 In this case, the OEM should create custom ASL
46 Linux kernel and changes to Linux kernel drive
47 ASL. The easiest way to accomplish this is to
48 method (_DSM) that is called from the Linux ke
49
50 In the past the kernel used to support somethi
51 _OSI("Linux-OEM-my_interface_name")
52 where 'OEM' is needed if this is an OEM-specif
53 and 'my_interface_name' describes the hook, wh
54 quirk, a bug, or a bug-fix.
55
56 However this was discovered to be abused by ot
57 completely unrelated code on completely unrela
58 an evaluation of all of its uses. This uncover
59 for any of the original reasons. As such, the
60 any custom Linux-* strings by default.
61
62 That was easy. Read on, to find out how to do
63
64 Before _OSI, there was _OS
65 ==========================
66
67 ACPI 1.0 specified "_OS" as an
68 "object that evaluates to a string that identi
69
70 The ACPI BIOS flow would include an evaluation
71 interpreter in the kernel would return to it a
72
73 Windows 98, SE: "Microsoft Windows"
74 Windows ME: "Microsoft WindowsME:Millennium Ed
75 Windows NT: "Microsoft Windows NT"
76
77 The idea was on a platform tasked with running
78 the BIOS could use _OS to enable devices that
79 might support, or enable quirks or bug workaro
80 necessary to make the platform compatible with
81
82 But _OS had fundamental problems. First, the
83 of every possible version of the OS that would
84 all the quirks of those OS's. Certainly it wo
85 for the BIOS to ask *specific* things of the O
86 "do you support a specific interface", and thu
87 _OSI was born to replace _OS.
88
89 _OS was abandoned, though even today, many BIO
90 _OS "Microsoft Windows NT", though it seems so
91 that anybody would install those old operating
92 over what came with the machine.
93
94 Linux answers "Microsoft Windows NT" to please
95 That is the *only* viable strategy, as that is
96 and so doing otherwise could steer the BIOS do
97
98 _OSI is born, and immediately misused
99 =====================================
100
101 With _OSI, the *BIOS* provides the string desc
102 and asks the OS: "YES/NO, are you compatible w
103
104 eg. _OSI("3.0 Thermal Model") would return TRU
105 to deal with the thermal extensions made to th
106 An old OS that doesn't know about those extens
107 and a new OS may be able to return TRUE.
108
109 For an OS-specific interface, the ACPI spec sa
110 were to agree on a string of the form such as
111
112 But two bad things happened. First, the Windo
113 not as designed, but as a direct replacement f
114 the OS version, rather than an OS supported in
115 from the start, the ACPI 3.0 spec itself codif
116 in example code using _OSI("Windows 2001").
117
118 This misuse was adopted and continues today.
119
120 Linux had no choice but to also return TRUE to
121 and its successors. To do otherwise would vir
122 a BIOS that has been tested only with that _OS
123
124 This strategy is problematic, as Linux is neve
125 the latest version of Windows, and sometimes i
126 to iron out incompatibilities.
127
128 Not to be out-done, the Linux community made t
129 to _OSI("Linux"). Doing so is even worse than
130 of _OSI, as "Linux" does not even contain any
131 _OSI("Linux") led to some BIOS' malfunctioning
132 using it in untested BIOS flows. But some OEM
133 in tested flows to support real Linux features
134 removed _OSI("Linux"), and added a cmdline par
135 for legacy systems still needed it. Further a
136 for all BIOS's that invoke it.
137
138 No BIOS should use _OSI("Linux").
139
140 The result is a strategy for Linux to maximize
141 ACPI BIOS that are tested on Windows machines.
142 of over-stating that compatibility; but the al
143 catastrophic failure resulting from the BIOS t
144 were never validated under *any* OS.
145
146 Do not use _REV
147 ===============
148
149 Since _OSI("Linux") went away, some BIOS write
150 to support Linux and Windows differences in th
151
152 _REV was defined in ACPI 1.0 to return the ver
153 supported by the OS and the OS AML interpreter
154
155 Modern Windows returns _REV = 2. Linux used A
156 which would increment, based on the version of
157
158 Unfortunately, _REV was also misused. eg. som
159 for _REV = 3, and do something for Linux, but
160 _REV = 4, that support broke.
161
162 In response to this problem, Linux returns _RE
163 from mid-2015 onward. The ACPI specification
164 to reflect that _REV is deprecated, and always
165
166 Apple Mac and _OSI("Darwin")
167 ============================
168
169 On Apple's Mac platforms, the ACPI BIOS invoke
170 to determine if the machine is running Apple O
171
172 Like Linux's _OSI("*Windows*") strategy, Linux
173 answering YES to _OSI("Darwin") to enable full
174 to the hardware and validated BIOS paths seen
175 Just like on Windows-tested platforms, this st
176
177 Starting in Linux-3.18, the kernel answered YE
178 for the purpose of enabling Mac Thunderbolt su
179 if the kernel noticed _OSI("Darwin") being inv
180 disabled all _OSI("*Windows*") to keep poorly
181 from going down untested combinations of paths
182
183 The Linux-3.18 change in default caused power
184 laptops, and the 3.18 implementation did not a
185 the default via cmdline "acpi_osi=!Darwin". L
186 the ability to use acpi_osi=!Darwin as a worka
187 we hope to see Mac Thunderbolt power managemen
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.