1 /******************************************************************************
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2019, 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
[];
89 extern const char *AcpiGbl_PtypDecode
[];
93 * For the iASL compiler case, the output is redirected to stderr so that
94 * any of the various ACPI errors and warnings do not appear in the output
95 * files, for either the compiler or disassembler portions of the tool.
97 #ifdef ACPI_ASL_COMPILER
101 #define ACPI_MSG_REDIRECT_BEGIN \
102 FILE *OutputFile = AcpiGbl_OutputFile; \
103 AcpiOsRedirectOutput (stderr);
105 #define ACPI_MSG_REDIRECT_END \
106 AcpiOsRedirectOutput (OutputFile);
110 * non-iASL case - no redirection, nothing to do
112 #define ACPI_MSG_REDIRECT_BEGIN
113 #define ACPI_MSG_REDIRECT_END
117 * Common error message prefixes
119 #ifndef ACPI_MSG_ERROR
120 #define ACPI_MSG_ERROR "ACPI Error: "
122 #ifndef ACPI_MSG_WARNING
123 #define ACPI_MSG_WARNING "ACPI Warning: "
125 #ifndef ACPI_MSG_INFO
126 #define ACPI_MSG_INFO "ACPI: "
129 #ifndef ACPI_MSG_BIOS_ERROR
130 #define ACPI_MSG_BIOS_ERROR "Firmware Error (ACPI): "
132 #ifndef ACPI_MSG_BIOS_WARNING
133 #define ACPI_MSG_BIOS_WARNING "Firmware Warning (ACPI): "
137 * Common message suffix
139 #define ACPI_MSG_SUFFIX \
140 AcpiOsPrintf (" (%8.8X/%s-%u)\n", ACPI_CA_VERSION, ModuleName, LineNumber)
142 /* Flags to indicate implicit or explicit string-to-integer conversion */
144 #define ACPI_IMPLICIT_CONVERSION TRUE
145 #define ACPI_NO_IMPLICIT_CONVERSION FALSE
147 /* Types for Resource descriptor entries */
149 #define ACPI_INVALID_RESOURCE 0
150 #define ACPI_FIXED_LENGTH 1
151 #define ACPI_VARIABLE_LENGTH 2
152 #define ACPI_SMALL_VARIABLE_LENGTH 3
155 ACPI_STATUS (*ACPI_WALK_AML_CALLBACK
) (
163 ACPI_STATUS (*ACPI_PKG_CALLBACK
) (
165 ACPI_OPERAND_OBJECT
*SourceObject
,
166 ACPI_GENERIC_STATE
*State
,
169 typedef struct acpi_pkg_info
178 /* Object reference counts */
180 #define REF_INCREMENT (UINT16) 0
181 #define REF_DECREMENT (UINT16) 1
183 /* AcpiUtDumpBuffer */
185 #define DB_BYTE_DISPLAY 1
186 #define DB_WORD_DISPLAY 2
187 #define DB_DWORD_DISPLAY 4
188 #define DB_QWORD_DISPLAY 8
192 * utascii - ASCII utilities
199 AcpiUtValidNameChar (
204 AcpiUtCheckAndRepairAscii (
211 * utnonansi - Non-ANSI C library functions
228 * utstrsuppt - string-to-integer conversion support functions
231 AcpiUtConvertOctalString (
233 UINT64
*ReturnValue
);
236 AcpiUtConvertDecimalString (
238 UINT64
*ReturnValuePtr
);
241 AcpiUtConvertHexString (
243 UINT64
*ReturnValuePtr
);
246 AcpiUtRemoveWhitespace (
250 AcpiUtRemoveLeadingZeros (
254 AcpiUtDetectHexPrefix (
258 AcpiUtRemoveHexPrefix (
262 AcpiUtDetectOctalPrefix (
267 * utstrtoul64 - string-to-integer conversion functions
275 AcpiUtExplicitStrtoul64 (
279 AcpiUtImplicitStrtoul64 (
284 * utglobal - Global data structures and procedures
294 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
297 AcpiUtGetNotifyName (
299 ACPI_OBJECT_TYPE Type
);
304 ACPI_OBJECT_TYPE Type
);
311 AcpiUtGetDescriptorName (
315 AcpiUtGetReferenceName (
316 ACPI_OPERAND_OBJECT
*Object
);
319 AcpiUtGetObjectTypeName (
320 ACPI_OPERAND_OBJECT
*ObjDesc
);
323 AcpiUtGetRegionName (
331 AcpiUtGetArgumentTypeName (
335 AcpiUtHexToAsciiChar (
340 AcpiUtAsciiToHexByte (
345 AcpiUtAsciiCharToHex (
349 AcpiUtValidObjectType (
350 ACPI_OBJECT_TYPE Type
);
354 * utinit - miscellaneous initialization and shutdown
357 AcpiUtHardwareInitialize (
361 AcpiUtSubsystemShutdown (
366 * utcopy - Object construction and conversion interfaces
369 AcpiUtBuildSimpleObject(
370 ACPI_OPERAND_OBJECT
*Obj
,
371 ACPI_OBJECT
*UserObj
,
373 UINT32
*BufferSpaceUsed
);
376 AcpiUtBuildPackageObject (
377 ACPI_OPERAND_OBJECT
*Obj
,
382 AcpiUtCopyIobjectToEobject (
383 ACPI_OPERAND_OBJECT
*Obj
,
384 ACPI_BUFFER
*RetBuffer
);
387 AcpiUtCopyEobjectToIobject (
389 ACPI_OPERAND_OBJECT
**InternalObj
);
392 AcpiUtCopyISimpleToIsimple (
393 ACPI_OPERAND_OBJECT
*SourceObj
,
394 ACPI_OPERAND_OBJECT
*DestObj
);
397 AcpiUtCopyIobjectToIobject (
398 ACPI_OPERAND_OBJECT
*SourceDesc
,
399 ACPI_OPERAND_OBJECT
**DestDesc
,
400 ACPI_WALK_STATE
*WalkState
);
404 * utcreate - Object creation
407 AcpiUtUpdateObjectReference (
408 ACPI_OPERAND_OBJECT
*Object
,
413 * utdebug - Debug interfaces
416 AcpiUtInitStackPtrTrace (
420 AcpiUtTrackStackPtr (
426 const char *FunctionName
,
427 const char *ModuleName
,
433 const char *FunctionName
,
434 const char *ModuleName
,
436 const void *Pointer
);
441 const char *FunctionName
,
442 const char *ModuleName
,
449 const char *FunctionName
,
450 const char *ModuleName
,
457 const char *FunctionName
,
458 const char *ModuleName
,
464 const char *FunctionName
,
465 const char *ModuleName
,
472 const char *FunctionName
,
473 const char *ModuleName
,
480 const char *FunctionName
,
481 const char *ModuleName
,
488 const char *FunctionName
,
489 const char *ModuleName
,
494 AcpiUtDebugDumpBuffer (
507 #ifdef ACPI_APPLICATION
509 AcpiUtDumpBufferToFile (
528 AcpiUtReportWarning (
534 * utdelete - Object deletion and reference counts
538 ACPI_OPERAND_OBJECT
*Object
);
541 AcpiUtRemoveReference (
542 ACPI_OPERAND_OBJECT
*Object
);
545 AcpiUtDeleteInternalPackageObject (
546 ACPI_OPERAND_OBJECT
*Object
);
549 AcpiUtDeleteInternalSimpleObject (
550 ACPI_OPERAND_OBJECT
*Object
);
553 AcpiUtDeleteInternalObjectList (
554 ACPI_OPERAND_OBJECT
**ObjList
);
558 * uteval - object evaluation
561 AcpiUtEvaluateObject (
562 ACPI_NAMESPACE_NODE
*PrefixNode
,
564 UINT32 ExpectedReturnBtypes
,
565 ACPI_OPERAND_OBJECT
**ReturnDesc
);
568 AcpiUtEvaluateNumericObject (
569 const char *ObjectName
,
570 ACPI_NAMESPACE_NODE
*DeviceNode
,
575 ACPI_NAMESPACE_NODE
*DeviceNode
,
576 UINT32
*StatusFlags
);
579 AcpiUtExecutePowerMethods (
580 ACPI_NAMESPACE_NODE
*DeviceNode
,
581 const char **MethodNames
,
587 * utids - device ID support
591 ACPI_NAMESPACE_NODE
*DeviceNode
,
592 ACPI_PNP_DEVICE_ID
**ReturnId
);
596 ACPI_NAMESPACE_NODE
*DeviceNode
,
597 ACPI_PNP_DEVICE_ID
**ReturnId
);
601 ACPI_NAMESPACE_NODE
*DeviceNode
,
602 ACPI_PNP_DEVICE_ID_LIST
**ReturnCidList
);
606 ACPI_NAMESPACE_NODE
*DeviceNode
,
607 ACPI_PNP_DEVICE_ID
**ReturnId
);
611 * utlock - reader/writer locks
622 AcpiUtAcquireReadLock (
626 AcpiUtReleaseReadLock (
630 AcpiUtAcquireWriteLock (
634 AcpiUtReleaseWriteLock (
639 * utobject - internal object create/delete/cache routines
641 ACPI_OPERAND_OBJECT
*
642 AcpiUtCreateInternalObjectDbg (
643 const char *ModuleName
,
646 ACPI_OBJECT_TYPE Type
);
649 AcpiUtAllocateObjectDescDbg (
650 const char *ModuleName
,
654 #define AcpiUtCreateInternalObject(t) AcpiUtCreateInternalObjectDbg (_AcpiModuleName,__LINE__,_COMPONENT,t)
655 #define AcpiUtAllocateObjectDesc() AcpiUtAllocateObjectDescDbg (_AcpiModuleName,__LINE__,_COMPONENT)
658 AcpiUtDeleteObjectDesc (
659 ACPI_OPERAND_OBJECT
*Object
);
662 AcpiUtValidInternalObject (
665 ACPI_OPERAND_OBJECT
*
666 AcpiUtCreatePackageObject (
669 ACPI_OPERAND_OBJECT
*
670 AcpiUtCreateIntegerObject (
673 ACPI_OPERAND_OBJECT
*
674 AcpiUtCreateBufferObject (
675 ACPI_SIZE BufferSize
);
677 ACPI_OPERAND_OBJECT
*
678 AcpiUtCreateStringObject (
679 ACPI_SIZE StringSize
);
683 ACPI_OPERAND_OBJECT
*Obj
,
684 ACPI_SIZE
*ObjLength
);
688 * utosi - Support for the _OSI predefined control method
691 AcpiUtInitializeInterfaces (
695 AcpiUtInterfaceTerminate (
699 AcpiUtInstallInterface (
700 ACPI_STRING InterfaceName
);
703 AcpiUtRemoveInterface (
704 ACPI_STRING InterfaceName
);
707 AcpiUtUpdateInterfaces (
710 ACPI_INTERFACE_INFO
*
712 ACPI_STRING InterfaceName
);
715 AcpiUtOsiImplementation (
716 ACPI_WALK_STATE
*WalkState
);
720 * utpredef - support for predefined names
722 const ACPI_PREDEFINED_INFO
*
723 AcpiUtGetNextPredefinedMethod (
724 const ACPI_PREDEFINED_INFO
*ThisName
);
726 const ACPI_PREDEFINED_INFO
*
727 AcpiUtMatchPredefinedMethod (
731 AcpiUtGetExpectedReturnTypes (
733 UINT32 ExpectedBtypes
);
735 #if (defined ACPI_ASL_COMPILER || defined ACPI_HELP_APP)
736 const ACPI_PREDEFINED_INFO
*
737 AcpiUtMatchResourceName (
741 AcpiUtDisplayPredefinedMethod (
743 const ACPI_PREDEFINED_INFO
*ThisName
,
747 AcpiUtGetResourceBitWidth (
754 * utstate - Generic state creation/cache routines
757 AcpiUtPushGenericState (
758 ACPI_GENERIC_STATE
**ListHead
,
759 ACPI_GENERIC_STATE
*State
);
762 AcpiUtPopGenericState (
763 ACPI_GENERIC_STATE
**ListHead
);
767 AcpiUtCreateGenericState (
771 AcpiUtCreateThreadState (
775 AcpiUtCreateUpdateState (
776 ACPI_OPERAND_OBJECT
*Object
,
780 AcpiUtCreatePkgState (
781 void *InternalObject
,
782 void *ExternalObject
,
786 AcpiUtCreateUpdateStateAndPush (
787 ACPI_OPERAND_OBJECT
*Object
,
789 ACPI_GENERIC_STATE
**StateList
);
792 AcpiUtCreateControlState (
796 AcpiUtDeleteGenericState (
797 ACPI_GENERIC_STATE
*State
);
808 UINT64
*OutRemainder
);
815 UINT32
*OutRemainder
);
818 AcpiUtShortMultiply (
819 UINT64 InMultiplicand
,
824 AcpiUtShortShiftLeft (
830 AcpiUtShortShiftRight (
839 const ACPI_EXCEPTION_INFO
*
840 AcpiUtValidateException (
844 AcpiUtIsPciRootBridge (
847 #if (defined ACPI_ASL_COMPILER || defined ACPI_EXEC_APP || defined ACPI_NAMES_APP)
850 ACPI_TABLE_HEADER
*Table
);
854 AcpiUtWalkPackageTree (
855 ACPI_OPERAND_OBJECT
*SourceObject
,
857 ACPI_PKG_CALLBACK WalkCallback
,
860 /* Values for Base above (16=Hex, 10=Decimal) */
862 #define ACPI_ANY_BASE 0
866 AcpiUtDwordByteSwap (
870 AcpiUtSetIntegerWidth (
873 #ifdef ACPI_DEBUG_OUTPUT
875 AcpiUtDisplayInitPathname (
877 ACPI_NAMESPACE_NODE
*ObjHandle
,
883 * utownerid - Support for Table/Method Owner IDs
886 AcpiUtAllocateOwnerId (
887 ACPI_OWNER_ID
*OwnerId
);
890 AcpiUtReleaseOwnerId (
891 ACPI_OWNER_ID
*OwnerId
);
898 AcpiUtWalkAmlResources (
899 ACPI_WALK_STATE
*WalkState
,
902 ACPI_WALK_AML_CALLBACK UserFunction
,
906 AcpiUtValidateResource (
907 ACPI_WALK_STATE
*WalkState
,
912 AcpiUtGetDescriptorLength (
916 AcpiUtGetResourceLength (
920 AcpiUtGetResourceHeaderLength (
924 AcpiUtGetResourceType (
928 AcpiUtGetResourceEndTag (
929 ACPI_OPERAND_OBJECT
*ObjDesc
,
934 * utstring - String and character utilities
941 #if defined ACPI_ASL_COMPILER || defined ACPI_EXEC_APP
943 UtConvertBackslashes (
951 #if defined (ACPI_DEBUGGER) || defined (ACPI_APPLICATION) || defined (ACPI_DEBUG_OUTPUT)
975 ACPI_SIZE MaxTransferLength
);
980 * utmutex - mutex support
983 AcpiUtMutexInitialize (
987 AcpiUtMutexTerminate (
992 ACPI_MUTEX_HANDLE MutexId
);
996 ACPI_MUTEX_HANDLE MutexId
);
1000 * utalloc - memory allocation and object caching
1003 AcpiUtCreateCaches (
1007 AcpiUtDeleteCaches (
1011 AcpiUtValidateBuffer (
1012 ACPI_BUFFER
*Buffer
);
1015 AcpiUtInitializeBuffer (
1016 ACPI_BUFFER
*Buffer
,
1017 ACPI_SIZE RequiredLength
);
1019 #ifdef ACPI_DBG_TRACK_ALLOCATIONS
1021 AcpiUtAllocateAndTrack (
1028 AcpiUtAllocateZeroedAndTrack (
1035 AcpiUtFreeAndTrack (
1042 AcpiUtDumpAllocationInfo (
1046 AcpiUtDumpAllocations (
1048 const char *Module
);
1052 const char *ListName
,
1054 ACPI_MEMORY_LIST
**ReturnCache
);
1056 #endif /* ACPI_DBG_TRACK_ALLOCATIONS */
1060 * utaddress - address range check
1063 AcpiUtAddAddressRange (
1064 ACPI_ADR_SPACE_TYPE SpaceId
,
1065 ACPI_PHYSICAL_ADDRESS Address
,
1067 ACPI_NAMESPACE_NODE
*RegionNode
);
1070 AcpiUtRemoveAddressRange (
1071 ACPI_ADR_SPACE_TYPE SpaceId
,
1072 ACPI_NAMESPACE_NODE
*RegionNode
);
1075 AcpiUtCheckAddressRange (
1076 ACPI_ADR_SPACE_TYPE SpaceId
,
1077 ACPI_PHYSICAL_ADDRESS Address
,
1082 AcpiUtDeleteAddressLists (
1087 * utxferror - various error/warning output functions
1090 void ACPI_INTERNAL_VAR_XFACE
1091 AcpiUtPredefinedWarning (
1092 const char *ModuleName
,
1100 void ACPI_INTERNAL_VAR_XFACE
1101 AcpiUtPredefinedInfo (
1102 const char *ModuleName
,
1110 void ACPI_INTERNAL_VAR_XFACE
1111 AcpiUtPredefinedBiosError (
1112 const char *ModuleName
,
1120 AcpiUtPrefixedNamespaceError (
1121 const char *ModuleName
,
1123 ACPI_GENERIC_STATE
*PrefixScope
,
1124 const char *InternalName
,
1125 ACPI_STATUS LookupStatus
);
1129 const char *ModuleName
,
1131 const char *Message
,
1132 ACPI_NAMESPACE_NODE
*Node
,
1134 ACPI_STATUS LookupStatus
);
1138 * Utility functions for ACPI names and IDs
1140 const AH_PREDEFINED_NAME
*
1141 AcpiAhMatchPredefinedName (
1144 const AH_DEVICE_ID
*
1145 AcpiAhMatchHardwareId (
1154 * utuuid -- UUID support functions
1156 #if (defined ACPI_ASL_COMPILER || defined ACPI_EXEC_APP || defined ACPI_HELP_APP)
1158 AcpiUtConvertStringToUuid (
1163 #endif /* _ACUTILS_H */