Documentation/firmware-guide/acpi/osi.rst

Source file repositories/reference/linux-study-clean/Documentation/firmware-guide/acpi/osi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/firmware-guide/acpi/osi.rst
Extension
.rst
Size
8329 bytes
Lines
188
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

==========================
ACPI _OSI and _REV methods
==========================

An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
to find out what the operating system supports. Eg. If BIOS
AML code includes _OSI("XYZ"), the kernel's AML interpreter
can evaluate that method, look to see if it supports 'XYZ'
and answer YES or NO to the BIOS.

The ACPI _REV method returns the "Revision of the ACPI specification
that OSPM supports"

This document explains how and why the BIOS and Linux should use these methods.
It also explains how and why they are widely misused.

How to use _OSI
===============

Linux runs on two groups of machines -- those that are tested by the OEM
to be compatible with Linux, and those that were never tested with Linux,
but where Linux was installed to replace the original OS (Windows or OSX).

The larger group is the systems tested to run only Windows.  Not only that,
but many were tested to run with just one specific version of Windows.
So even though the BIOS may use _OSI to query what version of Windows is running,
only a single path through the BIOS has actually been tested.
Experience shows that taking untested paths through the BIOS
exposes Linux to an entire category of BIOS bugs.
For this reason, Linux _OSI defaults must continue to claim compatibility
with all versions of Windows.

But Linux isn't actually compatible with Windows, and the Linux community
has also been hurt with regressions when Linux adds the latest version of
Windows to its list of _OSI strings.  So it is possible that additional strings
will be more thoroughly vetted before shipping upstream in the future.
But it is likely that they will all eventually be added.

What should an OEM do if they want to support Linux and Windows
using the same BIOS image?  Often they need to do something different
for Linux to deal with how Linux is different from Windows.

In this case, the OEM should create custom ASL to be executed by the
Linux kernel and changes to Linux kernel drivers to execute this custom
ASL.  The easiest way to accomplish this is to introduce a device specific
method (_DSM) that is called from the Linux kernel.

In the past the kernel used to support something like:
_OSI("Linux-OEM-my_interface_name")
where 'OEM' is needed if this is an OEM-specific hook,
and 'my_interface_name' describes the hook, which could be a
quirk, a bug, or a bug-fix.

However this was discovered to be abused by other BIOS vendors to change
completely unrelated code on completely unrelated systems.  This prompted
an evaluation of all of its uses. This uncovered that they aren't needed
for any of the original reasons. As such, the kernel will not respond to
any custom Linux-* strings by default.

That was easy.  Read on, to find out how to do it wrong.

Before _OSI, there was _OS
==========================

ACPI 1.0 specified "_OS" as an
"object that evaluates to a string that identifies the operating system."

The ACPI BIOS flow would include an evaluation of _OS, and the AML

Annotation

Implementation Notes