nswalk.c revision 1.1.1.9 1 1.1 jruoho /******************************************************************************
2 1.1 jruoho *
3 1.1 jruoho * Module Name: nswalk - Functions for walking the ACPI namespace
4 1.1 jruoho *
5 1.1 jruoho *****************************************************************************/
6 1.1 jruoho
7 1.1.1.2 jruoho /*
8 1.1.1.9 christos * Copyright (C) 2000 - 2019, Intel Corp.
9 1.1 jruoho * All rights reserved.
10 1.1 jruoho *
11 1.1.1.2 jruoho * Redistribution and use in source and binary forms, with or without
12 1.1.1.2 jruoho * modification, are permitted provided that the following conditions
13 1.1.1.2 jruoho * are met:
14 1.1.1.2 jruoho * 1. Redistributions of source code must retain the above copyright
15 1.1.1.2 jruoho * notice, this list of conditions, and the following disclaimer,
16 1.1.1.2 jruoho * without modification.
17 1.1.1.2 jruoho * 2. Redistributions in binary form must reproduce at minimum a disclaimer
18 1.1.1.2 jruoho * substantially similar to the "NO WARRANTY" disclaimer below
19 1.1.1.2 jruoho * ("Disclaimer") and any redistribution must be conditioned upon
20 1.1.1.2 jruoho * including a substantially similar Disclaimer requirement for further
21 1.1.1.2 jruoho * binary redistribution.
22 1.1.1.2 jruoho * 3. Neither the names of the above-listed copyright holders nor the names
23 1.1.1.2 jruoho * of any contributors may be used to endorse or promote products derived
24 1.1.1.2 jruoho * from this software without specific prior written permission.
25 1.1.1.2 jruoho *
26 1.1.1.2 jruoho * Alternatively, this software may be distributed under the terms of the
27 1.1.1.2 jruoho * GNU General Public License ("GPL") version 2 as published by the Free
28 1.1.1.2 jruoho * Software Foundation.
29 1.1.1.2 jruoho *
30 1.1.1.2 jruoho * NO WARRANTY
31 1.1.1.2 jruoho * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 1.1.1.2 jruoho * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 1.1.1.2 jruoho * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
34 1.1.1.2 jruoho * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 1.1.1.2 jruoho * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
36 1.1.1.2 jruoho * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
37 1.1.1.2 jruoho * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
38 1.1.1.2 jruoho * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 1.1.1.2 jruoho * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
40 1.1.1.2 jruoho * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
41 1.1.1.2 jruoho * POSSIBILITY OF SUCH DAMAGES.
42 1.1.1.2 jruoho */
43 1.1 jruoho
44 1.1 jruoho #include "acpi.h"
45 1.1 jruoho #include "accommon.h"
46 1.1 jruoho #include "acnamesp.h"
47 1.1 jruoho
48 1.1 jruoho
49 1.1 jruoho #define _COMPONENT ACPI_NAMESPACE
50 1.1 jruoho ACPI_MODULE_NAME ("nswalk")
51 1.1 jruoho
52 1.1 jruoho
53 1.1 jruoho /*******************************************************************************
54 1.1 jruoho *
55 1.1 jruoho * FUNCTION: AcpiNsGetNextNode
56 1.1 jruoho *
57 1.1 jruoho * PARAMETERS: ParentNode - Parent node whose children we are
58 1.1 jruoho * getting
59 1.1 jruoho * ChildNode - Previous child that was found.
60 1.1 jruoho * The NEXT child will be returned
61 1.1 jruoho *
62 1.1 jruoho * RETURN: ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
63 1.1 jruoho * none is found.
64 1.1 jruoho *
65 1.1.1.3 christos * DESCRIPTION: Return the next peer node within the namespace. If Handle
66 1.1.1.3 christos * is valid, Scope is ignored. Otherwise, the first node
67 1.1 jruoho * within Scope is returned.
68 1.1 jruoho *
69 1.1 jruoho ******************************************************************************/
70 1.1 jruoho
71 1.1 jruoho ACPI_NAMESPACE_NODE *
72 1.1 jruoho AcpiNsGetNextNode (
73 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode,
74 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode)
75 1.1 jruoho {
76 1.1 jruoho ACPI_FUNCTION_ENTRY ();
77 1.1 jruoho
78 1.1 jruoho
79 1.1 jruoho if (!ChildNode)
80 1.1 jruoho {
81 1.1 jruoho /* It's really the parent's _scope_ that we want */
82 1.1 jruoho
83 1.1 jruoho return (ParentNode->Child);
84 1.1 jruoho }
85 1.1 jruoho
86 1.1 jruoho /* Otherwise just return the next peer */
87 1.1 jruoho
88 1.1 jruoho return (ChildNode->Peer);
89 1.1 jruoho }
90 1.1 jruoho
91 1.1 jruoho
92 1.1 jruoho /*******************************************************************************
93 1.1 jruoho *
94 1.1 jruoho * FUNCTION: AcpiNsGetNextNodeTyped
95 1.1 jruoho *
96 1.1 jruoho * PARAMETERS: Type - Type of node to be searched for
97 1.1 jruoho * ParentNode - Parent node whose children we are
98 1.1 jruoho * getting
99 1.1 jruoho * ChildNode - Previous child that was found.
100 1.1 jruoho * The NEXT child will be returned
101 1.1 jruoho *
102 1.1 jruoho * RETURN: ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
103 1.1 jruoho * none is found.
104 1.1 jruoho *
105 1.1.1.3 christos * DESCRIPTION: Return the next peer node within the namespace. If Handle
106 1.1.1.3 christos * is valid, Scope is ignored. Otherwise, the first node
107 1.1 jruoho * within Scope is returned.
108 1.1 jruoho *
109 1.1 jruoho ******************************************************************************/
110 1.1 jruoho
111 1.1 jruoho ACPI_NAMESPACE_NODE *
112 1.1 jruoho AcpiNsGetNextNodeTyped (
113 1.1 jruoho ACPI_OBJECT_TYPE Type,
114 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode,
115 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode)
116 1.1 jruoho {
117 1.1 jruoho ACPI_NAMESPACE_NODE *NextNode = NULL;
118 1.1 jruoho
119 1.1 jruoho
120 1.1 jruoho ACPI_FUNCTION_ENTRY ();
121 1.1 jruoho
122 1.1 jruoho
123 1.1 jruoho NextNode = AcpiNsGetNextNode (ParentNode, ChildNode);
124 1.1 jruoho
125 1.1 jruoho /* If any type is OK, we are done */
126 1.1 jruoho
127 1.1 jruoho if (Type == ACPI_TYPE_ANY)
128 1.1 jruoho {
129 1.1 jruoho /* NextNode is NULL if we are at the end-of-list */
130 1.1 jruoho
131 1.1 jruoho return (NextNode);
132 1.1 jruoho }
133 1.1 jruoho
134 1.1 jruoho /* Must search for the node -- but within this scope only */
135 1.1 jruoho
136 1.1 jruoho while (NextNode)
137 1.1 jruoho {
138 1.1 jruoho /* If type matches, we are done */
139 1.1 jruoho
140 1.1 jruoho if (NextNode->Type == Type)
141 1.1 jruoho {
142 1.1 jruoho return (NextNode);
143 1.1 jruoho }
144 1.1 jruoho
145 1.1 jruoho /* Otherwise, move on to the next peer node */
146 1.1 jruoho
147 1.1 jruoho NextNode = NextNode->Peer;
148 1.1 jruoho }
149 1.1 jruoho
150 1.1 jruoho /* Not found */
151 1.1 jruoho
152 1.1 jruoho return (NULL);
153 1.1 jruoho }
154 1.1 jruoho
155 1.1 jruoho
156 1.1 jruoho /*******************************************************************************
157 1.1 jruoho *
158 1.1 jruoho * FUNCTION: AcpiNsWalkNamespace
159 1.1 jruoho *
160 1.1 jruoho * PARAMETERS: Type - ACPI_OBJECT_TYPE to search for
161 1.1 jruoho * StartNode - Handle in namespace where search begins
162 1.1 jruoho * MaxDepth - Depth to which search is to reach
163 1.1 jruoho * Flags - Whether to unlock the NS before invoking
164 1.1 jruoho * the callback routine
165 1.1.1.3 christos * DescendingCallback - Called during tree descent
166 1.1 jruoho * when an object of "Type" is found
167 1.1.1.3 christos * AscendingCallback - Called during tree ascent
168 1.1 jruoho * when an object of "Type" is found
169 1.1 jruoho * Context - Passed to user function(s) above
170 1.1 jruoho * ReturnValue - from the UserFunction if terminated
171 1.1 jruoho * early. Otherwise, returns NULL.
172 1.1 jruoho * RETURNS: Status
173 1.1 jruoho *
174 1.1 jruoho * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
175 1.1 jruoho * starting (and ending) at the node specified by StartHandle.
176 1.1 jruoho * The callback function is called whenever a node that matches
177 1.1 jruoho * the type parameter is found. If the callback function returns
178 1.1 jruoho * a non-zero value, the search is terminated immediately and
179 1.1 jruoho * this value is returned to the caller.
180 1.1 jruoho *
181 1.1 jruoho * The point of this procedure is to provide a generic namespace
182 1.1 jruoho * walk routine that can be called from multiple places to
183 1.1 jruoho * provide multiple services; the callback function(s) can be
184 1.1 jruoho * tailored to each task, whether it is a print function,
185 1.1 jruoho * a compare function, etc.
186 1.1 jruoho *
187 1.1 jruoho ******************************************************************************/
188 1.1 jruoho
189 1.1 jruoho ACPI_STATUS
190 1.1 jruoho AcpiNsWalkNamespace (
191 1.1 jruoho ACPI_OBJECT_TYPE Type,
192 1.1 jruoho ACPI_HANDLE StartNode,
193 1.1 jruoho UINT32 MaxDepth,
194 1.1 jruoho UINT32 Flags,
195 1.1.1.3 christos ACPI_WALK_CALLBACK DescendingCallback,
196 1.1.1.3 christos ACPI_WALK_CALLBACK AscendingCallback,
197 1.1 jruoho void *Context,
198 1.1 jruoho void **ReturnValue)
199 1.1 jruoho {
200 1.1 jruoho ACPI_STATUS Status;
201 1.1 jruoho ACPI_STATUS MutexStatus;
202 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode;
203 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode;
204 1.1 jruoho ACPI_OBJECT_TYPE ChildType;
205 1.1 jruoho UINT32 Level;
206 1.1 jruoho BOOLEAN NodePreviouslyVisited = FALSE;
207 1.1 jruoho
208 1.1 jruoho
209 1.1 jruoho ACPI_FUNCTION_TRACE (NsWalkNamespace);
210 1.1 jruoho
211 1.1 jruoho
212 1.1 jruoho /* Special case for the namespace Root Node */
213 1.1 jruoho
214 1.1 jruoho if (StartNode == ACPI_ROOT_OBJECT)
215 1.1 jruoho {
216 1.1 jruoho StartNode = AcpiGbl_RootNode;
217 1.1 jruoho }
218 1.1 jruoho
219 1.1 jruoho /* Null child means "get first node" */
220 1.1 jruoho
221 1.1.1.6 christos ParentNode = StartNode;
222 1.1.1.6 christos ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
223 1.1.1.6 christos ChildType = ACPI_TYPE_ANY;
224 1.1.1.6 christos Level = 1;
225 1.1 jruoho
226 1.1 jruoho /*
227 1.1 jruoho * Traverse the tree of nodes until we bubble back up to where we
228 1.1 jruoho * started. When Level is zero, the loop is done because we have
229 1.1 jruoho * bubbled up to (and passed) the original parent handle (StartEntry)
230 1.1 jruoho */
231 1.1 jruoho while (Level > 0 && ChildNode)
232 1.1 jruoho {
233 1.1 jruoho Status = AE_OK;
234 1.1 jruoho
235 1.1 jruoho /* Found next child, get the type if we are not searching for ANY */
236 1.1 jruoho
237 1.1 jruoho if (Type != ACPI_TYPE_ANY)
238 1.1 jruoho {
239 1.1 jruoho ChildType = ChildNode->Type;
240 1.1 jruoho }
241 1.1 jruoho
242 1.1 jruoho /*
243 1.1 jruoho * Ignore all temporary namespace nodes (created during control
244 1.1 jruoho * method execution) unless told otherwise. These temporary nodes
245 1.1 jruoho * can cause a race condition because they can be deleted during
246 1.1 jruoho * the execution of the user function (if the namespace is
247 1.1 jruoho * unlocked before invocation of the user function.) Only the
248 1.1 jruoho * debugger namespace dump will examine the temporary nodes.
249 1.1 jruoho */
250 1.1 jruoho if ((ChildNode->Flags & ANOBJ_TEMPORARY) &&
251 1.1 jruoho !(Flags & ACPI_NS_WALK_TEMP_NODES))
252 1.1 jruoho {
253 1.1 jruoho Status = AE_CTRL_DEPTH;
254 1.1 jruoho }
255 1.1 jruoho
256 1.1 jruoho /* Type must match requested type */
257 1.1 jruoho
258 1.1 jruoho else if (ChildType == Type)
259 1.1 jruoho {
260 1.1 jruoho /*
261 1.1 jruoho * Found a matching node, invoke the user callback function.
262 1.1 jruoho * Unlock the namespace if flag is set.
263 1.1 jruoho */
264 1.1 jruoho if (Flags & ACPI_NS_WALK_UNLOCK)
265 1.1 jruoho {
266 1.1 jruoho MutexStatus = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
267 1.1 jruoho if (ACPI_FAILURE (MutexStatus))
268 1.1 jruoho {
269 1.1 jruoho return_ACPI_STATUS (MutexStatus);
270 1.1 jruoho }
271 1.1 jruoho }
272 1.1 jruoho
273 1.1 jruoho /*
274 1.1.1.3 christos * Invoke the user function, either descending, ascending,
275 1.1 jruoho * or both.
276 1.1 jruoho */
277 1.1 jruoho if (!NodePreviouslyVisited)
278 1.1 jruoho {
279 1.1.1.3 christos if (DescendingCallback)
280 1.1 jruoho {
281 1.1.1.3 christos Status = DescendingCallback (ChildNode, Level,
282 1.1.1.6 christos Context, ReturnValue);
283 1.1 jruoho }
284 1.1 jruoho }
285 1.1 jruoho else
286 1.1 jruoho {
287 1.1.1.3 christos if (AscendingCallback)
288 1.1 jruoho {
289 1.1.1.3 christos Status = AscendingCallback (ChildNode, Level,
290 1.1.1.6 christos Context, ReturnValue);
291 1.1 jruoho }
292 1.1 jruoho }
293 1.1 jruoho
294 1.1 jruoho if (Flags & ACPI_NS_WALK_UNLOCK)
295 1.1 jruoho {
296 1.1 jruoho MutexStatus = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
297 1.1 jruoho if (ACPI_FAILURE (MutexStatus))
298 1.1 jruoho {
299 1.1 jruoho return_ACPI_STATUS (MutexStatus);
300 1.1 jruoho }
301 1.1 jruoho }
302 1.1 jruoho
303 1.1 jruoho switch (Status)
304 1.1 jruoho {
305 1.1 jruoho case AE_OK:
306 1.1 jruoho case AE_CTRL_DEPTH:
307 1.1 jruoho
308 1.1 jruoho /* Just keep going */
309 1.1 jruoho break;
310 1.1 jruoho
311 1.1 jruoho case AE_CTRL_TERMINATE:
312 1.1 jruoho
313 1.1 jruoho /* Exit now, with OK status */
314 1.1 jruoho
315 1.1 jruoho return_ACPI_STATUS (AE_OK);
316 1.1 jruoho
317 1.1 jruoho default:
318 1.1 jruoho
319 1.1 jruoho /* All others are valid exceptions */
320 1.1 jruoho
321 1.1 jruoho return_ACPI_STATUS (Status);
322 1.1 jruoho }
323 1.1 jruoho }
324 1.1 jruoho
325 1.1 jruoho /*
326 1.1 jruoho * Depth first search: Attempt to go down another level in the
327 1.1.1.3 christos * namespace if we are allowed to. Don't go any further if we have
328 1.1 jruoho * reached the caller specified maximum depth or if the user
329 1.1 jruoho * function has specified that the maximum depth has been reached.
330 1.1 jruoho */
331 1.1 jruoho if (!NodePreviouslyVisited &&
332 1.1 jruoho (Level < MaxDepth) &&
333 1.1 jruoho (Status != AE_CTRL_DEPTH))
334 1.1 jruoho {
335 1.1 jruoho if (ChildNode->Child)
336 1.1 jruoho {
337 1.1 jruoho /* There is at least one child of this node, visit it */
338 1.1 jruoho
339 1.1 jruoho Level++;
340 1.1 jruoho ParentNode = ChildNode;
341 1.1 jruoho ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
342 1.1 jruoho continue;
343 1.1 jruoho }
344 1.1 jruoho }
345 1.1 jruoho
346 1.1 jruoho /* No more children, re-visit this node */
347 1.1 jruoho
348 1.1 jruoho if (!NodePreviouslyVisited)
349 1.1 jruoho {
350 1.1 jruoho NodePreviouslyVisited = TRUE;
351 1.1 jruoho continue;
352 1.1 jruoho }
353 1.1 jruoho
354 1.1 jruoho /* No more children, visit peers */
355 1.1 jruoho
356 1.1 jruoho ChildNode = AcpiNsGetNextNode (ParentNode, ChildNode);
357 1.1 jruoho if (ChildNode)
358 1.1 jruoho {
359 1.1 jruoho NodePreviouslyVisited = FALSE;
360 1.1 jruoho }
361 1.1 jruoho
362 1.1 jruoho /* No peers, re-visit parent */
363 1.1 jruoho
364 1.1 jruoho else
365 1.1 jruoho {
366 1.1 jruoho /*
367 1.1 jruoho * No more children of this node (AcpiNsGetNextNode failed), go
368 1.1 jruoho * back upwards in the namespace tree to the node's parent.
369 1.1 jruoho */
370 1.1 jruoho Level--;
371 1.1 jruoho ChildNode = ParentNode;
372 1.1 jruoho ParentNode = ParentNode->Parent;
373 1.1 jruoho
374 1.1 jruoho NodePreviouslyVisited = TRUE;
375 1.1 jruoho }
376 1.1 jruoho }
377 1.1 jruoho
378 1.1 jruoho /* Complete walk, not terminated by user function */
379 1.1 jruoho
380 1.1 jruoho return_ACPI_STATUS (AE_OK);
381 1.1 jruoho }
382