Hi,while arguing about current _OSI Linux implementation,I realized this is complex and absolutely undocumented.I started to write this up properly.This was the point when I realized addingsome major general ACPI things OEMs should consider onLinux is urgently missing and should get published.Many thanks to Andi Kleen and Pavel Machek who alreadyreviewed an early version some weeks ago. I still changeda lot since then (also corrected a lot considering yourcorrections, thanks it probably was a lot work going throughthis that detailed!).I like to get as much feedback for this as possible.Be sure I will go through this attentively and add ormodify whatever makes sense.I mainly try to get feedback from OEMs and BIOS developers,I am going to and I also like you to point to this. Theyare the main audience for this paper.Currently OEMs start to take care or at least look at Linuxfor the future even in the laptop area (this is why every latestACPI BIOS checks whether Linux is running...).This should give them a documentation and an overview forwhat they should take care for. Until a BIOS hits thecustomer takes a lot time, so they need stability and ageneral policy they can count on.You find the paper here:ftp://ftp.suse.com/pub/people/trenn/ACPI_BIOS_on_Linux_guide/acpi_guideline_for_vendors.pdfAt the end are the sources of the original document forbetter commenting of special parts of the document.I am looking forward for a lot feedback.Thanks,            Thomas\documentclass[10pt,a4paper]{article}\usepackage{hyperref}\usepackage[numbers]{natbib}\title{ACPI BIOS Guideline for Linux}\author{Thomas Renninger - Copyright SUSE Linux GmbH, 2008}\begin{document}\maketitle\begin{abstract}This specification is intended for PC hardware vendors and PC BIOSdevelopers. It documents and describes ACPI implementations of theLinux kernel which are important for BIOS developers. Irregularitiesto the ACPI specification are discussed. It outlines problems that mayhappen on ACPI driven BIOSes on Linux and how to avoid them.\end{abstract}\newpage\tableofcontents\newpage\section{Introduction}Recently a lot PC hardware vendors have been started to offer Linux pre-loaded ontheir hardware. Linux fully supports the ACPI specification version 2.0and partly 3.0. There are still some pits vendors can fall in, whichcan be avoided easily. This paper describes problems that could occurwith ACPI implementations on Linux.It is intended to get input and feedback from vendors and programmers.If you have any ideas to improve or expand this documentation, please sendsuggestions to \href{mailto:trenn@suse.de}{trenn@suse.de} or to thelinux-acpi mailing list [8].\section{Vendor specific ACPI implementations}Linux perfectly supports most ACPI specified devices(e.g. battery'', battery vs. plugged-in status'', lid'',cpufreq frequency scaling (P-states)'', processor sleep states(C-states)'' and a lot more).Vendors often implement devices through ACPI which are not includedin the general ACPI or other specifications. For example buttons like wireless LANon/off switches, volume up/down and mute buttons and more.Vendors provide a proprietary driver for Windows for such vendorspecific devices and in many cases there also is a re-engineered Linux driver(e.g. asus\_acpi, sony\_acpi, thinkpad\_acpi and more). Those drivers areoften not complete and hard to maintain, so it is possible for examplefor parts of the undocumented interface to change from one model toanother or, even worse, through a BIOS update. Vendors should:\begin{enumerate}\item  Use devices described in the ACPI specification whenever  possible.\item  If new devices or functions are introduced, document how to use  them.  A short specification or a request for comments (RFC) can be the  basis of a new standard which is following your needs.  Also do make use of a unique Hardare ID to describe the device and  thus make it easy for the corresponding Linux driver to match and  register for the device.\item  Support mainline developers. Open source developers are often not  bound to a company. Most of the drivers implemented by open source  developers are made for private use only, many of them do not fit  other machines or models.  Incentives like a trip to the next Linux symposium, a machine of  their favorite hardware vendor or something like that is often a  quick and cheap option to get the driver into a shape you would  like to see it.\item  Provide an input channel (a mailinglist for example) to get  feedback. This can be of big help to get informed about  problems like breakage in upcoming Linux code. ACPI BIOS  bugs likely affect your supported Microsoft operating system or an  upcoming version also. It may happen that  problems are already analyzed and debugged very detailed by open  source developers. People may  already point to a specific firmware bug which can ease up the search  for BIOS developers to identify the problem and can save precious  time until an update can be provided to the customer.\end{enumerate}\section{Avoid the use of the \_OSI function if possible}\subsection{What is \_OSI and how is it used}\_OSI is an ACPI method provided by the operating system that can beinvoked by ACPI BIOS code. It is used by BIOS developersto detect which operating system is running. The method that should beused (cmp. ACPI spec[1], chapter 5.7.2 and 5.7.3) is \_OS. But tocheck for recent operating systems \_OSI is used to identify therunning OS for various reasons.The intent of the \_OSI function is to identify features provided bythe OS. For example some BIOSes check for Vista which supports anddemands the latest ACPI backlight functions (compare ACPI spec AppendixB).But feature identification is an exception. In reality BIOSdevelopers use the \_OSI functionality to work around operating systemerrors. If thesupported OS is a closed source one like Microsoft Windows, vendorsrely on the use of \_OSI to work around possibly upcoming OS specificerrors (for example through a Service Pack) via a BIOS update.Vendors must not do this on Linux. If bugs in the Linux OS areidentified, vendors must make sure that the cause is fixed in theLinux kernel. Linux does not have a strict OS versioning. The root causemight get fixed in the latest upstream kernel and the workaround couldbreak there. Such fixes are often backported to distributions.Therefore an identification(as it is common for Windows)whether the underlying Linux operating system is affected by aspecific bug is not possible.Here is an example of how a vendor wrongly fixed his ACPI BIOSimplementation and tried to workaround a Linux bug. It then brokewith more recent kernels after the bug got identified and fixed:\href{http://bugzilla.kernel.org/show\_bug.cgi?id=7787}{http://bugzilla.kernel.org/show\_bug.cgi?id=7787}\subsection{How \_OSI is implemented on Linux}Since version 2.6.23 the mainline kernel does not return true for\_OSI(Linux'') BIOS invocations anymore.The intent is to prevent BIOSproviders and kernel developers from a maintenance nightmare.Linux specific implementations should never be needed.The second ACPI specification violation is that the Linux kernelreturns true for all known Windows OS \_OSIstrings (compare with drivers/acpi/utilities/uteval.c in the kernelsources for the recent list):\begin{itemize}\item  Windows 2000'',         /* Windows 2000 */\item  Windows 2001'',         /* Windows XP */\item  Windows 2001 SP1'',     /* Windows XP SP1 */\item  Windows 2001 SP2'',     /* Windows XP SP2 */\item  Windows 2001.1'',       /* Windows Server 2003 */\item  Windows 2001.1 SP1'',  /* Windows Server 2003 SP1 - Added 03/2006 */\item  Windows 2006'',         /* Windows Vista - Added 03/2006 */\end{itemize}Therefore it is currently not possible for BIOS developers toidentify that the machine is running on Linux.The idea is to be compatible with the latest Microsoft operatingsystem. If people report bugs which come out to be operating systemspecific bug workarounds, it is currently tried to adopt or better, becompatible with these bugs of other operating systems.There are several drawbacks with this implementation:\begin{itemize}\item  Microsoft versions will change and can be fixed in future releases  (this only applies for \_OSI specific workarounds)  while the Linux implementation has to be compatible with all bugs  that ever appeared in any Microsoft ACPI implementation.\item  Microsoft does return true for only one specific version string.  This can lead to undefined code paths being executed on Linux where  for all known Windows strings true is returned. For example  the BIOS checks at initialization time for Windows XP and sets a  specific variable, then it checks for Windows Vista and sets another  variable.  Now later ACPI code paths executed on Linux will be unwanted as  Windows is probably only returning true for either Vista or XP.  Vendors should check with else if clauses or use the same variable  to store the results of \_OSI execution at initialisation time.  Make sure the latest Windows versions are tested in the end and the  latest Windows version (e.g. Windows 2006'', cmp. with above  strings) returning true is used.\item  It is nearly impossible for vendors to follow all kernel versions  in mainline and in distributions and to check what Windows strings  are returned in which kernel version.\item  Vendors who care about Linux cannot guarantee proper support of  Linux and Windows with the same BIOS without modifying the kernel  slightly(see below for details). Especially if they are forced to  implement Microsoft erratas through BIOS hot-fixes. Whether this is the  case cannot be proven, but comparing a lot recent ACPI BIOS  implementations harden the assumption that this is rather common.\end{itemize}\subsection{BIOS providers have to take care about \_OSI on Linux}It is expected that vendors must add \_OSI hooks to workaround bugs inother operating systems. If this is not the case, the use of \_OSIshould simply be avoided and everything works out fine.On Linux, vendors must (instead of adding workarounds into the ACPI BIOS)fix the Linux kernel or at least discuss and help to identify and fixthe problem for the latest mainline kernel. Then the needed necessary codepatches which fix the problem for the latest Linux kernel must bebackported to the kernels of the supported distributions. Like thatvendors can expect support from kernel developers and a quick solutionfor the problem and they can make sure they do not run intounmanageable maintenance problems (which are very likely to happen ifLinux kernel bugs get fixed in the BIOS).Unfortunately vendors seem to depend on the \_OSI functionality and itlooks like as they have to provide OS specific BIOS hot-fixes toguarantee support for Microsoft operating systems.Because the Linux \_OSI implementation is currentlytransparent to the Windows one, BIOS developers cannot distinguishwhether their code is running on Linux or on a Microsoft OS.Hopefully this will change soon, but it needs a testing phase and willtake some time until such a change find its way into distributions.Goal for Linux is to not return true for Windows OS strings.The Linux'' OSIkeyword as stated in the ACPI specification ([1], cmp. with chapter 5.7.2)already is and will stay obsolete in the future. It got removed inkernel version 2.6.23. Vendors should not rely on Linux returning truefor this string.For now, while Linux still is transparent to Microsoft Windows,vendors have to patch the kernel of the distribution they claim tosupport. (For example SLE 11'' string is used for SUSE LinuxEnterprise Server and Desktop version 11).The above described osi=''Supported Linux Distribution'' string mustonly be used to not execute operating system bug workarounds on aLinux system. If for example a BIOS hotfix is required for Vista SP2, theLinux kernel currently might also execute this code (depending onwhether the OS string has already been added to the kernel). In thiscase add the condition not to execute this BIOS hotfix on yoursupported Linux distributions to prevent them from breaking through the BIOSupdate.It is very important that vendors do not mis-use the ability todistinguish between Linux and Microsoft Windows and workaround Linuxkernel bugs. Once a problem is identified to be a kernel bug, reportthe problem on the linux-acpi mailing list (see links at theend). ACPI kernel developers will provide and commit a fix for thenext mainline kernel. This fix must then eventually be backported tothe kernel of the supported distributions (if not already done).Vendors must still make sure that their BIOS runs fine, even if\_OSI(Windows XY'') calls do not return true.The problems outlined above show that for long-term, the only maintainablesolution for Linux is to not return true for Windows OS strings. Whilesuch an interface change needs testing and some time to stabilize, BIOSdevelopers should keep in mind that this change could happen inthe future.\section{WMI - Windows Management Instrumentation}WMI is a Microsoft specific service. A small part of itdescribes possible ACPI WMI implementations provided by the BIOS.This is not part of the official ACPI specification and BIOS developersshould avoid using it. The Linux kernel driver supports basic WMI ACPIfunctionality (since 2.6.25), but it is marked experimental.ACPI functionality should not depend on the WMI interface.\section {Post Video BIOS after Suspend to Ram}Graphics drivers on Linux are located in userspace.Therefore they cannot initialize the graphics device in the earlyresume phase.There are efforts to move necessary parts of the graphics devicedrivers into the kernel, but this is complex and needs maturity to runstable on all recent graphics devices.Therefore the BIOS vendors still have to provide the legacy way ofgraphics cards resuming and have to make sure the BIOS does post''the video BIOS when resuming or at least make sure the operatingsystem can do so (by issuing lcall \$0xc000, 3''). Also regular softwareinterrupt calls (int \$0x10'') must work during resume from suspendto ram.\section{Check ACPI operation region declarations}Sanity check ACPI operation region declarations and PNP resources.ACPI operation region declarations define the IO port, memory andother resources to control devices in BIOS through the ACPI language.PNP resource declarations are bind to an ACPI device and reserveresources to exclusively be used by an operating system driver whichserves and registers for this ACPI device.Sometimes there exist several regiondeclarations for the same device or they partly overlap. This mustnot happen. Resources must be declared or used exclusively by eitherACPI BIOS parts or system drivers. Neither Operation Regiondeclarations nor PNP resources nor both may overlap.It is expected that some hardware vendors do get ACPI BIOS parts fromseveral external sources. ACPI BIOS templates for specific devcies maybe added to the BIOS. This makes it difficult for vendors to keep anoverview whether a device is addressed through ACPI parts themselvesor whether its resources are already be exported to an external drivervia PNP resources. If both is done, the device may be accessed through twoinstances without any access coordination, which can lead to sever andvery hard to identify system instability problems.The linuxfirmwarekit discussed below should be ableto identify most of such issues soon and could be of great help forvendors to smoothly glue several ACPI parts together into oneintegrated, sanity checked, ACPI aware BIOS.\section{Miscellaneous}\subsection{Smart Battery}The Smart Battery specification should be avoided.There were some hardware vendors, e.g. Acer, using the more complexbattery specification called Smart Battery'' (compare with ACPIspecification 10.1).Linux provides a driver for it, but because there were not much BIOSimplementations using it, the driver is not well tested.Instead of the Smart Battery Interface, make use of the ControlMethod Batteries'' interface (compare with ACPI specification 10.2).\subsection{Thermal Zones}Make use of ACPI thermal zones.Thermal control is important, and linux can do quite a goodjob in this area. Provide thermal zones when you can (that will meanlinux can monitor temperatures inside case) and provide reasonablepassive trip points and polling intervals as specified by the ACPIspecification. With properly set up passive trip points, the machinecan continue working even with failed fan. This is very important forservers.\subsection{Always return valid values if possible}Make sure sane figures are returned for all specified values of animplemented ACPI device. For example the battery voltage issometimes wrong or the entity for the current (mAh vs mW) are mixedup. While other applications may not need these values, Linuxapplications could make use of them and show wrong values or evenshutdown or suspend the system wrongly when the remaining batterycapacity is not calculated correctly.ACPI lacks the possibility to return error values.This is a general problem for BIOS developers. If an error code pathhas to be covered and it does not make sense to return a valid valueto the OS for the invoked function, then there is no possibility totell the OS about the error. Hopefully this will change in the future, fornow it is best to ask on the ACPI kernel developers list[6] what valuewould be best to return for the specific problem.\section{Get used to Intel's BIOS tools}\subsection{ACPICA - ACPI Component Architecture}\label{acpica}While Microsoft uses its own proprietary, closed source ACPI compiler,Linux does make use of Intel's \href{http://acpica.org} {ACPI Component  Architecture}. The code base is used as ACPI parser and interpreterinside the kernel, but it also provides a lot of easy-to-use tools forgeneral ACPI development and stability testing.Most important for vendors is the iasl binary which can disassembleand recompile raw ACPI tables provided by the BIOS. It uses the samecode base as the ACPI parser in the kernel. Therefore vendors shouldcheck whether their ACPI implementation sticks to the ACPIspecification and works with the ACPICA tools (for an easy quick test,see \ref{linuxfirmwarekit} below).The Intel compiler is more strict.Warnings often lead to general ACPI BIOS errors that may also affectMicrosoft Windows or other operating systems. Some may just point toACPI specification violations which the Microsoft compiler allows. TheIntel parser may also be able to cope with this code, but fixing suchviolations is easy in most cases and makes the ACPI BIOSimplementation more robust against future operating system changes.If in doubt whether a compiler warning is serious and how to fix it,you may get help if you subscribe and ask on the\href{http://www.acpica.org/mailman/listinfo/devel} {ACPICA developer  mailing list}.\subsection{Linuxfirmwarekit}\label{linuxfirmwarekit}Intel provides a tool to check the BIOS for Linux compatibility.The tool is distribution independent.A \href{http://www.linuxfirmwarekit.org/download.php#bootcd} {bootable  CD image} can be downloaded from linuxfirmware.org.Once the CD image is booted, the BIOS tests are startedautomatically. One test is to disassemble the ACPI tables provided bythe BIOS and recompile them again with Intel's iasl ACPI compiler.It may happen that there are misleading warnings. If in doubt, ask onthe acpica or linuxfirmwarekit mailing list (see chapter \ref{links}).OpenSuSE and SLES provide the same test application on theirinstallation media. But the kernel used for booting and starting theapplication is the same which is used by the SuSE distribution.The BIOS test can bechosen in the boot loader when booting the installation media orinvoked at runtime when the firmwarekit package is installed.\section{Summary}This section summerizes above discussed topics and shortly describeskeynotes, vendors should take care for to be able to ensure properACPI Linux support.\begin{itemize}\item  Avoid the use of ACPI WMI implementations.\item  Avoid \_OSI workarounds whenever possible.\item  If the supported Linux kernel is transparent to Windows, patch it  so that it returns true for the specific OS the vendor claims to  support. Only use this hook to not break the supported Linux  distribution by Microsoft Windows specific bug workarounds.\item  Report any Linux bugs to the linux-acpi mailing list. Fix the bug in  the source code of the supported Linux distribution (ask for help,  this is open source software), do not fix such bugs in the BIOS or  you end up in not being able to support future fixed Linux kernels  with this BIOS.\item  Avoid the Smart Battery ACPI interface, use the more common Control  Method Batteries interface.\item  Strictly implement the ACPI specification.\item  Use Intel's ACPICA compiler tools to detect ACPI Source Language  syntax errors.\item  Use Intel's linuxfirmwarekit to detect general and already known  BIOS errors.\end{itemize}\section{Useful Links and Mailing Lists}\label{links}\subsection{Links}\begin{itemize}\item  [1] ACPI Specification (Used for this paper: version 3.0b, 2006)      \href{http://www.acpi.info} {http://www.acpi.info}\item  [2] ACPI Component Architecture      \href{http://acpica.org} {http://acpica.org}\item  [3] Linuxfirmwarekit      \href{http://linuxfirmwarekit.org} {http://linuxfirmwarekit.org}\item  [4] Linux bug workaround in BIOS via \_OSI - A fix in the kernel  broke it  \href{http://bugzilla.kernel.org/show\_bug.cgi?id=7787}{http://bugzilla.kernel.org/show\_bug.cgi?id=7787}\item  [5] Kernel bug tracking system - Report problems there if you think you      hit a kernel bug  \href{http://bugzilla.kernel.org} {http://bugzilla.kernel.org}\end{itemize}\subsection{Mailing Lists}\begin{itemize}\item  [6] ACPICA developer list  \href{http://www.acpica.org/mailman/listinfo/devel} {http://www.acpica.org/mailman/listinfo/devel}\item  [7] Firmwarekit Developer and Discussion List  \href{http://www.bughost.org/mailman/listinfo/firmwarekit-discuss}       {http://www.bughost.org/mailman/listinfo/firmwarekit-discuss}\item   [8] ACPI kernel developer list   \href{mailto:http://vger.kernel.org/majordomo-info.html?Body=Subscribe     linux-acpi}        {mailto:http://vger.kernel.org/majordomo-info.html?Body=Subscribe linux-acpi}\end{itemize}\LargeDisclaimer:\normalsizeTrademarks and trade names may be used in this document to refer toeither the entities claiming the marks and names or theirproducts. The author of this document disclaims any proprietaryinterest in trademarks and trade names other than its own.\end{document}