cl_spinlock.h revision 219820
1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of spin lock object. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_SPINLOCK_H_ 42219820Sjeff#define _CL_SPINLOCK_H_ 43219820Sjeff 44219820Sjeff#include <complib/cl_spinlock_osd.h> 45219820Sjeff 46219820Sjeff#ifdef __cplusplus 47219820Sjeff# define BEGIN_C_DECLS extern "C" { 48219820Sjeff# define END_C_DECLS } 49219820Sjeff#else /* !__cplusplus */ 50219820Sjeff# define BEGIN_C_DECLS 51219820Sjeff# define END_C_DECLS 52219820Sjeff#endif /* __cplusplus */ 53219820Sjeff 54219820SjeffBEGIN_C_DECLS 55219820Sjeff/****h* Public/Spinlock 56219820Sjeff* NAME 57219820Sjeff* Spinlock 58219820Sjeff* 59219820Sjeff* DESCRIPTION 60219820Sjeff* Spinlock provides synchronization between threads for exclusive access to 61219820Sjeff* a resource. 62219820Sjeff* 63219820Sjeff* The spinlock functions manipulate a cl_spinlock_t structure which should 64219820Sjeff* be treated as opaque and should be manipulated only through the provided 65219820Sjeff* functions. 66219820Sjeff* 67219820Sjeff* SEE ALSO 68219820Sjeff* Structures: 69219820Sjeff* cl_spinlock_t 70219820Sjeff* 71219820Sjeff* Initialization: 72219820Sjeff* cl_spinlock_construct, cl_spinlock_init, cl_spinlock_destroy 73219820Sjeff* 74219820Sjeff* Manipulation 75219820Sjeff* cl_spinlock_acquire, cl_spinlock_release 76219820Sjeff* cl_spinlock_acquire_irq, cl_spinlock_release_irq 77219820Sjeff*********/ 78219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_construct 79219820Sjeff* NAME 80219820Sjeff* cl_spinlock_construct 81219820Sjeff* 82219820Sjeff* DESCRIPTION 83219820Sjeff* The cl_spinlock_construct function initializes the state of a 84219820Sjeff* spin lock. 85219820Sjeff* 86219820Sjeff* SYNOPSIS 87219820Sjeff*/ 88219820Sjeffvoid cl_spinlock_construct(IN cl_spinlock_t * const p_spinlock); 89219820Sjeff/* 90219820Sjeff* PARAMETERS 91219820Sjeff* p_spin_lock 92219820Sjeff* [in] Pointer to a spin lock structure whose state to initialize. 93219820Sjeff* 94219820Sjeff* RETURN VALUE 95219820Sjeff* This function does not return a value. 96219820Sjeff* 97219820Sjeff* NOTES 98219820Sjeff* Allows calling cl_spinlock_destroy without first calling 99219820Sjeff* cl_spinlock_init. 100219820Sjeff* 101219820Sjeff* Calling cl_spinlock_construct is a prerequisite to calling any other 102219820Sjeff* spin lock function except cl_spinlock_init. 103219820Sjeff* 104219820Sjeff* SEE ALSO 105219820Sjeff* Spinlock, cl_spinlock_init, cl_spinlock_destroy 106219820Sjeff*********/ 107219820Sjeff 108219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_init 109219820Sjeff* NAME 110219820Sjeff* cl_spinlock_init 111219820Sjeff* 112219820Sjeff* DESCRIPTION 113219820Sjeff* The cl_spinlock_init function initializes a spin lock for use. 114219820Sjeff* 115219820Sjeff* SYNOPSIS 116219820Sjeff*/ 117219820Sjeffcl_status_t cl_spinlock_init(IN cl_spinlock_t * const p_spinlock); 118219820Sjeff/* 119219820Sjeff* PARAMETERS 120219820Sjeff* p_spin_lock 121219820Sjeff* [in] Pointer to a spin lock structure to initialize. 122219820Sjeff* 123219820Sjeff* RETURN VALUES 124219820Sjeff* CL_SUCCESS if initialization succeeded. 125219820Sjeff* 126219820Sjeff* CL_ERROR if initialization failed. Callers should call 127219820Sjeff* cl_spinlock_destroy to clean up any resources allocated during 128219820Sjeff* initialization. 129219820Sjeff* 130219820Sjeff* NOTES 131219820Sjeff* Initialize the spin lock structure. Allows calling cl_spinlock_aquire 132219820Sjeff* and cl_spinlock_release. 133219820Sjeff* 134219820Sjeff* SEE ALSO 135219820Sjeff* Spinlock, cl_spinlock_construct, cl_spinlock_destroy, 136219820Sjeff* cl_spinlock_acquire, cl_spinlock_acquire_irq, 137219820Sjeff* cl_spinlock_release, cl_spinlock_release 138219820Sjeff* cl_spinlock_release_irq, cl_spinlock_release_irq 139219820Sjeff*********/ 140219820Sjeff 141219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_destroy 142219820Sjeff* NAME 143219820Sjeff* cl_spinlock_destroy 144219820Sjeff* 145219820Sjeff* DESCRIPTION 146219820Sjeff* The cl_spinlock_destroy function performs all necessary cleanup of a 147219820Sjeff* spin lock. 148219820Sjeff* 149219820Sjeff* SYNOPSIS 150219820Sjeff*/ 151219820Sjeffvoid cl_spinlock_destroy(IN cl_spinlock_t * const p_spinlock); 152219820Sjeff/* 153219820Sjeff* PARAMETERS 154219820Sjeff* p_spin_lock 155219820Sjeff* [in] Pointer to a spin lock structure to destroy. 156219820Sjeff* 157219820Sjeff* RETURN VALUE 158219820Sjeff* This function does not return a value. 159219820Sjeff* 160219820Sjeff* NOTES 161219820Sjeff* Performs any necessary cleanup of a spin lock. This function must only 162219820Sjeff* be called if either cl_spinlock_construct or cl_spinlock_init has been 163219820Sjeff* called. 164219820Sjeff* 165219820Sjeff* SEE ALSO 166219820Sjeff* Spinlock, cl_spinlock_construct, cl_spinlock_init 167219820Sjeff*********/ 168219820Sjeff 169219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_acquire 170219820Sjeff* NAME 171219820Sjeff* cl_spinlock_acquire 172219820Sjeff* 173219820Sjeff* DESCRIPTION 174219820Sjeff* The cl_spinlock_acquire function acquires a spin lock. 175219820Sjeff* This version of lock does not prevent an interrupt from 176219820Sjeff* occuring on the processor on which the code is being 177219820Sjeff* executed. To protect from an interrupt level resource 178219820Sjeff* use the cl_spinlock_acquire_irq function. 179219820Sjeff* 180219820Sjeff* SYNOPSIS 181219820Sjeff*/ 182219820Sjeffvoid cl_spinlock_acquire(IN cl_spinlock_t * const p_spinlock); 183219820Sjeff/* 184219820Sjeff* PARAMETERS 185219820Sjeff* p_spin_lock 186219820Sjeff* [in] Pointer to a spin lock structure to acquire. 187219820Sjeff* 188219820Sjeff* RETURN VALUE 189219820Sjeff* This function does not return a value. 190219820Sjeff* 191219820Sjeff* SEE ALSO 192219820Sjeff* Spinlock, cl_spinlock_acquire_irq, cl_spinlock_release 193219820Sjeff* cl_spinlock_release_irq 194219820Sjeff*********/ 195219820Sjeff 196219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_acquire_irq 197219820Sjeff* NAME 198219820Sjeff* cl_spinlock_acquire_irq 199219820Sjeff* 200219820Sjeff* DESCRIPTION 201219820Sjeff* The cl_spinlock_acquire_irq function acquires a spin lock and protects 202219820Sjeff* the current processor from taking interrupts. If you need to protect 203219820Sjeff* a variable from an interrupt resource, use this version to acquire 204219820Sjeff* a lock. 205219820Sjeff* 206219820Sjeff* SYNOPSIS 207219820Sjeff*/ 208219820Sjeffvoid cl_spinlock_acquire_irq(IN cl_spinlock_t * const p_spinlock); 209219820Sjeff/* 210219820Sjeff* PARAMETERS 211219820Sjeff* p_spin_lock 212219820Sjeff* [in] Pointer to a spin lock structure to acquire. 213219820Sjeff* 214219820Sjeff* RETURN VALUE 215219820Sjeff* This function does not return a value. 216219820Sjeff* 217219820Sjeff* SEE ALSO 218219820Sjeff* Spinlock, cl_spinlock_release_irq 219219820Sjeff*********/ 220219820Sjeff 221219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_release 222219820Sjeff* NAME 223219820Sjeff* cl_spinlock_release 224219820Sjeff* 225219820Sjeff* DESCRIPTION 226219820Sjeff* The cl_spinlock_release function releases a spin lock object. 227219820Sjeff* 228219820Sjeff* SYNOPSIS 229219820Sjeff*/ 230219820Sjeffvoid cl_spinlock_release(IN cl_spinlock_t * const p_spinlock); 231219820Sjeff/* 232219820Sjeff* PARAMETERS 233219820Sjeff* p_spin_lock 234219820Sjeff* [in] Pointer to a spin lock structure to release. 235219820Sjeff* 236219820Sjeff* RETURN VALUE 237219820Sjeff* This function does not return a value. 238219820Sjeff* 239219820Sjeff* NOTES 240219820Sjeff* Releases a spin lock after a call to cl_spinlock_acquire. 241219820Sjeff* 242219820Sjeff* SEE ALSO 243219820Sjeff* Spinlock, cl_spinlock_acquire 244219820Sjeff*********/ 245219820Sjeff 246219820Sjeff/****f* Component Library: Spinlock/cl_spinlock_release_irq 247219820Sjeff* NAME 248219820Sjeff* cl_spinlock_release_irq 249219820Sjeff* 250219820Sjeff* DESCRIPTION 251219820Sjeff* The cl_spinlock_release_irq function releases a spin lock object. 252219820Sjeff* 253219820Sjeff* SYNOPSIS 254219820Sjeff*/ 255219820Sjeffvoid cl_spinlock_release_irq(IN cl_spinlock_t * const p_spinlock); 256219820Sjeff/* 257219820Sjeff* PARAMETERS 258219820Sjeff* p_spin_lock 259219820Sjeff* [in] Pointer to a spin lock structure to release. 260219820Sjeff* 261219820Sjeff* RETURN VALUE 262219820Sjeff* This function does not return a value. 263219820Sjeff* 264219820Sjeff* NOTES 265219820Sjeff* Releases a spin lock after a call to cl_spinlock_acquire. 266219820Sjeff* 267219820Sjeff* SEE ALSO 268219820Sjeff* Spinlock, cl_spinlock_acquire_irq 269219820Sjeff*********/ 270219820Sjeff 271219820SjeffEND_C_DECLS 272219820Sjeff#endif /* _CL_SPINLOCK_H_ */ 273