[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_spinlock.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of spin lock object.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_SPINLOCK_H_\r
44 #define _CL_SPINLOCK_H_\r
45 \r
46 \r
47 #include <complib/cl_spinlock_osd.h>\r
48 \r
49 \r
50 /****h* Component Library/Spinlock\r
51 * NAME\r
52 *       Spinlock\r
53 *\r
54 * DESCRIPTION\r
55 *       Spinlock provides synchronization between threads for exclusive access to\r
56 *       a resource.\r
57 *\r
58 *       The spinlock functions manipulate a cl_spinlock_t structure which should\r
59 *       be treated as opaque and should be manipulated only through the provided\r
60 *       functions.\r
61 *\r
62 * SEE ALSO\r
63 *       Structures:\r
64 *               cl_spinlock_t\r
65 *\r
66 *       Initialization:\r
67 *               cl_spinlock_construct, cl_spinlock_init, cl_spinlock_destroy\r
68 *\r
69 *       Manipulation\r
70 *               cl_spinlock_acquire, cl_spinlock_release\r
71 *********/\r
72 \r
73 \r
74 #ifdef __cplusplus\r
75 extern "C"\r
76 {\r
77 #endif\r
78 \r
79 \r
80 /****f* Component Library: Spinlock/cl_spinlock_construct\r
81 * NAME\r
82 *       cl_spinlock_construct\r
83 *\r
84 * DESCRIPTION\r
85 *       The cl_spinlock_construct function initializes the state of a\r
86 *       spin lock.\r
87 *\r
88 * SYNOPSIS\r
89 */\r
90 CL_EXPORT void CL_API\r
91 cl_spinlock_construct(\r
92         IN      cl_spinlock_t* const    p_spinlock );\r
93 /*\r
94 * PARAMETERS\r
95 *       p_spinlock\r
96 *               [in] Pointer to a spin lock structure whose state to initialize.\r
97 *\r
98 * RETURN VALUE\r
99 *       This function does not return a value.\r
100 *\r
101 * NOTES\r
102 *       Allows calling cl_spinlock_destroy without first calling\r
103 *       cl_spinlock_init.\r
104 *\r
105 *       Calling cl_spinlock_construct is a prerequisite to calling any other\r
106 *       spin lock function except cl_spinlock_init.\r
107 *\r
108 * SEE ALSO\r
109 *       Spinlock, cl_spinlock_init, cl_spinlock_destroy\r
110 *********/\r
111 \r
112 \r
113 /****f* Component Library: Spinlock/cl_spinlock_init\r
114 * NAME\r
115 *       cl_spinlock_init\r
116 *\r
117 * DESCRIPTION\r
118 *       The cl_spinlock_init function initializes a spin lock for use.\r
119 *\r
120 * SYNOPSIS\r
121 */\r
122 CL_EXPORT cl_status_t CL_API\r
123 cl_spinlock_init(\r
124         IN      cl_spinlock_t* const    p_spinlock );\r
125 /*\r
126 * PARAMETERS\r
127 *       p_spinlock\r
128 *               [in] Pointer to a spin lock structure to initialize.\r
129 *\r
130 * RETURN VALUES\r
131 *       CL_SUCCESS if initialization succeeded.\r
132 *\r
133 *       CL_ERROR if initialization failed. Callers should call\r
134 *       cl_spinlock_destroy to clean up any resources allocated during\r
135 *       initialization.\r
136 *\r
137 * NOTES\r
138 *       Initialize the spin lock structure. Allows calling cl_spinlock_aquire\r
139 *       and cl_spinlock_release.\r
140 *\r
141 * SEE ALSO\r
142 *       Spinlock, cl_spinlock_construct, cl_spinlock_destroy,\r
143 *       cl_spinlock_acquire, cl_spinlock_release\r
144 *********/\r
145 \r
146 \r
147 /****f* Component Library: Spinlock/cl_spinlock_destroy\r
148 * NAME\r
149 *       cl_spinlock_destroy\r
150 *\r
151 * DESCRIPTION\r
152 *       The cl_spinlock_destroy function performs all necessary cleanup of a\r
153 *       spin lock.\r
154 *\r
155 * SYNOPSIS\r
156 */\r
157 CL_EXPORT void CL_API\r
158 cl_spinlock_destroy(\r
159         IN      cl_spinlock_t* const    p_spinlock );\r
160 /*\r
161 * PARAMETERS\r
162 *       p_spinlock\r
163 *               [in] Pointer to a spin lock structure to destroy.\r
164 *\r
165 * RETURN VALUE\r
166 *       This function does not return a value.\r
167 *\r
168 * NOTES\r
169 *       Performs any necessary cleanup of a spin lock. This function must only\r
170 *       be called if either cl_spinlock_construct or cl_spinlock_init has been\r
171 *       called.\r
172 *\r
173 * SEE ALSO\r
174 *       Spinlock, cl_spinlock_construct, cl_spinlock_init\r
175 *********/\r
176 \r
177 \r
178 /****f* Component Library: Spinlock/cl_spinlock_acquire\r
179 * NAME\r
180 *       cl_spinlock_acquire\r
181 *\r
182 * DESCRIPTION\r
183 *       The cl_spinlock_acquire function acquires a spin lock.\r
184 *       This version of lock does not prevent an interrupt from\r
185 *       occuring on the processor on which the code is being\r
186 *       executed.\r
187 *\r
188 * SYNOPSIS\r
189 */\r
190 CL_EXPORT void CL_API\r
191 cl_spinlock_acquire(\r
192         IN      cl_spinlock_t* const    p_spinlock );\r
193 /*\r
194 * PARAMETERS\r
195 *       p_spinlock\r
196 *               [in] Pointer to a spin lock structure to acquire.\r
197 *\r
198 * RETURN VALUE\r
199 *       This function does not return a value.\r
200 *\r
201 * SEE ALSO\r
202 *       Spinlock, cl_spinlock_release\r
203 *********/\r
204 \r
205 \r
206 /****f* Component Library: Spinlock/cl_spinlock_release\r
207 * NAME\r
208 *       cl_spinlock_release\r
209 *\r
210 * DESCRIPTION\r
211 *       The cl_spinlock_release function releases a spin lock object.\r
212 *\r
213 * SYNOPSIS\r
214 */\r
215 CL_EXPORT void CL_API\r
216 cl_spinlock_release(\r
217         IN      cl_spinlock_t* const    p_spinlock );\r
218 /*\r
219 * PARAMETERS\r
220 *       p_spinlock\r
221 *               [in] Pointer to a spin lock structure to release.\r
222 *\r
223 * RETURN VALUE\r
224 *       This function does not return a value.\r
225 *\r
226 * NOTES\r
227 *       Releases a spin lock after a call to cl_spinlock_acquire.\r
228 *\r
229 * SEE ALSO\r
230 *       Spinlock, cl_spinlock_acquire\r
231 *********/\r
232 \r
233 \r
234 #ifdef __cplusplus\r
235 }       /* extern "C" */\r
236 #endif\r
237 \r
238 #endif /* _CL_SPINLOCK_H_ */\r