Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / vendor / qcom-opensource / wlan / prima / aa8e15a6b4d2aa0edb4a1bdcfbe021844bc045d6 / . / CORE / VOSS / inc / vos_lock.h
blob: f3c8ea20af4cf5c0e4da60ceb7d54a9dfb6d571d [file] [log] [blame]
Jeff Johnson295189b2012-06-20 16:38:30 -0700[diff] [blame]1/*
Kiet Lamaa8e15a2014-02-11 23:30:06 -0800[diff] [blame^]2 * Copyright (c) 2012-2013 Qualcomm Atheros, Inc.
3 * All Rights Reserved.
4 * Qualcomm Atheros Confidential and Proprietary.
Gopichand Nakkala92f07d82013-01-08 21:16:34 -0800[diff] [blame]5 */
Jeff Johnson295189b2012-06-20 16:38:30 -0700[diff] [blame]6#if !defined( __VOS_LOCK_H )
7#define __VOS_LOCK_H
8
9/**=========================================================================
10
11 \file vos_lock.h
12
13 \brief virtual Operating System Servies (vOS) Locks
14
15 Definitions for vOSS Locks
16
17 Copyright 2008 (c) Qualcomm, Incorporated. All Rights Reserved.
18
19 Qualcomm Confidential and Proprietary.
20
21 ========================================================================*/
22
23/* $Header$ */
24
25/*--------------------------------------------------------------------------
26 Include Files
27 ------------------------------------------------------------------------*/
28#include "vos_status.h"
29#include "i_vos_lock.h"
30
31/*--------------------------------------------------------------------------
32 Preprocessor definitions and constants
33 ------------------------------------------------------------------------*/
34
35/*--------------------------------------------------------------------------
36 Type declarations
37 ------------------------------------------------------------------------*/
38
39/*-------------------------------------------------------------------------
40 Function declarations and documenation
41 ------------------------------------------------------------------------*/
42
43/*--------------------------------------------------------------------------
44
45 \brief vos_lock_init() - initialize a vOSS lock
46
47 The \a vos_lock_init() function initializes the specified lock. Upon
48 successful initialization, the state of the lock becomes initialized
49 and unlocked.
50
51 A lock must be initialized by calling vos_lock_init() before it
52 may be used in any other lock functions.
53
54 Attempting to initialize an already initialized lock results in
55 a failure.
56
57 \param lock - pointer to the opaque lock object to initialize
58
59 \return VOS_STATUS_SUCCESS - lock was successfully initialized and
60 is ready to be used.
61
62 VOS_STATUS_E_RESOURCES - System resources (other than memory)
63 are unavailable to initilize the lock
64
65 VOS_STATUS_E_NOMEM - insufficient memory exists to initialize
66 the lock
67
68 VOS_STATUS_E_BUSY - The implementation has detected an attempt
69 to reinitialize the object referenced by lock, a previously
70 initialized, but not yet destroyed, lock.
71
72 VOS_STATUS_E_FAULT - lock is an invalid pointer.
73 \sa
74
75 --------------------------------------------------------------------------*/
76VOS_STATUS vos_lock_init( vos_lock_t *lock );
77
78/*--------------------------------------------------------------------------
79
80 \brief vos_lock_acquire() - acquire a lock
81
82 A lock object is acquired by calling \a vos_lock_acquire(). If the lock
83 is already locked, the calling thread shall block until the lock becomes
84 available. This operation shall return with the lock object referenced by
85 lock in the locked state with the calling thread as its owner.
86
87 \param lock - the lock object to acquire
88
89 \return VOS_STATUS_SUCCESS - the lock was successfully acquired by
90 the calling thread.
91
92 VOS_STATUS_E_INVAL - The value specified by lock does not refer
93 to an initialized lock object.
94
95 VOS_STATUS_E_FAULT - lock is an invalid pointer.
96
97 \sa
98
99 ------------------------------------------------------------------------*/
100VOS_STATUS vos_lock_acquire( vos_lock_t * lock );
101
102
103/*--------------------------------------------------------------------------
104
105 \brief vos_lock_release() - release a lock
106
107 The \a vos_lock_release() function shall release the lock object
108 referenced by 'lock'.
109
110 If a thread attempts to release a lock that it unlocked or is not
111 initialized, an error is returned.
112
113 \param lock - the lock to release
114
115 \return VOS_STATUS_SUCCESS - the lock was successfully released
116
117 VOS_STATUS_E_INVAL - The value specified by lock does not refer
118 to an initialized lock object.
119
120 VOS_STATUS_E_FAULT - The value specified by lock does not refer
121 to an initialized lock object.
122
123 VOS_STATUS_E_PERM - Operation is not permitted. The calling
124 thread does not own the lock.
125
126 \sa
127
128 ------------------------------------------------------------------------*/
129VOS_STATUS vos_lock_release( vos_lock_t *lock );
130
131
132/*--------------------------------------------------------------------------
133
134 \brief vos_lock_destroy() - Destroy a vOSS Lock
135
136 The \a vos_lock_destroy() function shall destroy the lock object
137 referenced by lock. After a successful return from \a vos_lock_destroy()
138 the lock object becomes, in effect, uninitialized.
139
140 A destroyed lock object can be reinitialized using vos_lock_init();
141 the results of otherwise referencing the object after it has been destroyed
142 are undefined. Calls to vOSS lock functions to manipulate the lock such
143 as vos_lock_acquire() will fail if the lock is destroyed. Therefore,
144 don't use the lock after it has been destroyed until it has
145 been re-initialized.
146
147 \param lock - the lock object to be destroyed.
148
149 \return VOS_STATUS_SUCCESS - lock was successfully destroyed.
150
151 VOS_STATUS_E_BUSY - The implementation has detected an attempt
152 to destroy the object referenced by lock while it is locked
153 or still referenced.
154
155 VOS_STATUS_E_INVAL - The value specified by lock is invalid.
156
157 VOS_STATUS_E_FAULT - lock is an invalid pointer.
158 \sa
159
160 ------------------------------------------------------------------------*/
161VOS_STATUS vos_lock_destroy( vos_lock_t *lock );
162
163/*--------------------------------------------------------------------------
164
165 \brief vos_spin_lock_init() - initializes a vOSS spin lock
166
167 The vos_spin_lock_init() function initializes the specified spin lock. Upon
168 successful initialization, the state of the lock becomes initialized
169 and unlocked.
170
171 A lock must be initialized by calling vos_spin_lock_init() before it
172 may be used in any other lock functions.
173
174 Attempting to initialize an already initialized lock results in
175 a failure.
176
177 \param pLock - pointer to the opaque lock object to initialize
178
179 \return VOS_STATUS_SUCCESS - spin lock was successfully initialized and
180 is ready to be used.
181 --------------------------------------------------------------------------*/
182VOS_STATUS vos_spin_lock_init(vos_spin_lock_t *pLock);
183
184/*--------------------------------------------------------------------------
185
186 \brief vos_spin_lock_acquire() - acquires a spin lock
187
188 A lock object is acquired by calling \a vos_spin_lock_acquire(). If the lock
189 is already locked, the calling thread shall spin until the lock becomes
190 available. This operation shall return with the lock object referenced by
191 lock in the locked state with the calling thread as its owner.
192
193 \param pLock - the lock object to acquire
194
195 \return VOS_STATUS_SUCCESS - the lock was successfully acquired by
196 the calling thread.
197
198 \sa
199 ------------------------------------------------------------------------*/
200VOS_STATUS vos_spin_lock_acquire(vos_spin_lock_t *pLock);
201
202/*--------------------------------------------------------------------------
203
204 \brief vos_spin_lock_release() - releases a lock
205
206 The \a vos_lock_release() function shall release the spin lock object
207 referenced by 'lock'.
208
209 If a thread attempts to release a lock that it unlocked or is not
210 initialized, an error is returned.
211
212 \param pLock - the lock to release
213
214 \return VOS_STATUS_SUCCESS - the lock was successfully released
215
216 \sa
217 ------------------------------------------------------------------------*/
218VOS_STATUS vos_spin_lock_release(vos_spin_lock_t *pLock);
219
220/*--------------------------------------------------------------------------
221
222 \brief vos_spin_lock_destroy() - releases resource of a lock
223
224 \param pLock - pointer to a lock to release
225
226 \return VOS_STATUS_SUCCESS - the lock was successfully released
227
228 \sa
229 ------------------------------------------------------------------------*/
230VOS_STATUS vos_spin_lock_destroy(vos_spin_lock_t *pLock);
231
232
233#endif // __VOSS_LOCK_H