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