acutils.h revision 84491 
1/******************************************************************************
2 *
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
4 *       $Revision: 115 $
5 *
6 *****************************************************************************/
7
8/******************************************************************************
9 *
10 * 1. Copyright Notice
11 *
12 * Some or all of this work - Copyright (c) 1999, 2000, 2001, Intel Corp.
13 * All rights reserved.
14 *
15 * 2. License
16 *
17 * 2.1. This is your license from Intel Corp. under its intellectual property
18 * rights.  You may have additional license terms from the party that provided
19 * you this software, covering your right to use that party's intellectual
20 * property rights.
21 *
22 * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
23 * copy of the source code appearing in this file ("Covered Code") an
24 * irrevocable, perpetual, worldwide license under Intel's copyrights in the
25 * base code distributed originally by Intel ("Original Intel Code") to copy,
26 * make derivatives, distribute, use and display any portion of the Covered
27 * Code in any form, with the right to sublicense such rights; and
28 *
29 * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
30 * license (with the right to sublicense), under only those claims of Intel
31 * patents that are infringed by the Original Intel Code, to make, use, sell,
32 * offer to sell, and import the Covered Code and derivative works thereof
33 * solely to the minimum extent necessary to exercise the above copyright
34 * license, and in no event shall the patent license extend to any additions
35 * to or modifications of the Original Intel Code.  No other license or right
36 * is granted directly or by implication, estoppel or otherwise;
37 *
38 * The above copyright and patent license is granted only if the following
39 * conditions are met:
40 *
41 * 3. Conditions
42 *
43 * 3.1. Redistribution of Source with Rights to Further Distribute Source.
44 * Redistribution of source code of any substantial portion of the Covered
45 * Code or modification with rights to further distribute source must include
46 * the above Copyright Notice, the above License, this list of Conditions,
47 * and the following Disclaimer and Export Compliance provision.  In addition,
48 * Licensee must cause all Covered Code to which Licensee contributes to
49 * contain a file documenting the changes Licensee made to create that Covered
50 * Code and the date of any change.  Licensee must include in that file the
51 * documentation of any changes made by any predecessor Licensee.  Licensee
52 * must include a prominent statement that the modification is derived,
53 * directly or indirectly, from Original Intel Code.
54 *
55 * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
56 * Redistribution of source code of any substantial portion of the Covered
57 * Code or modification without rights to further distribute source must
58 * include the following Disclaimer and Export Compliance provision in the
59 * documentation and/or other materials provided with distribution.  In
60 * addition, Licensee may not authorize further sublicense of source of any
61 * portion of the Covered Code, and must include terms to the effect that the
62 * license from Licensee to its licensee is limited to the intellectual
63 * property embodied in the software Licensee provides to its licensee, and
64 * not to intellectual property embodied in modifications its licensee may
65 * make.
66 *
67 * 3.3. Redistribution of Executable. Redistribution in executable form of any
68 * substantial portion of the Covered Code or modification must reproduce the
69 * above Copyright Notice, and the following Disclaimer and Export Compliance
70 * provision in the documentation and/or other materials provided with the
71 * distribution.
72 *
73 * 3.4. Intel retains all right, title, and interest in and to the Original
74 * Intel Code.
75 *
76 * 3.5. Neither the name Intel nor any other trademark owned or controlled by
77 * Intel shall be used in advertising or otherwise to promote the sale, use or
78 * other dealings in products derived from or relating to the Covered Code
79 * without prior written authorization from Intel.
80 *
81 * 4. Disclaimer and Export Compliance
82 *
83 * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
84 * HERE.  ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
85 * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT,  ASSISTANCE,
86 * INSTALLATION, TRAINING OR OTHER SERVICES.  INTEL WILL NOT PROVIDE ANY
87 * UPDATES, ENHANCEMENTS OR EXTENSIONS.  INTEL SPECIFICALLY DISCLAIMS ANY
88 * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
89 * PARTICULAR PURPOSE.
90 *
91 * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
92 * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
93 * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
94 * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
95 * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
96 * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS
97 * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
98 * LIMITED REMEDY.
99 *
100 * 4.3. Licensee shall not export, either directly or indirectly, any of this
101 * software or system incorporating such software without first obtaining any
102 * required license or other approval from the U. S. Department of Commerce or
103 * any other agency or department of the United States Government.  In the
104 * event Licensee exports any such software from the United States or
105 * re-exports any such software from a foreign destination, Licensee shall
106 * ensure that the distribution and export/re-export of the software is in
107 * compliance with all laws, regulations, orders, or other restrictions of the
108 * U.S. Export Administration Regulations. Licensee agrees that neither it nor
109 * any of its subsidiaries will export/re-export any technical data, process,
110 * software, or service, directly or indirectly, to any country for which the
111 * United States government or any agency thereof requires an export license,
112 * other governmental approval, or letter of assurance, without first obtaining
113 * such license, approval or letter.
114 *
115 *****************************************************************************/
116
117#ifndef _ACUTILS_H
118#define _ACUTILS_H
119
120
121typedef
122ACPI_STATUS (*ACPI_PKG_CALLBACK) (
123    UINT8                   ObjectType,
124    ACPI_OPERAND_OBJECT     *SourceObject,
125    ACPI_GENERIC_STATE      *State,
126    void                    *Context);
127
128
129ACPI_STATUS
130AcpiUtWalkPackageTree (
131    ACPI_OPERAND_OBJECT     *SourceObject,
132    void                    *TargetObject,
133    ACPI_PKG_CALLBACK       WalkCallback,
134    void                    *Context);
135
136
137typedef struct acpi_pkg_info
138{
139    UINT8                   *FreeSpace;
140    UINT32                  Length;
141    UINT32                  ObjectSpace;
142    UINT32                  NumPackages;
143} ACPI_PKG_INFO;
144
145#define REF_INCREMENT       (UINT16) 0
146#define REF_DECREMENT       (UINT16) 1
147#define REF_FORCE_DELETE    (UINT16) 2
148
149/* AcpiUtDumpBuffer */
150
151#define DB_BYTE_DISPLAY     1
152#define DB_WORD_DISPLAY     2
153#define DB_DWORD_DISPLAY    4
154#define DB_QWORD_DISPLAY    8
155
156
157/* Global initialization interfaces */
158
159void
160AcpiUtInitGlobals (
161    void);
162
163void
164AcpiUtTerminate (
165    void);
166
167
168/*
169 * UtInit - miscellaneous initialization and shutdown
170 */
171
172ACPI_STATUS
173AcpiUtHardwareInitialize (
174    void);
175
176ACPI_STATUS
177AcpiUtSubsystemShutdown (
178    void);
179
180ACPI_STATUS
181AcpiUtValidateFadt (
182    void);
183
184/*
185 * UtGlobal - Global data structures and procedures
186 */
187
188#ifdef ACPI_DEBUG
189
190NATIVE_CHAR *
191AcpiUtGetMutexName (
192    UINT32                  MutexId);
193
194NATIVE_CHAR *
195AcpiUtGetTypeName (
196    UINT32                  Type);
197
198NATIVE_CHAR *
199AcpiUtGetRegionName (
200    UINT8                   SpaceId);
201
202#endif
203
204
205UINT8
206AcpiUtHexToAsciiChar (
207    ACPI_INTEGER            Integer,
208    UINT32                  Position);
209
210BOOLEAN
211AcpiUtValidObjectType (
212    UINT32                  Type);
213
214ACPI_OWNER_ID
215AcpiUtAllocateOwnerId (
216    UINT32                  IdType);
217
218
219/*
220 * UtClib - Local implementations of C library functions
221 */
222
223#ifndef ACPI_USE_SYSTEM_CLIBRARY
224
225UINT32
226AcpiUtStrlen (
227    const NATIVE_CHAR       *String);
228
229NATIVE_CHAR *
230AcpiUtStrcpy (
231    NATIVE_CHAR             *DstString,
232    const NATIVE_CHAR       *SrcString);
233
234NATIVE_CHAR *
235AcpiUtStrncpy (
236    NATIVE_CHAR             *DstString,
237    const NATIVE_CHAR       *SrcString,
238    NATIVE_UINT             Count);
239
240UINT32
241AcpiUtStrncmp (
242    const NATIVE_CHAR       *String1,
243    const NATIVE_CHAR       *String2,
244    NATIVE_UINT             Count);
245
246UINT32
247AcpiUtStrcmp (
248    const NATIVE_CHAR       *String1,
249    const NATIVE_CHAR       *String2);
250
251NATIVE_CHAR *
252AcpiUtStrcat (
253    NATIVE_CHAR             *DstString,
254    const NATIVE_CHAR       *SrcString);
255
256NATIVE_CHAR *
257AcpiUtStrncat (
258    NATIVE_CHAR             *DstString,
259    const NATIVE_CHAR       *SrcString,
260    NATIVE_UINT             Count);
261
262UINT32
263AcpiUtStrtoul (
264    const NATIVE_CHAR       *String,
265    NATIVE_CHAR             **Terminator,
266    UINT32                  Base);
267
268NATIVE_CHAR *
269AcpiUtStrstr (
270    NATIVE_CHAR             *String1,
271    NATIVE_CHAR             *String2);
272
273void *
274AcpiUtMemcpy (
275    void                    *Dest,
276    const void              *Src,
277    NATIVE_UINT             Count);
278
279void *
280AcpiUtMemset (
281    void                    *Dest,
282    NATIVE_UINT             Value,
283    NATIVE_UINT             Count);
284
285UINT32
286AcpiUtToUpper (
287    UINT32                  c);
288
289UINT32
290AcpiUtToLower (
291    UINT32                  c);
292
293#endif /* ACPI_USE_SYSTEM_CLIBRARY */
294
295/*
296 * UtCopy - Object construction and conversion interfaces
297 */
298
299ACPI_STATUS
300AcpiUtBuildSimpleObject(
301    ACPI_OPERAND_OBJECT     *Obj,
302    ACPI_OBJECT             *UserObj,
303    UINT8                   *DataSpace,
304    UINT32                  *BufferSpaceUsed);
305
306ACPI_STATUS
307AcpiUtBuildPackageObject (
308    ACPI_OPERAND_OBJECT     *Obj,
309    UINT8                   *Buffer,
310    UINT32                  *SpaceUsed);
311
312ACPI_STATUS
313AcpiUtCopyIobjectToEobject (
314    ACPI_OPERAND_OBJECT     *Obj,
315    ACPI_BUFFER             *RetBuffer);
316
317ACPI_STATUS
318AcpiUtCopyEsimpleToIsimple(
319    ACPI_OBJECT             *UserObj,
320    ACPI_OPERAND_OBJECT     **ReturnObj);
321
322ACPI_STATUS
323AcpiUtCopyEobjectToIobject (
324    ACPI_OBJECT             *Obj,
325    ACPI_OPERAND_OBJECT     **InternalObj);
326
327ACPI_STATUS
328AcpiUtCopyISimpleToIsimple (
329    ACPI_OPERAND_OBJECT     *SourceObj,
330    ACPI_OPERAND_OBJECT     *DestObj);
331
332ACPI_STATUS
333AcpiUtCopyIpackageToIpackage (
334    ACPI_OPERAND_OBJECT     *SourceObj,
335    ACPI_OPERAND_OBJECT     *DestObj,
336    ACPI_WALK_STATE         *WalkState);
337
338
339/*
340 * UtCreate - Object creation
341 */
342
343ACPI_STATUS
344AcpiUtUpdateObjectReference (
345    ACPI_OPERAND_OBJECT     *Object,
346    UINT16                  Action);
347
348
349/*
350 * UtDebug - Debug interfaces
351 */
352
353void
354AcpiUtInitStackPtrTrace (
355    void);
356
357void
358AcpiUtTrackStackPtr (
359    void);
360
361void
362AcpiUtTrace (
363    UINT32                  LineNumber,
364    ACPI_DEBUG_PRINT_INFO   *DbgInfo);
365
366void
367AcpiUtTracePtr (
368    UINT32                  LineNumber,
369    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
370    void                    *Pointer);
371
372void
373AcpiUtTraceU32 (
374    UINT32                  LineNumber,
375    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
376    UINT32                  Integer);
377
378void
379AcpiUtTraceStr (
380    UINT32                  LineNumber,
381    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
382    NATIVE_CHAR             *String);
383
384void
385AcpiUtExit (
386    UINT32                  LineNumber,
387    ACPI_DEBUG_PRINT_INFO   *DbgInfo);
388
389void
390AcpiUtStatusExit (
391    UINT32                  LineNumber,
392    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
393    ACPI_STATUS             Status);
394
395void
396AcpiUtValueExit (
397    UINT32                  LineNumber,
398    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
399    ACPI_INTEGER            Value);
400
401void
402AcpiUtPtrExit (
403    UINT32                  LineNumber,
404    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
405    UINT8                   *Ptr);
406
407void
408AcpiUtReportInfo (
409    NATIVE_CHAR             *ModuleName,
410    UINT32                  LineNumber,
411    UINT32                  ComponentId);
412
413void
414AcpiUtReportError (
415    NATIVE_CHAR             *ModuleName,
416    UINT32                  LineNumber,
417    UINT32                  ComponentId);
418
419void
420AcpiUtReportWarning (
421    NATIVE_CHAR             *ModuleName,
422    UINT32                  LineNumber,
423    UINT32                  ComponentId);
424
425void
426AcpiUtDumpBuffer (
427    UINT8                   *Buffer,
428    UINT32                  Count,
429    UINT32                  Display,
430    UINT32                  componentId);
431
432void
433AcpiUtDebugPrint (
434    UINT32                  RequestedDebugLevel,
435    UINT32                  LineNumber,
436    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
437    char                    *Format,
438    ...);
439
440void
441AcpiUtDebugPrintRaw (
442    UINT32                  RequestedDebugLevel,
443    UINT32                  LineNumber,
444    ACPI_DEBUG_PRINT_INFO   *DbgInfo,
445    char                    *Format,
446    ...);
447
448
449/*
450 * UtDelete - Object deletion
451 */
452
453void
454AcpiUtDeleteInternalObj (
455    ACPI_OPERAND_OBJECT     *Object);
456
457void
458AcpiUtDeleteInternalPackageObject (
459    ACPI_OPERAND_OBJECT     *Object);
460
461void
462AcpiUtDeleteInternalSimpleObject (
463    ACPI_OPERAND_OBJECT     *Object);
464
465ACPI_STATUS
466AcpiUtDeleteInternalObjectList (
467    ACPI_OPERAND_OBJECT     **ObjList);
468
469
470/*
471 * UtEval - object evaluation
472 */
473
474/* Method name strings */
475
476#define METHOD_NAME__HID        "_HID"
477#define METHOD_NAME__UID        "_UID"
478#define METHOD_NAME__ADR        "_ADR"
479#define METHOD_NAME__STA        "_STA"
480#define METHOD_NAME__REG        "_REG"
481#define METHOD_NAME__SEG        "_SEG"
482#define METHOD_NAME__BBN        "_BBN"
483
484
485ACPI_STATUS
486AcpiUtEvaluateNumericObject (
487    NATIVE_CHAR             *ObjectName,
488    ACPI_NAMESPACE_NODE     *DeviceNode,
489    ACPI_INTEGER            *Address);
490
491ACPI_STATUS
492AcpiUtExecute_HID (
493    ACPI_NAMESPACE_NODE     *DeviceNode,
494    ACPI_DEVICE_ID          *Hid);
495
496ACPI_STATUS
497AcpiUtExecute_STA (
498    ACPI_NAMESPACE_NODE     *DeviceNode,
499    UINT32                  *StatusFlags);
500
501ACPI_STATUS
502AcpiUtExecute_UID (
503    ACPI_NAMESPACE_NODE     *DeviceNode,
504    ACPI_DEVICE_ID          *Uid);
505
506
507/*
508 * UtMutex - mutual exclusion interfaces
509 */
510
511ACPI_STATUS
512AcpiUtMutexInitialize (
513    void);
514
515void
516AcpiUtMutexTerminate (
517    void);
518
519ACPI_STATUS
520AcpiUtCreateMutex (
521    ACPI_MUTEX_HANDLE       MutexId);
522
523ACPI_STATUS
524AcpiUtDeleteMutex (
525    ACPI_MUTEX_HANDLE       MutexId);
526
527ACPI_STATUS
528AcpiUtAcquireMutex (
529    ACPI_MUTEX_HANDLE       MutexId);
530
531ACPI_STATUS
532AcpiUtReleaseMutex (
533    ACPI_MUTEX_HANDLE       MutexId);
534
535
536/*
537 * UtObject - internal object create/delete/cache routines
538 */
539
540ACPI_OPERAND_OBJECT  *
541AcpiUtCreateInternalObjectDbg (
542    NATIVE_CHAR             *ModuleName,
543    UINT32                  LineNumber,
544    UINT32                  ComponentId,
545    ACPI_OBJECT_TYPE8       Type);
546
547void *
548AcpiUtAllocateObjectDescDbg (
549    NATIVE_CHAR             *ModuleName,
550    UINT32                  LineNumber,
551    UINT32                  ComponentId);
552
553#define AcpiUtCreateInternalObject(t)   AcpiUtCreateInternalObjectDbg (_THIS_MODULE,__LINE__,_COMPONENT,t)
554#define AcpiUtAllocateObjectDesc()      AcpiUtAllocateObjectDescDbg (_THIS_MODULE,__LINE__,_COMPONENT)
555
556void
557AcpiUtDeleteObjectDesc (
558    ACPI_OPERAND_OBJECT     *Object);
559
560BOOLEAN
561AcpiUtValidInternalObject (
562    void                    *Object);
563
564
565/*
566 * UtRefCnt - Object reference count management
567 */
568
569void
570AcpiUtAddReference (
571    ACPI_OPERAND_OBJECT     *Object);
572
573void
574AcpiUtRemoveReference (
575    ACPI_OPERAND_OBJECT     *Object);
576
577/*
578 * UtSize - Object size routines
579 */
580
581ACPI_STATUS
582AcpiUtGetSimpleObjectSize (
583    ACPI_OPERAND_OBJECT     *Obj,
584    UINT32                  *ObjLength);
585
586ACPI_STATUS
587AcpiUtGetPackageObjectSize (
588    ACPI_OPERAND_OBJECT     *Obj,
589    UINT32                  *ObjLength);
590
591ACPI_STATUS
592AcpiUtGetObjectSize(
593    ACPI_OPERAND_OBJECT     *Obj,
594    UINT32                  *ObjLength);
595
596
597/*
598 * UtState - Generic state creation/cache routines
599 */
600
601void
602AcpiUtPushGenericState (
603    ACPI_GENERIC_STATE      **ListHead,
604    ACPI_GENERIC_STATE      *State);
605
606ACPI_GENERIC_STATE *
607AcpiUtPopGenericState (
608    ACPI_GENERIC_STATE      **ListHead);
609
610
611ACPI_GENERIC_STATE *
612AcpiUtCreateGenericState (
613    void);
614
615ACPI_GENERIC_STATE *
616AcpiUtCreateUpdateState (
617    ACPI_OPERAND_OBJECT     *Object,
618    UINT16                  Action);
619
620ACPI_GENERIC_STATE *
621AcpiUtCreatePkgState (
622    void                    *InternalObject,
623    void                    *ExternalObject,
624    UINT16                  Index);
625
626ACPI_STATUS
627AcpiUtCreateUpdateStateAndPush (
628    ACPI_OPERAND_OBJECT     *Object,
629    UINT16                  Action,
630    ACPI_GENERIC_STATE      **StateList);
631
632ACPI_STATUS
633AcpiUtCreatePkgStateAndPush (
634    void                    *InternalObject,
635    void                    *ExternalObject,
636    UINT16                  Index,
637    ACPI_GENERIC_STATE      **StateList);
638
639ACPI_GENERIC_STATE *
640AcpiUtCreateControlState (
641    void);
642
643void
644AcpiUtDeleteGenericState (
645    ACPI_GENERIC_STATE      *State);
646
647void
648AcpiUtDeleteGenericStateCache (
649    void);
650
651void
652AcpiUtDeleteObjectCache (
653    void);
654
655/*
656 * utmisc
657 */
658
659ACPI_STATUS
660AcpiUtDivide (
661    ACPI_INTEGER            *InDividend,
662    ACPI_INTEGER            *InDivisor,
663    ACPI_INTEGER            *OutQuotient,
664    ACPI_INTEGER            *OutRemainder);
665
666ACPI_STATUS
667AcpiUtShortDivide (
668    ACPI_INTEGER            *InDividend,
669    UINT32                  Divisor,
670    ACPI_INTEGER            *OutQuotient,
671    UINT32                  *OutRemainder);
672
673BOOLEAN
674AcpiUtValidAcpiName (
675    UINT32                  Name);
676
677BOOLEAN
678AcpiUtValidAcpiCharacter (
679    NATIVE_CHAR             Character);
680
681NATIVE_CHAR *
682AcpiUtStrupr (
683    NATIVE_CHAR             *SrcString);
684
685ACPI_STATUS
686AcpiUtResolvePackageReferences (
687    ACPI_OPERAND_OBJECT     *ObjDesc);
688
689
690#ifdef ACPI_DEBUG
691void
692AcpiUtDisplayInitPathname (
693    ACPI_HANDLE             ObjHandle,
694    char                    *Path);
695
696#endif
697
698
699/*
700 * Utalloc - memory allocation and object caching
701 */
702
703void *
704AcpiUtAcquireFromCache (
705    UINT32                  ListId);
706
707void
708AcpiUtReleaseToCache (
709    UINT32                  ListId,
710    void                    *Object);
711
712void
713AcpiUtDeleteGenericCache (
714    UINT32                  ListId);
715
716
717/* Debug Memory allocation functions */
718
719void *
720AcpiUtAllocate (
721    UINT32                  Size,
722    UINT32                  Component,
723    NATIVE_CHAR             *Module,
724    UINT32                  Line);
725
726void *
727AcpiUtCallocate (
728    UINT32                  Size,
729    UINT32                  Component,
730    NATIVE_CHAR             *Module,
731    UINT32                  Line);
732
733void
734AcpiUtFree (
735    void                    *Address,
736    UINT32                  Component,
737    NATIVE_CHAR             *Module,
738    UINT32                  Line);
739
740#ifdef ACPI_DBG_TRACK_ALLOCATIONS
741void
742AcpiUtDumpAllocationInfo (
743    void);
744
745void
746AcpiUtDumpAllocations (
747    UINT32                  Component,
748    NATIVE_CHAR             *Module);
749#endif
750
751
752#endif /* _ACUTILS_H */
753