1 /******************************************************************************
2 *
3 * Module Name: nswalk - Functions for walking the ACPI namespace
4 *
5 *****************************************************************************/
6
7 /*
8 * Copyright (C) 2000 - 2004, R. Byron Moore
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
45 #include <acpi/acpi.h>
46 #include <acpi/acnamesp.h>
47
48
49 #define _COMPONENT ACPI_NAMESPACE
50 ACPI_MODULE_NAME ("nswalk")
51
52
53 /*******************************************************************************
54 *
55 * FUNCTION: acpi_ns_get_next_node
56 *
57 * PARAMETERS: Type - Type of node to be searched for
58 * parent_node - Parent node whose children we are
59 * getting
60 * child_node - Previous child that was found.
61 * The NEXT child will be returned
62 *
63 * RETURN: struct acpi_namespace_node - Pointer to the NEXT child or NULL if
64 * none is found.
65 *
66 * DESCRIPTION: Return the next peer node within the namespace. If Handle
67 * is valid, Scope is ignored. Otherwise, the first node
68 * within Scope is returned.
69 *
70 ******************************************************************************/
71
72 struct acpi_namespace_node *
acpi_ns_get_next_node(acpi_object_type type,struct acpi_namespace_node * parent_node,struct acpi_namespace_node * child_node)73 acpi_ns_get_next_node (
74 acpi_object_type type,
75 struct acpi_namespace_node *parent_node,
76 struct acpi_namespace_node *child_node)
77 {
78 struct acpi_namespace_node *next_node = NULL;
79
80
81 ACPI_FUNCTION_ENTRY ();
82
83
84 if (!child_node) {
85 /* It's really the parent's _scope_ that we want */
86
87 if (parent_node->child) {
88 next_node = parent_node->child;
89 }
90 }
91
92 else {
93 /* Start search at the NEXT node */
94
95 next_node = acpi_ns_get_next_valid_node (child_node);
96 }
97
98 /* If any type is OK, we are done */
99
100 if (type == ACPI_TYPE_ANY) {
101 /* next_node is NULL if we are at the end-of-list */
102
103 return (next_node);
104 }
105
106 /* Must search for the node -- but within this scope only */
107
108 while (next_node) {
109 /* If type matches, we are done */
110
111 if (next_node->type == type) {
112 return (next_node);
113 }
114
115 /* Otherwise, move on to the next node */
116
117 next_node = acpi_ns_get_next_valid_node (next_node);
118 }
119
120 /* Not found */
121
122 return (NULL);
123 }
124
125
126 /*******************************************************************************
127 *
128 * FUNCTION: acpi_ns_walk_namespace
129 *
130 * PARAMETERS: Type - acpi_object_type to search for
131 * start_node - Handle in namespace where search begins
132 * max_depth - Depth to which search is to reach
133 * unlock_before_callback- Whether to unlock the NS before invoking
134 * the callback routine
135 * user_function - Called when an object of "Type" is found
136 * Context - Passed to user function
137 * return_value - from the user_function if terminated early.
138 * Otherwise, returns NULL.
139 * RETURNS: Status
140 *
141 * DESCRIPTION: Performs a modified depth-first walk of the namespace tree,
142 * starting (and ending) at the node specified by start_handle.
143 * The user_function is called whenever a node that matches
144 * the type parameter is found. If the user function returns
145 * a non-zero value, the search is terminated immediately and this
146 * value is returned to the caller.
147 *
148 * The point of this procedure is to provide a generic namespace
149 * walk routine that can be called from multiple places to
150 * provide multiple services; the User Function can be tailored
151 * to each task, whether it is a print function, a compare
152 * function, etc.
153 *
154 ******************************************************************************/
155
156 acpi_status
acpi_ns_walk_namespace(acpi_object_type type,acpi_handle start_node,u32 max_depth,u8 unlock_before_callback,acpi_walk_callback user_function,void * context,void ** return_value)157 acpi_ns_walk_namespace (
158 acpi_object_type type,
159 acpi_handle start_node,
160 u32 max_depth,
161 u8 unlock_before_callback,
162 acpi_walk_callback user_function,
163 void *context,
164 void **return_value)
165 {
166 acpi_status status;
167 acpi_status mutex_status;
168 struct acpi_namespace_node *child_node;
169 struct acpi_namespace_node *parent_node;
170 acpi_object_type child_type;
171 u32 level;
172
173
174 ACPI_FUNCTION_TRACE ("ns_walk_namespace");
175
176
177 /* Special case for the namespace Root Node */
178
179 if (start_node == ACPI_ROOT_OBJECT) {
180 start_node = acpi_gbl_root_node;
181 }
182
183 /* Null child means "get first node" */
184
185 parent_node = start_node;
186 child_node = 0;
187 child_type = ACPI_TYPE_ANY;
188 level = 1;
189
190 /*
191 * Traverse the tree of nodes until we bubble back up to where we
192 * started. When Level is zero, the loop is done because we have
193 * bubbled up to (and passed) the original parent handle (start_entry)
194 */
195 while (level > 0) {
196 /* Get the next node in this scope. Null if not found */
197
198 status = AE_OK;
199 child_node = acpi_ns_get_next_node (ACPI_TYPE_ANY, parent_node, child_node);
200 if (child_node) {
201 /*
202 * Found node, Get the type if we are not
203 * searching for ANY
204 */
205 if (type != ACPI_TYPE_ANY) {
206 child_type = child_node->type;
207 }
208
209 if (child_type == type) {
210 /*
211 * Found a matching node, invoke the user
212 * callback function
213 */
214 if (unlock_before_callback) {
215 mutex_status = acpi_ut_release_mutex (ACPI_MTX_NAMESPACE);
216 if (ACPI_FAILURE (mutex_status)) {
217 return_ACPI_STATUS (mutex_status);
218 }
219 }
220
221 status = user_function (child_node, level,
222 context, return_value);
223
224 if (unlock_before_callback) {
225 mutex_status = acpi_ut_acquire_mutex (ACPI_MTX_NAMESPACE);
226 if (ACPI_FAILURE (mutex_status)) {
227 return_ACPI_STATUS (mutex_status);
228 }
229 }
230
231 switch (status) {
232 case AE_OK:
233 case AE_CTRL_DEPTH:
234
235 /* Just keep going */
236 break;
237
238 case AE_CTRL_TERMINATE:
239
240 /* Exit now, with OK status */
241
242 return_ACPI_STATUS (AE_OK);
243
244 default:
245
246 /* All others are valid exceptions */
247
248 return_ACPI_STATUS (status);
249 }
250 }
251
252 /*
253 * Depth first search:
254 * Attempt to go down another level in the namespace
255 * if we are allowed to. Don't go any further if we
256 * have reached the caller specified maximum depth
257 * or if the user function has specified that the
258 * maximum depth has been reached.
259 */
260 if ((level < max_depth) && (status != AE_CTRL_DEPTH)) {
261 if (acpi_ns_get_next_node (ACPI_TYPE_ANY, child_node, 0)) {
262 /*
263 * There is at least one child of this
264 * node, visit the onde
265 */
266 level++;
267 parent_node = child_node;
268 child_node = 0;
269 }
270 }
271 }
272 else {
273 /*
274 * No more children of this node (acpi_ns_get_next_node
275 * failed), go back upwards in the namespace tree to
276 * the node's parent.
277 */
278 level--;
279 child_node = parent_node;
280 parent_node = acpi_ns_get_parent_node (parent_node);
281 }
282 }
283
284 /* Complete walk, not terminated by user function */
285
286 return_ACPI_STATUS (AE_OK);
287 }
288
289
290