db5ab9e77a33df305f3d77625deb5885fda00a16
[dragonfly.git] / sys / contrib / dev / acpica-unix / executer / exmutex.c
1
2 /******************************************************************************
3  *
4  * Module Name: exmutex - ASL Mutex Acquire/Release functions
5  *
6  *****************************************************************************/
7
8 /******************************************************************************
9  *
10  * 1. Copyright Notice
11  *
12  * Some or all of this work - Copyright (c) 1999 - 2009, Intel Corp.
13  * All rights reserved.
14  *
15  * 2. License
16  *
17  * 2.1. This is your license from Intel Corp. under its intellectual property
18  * rights.  You may have additional license terms from the party that provided
19  * you this software, covering your right to use that party's intellectual
20  * property rights.
21  *
22  * 2.2. Intel grants, free of charge, to any person ("Licensee") obtaining a
23  * copy of the source code appearing in this file ("Covered Code") an
24  * irrevocable, perpetual, worldwide license under Intel's copyrights in the
25  * base code distributed originally by Intel ("Original Intel Code") to copy,
26  * make derivatives, distribute, use and display any portion of the Covered
27  * Code in any form, with the right to sublicense such rights; and
28  *
29  * 2.3. Intel grants Licensee a non-exclusive and non-transferable patent
30  * license (with the right to sublicense), under only those claims of Intel
31  * patents that are infringed by the Original Intel Code, to make, use, sell,
32  * offer to sell, and import the Covered Code and derivative works thereof
33  * solely to the minimum extent necessary to exercise the above copyright
34  * license, and in no event shall the patent license extend to any additions
35  * to or modifications of the Original Intel Code.  No other license or right
36  * is granted directly or by implication, estoppel or otherwise;
37  *
38  * The above copyright and patent license is granted only if the following
39  * conditions are met:
40  *
41  * 3. Conditions
42  *
43  * 3.1. Redistribution of Source with Rights to Further Distribute Source.
44  * Redistribution of source code of any substantial portion of the Covered
45  * Code or modification with rights to further distribute source must include
46  * the above Copyright Notice, the above License, this list of Conditions,
47  * and the following Disclaimer and Export Compliance provision.  In addition,
48  * Licensee must cause all Covered Code to which Licensee contributes to
49  * contain a file documenting the changes Licensee made to create that Covered
50  * Code and the date of any change.  Licensee must include in that file the
51  * documentation of any changes made by any predecessor Licensee.  Licensee
52  * must include a prominent statement that the modification is derived,
53  * directly or indirectly, from Original Intel Code.
54  *
55  * 3.2. Redistribution of Source with no Rights to Further Distribute Source.
56  * Redistribution of source code of any substantial portion of the Covered
57  * Code or modification without rights to further distribute source must
58  * include the following Disclaimer and Export Compliance provision in the
59  * documentation and/or other materials provided with distribution.  In
60  * addition, Licensee may not authorize further sublicense of source of any
61  * portion of the Covered Code, and must include terms to the effect that the
62  * license from Licensee to its licensee is limited to the intellectual
63  * property embodied in the software Licensee provides to its licensee, and
64  * not to intellectual property embodied in modifications its licensee may
65  * make.
66  *
67  * 3.3. Redistribution of Executable. Redistribution in executable form of any
68  * substantial portion of the Covered Code or modification must reproduce the
69  * above Copyright Notice, and the following Disclaimer and Export Compliance
70  * provision in the documentation and/or other materials provided with the
71  * distribution.
72  *
73  * 3.4. Intel retains all right, title, and interest in and to the Original
74  * Intel Code.
75  *
76  * 3.5. Neither the name Intel nor any other trademark owned or controlled by
77  * Intel shall be used in advertising or otherwise to promote the sale, use or
78  * other dealings in products derived from or relating to the Covered Code
79  * without prior written authorization from Intel.
80  *
81  * 4. Disclaimer and Export Compliance
82  *
83  * 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY SOFTWARE PROVIDED
84  * HERE.  ANY SOFTWARE ORIGINATING FROM INTEL OR DERIVED FROM INTEL SOFTWARE
85  * IS PROVIDED "AS IS," AND INTEL WILL NOT PROVIDE ANY SUPPORT,  ASSISTANCE,
86  * INSTALLATION, TRAINING OR OTHER SERVICES.  INTEL WILL NOT PROVIDE ANY
87  * UPDATES, ENHANCEMENTS OR EXTENSIONS.  INTEL SPECIFICALLY DISCLAIMS ANY
88  * IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A
89  * PARTICULAR PURPOSE.
90  *
91  * 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO LICENSEE, ITS LICENSEES
92  * OR ANY OTHER THIRD PARTY, FOR ANY LOST PROFITS, LOST DATA, LOSS OF USE OR
93  * COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY INDIRECT,
94  * SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, UNDER ANY
95  * CAUSE OF ACTION OR THEORY OF LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL
96  * HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS
97  * SHALL APPLY NOTWITHSTANDING THE FAILURE OF THE ESSENTIAL PURPOSE OF ANY
98  * LIMITED REMEDY.
99  *
100  * 4.3. Licensee shall not export, either directly or indirectly, any of this
101  * software or system incorporating such software without first obtaining any
102  * required license or other approval from the U. S. Department of Commerce or
103  * any other agency or department of the United States Government.  In the
104  * event Licensee exports any such software from the United States or
105  * re-exports any such software from a foreign destination, Licensee shall
106  * ensure that the distribution and export/re-export of the software is in
107  * compliance with all laws, regulations, orders, or other restrictions of the
108  * U.S. Export Administration Regulations. Licensee agrees that neither it nor
109  * any of its subsidiaries will export/re-export any technical data, process,
110  * software, or service, directly or indirectly, to any country for which the
111  * United States government or any agency thereof requires an export license,
112  * other governmental approval, or letter of assurance, without first obtaining
113  * such license, approval or letter.
114  *
115  *****************************************************************************/
116
117 #define __EXMUTEX_C__
118
119 #include "acpi.h"
120 #include "accommon.h"
121 #include "acinterp.h"
122 #include "acevents.h"
123
124 #define _COMPONENT          ACPI_EXECUTER
125         ACPI_MODULE_NAME    ("exmutex")
126
127 /* Local prototypes */
128
129 static void
130 AcpiExLinkMutex (
131     ACPI_OPERAND_OBJECT     *ObjDesc,
132     ACPI_THREAD_STATE       *Thread);
133
134
135 /*******************************************************************************
136  *
137  * FUNCTION:    AcpiExUnlinkMutex
138  *
139  * PARAMETERS:  ObjDesc             - The mutex to be unlinked
140  *
141  * RETURN:      None
142  *
143  * DESCRIPTION: Remove a mutex from the "AcquiredMutex" list
144  *
145  ******************************************************************************/
146
147 void
148 AcpiExUnlinkMutex (
149     ACPI_OPERAND_OBJECT     *ObjDesc)
150 {
151     ACPI_THREAD_STATE       *Thread = ObjDesc->Mutex.OwnerThread;
152
153
154     if (!Thread)
155     {
156         return;
157     }
158
159     /* Doubly linked list */
160
161     if (ObjDesc->Mutex.Next)
162     {
163         (ObjDesc->Mutex.Next)->Mutex.Prev = ObjDesc->Mutex.Prev;
164     }
165
166     if (ObjDesc->Mutex.Prev)
167     {
168         (ObjDesc->Mutex.Prev)->Mutex.Next = ObjDesc->Mutex.Next;
169
170         /*
171          * Migrate the previous sync level associated with this mutex to the
172          * previous mutex on the list so that it may be preserved. This handles
173          * the case where several mutexes have been acquired at the same level,
174          * but are not released in opposite order.
175          */
176         (ObjDesc->Mutex.Prev)->Mutex.OriginalSyncLevel =
177             ObjDesc->Mutex.OriginalSyncLevel;
178     }
179     else
180     {
181         Thread->AcquiredMutexList = ObjDesc->Mutex.Next;
182     }
183 }
184
185
186 /*******************************************************************************
187  *
188  * FUNCTION:    AcpiExLinkMutex
189  *
190  * PARAMETERS:  ObjDesc         - The mutex to be linked
191  *              Thread          - Current executing thread object
192  *
193  * RETURN:      None
194  *
195  * DESCRIPTION: Add a mutex to the "AcquiredMutex" list for this walk
196  *
197  ******************************************************************************/
198
199 static void
200 AcpiExLinkMutex (
201     ACPI_OPERAND_OBJECT     *ObjDesc,
202     ACPI_THREAD_STATE       *Thread)
203 {
204     ACPI_OPERAND_OBJECT     *ListHead;
205
206
207     ListHead = Thread->AcquiredMutexList;
208
209     /* This object will be the first object in the list */
210
211     ObjDesc->Mutex.Prev = NULL;
212     ObjDesc->Mutex.Next = ListHead;
213
214     /* Update old first object to point back to this object */
215
216     if (ListHead)
217     {
218         ListHead->Mutex.Prev = ObjDesc;
219     }
220
221     /* Update list head */
222
223     Thread->AcquiredMutexList = ObjDesc;
224 }
225
226
227 /*******************************************************************************
228  *
229  * FUNCTION:    AcpiExAcquireMutexObject
230  *
231  * PARAMETERS:  TimeDesc            - Timeout in milliseconds
232  *              ObjDesc             - Mutex object
233  *              Thread              - Current thread state
234  *
235  * RETURN:      Status
236  *
237  * DESCRIPTION: Acquire an AML mutex, low-level interface. Provides a common
238  *              path that supports multiple acquires by the same thread.
239  *
240  * MUTEX:       Interpreter must be locked
241  *
242  * NOTE: This interface is called from three places:
243  * 1) From AcpiExAcquireMutex, via an AML Acquire() operator
244  * 2) From AcpiExAcquireGlobalLock when an AML Field access requires the
245  *    global lock
246  * 3) From the external interface, AcpiAcquireGlobalLock
247  *
248  ******************************************************************************/
249
250 ACPI_STATUS
251 AcpiExAcquireMutexObject (
252     UINT16                  Timeout,
253     ACPI_OPERAND_OBJECT     *ObjDesc,
254     ACPI_THREAD_ID          ThreadId)
255 {
256     ACPI_STATUS             Status;
257
258
259     ACPI_FUNCTION_TRACE_PTR (ExAcquireMutexObject, ObjDesc);
260
261
262     if (!ObjDesc)
263     {
264         return_ACPI_STATUS (AE_BAD_PARAMETER);
265     }
266
267     /* Support for multiple acquires by the owning thread */
268
269     if (ObjDesc->Mutex.ThreadId == ThreadId)
270     {
271         /*
272          * The mutex is already owned by this thread, just increment the
273          * acquisition depth
274          */
275         ObjDesc->Mutex.AcquisitionDepth++;
276         return_ACPI_STATUS (AE_OK);
277     }
278
279     /* Acquire the mutex, wait if necessary. Special case for Global Lock */
280
281     if (ObjDesc == AcpiGbl_GlobalLockMutex)
282     {
283         Status = AcpiEvAcquireGlobalLock (Timeout);
284     }
285     else
286     {
287         Status = AcpiExSystemWaitMutex (ObjDesc->Mutex.OsMutex,
288                     Timeout);
289     }
290
291     if (ACPI_FAILURE (Status))
292     {
293         /* Includes failure from a timeout on TimeDesc */
294
295         return_ACPI_STATUS (Status);
296     }
297
298     /* Acquired the mutex: update mutex object */
299
300     ObjDesc->Mutex.ThreadId = ThreadId;
301     ObjDesc->Mutex.AcquisitionDepth = 1;
302     ObjDesc->Mutex.OriginalSyncLevel = 0;
303     ObjDesc->Mutex.OwnerThread = NULL;      /* Used only for AML Acquire() */
304
305     return_ACPI_STATUS (AE_OK);
306 }
307
308
309 /*******************************************************************************
310  *
311  * FUNCTION:    AcpiExAcquireMutex
312  *
313  * PARAMETERS:  TimeDesc            - Timeout integer
314  *              ObjDesc             - Mutex object
315  *              WalkState           - Current method execution state
316  *
317  * RETURN:      Status
318  *
319  * DESCRIPTION: Acquire an AML mutex
320  *
321  ******************************************************************************/
322
323 ACPI_STATUS
324 AcpiExAcquireMutex (
325     ACPI_OPERAND_OBJECT     *TimeDesc,
326     ACPI_OPERAND_OBJECT     *ObjDesc,
327     ACPI_WALK_STATE         *WalkState)
328 {
329     ACPI_STATUS             Status;
330
331
332     ACPI_FUNCTION_TRACE_PTR (ExAcquireMutex, ObjDesc);
333
334
335     if (!ObjDesc)
336     {
337         return_ACPI_STATUS (AE_BAD_PARAMETER);
338     }
339
340     /* Must have a valid thread ID */
341
342     if (!WalkState->Thread)
343     {
344         ACPI_ERROR ((AE_INFO, "Cannot acquire Mutex [%4.4s], null thread info",
345             AcpiUtGetNodeName (ObjDesc->Mutex.Node)));
346         return_ACPI_STATUS (AE_AML_INTERNAL);
347     }
348
349     /*
350      * Current sync level must be less than or equal to the sync level of the
351      * mutex. This mechanism provides some deadlock prevention
352      */
353     if (WalkState->Thread->CurrentSyncLevel > ObjDesc->Mutex.SyncLevel)
354     {
355         ACPI_ERROR ((AE_INFO,
356             "Cannot acquire Mutex [%4.4s], current SyncLevel is too large (%d)",
357             AcpiUtGetNodeName (ObjDesc->Mutex.Node),
358             WalkState->Thread->CurrentSyncLevel));
359         return_ACPI_STATUS (AE_AML_MUTEX_ORDER);
360     }
361
362     Status = AcpiExAcquireMutexObject ((UINT16) TimeDesc->Integer.Value,
363                 ObjDesc, WalkState->Thread->ThreadId);
364     if (ACPI_SUCCESS (Status) && ObjDesc->Mutex.AcquisitionDepth == 1)
365     {
366         /* Save Thread object, original/current sync levels */
367
368         ObjDesc->Mutex.OwnerThread = WalkState->Thread;
369         ObjDesc->Mutex.OriginalSyncLevel = WalkState->Thread->CurrentSyncLevel;
370         WalkState->Thread->CurrentSyncLevel = ObjDesc->Mutex.SyncLevel;
371
372         /* Link the mutex to the current thread for force-unlock at method exit */
373
374         AcpiExLinkMutex (ObjDesc, WalkState->Thread);
375     }
376
377     return_ACPI_STATUS (Status);
378 }
379
380
381 /*******************************************************************************
382  *
383  * FUNCTION:    AcpiExReleaseMutexObject
384  *
385  * PARAMETERS:  ObjDesc             - The object descriptor for this op
386  *
387  * RETURN:      Status
388  *
389  * DESCRIPTION: Release a previously acquired Mutex, low level interface.
390  *              Provides a common path that supports multiple releases (after
391  *              previous multiple acquires) by the same thread.
392  *
393  * MUTEX:       Interpreter must be locked
394  *
395  * NOTE: This interface is called from three places:
396  * 1) From AcpiExReleaseMutex, via an AML Acquire() operator
397  * 2) From AcpiExReleaseGlobalLock when an AML Field access requires the
398  *    global lock
399  * 3) From the external interface, AcpiReleaseGlobalLock
400  *
401  ******************************************************************************/
402
403 ACPI_STATUS
404 AcpiExReleaseMutexObject (
405     ACPI_OPERAND_OBJECT     *ObjDesc)
406 {
407     ACPI_STATUS             Status = AE_OK;
408
409
410     ACPI_FUNCTION_TRACE (ExReleaseMutexObject);
411
412
413     if (ObjDesc->Mutex.AcquisitionDepth == 0)
414     {
415         return (AE_NOT_ACQUIRED);
416     }
417
418     /* Match multiple Acquires with multiple Releases */
419
420     ObjDesc->Mutex.AcquisitionDepth--;
421     if (ObjDesc->Mutex.AcquisitionDepth != 0)
422     {
423         /* Just decrement the depth and return */
424
425         return_ACPI_STATUS (AE_OK);
426     }
427
428     if (ObjDesc->Mutex.OwnerThread)
429     {
430         /* Unlink the mutex from the owner's list */
431
432         AcpiExUnlinkMutex (ObjDesc);
433         ObjDesc->Mutex.OwnerThread = NULL;
434     }
435
436     /* Release the mutex, special case for Global Lock */
437
438     if (ObjDesc == AcpiGbl_GlobalLockMutex)
439     {
440         Status = AcpiEvReleaseGlobalLock ();
441     }
442     else
443     {
444         AcpiOsReleaseMutex (ObjDesc->Mutex.OsMutex);
445     }
446
447     /* Clear mutex info */
448
449     ObjDesc->Mutex.ThreadId = 0;
450     return_ACPI_STATUS (Status);
451 }
452
453
454 /*******************************************************************************
455  *
456  * FUNCTION:    AcpiExReleaseMutex
457  *
458  * PARAMETERS:  ObjDesc             - The object descriptor for this op
459  *              WalkState           - Current method execution state
460  *
461  * RETURN:      Status
462  *
463  * DESCRIPTION: Release a previously acquired Mutex.
464  *
465  ******************************************************************************/
466
467 ACPI_STATUS
468 AcpiExReleaseMutex (
469     ACPI_OPERAND_OBJECT     *ObjDesc,
470     ACPI_WALK_STATE         *WalkState)
471 {
472     ACPI_STATUS             Status = AE_OK;
473     UINT8                   PreviousSyncLevel;
474
475
476     ACPI_FUNCTION_TRACE (ExReleaseMutex);
477
478
479     if (!ObjDesc)
480     {
481         return_ACPI_STATUS (AE_BAD_PARAMETER);
482     }
483
484     /* The mutex must have been previously acquired in order to release it */
485
486     if (!ObjDesc->Mutex.OwnerThread)
487     {
488         ACPI_ERROR ((AE_INFO, "Cannot release Mutex [%4.4s], not acquired",
489             AcpiUtGetNodeName (ObjDesc->Mutex.Node)));
490         return_ACPI_STATUS (AE_AML_MUTEX_NOT_ACQUIRED);
491     }
492
493     /*
494      * The Mutex is owned, but this thread must be the owner.
495      * Special case for Global Lock, any thread can release
496      */
497     if ((ObjDesc->Mutex.OwnerThread->ThreadId != WalkState->Thread->ThreadId) &&
498         (ObjDesc != AcpiGbl_GlobalLockMutex))
499     {
500         ACPI_ERROR ((AE_INFO,
501             "Thread %p cannot release Mutex [%4.4s] acquired by thread %p",
502             ACPI_CAST_PTR (void, WalkState->Thread->ThreadId),
503             AcpiUtGetNodeName (ObjDesc->Mutex.Node),
504             ACPI_CAST_PTR (void, ObjDesc->Mutex.OwnerThread->ThreadId)));
505         return_ACPI_STATUS (AE_AML_NOT_OWNER);
506     }
507
508     /* Must have a valid thread ID */
509
510     if (!WalkState->Thread)
511     {
512         ACPI_ERROR ((AE_INFO, "Cannot release Mutex [%4.4s], null thread info",
513             AcpiUtGetNodeName (ObjDesc->Mutex.Node)));
514         return_ACPI_STATUS (AE_AML_INTERNAL);
515     }
516
517     /*
518      * The sync level of the mutex must be equal to the current sync level. In
519      * other words, the current level means that at least one mutex at that
520      * level is currently being held. Attempting to release a mutex of a
521      * different level can only mean that the mutex ordering rule is being
522      * violated. This behavior is clarified in ACPI 4.0 specification.
523      */
524     if (ObjDesc->Mutex.SyncLevel != WalkState->Thread->CurrentSyncLevel)
525     {
526         ACPI_ERROR ((AE_INFO,
527             "Cannot release Mutex [%4.4s], SyncLevel mismatch: mutex %d current %d",
528             AcpiUtGetNodeName (ObjDesc->Mutex.Node),
529             ObjDesc->Mutex.SyncLevel, WalkState->Thread->CurrentSyncLevel));
530         return_ACPI_STATUS (AE_AML_MUTEX_ORDER);
531     }
532
533     /*
534      * Get the previous SyncLevel from the head of the acquired mutex list.
535      * This handles the case where several mutexes at the same level have been
536      * acquired, but are not released in reverse order.
537      */
538     PreviousSyncLevel =
539         WalkState->Thread->AcquiredMutexList->Mutex.OriginalSyncLevel;
540
541     Status = AcpiExReleaseMutexObject (ObjDesc);
542     if (ACPI_FAILURE (Status))
543     {
544         return_ACPI_STATUS (Status);
545     }
546
547     if (ObjDesc->Mutex.AcquisitionDepth == 0)
548     {
549         /* Restore the previous SyncLevel */
550
551         WalkState->Thread->CurrentSyncLevel = PreviousSyncLevel;
552     }
553     return_ACPI_STATUS (Status);
554 }
555
556
557 /*******************************************************************************
558  *
559  * FUNCTION:    AcpiExReleaseAllMutexes
560  *
561  * PARAMETERS:  Thread          - Current executing thread object
562  *
563  * RETURN:      Status
564  *
565  * DESCRIPTION: Release all mutexes held by this thread
566  *
567  * NOTE: This function is called as the thread is exiting the interpreter.
568  * Mutexes are not released when an individual control method is exited, but
569  * only when the parent thread actually exits the interpreter. This allows one
570  * method to acquire a mutex, and a different method to release it, as long as
571  * this is performed underneath a single parent control method.
572  *
573  ******************************************************************************/
574
575 void
576 AcpiExReleaseAllMutexes (
577     ACPI_THREAD_STATE       *Thread)
578 {
579     ACPI_OPERAND_OBJECT     *Next = Thread->AcquiredMutexList;
580     ACPI_OPERAND_OBJECT     *ObjDesc;
581
582
583     ACPI_FUNCTION_ENTRY ();
584
585
586     /* Traverse the list of owned mutexes, releasing each one */
587
588     while (Next)
589     {
590         ObjDesc = Next;
591         Next = ObjDesc->Mutex.Next;
592
593         ObjDesc->Mutex.Prev = NULL;
594         ObjDesc->Mutex.Next = NULL;
595         ObjDesc->Mutex.AcquisitionDepth = 0;
596
597         /* Release the mutex, special case for Global Lock */
598
599         if (ObjDesc == AcpiGbl_GlobalLockMutex)
600         {
601             /* Ignore errors */
602
603             (void) AcpiEvReleaseGlobalLock ();
604         }
605         else
606         {
607             AcpiOsReleaseMutex (ObjDesc->Mutex.OsMutex);
608         }
609
610         /* Mark mutex unowned */
611
612         ObjDesc->Mutex.OwnerThread = NULL;
613         ObjDesc->Mutex.ThreadId = 0;
614
615         /* Update Thread SyncLevel (Last mutex is the important one) */
616
617         Thread->CurrentSyncLevel = ObjDesc->Mutex.OriginalSyncLevel;
618     }
619 }
620
621