xref: /openbmc/linux/drivers/acpi/acpica/exmutex.c (revision b6dcefde)
1 
2 /******************************************************************************
3  *
4  * Module Name: exmutex - ASL Mutex Acquire/Release functions
5  *
6  *****************************************************************************/
7 
8 /*
9  * Copyright (C) 2000 - 2008, 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 MERCHANTIBILITY 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 #include <acpi/acpi.h>
46 #include "accommon.h"
47 #include "acinterp.h"
48 #include "acevents.h"
49 
50 #define _COMPONENT          ACPI_EXECUTER
51 ACPI_MODULE_NAME("exmutex")
52 
53 /* Local prototypes */
54 static void
55 acpi_ex_link_mutex(union acpi_operand_object *obj_desc,
56 		   struct acpi_thread_state *thread);
57 
58 /*******************************************************************************
59  *
60  * FUNCTION:    acpi_ex_unlink_mutex
61  *
62  * PARAMETERS:  obj_desc            - The mutex to be unlinked
63  *
64  * RETURN:      None
65  *
66  * DESCRIPTION: Remove a mutex from the "AcquiredMutex" list
67  *
68  ******************************************************************************/
69 
70 void acpi_ex_unlink_mutex(union acpi_operand_object *obj_desc)
71 {
72 	struct acpi_thread_state *thread = obj_desc->mutex.owner_thread;
73 
74 	if (!thread) {
75 		return;
76 	}
77 
78 	/* Doubly linked list */
79 
80 	if (obj_desc->mutex.next) {
81 		(obj_desc->mutex.next)->mutex.prev = obj_desc->mutex.prev;
82 	}
83 
84 	if (obj_desc->mutex.prev) {
85 		(obj_desc->mutex.prev)->mutex.next = obj_desc->mutex.next;
86 
87 		/*
88 		 * Migrate the previous sync level associated with this mutex to the
89 		 * previous mutex on the list so that it may be preserved. This handles
90 		 * the case where several mutexes have been acquired at the same level,
91 		 * but are not released in opposite order.
92 		 */
93 		(obj_desc->mutex.prev)->mutex.original_sync_level =
94 		    obj_desc->mutex.original_sync_level;
95 	} else {
96 		thread->acquired_mutex_list = obj_desc->mutex.next;
97 	}
98 }
99 
100 /*******************************************************************************
101  *
102  * FUNCTION:    acpi_ex_link_mutex
103  *
104  * PARAMETERS:  obj_desc        - The mutex to be linked
105  *              Thread          - Current executing thread object
106  *
107  * RETURN:      None
108  *
109  * DESCRIPTION: Add a mutex to the "AcquiredMutex" list for this walk
110  *
111  ******************************************************************************/
112 
113 static void
114 acpi_ex_link_mutex(union acpi_operand_object *obj_desc,
115 		   struct acpi_thread_state *thread)
116 {
117 	union acpi_operand_object *list_head;
118 
119 	list_head = thread->acquired_mutex_list;
120 
121 	/* This object will be the first object in the list */
122 
123 	obj_desc->mutex.prev = NULL;
124 	obj_desc->mutex.next = list_head;
125 
126 	/* Update old first object to point back to this object */
127 
128 	if (list_head) {
129 		list_head->mutex.prev = obj_desc;
130 	}
131 
132 	/* Update list head */
133 
134 	thread->acquired_mutex_list = obj_desc;
135 }
136 
137 /*******************************************************************************
138  *
139  * FUNCTION:    acpi_ex_acquire_mutex_object
140  *
141  * PARAMETERS:  time_desc           - Timeout in milliseconds
142  *              obj_desc            - Mutex object
143  *              Thread              - Current thread state
144  *
145  * RETURN:      Status
146  *
147  * DESCRIPTION: Acquire an AML mutex, low-level interface. Provides a common
148  *              path that supports multiple acquires by the same thread.
149  *
150  * MUTEX:       Interpreter must be locked
151  *
152  * NOTE: This interface is called from three places:
153  * 1) From acpi_ex_acquire_mutex, via an AML Acquire() operator
154  * 2) From acpi_ex_acquire_global_lock when an AML Field access requires the
155  *    global lock
156  * 3) From the external interface, acpi_acquire_global_lock
157  *
158  ******************************************************************************/
159 
160 acpi_status
161 acpi_ex_acquire_mutex_object(u16 timeout,
162 			     union acpi_operand_object *obj_desc,
163 			     acpi_thread_id thread_id)
164 {
165 	acpi_status status;
166 
167 	ACPI_FUNCTION_TRACE_PTR(ex_acquire_mutex_object, obj_desc);
168 
169 	if (!obj_desc) {
170 		return_ACPI_STATUS(AE_BAD_PARAMETER);
171 	}
172 
173 	/* Support for multiple acquires by the owning thread */
174 
175 	if (obj_desc->mutex.thread_id == thread_id) {
176 		/*
177 		 * The mutex is already owned by this thread, just increment the
178 		 * acquisition depth
179 		 */
180 		obj_desc->mutex.acquisition_depth++;
181 		return_ACPI_STATUS(AE_OK);
182 	}
183 
184 	/* Acquire the mutex, wait if necessary. Special case for Global Lock */
185 
186 	if (obj_desc == acpi_gbl_global_lock_mutex) {
187 		status = acpi_ev_acquire_global_lock(timeout);
188 	} else {
189 		status = acpi_ex_system_wait_mutex(obj_desc->mutex.os_mutex,
190 						   timeout);
191 	}
192 
193 	if (ACPI_FAILURE(status)) {
194 
195 		/* Includes failure from a timeout on time_desc */
196 
197 		return_ACPI_STATUS(status);
198 	}
199 
200 	/* Acquired the mutex: update mutex object */
201 
202 	obj_desc->mutex.thread_id = thread_id;
203 	obj_desc->mutex.acquisition_depth = 1;
204 	obj_desc->mutex.original_sync_level = 0;
205 	obj_desc->mutex.owner_thread = NULL;	/* Used only for AML Acquire() */
206 
207 	return_ACPI_STATUS(AE_OK);
208 }
209 
210 /*******************************************************************************
211  *
212  * FUNCTION:    acpi_ex_acquire_mutex
213  *
214  * PARAMETERS:  time_desc           - Timeout integer
215  *              obj_desc            - Mutex object
216  *              walk_state          - Current method execution state
217  *
218  * RETURN:      Status
219  *
220  * DESCRIPTION: Acquire an AML mutex
221  *
222  ******************************************************************************/
223 
224 acpi_status
225 acpi_ex_acquire_mutex(union acpi_operand_object *time_desc,
226 		      union acpi_operand_object *obj_desc,
227 		      struct acpi_walk_state *walk_state)
228 {
229 	acpi_status status;
230 
231 	ACPI_FUNCTION_TRACE_PTR(ex_acquire_mutex, obj_desc);
232 
233 	if (!obj_desc) {
234 		return_ACPI_STATUS(AE_BAD_PARAMETER);
235 	}
236 
237 	/* Must have a valid thread ID */
238 
239 	if (!walk_state->thread) {
240 		ACPI_ERROR((AE_INFO,
241 			    "Cannot acquire Mutex [%4.4s], null thread info",
242 			    acpi_ut_get_node_name(obj_desc->mutex.node)));
243 		return_ACPI_STATUS(AE_AML_INTERNAL);
244 	}
245 
246 	/*
247 	 * Current sync level must be less than or equal to the sync level of the
248 	 * mutex. This mechanism provides some deadlock prevention
249 	 */
250 	if (walk_state->thread->current_sync_level > obj_desc->mutex.sync_level) {
251 		ACPI_ERROR((AE_INFO,
252 			    "Cannot acquire Mutex [%4.4s], current SyncLevel is too large (%d)",
253 			    acpi_ut_get_node_name(obj_desc->mutex.node),
254 			    walk_state->thread->current_sync_level));
255 		return_ACPI_STATUS(AE_AML_MUTEX_ORDER);
256 	}
257 
258 	status = acpi_ex_acquire_mutex_object((u16) time_desc->integer.value,
259 					      obj_desc,
260 					      walk_state->thread->thread_id);
261 	if (ACPI_SUCCESS(status) && obj_desc->mutex.acquisition_depth == 1) {
262 
263 		/* Save Thread object, original/current sync levels */
264 
265 		obj_desc->mutex.owner_thread = walk_state->thread;
266 		obj_desc->mutex.original_sync_level =
267 		    walk_state->thread->current_sync_level;
268 		walk_state->thread->current_sync_level =
269 		    obj_desc->mutex.sync_level;
270 
271 		/* Link the mutex to the current thread for force-unlock at method exit */
272 
273 		acpi_ex_link_mutex(obj_desc, walk_state->thread);
274 	}
275 
276 	return_ACPI_STATUS(status);
277 }
278 
279 /*******************************************************************************
280  *
281  * FUNCTION:    acpi_ex_release_mutex_object
282  *
283  * PARAMETERS:  obj_desc            - The object descriptor for this op
284  *
285  * RETURN:      Status
286  *
287  * DESCRIPTION: Release a previously acquired Mutex, low level interface.
288  *              Provides a common path that supports multiple releases (after
289  *              previous multiple acquires) by the same thread.
290  *
291  * MUTEX:       Interpreter must be locked
292  *
293  * NOTE: This interface is called from three places:
294  * 1) From acpi_ex_release_mutex, via an AML Acquire() operator
295  * 2) From acpi_ex_release_global_lock when an AML Field access requires the
296  *    global lock
297  * 3) From the external interface, acpi_release_global_lock
298  *
299  ******************************************************************************/
300 
301 acpi_status acpi_ex_release_mutex_object(union acpi_operand_object *obj_desc)
302 {
303 	acpi_status status = AE_OK;
304 
305 	ACPI_FUNCTION_TRACE(ex_release_mutex_object);
306 
307 	if (obj_desc->mutex.acquisition_depth == 0) {
308 		return (AE_NOT_ACQUIRED);
309 	}
310 
311 	/* Match multiple Acquires with multiple Releases */
312 
313 	obj_desc->mutex.acquisition_depth--;
314 	if (obj_desc->mutex.acquisition_depth != 0) {
315 
316 		/* Just decrement the depth and return */
317 
318 		return_ACPI_STATUS(AE_OK);
319 	}
320 
321 	if (obj_desc->mutex.owner_thread) {
322 
323 		/* Unlink the mutex from the owner's list */
324 
325 		acpi_ex_unlink_mutex(obj_desc);
326 		obj_desc->mutex.owner_thread = NULL;
327 	}
328 
329 	/* Release the mutex, special case for Global Lock */
330 
331 	if (obj_desc == acpi_gbl_global_lock_mutex) {
332 		status = acpi_ev_release_global_lock();
333 	} else {
334 		acpi_os_release_mutex(obj_desc->mutex.os_mutex);
335 	}
336 
337 	/* Clear mutex info */
338 
339 	obj_desc->mutex.thread_id = NULL;
340 	return_ACPI_STATUS(status);
341 }
342 
343 /*******************************************************************************
344  *
345  * FUNCTION:    acpi_ex_release_mutex
346  *
347  * PARAMETERS:  obj_desc            - The object descriptor for this op
348  *              walk_state          - Current method execution state
349  *
350  * RETURN:      Status
351  *
352  * DESCRIPTION: Release a previously acquired Mutex.
353  *
354  ******************************************************************************/
355 
356 acpi_status
357 acpi_ex_release_mutex(union acpi_operand_object *obj_desc,
358 		      struct acpi_walk_state *walk_state)
359 {
360 	acpi_status status = AE_OK;
361 	u8 previous_sync_level;
362 
363 	ACPI_FUNCTION_TRACE(ex_release_mutex);
364 
365 	if (!obj_desc) {
366 		return_ACPI_STATUS(AE_BAD_PARAMETER);
367 	}
368 
369 	/* The mutex must have been previously acquired in order to release it */
370 
371 	if (!obj_desc->mutex.owner_thread) {
372 		ACPI_ERROR((AE_INFO,
373 			    "Cannot release Mutex [%4.4s], not acquired",
374 			    acpi_ut_get_node_name(obj_desc->mutex.node)));
375 		return_ACPI_STATUS(AE_AML_MUTEX_NOT_ACQUIRED);
376 	}
377 
378 	/* Must have a valid thread ID */
379 
380 	if (!walk_state->thread) {
381 		ACPI_ERROR((AE_INFO,
382 			    "Cannot release Mutex [%4.4s], null thread info",
383 			    acpi_ut_get_node_name(obj_desc->mutex.node)));
384 		return_ACPI_STATUS(AE_AML_INTERNAL);
385 	}
386 
387 	/*
388 	 * The Mutex is owned, but this thread must be the owner.
389 	 * Special case for Global Lock, any thread can release
390 	 */
391 	if ((obj_desc->mutex.owner_thread->thread_id !=
392 	     walk_state->thread->thread_id)
393 	    && (obj_desc != acpi_gbl_global_lock_mutex)) {
394 		ACPI_ERROR((AE_INFO,
395 			    "Thread %p cannot release Mutex [%4.4s] acquired by thread %p",
396 			    ACPI_CAST_PTR(void, walk_state->thread->thread_id),
397 			    acpi_ut_get_node_name(obj_desc->mutex.node),
398 			    ACPI_CAST_PTR(void,
399 					  obj_desc->mutex.owner_thread->
400 					  thread_id)));
401 		return_ACPI_STATUS(AE_AML_NOT_OWNER);
402 	}
403 
404 	/*
405 	 * The sync level of the mutex must be equal to the current sync level. In
406 	 * other words, the current level means that at least one mutex at that
407 	 * level is currently being held. Attempting to release a mutex of a
408 	 * different level can only mean that the mutex ordering rule is being
409 	 * violated. This behavior is clarified in ACPI 4.0 specification.
410 	 */
411 	if (obj_desc->mutex.sync_level !=
412 	    walk_state->thread->current_sync_level) {
413 		ACPI_ERROR((AE_INFO,
414 			    "Cannot release Mutex [%4.4s], SyncLevel mismatch: mutex %d current %d",
415 			    acpi_ut_get_node_name(obj_desc->mutex.node),
416 			    obj_desc->mutex.sync_level,
417 			    walk_state->thread->current_sync_level));
418 		return_ACPI_STATUS(AE_AML_MUTEX_ORDER);
419 	}
420 
421 	/*
422 	 * Get the previous sync_level from the head of the acquired mutex list.
423 	 * This handles the case where several mutexes at the same level have been
424 	 * acquired, but are not released in reverse order.
425 	 */
426 	previous_sync_level =
427 	    walk_state->thread->acquired_mutex_list->mutex.original_sync_level;
428 
429 	status = acpi_ex_release_mutex_object(obj_desc);
430 	if (ACPI_FAILURE(status)) {
431 		return_ACPI_STATUS(status);
432 	}
433 
434 	if (obj_desc->mutex.acquisition_depth == 0) {
435 
436 		/* Restore the previous sync_level */
437 
438 		walk_state->thread->current_sync_level = previous_sync_level;
439 	}
440 	return_ACPI_STATUS(status);
441 }
442 
443 /*******************************************************************************
444  *
445  * FUNCTION:    acpi_ex_release_all_mutexes
446  *
447  * PARAMETERS:  Thread          - Current executing thread object
448  *
449  * RETURN:      Status
450  *
451  * DESCRIPTION: Release all mutexes held by this thread
452  *
453  * NOTE: This function is called as the thread is exiting the interpreter.
454  * Mutexes are not released when an individual control method is exited, but
455  * only when the parent thread actually exits the interpreter. This allows one
456  * method to acquire a mutex, and a different method to release it, as long as
457  * this is performed underneath a single parent control method.
458  *
459  ******************************************************************************/
460 
461 void acpi_ex_release_all_mutexes(struct acpi_thread_state *thread)
462 {
463 	union acpi_operand_object *next = thread->acquired_mutex_list;
464 	union acpi_operand_object *obj_desc;
465 
466 	ACPI_FUNCTION_ENTRY();
467 
468 	/* Traverse the list of owned mutexes, releasing each one */
469 
470 	while (next) {
471 		obj_desc = next;
472 		next = obj_desc->mutex.next;
473 
474 		obj_desc->mutex.prev = NULL;
475 		obj_desc->mutex.next = NULL;
476 		obj_desc->mutex.acquisition_depth = 0;
477 
478 		/* Release the mutex, special case for Global Lock */
479 
480 		if (obj_desc == acpi_gbl_global_lock_mutex) {
481 
482 			/* Ignore errors */
483 
484 			(void)acpi_ev_release_global_lock();
485 		} else {
486 			acpi_os_release_mutex(obj_desc->mutex.os_mutex);
487 		}
488 
489 		/* Mark mutex unowned */
490 
491 		obj_desc->mutex.owner_thread = NULL;
492 		obj_desc->mutex.thread_id = NULL;
493 
494 		/* Update Thread sync_level (Last mutex is the important one) */
495 
496 		thread->current_sync_level =
497 		    obj_desc->mutex.original_sync_level;
498 	}
499 }
500