2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
6 * This software is available to you under a choice of one of two
7 * licenses. You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials
23 * provided with the distribution.
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
38 * Declaration of spin lock object.
41 #ifndef _CL_SPINLOCK_H_
42 #define _CL_SPINLOCK_H_
44 #include <complib/cl_spinlock_osd.h>
47 # define BEGIN_C_DECLS extern "C" {
48 # define END_C_DECLS }
49 #else /* !__cplusplus */
50 # define BEGIN_C_DECLS
52 #endif /* __cplusplus */
55 /****h* Public/Spinlock
60 * Spinlock provides synchronization between threads for exclusive access to
63 * The spinlock functions manipulate a cl_spinlock_t structure which should
64 * be treated as opaque and should be manipulated only through the provided
72 * cl_spinlock_construct, cl_spinlock_init, cl_spinlock_destroy
75 * cl_spinlock_acquire, cl_spinlock_release
76 * cl_spinlock_acquire_irq, cl_spinlock_release_irq
78 /****f* Component Library: Spinlock/cl_spinlock_construct
80 * cl_spinlock_construct
83 * The cl_spinlock_construct function initializes the state of a
88 void cl_spinlock_construct(IN cl_spinlock_t * const p_spinlock);
92 * [in] Pointer to a spin lock structure whose state to initialize.
95 * This function does not return a value.
98 * Allows calling cl_spinlock_destroy without first calling
101 * Calling cl_spinlock_construct is a prerequisite to calling any other
102 * spin lock function except cl_spinlock_init.
105 * Spinlock, cl_spinlock_init, cl_spinlock_destroy
108 /****f* Component Library: Spinlock/cl_spinlock_init
113 * The cl_spinlock_init function initializes a spin lock for use.
117 cl_status_t cl_spinlock_init(IN cl_spinlock_t * const p_spinlock);
121 * [in] Pointer to a spin lock structure to initialize.
124 * CL_SUCCESS if initialization succeeded.
126 * CL_ERROR if initialization failed. Callers should call
127 * cl_spinlock_destroy to clean up any resources allocated during
131 * Initialize the spin lock structure. Allows calling cl_spinlock_aquire
132 * and cl_spinlock_release.
135 * Spinlock, cl_spinlock_construct, cl_spinlock_destroy,
136 * cl_spinlock_acquire, cl_spinlock_acquire_irq,
137 * cl_spinlock_release, cl_spinlock_release
138 * cl_spinlock_release_irq, cl_spinlock_release_irq
141 /****f* Component Library: Spinlock/cl_spinlock_destroy
143 * cl_spinlock_destroy
146 * The cl_spinlock_destroy function performs all necessary cleanup of a
151 void cl_spinlock_destroy(IN cl_spinlock_t * const p_spinlock);
155 * [in] Pointer to a spin lock structure to destroy.
158 * This function does not return a value.
161 * Performs any necessary cleanup of a spin lock. This function must only
162 * be called if either cl_spinlock_construct or cl_spinlock_init has been
166 * Spinlock, cl_spinlock_construct, cl_spinlock_init
169 /****f* Component Library: Spinlock/cl_spinlock_acquire
171 * cl_spinlock_acquire
174 * The cl_spinlock_acquire function acquires a spin lock.
175 * This version of lock does not prevent an interrupt from
176 * occuring on the processor on which the code is being
177 * executed. To protect from an interrupt level resource
178 * use the cl_spinlock_acquire_irq function.
182 void cl_spinlock_acquire(IN cl_spinlock_t * const p_spinlock);
186 * [in] Pointer to a spin lock structure to acquire.
189 * This function does not return a value.
192 * Spinlock, cl_spinlock_acquire_irq, cl_spinlock_release
193 * cl_spinlock_release_irq
196 /****f* Component Library: Spinlock/cl_spinlock_acquire_irq
198 * cl_spinlock_acquire_irq
201 * The cl_spinlock_acquire_irq function acquires a spin lock and protects
202 * the current processor from taking interrupts. If you need to protect
203 * a variable from an interrupt resource, use this version to acquire
208 void cl_spinlock_acquire_irq(IN cl_spinlock_t * const p_spinlock);
212 * [in] Pointer to a spin lock structure to acquire.
215 * This function does not return a value.
218 * Spinlock, cl_spinlock_release_irq
221 /****f* Component Library: Spinlock/cl_spinlock_release
223 * cl_spinlock_release
226 * The cl_spinlock_release function releases a spin lock object.
230 void cl_spinlock_release(IN cl_spinlock_t * const p_spinlock);
234 * [in] Pointer to a spin lock structure to release.
237 * This function does not return a value.
240 * Releases a spin lock after a call to cl_spinlock_acquire.
243 * Spinlock, cl_spinlock_acquire
246 /****f* Component Library: Spinlock/cl_spinlock_release_irq
248 * cl_spinlock_release_irq
251 * The cl_spinlock_release_irq function releases a spin lock object.
255 void cl_spinlock_release_irq(IN cl_spinlock_t * const p_spinlock);
259 * [in] Pointer to a spin lock structure to release.
262 * This function does not return a value.
265 * Releases a spin lock after a call to cl_spinlock_acquire.
268 * Spinlock, cl_spinlock_acquire_irq
272 #endif /* _CL_SPINLOCK_H_ */