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