Commit 1cf70ae6 authored by Changbin Du's avatar Changbin Du Committed by Rafael J. Wysocki
Browse files

Documentation: ACPI: move osi.txt to firmware-guide/acpi and convert to reST 



This converts the plain text documentation to reStructuredText format
and adds it to Sphinx TOC tree.

No essential content change.

Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent c24bc66e

Documentation/firmware-guide/acpi/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -9,3 +9,4 @@ ACPI Support 


   namespace

   enumeration

   osi

Documentation/acpi/osi.txt→Documentation/firmware-guide/acpi/osi.rst

+9 −6
Original line number Diff line number Diff line 
.. 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
@@ -14,7 +17,7 @@ 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,
@@ -62,7 +65,7 @@ the string when that support is added to the kernel. 
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."
@@ -96,7 +99,7 @@ That is the *only* viable strategy, as that is what modern Windows does, 
and so doing otherwise could steer the BIOS down an untested path.



_OSI is born, and immediately misused

--------------------------------------

=====================================



With _OSI, the *BIOS* provides the string describing an interface,

and asks the OS: "YES/NO, are you compatible with this interface?"
@@ -144,7 +147,7 @@ catastrophic failure resulting from the BIOS taking paths that 
were never validated under *any* OS.



Do not use _REV

---------------

===============



Since _OSI("Linux") went away, some BIOS writers used _REV

to support Linux and Windows differences in the same BIOS.
@@ -164,7 +167,7 @@ from mid-2015 onward. The ACPI specification will also be updated 
to reflect that _REV is deprecated, and always returns 2.



Apple Mac and _OSI("Darwin")

----------------------------

============================



On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")

to determine if the machine is running Apple OSX.

CRA Git | Maintained and supported by SUSTech CRA and CCSE