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