ࡱ> SVNOPQR zbjbjdUdU ?g?gyM!!..1114B1B1B1h1~4B1[7: L@@@@YHk\p$1XvLU.Y^XvXv..@@~Xv .@1@XvdT`0 @/. H+0[1NxrzshsT6t"rrrʗrrr[XvXvXvXvrrrrrrrrr!X h-: iASL: ACPI Source Language Optimizing Compiler and Disassembler User Guide iASL Overview and Compiler Operation Revision 6.3 September 14, 2021 Information in this document is provided in connection with Intel products. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted by this document with the sole exceptions that a) you may republish an unmodified copy and b) code included in this document is licensed subject to Zero-Clause BSD open source license (OBSD). You may create software implementations based on this document and in compliance with the foregoing. No rights are granted to create modifications or derivatives of this document. Except as provided in Intels Terms and Conditions of Sale for such products, Intel assumes no liability whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright, or other intellectual property right. Intel products are not intended for use in medical, life saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The iASL compiler may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Copyright 2000 - 2021 Intel Corporation *Other brands and names are the property of their respective owners. Contents  TOC \o 1 Introduction  PAGEREF _Toc483983768 \h 6 1.1 Document Structure  PAGEREF _Toc483983769 \h 7 1.2 Reference Documents  PAGEREF _Toc483983770 \h 7 1.3 Document History  PAGEREF _Toc483983771 \h 8 1.4 Definition of Terms  PAGEREF _Toc483983772 \h 9 2 Compiler/Disassembler Overview  PAGEREF _Toc483983773 \h 10 2.1 Supported Execution Environments  PAGEREF _Toc483983774 \h 10 2.2 ASL Compiler  PAGEREF _Toc483983775 \h 10 2.2.1 Input Files  PAGEREF _Toc483983776 \h 10 2.2.2 Output File Options  PAGEREF _Toc483983777 \h 10 2.3 AML Disassembler  PAGEREF _Toc483983778 \h 11 2.3.1 Input Files  PAGEREF _Toc483983779 \h 11 2.3.2 Output  PAGEREF _Toc483983780 \h 11 2.4 Data Table Compiler  PAGEREF _Toc483983781 \h 11 2.4.1 Input Files  PAGEREF _Toc483983782 \h 12 2.4.2 Output  PAGEREF _Toc483983783 \h 12 2.5 Data Table Disassembler  PAGEREF _Toc483983784 \h 12 2.5.1 Input Files  PAGEREF _Toc483983785 \h 12 2.5.2 Output  PAGEREF _Toc483983786 \h 12 2.6 Template Generator  PAGEREF _Toc483983787 \h 12 3 Preprocessor  PAGEREF _Toc483983788 \h 13 3.1 Command Line Options  PAGEREF _Toc483983789 \h 13 3.2 Integer Expressions  PAGEREF _Toc483983790 \h 13 3.3 Supported Directives  PAGEREF _Toc483983791 \h 13 3.3.1 Text Substitution and Macros  PAGEREF _Toc483983792 \h 14 3.3.1.1 #define  PAGEREF _Toc483983793 \h 14 3.3.1.2 #undef  PAGEREF _Toc483983794 \h 14 3.3.2 Conditional Compilation  PAGEREF _Toc483983795 \h 14 3.3.2.1 #if -  PAGEREF _Toc483983796 \h 14 3.3.2.2 #ifdef  PAGEREF _Toc483983797 \h 14 3.3.2.3 #ifndef  PAGEREF _Toc483983798 \h 15 3.3.2.4 #else  PAGEREF _Toc483983799 \h 15 3.3.2.5 #elif  PAGEREF _Toc483983800 \h 15 3.3.2.6 #endif  PAGEREF _Toc483983801 \h 15 3.3.3 Include Files  PAGEREF _Toc483983802 \h 15 3.3.3.1 #include vs. ASL Include()  PAGEREF _Toc483983803 \h 15 3.3.3.2 #include  PAGEREF _Toc483983804 \h 15 3.3.3.3 #includebuffer  PAGEREF _Toc483983805 \h 16 3.3.3.4 #line  PAGEREF _Toc483983806 \h 16 3.3.4 Miscellaneous Directives  PAGEREF _Toc483983807 \h 16 3.3.4.1 #error  PAGEREF _Toc483983808 \h 16 3.3.4.2 #pragma  PAGEREF _Toc483983809 \h 16 3.3.4.3 #warning  PAGEREF _Toc483983810 \h 17 4 ASL-AML Subsystem  PAGEREF _Toc483983811 \h 18 4.1 ASL Compiler  PAGEREF _Toc483983812 \h 18 4.1.1 Support for Symbolic Operators and Expressions (ASL+)  PAGEREF _Toc483983813 \h 18 4.1.1.1 Binary AML Considerations  PAGEREF _Toc483983814 \h 20 4.1.1.2 AML Disassembler Notes  PAGEREF _Toc483983815 \h 20 4.1.2 Built-in ASL Macros  PAGEREF _Toc483983816 \h 21 4.1.3 Compiler Analysis Phases  PAGEREF _Toc483983817 \h 21 4.1.3.1 General ASL Syntax Analysis  PAGEREF _Toc483983818 \h 21 4.1.3.2 General Semantic Analysis  PAGEREF _Toc483983819 \h 21 4.1.3.3 Control Method Semantic Analysis  PAGEREF _Toc483983820 \h 22 4.1.3.4 Control Method Invocation Analysis  PAGEREF _Toc483983821 \h 22 4.1.3.5 Predefined ACPI Names  PAGEREF _Toc483983822 \h 22 4.1.3.6 Resource Descriptors  PAGEREF _Toc483983823 \h 22 4.1.4 Compiler Optimizations  PAGEREF _Toc483983824 \h 23 4.1.4.1 Named References  PAGEREF _Toc483983825 \h 23 4.1.4.2 Integers  PAGEREF _Toc483983826 \h 23 4.1.4.3 Constant Folding  PAGEREF _Toc483983827 \h 23 4.2 ASL-to-AML Disassembler  PAGEREF _Toc483983828 \h 23 4.2.1 Multiple Table Disassembly  PAGEREF _Toc483983829 \h 23 4.2.2 External Declarations  PAGEREF _Toc483983830 \h 24 4.2.2.1 The External AML Opcode  PAGEREF _Toc483983831 \h 24 4.2.2.2 Generation of ASL External() Statements  PAGEREF _Toc483983832 \h 25 4.3 ASL to ASL+ Converter  PAGEREF _Toc483983833 \h 25 4.3.1 Using the ASL/ASL+ Converter  PAGEREF _Toc483983834 \h 25 4.3.2 Example: ASL/ASL+ Converter and Disassembler  PAGEREF _Toc483983835 \h 25 4.3.3 Items currently not supported  PAGEREF _Toc483983836 \h 26 5 ACPI Data Table Subsystem  PAGEREF _Toc483983837 \h 27 5.1 Data Table Compiler  PAGEREF _Toc483983838 \h 27 5.1.1 Input Format  PAGEREF _Toc483983839 \h 27 5.1.1.1 Ignored Fields/Comments  PAGEREF _Toc483983840 \h 28 5.1.2 Data Table Definition Language  PAGEREF _Toc483983841 \h 28 5.1.3 Input Example  PAGEREF _Toc483983842 \h 30 5.1.4 Data Types for User-Entered Fields  PAGEREF _Toc483983843 \h 30 5.1.4.1 Integers  PAGEREF _Toc483983844 \h 30 5.1.4.2 Integer Expressions  PAGEREF _Toc483983845 \h 30 5.1.4.3 Flags  PAGEREF _Toc483983846 \h 31 5.1.4.4 Strings  PAGEREF _Toc483983847 \h 31 5.1.4.5 Buffers  PAGEREF _Toc483983848 \h 32 5.1.5 Fields Set Automatically  PAGEREF _Toc483983849 \h 32 5.1.6 Special Fields  PAGEREF _Toc483983850 \h 32 5.1.7 Generic Fields / Generic Data Types  PAGEREF _Toc483983851 \h 33 5.2 Data Table Disassembler  PAGEREF _Toc483983852 \h 35 5.2.1 Example Output  PAGEREF _Toc483983853 \h 35 5.3 ACPI Table Template Generator  PAGEREF _Toc483983854 \h 38 6 Compiler/Disassembler Operation  PAGEREF _Toc483983855 \h 39 6.1 Command Line Invocation  PAGEREF _Toc483983856 \h 39 6.2 Wildcard Support  PAGEREF _Toc483983857 \h 39 6.3 Command Line Options  PAGEREF _Toc483983858 \h 40 6.3.1 General Options  PAGEREF _Toc483983859 \h 41 6.3.2 Help  PAGEREF _Toc483983860 \h 42 6.3.3 Preprocessor  PAGEREF _Toc483983861 \h 42 6.3.4 Errors, Warnings, and Remarks  PAGEREF _Toc483983862 \h 42 6.3.5 AML Bytecode Generation  PAGEREF _Toc483983863 \h 43 6.3.6 Listings  PAGEREF _Toc483983864 \h 43 6.3.7 Firmware Support C Text Output  PAGEREF _Toc483983865 \h 43 6.3.8 Firmware Support Assembler Text Output  PAGEREF _Toc483983866 \h 44 6.3.9 Firmware Support ASL Text Output  PAGEREF _Toc483983867 \h 44 6.3.10 Legacy-ASL to ASL+ Converter  PAGEREF _Toc483983868 \h 44 6.3.11 Data Table Compiler  PAGEREF _Toc483983869 \h 44 6.3.12 AML Disassembler  PAGEREF _Toc483983870 \h 45 6.3.13 Compiler Debug Options  PAGEREF _Toc483983871 \h 45 6.4 Compiler Output Examples  PAGEREF _Toc483983872 \h 46 6.4.1 Input ASL  PAGEREF _Toc483983873 \h 46 6.4.2 Output of tc (make C hex table) Option  PAGEREF _Toc483983874 \h 47 6.4.3 Output of sc (make C source) Option  PAGEREF _Toc483983875 \h 48 6.4.4 Output of ic (make include file) Option  PAGEREF _Toc483983876 \h 49 6.4.5 Output of l (Listing) Option  PAGEREF _Toc483983877 \h 49 6.4.6 Output of lm (Hardware Mapfile) Option  PAGEREF _Toc483983878 \h 50 6.4.7 Output of ln (Namespace Listing) Option  PAGEREF _Toc483983879 \h 51 6.5 Using the Disassembler  PAGEREF _Toc483983880 \h 51 6.5.1 Resolving External Control Methods  PAGEREF _Toc483983881 \h 51 6.5.1.1 Standard Disassembly  PAGEREF _Toc483983882 \h 52 6.5.1.2 Disassembly with e option  PAGEREF _Toc483983883 \h 53 6.5.1.3 Disassembly with both e and fe options  PAGEREF _Toc483983884 \h 53 6.6 Integration Into MS VC++ Environment  PAGEREF _Toc483983885 \h 54 6.6.1 Integration as a Custom Tool  PAGEREF _Toc483983886 \h 54 6.6.2 Integration into a Project Build  PAGEREF _Toc483983887 \h 55 7 Generating iASL from Source Code  PAGEREF _Toc483983888 \h 56 7.1 Required Tools  PAGEREF _Toc483983889 \h 56 7.2 Required Source Code  PAGEREF _Toc483983890 \h 56  Introduction The iASL compiler/disassembler is a fully-featured translator for the ACPI Source Language (ASL) and ACPI binary data tables. As part of the Intel ACPI Component Architecture, the Intel ASL compiler implements translation for the ACPI Source Language (ASL) to the ACPI Machine Language (AML). The disassembler feature will disassemble compiled AML code back to (near-original) ASL source code. The major features of the iASL compiler include: Full support for the ACPI 5.1 Specification including ASL grammar elements and operators. Extensive compiler syntax and semantic error checking, especially in the area of control methods. This reduces the number of errors that are not discovered until the AML code is actually interpreted (i.e., the compile-time error checking reduces the number of run-time errors.) An integrated preprocessor provides C-compatible preprocessor directives and conditional compilation directives such as #define, #if, #ifdef, #else, etc. Multiple types of output files. Besides binary ACPI tables, output options include formatted listing files with intermixed source, several types of AML files, and error messages. Automatic detection and compilation of either ASL source code or ACPI data table source code. Portable code (ANSI C) and source code availability allows the compiler to be easily ported and run on multiple execution platforms. Support for integration with the Microsoft Visual C++ (or similar) development environments. Disassembly of all ACPI tables, including tables that contain AML (DSDT, SSDT) as well as ACPI data tables such as the FADT, MADT, SRAT, etc. Support for compilation of non-AML data tables such as the FADT, MADT, SRAT, etc. Support for ASL language extensions that support symbolic math/logical operators and expressions. Document Structure This document consists of these major sections: Introduction: Contains a brief overview of the iASL compiler/disassembler, document structure, related reference documents, and definition of terms used throughout the document Compile/Disassembler Overview: Compiler subsystems, inputs, outputs, and supported system environments. ASL-AML Subsystem: Describes the ASL compiler and the AML disassembler. ACPI Data Table Subsystem: Describes the Data Table compiler and the Data Table disassembler. Compiler/Disassembler Operation: Guide for compiler options and general operation, including output examples. Generating iASL from Source Code: Instructions for building the iASL compiler from the open-source package. Reference Documents ACPI documents are available at:  HYPERLINK "http://uefi.org/specifications/" http://uefi.org/specifications/ Advanced Configuration and Power Interface Specification, Revision 1.0, December 1, 1996 Advanced Configuration and Power Interface Specification, Revision 1.0a, July 1, 1998 Advanced Configuration and Power Interface Specification, Revision 1.0b, February 8, 1999 Advanced Configuration and Power Interface Specification, Revision 2.0, July 27, 2000 Advanced Configuration and Power Interface Specification, Revision 2.0a, March 32, 2002 Advanced Configuration and Power Interface Specification, Revision 2.0b, October 11, 2002 Advanced Configuration and Power Interface Specification, Revision 2.0c, August 23, 2003 Advanced Configuration and Power Interface Specification, Revision 3.0, September 2, 2004 Advanced Configuration and Power Interface Specification, Revision 3.0a, December 30, 2005 Advanced Configuration and Power Interface Specification, Revision 3.0b, October 10, 2006 Advanced Configuration and Power Interface Specification, Revision 4.0, June 16, 2009 Advanced Configuration and Power Interface Specification, Revision 4.0a, April 5, 2010 Advanced Configuration and Power Interface Specification, Revision 5.0, December, 6, 2011 Advanced Configuration and Power Interface Specification, Revision 5.0a, November, 13, 2013 Advanced Configuration and Power Interface Specification, Revision 5.1, July 2014 Advanced Configuration and Power Interface Specification, Revision 6.0, April 2015 Advanced Configuration and Power Interface Specification, Revision 6.1, January 2016 ACPICA documents are available at:  HYPERLINK "https://www.acpica.org/documentation/" https://www.acpica.org/documentation/ ACPI Component Architecture User Guide and Programmer Reference iASL: ACPI Source Language Optimizing Compiler and Disassembler User Guide ACPICA and iASL source code is available at:  HYPERLINK "https://www.acpica.org/downloads/" https://www.acpica.org/downloads/ iASL Windows binaries are available at:  HYPERLINK "https://www.acpica.org/downloads/binary-tools" https://www.acpica.org/downloads/binary-tools Document History May 2012: Add preprocessor support. June 2012: Update command line options and descriptions. January 2013: Add in flag to ignore ASL/AML NoOp operators/opcodes. August 2013: Add fe option for the disassembler. December 2013: Add ve option to display compilation errors only, no warnings or remarks. September 2014: Add lm option to generate a hardware mapfile. November 2014: Add support for C-style math/logical operators and expressions. Added new debug option to prune ASL namespace hierarchy tree. May 2015: Add the #includebuffer preprocessor directive. May 2016: Add support for ASL-to-ASL+ converter. Definition of Terms ACPI: Advanced Configuration and Power Interface. An open standard for device configuration and power management. ACPICA: ACPI Component Architecture. An open-source implementation of ACPI that is hosted on many different operating systems. ACPI Data Table: Any ACPI table that does not contain AML byte code but is instead simply a structure of static packed binary data. In practice, any ACPI table other than DSDTs or SSDTs. ACPI Table: Generic reference to any of the ACPI-related tables (both AML and Data Tables) that are presented by the BIOS for consumption by the host operating system. AML: ACPI Machine Language. A byte code language to be executed by an ACPI/AML interpreter within the host operating system. Created by translation of ASL code via an ASL compiler. Defined by the ACPI specification. ASL: ACPI Source Language. A higher level language that corresponds to the low level AML byte code language. ASL source code is translated into AML byte code by an ASL compiler. Defined by the ACPI specification Binary ACPI Table: An ACPI table that contains either raw AML byte code, or a packed ACPI Data Table Data Table Language: A simple language developed to describe the individual fields within an ACPI Data Table. It is used by both the compiler and disassembler portions of the iASL Data Table Subsystem. Disassembler: In the ACPI context, a tool that will either convert AML byte code back to the original ASL code, or will convert an ACPI Data Table into a format that is human-readable. Hex Table: A table containing data that is in a format suitable for translation via an Assembler, C compiler, or ASL compiler. Compiler/Disassembler Overview The iASL compiler/disassembler consists of several distinct subsystems, as described below: An integrated C-like preprocessor An ASL-to-AML compiler that translates ASL code (ACPI Source Language) to AML byte code (ACPI Machine Language). An ACPI Data Table compiler that translates Data Table definitions to binary ACPI tables. An ACPI Data Table is any ACPI table that contains only data, not AML byte code. Examples include the FADT, MADT, SRAT, etc. An AML-to-ASL disassembler that translates compiled AML byte code back to the (nearly) original ASL source code. This disassembler is used on tables like the DSDT and SSDT. An ACPI Data Table disassembler that formats binary ACPI data tables into a readable format. The output of this disassembler can be compiled with the ACPI data table compiler. An ACPI table template generator that will emit examples of all known ACPI tables, in a format similar to the output of the data table disassembler. The output files from the template generator are intended to be used as the basis or starting point for the development of actual ACPI tables. Supported Execution Environments iASL runs on multiple platforms as a 32-bit or 64-bit application. Portable code requires only ANSI C and a compiler generation package such as Bison/Flex or Yacc/Lex. Error and warning messages are compatible with Microsoft Visual C++, allowing for integration of the compiler into the development environment to simplify project building and debug. The iASL source code is distributed with the compiler binaries under the ACPICA source license. ASL Compiler Input Files Existing ACPI ASL source files are fully supported. Enhanced compiler error checking will often uncover unknown problems in these files. All ACPI 5.0 ASL additions and new ACPI tables are supported. The compiler fully supports ACPI 5.0. Output File Options Preprocessed source code file AML binary output file AML code in C source code form for inclusion into a BIOS project AML code in x86 assembly code form for inclusion into a BIOS project AML Hex Table output file in either C, ASL, or x86 assembly code as a table initialization statement. Listing file with source file line number, source statements, and intermixed generated AML code. Include files named in the original source ASL file are expanded within the listing file Namespace output file shows the ACPI namespace that corresponds to the input ASL file (and all include files.) Debug parse trace output file gives a trace of the parser and namespace during the compile. Used to debug problems in the compiler, or to help add new compiler features. AML Disassembler The AML Disassembler has the capability of reverse translating any binary AML table back to nearly the original ASL code. These are typically DSDTs and SSDTs. It can also disassemble and format all other known non-AML data tables. Input Files The AML Disassembler accepts binary ACPI tables that contain valid AML code. These tables are the DSDT and any SSDTs. These files may be obtained via the acpidump/acpixtract utilities, or some other host-specific tools. Output The output is disassembled (or de-compiled) ASL code. The file extension used for these output files is .DSL, meaning disassembled ASL. As opposed to original ASL source code files which typically have the extension .ASL. Data Table Compiler The Data Table compiler is used to compile the non-ASL/AML ACPI tables such as the FADT, MADT, SRAT, etc. These tables are not compiled to AML byte code, but are compiled to simple binary data, usually with the standard ACPI table header (signature, length, checksum, etc.) The intent of the Data Table Compiler is to simplify the generation of the many non-ASL ACPI data tables and to make the generation process less error-prone. The Data Table Compiler knows the required format for each recognized ACPI table, as well as the exact size and allowable values for each field within the tables. Input Files The Data Table compiler accepts as input files that are in the same or simplified format as the files emitted by the data table disassembler. An existing ACPI binary data table may be disassembled, modified, and then recompiled. Also, the ACPI table template generator may be used to generate template ACPI data tables that can in turn be used for the basis for additional table development. This would be the preferred starting point for ACPI table development, since the ACPI table templates contain a valid example of each table header, table section, and table sub-table as applicable. Output Binary output file Hex Table output file in either C, ASL, or x86 assembly code as a table initialization statement for inclusion into a BIOS project. Data Table Disassembler This second part of the disassembler package will extract all data from a binary ACPI data table and format it into human readable form. The format of this output is compatible with the Data Table Compiler, meaning that such ACPI tables may be easily disassembled, modified, and recompiled. Input Files The Data Table Disassembler accepts binary ACPI tables that do not contain AML code. These tables include the FADT, MADT, SRAT, etc. Output The output is a disassembled and formatted ACPI table in human-readable format. The file extension used for these files is also .DSL, for consistency with the AML disassembler. Template Generator The iASL Template Generator can be used to create ACPI tables from templates that are stored within the iASL image. These templates can be used as a starting point for the development of any ACPI table known to the compiler. Preprocessor iASL contains an integrated preprocessor that is compatible with most C preprocessors, and implements a large subset of the standard C preprocessor directives Command Line Options These iASL command line options directly affect the operation of the preprocessor: -D Define symbol for preprocessor use -li Create preprocessed output file (*.i) -P Preprocess only and create preprocessor output file (*.i) -Pn Disable preprocessor Integer Expressions Expressions are supported in all fields that require an integer value. Supported operators (Standard C meanings, in precedence order): ! Logical NOT ~ Bitwise ones compliment (NOT) * Multiply / Divide % Modulo + Add - Subtract << Shift left >> Shift right < Less than > Greater than <= Less than or equal >= Greater than or equal == Equal != Not Equal & Bitwise AND ^ bitwise Exclusive OR | Bitwise OR && Logical AND || Logical OR Supported Directives The following directives are supported: #define #elif #else #endif #error #if #ifdef #ifndef #include #includeBuffer #line #pragma #undef #warning Text Substitution and Macros #define Note: At this time, only text substitution #defines are supported. Full macros (with arguments) are not supported. Usage: #define name text_to_substitute Every instance of name is replaced by text_to_substitue. #undef Usage: #undef symbol Removes a previously defined symbol, either from a #define or from the D command line option. Conditional Compilation #if - Usage: #if expression Conditionally compile a block of text. The block is included in the compilation if the expression evaluates to a non-zero value. The standard C operators (+,-,/,*,==, etc.) may be used within the expression. #ifdef Usage: #ifdef symbol Conditionally compile a block of text. The block is included in the compilation if the symbol is defined, either from a #define or from the D command line option. #ifndef Usage: #ifndef symbol Conditionally compile a block of text. The block is included in the compilation if the symbol is not defined (opposite from #ifdef.) #else Usage: #else Conditionally compile a block of text. The block is included in the compilation if the result of a previous #if, #ifdef, #ifndef, or #elif was false. #elif Usage: #elif expression Combines #else and #if to conditionally compile a block of text. #endif Usage: #endif Indicates the completion of a #if#else block. Include Files #include vs. ASL Include() The #include is a preprocessor directive. The included file can contain additional preprocessor directives. The ASL Include() operator includes a file during compile time, after the preprocessor has run. Therefore, it cannot contain any preprocessor directives. #include Usage: #include filename #include Include an additional file for compilation. This file is subject to processing by the preprocessor, unlike the Include() ASL operator, which is only invoked after the preprocessor has completed operation. #includebuffer Usage: #includebuffer binary_filename BufferName #includebuffer BufferName Where BufferName is a standard ACPI NamePath. An ACPI buffer object is created with this name and the named object can be created anywhere within the ACPI namespace. This directive allows for the inclusion of binary data into an ASL file. The binary data is converted into the ASL declaration of an ACPI Buffer object with the binary data as the buffer initialization data. Since #includebuffer is not a standard C or ASL preprocessor directive, the directive can be bypassed during this early preprocessing via the __IASL__ predefined name: #ifdef __IASL__ #includebuffer #endif #line Usage: #line value Changes the internal line number that is used for compiler error and warning messages. Miscellaneous Directives #error Usage: #error error_message Generates a compiler error. #pragma Usage: #pragma operator Only #pragma message is suppported at this time. #pragma message message. Emits the message. #warning Usage: #warning warning_message Generates a compiler warning. ASL-AML Subsystem This subsystem consists of tools to compile ASL source code to AML byte code, and disassemble AML byte code back to the original ASL code. ASL Compiler The iASL compiler fully supports ACPI 5.1. The ASL and AML languages are defined within the ACPI specification. Support for Symbolic Operators and Expressions (ASL+) As an extension to the ASL language, iASL implements support for symbolic (C-style) operators for math and logical expressions. This can greatly simplify ASL code as well as improve readability and maintainability. These language extensions can exist concurrently with all legacy ASL code and expressions. ASL with these language extensions is called ASL+. The symbolic extensions are 100% compatible with existing AML interpreters, since no new AML opcodes are created. To implement the extensions, the iASL compiler transforms the symbolic expressions into the legacy ASL/AML equivalents at compile time. Full symbolic expressions are supported, along with the standard C precedence and associativity rules. Full disassembler support for the symbolic expressions is provided, and creates a migration path for existing ASL code via the disassembly process. Below is the full list of the currently supported symbolic operators with examples to follow. ASL+ Syntax Legacy ASL Equivalent // Math operators Z = X + Y Add (X, Y, Z) Z = X - Y Subtract (X, Y, Z) Z = X * Y Multiply (X, Y, Z) Z = X / Y Divide (X, Y, , Z) Z = X % Y Mod (X, Y, Z) Z = X << Y ShiftLeft (X, Y, Z) Z = X >> Y ShiftRight (X, Y, Z) Z = X & Y And (X, Y, Z) Z = X | Y Or (X, Y, Z) Z = X ^ Y Xor (X, Y, Z) Z = ~X Not (X, Z) X++ Increment (X) X-- Decrement (X) // Logical operators (X == Y) LEqual (X, Y) (X != Y) LNotEqual (X, Y) (X < Y) LLess (X, Y) (X > Y) LGreater (X, Y) (X <= Y) LLessEqual (X, Y) (X >= Y) LGreaterEqual (X, Y) (X && Y) LAnd (X, Y) (X || Y) LOr (X, Y) (!X) LNot (X) // Compound assignment operations X = Y Store (Y, X) X += Y Add (X, Y, X) X -= Y Subtract (X, Y, X) X *= Y Multiply (X, Y, X) X /= Y Divide (X, Y, , X) X %= Y Mod (X, Y, X) X <<= Y ShiftLeft (X, Y, X) X >>= Y ShiftRight (X, Y, X) X &= Y And (X, Y, X) X |= Y Or (X, Y, X) X ^= Y Xor (X, Y, X) Examples: If (LAnd (LAnd (LEqual (IID0, EID0), LEqual (IID1, EID1)), LAnd (LEqual (IID2, EID2), LEqual (IID3, EID3)))) ---> if ((IID0 == EID0) && (IID1 == EID1) && (IID2 == EID2) && (IID3 == EID3)) If (LAnd (LGreaterEqual (\_PR.CLVL, One), LLessEqual (\_PR.CLVL, 0x03))) ---> if ((\_PR.CLVL >= 1) && (\_PR.CLVL <= 3)) If (LOr (LEqual (And (RF0H, 0xE0), 0x60), LEqual (And ( RF0H, 0xE0), 0x40))) ---> if (((RF0H & 0xE0) == 0x60) || ((RF0H & 0xE0) == 0x40)) ShiftRight (And (\_SB.IAOE.ECTM, 0x00FF0000), 0x10) ---> (\_SB.IAOE.ECTM & 0x00FF0000) >> 0x10 If (LAnd (And (IUBE, One), LGreaterEqual (OSYS, 0x07DC))) ---> if ((IUBE & 1) && (OSYS >= 0x07DC)) Binary AML Considerations Typically, the iASL compiler will produce identical AML code for both symbolic expressions and the equivalent legacy ASL code. For example, consider these two sematically identical statements: Add (Local0, ShiftLeft (Temp, 3), Local1) Local1 = Local0 + (Temp << 3) Both of these statements compile to the identical AML code, as shown in the listing below: 11: Add (Local0, ShiftLeft (Temp, 3), Local1) 0000003A: 72 60 .................. "r`" 0000003C: 79 54 45 4D 50 0A 03 00 "yTEMP..." 00000044: 61 ..................... "a" 13: Local1 = Local0 + (Temp << 3) 00000045: 72 60 .................. "r`" 00000047: 79 54 45 4D 50 0A 03 00 "yTEMP..." 0000004F: 61 ..................... "a" AML Disassembler Notes The AML disassembler by default produces ASL+ code with symbolic operators and expressions. In fact, this is the quickest way to convert existing (legacy) ASL code to the ASL+ language. In general, a disassemble/recompile sequence will produce AML code that is identical to the original AML code. However, there are some cases where this is not true and the AML code becomes optimized during the process. For example: 14: Store (Multiply (TEMP, 5), Local1) 00000050: 70 ..................... "p" 00000051: 77 54 45 4D 50 0A 05 00 "wTEMP..." 00000059: 61 ..................... "a" This code will disassemble to equivalent ASL+ and and then recompile to slightly different AML: 14: Local1 = TEMP * 5 00000050: 77 54 45 4D 50 0A 05 61 "wTEMP..a" As shown above, the disassembly/recompile process has optimized the original statement to this legacy ASL equivalent: 18: Multiply (TEMP, 5, Local1) 00000062: 77 54 45 4D 50 0A 05 61 "wTEMP..a" Built-in ASL Macros The iASL compiler implements several macros that are not part of the ACPI specification, but have been implemented for convenience. These macros are similar to their C equivalents: __FILE__ - Returns the current input (source) filename. __PATH__ - Returns the current full pathname of the input (source) file. __LINE__ - Returns the current line number within the input (source) file. __DATE__ - Returns the current date and time. __IASL__ - Always defined for the iASL compiler. Can be used to differentiate between ASL compilers and/or other preprocessors such as a C preprocessor. Example: DefinitionBlock ("dsdt.aml", "DSDT", 2, "Intel", "Template", 0x00000001) { Method (MAIN, 0, NotSerialized) { Store (__FILE__, Debug) Store (__LINE__, Debug) Store (__DATE__, Debug) } } - execute main Executing \MAIN [ACPI Debug] String [0x08] "dsdt.asl" [ACPI Debug] Integer 0x0000000000000006 [ACPI Debug] String [0x18] "Thu Jan 13 12:29:44 2011" Compiler Analysis Phases General ASL Syntax Analysis Enhanced ASL syntax checking. Multiple errors and warnings are reported in one compile the compiler recovers to the next ASL statement upon detection of a syntax error. Constants larger than the target data size are flagged as errors. For example, if the target data type is a BYTE, the compiler will reject any constants larger than 0xFF (255). The same error checking is performed for WORD and DWORD constants. General Semantic Analysis All named references to objects are checked for validity. All names (both full ACPI Namepaths and 4-character Namesegs) must refer to valid declared objects. All Fields created within Operation Regions and Buffers are checked for out-of-bounds offset and length. The minimum access width specified for the field is used when performing this check to ensure that the field can be properly accessed. Control Method Semantic Analysis Method local variables are checked for initialization before use. All locals (LOCAL0 LOCAL7) must be initialized before use. This prevents fatal run-time errors for uninitialized ASL arguments. Method arguments are checked for validity. For example, a control method defined with 1 argument cant use ARG4. Again, this prevents fatal run-time errors for uninitialized ASL arguments. Control method execution paths are analyzed to determine if all return statements are of the same type to ensure that either all return statements return a value, or all do not. This includes an analysis to determine if execution can possibly fall through to the default implicit return (which does not return a value) at the end of the method. A warning is issued if some method control paths return a value and others do not Control Method Invocation Analysis All control method invocations (method calls) are checked for the correct number of arguments in all cases, regardless of whether the method is invoked with argument parentheses or not (e.g. both ABCD() and ABCD). Prevents run-time errors caused by non-existent arguments. All control methods and invocations are checked to ensure that if a return value is expected and used by the method caller, the target method actually returns a value. Predefined ACPI Names For all ACPI reserved control methods (such as _STA, _TMP, etc.), both the number of arguments and return types (whether the method must return a value or not) are checked. This prevents missing operand run-time errors that may not be detected until after the product is shipped. Predefined names that are defined with arguments or return no value must be implemented as control methods and are flagged if they are not. Predefined names that may be implemented as static objects via the ASL Name() operator are typechecked. Reserved names (all names that begin with an underscore are reserved) that are not currently defined by ACPI are flagged with a warning. Resource Descriptors Validation of values for Resource Descriptors is performed wherever possible. Address Descriptors: Values for AddressMin, AddressMax, Length, and Granularity are validated: AddressMax must be greater than or equal to AddressMin Length must be less than or equal to (Max-Min+1) If Granularity is non-zero, it must be a power-of-two minus one. The IsMinFixed and IsMaxFixed parameters are validated against the values given for the AddressMin, AddressMax, Length, and Granularity. This implements the rules given in Table 6-179 of the ACPI 5.0 specification. Compiler Optimizations The compiler implements several optimizations whose primary intent is to reduce the size of the resulting AML output. Named References Namepaths within the ASL can often be optimized to shorter strings than specified by the ASL programmer. For example, a full pathname can be optimized to a single 4-character ACPI name if the final name in the path is within the local scope or is along the upward search path to the root from the local scope. In addition, the carat (^) operator can often be used to optimize Namepaths. Integers Certain integers can be optimized to single-byte AML opcodes. These are: 0, 1, and -1. The opcodes used are Zero, One, and Ones. All other integers are described in AML code using the smallest representation necessary either Byte, Word, DWord, or QWord. Constant Folding All expressions that can be evaluated at compile-time rather than run time are executed and reduced to the simplified value. The ASL operators that are supported in this manner are the Type3, Type4, and Type5 operators defined in the ACPI specification. The iASL compiler contains the ACPICA AML interpreter which is used to evaluate these expressions at compile time. ASL-to-AML Disassembler The AML disassembler is used to regenerate the original ASL code from a binary ACPI AML table. Tables that contain AML are typically the DSDT and any SSDTs. The disassembler is invoked by using the d option of iASL. Because the AML contains all of the original symbols from the ASL, the AML byte code of a binary ACPI table can be disassembled back to nearly the original ASL code with only a few caveats. Multiple Table Disassembly There is a known difficulty in disassembling control method invocations for methods that are external to the table being disassembled. This is because there is often insufficient information within the AML to properly disassemble these method invocations. Therefore, whenever possible, all DSDTs and SSDTs for a given machine should be disassembled together using the da or e option. If all SSDTs are included this way, the necessary information will be available to fully and correctly disassemble the target table. For example, to disassemble the DSDT on a machine with multiple SSDTs: $ iasl -essdt1.dat,ssdt2.dat,ssdt3.dat -d dsdt.dat Intel ACPI Component Architecture AML Disassembler version 20100528 [May 28 2010] Copyright (c) 2000 - 2010 Intel Corporation Supports ACPI Specification Revision 5.0 Loading Acpi table from file DSDT.dat Acpi table [DSDT] successfully installed and loaded Loading Acpi table from file ssdt1.dat Acpi table [SSDT] successfully installed and loaded Pass 1 parse of [SSDT] Pass 2 parse of [SSDT] Loading Acpi table from file ssdt2.dat Acpi table [SSDT] successfully installed and loaded Pass 1 parse of [SSDT] Pass 2 parse of [SSDT] Loading Acpi table from file ssdt3.dat Acpi table [SSDT] successfully installed and loaded Pass 1 parse of [SSDT] Pass 2 parse of [SSDT] Pass 1 parse of [DSDT] Pass 2 parse of [DSDT] Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions) .................................................................................. Parsing completed Disassembly completed, written to "DSDT.dsl" External Declarations During disassembly, any ACPI names that cannot be found or resolved within the table under disassembly are added to a list of externals that are emitted at the start of the table definition block, as shown below: DefinitionBlock ("DSDT.aml", "DSDT", 1, "INTEL ", "EXAMPLE", 0x06040000) { External (Z003) External (\_SB_.PCI0.LNKH) If the object type that is associated with the name can be resolved during the disassembly, this type is emitted with the external statement also: External (PETE, IntObj) External (HDOS, MethodObj) // 0 Arguments External (ECST, MethodObj) // 1 Arguments External (PSEN, FieldUnitObj) External (C7EN, FieldUnitObj) External (\_PR_.CPU1, DeviceObj) External (\_PR_.CPU0, DeviceObj) The External AML Opcode In ACPI 6.1, a new AML opcode (0x15) was defined to allow the compiler to insert external declarations within the AML code itself. This allows the disassembler to easily and deterministically construct the original External() statements in the source ASL code. Generation of ASL External() Statements There are two ways that external declarations can be emitted by the disassembler: external opcodes within the AML and ACPI names that cannot be found within the table. External opcodes encode names that should be declared as external named objects. This facilitates disassembly of external control method objects because the external opcode contains the objects type as well as the number of parameters for external control methods. These externals are emitted at the start of the table definition block shown below: However, not all AML contain external opcodes. During disassembly, any ACPI names that cannot be found or resolved within the table under disassembly are added to a list of externals that are emitted at the start of the table definition block, as shown above. ASL to ASL+ Converter Legacy ASL (also known as ASL) does not support symbolic operators such as arithmetic and logical operators. This often results in code that looks cluttered and therefore difficult to read and maintain. The ASL/ASL+ Converter can be used to translate legacy ASL to ASL+ by compiling and disassembling an input ASL file while retaining comments. Since ASL+ has support for symbolic operators, the ASL/ASL+ Converter can be used to increase redability and maintainability. Using the ASL/ASL+ Converter To run the converter, use the ca flag along with a targetASL filename. iasl ca ssdt.asl This produces translated dsl files for ssdt.asl as well as all files that sstd.asl includes via the ASL include. A sample file is located at acpica/tests/misc/converterSample.asl Example: ASL/ASL+ Converter and Disassembler AML files resulting from compiling the converted file should be an exact binary match as a normally compiled ASL file. This is true for files that have been compiled with externals in place, disassembled with externals, and recompiled. Figure 1 illustrates a portion of the ASL test suite architecture that exercise the ideas described above. Note that all AML files generated from this process should all have matching binary comparisons. Figure 1. ASL Test Suite Architecture  SHAPE \* MERGEFORMAT  Items currently not supported The following ASL constructs are currently not supported within the ASL/ASL+ converter: Pre-processor directives such as #include and macros are not supported. Comments within buffer and resource template declarations will not be kept. Using the f option in conjunction with ca does not guarantee a correct conversion. ACPI Data Table Subsystem This subsystem consists of tools to compile ACPI Data Tables such as the FADT, MADT, SRAT, etc., to binary ACPI tables, and to disassemble binary ACPI data tables to formatted and structured tables in the data table language. Data Table Compiler The iASL Data Table Compiler is intended to compile ACPI data tables (FADT, MADT, etc) to binary data, to be integrated into a BIOS project. Data Tables are described in a simple language that is directly compatible with the output of the data table disassembler. The two goals for this language are simplicity and compatibility with the disassembler. Data Table input files are automatically detected and differentiated from ASL files, therefore no special iASL option is required to invoke the data table compiler. The default output is a binary ACPI data table. Use one of the iASL options ta, tc, or ts, in order to create the binary output in an ASCII hex table that is suitable for direct inclusion into a BIOS project. On some host operating systems, the iASL data table disassembler and compiler may be used to disassemble a data table, modify it, then recompile it to a binary file that can be used to override the original table. This override support depends upon features supported by the host operating system. This feature would be useful, for example, to repair invalid or incorrect values in an important table such as the FADT. Input Format The format of the input file is a series of fields, each of which represents a field in the target ACPI table. Each field is comprised of a field name and a field value, separated by a colon. The fields must appear in the exact order in which they are defined for the target ACPI table. : : . . . : Both slash-asterisk and slash-slash comments are supported. Blank lines are ignored. The language itself is defined in the next section. The Field Names (AcpiTableFieldName) that are available for any given ACPI table can be obtained from the template file generated by the iASL Template Generator: iASL T // Obtain one template iASL T all // Obtain templates for all ACPI tables Ignored Fields/Comments Comments can be either traditional /* .. */ style or // style. Additional fields that are ignored (and are essentially comments) are fields surrounded by brackets [..]. This allows automatic compatibility with the output of the AML disassembler. Data Table Definition Language // // Root Term // DataTable := FieldList // // Field Terms // FieldList := Field | Field := | CommentField FieldDefinition := // Fields for predefined (known) ACPI tables | // Generic data types (used for custom or undefined ACPI tables) | // 8-bit unsigned integer | // 16-bit unsigned integer | // 24-bit unsigned integer | // 32-bit unsigned integer | // 40-bit unsigned integer | // 48-bit unsigned integer | // 56-bit unsigned integer | // 64-bit unsigned integer | // Quoted ASCII string | // Quoted ASCII string -> Unicode string | // Raw buffer of 8-bit unsigned integers | // In GUID format