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