1 /******************************************************************************
3 * Module Name: ahdecode - Operator/Opcode decoding for acpihelp utility
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2015, Intel Corp.
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions, and the following disclaimer,
16 * without modification.
17 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
18 * substantially similar to the "NO WARRANTY" disclaimer below
19 * ("Disclaimer") and any redistribution must be conditioned upon
20 * including a substantially similar Disclaimer requirement for further
21 * binary redistribution.
22 * 3. Neither the names of the above-listed copyright holders nor the names
23 * of any contributors may be used to endorse or promote products derived
24 * from this software without specific prior written permission.
26 * Alternatively, this software may be distributed under the terms of the
27 * GNU General Public License ("GPL") version 2 as published by the Free
28 * Software Foundation.
31 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
34 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
40 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
41 * POSSIBILITY OF SUCH DAMAGES.
44 #define ACPI_CREATE_PREDEFINED_TABLE
45 #define ACPI_CREATE_RESOURCE_TABLE
51 #define AH_DISPLAY_EXCEPTION(Status, Name) \
52 printf ("%.4X: %s\n", Status, Name)
54 #define AH_DISPLAY_EXCEPTION_TEXT(Status, Exception) \
55 printf ("%.4X: %-28s (%s)\n", Status, Exception->Name, Exception->Description)
57 #define BUFFER_LENGTH 128
58 #define LINE_BUFFER_LENGTH 512
60 static char Gbl_Buffer[BUFFER_LENGTH];
61 static char Gbl_LineBuffer[LINE_BUFFER_LENGTH];
64 /* Local prototypes */
67 AhDisplayPredefinedName (
72 AhDisplayPredefinedInfo (
76 AhDisplayResourceName (
77 const ACPI_PREDEFINED_INFO *ThisName);
81 const AH_AML_OPCODE *Op);
84 AhDisplayAslOperator (
85 const AH_ASL_OPERATOR *Op);
88 AhDisplayOperatorKeywords (
89 const AH_ASL_OPERATOR *Op);
93 const AH_ASL_KEYWORD *Op);
98 UINT32 CurrentPosition,
103 /*******************************************************************************
105 * FUNCTION: AhDisplayDirectives
111 * DESCRIPTION: Display all iASL preprocessor directives.
113 ******************************************************************************/
116 AhDisplayDirectives (
119 const AH_DIRECTIVE_INFO *Info;
122 printf ("iASL Preprocessor Directives\n\n");
124 for (Info = PreprocessorDirectives; Info->Name; Info++)
126 printf (" %-36s : %s\n", Info->Name, Info->Description);
131 /*******************************************************************************
133 * FUNCTION: AhFindPredefinedNames (entry point for predefined name search)
135 * PARAMETERS: NamePrefix - Name or prefix to find. Must start with
136 * an underscore. NULL means "find all"
140 * DESCRIPTION: Find and display all ACPI predefined names that match the
141 * input name or prefix. Includes the required number of arguments
142 * and the expected return type, if any.
144 ******************************************************************************/
147 AhFindPredefinedNames (
157 Found = AhDisplayPredefinedName (NULL, 0);
161 /* Contruct a local name or name prefix */
163 AcpiUtStrupr (NamePrefix);
164 if (*NamePrefix == '_')
170 strncpy (&Name[1], NamePrefix, 7);
172 Length = strlen (Name);
175 printf ("%.8s: Predefined name must be 4 characters maximum\n", Name);
179 Found = AhDisplayPredefinedName (Name, Length);
182 printf ("%s, no matching predefined names\n", Name);
187 /*******************************************************************************
189 * FUNCTION: AhDisplayPredefinedName
191 * PARAMETERS: Name - Name or name prefix
193 * RETURN: TRUE if any names matched, FALSE otherwise
195 * DESCRIPTION: Display information about ACPI predefined names that match
196 * the input name or name prefix.
198 ******************************************************************************/
201 AhDisplayPredefinedName (
205 const AH_PREDEFINED_NAME *Info;
206 BOOLEAN Found = FALSE;
211 /* Find/display all names that match the input name prefix */
213 for (Info = AslPredefinedInfo; Info->Name; Info++)
218 printf ("%s: <%s>\n", Info->Name, Info->Description);
219 printf ("%*s%s\n", 6, " ", Info->Action);
221 AhDisplayPredefinedInfo (Info->Name);
227 for (i = 0; i < Length; i++)
229 if (Info->Name[i] != Name[i])
239 printf ("%s: <%s>\n", Info->Name, Info->Description);
240 printf ("%*s%s\n", 6, " ", Info->Action);
242 AhDisplayPredefinedInfo (Info->Name);
248 printf ("\nFound %d Predefined ACPI Names\n", i);
254 /*******************************************************************************
256 * FUNCTION: AhDisplayPredefinedInfo
258 * PARAMETERS: Name - Exact 4-character ACPI name.
262 * DESCRIPTION: Find the name in the main ACPICA predefined info table and
263 * display the # of arguments and the return value type.
265 * Note: Resource Descriptor field names do not appear in this
266 * table -- thus, nothing will be displayed for them.
268 ******************************************************************************/
271 AhDisplayPredefinedInfo (
274 const ACPI_PREDEFINED_INFO *ThisName;
277 /* NOTE: we check both tables always because there are some dupes */
279 /* Check against the predefine methods first */
281 ThisName = AcpiUtMatchPredefinedMethod (Name);
284 AcpiUtDisplayPredefinedMethod (Gbl_Buffer, ThisName, TRUE);
287 /* Check against the predefined resource descriptor names */
289 ThisName = AcpiUtMatchResourceName (Name);
292 AhDisplayResourceName (ThisName);
297 /*******************************************************************************
299 * FUNCTION: AhDisplayResourceName
301 * PARAMETERS: ThisName - Entry in the predefined method/name table
305 * DESCRIPTION: Display information about a resource descriptor name.
307 ******************************************************************************/
310 AhDisplayResourceName (
311 const ACPI_PREDEFINED_INFO *ThisName)
316 NumTypes = AcpiUtGetResourceBitWidth (Gbl_Buffer,
317 ThisName->Info.ArgumentList);
319 printf (" %4.4s resource descriptor field is %s bits wide%s\n",
322 (NumTypes > 1) ? " (depending on descriptor type)" : "");
326 /*******************************************************************************
328 * FUNCTION: AhFindAmlOpcode (entry point for AML opcode name search)
330 * PARAMETERS: Name - Name or prefix for an AML opcode.
331 * NULL means "find all"
335 * DESCRIPTION: Find all AML opcodes that match the input Name or name
338 ******************************************************************************/
344 const AH_AML_OPCODE *Op;
345 BOOLEAN Found = FALSE;
350 /* Find/display all opcode names that match the input name prefix */
352 for (Op = AmlOpcodeInfo; Op->OpcodeString; Op++)
354 if (!Op->OpcodeName) /* Unused opcodes */
361 AhDisplayAmlOpcode (Op);
366 /* Upper case the opcode name before substring compare */
368 strcpy (Gbl_Buffer, Op->OpcodeName);
369 AcpiUtStrupr (Gbl_Buffer);
371 if (strstr (Gbl_Buffer, Name) == Gbl_Buffer)
373 AhDisplayAmlOpcode (Op);
380 printf ("%s, no matching AML operators\n", Name);
385 /*******************************************************************************
387 * FUNCTION: AhDecodeAmlOpcode (entry point for AML opcode search)
389 * PARAMETERS: OpcodeString - String version of AML opcode
393 * DESCRIPTION: Display information about the input AML opcode
395 ******************************************************************************/
401 const AH_AML_OPCODE *Op;
408 AhFindAmlOpcode (NULL);
412 Opcode = strtoul (OpcodeString, NULL, 16);
413 if (Opcode > ACPI_UINT16_MAX)
415 printf ("Invalid opcode (more than 16 bits)\n");
419 /* Only valid opcode extension is 0x5B */
421 Prefix = (Opcode & 0x0000FF00) >> 8;
422 if (Prefix && (Prefix != 0x5B))
424 printf ("Invalid opcode (invalid extension prefix 0x%X)\n",
429 /* Find/Display the opcode. May fall within an opcode range */
431 for (Op = AmlOpcodeInfo; Op->OpcodeString; Op++)
433 if ((Opcode >= Op->OpcodeRangeStart) &&
434 (Opcode <= Op->OpcodeRangeEnd))
436 AhDisplayAmlOpcode (Op);
442 /*******************************************************************************
444 * FUNCTION: AhDisplayAmlOpcode
446 * PARAMETERS: Op - An opcode info struct
450 * DESCRIPTION: Display the contents of an AML opcode information struct
452 ******************************************************************************/
456 const AH_AML_OPCODE *Op)
461 printf ("%18s: Opcode=%-9s\n", "Reserved opcode", Op->OpcodeString);
465 /* Opcode name and value(s) */
467 printf ("%18s: Opcode=%-9s Type (%s)",
468 Op->OpcodeName, Op->OpcodeString, Op->Type);
470 /* Optional fixed/static arguments */
472 if (Op->FixedArguments)
474 printf (" FixedArgs (");
475 AhPrintOneField (37, 36 + 7 + strlen (Op->Type) + 12,
476 AH_MAX_AML_LINE_LENGTH, Op->FixedArguments);
480 /* Optional variable-length argument list */
482 if (Op->VariableArguments)
484 if (Op->FixedArguments)
486 printf ("\n%*s", 36, " ");
488 printf (" VariableArgs (");
489 AhPrintOneField (37, 15, AH_MAX_AML_LINE_LENGTH, Op->VariableArguments);
494 /* Grammar specification */
498 AhPrintOneField (37, 0, AH_MAX_AML_LINE_LENGTH, Op->Grammar);
504 /*******************************************************************************
506 * FUNCTION: AhFindAslKeywords (entry point for ASL keyword search)
508 * PARAMETERS: Name - Name or prefix for an ASL keyword.
509 * NULL means "find all"
513 * DESCRIPTION: Find all ASL keywords that match the input Name or name
516 ******************************************************************************/
522 const AH_ASL_KEYWORD *Keyword;
523 BOOLEAN Found = FALSE;
528 for (Keyword = AslKeywordInfo; Keyword->Name; Keyword++)
532 AhDisplayAslKeyword (Keyword);
537 /* Upper case the operator name before substring compare */
539 strcpy (Gbl_Buffer, Keyword->Name);
540 AcpiUtStrupr (Gbl_Buffer);
542 if (strstr (Gbl_Buffer, Name) == Gbl_Buffer)
544 AhDisplayAslKeyword (Keyword);
551 printf ("%s, no matching ASL keywords\n", Name);
556 /*******************************************************************************
558 * FUNCTION: AhDisplayAslKeyword
560 * PARAMETERS: Op - Pointer to ASL keyword with syntax info
564 * DESCRIPTION: Format and display syntax info for an ASL keyword. Splits
565 * long lines appropriately for reading.
567 ******************************************************************************/
570 AhDisplayAslKeyword (
571 const AH_ASL_KEYWORD *Op)
574 /* ASL keyword name and description */
576 printf ("%22s: %s\n", Op->Name, Op->Description);
577 if (!Op->KeywordList)
582 /* List of actual keywords */
584 AhPrintOneField (24, 0, AH_MAX_ASL_LINE_LENGTH, Op->KeywordList);
589 /*******************************************************************************
591 * FUNCTION: AhFindAslAndAmlOperators
593 * PARAMETERS: Name - Name or prefix for an ASL operator.
594 * NULL means "find all"
598 * DESCRIPTION: Find all ASL operators that match the input Name or name
599 * prefix. Also displays the AML information if only one entry
602 ******************************************************************************/
605 AhFindAslAndAmlOperators (
611 MatchCount = AhFindAslOperators (Name);
614 AhFindAmlOpcode (Name);
619 /*******************************************************************************
621 * FUNCTION: AhFindAslOperators (entry point for ASL operator search)
623 * PARAMETERS: Name - Name or prefix for an ASL operator.
624 * NULL means "find all"
626 * RETURN: Number of operators that matched the name prefix.
628 * DESCRIPTION: Find all ASL operators that match the input Name or name
631 ******************************************************************************/
637 const AH_ASL_OPERATOR *Operator;
638 BOOLEAN MatchCount = 0;
643 /* Find/display all names that match the input name prefix */
645 for (Operator = AslOperatorInfo; Operator->Name; Operator++)
649 AhDisplayAslOperator (Operator);
654 /* Upper case the operator name before substring compare */
656 strcpy (Gbl_Buffer, Operator->Name);
657 AcpiUtStrupr (Gbl_Buffer);
659 if (strstr (Gbl_Buffer, Name) == Gbl_Buffer)
661 AhDisplayAslOperator (Operator);
668 printf ("%s, no matching ASL operators\n", Name);
675 /*******************************************************************************
677 * FUNCTION: AhDisplayAslOperator
679 * PARAMETERS: Op - Pointer to ASL operator with syntax info
683 * DESCRIPTION: Format and display syntax info for an ASL operator. Splits
684 * long lines appropriately for reading.
686 ******************************************************************************/
689 AhDisplayAslOperator (
690 const AH_ASL_OPERATOR *Op)
693 /* ASL operator name and description */
695 printf ("%16s: %s\n", Op->Name, Op->Description);
701 /* Syntax for the operator */
703 AhPrintOneField (18, 0, AH_MAX_ASL_LINE_LENGTH, Op->Syntax);
706 AhDisplayOperatorKeywords (Op);
711 /*******************************************************************************
713 * FUNCTION: AhDisplayOperatorKeywords
715 * PARAMETERS: Op - Pointer to ASL keyword with syntax info
719 * DESCRIPTION: Display any/all keywords that are associated with the ASL
722 ******************************************************************************/
725 AhDisplayOperatorKeywords (
726 const AH_ASL_OPERATOR *Op)
729 char *Separators = "(){}, ";
730 BOOLEAN FirstKeyword = TRUE;
733 if (!Op || !Op->Syntax)
739 * Find all parameters that have the word "keyword" within, and then
740 * display the info about that keyword
742 strcpy (Gbl_LineBuffer, Op->Syntax);
743 Token = strtok (Gbl_LineBuffer, Separators);
746 if (strstr (Token, "Keyword"))
751 FirstKeyword = FALSE;
754 /* Found a keyword, display keyword information */
756 AhFindAslKeywords (Token);
759 Token = strtok (NULL, Separators);
764 /*******************************************************************************
766 * FUNCTION: AhPrintOneField
768 * PARAMETERS: Indent - Indent length for new line(s)
769 * CurrentPosition - Position on current line
770 * MaxPosition - Max allowed line length
771 * Field - Data to output
773 * RETURN: Line position after field is written
775 * DESCRIPTION: Split long lines appropriately for ease of reading.
777 ******************************************************************************/
782 UINT32 CurrentPosition,
794 Position = CurrentPosition;
798 printf ("%*s", (int) Indent, " ");
802 Last = This + strlen (This);
803 while ((Next = strpbrk (This, " ")))
805 TokenLength = Next - This;
806 Position += TokenLength;
808 /* Split long lines */
810 if (Position > MaxPosition)
812 printf ("\n%*s", (int) Indent, " ");
813 Position = TokenLength;
816 printf ("%.*s ", (int) TokenLength, This);
820 /* Handle last token on the input line */
822 TokenLength = Last - This;
825 Position += TokenLength;
826 if (Position > MaxPosition)
828 printf ("\n%*s", (int) Indent, " ");
835 /*******************************************************************************
837 * FUNCTION: AhDisplayDeviceIds
839 * PARAMETERS: Name - Device Hardware ID string.
840 * NULL means "find all"
844 * DESCRIPTION: Display PNP* and ACPI* device IDs.
846 ******************************************************************************/
852 const AH_DEVICE_ID *Info;
856 BOOLEAN Found = FALSE;
859 /* Null input name indicates "display all" */
863 printf ("ACPI and PNP Device/Hardware IDs:\n\n");
864 for (Info = AslDeviceIds; Info->Name; Info++)
866 printf ("%8s %s\n", Info->Name, Info->Description);
872 Length = strlen (Name);
875 printf ("%.8s: Hardware ID must be 8 characters maximum\n", Name);
879 /* Find/display all names that match the input name prefix */
882 for (Info = AslDeviceIds; Info->Name; Info++)
885 for (i = 0; i < Length; i++)
887 if (Info->Name[i] != Name[i])
897 printf ("%8s %s\n", Info->Name, Info->Description);
903 printf ("%s, Hardware ID not found\n", Name);
908 /*******************************************************************************
910 * FUNCTION: AhDisplayUuids
916 * DESCRIPTION: Display all known UUIDs.
918 ******************************************************************************/
927 printf ("ACPI-related UUIDs/GUIDs:\n");
929 /* Display entire table of known ACPI-related UUIDs/GUIDs */
931 for (Info = AcpiUuids; Info->Description; Info++)
933 if (!Info->String) /* Null UUID string means group description */
935 printf ("\n%36s\n", Info->Description);
939 printf ("%32s : %s\n", Info->Description, Info->String);
943 /* Help info on how UUIDs/GUIDs strings are encoded */
945 printf ("\n\nByte encoding of UUID/GUID strings"
946 " into ACPI Buffer objects (use ToUUID from ASL):\n\n");
948 printf ("%32s : %s\n", "Input UUID/GUID String format",
949 "aabbccdd-eeff-gghh-iijj-kkllmmnnoopp");
951 printf ("%32s : %s\n", "Expected output ACPI buffer",
952 "dd,cc,bb,aa, ff,ee, hh,gg, ii,jj, kk,ll,mm,nn,oo,pp");
956 /*******************************************************************************
958 * FUNCTION: AhDisplayTables
964 * DESCRIPTION: Display all known ACPI tables
966 ******************************************************************************/
972 const AH_TABLE *Info;
976 printf ("Known ACPI tables:\n");
978 for (Info = AcpiSupportedTables; Info->Signature; Info++)
980 printf ("%8s : %s\n", Info->Signature, Info->Description);
984 printf ("\nTotal %u ACPI tables\n\n", i);
988 /*******************************************************************************
990 * FUNCTION: AhDecodeException
992 * PARAMETERS: HexString - ACPI status string from command line, in
993 * hex. If null, display all exceptions.
997 * DESCRIPTION: Decode and display an ACPI_STATUS exception code.
999 ******************************************************************************/
1005 const ACPI_EXCEPTION_INFO *ExceptionInfo;
1011 * A null input string means to decode and display all known
1016 printf ("All defined ACPICA exception codes:\n\n");
1017 AH_DISPLAY_EXCEPTION (0, "AE_OK (No error occurred)");
1019 /* Display codes in each block of exception types */
1021 for (i = 1; (i & AE_CODE_MASK) <= AE_CODE_MAX; i += 0x1000)
1026 ExceptionInfo = AcpiUtValidateException ((ACPI_STATUS) Status);
1029 AH_DISPLAY_EXCEPTION_TEXT (Status, ExceptionInfo);
1033 } while (ExceptionInfo);
1038 /* Decode a single user-supplied exception code */
1040 Status = strtoul (HexString, NULL, 16);
1043 printf ("%s: Invalid hexadecimal exception code value\n", HexString);
1047 if (Status > ACPI_UINT16_MAX)
1049 AH_DISPLAY_EXCEPTION (Status, "Invalid exception code (more than 16 bits)");
1053 ExceptionInfo = AcpiUtValidateException ((ACPI_STATUS) Status);
1056 AH_DISPLAY_EXCEPTION (Status, "Unknown exception code");
1060 AH_DISPLAY_EXCEPTION_TEXT (Status, ExceptionInfo);