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