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