nswalk.c revision 1.1.1.4 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.4 christos * Copyright (C) 2000 - 2014, 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 #define __NSWALK_C__
45 1.1 jruoho
46 1.1 jruoho #include "acpi.h"
47 1.1 jruoho #include "accommon.h"
48 1.1 jruoho #include "acnamesp.h"
49 1.1 jruoho
50 1.1 jruoho
51 1.1 jruoho #define _COMPONENT ACPI_NAMESPACE
52 1.1 jruoho ACPI_MODULE_NAME ("nswalk")
53 1.1 jruoho
54 1.1 jruoho
55 1.1 jruoho /*******************************************************************************
56 1.1 jruoho *
57 1.1 jruoho * FUNCTION: AcpiNsGetNextNode
58 1.1 jruoho *
59 1.1 jruoho * PARAMETERS: ParentNode - Parent node whose children we are
60 1.1 jruoho * getting
61 1.1 jruoho * ChildNode - Previous child that was found.
62 1.1 jruoho * The NEXT child will be returned
63 1.1 jruoho *
64 1.1 jruoho * RETURN: ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
65 1.1 jruoho * none is found.
66 1.1 jruoho *
67 1.1.1.3 christos * DESCRIPTION: Return the next peer node within the namespace. If Handle
68 1.1.1.3 christos * is valid, Scope is ignored. Otherwise, the first node
69 1.1 jruoho * within Scope is returned.
70 1.1 jruoho *
71 1.1 jruoho ******************************************************************************/
72 1.1 jruoho
73 1.1 jruoho ACPI_NAMESPACE_NODE *
74 1.1 jruoho AcpiNsGetNextNode (
75 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode,
76 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode)
77 1.1 jruoho {
78 1.1 jruoho ACPI_FUNCTION_ENTRY ();
79 1.1 jruoho
80 1.1 jruoho
81 1.1 jruoho if (!ChildNode)
82 1.1 jruoho {
83 1.1 jruoho /* It's really the parent's _scope_ that we want */
84 1.1 jruoho
85 1.1 jruoho return (ParentNode->Child);
86 1.1 jruoho }
87 1.1 jruoho
88 1.1 jruoho /* Otherwise just return the next peer */
89 1.1 jruoho
90 1.1 jruoho return (ChildNode->Peer);
91 1.1 jruoho }
92 1.1 jruoho
93 1.1 jruoho
94 1.1 jruoho /*******************************************************************************
95 1.1 jruoho *
96 1.1 jruoho * FUNCTION: AcpiNsGetNextNodeTyped
97 1.1 jruoho *
98 1.1 jruoho * PARAMETERS: Type - Type of node to be searched for
99 1.1 jruoho * ParentNode - Parent node whose children we are
100 1.1 jruoho * getting
101 1.1 jruoho * ChildNode - Previous child that was found.
102 1.1 jruoho * The NEXT child will be returned
103 1.1 jruoho *
104 1.1 jruoho * RETURN: ACPI_NAMESPACE_NODE - Pointer to the NEXT child or NULL if
105 1.1 jruoho * none is found.
106 1.1 jruoho *
107 1.1.1.3 christos * DESCRIPTION: Return the next peer node within the namespace. If Handle
108 1.1.1.3 christos * is valid, Scope is ignored. Otherwise, the first node
109 1.1 jruoho * within Scope is returned.
110 1.1 jruoho *
111 1.1 jruoho ******************************************************************************/
112 1.1 jruoho
113 1.1 jruoho ACPI_NAMESPACE_NODE *
114 1.1 jruoho AcpiNsGetNextNodeTyped (
115 1.1 jruoho ACPI_OBJECT_TYPE Type,
116 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode,
117 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode)
118 1.1 jruoho {
119 1.1 jruoho ACPI_NAMESPACE_NODE *NextNode = NULL;
120 1.1 jruoho
121 1.1 jruoho
122 1.1 jruoho ACPI_FUNCTION_ENTRY ();
123 1.1 jruoho
124 1.1 jruoho
125 1.1 jruoho NextNode = AcpiNsGetNextNode (ParentNode, ChildNode);
126 1.1 jruoho
127 1.1 jruoho /* If any type is OK, we are done */
128 1.1 jruoho
129 1.1 jruoho if (Type == ACPI_TYPE_ANY)
130 1.1 jruoho {
131 1.1 jruoho /* NextNode is NULL if we are at the end-of-list */
132 1.1 jruoho
133 1.1 jruoho return (NextNode);
134 1.1 jruoho }
135 1.1 jruoho
136 1.1 jruoho /* Must search for the node -- but within this scope only */
137 1.1 jruoho
138 1.1 jruoho while (NextNode)
139 1.1 jruoho {
140 1.1 jruoho /* If type matches, we are done */
141 1.1 jruoho
142 1.1 jruoho if (NextNode->Type == Type)
143 1.1 jruoho {
144 1.1 jruoho return (NextNode);
145 1.1 jruoho }
146 1.1 jruoho
147 1.1 jruoho /* Otherwise, move on to the next peer node */
148 1.1 jruoho
149 1.1 jruoho NextNode = NextNode->Peer;
150 1.1 jruoho }
151 1.1 jruoho
152 1.1 jruoho /* Not found */
153 1.1 jruoho
154 1.1 jruoho return (NULL);
155 1.1 jruoho }
156 1.1 jruoho
157 1.1 jruoho
158 1.1 jruoho /*******************************************************************************
159 1.1 jruoho *
160 1.1 jruoho * FUNCTION: AcpiNsWalkNamespace
161 1.1 jruoho *
162 1.1 jruoho * PARAMETERS: Type - ACPI_OBJECT_TYPE to search for
163 1.1 jruoho * StartNode - Handle in namespace where search begins
164 1.1 jruoho * MaxDepth - Depth to which search is to reach
165 1.1 jruoho * Flags - Whether to unlock the NS before invoking
166 1.1 jruoho * the callback routine
167 1.1.1.3 christos * DescendingCallback - Called during tree descent
168 1.1 jruoho * when an object of "Type" is found
169 1.1.1.3 christos * AscendingCallback - Called during tree ascent
170 1.1 jruoho * when an object of "Type" is found
171 1.1 jruoho * Context - Passed to user function(s) above
172 1.1 jruoho * ReturnValue - from the UserFunction if terminated
173 1.1 jruoho * early. Otherwise, returns NULL.
174 1.1 jruoho * RETURNS: Status
175 1.1 jruoho *
176 1.1 jruoho * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
177 1.1 jruoho * starting (and ending) at the node specified by StartHandle.
178 1.1 jruoho * The callback function is called whenever a node that matches
179 1.1 jruoho * the type parameter is found. If the callback function returns
180 1.1 jruoho * a non-zero value, the search is terminated immediately and
181 1.1 jruoho * this value is returned to the caller.
182 1.1 jruoho *
183 1.1 jruoho * The point of this procedure is to provide a generic namespace
184 1.1 jruoho * walk routine that can be called from multiple places to
185 1.1 jruoho * provide multiple services; the callback function(s) can be
186 1.1 jruoho * tailored to each task, whether it is a print function,
187 1.1 jruoho * a compare function, etc.
188 1.1 jruoho *
189 1.1 jruoho ******************************************************************************/
190 1.1 jruoho
191 1.1 jruoho ACPI_STATUS
192 1.1 jruoho AcpiNsWalkNamespace (
193 1.1 jruoho ACPI_OBJECT_TYPE Type,
194 1.1 jruoho ACPI_HANDLE StartNode,
195 1.1 jruoho UINT32 MaxDepth,
196 1.1 jruoho UINT32 Flags,
197 1.1.1.3 christos ACPI_WALK_CALLBACK DescendingCallback,
198 1.1.1.3 christos ACPI_WALK_CALLBACK AscendingCallback,
199 1.1 jruoho void *Context,
200 1.1 jruoho void **ReturnValue)
201 1.1 jruoho {
202 1.1 jruoho ACPI_STATUS Status;
203 1.1 jruoho ACPI_STATUS MutexStatus;
204 1.1 jruoho ACPI_NAMESPACE_NODE *ChildNode;
205 1.1 jruoho ACPI_NAMESPACE_NODE *ParentNode;
206 1.1 jruoho ACPI_OBJECT_TYPE ChildType;
207 1.1 jruoho UINT32 Level;
208 1.1 jruoho BOOLEAN NodePreviouslyVisited = FALSE;
209 1.1 jruoho
210 1.1 jruoho
211 1.1 jruoho ACPI_FUNCTION_TRACE (NsWalkNamespace);
212 1.1 jruoho
213 1.1 jruoho
214 1.1 jruoho /* Special case for the namespace Root Node */
215 1.1 jruoho
216 1.1 jruoho if (StartNode == ACPI_ROOT_OBJECT)
217 1.1 jruoho {
218 1.1 jruoho StartNode = AcpiGbl_RootNode;
219 1.1 jruoho }
220 1.1 jruoho
221 1.1 jruoho /* Null child means "get first node" */
222 1.1 jruoho
223 1.1 jruoho ParentNode = StartNode;
224 1.1 jruoho ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
225 1.1 jruoho ChildType = ACPI_TYPE_ANY;
226 1.1 jruoho Level = 1;
227 1.1 jruoho
228 1.1 jruoho /*
229 1.1 jruoho * Traverse the tree of nodes until we bubble back up to where we
230 1.1 jruoho * started. When Level is zero, the loop is done because we have
231 1.1 jruoho * bubbled up to (and passed) the original parent handle (StartEntry)
232 1.1 jruoho */
233 1.1 jruoho while (Level > 0 && ChildNode)
234 1.1 jruoho {
235 1.1 jruoho Status = AE_OK;
236 1.1 jruoho
237 1.1 jruoho /* Found next child, get the type if we are not searching for ANY */
238 1.1 jruoho
239 1.1 jruoho if (Type != ACPI_TYPE_ANY)
240 1.1 jruoho {
241 1.1 jruoho ChildType = ChildNode->Type;
242 1.1 jruoho }
243 1.1 jruoho
244 1.1 jruoho /*
245 1.1 jruoho * Ignore all temporary namespace nodes (created during control
246 1.1 jruoho * method execution) unless told otherwise. These temporary nodes
247 1.1 jruoho * can cause a race condition because they can be deleted during
248 1.1 jruoho * the execution of the user function (if the namespace is
249 1.1 jruoho * unlocked before invocation of the user function.) Only the
250 1.1 jruoho * debugger namespace dump will examine the temporary nodes.
251 1.1 jruoho */
252 1.1 jruoho if ((ChildNode->Flags & ANOBJ_TEMPORARY) &&
253 1.1 jruoho !(Flags & ACPI_NS_WALK_TEMP_NODES))
254 1.1 jruoho {
255 1.1 jruoho Status = AE_CTRL_DEPTH;
256 1.1 jruoho }
257 1.1 jruoho
258 1.1 jruoho /* Type must match requested type */
259 1.1 jruoho
260 1.1 jruoho else if (ChildType == Type)
261 1.1 jruoho {
262 1.1 jruoho /*
263 1.1 jruoho * Found a matching node, invoke the user callback function.
264 1.1 jruoho * Unlock the namespace if flag is set.
265 1.1 jruoho */
266 1.1 jruoho if (Flags & ACPI_NS_WALK_UNLOCK)
267 1.1 jruoho {
268 1.1 jruoho MutexStatus = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
269 1.1 jruoho if (ACPI_FAILURE (MutexStatus))
270 1.1 jruoho {
271 1.1 jruoho return_ACPI_STATUS (MutexStatus);
272 1.1 jruoho }
273 1.1 jruoho }
274 1.1 jruoho
275 1.1 jruoho /*
276 1.1.1.3 christos * Invoke the user function, either descending, ascending,
277 1.1 jruoho * or both.
278 1.1 jruoho */
279 1.1 jruoho if (!NodePreviouslyVisited)
280 1.1 jruoho {
281 1.1.1.3 christos if (DescendingCallback)
282 1.1 jruoho {
283 1.1.1.3 christos Status = DescendingCallback (ChildNode, Level,
284 1.1 jruoho Context, ReturnValue);
285 1.1 jruoho }
286 1.1 jruoho }
287 1.1 jruoho else
288 1.1 jruoho {
289 1.1.1.3 christos if (AscendingCallback)
290 1.1 jruoho {
291 1.1.1.3 christos Status = AscendingCallback (ChildNode, Level,
292 1.1 jruoho Context, ReturnValue);
293 1.1 jruoho }
294 1.1 jruoho }
295 1.1 jruoho
296 1.1 jruoho if (Flags & ACPI_NS_WALK_UNLOCK)
297 1.1 jruoho {
298 1.1 jruoho MutexStatus = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
299 1.1 jruoho if (ACPI_FAILURE (MutexStatus))
300 1.1 jruoho {
301 1.1 jruoho return_ACPI_STATUS (MutexStatus);
302 1.1 jruoho }
303 1.1 jruoho }
304 1.1 jruoho
305 1.1 jruoho switch (Status)
306 1.1 jruoho {
307 1.1 jruoho case AE_OK:
308 1.1 jruoho case AE_CTRL_DEPTH:
309 1.1 jruoho
310 1.1 jruoho /* Just keep going */
311 1.1 jruoho break;
312 1.1 jruoho
313 1.1 jruoho case AE_CTRL_TERMINATE:
314 1.1 jruoho
315 1.1 jruoho /* Exit now, with OK status */
316 1.1 jruoho
317 1.1 jruoho return_ACPI_STATUS (AE_OK);
318 1.1 jruoho
319 1.1 jruoho default:
320 1.1 jruoho
321 1.1 jruoho /* All others are valid exceptions */
322 1.1 jruoho
323 1.1 jruoho return_ACPI_STATUS (Status);
324 1.1 jruoho }
325 1.1 jruoho }
326 1.1 jruoho
327 1.1 jruoho /*
328 1.1 jruoho * Depth first search: Attempt to go down another level in the
329 1.1.1.3 christos * namespace if we are allowed to. Don't go any further if we have
330 1.1 jruoho * reached the caller specified maximum depth or if the user
331 1.1 jruoho * function has specified that the maximum depth has been reached.
332 1.1 jruoho */
333 1.1 jruoho if (!NodePreviouslyVisited &&
334 1.1 jruoho (Level < MaxDepth) &&
335 1.1 jruoho (Status != AE_CTRL_DEPTH))
336 1.1 jruoho {
337 1.1 jruoho if (ChildNode->Child)
338 1.1 jruoho {
339 1.1 jruoho /* There is at least one child of this node, visit it */
340 1.1 jruoho
341 1.1 jruoho Level++;
342 1.1 jruoho ParentNode = ChildNode;
343 1.1 jruoho ChildNode = AcpiNsGetNextNode (ParentNode, NULL);
344 1.1 jruoho continue;
345 1.1 jruoho }
346 1.1 jruoho }
347 1.1 jruoho
348 1.1 jruoho /* No more children, re-visit this node */
349 1.1 jruoho
350 1.1 jruoho if (!NodePreviouslyVisited)
351 1.1 jruoho {
352 1.1 jruoho NodePreviouslyVisited = TRUE;
353 1.1 jruoho continue;
354 1.1 jruoho }
355 1.1 jruoho
356 1.1 jruoho /* No more children, visit peers */
357 1.1 jruoho
358 1.1 jruoho ChildNode = AcpiNsGetNextNode (ParentNode, ChildNode);
359 1.1 jruoho if (ChildNode)
360 1.1 jruoho {
361 1.1 jruoho NodePreviouslyVisited = FALSE;
362 1.1 jruoho }
363 1.1 jruoho
364 1.1 jruoho /* No peers, re-visit parent */
365 1.1 jruoho
366 1.1 jruoho else
367 1.1 jruoho {
368 1.1 jruoho /*
369 1.1 jruoho * No more children of this node (AcpiNsGetNextNode failed), go
370 1.1 jruoho * back upwards in the namespace tree to the node's parent.
371 1.1 jruoho */
372 1.1 jruoho Level--;
373 1.1 jruoho ChildNode = ParentNode;
374 1.1 jruoho ParentNode = ParentNode->Parent;
375 1.1 jruoho
376 1.1 jruoho NodePreviouslyVisited = TRUE;
377 1.1 jruoho }
378 1.1 jruoho }
379 1.1 jruoho
380 1.1 jruoho /* Complete walk, not terminated by user function */
381 1.1 jruoho
382 1.1 jruoho return_ACPI_STATUS (AE_OK);
383 1.1 jruoho }
384