1 /*******************************************************************************
2  *
3  * Module Name: nsxfobj - Public interfaces to the ACPI subsystem
4  *                         ACPI Object oriented interfaces
5  *
6  ******************************************************************************/
7 
8 /*
9  * Copyright (C) 2000 - 2021, Intel Corp.
10  * All rights reserved.
11  *
12  * Redistribution and use in source and binary forms, with or without
13  * modification, are permitted provided that the following conditions
14  * are met:
15  * 1. Redistributions of source code must retain the above copyright
16  *    notice, this list of conditions, and the following disclaimer,
17  *    without modification.
18  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
19  *    substantially similar to the "NO WARRANTY" disclaimer below
20  *    ("Disclaimer") and any redistribution must be conditioned upon
21  *    including a substantially similar Disclaimer requirement for further
22  *    binary redistribution.
23  * 3. Neither the names of the above-listed copyright holders nor the names
24  *    of any contributors may be used to endorse or promote products derived
25  *    from this software without specific prior written permission.
26  *
27  * Alternatively, this software may be distributed under the terms of the
28  * GNU General Public License ("GPL") version 2 as published by the Free
29  * Software Foundation.
30  *
31  * NO WARRANTY
32  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
33  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
35  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
36  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
37  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
38  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
39  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
40  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
41  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
42  * POSSIBILITY OF SUCH DAMAGES.
43  */
44 
45 #define EXPORT_ACPI_INTERFACES
46 
47 #include "acpi.h"
48 #include "accommon.h"
49 #include "acnamesp.h"
50 
51 
52 #define _COMPONENT          ACPI_NAMESPACE
53         ACPI_MODULE_NAME    ("nsxfobj")
54 
55 /*******************************************************************************
56  *
57  * FUNCTION:    AcpiGetType
58  *
59  * PARAMETERS:  Handle          - Handle of object whose type is desired
60  *              RetType         - Where the type will be placed
61  *
62  * RETURN:      Status
63  *
64  * DESCRIPTION: This routine returns the type associated with a particular
65  *              handle
66  *
67  ******************************************************************************/
68 
69 ACPI_STATUS
70 AcpiGetType (
71     ACPI_HANDLE             Handle,
72     ACPI_OBJECT_TYPE        *RetType)
73 {
74     ACPI_NAMESPACE_NODE     *Node;
75     ACPI_STATUS             Status;
76 
77 
78     /* Parameter Validation */
79 
80     if (!RetType)
81     {
82         return (AE_BAD_PARAMETER);
83     }
84 
85     /* Special case for the predefined Root Node (return type ANY) */
86 
87     if (Handle == ACPI_ROOT_OBJECT)
88     {
89         *RetType = ACPI_TYPE_ANY;
90         return (AE_OK);
91     }
92 
93     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
94     if (ACPI_FAILURE (Status))
95     {
96         return (Status);
97     }
98 
99     /* Convert and validate the handle */
100 
101     Node = AcpiNsValidateHandle (Handle);
102     if (!Node)
103     {
104         (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
105         return (AE_BAD_PARAMETER);
106     }
107 
108     *RetType = Node->Type;
109 
110     Status = AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
111     return (Status);
112 }
113 
114 ACPI_EXPORT_SYMBOL (AcpiGetType)
115 
116 
117 /*******************************************************************************
118  *
119  * FUNCTION:    AcpiGetParent
120  *
121  * PARAMETERS:  Handle          - Handle of object whose parent is desired
122  *              RetHandle       - Where the parent handle will be placed
123  *
124  * RETURN:      Status
125  *
126  * DESCRIPTION: Returns a handle to the parent of the object represented by
127  *              Handle.
128  *
129  ******************************************************************************/
130 
131 ACPI_STATUS
132 AcpiGetParent (
133     ACPI_HANDLE             Handle,
134     ACPI_HANDLE             *RetHandle)
135 {
136     ACPI_NAMESPACE_NODE     *Node;
137     ACPI_NAMESPACE_NODE     *ParentNode;
138     ACPI_STATUS             Status;
139 
140 
141     if (!RetHandle)
142     {
143         return (AE_BAD_PARAMETER);
144     }
145 
146     /* Special case for the predefined Root Node (no parent) */
147 
148     if (Handle == ACPI_ROOT_OBJECT)
149     {
150         return (AE_NULL_ENTRY);
151     }
152 
153     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
154     if (ACPI_FAILURE (Status))
155     {
156         return (Status);
157     }
158 
159     /* Convert and validate the handle */
160 
161     Node = AcpiNsValidateHandle (Handle);
162     if (!Node)
163     {
164         Status = AE_BAD_PARAMETER;
165         goto UnlockAndExit;
166     }
167 
168     /* Get the parent entry */
169 
170     ParentNode = Node->Parent;
171     *RetHandle = ACPI_CAST_PTR (ACPI_HANDLE, ParentNode);
172 
173     /* Return exception if parent is null */
174 
175     if (!ParentNode)
176     {
177         Status = AE_NULL_ENTRY;
178     }
179 
180 
181 UnlockAndExit:
182 
183     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
184     return (Status);
185 }
186 
187 ACPI_EXPORT_SYMBOL (AcpiGetParent)
188 
189 
190 /*******************************************************************************
191  *
192  * FUNCTION:    AcpiGetNextObject
193  *
194  * PARAMETERS:  Type            - Type of object to be searched for
195  *              Parent          - Parent object whose children we are getting
196  *              LastChild       - Previous child that was found.
197  *                                The NEXT child will be returned
198  *              RetHandle       - Where handle to the next object is placed
199  *
200  * RETURN:      Status
201  *
202  * DESCRIPTION: Return the next peer object within the namespace. If Handle is
203  *              valid, Scope is ignored. Otherwise, the first object within
204  *              Scope is returned.
205  *
206  ******************************************************************************/
207 
208 ACPI_STATUS
209 AcpiGetNextObject (
210     ACPI_OBJECT_TYPE        Type,
211     ACPI_HANDLE             Parent,
212     ACPI_HANDLE             Child,
213     ACPI_HANDLE             *RetHandle)
214 {
215     ACPI_STATUS             Status;
216     ACPI_NAMESPACE_NODE     *Node;
217     ACPI_NAMESPACE_NODE     *ParentNode = NULL;
218     ACPI_NAMESPACE_NODE     *ChildNode = NULL;
219 
220 
221     /* Parameter validation */
222 
223     if (Type > ACPI_TYPE_EXTERNAL_MAX)
224     {
225         return (AE_BAD_PARAMETER);
226     }
227 
228     Status = AcpiUtAcquireMutex (ACPI_MTX_NAMESPACE);
229     if (ACPI_FAILURE (Status))
230     {
231         return (Status);
232     }
233 
234     /* If null handle, use the parent */
235 
236     if (!Child)
237     {
238         /* Start search at the beginning of the specified scope */
239 
240         ParentNode = AcpiNsValidateHandle (Parent);
241         if (!ParentNode)
242         {
243             Status = AE_BAD_PARAMETER;
244             goto UnlockAndExit;
245         }
246     }
247     else
248     {
249         /* Non-null handle, ignore the parent */
250         /* Convert and validate the handle */
251 
252         ChildNode = AcpiNsValidateHandle (Child);
253         if (!ChildNode)
254         {
255             Status = AE_BAD_PARAMETER;
256             goto UnlockAndExit;
257         }
258     }
259 
260     /* Internal function does the real work */
261 
262     Node = AcpiNsGetNextNodeTyped (Type, ParentNode, ChildNode);
263     if (!Node)
264     {
265         Status = AE_NOT_FOUND;
266         goto UnlockAndExit;
267     }
268 
269     if (RetHandle)
270     {
271         *RetHandle = ACPI_CAST_PTR (ACPI_HANDLE, Node);
272     }
273 
274 
275 UnlockAndExit:
276 
277     (void) AcpiUtReleaseMutex (ACPI_MTX_NAMESPACE);
278     return (Status);
279 }
280 
281 ACPI_EXPORT_SYMBOL (AcpiGetNextObject)
282