1 /* 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. 5 * 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: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 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. 24 * 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 32 * SOFTWARE. 33 * 34 */ 35 36 /* 37 * Abstract: 38 * Declaration of spin lock object. 39 */ 40 41 #ifndef _CL_SPINLOCK_H_ 42 #define _CL_SPINLOCK_H_ 43 44 #include <complib/cl_spinlock_osd.h> 45 46 #ifdef __cplusplus 47 # define BEGIN_C_DECLS extern "C" { 48 # define END_C_DECLS } 49 #else /* !__cplusplus */ 50 # define BEGIN_C_DECLS 51 # define END_C_DECLS 52 #endif /* __cplusplus */ 53 54 BEGIN_C_DECLS 55 /****h* Public/Spinlock 56 * NAME 57 * Spinlock 58 * 59 * DESCRIPTION 60 * Spinlock provides synchronization between threads for exclusive access to 61 * a resource. 62 * 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 65 * functions. 66 * 67 * SEE ALSO 68 * Structures: 69 * cl_spinlock_t 70 * 71 * Initialization: 72 * cl_spinlock_construct, cl_spinlock_init, cl_spinlock_destroy 73 * 74 * Manipulation 75 * cl_spinlock_acquire, cl_spinlock_release 76 *********/ 77 /****f* Component Library: Spinlock/cl_spinlock_construct 78 * NAME 79 * cl_spinlock_construct 80 * 81 * DESCRIPTION 82 * The cl_spinlock_construct function initializes the state of a 83 * spin lock. 84 * 85 * SYNOPSIS 86 */ 87 void cl_spinlock_construct(IN cl_spinlock_t * const p_spinlock); 88 /* 89 * PARAMETERS 90 * p_spin_lock 91 * [in] Pointer to a spin lock structure whose state to initialize. 92 * 93 * RETURN VALUE 94 * This function does not return a value. 95 * 96 * NOTES 97 * Allows calling cl_spinlock_destroy without first calling 98 * cl_spinlock_init. 99 * 100 * Calling cl_spinlock_construct is a prerequisite to calling any other 101 * spin lock function except cl_spinlock_init. 102 * 103 * SEE ALSO 104 * Spinlock, cl_spinlock_init, cl_spinlock_destroy 105 *********/ 106 107 /****f* Component Library: Spinlock/cl_spinlock_init 108 * NAME 109 * cl_spinlock_init 110 * 111 * DESCRIPTION 112 * The cl_spinlock_init function initializes a spin lock for use. 113 * 114 * SYNOPSIS 115 */ 116 cl_status_t cl_spinlock_init(IN cl_spinlock_t * const p_spinlock); 117 /* 118 * PARAMETERS 119 * p_spin_lock 120 * [in] Pointer to a spin lock structure to initialize. 121 * 122 * RETURN VALUES 123 * CL_SUCCESS if initialization succeeded. 124 * 125 * CL_ERROR if initialization failed. Callers should call 126 * cl_spinlock_destroy to clean up any resources allocated during 127 * initialization. 128 * 129 * NOTES 130 * Initialize the spin lock structure. Allows calling cl_spinlock_aquire 131 * and cl_spinlock_release. 132 * 133 * SEE ALSO 134 * Spinlock, cl_spinlock_construct, cl_spinlock_destroy, 135 * cl_spinlock_acquire, cl_spinlock_release 136 *********/ 137 138 /****f* Component Library: Spinlock/cl_spinlock_destroy 139 * NAME 140 * cl_spinlock_destroy 141 * 142 * DESCRIPTION 143 * The cl_spinlock_destroy function performs all necessary cleanup of a 144 * spin lock. 145 * 146 * SYNOPSIS 147 */ 148 void cl_spinlock_destroy(IN cl_spinlock_t * const p_spinlock); 149 /* 150 * PARAMETERS 151 * p_spin_lock 152 * [in] Pointer to a spin lock structure to destroy. 153 * 154 * RETURN VALUE 155 * This function does not return a value. 156 * 157 * NOTES 158 * Performs any necessary cleanup of a spin lock. This function must only 159 * be called if either cl_spinlock_construct or cl_spinlock_init has been 160 * called. 161 * 162 * SEE ALSO 163 * Spinlock, cl_spinlock_construct, cl_spinlock_init 164 *********/ 165 166 /****f* Component Library: Spinlock/cl_spinlock_acquire 167 * NAME 168 * cl_spinlock_acquire 169 * 170 * DESCRIPTION 171 * The cl_spinlock_acquire function acquires a spin lock. 172 * This version of lock does not prevent an interrupt from 173 * occuring on the processor on which the code is being 174 * executed. 175 * 176 * SYNOPSIS 177 */ 178 void cl_spinlock_acquire(IN cl_spinlock_t * const p_spinlock); 179 /* 180 * PARAMETERS 181 * p_spin_lock 182 * [in] Pointer to a spin lock structure to acquire. 183 * 184 * RETURN VALUE 185 * This function does not return a value. 186 * 187 * SEE ALSO 188 * Spinlock, cl_spinlock_release 189 *********/ 190 191 /****f* Component Library: Spinlock/cl_spinlock_release 192 * NAME 193 * cl_spinlock_release 194 * 195 * DESCRIPTION 196 * The cl_spinlock_release function releases a spin lock object. 197 * 198 * SYNOPSIS 199 */ 200 void cl_spinlock_release(IN cl_spinlock_t * const p_spinlock); 201 /* 202 * PARAMETERS 203 * p_spin_lock 204 * [in] Pointer to a spin lock structure to release. 205 * 206 * RETURN VALUE 207 * This function does not return a value. 208 * 209 * NOTES 210 * Releases a spin lock after a call to cl_spinlock_acquire. 211 * 212 * SEE ALSO 213 * Spinlock, cl_spinlock_acquire 214 *********/ 215 216 END_C_DECLS 217 #endif /* _CL_SPINLOCK_H_ */ 218