1 /******************************************************************************
2  *
3  * Name: acnamesp.h - Namespace subcomponent prototypes and defines
4  *
5  *****************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2020, 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 void
383 AcpiNsNormalizePathname (
384     char                    *OriginalPath);
385 
386 char *
387 AcpiNsGetNormalizedPathname (
388     ACPI_NAMESPACE_NODE     *Node,
389     BOOLEAN                 NoTrailing);
390 
391 char *
392 AcpiNsBuildPrefixedPathname (
393     ACPI_GENERIC_STATE      *PrefixScope,
394     const char              *InternalPath);
395 
396 char *
397 AcpiNsNameOfCurrentScope (
398     ACPI_WALK_STATE         *WalkState);
399 
400 ACPI_STATUS
401 AcpiNsHandleToName (
402     ACPI_HANDLE             TargetHandle,
403     ACPI_BUFFER             *Buffer);
404 
405 ACPI_STATUS
406 AcpiNsHandleToPathname (
407     ACPI_HANDLE             TargetHandle,
408     ACPI_BUFFER             *Buffer,
409     BOOLEAN                 NoTrailing);
410 
411 BOOLEAN
412 AcpiNsPatternMatch (
413     ACPI_NAMESPACE_NODE     *ObjNode,
414     char                    *SearchFor);
415 
416 ACPI_STATUS
417 AcpiNsGetNodeUnlocked (
418     ACPI_NAMESPACE_NODE     *PrefixNode,
419     const char              *ExternalPathname,
420     UINT32                  Flags,
421     ACPI_NAMESPACE_NODE     **OutNode);
422 
423 ACPI_STATUS
424 AcpiNsGetNode (
425     ACPI_NAMESPACE_NODE     *PrefixNode,
426     const char              *ExternalPathname,
427     UINT32                  Flags,
428     ACPI_NAMESPACE_NODE     **OutNode);
429 
430 ACPI_SIZE
431 AcpiNsGetPathnameLength (
432     ACPI_NAMESPACE_NODE     *Node);
433 
434 
435 /*
436  * nsobject - Object management for namespace nodes
437  */
438 ACPI_STATUS
439 AcpiNsAttachObject (
440     ACPI_NAMESPACE_NODE     *Node,
441     ACPI_OPERAND_OBJECT     *Object,
442     ACPI_OBJECT_TYPE        Type);
443 
444 ACPI_OPERAND_OBJECT *
445 AcpiNsGetAttachedObject (
446     ACPI_NAMESPACE_NODE     *Node);
447 
448 ACPI_OPERAND_OBJECT *
449 AcpiNsGetSecondaryObject (
450     ACPI_OPERAND_OBJECT     *ObjDesc);
451 
452 ACPI_STATUS
453 AcpiNsAttachData (
454     ACPI_NAMESPACE_NODE     *Node,
455     ACPI_OBJECT_HANDLER     Handler,
456     void                    *Data);
457 
458 ACPI_STATUS
459 AcpiNsDetachData (
460     ACPI_NAMESPACE_NODE     *Node,
461     ACPI_OBJECT_HANDLER     Handler);
462 
463 ACPI_STATUS
464 AcpiNsGetAttachedData (
465     ACPI_NAMESPACE_NODE     *Node,
466     ACPI_OBJECT_HANDLER     Handler,
467     void                    **Data);
468 
469 
470 /*
471  * nsrepair - General return object repair for all
472  * predefined methods/objects
473  */
474 ACPI_STATUS
475 AcpiNsSimpleRepair (
476     ACPI_EVALUATE_INFO      *Info,
477     UINT32                  ExpectedBtypes,
478     UINT32                  PackageIndex,
479     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
480 
481 ACPI_STATUS
482 AcpiNsWrapWithPackage (
483     ACPI_EVALUATE_INFO      *Info,
484     ACPI_OPERAND_OBJECT     *OriginalObject,
485     ACPI_OPERAND_OBJECT     **ObjDescPtr);
486 
487 ACPI_STATUS
488 AcpiNsRepairNullElement (
489     ACPI_EVALUATE_INFO      *Info,
490     UINT32                  ExpectedBtypes,
491     UINT32                  PackageIndex,
492     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
493 
494 void
495 AcpiNsRemoveNullElements (
496     ACPI_EVALUATE_INFO      *Info,
497     UINT8                   PackageType,
498     ACPI_OPERAND_OBJECT     *ObjDesc);
499 
500 
501 /*
502  * nsrepair2 - Return object repair for specific
503  * predefined methods/objects
504  */
505 ACPI_STATUS
506 AcpiNsComplexRepairs (
507     ACPI_EVALUATE_INFO      *Info,
508     ACPI_NAMESPACE_NODE     *Node,
509     ACPI_STATUS             ValidateStatus,
510     ACPI_OPERAND_OBJECT     **ReturnObjectPtr);
511 
512 
513 /*
514  * nssearch - Namespace searching and entry
515  */
516 ACPI_STATUS
517 AcpiNsSearchAndEnter (
518     UINT32                  EntryName,
519     ACPI_WALK_STATE         *WalkState,
520     ACPI_NAMESPACE_NODE     *Node,
521     ACPI_INTERPRETER_MODE   InterpreterMode,
522     ACPI_OBJECT_TYPE        Type,
523     UINT32                  Flags,
524     ACPI_NAMESPACE_NODE     **RetNode);
525 
526 ACPI_STATUS
527 AcpiNsSearchOneScope (
528     UINT32                  EntryName,
529     ACPI_NAMESPACE_NODE     *Node,
530     ACPI_OBJECT_TYPE        Type,
531     ACPI_NAMESPACE_NODE     **RetNode);
532 
533 void
534 AcpiNsInstallNode (
535     ACPI_WALK_STATE         *WalkState,
536     ACPI_NAMESPACE_NODE     *ParentNode,
537     ACPI_NAMESPACE_NODE     *Node,
538     ACPI_OBJECT_TYPE        Type);
539 
540 
541 /*
542  * nsutils - Utility functions
543  */
544 ACPI_OBJECT_TYPE
545 AcpiNsGetType (
546     ACPI_NAMESPACE_NODE     *Node);
547 
548 UINT32
549 AcpiNsLocal (
550     ACPI_OBJECT_TYPE        Type);
551 
552 void
553 AcpiNsPrintNodePathname (
554     ACPI_NAMESPACE_NODE     *Node,
555     const char              *Msg);
556 
557 ACPI_STATUS
558 AcpiNsBuildInternalName (
559     ACPI_NAMESTRING_INFO    *Info);
560 
561 void
562 AcpiNsGetInternalNameLength (
563     ACPI_NAMESTRING_INFO    *Info);
564 
565 ACPI_STATUS
566 AcpiNsInternalizeName (
567     const char              *DottedName,
568     char                    **ConvertedName);
569 
570 ACPI_STATUS
571 AcpiNsExternalizeName (
572     UINT32                  InternalNameLength,
573     const char              *InternalName,
574     UINT32                  *ConvertedNameLength,
575     char                    **ConvertedName);
576 
577 ACPI_NAMESPACE_NODE *
578 AcpiNsValidateHandle (
579     ACPI_HANDLE             Handle);
580 
581 void
582 AcpiNsTerminate (
583     void);
584 
585 #endif /* __ACNAMESP_H__ */
586