1 /******************************************************************************
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2016, 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 #ifndef ACPI_MSG_ERROR
119 #define ACPI_MSG_ERROR "ACPI Error: "
121 #ifndef ACPI_MSG_EXCEPTION
122 #define ACPI_MSG_EXCEPTION "ACPI Exception: "
124 #ifndef ACPI_MSG_WARNING
125 #define ACPI_MSG_WARNING "ACPI Warning: "
127 #ifndef ACPI_MSG_INFO
128 #define ACPI_MSG_INFO "ACPI: "
131 #ifndef ACPI_MSG_BIOS_ERROR
132 #define ACPI_MSG_BIOS_ERROR "ACPI BIOS Error (bug): "
134 #ifndef ACPI_MSG_BIOS_WARNING
135 #define ACPI_MSG_BIOS_WARNING "ACPI BIOS Warning (bug): "
139 * Common message suffix
141 #define ACPI_MSG_SUFFIX \
142 AcpiOsPrintf (" (%8.8X/%s-%u)\n", ACPI_CA_VERSION, ModuleName, LineNumber)
145 /* Types for Resource descriptor entries */
147 #define ACPI_INVALID_RESOURCE 0
148 #define ACPI_FIXED_LENGTH 1
149 #define ACPI_VARIABLE_LENGTH 2
150 #define ACPI_SMALL_VARIABLE_LENGTH 3
153 ACPI_STATUS (*ACPI_WALK_AML_CALLBACK) (
161 ACPI_STATUS (*ACPI_PKG_CALLBACK) (
163 ACPI_OPERAND_OBJECT *SourceObject,
164 ACPI_GENERIC_STATE *State,
167 typedef struct acpi_pkg_info
176 /* Object reference counts */
178 #define REF_INCREMENT (UINT16) 0
179 #define REF_DECREMENT (UINT16) 1
181 /* AcpiUtDumpBuffer */
183 #define DB_BYTE_DISPLAY 1
184 #define DB_WORD_DISPLAY 2
185 #define DB_DWORD_DISPLAY 4
186 #define DB_QWORD_DISPLAY 8
190 * utascii - ASCII utilities
197 AcpiUtValidNameChar (
202 AcpiUtCheckAndRepairAscii (
209 * utnonansi - Non-ANSI C library functions
231 * Values for Flags above
232 * Note: LIMIT values correspond to AcpiGbl_IntegerByteWidth values (4/8)
234 #define ACPI_STRTOUL_32BIT 0x04 /* 4 bytes */
235 #define ACPI_STRTOUL_64BIT 0x08 /* 8 bytes */
236 #define ACPI_STRTOUL_BASE16 0x10 /* Default: Base10/16 */
240 * utglobal - Global data structures and procedures
246 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
253 AcpiUtGetNotifyName (
255 ACPI_OBJECT_TYPE Type);
260 ACPI_OBJECT_TYPE Type);
267 AcpiUtGetDescriptorName (
271 AcpiUtGetReferenceName (
272 ACPI_OPERAND_OBJECT *Object);
275 AcpiUtGetObjectTypeName (
276 ACPI_OPERAND_OBJECT *ObjDesc);
279 AcpiUtGetRegionName (
287 AcpiUtGetArgumentTypeName (
291 AcpiUtHexToAsciiChar (
296 AcpiUtAsciiToHexByte (
301 AcpiUtAsciiCharToHex (
305 AcpiUtValidObjectType (
306 ACPI_OBJECT_TYPE Type);
310 * utinit - miscellaneous initialization and shutdown
313 AcpiUtHardwareInitialize (
317 AcpiUtSubsystemShutdown (
322 * utcopy - Object construction and conversion interfaces
325 AcpiUtBuildSimpleObject(
326 ACPI_OPERAND_OBJECT *Obj,
327 ACPI_OBJECT *UserObj,
329 UINT32 *BufferSpaceUsed);
332 AcpiUtBuildPackageObject (
333 ACPI_OPERAND_OBJECT *Obj,
338 AcpiUtCopyIobjectToEobject (
339 ACPI_OPERAND_OBJECT *Obj,
340 ACPI_BUFFER *RetBuffer);
343 AcpiUtCopyEobjectToIobject (
345 ACPI_OPERAND_OBJECT **InternalObj);
348 AcpiUtCopyISimpleToIsimple (
349 ACPI_OPERAND_OBJECT *SourceObj,
350 ACPI_OPERAND_OBJECT *DestObj);
353 AcpiUtCopyIobjectToIobject (
354 ACPI_OPERAND_OBJECT *SourceDesc,
355 ACPI_OPERAND_OBJECT **DestDesc,
356 ACPI_WALK_STATE *WalkState);
360 * utcreate - Object creation
363 AcpiUtUpdateObjectReference (
364 ACPI_OPERAND_OBJECT *Object,
369 * utdebug - Debug interfaces
372 AcpiUtInitStackPtrTrace (
376 AcpiUtTrackStackPtr (
382 const char *FunctionName,
383 const char *ModuleName,
389 const char *FunctionName,
390 const char *ModuleName,
392 const void *Pointer);
397 const char *FunctionName,
398 const char *ModuleName,
405 const char *FunctionName,
406 const char *ModuleName,
413 const char *FunctionName,
414 const char *ModuleName,
420 const char *FunctionName,
421 const char *ModuleName,
428 const char *FunctionName,
429 const char *ModuleName,
436 const char *FunctionName,
437 const char *ModuleName,
444 const char *FunctionName,
445 const char *ModuleName,
450 AcpiUtDebugDumpBuffer (
463 #ifdef ACPI_APPLICATION
465 AcpiUtDumpBufferToFile (
484 AcpiUtReportWarning (
490 * utdelete - Object deletion and reference counts
494 ACPI_OPERAND_OBJECT *Object);
497 AcpiUtRemoveReference (
498 ACPI_OPERAND_OBJECT *Object);
501 AcpiUtDeleteInternalPackageObject (
502 ACPI_OPERAND_OBJECT *Object);
505 AcpiUtDeleteInternalSimpleObject (
506 ACPI_OPERAND_OBJECT *Object);
509 AcpiUtDeleteInternalObjectList (
510 ACPI_OPERAND_OBJECT **ObjList);
514 * uteval - object evaluation
517 AcpiUtEvaluateObject (
518 ACPI_NAMESPACE_NODE *PrefixNode,
520 UINT32 ExpectedReturnBtypes,
521 ACPI_OPERAND_OBJECT **ReturnDesc);
524 AcpiUtEvaluateNumericObject (
525 const char *ObjectName,
526 ACPI_NAMESPACE_NODE *DeviceNode,
531 ACPI_NAMESPACE_NODE *DeviceNode,
532 UINT32 *StatusFlags);
535 AcpiUtExecutePowerMethods (
536 ACPI_NAMESPACE_NODE *DeviceNode,
537 const char **MethodNames,
543 * utids - device ID support
547 ACPI_NAMESPACE_NODE *DeviceNode,
548 ACPI_PNP_DEVICE_ID **ReturnId);
552 ACPI_NAMESPACE_NODE *DeviceNode,
553 ACPI_PNP_DEVICE_ID **ReturnId);
557 ACPI_NAMESPACE_NODE *DeviceNode,
558 ACPI_PNP_DEVICE_ID_LIST **ReturnCidList);
562 ACPI_NAMESPACE_NODE *DeviceNode,
563 ACPI_PNP_DEVICE_ID **ReturnId);
567 * utlock - reader/writer locks
578 AcpiUtAcquireReadLock (
582 AcpiUtReleaseReadLock (
586 AcpiUtAcquireWriteLock (
590 AcpiUtReleaseWriteLock (
595 * utobject - internal object create/delete/cache routines
597 ACPI_OPERAND_OBJECT *
598 AcpiUtCreateInternalObjectDbg (
599 const char *ModuleName,
602 ACPI_OBJECT_TYPE Type);
605 AcpiUtAllocateObjectDescDbg (
606 const char *ModuleName,
610 #define AcpiUtCreateInternalObject(t) AcpiUtCreateInternalObjectDbg (_AcpiModuleName,__LINE__,_COMPONENT,t)
611 #define AcpiUtAllocateObjectDesc() AcpiUtAllocateObjectDescDbg (_AcpiModuleName,__LINE__,_COMPONENT)
614 AcpiUtDeleteObjectDesc (
615 ACPI_OPERAND_OBJECT *Object);
618 AcpiUtValidInternalObject (
621 ACPI_OPERAND_OBJECT *
622 AcpiUtCreatePackageObject (
625 ACPI_OPERAND_OBJECT *
626 AcpiUtCreateIntegerObject (
629 ACPI_OPERAND_OBJECT *
630 AcpiUtCreateBufferObject (
631 ACPI_SIZE BufferSize);
633 ACPI_OPERAND_OBJECT *
634 AcpiUtCreateStringObject (
635 ACPI_SIZE StringSize);
639 ACPI_OPERAND_OBJECT *Obj,
640 ACPI_SIZE *ObjLength);
644 * utosi - Support for the _OSI predefined control method
647 AcpiUtInitializeInterfaces (
651 AcpiUtInterfaceTerminate (
655 AcpiUtInstallInterface (
656 ACPI_STRING InterfaceName);
659 AcpiUtRemoveInterface (
660 ACPI_STRING InterfaceName);
663 AcpiUtUpdateInterfaces (
666 ACPI_INTERFACE_INFO *
668 ACPI_STRING InterfaceName);
671 AcpiUtOsiImplementation (
672 ACPI_WALK_STATE *WalkState);
676 * utpredef - support for predefined names
678 const ACPI_PREDEFINED_INFO *
679 AcpiUtGetNextPredefinedMethod (
680 const ACPI_PREDEFINED_INFO *ThisName);
682 const ACPI_PREDEFINED_INFO *
683 AcpiUtMatchPredefinedMethod (
687 AcpiUtGetExpectedReturnTypes (
689 UINT32 ExpectedBtypes);
691 #if (defined ACPI_ASL_COMPILER || defined ACPI_HELP_APP)
692 const ACPI_PREDEFINED_INFO *
693 AcpiUtMatchResourceName (
697 AcpiUtDisplayPredefinedMethod (
699 const ACPI_PREDEFINED_INFO *ThisName,
703 AcpiUtGetResourceBitWidth (
710 * utstate - Generic state creation/cache routines
713 AcpiUtPushGenericState (
714 ACPI_GENERIC_STATE **ListHead,
715 ACPI_GENERIC_STATE *State);
718 AcpiUtPopGenericState (
719 ACPI_GENERIC_STATE **ListHead);
723 AcpiUtCreateGenericState (
727 AcpiUtCreateThreadState (
731 AcpiUtCreateUpdateState (
732 ACPI_OPERAND_OBJECT *Object,
736 AcpiUtCreatePkgState (
737 void *InternalObject,
738 void *ExternalObject,
742 AcpiUtCreateUpdateStateAndPush (
743 ACPI_OPERAND_OBJECT *Object,
745 ACPI_GENERIC_STATE **StateList);
748 AcpiUtCreateControlState (
752 AcpiUtDeleteGenericState (
753 ACPI_GENERIC_STATE *State);
764 UINT64 *OutRemainder);
771 UINT32 *OutRemainder);
777 const ACPI_EXCEPTION_INFO *
778 AcpiUtValidateException (
782 AcpiUtIsPciRootBridge (
785 #if (defined ACPI_ASL_COMPILER || defined ACPI_EXEC_APP || defined ACPI_NAMES_APP)
788 ACPI_TABLE_HEADER *Table);
792 AcpiUtWalkPackageTree (
793 ACPI_OPERAND_OBJECT *SourceObject,
795 ACPI_PKG_CALLBACK WalkCallback,
798 /* Values for Base above (16=Hex, 10=Decimal) */
800 #define ACPI_ANY_BASE 0
804 AcpiUtDwordByteSwap (
808 AcpiUtSetIntegerWidth (
811 #ifdef ACPI_DEBUG_OUTPUT
813 AcpiUtDisplayInitPathname (
815 ACPI_NAMESPACE_NODE *ObjHandle,
821 * utownerid - Support for Table/Method Owner IDs
824 AcpiUtAllocateOwnerId (
825 ACPI_OWNER_ID *OwnerId);
828 AcpiUtReleaseOwnerId (
829 ACPI_OWNER_ID *OwnerId);
836 AcpiUtWalkAmlResources (
837 ACPI_WALK_STATE *WalkState,
840 ACPI_WALK_AML_CALLBACK UserFunction,
844 AcpiUtValidateResource (
845 ACPI_WALK_STATE *WalkState,
850 AcpiUtGetDescriptorLength (
854 AcpiUtGetResourceLength (
858 AcpiUtGetResourceHeaderLength (
862 AcpiUtGetResourceType (
866 AcpiUtGetResourceEndTag (
867 ACPI_OPERAND_OBJECT *ObjDesc,
872 * utstring - String and character utilities
879 #if defined ACPI_ASL_COMPILER || defined ACPI_EXEC_APP
881 UtConvertBackslashes (
889 #if defined (ACPI_DEBUGGER) || defined (ACPI_APPLICATION)
907 ACPI_SIZE MaxTransferLength);
912 * utmutex - mutex support
915 AcpiUtMutexInitialize (
919 AcpiUtMutexTerminate (
924 ACPI_MUTEX_HANDLE MutexId);
928 ACPI_MUTEX_HANDLE MutexId);
932 * utalloc - memory allocation and object caching
943 AcpiUtValidateBuffer (
944 ACPI_BUFFER *Buffer);
947 AcpiUtInitializeBuffer (
949 ACPI_SIZE RequiredLength);
951 #ifdef ACPI_DBG_TRACK_ALLOCATIONS
953 AcpiUtAllocateAndTrack (
960 AcpiUtAllocateZeroedAndTrack (
974 AcpiUtDumpAllocationInfo (
978 AcpiUtDumpAllocations (
984 const char *ListName,
986 ACPI_MEMORY_LIST **ReturnCache);
988 #endif /* ACPI_DBG_TRACK_ALLOCATIONS */
992 * utaddress - address range check
995 AcpiUtAddAddressRange (
996 ACPI_ADR_SPACE_TYPE SpaceId,
997 ACPI_PHYSICAL_ADDRESS Address,
999 ACPI_NAMESPACE_NODE *RegionNode);
1002 AcpiUtRemoveAddressRange (
1003 ACPI_ADR_SPACE_TYPE SpaceId,
1004 ACPI_NAMESPACE_NODE *RegionNode);
1007 AcpiUtCheckAddressRange (
1008 ACPI_ADR_SPACE_TYPE SpaceId,
1009 ACPI_PHYSICAL_ADDRESS Address,
1014 AcpiUtDeleteAddressLists (
1019 * utxferror - various error/warning output functions
1021 void ACPI_INTERNAL_VAR_XFACE
1022 AcpiUtPredefinedWarning (
1023 const char *ModuleName,
1030 void ACPI_INTERNAL_VAR_XFACE
1031 AcpiUtPredefinedInfo (
1032 const char *ModuleName,
1039 void ACPI_INTERNAL_VAR_XFACE
1040 AcpiUtPredefinedBiosError (
1041 const char *ModuleName,
1049 AcpiUtNamespaceError (
1050 const char *ModuleName,
1052 const char *InternalName,
1053 ACPI_STATUS LookupStatus);
1057 const char *ModuleName,
1059 const char *Message,
1060 ACPI_NAMESPACE_NODE *Node,
1062 ACPI_STATUS LookupStatus);
1066 * Utility functions for ACPI names and IDs
1068 const AH_PREDEFINED_NAME *
1069 AcpiAhMatchPredefinedName (
1072 const AH_DEVICE_ID *
1073 AcpiAhMatchHardwareId (
1082 * utuuid -- UUID support functions
1084 #if (defined ACPI_ASL_COMPILER || defined ACPI_DISASSEMBLER || defined ACPI_EXEC_APP || defined ACPI_HELP_APP)
1086 AcpiUtConvertStringToUuid (
1091 #endif /* _ACUTILS_H */