Documentation/firmware-guide/acpi/osi.rst

   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 Interfaces" method (_OSI)
   8 to find out what the operating system supports. Eg. If BIOS
   9 AML code includes _OSI("XYZ"), the kernel's AML interpreter
  10 can evaluate that method, look to see if it supports 'XYZ'
  11 and answer YES or NO to the BIOS.
  12
  13 The ACPI _REV method returns the "Revision of the ACPI specification
  14 that OSPM supports"
  15
  16 This document explains how and why the BIOS and Linux should use these methods.
  17 It also explains how and why they are widely misused.
  18
  19 How to use _OSI
  20 ===============
  21
  22 Linux runs on two groups of machines -- those that are tested by the OEM
  23 to be compatible with Linux, and those that were never tested with Linux,
  24 but where Linux was installed to replace the original OS (Windows or OSX).
  25
  26 The larger group is the systems tested to run only Windows.  Not only that,
  27 but many were tested to run with just one specific version of Windows.
  28 So even though the BIOS may use _OSI to query what version of Windows is running,
  29 only a single path through the BIOS has actually been tested.
  30 Experience shows that taking untested paths through the BIOS
  31 exposes Linux to an entire category of BIOS bugs.
  32 For this reason, Linux _OSI defaults must continue to claim compatibility
  33 with all versions of Windows.
  34
  35 But Linux isn't actually compatible with Windows, and the Linux community
  36 has also been hurt with regressions when Linux adds the latest version of
  37 Windows to its list of _OSI strings.  So it is possible that additional strings
  38 will be more thoroughly vetted before shipping upstream in the future.
  39 But it is likely that they will all eventually be added.
  40
  41 What should an OEM do if they want to support Linux and Windows
  42 using the same BIOS image?  Often they need to do something different
  43 for Linux to deal with how Linux is different from Windows.
  44 Here the BIOS should ask exactly what it wants to know:
  45
  46 _OSI("Linux-OEM-my_interface_name")
  47 where 'OEM' is needed if this is an OEM-specific hook,
  48 and 'my_interface_name' describes the hook, which could be a
  49 quirk, a bug, or a bug-fix.
  50
  51 In addition, the OEM should send a patch to upstream Linux
  52 via the linux-acpi@vger.kernel.org mailing list.  When that patch
  53 is checked into Linux, the OS will answer "YES" when the BIOS
  54 on the OEM's system uses _OSI to ask if the interface is supported
  55 by the OS.  Linux distributors can back-port that patch for Linux
  56 pre-installs, and it will be included by all distributions that
  57 re-base to upstream.  If the distribution can not update the kernel binary,
  58 they can also add an acpi_osi=Linux-OEM-my_interface_name
  59 cmdline parameter to the boot loader, as needed.
  60
  61 If the string refers to a feature where the upstream kernel
  62 eventually grows support, a patch should be sent to remove
  63 the string when that support is added to the kernel.
  64
  65 That was easy.  Read on, to find out how to do it wrong.
  66
  67 Before _OSI, there was _OS
  68 ==========================
  69
  70 ACPI 1.0 specified "_OS" as an
  71 "object that evaluates to a string that identifies the operating system."
  72
  73 The ACPI BIOS flow would include an evaluation of _OS, and the AML
  74 interpreter in the kernel would return to it a string identifying the OS:
  75
  76 Windows 98, SE: "Microsoft Windows"
  77 Windows ME: "Microsoft WindowsME:Millenium Edition"
  78 Windows NT: "Microsoft Windows NT"
  79
  80 The idea was on a platform tasked with running multiple OS's,
  81 the BIOS could use _OS to enable devices that an OS
  82 might support, or enable quirks or bug workarounds
  83 necessary to make the platform compatible with that pre-existing OS.
  84
  85 But _OS had fundamental problems.  First, the BIOS needed to know the name
  86 of every possible version of the OS that would run on it, and needed to know
  87 all the quirks of those OS's.  Certainly it would make more sense
  88 for the BIOS to ask *specific* things of the OS, such
  89 "do you support a specific interface", and thus in ACPI 3.0,
  90 _OSI was born to replace _OS.
  91
  92 _OS was abandoned, though even today, many BIOS look for
  93 _OS "Microsoft Windows NT", though it seems somewhat far-fetched
  94 that anybody would install those old operating systems
  95 over what came with the machine.
  96
  97 Linux answers "Microsoft Windows NT" to please that BIOS idiom.
  98 That is the *only* viable strategy, as that is what modern Windows does,
  99 and so doing otherwise could steer the BIOS down an untested path.
 100
 101 _OSI is born, and immediately misused
 102 =====================================
 103
 104 With _OSI, the *BIOS* provides the string describing an interface,
 105 and asks the OS: "YES/NO, are you compatible with this interface?"
 106
 107 eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how
 108 to deal with the thermal extensions made to the ACPI 3.0 specification.
 109 An old OS that doesn't know about those extensions would answer FALSE,
 110 and a new OS may be able to return TRUE.
 111
 112 For an OS-specific interface, the ACPI spec said that the BIOS and the OS
 113 were to agree on a string of the form such as "Windows-interface_name".
 114
 115 But two bad things happened.  First, the Windows ecosystem used _OSI
 116 not as designed, but as a direct replacement for _OS -- identifying
 117 the OS version, rather than an OS supported interface.  Indeed, right
 118 from the start, the ACPI 3.0 spec itself codified this misuse
 119 in example code using _OSI("Windows 2001").
 120
 121 This misuse was adopted and continues today.
 122
 123 Linux had no choice but to also return TRUE to _OSI("Windows 2001")
 124 and its successors.  To do otherwise would virtually guarantee breaking
 125 a BIOS that has been tested only with that _OSI returning TRUE.
 126
 127 This strategy is problematic, as Linux is never completely compatible with
 128 the latest version of Windows, and sometimes it takes more than a year
 129 to iron out incompatibilities.
 130
 131 Not to be out-done, the Linux community made things worse by returning TRUE
 132 to _OSI("Linux").  Doing so is even worse than the Windows misuse
 133 of _OSI, as "Linux" does not even contain any version information.
 134 _OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's
 135 using it in untested BIOS flows.  But some OEM's used _OSI("Linux")
 136 in tested flows to support real Linux features.  In 2009, Linux
 137 removed _OSI("Linux"), and added a cmdline parameter to restore it
 138 for legacy systems still needed it.  Further a BIOS_BUG warning prints
 139 for all BIOS's that invoke it.
 140
 141 No BIOS should use _OSI("Linux").
 142
 143 The result is a strategy for Linux to maximize compatibility with
 144 ACPI BIOS that are tested on Windows machines.  There is a real risk
 145 of over-stating that compatibility; but the alternative has often been
 146 catastrophic failure resulting from the BIOS taking paths that
 147 were never validated under *any* OS.
 148
 149 Do not use _REV
 150 ===============
 151
 152 Since _OSI("Linux") went away, some BIOS writers used _REV
 153 to support Linux and Windows differences in the same BIOS.
 154
 155 _REV was defined in ACPI 1.0 to return the version of ACPI
 156 supported by the OS and the OS AML interpreter.
 157
 158 Modern Windows returns _REV = 2.  Linux used ACPI_CA_SUPPORT_LEVEL,
 159 which would increment, based on the version of the spec supported.
 160
 161 Unfortunately, _REV was also misused.  eg. some BIOS would check
 162 for _REV = 3, and do something for Linux, but when Linux returned
 163 _REV = 4, that support broke.
 164
 165 In response to this problem, Linux returns _REV = 2 always,
 166 from mid-2015 onward.  The ACPI specification will also be updated
 167 to reflect that _REV is deprecated, and always returns 2.
 168
 169 Apple Mac and _OSI("Darwin")
 170 ============================
 171
 172 On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
 173 to determine if the machine is running Apple OSX.
 174
 175 Like Linux's _OSI("*Windows*") strategy, Linux defaults to
 176 answering YES to _OSI("Darwin") to enable full access
 177 to the hardware and validated BIOS paths seen by OSX.
 178 Just like on Windows-tested platforms, this strategy has risks.
 179
 180 Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin")
 181 for the purpose of enabling Mac Thunderbolt support.  Further,
 182 if the kernel noticed _OSI("Darwin") being invoked, it additionally
 183 disabled all _OSI("*Windows*") to keep poorly written Mac BIOS
 184 from going down untested combinations of paths.
 185
 186 The Linux-3.18 change in default caused power regressions on Mac
 187 laptops, and the 3.18 implementation did not allow changing
 188 the default via cmdline "acpi_osi=!Darwin".  Linux-4.7 fixed
 189 the ability to use acpi_osi=!Darwin as a workaround, and
 190 we hope to see Mac Thunderbolt power management support in Linux-4.11.