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*	cl_atomic_xchg, cl_atomic_comp_xchg
92*********/
93
94/****f* Component Library: Atomic Operations/cl_atomic_dec
95* NAME
96*	cl_atomic_dec
97*
98* DESCRIPTION
99*	The cl_atomic_dec function atomically decrements a 32-bit signed
100*	integer and returns the decremented value.
101*
102* SYNOPSIS
103*/
104int32_t cl_atomic_dec(IN atomic32_t * const p_value);
105/*
106* PARAMETERS
107*	p_value
108*		[in] Pointer to a 32-bit integer to decrement.
109*
110* RETURN VALUE
111*	Returns the decremented value pointed to by p_value.
112*
113* NOTES
114*	The provided value is decremented and its value returned in one atomic
115*	operation.
116*
117*	cl_atomic_dec maintains data consistency without requiring additional
118*	synchronization mechanisms in multi-threaded environments.
119*
120* SEE ALSO
121*	Atomic Operations, cl_atomic_inc, cl_atomic_add, cl_atomic_sub,
122*	cl_atomic_xchg, cl_atomic_comp_xchg
123*********/
124
125/****f* Component Library: Atomic Operations/cl_atomic_add
126* NAME
127*	cl_atomic_add
128*
129* DESCRIPTION
130*	The cl_atomic_add function atomically adds a value to a
131*	32-bit signed integer and returns the resulting value.
132*
133* SYNOPSIS
134*/
135int32_t
136cl_atomic_add(IN atomic32_t * const p_value, IN const int32_t increment);
137/*
138* PARAMETERS
139*	p_value
140*		[in] Pointer to a 32-bit integer that will be added to.
141*
142*	increment
143*		[in] Value by which to increment the integer pointed to by p_value.
144*
145* RETURN VALUE
146*	Returns the value pointed to by p_value after the addition.
147*
148* NOTES
149*	The provided increment is added to the value and the result returned in
150*	one atomic operation.
151*
152*	cl_atomic_add maintains data consistency without requiring additional
153*	synchronization mechanisms in multi-threaded environments.
154*
155* SEE ALSO
156*	Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_sub,
157*	cl_atomic_xchg, cl_atomic_comp_xchg
158*********/
159
160/****f* Component Library: Atomic Operations/cl_atomic_sub
161* NAME
162*	cl_atomic_sub
163*
164* DESCRIPTION
165*	The cl_atomic_sub function atomically subtracts a value from a
166*	32-bit signed integer and returns the resulting value.
167*
168* SYNOPSIS
169*/
170int32_t
171cl_atomic_sub(IN atomic32_t * const p_value, IN const int32_t decrement);
172/*
173* PARAMETERS
174*	p_value
175*		[in] Pointer to a 32-bit integer that will be subtracted from.
176*
177*	decrement
178*		[in] Value by which to decrement the integer pointed to by p_value.
179*
180* RETURN VALUE
181*	Returns the value pointed to by p_value after the subtraction.
182*
183* NOTES
184*	The provided decrement is subtracted from the value and the result
185*	returned in one atomic operation.
186*
187*	cl_atomic_sub maintains data consistency without requiring additional
188*	synchronization mechanisms in multi-threaded environments.
189*
190* SEE ALSO
191*	Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_add,
192*	cl_atomic_xchg, cl_atomic_comp_xchg
193*********/
194
195END_C_DECLS
196#endif				/* _CL_ATOMIC_H_ */
197