1 /******************************************************************************
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
5 *****************************************************************************/
8 * Copyright (C) 2000 - 2013, 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_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
99 extern FILE *AcpiGbl_OutputFile;
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 #define ACPI_MSG_ERROR "ACPI Error: "
120 #define ACPI_MSG_EXCEPTION "ACPI Exception: "
121 #define ACPI_MSG_WARNING "ACPI Warning: "
122 #define ACPI_MSG_INFO "ACPI: "
124 #define ACPI_MSG_BIOS_ERROR "ACPI BIOS Error (bug): "
125 #define ACPI_MSG_BIOS_WARNING "ACPI BIOS Warning (bug): "
128 * Common message suffix
130 #define ACPI_MSG_SUFFIX \
131 AcpiOsPrintf (" (%8.8X/%s-%u)\n", ACPI_CA_VERSION, ModuleName, LineNumber)
134 /* Types for Resource descriptor entries */
136 #define ACPI_INVALID_RESOURCE 0
137 #define ACPI_FIXED_LENGTH 1
138 #define ACPI_VARIABLE_LENGTH 2
139 #define ACPI_SMALL_VARIABLE_LENGTH 3
142 ACPI_STATUS (*ACPI_WALK_AML_CALLBACK) (
150 ACPI_STATUS (*ACPI_PKG_CALLBACK) (
152 ACPI_OPERAND_OBJECT *SourceObject,
153 ACPI_GENERIC_STATE *State,
156 typedef struct acpi_pkg_info
165 /* Object reference counts */
167 #define REF_INCREMENT (UINT16) 0
168 #define REF_DECREMENT (UINT16) 1
170 /* AcpiUtDumpBuffer */
172 #define DB_BYTE_DISPLAY 1
173 #define DB_WORD_DISPLAY 2
174 #define DB_DWORD_DISPLAY 4
175 #define DB_QWORD_DISPLAY 8
178 * utglobal - Global data structures and procedures
184 #if defined(ACPI_DEBUG_OUTPUT) || defined(ACPI_DEBUGGER)
191 AcpiUtGetNotifyName (
198 ACPI_OBJECT_TYPE Type);
205 AcpiUtGetDescriptorName (
209 AcpiUtGetReferenceName (
210 ACPI_OPERAND_OBJECT *Object);
213 AcpiUtGetObjectTypeName (
214 ACPI_OPERAND_OBJECT *ObjDesc);
217 AcpiUtGetRegionName (
225 AcpiUtHexToAsciiChar (
230 AcpiUtValidObjectType (
231 ACPI_OBJECT_TYPE Type);
235 * utinit - miscellaneous initialization and shutdown
238 AcpiUtHardwareInitialize (
242 AcpiUtSubsystemShutdown (
247 * utclib - Local implementations of C library functions
249 #ifndef ACPI_USE_SYSTEM_CLIBRARY
258 const char *SrcString);
263 const char *SrcString,
281 const char *String2);
286 const char *SrcString);
291 const char *SrcString,
325 extern const UINT8 _acpi_ctype[];
327 #define _ACPI_XA 0x00 /* extra alphabetic - not supported */
328 #define _ACPI_XS 0x40 /* extra space */
329 #define _ACPI_BB 0x00 /* BEL, BS, etc. - not supported */
330 #define _ACPI_CN 0x20 /* CR, FF, HT, NL, VT */
331 #define _ACPI_DI 0x04 /* '0'-'9' */
332 #define _ACPI_LO 0x02 /* 'a'-'z' */
333 #define _ACPI_PU 0x10 /* punctuation */
334 #define _ACPI_SP 0x08 /* space */
335 #define _ACPI_UP 0x01 /* 'A'-'Z' */
336 #define _ACPI_XD 0x80 /* '0'-'9', 'A'-'F', 'a'-'f' */
338 #define ACPI_IS_DIGIT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_DI))
339 #define ACPI_IS_SPACE(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_SP))
340 #define ACPI_IS_XDIGIT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_XD))
341 #define ACPI_IS_UPPER(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_UP))
342 #define ACPI_IS_LOWER(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO))
343 #define ACPI_IS_PRINT(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP | _ACPI_DI | _ACPI_SP | _ACPI_PU))
344 #define ACPI_IS_ALPHA(c) (_acpi_ctype[(unsigned char)(c)] & (_ACPI_LO | _ACPI_UP))
346 #endif /* !ACPI_USE_SYSTEM_CLIBRARY */
348 #define ACPI_IS_ASCII(c) ((c) < 0x80)
352 * utcopy - Object construction and conversion interfaces
355 AcpiUtBuildSimpleObject(
356 ACPI_OPERAND_OBJECT *Obj,
357 ACPI_OBJECT *UserObj,
359 UINT32 *BufferSpaceUsed);
362 AcpiUtBuildPackageObject (
363 ACPI_OPERAND_OBJECT *Obj,
368 AcpiUtCopyIobjectToEobject (
369 ACPI_OPERAND_OBJECT *Obj,
370 ACPI_BUFFER *RetBuffer);
373 AcpiUtCopyEobjectToIobject (
375 ACPI_OPERAND_OBJECT **InternalObj);
378 AcpiUtCopyISimpleToIsimple (
379 ACPI_OPERAND_OBJECT *SourceObj,
380 ACPI_OPERAND_OBJECT *DestObj);
383 AcpiUtCopyIobjectToIobject (
384 ACPI_OPERAND_OBJECT *SourceDesc,
385 ACPI_OPERAND_OBJECT **DestDesc,
386 ACPI_WALK_STATE *WalkState);
390 * utcreate - Object creation
393 AcpiUtUpdateObjectReference (
394 ACPI_OPERAND_OBJECT *Object,
399 * utdebug - Debug interfaces
402 AcpiUtInitStackPtrTrace (
406 AcpiUtTrackStackPtr (
412 const char *FunctionName,
413 const char *ModuleName,
419 const char *FunctionName,
420 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,
450 const char *FunctionName,
451 const char *ModuleName,
458 const char *FunctionName,
459 const char *ModuleName,
466 const char *FunctionName,
467 const char *ModuleName,
472 AcpiUtDebugDumpBuffer (
496 AcpiUtReportWarning (
501 * utdelete - Object deletion and reference counts
505 ACPI_OPERAND_OBJECT *Object);
508 AcpiUtRemoveReference (
509 ACPI_OPERAND_OBJECT *Object);
512 AcpiUtDeleteInternalPackageObject (
513 ACPI_OPERAND_OBJECT *Object);
516 AcpiUtDeleteInternalSimpleObject (
517 ACPI_OPERAND_OBJECT *Object);
520 AcpiUtDeleteInternalObjectList (
521 ACPI_OPERAND_OBJECT **ObjList);
525 * uteval - object evaluation
528 AcpiUtEvaluateObject (
529 ACPI_NAMESPACE_NODE *PrefixNode,
531 UINT32 ExpectedReturnBtypes,
532 ACPI_OPERAND_OBJECT **ReturnDesc);
535 AcpiUtEvaluateNumericObject (
537 ACPI_NAMESPACE_NODE *DeviceNode,
542 ACPI_NAMESPACE_NODE *DeviceNode,
543 UINT32 *StatusFlags);
546 AcpiUtExecutePowerMethods (
547 ACPI_NAMESPACE_NODE *DeviceNode,
548 const char **MethodNames,
554 * utids - device ID support
558 ACPI_NAMESPACE_NODE *DeviceNode,
559 ACPI_PNP_DEVICE_ID **ReturnId);
563 ACPI_NAMESPACE_NODE *DeviceNode,
564 ACPI_PNP_DEVICE_ID **ReturnId);
568 ACPI_NAMESPACE_NODE *DeviceNode,
569 ACPI_PNP_DEVICE_ID **ReturnId);
573 ACPI_NAMESPACE_NODE *DeviceNode,
574 ACPI_PNP_DEVICE_ID_LIST **ReturnCidList);
578 * utlock - reader/writer locks
589 AcpiUtAcquireReadLock (
593 AcpiUtReleaseReadLock (
597 AcpiUtAcquireWriteLock (
601 AcpiUtReleaseWriteLock (
606 * utobject - internal object create/delete/cache routines
608 ACPI_OPERAND_OBJECT *
609 AcpiUtCreateInternalObjectDbg (
610 const char *ModuleName,
613 ACPI_OBJECT_TYPE Type);
616 AcpiUtAllocateObjectDescDbg (
617 const char *ModuleName,
621 #define AcpiUtCreateInternalObject(t) AcpiUtCreateInternalObjectDbg (_AcpiModuleName,__LINE__,_COMPONENT,t)
622 #define AcpiUtAllocateObjectDesc() AcpiUtAllocateObjectDescDbg (_AcpiModuleName,__LINE__,_COMPONENT)
625 AcpiUtDeleteObjectDesc (
626 ACPI_OPERAND_OBJECT *Object);
629 AcpiUtValidInternalObject (
632 ACPI_OPERAND_OBJECT *
633 AcpiUtCreatePackageObject (
636 ACPI_OPERAND_OBJECT *
637 AcpiUtCreateIntegerObject (
640 ACPI_OPERAND_OBJECT *
641 AcpiUtCreateBufferObject (
642 ACPI_SIZE BufferSize);
644 ACPI_OPERAND_OBJECT *
645 AcpiUtCreateStringObject (
646 ACPI_SIZE StringSize);
650 ACPI_OPERAND_OBJECT *Obj,
651 ACPI_SIZE *ObjLength);
655 * utosi - Support for the _OSI predefined control method
658 AcpiUtInitializeInterfaces (
662 AcpiUtInterfaceTerminate (
666 AcpiUtInstallInterface (
667 ACPI_STRING InterfaceName);
670 AcpiUtRemoveInterface (
671 ACPI_STRING InterfaceName);
674 AcpiUtUpdateInterfaces (
677 ACPI_INTERFACE_INFO *
679 ACPI_STRING InterfaceName);
682 AcpiUtOsiImplementation (
683 ACPI_WALK_STATE *WalkState);
687 * utpredef - support for predefined names
689 const ACPI_PREDEFINED_INFO *
690 AcpiUtGetNextPredefinedMethod (
691 const ACPI_PREDEFINED_INFO *ThisName);
693 const ACPI_PREDEFINED_INFO *
694 AcpiUtMatchPredefinedMethod (
697 const ACPI_PREDEFINED_INFO *
698 AcpiUtMatchResourceName (
702 AcpiUtDisplayPredefinedMethod (
704 const ACPI_PREDEFINED_INFO *ThisName,
708 AcpiUtGetExpectedReturnTypes (
710 UINT32 ExpectedBtypes);
713 AcpiUtGetResourceBitWidth (
719 * utstate - Generic state creation/cache routines
722 AcpiUtPushGenericState (
723 ACPI_GENERIC_STATE **ListHead,
724 ACPI_GENERIC_STATE *State);
727 AcpiUtPopGenericState (
728 ACPI_GENERIC_STATE **ListHead);
732 AcpiUtCreateGenericState (
736 AcpiUtCreateThreadState (
740 AcpiUtCreateUpdateState (
741 ACPI_OPERAND_OBJECT *Object,
745 AcpiUtCreatePkgState (
746 void *InternalObject,
747 void *ExternalObject,
751 AcpiUtCreateUpdateStateAndPush (
752 ACPI_OPERAND_OBJECT *Object,
754 ACPI_GENERIC_STATE **StateList);
757 AcpiUtCreatePkgStateAndPush (
758 void *InternalObject,
759 void *ExternalObject,
761 ACPI_GENERIC_STATE **StateList);
764 AcpiUtCreateControlState (
768 AcpiUtDeleteGenericState (
769 ACPI_GENERIC_STATE *State);
780 UINT64 *OutRemainder);
787 UINT32 *OutRemainder);
793 const ACPI_EXCEPTION_INFO *
794 AcpiUtValidateException (
798 AcpiUtIsPciRootBridge (
803 ACPI_TABLE_HEADER *Table);
806 AcpiUtWalkPackageTree (
807 ACPI_OPERAND_OBJECT *SourceObject,
809 ACPI_PKG_CALLBACK WalkCallback,
813 /* Values for Base above (16=Hex, 10=Decimal) */
815 #define ACPI_ANY_BASE 0
818 AcpiUtDwordByteSwap (
822 AcpiUtSetIntegerWidth (
825 #ifdef ACPI_DEBUG_OUTPUT
827 AcpiUtDisplayInitPathname (
829 ACPI_NAMESPACE_NODE *ObjHandle,
835 * utownerid - Support for Table/Method Owner IDs
838 AcpiUtAllocateOwnerId (
839 ACPI_OWNER_ID *OwnerId);
842 AcpiUtReleaseOwnerId (
843 ACPI_OWNER_ID *OwnerId);
850 AcpiUtWalkAmlResources (
851 ACPI_WALK_STATE *WalkState,
854 ACPI_WALK_AML_CALLBACK UserFunction,
858 AcpiUtValidateResource (
859 ACPI_WALK_STATE *WalkState,
864 AcpiUtGetDescriptorLength (
868 AcpiUtGetResourceLength (
872 AcpiUtGetResourceHeaderLength (
876 AcpiUtGetResourceType (
880 AcpiUtGetResourceEndTag (
881 ACPI_OPERAND_OBJECT *ObjDesc,
886 * utstring - String and character utilities
913 UtConvertBackslashes (
917 AcpiUtValidAcpiName (
921 AcpiUtValidAcpiChar (
931 * utmutex - mutex support
934 AcpiUtMutexInitialize (
938 AcpiUtMutexTerminate (
943 ACPI_MUTEX_HANDLE MutexId);
947 ACPI_MUTEX_HANDLE MutexId);
951 * utalloc - memory allocation and object caching
962 AcpiUtValidateBuffer (
963 ACPI_BUFFER *Buffer);
966 AcpiUtInitializeBuffer (
968 ACPI_SIZE RequiredLength);
978 AcpiUtAllocateZeroed (
984 #ifdef ACPI_DBG_TRACK_ALLOCATIONS
986 AcpiUtAllocateAndTrack (
993 AcpiUtAllocateZeroedAndTrack (
1000 AcpiUtFreeAndTrack (
1007 AcpiUtDumpAllocationInfo (
1011 AcpiUtDumpAllocations (
1013 const char *Module);
1019 ACPI_MEMORY_LIST **ReturnCache);
1021 #endif /* ACPI_DBG_TRACK_ALLOCATIONS */
1024 * utaddress - address range check
1027 AcpiUtAddAddressRange (
1028 ACPI_ADR_SPACE_TYPE SpaceId,
1029 ACPI_PHYSICAL_ADDRESS Address,
1031 ACPI_NAMESPACE_NODE *RegionNode);
1034 AcpiUtRemoveAddressRange (
1035 ACPI_ADR_SPACE_TYPE SpaceId,
1036 ACPI_NAMESPACE_NODE *RegionNode);
1039 AcpiUtCheckAddressRange (
1040 ACPI_ADR_SPACE_TYPE SpaceId,
1041 ACPI_PHYSICAL_ADDRESS Address,
1046 AcpiUtDeleteAddressLists (
1050 * utxferror - various error/warning output functions
1052 void ACPI_INTERNAL_VAR_XFACE
1053 AcpiUtPredefinedWarning (
1054 const char *ModuleName,
1061 void ACPI_INTERNAL_VAR_XFACE
1062 AcpiUtPredefinedInfo (
1063 const char *ModuleName,
1070 void ACPI_INTERNAL_VAR_XFACE
1071 AcpiUtPredefinedBiosError (
1072 const char *ModuleName,
1080 AcpiUtNamespaceError (
1081 const char *ModuleName,
1083 const char *InternalName,
1084 ACPI_STATUS LookupStatus);
1088 const char *ModuleName,
1090 const char *Message,
1091 ACPI_NAMESPACE_NODE *Node,
1093 ACPI_STATUS LookupStatus);
1095 #endif /* _ACUTILS_H */