1/*
2 * Copyright (c) 2004-2006 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 atomic manipulation functions.
39 */
40
41#ifndef _CL_ATOMIC_H_
42#define _CL_ATOMIC_H_
43
44#include <complib/cl_atomic_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* Component Library/Atomic Operations
56* NAME
57*	Atomic Operations
58*
59* DESCRIPTION
60*	The Atomic Operations functions allow callers to operate on
61*	32-bit signed integers in an atomic fashion.
62*********/
63/****f* Component Library: Atomic Operations/cl_atomic_inc
64* NAME
65*	cl_atomic_inc
66*
67* DESCRIPTION
68*	The cl_atomic_inc function atomically increments a 32-bit signed
69*	integer and returns the incremented value.
70*
71* SYNOPSIS
72*/
73int32_t cl_atomic_inc(IN atomic32_t * const p_value);
74/*
75* PARAMETERS
76*	p_value
77*		[in] Pointer to a 32-bit integer to increment.
78*
79* RETURN VALUE
80*	Returns the incremented value pointed to by p_value.
81*
82* NOTES
83*	The provided value is incremented and its value returned in one atomic
84*	operation.
85*
86*	cl_atomic_inc maintains data consistency without requiring additional
87*	synchronization mechanisms in multi-threaded environments.
88*
89* SEE ALSO
90*	Atomic Operations, cl_atomic_dec, cl_atomic_add, cl_atomic_sub
91*********/
92
93/****f* Component Library: Atomic Operations/cl_atomic_dec
94* NAME
95*	cl_atomic_dec
96*
97* DESCRIPTION
98*	The cl_atomic_dec function atomically decrements a 32-bit signed
99*	integer and returns the decremented value.
100*
101* SYNOPSIS
102*/
103int32_t cl_atomic_dec(IN atomic32_t * const p_value);
104/*
105* PARAMETERS
106*	p_value
107*		[in] Pointer to a 32-bit integer to decrement.
108*
109* RETURN VALUE
110*	Returns the decremented value pointed to by p_value.
111*
112* NOTES
113*	The provided value is decremented and its value returned in one atomic
114*	operation.
115*
116*	cl_atomic_dec maintains data consistency without requiring additional
117*	synchronization mechanisms in multi-threaded environments.
118*
119* SEE ALSO
120*	Atomic Operations, cl_atomic_inc, cl_atomic_add, cl_atomic_sub
121*********/
122
123/****f* Component Library: Atomic Operations/cl_atomic_add
124* NAME
125*	cl_atomic_add
126*
127* DESCRIPTION
128*	The cl_atomic_add function atomically adds a value to a
129*	32-bit signed integer and returns the resulting value.
130*
131* SYNOPSIS
132*/
133int32_t
134cl_atomic_add(IN atomic32_t * const p_value, IN const int32_t increment);
135/*
136* PARAMETERS
137*	p_value
138*		[in] Pointer to a 32-bit integer that will be added to.
139*
140*	increment
141*		[in] Value by which to increment the integer pointed to by p_value.
142*
143* RETURN VALUE
144*	Returns the value pointed to by p_value after the addition.
145*
146* NOTES
147*	The provided increment is added to the value and the result returned in
148*	one atomic operation.
149*
150*	cl_atomic_add maintains data consistency without requiring additional
151*	synchronization mechanisms in multi-threaded environments.
152*
153* SEE ALSO
154*	Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_sub
155*********/
156
157/****f* Component Library: Atomic Operations/cl_atomic_sub
158* NAME
159*	cl_atomic_sub
160*
161* DESCRIPTION
162*	The cl_atomic_sub function atomically subtracts a value from a
163*	32-bit signed integer and returns the resulting value.
164*
165* SYNOPSIS
166*/
167int32_t
168cl_atomic_sub(IN atomic32_t * const p_value, IN const int32_t decrement);
169/*
170* PARAMETERS
171*	p_value
172*		[in] Pointer to a 32-bit integer that will be subtracted from.
173*
174*	decrement
175*		[in] Value by which to decrement the integer pointed to by p_value.
176*
177* RETURN VALUE
178*	Returns the value pointed to by p_value after the subtraction.
179*
180* NOTES
181*	The provided decrement is subtracted from the value and the result
182*	returned in one atomic operation.
183*
184*	cl_atomic_sub maintains data consistency without requiring additional
185*	synchronization mechanisms in multi-threaded environments.
186*
187* SEE ALSO
188*	Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_add
189*********/
190
191END_C_DECLS
192#endif				/* _CL_ATOMIC_H_ */
193