xref: /freebsd/sys/contrib/dev/acpica/include/acnamesp.h (revision 60b9567d16b585b05c86c60393958ad81cbfa72f)
1 /******************************************************************************
2  *
3  * Name: acnamesp.h - Namespace subcomponent prototypes and defines
4  *
5  *****************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2017, Intel Corp.
9  * All rights reserved.
10  *
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions
13  * are met:
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.
25  *
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.
29  *
30  * NO WARRANTY
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.
42  */
43 
44 #ifndef __ACNAMESP_H__
45 #define __ACNAMESP_H__
46 
47 
48 /* To search the entire name space, pass this as SearchBase */
49 
50 #define ACPI_NS_ALL                 ((ACPI_HANDLE)0)
51 
52 /*
53  * Elements of AcpiNsProperties are bit significant
54  * and should be one-to-one with values of ACPI_OBJECT_TYPE
55  */
56 #define ACPI_NS_NORMAL              0
57 #define ACPI_NS_NEWSCOPE            1   /* a definition of this type opens a name scope */
58 #define ACPI_NS_LOCAL               2   /* suppress search of enclosing scopes */
59 
60 /* Flags for AcpiNsLookup, AcpiNsSearchAndEnter */
61 
62 #define ACPI_NS_NO_UPSEARCH         0
63 #define ACPI_NS_SEARCH_PARENT       0x01
64 #define ACPI_NS_DONT_OPEN_SCOPE     0x02
65 #define ACPI_NS_NO_PEER_SEARCH      0x04
66 #define ACPI_NS_ERROR_IF_FOUND      0x08
67 #define ACPI_NS_PREFIX_IS_SCOPE     0x10
68 #define ACPI_NS_EXTERNAL            0x20
69 #define ACPI_NS_TEMPORARY           0x40
70 #define ACPI_NS_OVERRIDE_IF_FOUND   0x80
71 
72 /* Flags for AcpiNsWalkNamespace */
73 
74 #define ACPI_NS_WALK_NO_UNLOCK      0
75 #define ACPI_NS_WALK_UNLOCK         0x01
76 #define ACPI_NS_WALK_TEMP_NODES     0x02
77 
78 /* Object is not a package element */
79 
80 #define ACPI_NOT_PACKAGE_ELEMENT    ACPI_UINT32_MAX
81 #define ACPI_ALL_PACKAGE_ELEMENTS   (ACPI_UINT32_MAX-1)
82 
83 /* Always emit warning message, not dependent on node flags */
84 
85 #define ACPI_WARN_ALWAYS            0
86 
87 
88 /*
89  * nsinit - Namespace initialization
90  */
91 ACPI_STATUS
92 AcpiNsInitializeObjects (
93     void);
94 
95 ACPI_STATUS
96 AcpiNsInitializeDevices (
97     UINT32                  Flags);
98 
99 
100 /*
101  * nsload -  Namespace loading
102  */
103 ACPI_STATUS
104 AcpiNsLoadNamespace (
105     void);
106 
107 ACPI_STATUS
108 AcpiNsLoadTable (
109     UINT32                  TableIndex,
110     ACPI_NAMESPACE_NODE     *Node);
111 
112 
113 /*
114  * nswalk - walk the namespace
115  */
116 ACPI_STATUS
117 AcpiNsWalkNamespace (
118     ACPI_OBJECT_TYPE        Type,
119     ACPI_HANDLE             StartObject,
120     UINT32                  MaxDepth,
121     UINT32                  Flags,
122     ACPI_WALK_CALLBACK      DescendingCallback,
123     ACPI_WALK_CALLBACK      AscendingCallback,
124     void                    *Context,
125     void                    **ReturnValue);
126 
127 ACPI_NAMESPACE_NODE *
128 AcpiNsGetNextNode (
129     ACPI_NAMESPACE_NODE     *Parent,
130     ACPI_NAMESPACE_NODE     *Child);
131 
132 ACPI_NAMESPACE_NODE *
133 AcpiNsGetNextNodeTyped (
134     ACPI_OBJECT_TYPE        Type,
135     ACPI_NAMESPACE_NODE     *Parent,
136     ACPI_NAMESPACE_NODE     *Child);
137 
138 /*
139  * nsparse - table parsing
140  */
141 ACPI_STATUS
142 AcpiNsParseTable (
143     UINT32                  TableIndex,
144     ACPI_NAMESPACE_NODE     *StartNode);
145 
146 ACPI_STATUS
147 AcpiNsExecuteTable (
148     UINT32                  TableIndex,
149     ACPI_NAMESPACE_NODE     *StartNode);
150 
151 ACPI_STATUS
152 AcpiNsOneCompleteParse (
153     UINT32                  PassNumber,
154     UINT32                  TableIndex,
155     ACPI_NAMESPACE_NODE     *StartNode);
156 
157 
158 /*
159  * nsaccess - Top-level namespace access
160  */
161 ACPI_STATUS
162 AcpiNsRootInitialize (
163     void);
164 
165 ACPI_STATUS
166 AcpiNsLookup (
167     ACPI_GENERIC_STATE      *ScopeInfo,
168     char                    *Name,
169     ACPI_OBJECT_TYPE        Type,
170     ACPI_INTERPRETER_MODE   InterpreterMode,
171     UINT32                  Flags,
172     ACPI_WALK_STATE         *WalkState,
173     ACPI_NAMESPACE_NODE     **RetNode);
174 
175 
176 /*
177  * nsalloc - Named object allocation/deallocation
178  */
179 ACPI_NAMESPACE_NODE *
180 AcpiNsCreateNode (
181     UINT32                  Name);
182 
183 void
184 AcpiNsDeleteNode (
185     ACPI_NAMESPACE_NODE     *Node);
186 
187 void
188 AcpiNsRemoveNode (
189     ACPI_NAMESPACE_NODE     *Node);
190 
191 void
192 AcpiNsDeleteNamespaceSubtree (
193     ACPI_NAMESPACE_NODE     *ParentHandle);
194 
195 void
196 AcpiNsDeleteNamespaceByOwner (
197     ACPI_OWNER_ID           OwnerId);
198 
199 void
200 AcpiNsDetachObject (
201     ACPI_NAMESPACE_NODE     *Node);
202 
203 void
204 AcpiNsDeleteChildren (
205     ACPI_NAMESPACE_NODE     *Parent);
206 
207 int
208 AcpiNsCompareNames (
209     char                    *Name1,
210     char                    *Name2);
211 
212 
213 /*
214  * nsconvert - Dynamic object conversion routines
215  */
216 ACPI_STATUS
217 AcpiNsConvertToInteger (
218     ACPI_OPERAND_OBJECT     *OriginalObject,
219     ACPI_OPERAND_OBJECT     **ReturnObject);
220 
221 ACPI_STATUS
222 AcpiNsConvertToString (
223     ACPI_OPERAND_OBJECT     *OriginalObject,
224     ACPI_OPERAND_OBJECT     **ReturnObject);
225 
226 ACPI_STATUS
227 AcpiNsConvertToBuffer (
228     ACPI_OPERAND_OBJECT     *OriginalObject,
229     ACPI_OPERAND_OBJECT     **ReturnObject);
230 
231 ACPI_STATUS
232 AcpiNsConvertToUnicode (
233     ACPI_NAMESPACE_NODE     *Scope,
234     ACPI_OPERAND_OBJECT     *OriginalObject,
235     ACPI_OPERAND_OBJECT     **ReturnObject);
236 
237 ACPI_STATUS
238 AcpiNsConvertToResource (
239     ACPI_NAMESPACE_NODE     *Scope,
240     ACPI_OPERAND_OBJECT     *OriginalObject,
241     ACPI_OPERAND_OBJECT     **ReturnObject);
242 
243 ACPI_STATUS
244 AcpiNsConvertToReference (
245     ACPI_NAMESPACE_NODE     *Scope,
246     ACPI_OPERAND_OBJECT     *OriginalObject,
247     ACPI_OPERAND_OBJECT     **ReturnObject);
248 
249 
250 /*
251  * nsdump - Namespace dump/print utilities
252  */
253 void
254 AcpiNsDumpTables (
255     ACPI_HANDLE             SearchBase,
256     UINT32                  MaxDepth);
257 
258 void
259 AcpiNsDumpEntry (
260     ACPI_HANDLE             Handle,
261     UINT32                  DebugLevel);
262 
263 void
264 AcpiNsDumpPathname (
265     ACPI_HANDLE             Handle,
266     const char              *Msg,
267     UINT32                  Level,
268     UINT32                  Component);
269 
270 void
271 AcpiNsPrintPathname (
272     UINT32                  NumSegments,
273     const char              *Pathname);
274 
275 ACPI_STATUS
276 AcpiNsDumpOneObject (
277     ACPI_HANDLE             ObjHandle,
278     UINT32                  Level,
279     void                    *Context,
280     void                    **ReturnValue);
281 
282 void
283 AcpiNsDumpObjects (
284     ACPI_OBJECT_TYPE        Type,
285     UINT8                   DisplayType,
286     UINT32                  MaxDepth,
287     ACPI_OWNER_ID           OwnerId,
288     ACPI_HANDLE             StartHandle);
289 
290 void
291 AcpiNsDumpObjectPaths (
292     ACPI_OBJECT_TYPE        Type,
293     UINT8                   DisplayType,
294     UINT32                  MaxDepth,
295     ACPI_OWNER_ID           OwnerId,
296     ACPI_HANDLE             StartHandle);
297 
298 
299 /*
300  * nseval - Namespace evaluation functions
301  */
302 ACPI_STATUS
303 AcpiNsEvaluate (
304     ACPI_EVALUATE_INFO      *Info);
305 
306 void
307 AcpiNsExecModuleCodeList (
308     void);
309 
310 
311 /*
312  * nsarguments - Argument count/type checking for predefined/reserved names
313  */
314 void
315 AcpiNsCheckArgumentCount (
316     char                        *Pathname,
317     ACPI_NAMESPACE_NODE         *Node,
318     UINT32                      UserParamCount,
319     const ACPI_PREDEFINED_INFO  *Info);
320 
321 void
322 AcpiNsCheckAcpiCompliance (
323     char                        *Pathname,
324     ACPI_NAMESPACE_NODE         *Node,
325     const ACPI_PREDEFINED_INFO  *Predefined);
326 
327 void
328 AcpiNsCheckArgumentTypes (
329     ACPI_EVALUATE_INFO          *Info);
330 
331 
332 /*
333  * nspredef - Return value checking for predefined/reserved names
334  */
335 ACPI_STATUS
336 AcpiNsCheckReturnValue (
337     ACPI_NAMESPACE_NODE         *Node,
338     ACPI_EVALUATE_INFO          *Info,
339     UINT32                      UserParamCount,
340     ACPI_STATUS                 ReturnStatus,
341     ACPI_OPERAND_OBJECT         **ReturnObject);
342 
343 ACPI_STATUS
344 AcpiNsCheckObjectType (
345     ACPI_EVALUATE_INFO          *Info,
346     ACPI_OPERAND_OBJECT         **ReturnObjectPtr,
347     UINT32                      ExpectedBtypes,
348     UINT32                      PackageIndex);
349 
350 
351 /*
352  * nsprepkg - Validation of predefined name packages
353  */
354 ACPI_STATUS
355 AcpiNsCheckPackage (
356     ACPI_EVALUATE_INFO          *Info,
357     ACPI_OPERAND_OBJECT         **ReturnObjectPtr);
358 
359 
360 /*
361  * nsnames - Name and Scope manipulation
362  */
363 UINT32
364 AcpiNsOpensScope (
365     ACPI_OBJECT_TYPE        Type);
366 
367 char *
368 AcpiNsGetExternalPathname (
369     ACPI_NAMESPACE_NODE     *Node);
370 
371 UINT32
372 AcpiNsBuildNormalizedPath (
373     ACPI_NAMESPACE_NODE     *Node,
374     char                    *FullPath,
375     UINT32                  PathSize,
376     BOOLEAN                 NoTrailing);
377 
378 char *
379 AcpiNsGetNormalizedPathname (
380     ACPI_NAMESPACE_NODE     *Node,
381     BOOLEAN                 NoTrailing);
382 
383 char *
384 AcpiNsNameOfCurrentScope (
385     ACPI_WALK_STATE         *WalkState);
386 
387 ACPI_STATUS
388 AcpiNsHandleToName (
389     ACPI_HANDLE             TargetHandle,
390     ACPI_BUFFER             *Buffer);
391 
392 ACPI_STATUS
393 AcpiNsHandleToPathname (
394     ACPI_HANDLE             TargetHandle,
395     ACPI_BUFFER             *Buffer,
396     BOOLEAN                 NoTrailing);
397 
398 BOOLEAN
399 AcpiNsPatternMatch (
400     ACPI_NAMESPACE_NODE     *ObjNode,
401     char                    *SearchFor);
402 
403 ACPI_STATUS
404 AcpiNsGetNodeUnlocked (
405     ACPI_NAMESPACE_NODE     *PrefixNode,
406     const char              *ExternalPathname,
407     UINT32                  Flags,
408     ACPI_NAMESPACE_NODE     **OutNode);
409 
410 ACPI_STATUS
411 AcpiNsGetNode (
412     ACPI_NAMESPACE_NODE     *PrefixNode,
413     const char              *ExternalPathname,
414     UINT32                  Flags,
415     ACPI_NAMESPACE_NODE     **OutNode);
416 
417 ACPI_SIZE
418 AcpiNsGetPathnameLength (
419     ACPI_NAMESPACE_NODE     *Node);
420 
421 
422 /*
423  * nsobject - Object management for namespace nodes
424  */
425 ACPI_STATUS
426 AcpiNsAttachObject (
427     ACPI_NAMESPACE_NODE     *Node,
428     ACPI_OPERAND_OBJECT     *Object,
429     ACPI_OBJECT_TYPE        Type);
430 
431 ACPI_OPERAND_OBJECT *
432 AcpiNsGetAttachedObject (
433     ACPI_NAMESPACE_NODE     *Node);
434 
435 ACPI_OPERAND_OBJECT *
436 AcpiNsGetSecondaryObject (
437     ACPI_OPERAND_OBJECT     *ObjDesc);
438 
439 ACPI_STATUS
440 AcpiNsAttachData (
441     ACPI_NAMESPACE_NODE     *Node,
442     ACPI_OBJECT_HANDLER     Handler,
443     void                    *Data);
444 
445 ACPI_STATUS
446 AcpiNsDetachData (
447     ACPI_NAMESPACE_NODE     *Node,
448     ACPI_OBJECT_HANDLER     Handler);
449 
450 ACPI_STATUS
451 AcpiNsGetAttachedData (
452     ACPI_NAMESPACE_NODE     *Node,
453     ACPI_OBJECT_HANDLER     Handler,
454     void                    **Data);
455 
456 
457 /*
458  * nsrepair - General return object repair for all
459  * predefined methods/objects
460  */
461 ACPI_STATUS
462 AcpiNsSimpleRepair (
463     ACPI_EVALUATE_INFO      *Info,
464     UINT32                  ExpectedBtypes,
465     UINT32                  PackageIndex,
466     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
467 
468 ACPI_STATUS
469 AcpiNsWrapWithPackage (
470     ACPI_EVALUATE_INFO      *Info,
471     ACPI_OPERAND_OBJECT     *OriginalObject,
472     ACPI_OPERAND_OBJECT     **ObjDescPtr);
473 
474 ACPI_STATUS
475 AcpiNsRepairNullElement (
476     ACPI_EVALUATE_INFO      *Info,
477     UINT32                  ExpectedBtypes,
478     UINT32                  PackageIndex,
479     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
480 
481 void
482 AcpiNsRemoveNullElements (
483     ACPI_EVALUATE_INFO      *Info,
484     UINT8                   PackageType,
485     ACPI_OPERAND_OBJECT     *ObjDesc);
486 
487 
488 /*
489  * nsrepair2 - Return object repair for specific
490  * predefined methods/objects
491  */
492 ACPI_STATUS
493 AcpiNsComplexRepairs (
494     ACPI_EVALUATE_INFO      *Info,
495     ACPI_NAMESPACE_NODE     *Node,
496     ACPI_STATUS             ValidateStatus,
497     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
498 
499 
500 /*
501  * nssearch - Namespace searching and entry
502  */
503 ACPI_STATUS
504 AcpiNsSearchAndEnter (
505     UINT32                  EntryName,
506     ACPI_WALK_STATE         *WalkState,
507     ACPI_NAMESPACE_NODE     *Node,
508     ACPI_INTERPRETER_MODE   InterpreterMode,
509     ACPI_OBJECT_TYPE        Type,
510     UINT32                  Flags,
511     ACPI_NAMESPACE_NODE     **RetNode);
512 
513 ACPI_STATUS
514 AcpiNsSearchOneScope (
515     UINT32                  EntryName,
516     ACPI_NAMESPACE_NODE     *Node,
517     ACPI_OBJECT_TYPE        Type,
518     ACPI_NAMESPACE_NODE     **RetNode);
519 
520 void
521 AcpiNsInstallNode (
522     ACPI_WALK_STATE         *WalkState,
523     ACPI_NAMESPACE_NODE     *ParentNode,
524     ACPI_NAMESPACE_NODE     *Node,
525     ACPI_OBJECT_TYPE        Type);
526 
527 
528 /*
529  * nsutils - Utility functions
530  */
531 ACPI_OBJECT_TYPE
532 AcpiNsGetType (
533     ACPI_NAMESPACE_NODE     *Node);
534 
535 UINT32
536 AcpiNsLocal (
537     ACPI_OBJECT_TYPE        Type);
538 
539 void
540 AcpiNsPrintNodePathname (
541     ACPI_NAMESPACE_NODE     *Node,
542     const char              *Msg);
543 
544 ACPI_STATUS
545 AcpiNsBuildInternalName (
546     ACPI_NAMESTRING_INFO    *Info);
547 
548 void
549 AcpiNsGetInternalNameLength (
550     ACPI_NAMESTRING_INFO    *Info);
551 
552 ACPI_STATUS
553 AcpiNsInternalizeName (
554     const char              *DottedName,
555     char                    **ConvertedName);
556 
557 ACPI_STATUS
558 AcpiNsExternalizeName (
559     UINT32                  InternalNameLength,
560     const char              *InternalName,
561     UINT32                  *ConvertedNameLength,
562     char                    **ConvertedName);
563 
564 ACPI_NAMESPACE_NODE *
565 AcpiNsValidateHandle (
566     ACPI_HANDLE             Handle);
567 
568 void
569 AcpiNsTerminate (
570     void);
571 
572 #endif /* __ACNAMESP_H__ */
573