acutils.h revision 82367 
1/******************************************************************************
2 *
3 * Name: acutils.h -- prototypes for the common (subsystem-wide) procedures
4 *       $Revision: 108 $
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     *Obj);
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
348ACPI_OPERAND_OBJECT  *
349_UtCreateInternalObject (
350    NATIVE_CHAR             *ModuleName,
351    UINT32                  LineNumber,
352    UINT32                  ComponentId,
353    ACPI_OBJECT_TYPE8       Type);
354
355
356/*
357 * UtDebug - Debug interfaces
358 */
359
360UINT32
361GetDebugLevel (
362    void);
363
364void
365SetDebugLevel (
366    UINT32                  level);
367
368void
369FunctionTrace (
370    NATIVE_CHAR             *ModuleName,
371    UINT32                  LineNumber,
372    UINT32                  ComponentId,
373    NATIVE_CHAR             *FunctionName);
374
375void
376FunctionTracePtr (
377    NATIVE_CHAR             *ModuleName,
378    UINT32                  LineNumber,
379    UINT32                  ComponentId,
380    NATIVE_CHAR             *FunctionName,
381    void                    *Pointer);
382
383void
384FunctionTraceU32 (
385    NATIVE_CHAR             *ModuleName,
386    UINT32                  LineNumber,
387    UINT32                  ComponentId,
388    NATIVE_CHAR             *FunctionName,
389    UINT32                  Integer);
390
391void
392FunctionTraceStr (
393    NATIVE_CHAR             *ModuleName,
394    UINT32                  LineNumber,
395    UINT32                  ComponentId,
396    NATIVE_CHAR             *FunctionName,
397    NATIVE_CHAR             *String);
398
399void
400FunctionExit (
401    NATIVE_CHAR             *ModuleName,
402    UINT32                  LineNumber,
403    UINT32                  ComponentId,
404    NATIVE_CHAR             *FunctionName);
405
406void
407FunctionStatusExit (
408    NATIVE_CHAR             *ModuleName,
409    UINT32                  LineNumber,
410    UINT32                  ComponentId,
411    NATIVE_CHAR             *FunctionName,
412    ACPI_STATUS             Status);
413
414void
415FunctionValueExit (
416    NATIVE_CHAR             *ModuleName,
417    UINT32                  LineNumber,
418    UINT32                  ComponentId,
419    NATIVE_CHAR             *FunctionName,
420    ACPI_INTEGER            Value);
421
422void
423FunctionPtrExit (
424    NATIVE_CHAR             *ModuleName,
425    UINT32                  LineNumber,
426    UINT32                  ComponentId,
427    NATIVE_CHAR             *FunctionName,
428    UINT8                   *Ptr);
429
430void
431_ReportInfo (
432    NATIVE_CHAR             *ModuleName,
433    UINT32                  LineNumber,
434    UINT32                  ComponentId);
435
436void
437_ReportError (
438    NATIVE_CHAR             *ModuleName,
439    UINT32                  LineNumber,
440    UINT32                  ComponentId);
441
442void
443_ReportWarning (
444    NATIVE_CHAR             *ModuleName,
445    UINT32                  LineNumber,
446    UINT32                  ComponentId);
447
448void
449AcpiUtDumpBuffer (
450    UINT8                   *Buffer,
451    UINT32                  Count,
452    UINT32                  Display,
453    UINT32                  componentId);
454
455void
456AcpiUtDebugPrint (
457    UINT32                  RequestedDebugLevel,
458    UINT32                  ComponentId,
459    NATIVE_CHAR             *ModuleName,
460    NATIVE_CHAR             *ProcName,
461    UINT32                  LineNumber,
462    char                    *Format,
463    ...);
464
465void
466AcpiUtDebugPrintRaw (
467    UINT32                  RequestedDebugLevel,
468    UINT32                  ComponentId,
469    NATIVE_CHAR             *ModuleName,
470    NATIVE_CHAR             *ProcName,
471    UINT32                  LineNumber,
472    char                    *Format,
473    ...);
474
475/*
476 * UtDelete - Object deletion
477 */
478
479void
480AcpiUtDeleteInternalObj (
481    ACPI_OPERAND_OBJECT     *Object);
482
483void
484AcpiUtDeleteInternalPackageObject (
485    ACPI_OPERAND_OBJECT     *Object);
486
487void
488AcpiUtDeleteInternalSimpleObject (
489    ACPI_OPERAND_OBJECT     *Object);
490
491ACPI_STATUS
492AcpiUtDeleteInternalObjectList (
493    ACPI_OPERAND_OBJECT     **ObjList);
494
495
496/*
497 * UtEval - object evaluation
498 */
499
500/* Method name strings */
501
502#define METHOD_NAME__HID        "_HID"
503#define METHOD_NAME__UID        "_UID"
504#define METHOD_NAME__ADR        "_ADR"
505#define METHOD_NAME__STA        "_STA"
506#define METHOD_NAME__REG        "_REG"
507#define METHOD_NAME__SEG        "_SEG"
508#define METHOD_NAME__BBN        "_BBN"
509
510
511ACPI_STATUS
512AcpiUtEvaluateNumericObject (
513    NATIVE_CHAR             *ObjectName,
514    ACPI_NAMESPACE_NODE     *DeviceNode,
515    ACPI_INTEGER            *Address);
516
517ACPI_STATUS
518AcpiUtExecute_HID (
519    ACPI_NAMESPACE_NODE     *DeviceNode,
520    ACPI_DEVICE_ID          *Hid);
521
522ACPI_STATUS
523AcpiUtExecute_STA (
524    ACPI_NAMESPACE_NODE     *DeviceNode,
525    UINT32                  *StatusFlags);
526
527ACPI_STATUS
528AcpiUtExecute_UID (
529    ACPI_NAMESPACE_NODE     *DeviceNode,
530    ACPI_DEVICE_ID          *Uid);
531
532
533/*
534 * UtMutex - mutual exclusion interfaces
535 */
536
537ACPI_STATUS
538AcpiUtMutexInitialize (
539    void);
540
541void
542AcpiUtMutexTerminate (
543    void);
544
545ACPI_STATUS
546AcpiUtCreateMutex (
547    ACPI_MUTEX_HANDLE       MutexId);
548
549ACPI_STATUS
550AcpiUtDeleteMutex (
551    ACPI_MUTEX_HANDLE       MutexId);
552
553ACPI_STATUS
554AcpiUtAcquireMutex (
555    ACPI_MUTEX_HANDLE       MutexId);
556
557ACPI_STATUS
558AcpiUtReleaseMutex (
559    ACPI_MUTEX_HANDLE       MutexId);
560
561
562/*
563 * UtObject - internal object create/delete/cache routines
564 */
565
566void *
567_UtAllocateObjectDesc (
568    NATIVE_CHAR             *ModuleName,
569    UINT32                  LineNumber,
570    UINT32                  ComponentId);
571
572#define AcpiUtCreateInternalObject(t)   _UtCreateInternalObject(_THIS_MODULE,__LINE__,_COMPONENT,t)
573#define AcpiUtAllocateObjectDesc()      _UtAllocateObjectDesc(_THIS_MODULE,__LINE__,_COMPONENT)
574
575void
576AcpiUtDeleteObjectDesc (
577    ACPI_OPERAND_OBJECT     *Object);
578
579BOOLEAN
580AcpiUtValidInternalObject (
581    void                    *Object);
582
583
584/*
585 * UtRefCnt - Object reference count management
586 */
587
588void
589AcpiUtAddReference (
590    ACPI_OPERAND_OBJECT     *Object);
591
592void
593AcpiUtRemoveReference (
594    ACPI_OPERAND_OBJECT     *Object);
595
596/*
597 * UtSize - Object size routines
598 */
599
600ACPI_STATUS
601AcpiUtGetSimpleObjectSize (
602    ACPI_OPERAND_OBJECT     *Obj,
603    UINT32                  *ObjLength);
604
605ACPI_STATUS
606AcpiUtGetPackageObjectSize (
607    ACPI_OPERAND_OBJECT     *Obj,
608    UINT32                  *ObjLength);
609
610ACPI_STATUS
611AcpiUtGetObjectSize(
612    ACPI_OPERAND_OBJECT     *Obj,
613    UINT32                  *ObjLength);
614
615
616/*
617 * UtState - Generic state creation/cache routines
618 */
619
620void
621AcpiUtPushGenericState (
622    ACPI_GENERIC_STATE      **ListHead,
623    ACPI_GENERIC_STATE      *State);
624
625ACPI_GENERIC_STATE *
626AcpiUtPopGenericState (
627    ACPI_GENERIC_STATE      **ListHead);
628
629
630ACPI_GENERIC_STATE *
631AcpiUtCreateGenericState (
632    void);
633
634ACPI_GENERIC_STATE *
635AcpiUtCreateUpdateState (
636    ACPI_OPERAND_OBJECT     *Object,
637    UINT16                  Action);
638
639ACPI_GENERIC_STATE *
640AcpiUtCreatePkgState (
641    void                    *InternalObject,
642    void                    *ExternalObject,
643    UINT16                  Index);
644
645ACPI_STATUS
646AcpiUtCreateUpdateStateAndPush (
647    ACPI_OPERAND_OBJECT     *Object,
648    UINT16                  Action,
649    ACPI_GENERIC_STATE      **StateList);
650
651ACPI_STATUS
652AcpiUtCreatePkgStateAndPush (
653    void                    *InternalObject,
654    void                    *ExternalObject,
655    UINT16                  Index,
656    ACPI_GENERIC_STATE      **StateList);
657
658ACPI_GENERIC_STATE *
659AcpiUtCreateControlState (
660    void);
661
662void
663AcpiUtDeleteGenericState (
664    ACPI_GENERIC_STATE      *State);
665
666void
667AcpiUtDeleteGenericStateCache (
668    void);
669
670void
671AcpiUtDeleteObjectCache (
672    void);
673
674/*
675 * Ututils
676 */
677
678BOOLEAN
679AcpiUtValidAcpiName (
680    UINT32                  Name);
681
682BOOLEAN
683AcpiUtValidAcpiCharacter (
684    NATIVE_CHAR             Character);
685
686NATIVE_CHAR *
687AcpiUtStrupr (
688    NATIVE_CHAR             *SrcString);
689
690ACPI_STATUS
691AcpiUtResolvePackageReferences (
692    ACPI_OPERAND_OBJECT     *ObjDesc);
693
694
695#ifdef ACPI_DEBUG
696void
697AcpiUtDisplayInitPathname (
698    ACPI_HANDLE             ObjHandle,
699    char                    *Path);
700
701#endif
702
703
704/*
705 * Utalloc - memory allocation and object caching
706 */
707
708void *
709AcpiUtAcquireFromCache (
710    UINT32                  ListId);
711
712void
713AcpiUtReleaseToCache (
714    UINT32                  ListId,
715    void                    *Object);
716
717void
718AcpiUtDeleteGenericCache (
719    UINT32                  ListId);
720
721
722/* Debug Memory allocation functions */
723
724void *
725AcpiUtAllocate (
726    UINT32                  Size,
727    UINT32                  Component,
728    NATIVE_CHAR             *Module,
729    UINT32                  Line);
730
731void *
732AcpiUtCallocate (
733    UINT32                  Size,
734    UINT32                  Component,
735    NATIVE_CHAR             *Module,
736    UINT32                  Line);
737
738void
739AcpiUtFree (
740    void                    *Address,
741    UINT32                  Component,
742    NATIVE_CHAR             *Module,
743    UINT32                  Line);
744
745void
746AcpiUtInitStaticObject (
747    ACPI_OPERAND_OBJECT     *ObjDesc);
748
749
750#ifdef ACPI_DBG_TRACK_ALLOCATIONS
751void
752AcpiUtDumpAllocationInfo (
753    void);
754
755void
756AcpiUtDumpCurrentAllocations (
757    UINT32                  Component,
758    NATIVE_CHAR             *Module);
759#endif
760
761
762
763#endif /* _ACUTILS_H */
764