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 54BEGIN_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* cl_spinlock_acquire_irq, cl_spinlock_release_irq 77*********/ 78/****f* Component Library: Spinlock/cl_spinlock_construct 79* NAME 80* cl_spinlock_construct 81* 82* DESCRIPTION 83* The cl_spinlock_construct function initializes the state of a 84* spin lock. 85* 86* SYNOPSIS 87*/ 88void cl_spinlock_construct(IN cl_spinlock_t * const p_spinlock); 89/* 90* PARAMETERS 91* p_spin_lock 92* [in] Pointer to a spin lock structure whose state to initialize. 93* 94* RETURN VALUE 95* This function does not return a value. 96* 97* NOTES 98* Allows calling cl_spinlock_destroy without first calling 99* cl_spinlock_init. 100* 101* Calling cl_spinlock_construct is a prerequisite to calling any other 102* spin lock function except cl_spinlock_init. 103* 104* SEE ALSO 105* Spinlock, cl_spinlock_init, cl_spinlock_destroy 106*********/ 107 108/****f* Component Library: Spinlock/cl_spinlock_init 109* NAME 110* cl_spinlock_init 111* 112* DESCRIPTION 113* The cl_spinlock_init function initializes a spin lock for use. 114* 115* SYNOPSIS 116*/ 117cl_status_t cl_spinlock_init(IN cl_spinlock_t * const p_spinlock); 118/* 119* PARAMETERS 120* p_spin_lock 121* [in] Pointer to a spin lock structure to initialize. 122* 123* RETURN VALUES 124* CL_SUCCESS if initialization succeeded. 125* 126* CL_ERROR if initialization failed. Callers should call 127* cl_spinlock_destroy to clean up any resources allocated during 128* initialization. 129* 130* NOTES 131* Initialize the spin lock structure. Allows calling cl_spinlock_aquire 132* and cl_spinlock_release. 133* 134* SEE ALSO 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 139*********/ 140 141/****f* Component Library: Spinlock/cl_spinlock_destroy 142* NAME 143* cl_spinlock_destroy 144* 145* DESCRIPTION 146* The cl_spinlock_destroy function performs all necessary cleanup of a 147* spin lock. 148* 149* SYNOPSIS 150*/ 151void cl_spinlock_destroy(IN cl_spinlock_t * const p_spinlock); 152/* 153* PARAMETERS 154* p_spin_lock 155* [in] Pointer to a spin lock structure to destroy. 156* 157* RETURN VALUE 158* This function does not return a value. 159* 160* NOTES 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 163* called. 164* 165* SEE ALSO 166* Spinlock, cl_spinlock_construct, cl_spinlock_init 167*********/ 168 169/****f* Component Library: Spinlock/cl_spinlock_acquire 170* NAME 171* cl_spinlock_acquire 172* 173* DESCRIPTION 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. 179* 180* SYNOPSIS 181*/ 182void cl_spinlock_acquire(IN cl_spinlock_t * const p_spinlock); 183/* 184* PARAMETERS 185* p_spin_lock 186* [in] Pointer to a spin lock structure to acquire. 187* 188* RETURN VALUE 189* This function does not return a value. 190* 191* SEE ALSO 192* Spinlock, cl_spinlock_acquire_irq, cl_spinlock_release 193* cl_spinlock_release_irq 194*********/ 195 196/****f* Component Library: Spinlock/cl_spinlock_acquire_irq 197* NAME 198* cl_spinlock_acquire_irq 199* 200* DESCRIPTION 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 204* a lock. 205* 206* SYNOPSIS 207*/ 208void cl_spinlock_acquire_irq(IN cl_spinlock_t * const p_spinlock); 209/* 210* PARAMETERS 211* p_spin_lock 212* [in] Pointer to a spin lock structure to acquire. 213* 214* RETURN VALUE 215* This function does not return a value. 216* 217* SEE ALSO 218* Spinlock, cl_spinlock_release_irq 219*********/ 220 221/****f* Component Library: Spinlock/cl_spinlock_release 222* NAME 223* cl_spinlock_release 224* 225* DESCRIPTION 226* The cl_spinlock_release function releases a spin lock object. 227* 228* SYNOPSIS 229*/ 230void cl_spinlock_release(IN cl_spinlock_t * const p_spinlock); 231/* 232* PARAMETERS 233* p_spin_lock 234* [in] Pointer to a spin lock structure to release. 235* 236* RETURN VALUE 237* This function does not return a value. 238* 239* NOTES 240* Releases a spin lock after a call to cl_spinlock_acquire. 241* 242* SEE ALSO 243* Spinlock, cl_spinlock_acquire 244*********/ 245 246/****f* Component Library: Spinlock/cl_spinlock_release_irq 247* NAME 248* cl_spinlock_release_irq 249* 250* DESCRIPTION 251* The cl_spinlock_release_irq function releases a spin lock object. 252* 253* SYNOPSIS 254*/ 255void cl_spinlock_release_irq(IN cl_spinlock_t * const p_spinlock); 256/* 257* PARAMETERS 258* p_spin_lock 259* [in] Pointer to a spin lock structure to release. 260* 261* RETURN VALUE 262* This function does not return a value. 263* 264* NOTES 265* Releases a spin lock after a call to cl_spinlock_acquire. 266* 267* SEE ALSO 268* Spinlock, cl_spinlock_acquire_irq 269*********/ 270 271END_C_DECLS 272#endif /* _CL_SPINLOCK_H_ */ 273