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*********/ 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*/ 87void 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*/ 116cl_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*/ 148void 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*/ 178void 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*/ 200void 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 216END_C_DECLS 217#endif /* _CL_SPINLOCK_H_ */ 218