1 /*******************************************************************************
2  *
3  * Module Name: utstate - state object support procedures
4  *
5  ******************************************************************************/
6 
7 /*
8  * Copyright (C) 2000 - 2021, 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 
47 #define _COMPONENT          ACPI_UTILITIES
48         ACPI_MODULE_NAME    ("utstate")
49 
50 
51 /*******************************************************************************
52  *
53  * FUNCTION:    AcpiUtPushGenericState
54  *
55  * PARAMETERS:  ListHead            - Head of the state stack
56  *              State               - State object to push
57  *
58  * RETURN:      None
59  *
60  * DESCRIPTION: Push a state object onto a state stack
61  *
62  ******************************************************************************/
63 
64 void
65 AcpiUtPushGenericState (
66     ACPI_GENERIC_STATE      **ListHead,
67     ACPI_GENERIC_STATE      *State)
68 {
69     ACPI_FUNCTION_ENTRY ();
70 
71 
72     /* Push the state object onto the front of the list (stack) */
73 
74     State->Common.Next = *ListHead;
75     *ListHead = State;
76     return;
77 }
78 
79 
80 /*******************************************************************************
81  *
82  * FUNCTION:    AcpiUtPopGenericState
83  *
84  * PARAMETERS:  ListHead            - Head of the state stack
85  *
86  * RETURN:      The popped state object
87  *
88  * DESCRIPTION: Pop a state object from a state stack
89  *
90  ******************************************************************************/
91 
92 ACPI_GENERIC_STATE *
93 AcpiUtPopGenericState (
94     ACPI_GENERIC_STATE      **ListHead)
95 {
96     ACPI_GENERIC_STATE      *State;
97 
98 
99     ACPI_FUNCTION_ENTRY ();
100 
101 
102     /* Remove the state object at the head of the list (stack) */
103 
104     State = *ListHead;
105     if (State)
106     {
107         /* Update the list head */
108 
109         *ListHead = State->Common.Next;
110     }
111 
112     return (State);
113 }
114 
115 
116 /*******************************************************************************
117  *
118  * FUNCTION:    AcpiUtCreateGenericState
119  *
120  * PARAMETERS:  None
121  *
122  * RETURN:      The new state object. NULL on failure.
123  *
124  * DESCRIPTION: Create a generic state object. Attempt to obtain one from
125  *              the global state cache;  If none available, create a new one.
126  *
127  ******************************************************************************/
128 
129 ACPI_GENERIC_STATE *
130 AcpiUtCreateGenericState (
131     void)
132 {
133     ACPI_GENERIC_STATE      *State;
134 
135 
136     ACPI_FUNCTION_ENTRY ();
137 
138 
139     State = AcpiOsAcquireObject (AcpiGbl_StateCache);
140     if (State)
141     {
142         /* Initialize */
143         State->Common.DescriptorType = ACPI_DESC_TYPE_STATE;
144     }
145 
146     return (State);
147 }
148 
149 
150 /*******************************************************************************
151  *
152  * FUNCTION:    AcpiUtCreateThreadState
153  *
154  * PARAMETERS:  None
155  *
156  * RETURN:      New Thread State. NULL on failure
157  *
158  * DESCRIPTION: Create a "Thread State" - a flavor of the generic state used
159  *              to track per-thread info during method execution
160  *
161  ******************************************************************************/
162 
163 ACPI_THREAD_STATE *
164 AcpiUtCreateThreadState (
165     void)
166 {
167     ACPI_GENERIC_STATE      *State;
168 
169 
170     ACPI_FUNCTION_ENTRY ();
171 
172 
173     /* Create the generic state object */
174 
175     State = AcpiUtCreateGenericState ();
176     if (!State)
177     {
178         return (NULL);
179     }
180 
181     /* Init fields specific to the update struct */
182 
183     State->Common.DescriptorType = ACPI_DESC_TYPE_STATE_THREAD;
184     State->Thread.ThreadId = AcpiOsGetThreadId ();
185 
186     /* Check for invalid thread ID - zero is very bad, it will break things */
187 
188     if (!State->Thread.ThreadId)
189     {
190         ACPI_ERROR ((AE_INFO, "Invalid zero ID from AcpiOsGetThreadId"));
191         State->Thread.ThreadId = (ACPI_THREAD_ID) 1;
192     }
193 
194     return ((ACPI_THREAD_STATE *) State);
195 }
196 
197 
198 /*******************************************************************************
199  *
200  * FUNCTION:    AcpiUtCreateUpdateState
201  *
202  * PARAMETERS:  Object          - Initial Object to be installed in the state
203  *              Action          - Update action to be performed
204  *
205  * RETURN:      New state object, null on failure
206  *
207  * DESCRIPTION: Create an "Update State" - a flavor of the generic state used
208  *              to update reference counts and delete complex objects such
209  *              as packages.
210  *
211  ******************************************************************************/
212 
213 ACPI_GENERIC_STATE *
214 AcpiUtCreateUpdateState (
215     ACPI_OPERAND_OBJECT     *Object,
216     UINT16                  Action)
217 {
218     ACPI_GENERIC_STATE      *State;
219 
220 
221     ACPI_FUNCTION_ENTRY ();
222 
223 
224     /* Create the generic state object */
225 
226     State = AcpiUtCreateGenericState ();
227     if (!State)
228     {
229         return (NULL);
230     }
231 
232     /* Init fields specific to the update struct */
233 
234     State->Common.DescriptorType = ACPI_DESC_TYPE_STATE_UPDATE;
235     State->Update.Object = Object;
236     State->Update.Value = Action;
237     return (State);
238 }
239 
240 
241 /*******************************************************************************
242  *
243  * FUNCTION:    AcpiUtCreatePkgState
244  *
245  * PARAMETERS:  Object          - Initial Object to be installed in the state
246  *              Action          - Update action to be performed
247  *
248  * RETURN:      New state object, null on failure
249  *
250  * DESCRIPTION: Create a "Package State"
251  *
252  ******************************************************************************/
253 
254 ACPI_GENERIC_STATE *
255 AcpiUtCreatePkgState (
256     void                    *InternalObject,
257     void                    *ExternalObject,
258     UINT32                  Index)
259 {
260     ACPI_GENERIC_STATE      *State;
261 
262 
263     ACPI_FUNCTION_ENTRY ();
264 
265 
266     /* Create the generic state object */
267 
268     State = AcpiUtCreateGenericState ();
269     if (!State)
270     {
271         return (NULL);
272     }
273 
274     /* Init fields specific to the update struct */
275 
276     State->Common.DescriptorType = ACPI_DESC_TYPE_STATE_PACKAGE;
277     State->Pkg.SourceObject = (ACPI_OPERAND_OBJECT *) InternalObject;
278     State->Pkg.DestObject = ExternalObject;
279     State->Pkg.Index= Index;
280     State->Pkg.NumPackages = 1;
281 
282     return (State);
283 }
284 
285 
286 /*******************************************************************************
287  *
288  * FUNCTION:    AcpiUtCreateControlState
289  *
290  * PARAMETERS:  None
291  *
292  * RETURN:      New state object, null on failure
293  *
294  * DESCRIPTION: Create a "Control State" - a flavor of the generic state used
295  *              to support nested IF/WHILE constructs in the AML.
296  *
297  ******************************************************************************/
298 
299 ACPI_GENERIC_STATE *
300 AcpiUtCreateControlState (
301     void)
302 {
303     ACPI_GENERIC_STATE      *State;
304 
305 
306     ACPI_FUNCTION_ENTRY ();
307 
308 
309     /* Create the generic state object */
310 
311     State = AcpiUtCreateGenericState ();
312     if (!State)
313     {
314         return (NULL);
315     }
316 
317     /* Init fields specific to the control struct */
318 
319     State->Common.DescriptorType = ACPI_DESC_TYPE_STATE_CONTROL;
320     State->Common.State = ACPI_CONTROL_CONDITIONAL_EXECUTING;
321 
322     return (State);
323 }
324 
325 
326 /*******************************************************************************
327  *
328  * FUNCTION:    AcpiUtDeleteGenericState
329  *
330  * PARAMETERS:  State               - The state object to be deleted
331  *
332  * RETURN:      None
333  *
334  * DESCRIPTION: Release a state object to the state cache. NULL state objects
335  *              are ignored.
336  *
337  ******************************************************************************/
338 
339 void
340 AcpiUtDeleteGenericState (
341     ACPI_GENERIC_STATE      *State)
342 {
343     ACPI_FUNCTION_ENTRY ();
344 
345 
346     /* Ignore null state */
347 
348     if (State)
349     {
350         (void) AcpiOsReleaseObject (AcpiGbl_StateCache, State);
351     }
352 
353     return;
354 }
355