1 /******************************************************************************
2  *
3  * Module Name: utdecode - Utility decoding routines (value-to-string)
4  *
5  *****************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2014, 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:    AcpiUtGetRegionName
97  *
98  * PARAMETERS:  Space ID            - ID for the region
99  *
100  * RETURN:      Decoded region SpaceId name
101  *
102  * DESCRIPTION: Translate a Space ID into a name string (Debug only)
103  *
104  ******************************************************************************/
105 
106 /* Region type decoding */
107 
108 const char        *AcpiGbl_RegionTypes[ACPI_NUM_PREDEFINED_REGIONS] =
109 {
110     "SystemMemory",     /* 0x00 */
111     "SystemIO",         /* 0x01 */
112     "PCI_Config",       /* 0x02 */
113     "EmbeddedControl",  /* 0x03 */
114     "SMBus",            /* 0x04 */
115     "SystemCMOS",       /* 0x05 */
116     "PCIBARTarget",     /* 0x06 */
117     "IPMI",             /* 0x07 */
118     "GeneralPurposeIo", /* 0x08 */
119     "GenericSerialBus", /* 0x09 */
120     "PCC"               /* 0x0A */
121 };
122 
123 
124 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 (ACPI_CAST_PTR (char, 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 char *
175 AcpiUtGetEventName (
176     UINT32                  EventId)
177 {
178 
179     if (EventId > ACPI_EVENT_MAX)
180     {
181         return ("InvalidEventID");
182     }
183 
184     return (ACPI_CAST_PTR (char, 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 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 char *
249 AcpiUtGetTypeName (
250     ACPI_OBJECT_TYPE        Type)
251 {
252 
253     if (Type > ACPI_TYPE_INVALID)
254     {
255         return (ACPI_CAST_PTR (char, AcpiGbl_BadType));
256     }
257 
258     return (ACPI_CAST_PTR (char, AcpiGbl_NsTypeNames[Type]));
259 }
260 
261 
262 char *
263 AcpiUtGetObjectTypeName (
264     ACPI_OPERAND_OBJECT     *ObjDesc)
265 {
266 
267     if (!ObjDesc)
268     {
269         return ("[NULL Object Descriptor]");
270     }
271 
272     return (AcpiUtGetTypeName (ObjDesc->Common.Type));
273 }
274 
275 
276 /*******************************************************************************
277  *
278  * FUNCTION:    AcpiUtGetNodeName
279  *
280  * PARAMETERS:  Object               - A namespace node
281  *
282  * RETURN:      ASCII name of the node
283  *
284  * DESCRIPTION: Validate the node and return the node's ACPI name.
285  *
286  ******************************************************************************/
287 
288 char *
289 AcpiUtGetNodeName (
290     void                    *Object)
291 {
292     ACPI_NAMESPACE_NODE     *Node = (ACPI_NAMESPACE_NODE *) Object;
293 
294 
295     /* Must return a string of exactly 4 characters == ACPI_NAME_SIZE */
296 
297     if (!Object)
298     {
299         return ("NULL");
300     }
301 
302     /* Check for Root node */
303 
304     if ((Object == ACPI_ROOT_OBJECT) ||
305         (Object == AcpiGbl_RootNode))
306     {
307         return ("\"\\\" ");
308     }
309 
310     /* Descriptor must be a namespace node */
311 
312     if (ACPI_GET_DESCRIPTOR_TYPE (Node) != ACPI_DESC_TYPE_NAMED)
313     {
314         return ("####");
315     }
316 
317     /*
318      * Ensure name is valid. The name was validated/repaired when the node
319      * was created, but make sure it has not been corrupted.
320      */
321     AcpiUtRepairName (Node->Name.Ascii);
322 
323     /* Return the name */
324 
325     return (Node->Name.Ascii);
326 }
327 
328 
329 /*******************************************************************************
330  *
331  * FUNCTION:    AcpiUtGetDescriptorName
332  *
333  * PARAMETERS:  Object               - An ACPI object
334  *
335  * RETURN:      Decoded name of the descriptor type
336  *
337  * DESCRIPTION: Validate object and return the descriptor type
338  *
339  ******************************************************************************/
340 
341 /* Printable names of object descriptor types */
342 
343 static const char           *AcpiGbl_DescTypeNames[] =
344 {
345     /* 00 */ "Not a Descriptor",
346     /* 01 */ "Cached",
347     /* 02 */ "State-Generic",
348     /* 03 */ "State-Update",
349     /* 04 */ "State-Package",
350     /* 05 */ "State-Control",
351     /* 06 */ "State-RootParseScope",
352     /* 07 */ "State-ParseScope",
353     /* 08 */ "State-WalkScope",
354     /* 09 */ "State-Result",
355     /* 10 */ "State-Notify",
356     /* 11 */ "State-Thread",
357     /* 12 */ "Walk",
358     /* 13 */ "Parser",
359     /* 14 */ "Operand",
360     /* 15 */ "Node"
361 };
362 
363 
364 char *
365 AcpiUtGetDescriptorName (
366     void                    *Object)
367 {
368 
369     if (!Object)
370     {
371         return ("NULL OBJECT");
372     }
373 
374     if (ACPI_GET_DESCRIPTOR_TYPE (Object) > ACPI_DESC_TYPE_MAX)
375     {
376         return ("Not a Descriptor");
377     }
378 
379     return (ACPI_CAST_PTR (char,
380         AcpiGbl_DescTypeNames[ACPI_GET_DESCRIPTOR_TYPE (Object)]));
381 
382 }
383 
384 
385 /*******************************************************************************
386  *
387  * FUNCTION:    AcpiUtGetReferenceName
388  *
389  * PARAMETERS:  Object               - An ACPI reference object
390  *
391  * RETURN:      Decoded name of the type of reference
392  *
393  * DESCRIPTION: Decode a reference object sub-type to a string.
394  *
395  ******************************************************************************/
396 
397 /* Printable names of reference object sub-types */
398 
399 static const char           *AcpiGbl_RefClassNames[] =
400 {
401     /* 00 */ "Local",
402     /* 01 */ "Argument",
403     /* 02 */ "RefOf",
404     /* 03 */ "Index",
405     /* 04 */ "DdbHandle",
406     /* 05 */ "Named Object",
407     /* 06 */ "Debug"
408 };
409 
410 const char *
411 AcpiUtGetReferenceName (
412     ACPI_OPERAND_OBJECT     *Object)
413 {
414 
415     if (!Object)
416     {
417         return ("NULL Object");
418     }
419 
420     if (ACPI_GET_DESCRIPTOR_TYPE (Object) != ACPI_DESC_TYPE_OPERAND)
421     {
422         return ("Not an Operand object");
423     }
424 
425     if (Object->Common.Type != ACPI_TYPE_LOCAL_REFERENCE)
426     {
427         return ("Not a Reference object");
428     }
429 
430     if (Object->Reference.Class > ACPI_REFCLASS_MAX)
431     {
432         return ("Unknown Reference class");
433     }
434 
435     return (AcpiGbl_RefClassNames[Object->Reference.Class]);
436 }
437 
438 
439 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
440 /*
441  * Strings and procedures used for debug only
442  */
443 
444 /*******************************************************************************
445  *
446  * FUNCTION:    AcpiUtGetMutexName
447  *
448  * PARAMETERS:  MutexId         - The predefined ID for this mutex.
449  *
450  * RETURN:      Decoded name of the internal mutex
451  *
452  * DESCRIPTION: Translate a mutex ID into a name string (Debug only)
453  *
454  ******************************************************************************/
455 
456 /* Names for internal mutex objects, used for debug output */
457 
458 static char                 *AcpiGbl_MutexNames[ACPI_NUM_MUTEX] =
459 {
460     "ACPI_MTX_Interpreter",
461     "ACPI_MTX_Namespace",
462     "ACPI_MTX_Tables",
463     "ACPI_MTX_Events",
464     "ACPI_MTX_Caches",
465     "ACPI_MTX_Memory",
466     "ACPI_MTX_CommandComplete",
467     "ACPI_MTX_CommandReady"
468 };
469 
470 char *
471 AcpiUtGetMutexName (
472     UINT32                  MutexId)
473 {
474 
475     if (MutexId > ACPI_MAX_MUTEX)
476     {
477         return ("Invalid Mutex ID");
478     }
479 
480     return (AcpiGbl_MutexNames[MutexId]);
481 }
482 
483 
484 /*******************************************************************************
485  *
486  * FUNCTION:    AcpiUtGetNotifyName
487  *
488  * PARAMETERS:  NotifyValue     - Value from the Notify() request
489  *
490  * RETURN:      Decoded name for the notify value
491  *
492  * DESCRIPTION: Translate a Notify Value to a notify namestring.
493  *
494  ******************************************************************************/
495 
496 /* Names for Notify() values, used for debug output */
497 
498 static const char           *AcpiGbl_GenericNotify[ACPI_NOTIFY_MAX + 1] =
499 {
500     /* 00 */ "Bus Check",
501     /* 01 */ "Device Check",
502     /* 02 */ "Device Wake",
503     /* 03 */ "Eject Request",
504     /* 04 */ "Device Check Light",
505     /* 05 */ "Frequency Mismatch",
506     /* 06 */ "Bus Mode Mismatch",
507     /* 07 */ "Power Fault",
508     /* 08 */ "Capabilities Check",
509     /* 09 */ "Device PLD Check",
510     /* 0A */ "Reserved",
511     /* 0B */ "System Locality Update",
512     /* 0C */ "Shutdown Request",
513     /* 0D */ "System Resource Affinity Update"
514 };
515 
516 static const char           *AcpiGbl_DeviceNotify[4] =
517 {
518     /* 80 */ "Status Change",
519     /* 81 */ "Information Change",
520     /* 82 */ "Device-Specific Change",
521     /* 83 */ "Device-Specific Change"
522 };
523 
524 static const char           *AcpiGbl_ProcessorNotify[4] =
525 {
526     /* 80 */ "Performance Capability Change",
527     /* 81 */ "C-State Change",
528     /* 82 */ "Throttling Capability Change",
529     /* 83 */ "Device-Specific Change"
530 };
531 
532 static const char           *AcpiGbl_ThermalNotify[4] =
533 {
534     /* 80 */ "Thermal Status Change",
535     /* 81 */ "Thermal Trip Point Change",
536     /* 82 */ "Thermal Device List Change",
537     /* 83 */ "Thermal Relationship Change"
538 };
539 
540 
541 const char *
542 AcpiUtGetNotifyName (
543     UINT32                  NotifyValue,
544     ACPI_OBJECT_TYPE        Type)
545 {
546 
547     /* 00 - 0D are common to all object types */
548 
549     if (NotifyValue <= ACPI_NOTIFY_MAX)
550     {
551         return (AcpiGbl_GenericNotify[NotifyValue]);
552     }
553 
554     /* 0D - 7F are reserved */
555 
556     if (NotifyValue <= ACPI_MAX_SYS_NOTIFY)
557     {
558         return ("Reserved");
559     }
560 
561     /* 80 - 83 are per-object-type */
562 
563     if (NotifyValue <= 0x83)
564     {
565         switch (Type)
566         {
567         case ACPI_TYPE_ANY:
568         case ACPI_TYPE_DEVICE:
569             return (AcpiGbl_DeviceNotify [NotifyValue - 0x80]);
570 
571         case ACPI_TYPE_PROCESSOR:
572             return (AcpiGbl_ProcessorNotify [NotifyValue - 0x80]);
573 
574         case ACPI_TYPE_THERMAL:
575             return (AcpiGbl_ThermalNotify [NotifyValue - 0x80]);
576 
577         default:
578             return ("Target object type does not support notifies");
579         }
580     }
581 
582     /* 84 - BF are device-specific */
583 
584     if (NotifyValue <= ACPI_MAX_DEVICE_SPECIFIC_NOTIFY)
585     {
586         return ("Device-Specific");
587     }
588 
589     /* C0 and above are hardware-specific */
590 
591     return ("Hardware-Specific");
592 }
593 #endif
594 
595 
596 /*******************************************************************************
597  *
598  * FUNCTION:    AcpiUtValidObjectType
599  *
600  * PARAMETERS:  Type            - Object type to be validated
601  *
602  * RETURN:      TRUE if valid object type, FALSE otherwise
603  *
604  * DESCRIPTION: Validate an object type
605  *
606  ******************************************************************************/
607 
608 BOOLEAN
609 AcpiUtValidObjectType (
610     ACPI_OBJECT_TYPE        Type)
611 {
612 
613     if (Type > ACPI_TYPE_LOCAL_MAX)
614     {
615         /* Note: Assumes all TYPEs are contiguous (external/local) */
616 
617         return (FALSE);
618     }
619 
620     return (TRUE);
621 }
622