[deliverable/linux.git] / include / linux / mutex.h

/*
 * Mutexes: blocking mutual exclusion locks
 *
 * started by Ingo Molnar:
 *
 *  Copyright (C) 2004, 2005, 2006 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
 *
 * This file contains the main data structure and API definitions.
 */
#ifndef __LINUX_MUTEX_H
#define __LINUX_MUTEX_H

#include <linux/list.h>
#include <linux/spinlock_types.h>

#include <asm/atomic.h>

/*
 * Simple, straightforward mutexes with strict semantics:
 *
 * - only one task can hold the mutex at a time
 * - only the owner can unlock the mutex
 * - multiple unlocks are not permitted
 * - recursive locking is not permitted
 * - a mutex object must be initialized via the API
 * - a mutex object must not be initialized via memset or copying
 * - task may not exit with mutex held
 * - memory areas where held locks reside must not be freed
 * - held mutexes must not be reinitialized
 * - mutexes may not be used in irq contexts
 *
 * These semantics are fully enforced when DEBUG_MUTEXES is
 * enabled. Furthermore, besides enforcing the above rules, the mutex
 * debugging code also implements a number of additional features
 * that make lock debugging easier and faster:
 *
 * - uses symbolic names of mutexes, whenever they are printed in debug output
 * - point-of-acquire tracking, symbolic lookup of function names
 * - list of all locks held in the system, printout of them
 * - owner tracking
 * - detects self-recursing locks and prints out all relevant info
 * - detects multi-task circular deadlocks and prints out all affected
 *   locks and tasks (and only those tasks)
 */
struct mutex {
	/* 1: unlocked, 0: locked, negative: locked, possible waiters */
	atomic_t		count;
	spinlock_t		wait_lock;
	struct list_head	wait_list;
#ifdef CONFIG_DEBUG_MUTEXES
	struct thread_info	*owner;
	struct list_head	held_list;
	unsigned long		acquire_ip;
	const char 		*name;
	void			*magic;
#endif
};

/*
 * This is the control structure for tasks blocked on mutex,
 * which resides on the blocked task's kernel stack:
 */
struct mutex_waiter {
	struct list_head	list;
	struct task_struct	*task;
#ifdef CONFIG_DEBUG_MUTEXES
	struct mutex		*lock;
	void			*magic;
#endif
};

#ifdef CONFIG_DEBUG_MUTEXES
# include <linux/mutex-debug.h>
#else
# define __DEBUG_MUTEX_INITIALIZER(lockname)
# define mutex_init(mutex)			__mutex_init(mutex, NULL)
# define mutex_destroy(mutex)				do { } while (0)
# define mutex_debug_show_all_locks()			do { } while (0)
# define mutex_debug_show_held_locks(p)			do { } while (0)
# define mutex_debug_check_no_locks_held(task)		do { } while (0)
# define mutex_debug_check_no_locks_freed(from, to)	do { } while (0)
#endif

#define __MUTEX_INITIALIZER(lockname) \
		{ .count = ATOMIC_INIT(1) \
		, .wait_lock = SPIN_LOCK_UNLOCKED \
		, .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
		__DEBUG_MUTEX_INITIALIZER(lockname) }

#define DEFINE_MUTEX(mutexname) \
	struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)

extern void fastcall __mutex_init(struct mutex *lock, const char *name);

/***
 * mutex_is_locked - is the mutex locked
 * @lock: the mutex to be queried
 *
 * Returns 1 if the mutex is locked, 0 if unlocked.
 */
static inline int fastcall mutex_is_locked(struct mutex *lock)
{
	return atomic_read(&lock->count) != 1;
}

/*
 * See kernel/mutex.c for detailed documentation of these APIs.
 * Also see Documentation/mutex-design.txt.
 */
extern void fastcall mutex_lock(struct mutex *lock);
extern int fastcall mutex_lock_interruptible(struct mutex *lock);
/*
 * NOTE: mutex_trylock() follows the spin_trylock() convention,
 *       not the down_trylock() convention!
 */
extern int fastcall mutex_trylock(struct mutex *lock);
extern void fastcall mutex_unlock(struct mutex *lock);

#endif
Commit	Line	Data
6053ee3b IM	1	/*
	2	* Mutexes: blocking mutual exclusion locks
	3	*
	4	* started by Ingo Molnar:
	5	*
	6	* Copyright (C) 2004, 2005, 2006 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
	7	*
	8	* This file contains the main data structure and API definitions.
	9	*/
	10	#ifndef __LINUX_MUTEX_H
	11	#define __LINUX_MUTEX_H
	12
	13	#include <linux/list.h>
	14	#include <linux/spinlock_types.h>
	15
	16	#include <asm/atomic.h>
	17
	18	/*
	19	* Simple, straightforward mutexes with strict semantics:
	20	*
	21	* - only one task can hold the mutex at a time
	22	* - only the owner can unlock the mutex
	23	* - multiple unlocks are not permitted
	24	* - recursive locking is not permitted
	25	* - a mutex object must be initialized via the API
	26	* - a mutex object must not be initialized via memset or copying
	27	* - task may not exit with mutex held
	28	* - memory areas where held locks reside must not be freed
	29	* - held mutexes must not be reinitialized
	30	* - mutexes may not be used in irq contexts
	31	*
	32	* These semantics are fully enforced when DEBUG_MUTEXES is
	33	* enabled. Furthermore, besides enforcing the above rules, the mutex
	34	* debugging code also implements a number of additional features
	35	* that make lock debugging easier and faster:
	36	*
	37	* - uses symbolic names of mutexes, whenever they are printed in debug output
	38	* - point-of-acquire tracking, symbolic lookup of function names
	39	* - list of all locks held in the system, printout of them
	40	* - owner tracking
	41	* - detects self-recursing locks and prints out all relevant info
	42	* - detects multi-task circular deadlocks and prints out all affected
	43	* locks and tasks (and only those tasks)
	44	*/
	45	struct mutex {
	46	/* 1: unlocked, 0: locked, negative: locked, possible waiters */
	47	atomic_t count;
	48	spinlock_t wait_lock;
	49	struct list_head wait_list;
	50	#ifdef CONFIG_DEBUG_MUTEXES
	51	struct thread_info *owner;
	52	struct list_head held_list;
	53	unsigned long acquire_ip;
	54	const char *name;
	55	void *magic;
	56	#endif
	57	};
	58
	59	/*
	60	* This is the control structure for tasks blocked on mutex,
	61	* which resides on the blocked task's kernel stack:
	62	*/
	63	struct mutex_waiter {
	64	struct list_head list;
65	struct task_struct *task;
66	#ifdef CONFIG_DEBUG_MUTEXES
67	struct mutex *lock;
68	void *magic;
69	#endif
70	};
71
72	#ifdef CONFIG_DEBUG_MUTEXES
73	# include <linux/mutex-debug.h>
74	#else
75	# define __DEBUG_MUTEX_INITIALIZER(lockname)
76	# define mutex_init(mutex) __mutex_init(mutex, NULL)
77	# define mutex_destroy(mutex) do { } while (0)
78	# define mutex_debug_show_all_locks() do { } while (0)
79	# define mutex_debug_show_held_locks(p) do { } while (0)
80	# define mutex_debug_check_no_locks_held(task) do { } while (0)
81	# define mutex_debug_check_no_locks_freed(from, to) do { } while (0)
82	#endif
83
84	#define __MUTEX_INITIALIZER(lockname) \
85	{ .count = ATOMIC_INIT(1) \
86	, .wait_lock = SPIN_LOCK_UNLOCKED \
87	, .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
88	__DEBUG_MUTEX_INITIALIZER(lockname) }
89
90	#define DEFINE_MUTEX(mutexname) \
91	struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
92
93	extern void fastcall __mutex_init(struct mutex lock, const char name);
94
95	/***
96	* mutex_is_locked - is the mutex locked
97	* @lock: the mutex to be queried
98	*
99	* Returns 1 if the mutex is locked, 0 if unlocked.
100	*/
101	static inline int fastcall mutex_is_locked(struct mutex *lock)
102	{
103	return atomic_read(&lock->count) != 1;
104	}
105
106	/*
107	* See kernel/mutex.c for detailed documentation of these APIs.
108	* Also see Documentation/mutex-design.txt.
109	*/
110	extern void fastcall mutex_lock(struct mutex *lock);
111	extern int fastcall mutex_lock_interruptible(struct mutex *lock);
112	/*
113	* NOTE: mutex_trylock() follows the spin_trylock() convention,
114	* not the down_trylock() convention!
115	*/
116	extern int fastcall mutex_trylock(struct mutex *lock);
117	extern void fastcall mutex_unlock(struct mutex *lock);
118
119	#endif