Define symbol for preprocessor use
-li Create preprocessed output file (*.i)
-P Preprocess only and create preprocessor output file (*.i)
-Pn Disable preprocessor
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)
<< Shift left
>> Shift right
< Less than
> Greater than
<= Less than or equal
>= Greater than or equal
!= Not Equal
& Bitwise AND
^ bitwise Exclusive OR
| Bitwise OR
&& Logical AND
|| Logical OR
The following directives are supported:
3.3.1Text Substitution and Macros
Note: At this time, only text substitution #defines are supported. Full macros (with arguments) are not supported.
#define name text_to_substitute
Every instance of “name” is replaced by “text_to_substitue”.
Removes a previously defined symbol, either from a #define or from the –D command line option.
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.
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.
Conditionally compile a block of text. The block is included in the compilation if the symbol is not defined (opposite from #ifdef.)
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.
Combines #else and #if to conditionally compile a block of text.
Indicates the completion of a #if…#else block.
18.104.22.168#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 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 “binary_filename” 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:
Changes the internal line number that is used for compiler error and warning messages.
Generates a compiler error.
Only “#pragma message” is suppported at this time.
#pragma message “message”.
Emits the message.
Generates a compiler warning.
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.
The iASL compiler fully supports ACPI 5.1. The ASL and AML languages are defined within the ACPI specification.
4.1.1Support 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)
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))
22.214.171.124Binary 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"
126.96.36.199AML 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"
4.1.2Built-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.
DefinitionBlock ("dsdt.aml", "DSDT", 2, "Intel", "Template", 0x00000001)
Method (MAIN, 0, NotSerialized)
Store (__FILE__, Debug)
Store (__LINE__, Debug)
Store (__DATE__, Debug)
- execute main
[ACPI Debug] String [0x08] "dsdt.asl"
[ACPI Debug] Integer 0x0000000000000006
[ACPI Debug] String [0x18] "Thu Jan 13 12:29:44 2011"
4.1.3Compiler Analysis Phases
188.8.131.52General 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.
184.108.40.206General 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.
220.127.116.11Control 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 can’t 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
18.104.22.168Control 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.
22.214.171.124Predefined 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.
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.
The compiler implements several optimizations whose primary intent is to reduce the size of the resulting AML output.
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.
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.
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.