1 /******************************************************************************
   2  *
   3  * Module Name: utdecode - Utility decoding routines (value-to-string)
   4  *
   5  *****************************************************************************/
   6 
   7 /*
   8  * Copyright (C) 2000 - 2013, Intel Corp.
   9  * All rights reserved.
  10  *
  11  * Redistribution and use in source and binary forms, with or without
  12  * modification, are permitted provided that the following conditions
  13  * are met:
  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.
  25  *
  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.
  29  *
  30  * NO WARRANTY
  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.
  42  */
  43 
  44 #define __UTDECODE_C__
  45 
  46 #include "acpi.h"
  47 #include "accommon.h"
  48 #include "acnamesp.h"
  49 
  50 #define _COMPONENT          ACPI_UTILITIES
  51         ACPI_MODULE_NAME    ("utdecode")
  52 
  53 
  54 /*
  55  * Properties of the ACPI Object Types, both internal and external.
  56  * The table is indexed by values of ACPI_OBJECT_TYPE
  57  */
  58 const UINT8                     AcpiGbl_NsProperties[ACPI_NUM_NS_TYPES] =
  59 {
  60     ACPI_NS_NORMAL,                     /* 00 Any              */
  61     ACPI_NS_NORMAL,                     /* 01 Number           */
  62     ACPI_NS_NORMAL,                     /* 02 String           */
  63     ACPI_NS_NORMAL,                     /* 03 Buffer           */
  64     ACPI_NS_NORMAL,                     /* 04 Package          */
  65     ACPI_NS_NORMAL,                     /* 05 FieldUnit        */
  66     ACPI_NS_NEWSCOPE,                   /* 06 Device           */
  67     ACPI_NS_NORMAL,                     /* 07 Event            */
  68     ACPI_NS_NEWSCOPE,                   /* 08 Method           */
  69     ACPI_NS_NORMAL,                     /* 09 Mutex            */
  70     ACPI_NS_NORMAL,                     /* 10 Region           */
  71     ACPI_NS_NEWSCOPE,                   /* 11 Power            */
  72     ACPI_NS_NEWSCOPE,                   /* 12 Processor        */
  73     ACPI_NS_NEWSCOPE,                   /* 13 Thermal          */
  74     ACPI_NS_NORMAL,                     /* 14 BufferField      */
  75     ACPI_NS_NORMAL,                     /* 15 DdbHandle        */
  76     ACPI_NS_NORMAL,                     /* 16 Debug Object     */
  77     ACPI_NS_NORMAL,                     /* 17 DefField         */
  78     ACPI_NS_NORMAL,                     /* 18 BankField        */
  79     ACPI_NS_NORMAL,                     /* 19 IndexField       */
  80     ACPI_NS_NORMAL,                     /* 20 Reference        */
  81     ACPI_NS_NORMAL,                     /* 21 Alias            */
  82     ACPI_NS_NORMAL,                     /* 22 MethodAlias      */
  83     ACPI_NS_NORMAL,                     /* 23 Notify           */
  84     ACPI_NS_NORMAL,                     /* 24 Address Handler  */
  85     ACPI_NS_NEWSCOPE | ACPI_NS_LOCAL,   /* 25 Resource Desc    */
  86     ACPI_NS_NEWSCOPE | ACPI_NS_LOCAL,   /* 26 Resource Field   */
  87     ACPI_NS_NEWSCOPE,                   /* 27 Scope            */
  88     ACPI_NS_NORMAL,                     /* 28 Extra            */
  89     ACPI_NS_NORMAL,                     /* 29 Data             */
  90     ACPI_NS_NORMAL                      /* 30 Invalid          */
  91 };
  92 
  93 
  94 /*******************************************************************************
  95  *
  96  * FUNCTION:    AcpiUtHexToAsciiChar
  97  *
  98  * PARAMETERS:  Integer             - Contains the hex digit
  99  *              Position            - bit position of the digit within the
 100  *                                    integer (multiple of 4)
 101  *
 102  * RETURN:      The converted Ascii character
 103  *
 104  * DESCRIPTION: Convert a hex digit to an Ascii character
 105  *
 106  ******************************************************************************/
 107 
 108 /* Hex to ASCII conversion table */
 109 
 110 static const char           AcpiGbl_HexToAscii[] =
 111 {
 112     '0','1','2','3','4','5','6','7',
 113     '8','9','A','B','C','D','E','F'
 114 };
 115 
 116 char
 117 AcpiUtHexToAsciiChar (
 118     UINT64                  Integer,
 119     UINT32                  Position)
 120 {
 121 
 122     return (AcpiGbl_HexToAscii[(Integer >> Position) & 0xF]);
 123 }
 124 
 125 
 126 /*******************************************************************************
 127  *
 128  * FUNCTION:    AcpiUtGetRegionName
 129  *
 130  * PARAMETERS:  Space ID            - ID for the region
 131  *
 132  * RETURN:      Decoded region SpaceId name
 133  *
 134  * DESCRIPTION: Translate a Space ID into a name string (Debug only)
 135  *
 136  ******************************************************************************/
 137 
 138 /* Region type decoding */
 139 
 140 const char        *AcpiGbl_RegionTypes[ACPI_NUM_PREDEFINED_REGIONS] =
 141 {
 142     "SystemMemory",     /* 0x00 */
 143     "SystemIO",         /* 0x01 */
 144     "PCI_Config",       /* 0x02 */
 145     "EmbeddedControl",  /* 0x03 */
 146     "SMBus",            /* 0x04 */
 147     "SystemCMOS",       /* 0x05 */
 148     "PCIBARTarget",     /* 0x06 */
 149     "IPMI",             /* 0x07 */
 150     "GeneralPurposeIo", /* 0x08 */
 151     "GenericSerialBus", /* 0x09 */
 152     "PCC"               /* 0x0A */
 153 };
 154 
 155 
 156 char *
 157 AcpiUtGetRegionName (
 158     UINT8                   SpaceId)
 159 {
 160 
 161     if (SpaceId >= ACPI_USER_REGION_BEGIN)
 162     {
 163         return ("UserDefinedRegion");
 164     }
 165     else if (SpaceId == ACPI_ADR_SPACE_DATA_TABLE)
 166     {
 167         return ("DataTable");
 168     }
 169     else if (SpaceId == ACPI_ADR_SPACE_FIXED_HARDWARE)
 170     {
 171         return ("FunctionalFixedHW");
 172     }
 173     else if (SpaceId >= ACPI_NUM_PREDEFINED_REGIONS)
 174     {
 175         return ("InvalidSpaceId");
 176     }
 177 
 178     return (ACPI_CAST_PTR (char, AcpiGbl_RegionTypes[SpaceId]));
 179 }
 180 
 181 
 182 /*******************************************************************************
 183  *
 184  * FUNCTION:    AcpiUtGetEventName
 185  *
 186  * PARAMETERS:  EventId             - Fixed event ID
 187  *
 188  * RETURN:      Decoded event ID name
 189  *
 190  * DESCRIPTION: Translate a Event ID into a name string (Debug only)
 191  *
 192  ******************************************************************************/
 193 
 194 /* Event type decoding */
 195 
 196 static const char        *AcpiGbl_EventTypes[ACPI_NUM_FIXED_EVENTS] =
 197 {
 198     "PM_Timer",
 199     "GlobalLock",
 200     "PowerButton",
 201     "SleepButton",
 202     "RealTimeClock",
 203 };
 204 
 205 
 206 char *
 207 AcpiUtGetEventName (
 208     UINT32                  EventId)
 209 {
 210 
 211     if (EventId > ACPI_EVENT_MAX)
 212     {
 213         return ("InvalidEventID");
 214     }
 215 
 216     return (ACPI_CAST_PTR (char, AcpiGbl_EventTypes[EventId]));
 217 }
 218 
 219 
 220 /*******************************************************************************
 221  *
 222  * FUNCTION:    AcpiUtGetTypeName
 223  *
 224  * PARAMETERS:  Type                - An ACPI object type
 225  *
 226  * RETURN:      Decoded ACPI object type name
 227  *
 228  * DESCRIPTION: Translate a Type ID into a name string (Debug only)
 229  *
 230  ******************************************************************************/
 231 
 232 /*
 233  * Elements of AcpiGbl_NsTypeNames below must match
 234  * one-to-one with values of ACPI_OBJECT_TYPE
 235  *
 236  * The type ACPI_TYPE_ANY (Untyped) is used as a "don't care" when searching;
 237  * when stored in a table it really means that we have thus far seen no
 238  * evidence to indicate what type is actually going to be stored for this entry.
 239  */
 240 static const char           AcpiGbl_BadType[] = "UNDEFINED";
 241 
 242 /* Printable names of the ACPI object types */
 243 
 244 static const char           *AcpiGbl_NsTypeNames[] =
 245 {
 246     /* 00 */ "Untyped",
 247     /* 01 */ "Integer",
 248     /* 02 */ "String",
 249     /* 03 */ "Buffer",
 250     /* 04 */ "Package",
 251     /* 05 */ "FieldUnit",
 252     /* 06 */ "Device",
 253     /* 07 */ "Event",
 254     /* 08 */ "Method",
 255     /* 09 */ "Mutex",
 256     /* 10 */ "Region",
 257     /* 11 */ "Power",
 258     /* 12 */ "Processor",
 259     /* 13 */ "Thermal",
 260     /* 14 */ "BufferField",
 261     /* 15 */ "DdbHandle",
 262     /* 16 */ "DebugObject",
 263     /* 17 */ "RegionField",
 264     /* 18 */ "BankField",
 265     /* 19 */ "IndexField",
 266     /* 20 */ "Reference",
 267     /* 21 */ "Alias",
 268     /* 22 */ "MethodAlias",
 269     /* 23 */ "Notify",
 270     /* 24 */ "AddrHandler",
 271     /* 25 */ "ResourceDesc",
 272     /* 26 */ "ResourceFld",
 273     /* 27 */ "Scope",
 274     /* 28 */ "Extra",
 275     /* 29 */ "Data",
 276     /* 30 */ "Invalid"
 277 };
 278 
 279 
 280 char *
 281 AcpiUtGetTypeName (
 282     ACPI_OBJECT_TYPE        Type)
 283 {
 284 
 285     if (Type > ACPI_TYPE_INVALID)
 286     {
 287         return (ACPI_CAST_PTR (char, AcpiGbl_BadType));
 288     }
 289 
 290     return (ACPI_CAST_PTR (char, AcpiGbl_NsTypeNames[Type]));
 291 }
 292 
 293 
 294 char *
 295 AcpiUtGetObjectTypeName (
 296     ACPI_OPERAND_OBJECT     *ObjDesc)
 297 {
 298 
 299     if (!ObjDesc)
 300     {
 301         return ("[NULL Object Descriptor]");
 302     }
 303 
 304     return (AcpiUtGetTypeName (ObjDesc->Common.Type));
 305 }
 306 
 307 
 308 /*******************************************************************************
 309  *
 310  * FUNCTION:    AcpiUtGetNodeName
 311  *
 312  * PARAMETERS:  Object               - A namespace node
 313  *
 314  * RETURN:      ASCII name of the node
 315  *
 316  * DESCRIPTION: Validate the node and return the node's ACPI name.
 317  *
 318  ******************************************************************************/
 319 
 320 char *
 321 AcpiUtGetNodeName (
 322     void                    *Object)
 323 {
 324     ACPI_NAMESPACE_NODE     *Node = (ACPI_NAMESPACE_NODE *) Object;
 325 
 326 
 327     /* Must return a string of exactly 4 characters == ACPI_NAME_SIZE */
 328 
 329     if (!Object)
 330     {
 331         return ("NULL");
 332     }
 333 
 334     /* Check for Root node */
 335 
 336     if ((Object == ACPI_ROOT_OBJECT) ||
 337         (Object == AcpiGbl_RootNode))
 338     {
 339         return ("\"\\\" ");
 340     }
 341 
 342     /* Descriptor must be a namespace node */
 343 
 344     if (ACPI_GET_DESCRIPTOR_TYPE (Node) != ACPI_DESC_TYPE_NAMED)
 345     {
 346         return ("####");
 347     }
 348 
 349     /*
 350      * Ensure name is valid. The name was validated/repaired when the node
 351      * was created, but make sure it has not been corrupted.
 352      */
 353     AcpiUtRepairName (Node->Name.Ascii);
 354 
 355     /* Return the name */
 356 
 357     return (Node->Name.Ascii);
 358 }
 359 
 360 
 361 /*******************************************************************************
 362  *
 363  * FUNCTION:    AcpiUtGetDescriptorName
 364  *
 365  * PARAMETERS:  Object               - An ACPI object
 366  *
 367  * RETURN:      Decoded name of the descriptor type
 368  *
 369  * DESCRIPTION: Validate object and return the descriptor type
 370  *
 371  ******************************************************************************/
 372 
 373 /* Printable names of object descriptor types */
 374 
 375 static const char           *AcpiGbl_DescTypeNames[] =
 376 {
 377     /* 00 */ "Not a Descriptor",
 378     /* 01 */ "Cached",
 379     /* 02 */ "State-Generic",
 380     /* 03 */ "State-Update",
 381     /* 04 */ "State-Package",
 382     /* 05 */ "State-Control",
 383     /* 06 */ "State-RootParseScope",
 384     /* 07 */ "State-ParseScope",
 385     /* 08 */ "State-WalkScope",
 386     /* 09 */ "State-Result",
 387     /* 10 */ "State-Notify",
 388     /* 11 */ "State-Thread",
 389     /* 12 */ "Walk",
 390     /* 13 */ "Parser",
 391     /* 14 */ "Operand",
 392     /* 15 */ "Node"
 393 };
 394 
 395 
 396 char *
 397 AcpiUtGetDescriptorName (
 398     void                    *Object)
 399 {
 400 
 401     if (!Object)
 402     {
 403         return ("NULL OBJECT");
 404     }
 405 
 406     if (ACPI_GET_DESCRIPTOR_TYPE (Object) > ACPI_DESC_TYPE_MAX)
 407     {
 408         return ("Not a Descriptor");
 409     }
 410 
 411     return (ACPI_CAST_PTR (char,
 412         AcpiGbl_DescTypeNames[ACPI_GET_DESCRIPTOR_TYPE (Object)]));
 413 
 414 }
 415 
 416 
 417 /*******************************************************************************
 418  *
 419  * FUNCTION:    AcpiUtGetReferenceName
 420  *
 421  * PARAMETERS:  Object               - An ACPI reference object
 422  *
 423  * RETURN:      Decoded name of the type of reference
 424  *
 425  * DESCRIPTION: Decode a reference object sub-type to a string.
 426  *
 427  ******************************************************************************/
 428 
 429 /* Printable names of reference object sub-types */
 430 
 431 static const char           *AcpiGbl_RefClassNames[] =
 432 {
 433     /* 00 */ "Local",
 434     /* 01 */ "Argument",
 435     /* 02 */ "RefOf",
 436     /* 03 */ "Index",
 437     /* 04 */ "DdbHandle",
 438     /* 05 */ "Named Object",
 439     /* 06 */ "Debug"
 440 };
 441 
 442 const char *
 443 AcpiUtGetReferenceName (
 444     ACPI_OPERAND_OBJECT     *Object)
 445 {
 446 
 447     if (!Object)
 448     {
 449         return ("NULL Object");
 450     }
 451 
 452     if (ACPI_GET_DESCRIPTOR_TYPE (Object) != ACPI_DESC_TYPE_OPERAND)
 453     {
 454         return ("Not an Operand object");
 455     }
 456 
 457     if (Object->Common.Type != ACPI_TYPE_LOCAL_REFERENCE)
 458     {
 459         return ("Not a Reference object");
 460     }
 461 
 462     if (Object->Reference.Class > ACPI_REFCLASS_MAX)
 463     {
 464         return ("Unknown Reference class");
 465     }
 466 
 467     return (AcpiGbl_RefClassNames[Object->Reference.Class]);
 468 }
 469 
 470 
 471 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
 472 /*
 473  * Strings and procedures used for debug only
 474  */
 475 
 476 /*******************************************************************************
 477  *
 478  * FUNCTION:    AcpiUtGetMutexName
 479  *
 480  * PARAMETERS:  MutexId         - The predefined ID for this mutex.
 481  *
 482  * RETURN:      Decoded name of the internal mutex
 483  *
 484  * DESCRIPTION: Translate a mutex ID into a name string (Debug only)
 485  *
 486  ******************************************************************************/
 487 
 488 /* Names for internal mutex objects, used for debug output */
 489 
 490 static char                 *AcpiGbl_MutexNames[ACPI_NUM_MUTEX] =
 491 {
 492     "ACPI_MTX_Interpreter",
 493     "ACPI_MTX_Namespace",
 494     "ACPI_MTX_Tables",
 495     "ACPI_MTX_Events",
 496     "ACPI_MTX_Caches",
 497     "ACPI_MTX_Memory",
 498     "ACPI_MTX_CommandComplete",
 499     "ACPI_MTX_CommandReady"
 500 };
 501 
 502 char *
 503 AcpiUtGetMutexName (
 504     UINT32                  MutexId)
 505 {
 506 
 507     if (MutexId > ACPI_MAX_MUTEX)
 508     {
 509         return ("Invalid Mutex ID");
 510     }
 511 
 512     return (AcpiGbl_MutexNames[MutexId]);
 513 }
 514 
 515 
 516 /*******************************************************************************
 517  *
 518  * FUNCTION:    AcpiUtGetNotifyName
 519  *
 520  * PARAMETERS:  NotifyValue     - Value from the Notify() request
 521  *
 522  * RETURN:      Decoded name for the notify value
 523  *
 524  * DESCRIPTION: Translate a Notify Value to a notify namestring.
 525  *
 526  ******************************************************************************/
 527 
 528 /* Names for Notify() values, used for debug output */
 529 
 530 static const char           *AcpiGbl_NotifyValueNames[ACPI_NOTIFY_MAX + 1] =
 531 {
 532     /* 00 */ "Bus Check",
 533     /* 01 */ "Device Check",
 534     /* 02 */ "Device Wake",
 535     /* 03 */ "Eject Request",
 536     /* 04 */ "Device Check Light",
 537     /* 05 */ "Frequency Mismatch",
 538     /* 06 */ "Bus Mode Mismatch",
 539     /* 07 */ "Power Fault",
 540     /* 08 */ "Capabilities Check",
 541     /* 09 */ "Device PLD Check",
 542     /* 10 */ "Reserved",
 543     /* 11 */ "System Locality Update",
 544     /* 12 */ "Shutdown Request"
 545 };
 546 
 547 const char *
 548 AcpiUtGetNotifyName (
 549     UINT32                  NotifyValue)
 550 {
 551 
 552     if (NotifyValue <= ACPI_NOTIFY_MAX)
 553     {
 554         return (AcpiGbl_NotifyValueNames[NotifyValue]);
 555     }
 556     else if (NotifyValue <= ACPI_MAX_SYS_NOTIFY)
 557     {
 558         return ("Reserved");
 559     }
 560     else if (NotifyValue <= ACPI_MAX_DEVICE_SPECIFIC_NOTIFY)
 561     {
 562         return ("Device Specific");
 563     }
 564     else
 565     {
 566         return ("Hardware Specific");
 567     }
 568 }
 569 #endif
 570 
 571 
 572 /*******************************************************************************
 573  *
 574  * FUNCTION:    AcpiUtValidObjectType
 575  *
 576  * PARAMETERS:  Type            - Object type to be validated
 577  *
 578  * RETURN:      TRUE if valid object type, FALSE otherwise
 579  *
 580  * DESCRIPTION: Validate an object type
 581  *
 582  ******************************************************************************/
 583 
 584 BOOLEAN
 585 AcpiUtValidObjectType (
 586     ACPI_OBJECT_TYPE        Type)
 587 {
 588 
 589     if (Type > ACPI_TYPE_LOCAL_MAX)
 590     {
 591         /* Note: Assumes all TYPEs are contiguous (external/local) */
 592 
 593         return (FALSE);
 594     }
 595 
 596     return (TRUE);
 597 }