1 /******************************************************************************
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2014, Intel Corp.
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
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.
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.
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.
48 extern const UINT8 AcpiGbl_ResourceAmlSizes[];
49 extern const UINT8 AcpiGbl_ResourceAmlSerialBusSizes[];
51 /* Strings used by the disassembler and debugger resource dump routines */
53 #if defined(ACPI_DEBUG_OUTPUT) || defined (ACPI_DISASSEMBLER) || defined (ACPI_DEBUGGER)
55 extern const char *AcpiGbl_BmDecode[];
56 extern const char *AcpiGbl_ConfigDecode[];
57 extern const char *AcpiGbl_ConsumeDecode[];
58 extern const char *AcpiGbl_DecDecode[];
59 extern const char *AcpiGbl_HeDecode[];
60 extern const char *AcpiGbl_IoDecode[];
61 extern const char *AcpiGbl_LlDecode[];
62 extern const char *AcpiGbl_MaxDecode[];
63 extern const char *AcpiGbl_MemDecode[];
64 extern const char *AcpiGbl_MinDecode[];
65 extern const char *AcpiGbl_MtpDecode[];
66 extern const char *AcpiGbl_RngDecode[];
67 extern const char *AcpiGbl_RwDecode[];
68 extern const char *AcpiGbl_ShrDecode[];
69 extern const char *AcpiGbl_SizDecode[];
70 extern const char *AcpiGbl_TrsDecode[];
71 extern const char *AcpiGbl_TtpDecode[];
72 extern const char *AcpiGbl_TypDecode[];
73 extern const char *AcpiGbl_PpcDecode[];
74 extern const char *AcpiGbl_IorDecode[];
75 extern const char *AcpiGbl_DtsDecode[];
76 extern const char *AcpiGbl_CtDecode[];
77 extern const char *AcpiGbl_SbtDecode[];
78 extern const char *AcpiGbl_AmDecode[];
79 extern const char *AcpiGbl_SmDecode[];
80 extern const char *AcpiGbl_WmDecode[];
81 extern const char *AcpiGbl_CphDecode[];
82 extern const char *AcpiGbl_CpoDecode[];
83 extern const char *AcpiGbl_DpDecode[];
84 extern const char *AcpiGbl_EdDecode[];
85 extern const char *AcpiGbl_BpbDecode[];
86 extern const char *AcpiGbl_SbDecode[];
87 extern const char *AcpiGbl_FcDecode[];
88 extern const char *AcpiGbl_PtDecode[];
92 * For the iASL compiler case, the output is redirected to stderr so that
93 * any of the various ACPI errors and warnings do not appear in the output
94 * files, for either the compiler or disassembler portions of the tool.
96 #ifdef ACPI_ASL_COMPILER
100 #define ACPI_MSG_REDIRECT_BEGIN \
101 FILE *OutputFile = AcpiGbl_OutputFile; \
102 AcpiOsRedirectOutput (stderr);
104 #define ACPI_MSG_REDIRECT_END \
105 AcpiOsRedirectOutput (OutputFile);
109 * non-iASL case - no redirection, nothing to do
111 #define ACPI_MSG_REDIRECT_BEGIN
112 #define ACPI_MSG_REDIRECT_END
116 * Common error message prefixes
118 #define ACPI_MSG_ERROR "ACPI Error: "
119 #define ACPI_MSG_EXCEPTION "ACPI Exception: "
120 #define ACPI_MSG_WARNING "ACPI Warning: "
121 #define ACPI_MSG_INFO "ACPI: "
123 #define ACPI_MSG_BIOS_ERROR "ACPI BIOS Error (bug): "
124 #define ACPI_MSG_BIOS_WARNING "ACPI BIOS Warning (bug): "
127 * Common message suffix
129 #define ACPI_MSG_SUFFIX \
130 AcpiOsPrintf (" (%8.8X/%s-%u)\n", ACPI_CA_VERSION, ModuleName, LineNumber)
133 /* Types for Resource descriptor entries */
135 #define ACPI_INVALID_RESOURCE 0
136 #define ACPI_FIXED_LENGTH 1
137 #define ACPI_VARIABLE_LENGTH 2
138 #define ACPI_SMALL_VARIABLE_LENGTH 3
141 ACPI_STATUS (*ACPI_WALK_AML_CALLBACK) (
149 ACPI_STATUS (*ACPI_PKG_CALLBACK) (
151 ACPI_OPERAND_OBJECT *SourceObject,
152 ACPI_GENERIC_STATE *State,
155 typedef struct acpi_pkg_info
164 /* Object reference counts */
166 #define REF_INCREMENT (UINT16) 0
167 #define REF_DECREMENT (UINT16) 1
169 /* AcpiUtDumpBuffer */
171 #define DB_BYTE_DISPLAY 1
172 #define DB_WORD_DISPLAY 2
173 #define DB_DWORD_DISPLAY 4
174 #define DB_QWORD_DISPLAY 8
177 * utglobal - Global data structures and procedures
183 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
190 AcpiUtGetNotifyName (
192 ACPI_OBJECT_TYPE Type);
197 ACPI_OBJECT_TYPE Type);
204 AcpiUtGetDescriptorName (
208 AcpiUtGetReferenceName (
209 ACPI_OPERAND_OBJECT *Object);
212 AcpiUtGetObjectTypeName (
213 ACPI_OPERAND_OBJECT *ObjDesc);
216 AcpiUtGetRegionName (
224 AcpiUtHexToAsciiChar (
229 AcpiUtAsciiCharToHex (
233 AcpiUtValidObjectType (
234 ACPI_OBJECT_TYPE Type);
238 * utinit - miscellaneous initialization and shutdown
241 AcpiUtHardwareInitialize (
245 AcpiUtSubsystemShutdown (
250 * utclib - Local implementations of C library functions
252 #ifndef ACPI_USE_SYSTEM_CLIBRARY
266 const char *SrcString);
271 const char *SrcString,
289 const char *String2);
294 const char *SrcString);
299 const char *SrcString,
333 extern const UINT8 _acpi_ctype[];
335 #define _ACPI_XA 0x00 /* extra alphabetic - not supported */
336 #define _ACPI_XS 0x40 /* extra space */
337 #define _ACPI_BB 0x00 /* BEL, BS, etc. - not supported */
338 #define _ACPI_CN 0x20 /* CR, FF, HT, NL, VT */
339 #define _ACPI_DI 0x04 /* '0'-'9' */
340 #define _ACPI_LO 0x02 /* 'a'-'z' */
341 #define _ACPI_PU 0x10 /* punctuation */
342 #define _ACPI_SP 0x08 /* space */
343 #define _ACPI_UP 0x01 /* 'A'-'Z' */
344 #define _ACPI_XD 0x80 /* '0'-'9', 'A'-'F', 'a'-'f' */
346 #define ACPI_IS_DIGIT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_DI))
347 #define ACPI_IS_SPACE(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_SP))
348 #define ACPI_IS_XDIGIT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_XD))
349 #define ACPI_IS_UPPER(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_UP))
350 #define ACPI_IS_LOWER(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO))
351 #define ACPI_IS_PRINT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP | _ACPI_DI | _ACPI_XS | _ACPI_PU))
352 #define ACPI_IS_ALPHA(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP))
354 #endif /* !ACPI_USE_SYSTEM_CLIBRARY */
356 #define ACPI_IS_ASCII(c) ((c) < 0x80)
360 * utcopy - Object construction and conversion interfaces
363 AcpiUtBuildSimpleObject(
364 ACPI_OPERAND_OBJECT *Obj,
365 ACPI_OBJECT *UserObj,
367 UINT32 *BufferSpaceUsed);
370 AcpiUtBuildPackageObject (
371 ACPI_OPERAND_OBJECT *Obj,
376 AcpiUtCopyIobjectToEobject (
377 ACPI_OPERAND_OBJECT *Obj,
378 ACPI_BUFFER *RetBuffer);
381 AcpiUtCopyEobjectToIobject (
383 ACPI_OPERAND_OBJECT **InternalObj);
386 AcpiUtCopyISimpleToIsimple (
387 ACPI_OPERAND_OBJECT *SourceObj,
388 ACPI_OPERAND_OBJECT *DestObj);
391 AcpiUtCopyIobjectToIobject (
392 ACPI_OPERAND_OBJECT *SourceDesc,
393 ACPI_OPERAND_OBJECT **DestDesc,
394 ACPI_WALK_STATE *WalkState);
398 * utcreate - Object creation
401 AcpiUtUpdateObjectReference (
402 ACPI_OPERAND_OBJECT *Object,
407 * utdebug - Debug interfaces
410 AcpiUtInitStackPtrTrace (
414 AcpiUtTrackStackPtr (
420 const char *FunctionName,
421 const char *ModuleName,
427 const char *FunctionName,
428 const char *ModuleName,
435 const char *FunctionName,
436 const char *ModuleName,
443 const char *FunctionName,
444 const char *ModuleName,
451 const char *FunctionName,
452 const char *ModuleName,
458 const char *FunctionName,
459 const char *ModuleName,
466 const char *FunctionName,
467 const char *ModuleName,
474 const char *FunctionName,
475 const char *ModuleName,
480 AcpiUtDebugDumpBuffer (
493 #ifdef ACPI_APPLICATION
495 AcpiUtDumpBufferToFile (
514 AcpiUtReportWarning (
519 * utdelete - Object deletion and reference counts
523 ACPI_OPERAND_OBJECT *Object);
526 AcpiUtRemoveReference (
527 ACPI_OPERAND_OBJECT *Object);
530 AcpiUtDeleteInternalPackageObject (
531 ACPI_OPERAND_OBJECT *Object);
534 AcpiUtDeleteInternalSimpleObject (
535 ACPI_OPERAND_OBJECT *Object);
538 AcpiUtDeleteInternalObjectList (
539 ACPI_OPERAND_OBJECT **ObjList);
543 * uteval - object evaluation
546 AcpiUtEvaluateObject (
547 ACPI_NAMESPACE_NODE *PrefixNode,
549 UINT32 ExpectedReturnBtypes,
550 ACPI_OPERAND_OBJECT **ReturnDesc);
553 AcpiUtEvaluateNumericObject (
555 ACPI_NAMESPACE_NODE *DeviceNode,
560 ACPI_NAMESPACE_NODE *DeviceNode,
561 UINT32 *StatusFlags);
564 AcpiUtExecutePowerMethods (
565 ACPI_NAMESPACE_NODE *DeviceNode,
566 const char **MethodNames,
572 * utfileio - file operations
574 #ifdef ACPI_APPLICATION
576 AcpiUtReadTableFromFile (
578 ACPI_TABLE_HEADER **Table);
583 * utids - device ID support
587 ACPI_NAMESPACE_NODE *DeviceNode,
588 ACPI_PNP_DEVICE_ID **ReturnId);
592 ACPI_NAMESPACE_NODE *DeviceNode,
593 ACPI_PNP_DEVICE_ID **ReturnId);
597 ACPI_NAMESPACE_NODE *DeviceNode,
598 ACPI_PNP_DEVICE_ID **ReturnId);
602 ACPI_NAMESPACE_NODE *DeviceNode,
603 ACPI_PNP_DEVICE_ID_LIST **ReturnCidList);
607 * utlock - reader/writer locks
618 AcpiUtAcquireReadLock (
622 AcpiUtReleaseReadLock (
626 AcpiUtAcquireWriteLock (
630 AcpiUtReleaseWriteLock (
635 * utobject - internal object create/delete/cache routines
637 ACPI_OPERAND_OBJECT *
638 AcpiUtCreateInternalObjectDbg (
639 const char *ModuleName,
642 ACPI_OBJECT_TYPE Type);
645 AcpiUtAllocateObjectDescDbg (
646 const char *ModuleName,
650 #define AcpiUtCreateInternalObject(t) AcpiUtCreateInternalObjectDbg (_AcpiModuleName,__LINE__,_COMPONENT,t)
651 #define AcpiUtAllocateObjectDesc() AcpiUtAllocateObjectDescDbg (_AcpiModuleName,__LINE__,_COMPONENT)
654 AcpiUtDeleteObjectDesc (
655 ACPI_OPERAND_OBJECT *Object);
658 AcpiUtValidInternalObject (
661 ACPI_OPERAND_OBJECT *
662 AcpiUtCreatePackageObject (
665 ACPI_OPERAND_OBJECT *
666 AcpiUtCreateIntegerObject (
669 ACPI_OPERAND_OBJECT *
670 AcpiUtCreateBufferObject (
671 ACPI_SIZE BufferSize);
673 ACPI_OPERAND_OBJECT *
674 AcpiUtCreateStringObject (
675 ACPI_SIZE StringSize);
679 ACPI_OPERAND_OBJECT *Obj,
680 ACPI_SIZE *ObjLength);
684 * utosi - Support for the _OSI predefined control method
687 AcpiUtInitializeInterfaces (
691 AcpiUtInterfaceTerminate (
695 AcpiUtInstallInterface (
696 ACPI_STRING InterfaceName);
699 AcpiUtRemoveInterface (
700 ACPI_STRING InterfaceName);
703 AcpiUtUpdateInterfaces (
706 ACPI_INTERFACE_INFO *
708 ACPI_STRING InterfaceName);
711 AcpiUtOsiImplementation (
712 ACPI_WALK_STATE *WalkState);
716 * utpredef - support for predefined names
718 const ACPI_PREDEFINED_INFO *
719 AcpiUtGetNextPredefinedMethod (
720 const ACPI_PREDEFINED_INFO *ThisName);
722 const ACPI_PREDEFINED_INFO *
723 AcpiUtMatchPredefinedMethod (
726 const ACPI_PREDEFINED_INFO *
727 AcpiUtMatchResourceName (
731 AcpiUtDisplayPredefinedMethod (
733 const ACPI_PREDEFINED_INFO *ThisName,
737 AcpiUtGetExpectedReturnTypes (
739 UINT32 ExpectedBtypes);
742 AcpiUtGetResourceBitWidth (
748 * utstate - Generic state creation/cache routines
751 AcpiUtPushGenericState (
752 ACPI_GENERIC_STATE **ListHead,
753 ACPI_GENERIC_STATE *State);
756 AcpiUtPopGenericState (
757 ACPI_GENERIC_STATE **ListHead);
761 AcpiUtCreateGenericState (
765 AcpiUtCreateThreadState (
769 AcpiUtCreateUpdateState (
770 ACPI_OPERAND_OBJECT *Object,
774 AcpiUtCreatePkgState (
775 void *InternalObject,
776 void *ExternalObject,
780 AcpiUtCreateUpdateStateAndPush (
781 ACPI_OPERAND_OBJECT *Object,
783 ACPI_GENERIC_STATE **StateList);
786 AcpiUtCreatePkgStateAndPush (
787 void *InternalObject,
788 void *ExternalObject,
790 ACPI_GENERIC_STATE **StateList);
793 AcpiUtCreateControlState (
797 AcpiUtDeleteGenericState (
798 ACPI_GENERIC_STATE *State);
809 UINT64 *OutRemainder);
816 UINT32 *OutRemainder);
822 const ACPI_EXCEPTION_INFO *
823 AcpiUtValidateException (
827 AcpiUtIsPciRootBridge (
832 ACPI_TABLE_HEADER *Table);
835 AcpiUtWalkPackageTree (
836 ACPI_OPERAND_OBJECT *SourceObject,
838 ACPI_PKG_CALLBACK WalkCallback,
842 /* Values for Base above (16=Hex, 10=Decimal) */
844 #define ACPI_ANY_BASE 0
847 AcpiUtDwordByteSwap (
851 AcpiUtSetIntegerWidth (
854 #ifdef ACPI_DEBUG_OUTPUT
856 AcpiUtDisplayInitPathname (
858 ACPI_NAMESPACE_NODE *ObjHandle,
864 * utownerid - Support for Table/Method Owner IDs
867 AcpiUtAllocateOwnerId (
868 ACPI_OWNER_ID *OwnerId);
871 AcpiUtReleaseOwnerId (
872 ACPI_OWNER_ID *OwnerId);
879 AcpiUtWalkAmlResources (
880 ACPI_WALK_STATE *WalkState,
883 ACPI_WALK_AML_CALLBACK UserFunction,
887 AcpiUtValidateResource (
888 ACPI_WALK_STATE *WalkState,
893 AcpiUtGetDescriptorLength (
897 AcpiUtGetResourceLength (
901 AcpiUtGetResourceHeaderLength (
905 AcpiUtGetResourceType (
909 AcpiUtGetResourceEndTag (
910 ACPI_OPERAND_OBJECT *ObjDesc,
915 * utstring - String and character utilities
942 UtConvertBackslashes (
946 AcpiUtValidAcpiName (
950 AcpiUtValidAcpiChar (
958 #if defined (ACPI_DEBUGGER) || defined (ACPI_APPLICATION)
977 ACPI_SIZE MaxTransferLength);
983 * utmutex - mutex support
986 AcpiUtMutexInitialize (
990 AcpiUtMutexTerminate (
995 ACPI_MUTEX_HANDLE MutexId);
999 ACPI_MUTEX_HANDLE MutexId);
1003 * utalloc - memory allocation and object caching
1006 AcpiUtCreateCaches (
1010 AcpiUtDeleteCaches (
1014 AcpiUtValidateBuffer (
1015 ACPI_BUFFER *Buffer);
1018 AcpiUtInitializeBuffer (
1019 ACPI_BUFFER *Buffer,
1020 ACPI_SIZE RequiredLength);
1022 #ifdef ACPI_DBG_TRACK_ALLOCATIONS
1024 AcpiUtAllocateAndTrack (
1031 AcpiUtAllocateZeroedAndTrack (
1038 AcpiUtFreeAndTrack (
1045 AcpiUtDumpAllocationInfo (
1049 AcpiUtDumpAllocations (
1051 const char *Module);
1057 ACPI_MEMORY_LIST **ReturnCache);
1059 #endif /* ACPI_DBG_TRACK_ALLOCATIONS */
1062 * utaddress - address range check
1065 AcpiUtAddAddressRange (
1066 ACPI_ADR_SPACE_TYPE SpaceId,
1067 ACPI_PHYSICAL_ADDRESS Address,
1069 ACPI_NAMESPACE_NODE *RegionNode);
1072 AcpiUtRemoveAddressRange (
1073 ACPI_ADR_SPACE_TYPE SpaceId,
1074 ACPI_NAMESPACE_NODE *RegionNode);
1077 AcpiUtCheckAddressRange (
1078 ACPI_ADR_SPACE_TYPE SpaceId,
1079 ACPI_PHYSICAL_ADDRESS Address,
1084 AcpiUtDeleteAddressLists (
1088 * utxferror - various error/warning output functions
1090 void ACPI_INTERNAL_VAR_XFACE
1091 AcpiUtPredefinedWarning (
1092 const char *ModuleName,
1099 void ACPI_INTERNAL_VAR_XFACE
1100 AcpiUtPredefinedInfo (
1101 const char *ModuleName,
1108 void ACPI_INTERNAL_VAR_XFACE
1109 AcpiUtPredefinedBiosError (
1110 const char *ModuleName,
1118 AcpiUtNamespaceError (
1119 const char *ModuleName,
1121 const char *InternalName,
1122 ACPI_STATUS LookupStatus);
1126 const char *ModuleName,
1128 const char *Message,
1129 ACPI_NAMESPACE_NODE *Node,
1131 ACPI_STATUS LookupStatus);
1134 * Utility functions for ACPI names and IDs
1136 const AH_PREDEFINED_NAME *
1137 AcpiAhMatchPredefinedName (
1140 const AH_DEVICE_ID *
1141 AcpiAhMatchHardwareId (
1149 * utprint - printf/vprintf output functions
1175 #ifdef ACPI_APPLICATION
1190 * utuuid -- UUID support functions
1193 AcpiUtConvertStringToUuid (
1197 #endif /* _ACUTILS_H */