[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_waitobj.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 wait object.\r
37  * \r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_WAITOBJ_H_\r
44 #define _CL_WAITOBJ_H_\r
45 \r
46 \r
47 #include <complib/cl_waitobj_osd.h>\r
48 \r
49 \r
50 /****h* Component Library/Wait Object\r
51 * NAME\r
52 *       Wait Object\r
53 *\r
54 * DESCRIPTION\r
55 *       The Wait Object provides the capability for a user mode process to\r
56 *       create and manipulate a wait object that can also be manipulated from\r
57 *       kernel mode.\r
58 *\r
59 * SEE ALSO\r
60 *       Structures:\r
61 *               cl_waitobj_handle_t\r
62 *\r
63 *       User Mode Initialization/Destruction:\r
64 *               cl_waitobj_create\r
65 *               cl_waitobj_destroy\r
66 *\r
67 *       Kernel Mode Access:\r
68 *               cl_waitobj_ref\r
69 *               cl_waitobj_deref\r
70 *\r
71 *       Manipulation:\r
72 *               cl_waitobj_signal\r
73 *               cl_waitobj_reset\r
74 *               cl_waitobj_wait_on\r
75 ******/\r
76 \r
77 \r
78 /****d* Component Library: Wait Object/cl_waitobj_handle_t\r
79 * NAME\r
80 *       cl_waitobj_handle_t\r
81 *\r
82 * DESCRIPTION\r
83 *       Defines the handle for an OS wait object.\r
84 *\r
85 * NOTES\r
86 *       The wait object handle should be treated as opaque and is defined\r
87 *       differently depending on the target environment.\r
88 *\r
89 * SEE ALSO\r
90 *       Wait Object, cl_waitobj_create, cl_waitobj_destroy,\r
91 *       cl_waitobj_ref, cl_waitobj_deref, cl_waitobj_signal,\r
92 *       cl_waitobj_reset, cl_waitobj_wait_on\r
93 ******/\r
94 \r
95 \r
96 #ifdef __cplusplus\r
97 extern "C"\r
98 {\r
99 #endif  /* __cplusplus */\r
100 \r
101 \r
102 #if defined(CL_KERNEL)\r
103 \r
104 /****f* Component Library: Wait Object/cl_waitobj_ref\r
105 * NAME\r
106 *       cl_waitobj_ref\r
107\r
108 * DESCRIPTION\r
109 *       The cl_waitobj_ref function validates a user mode wait object handle \r
110 *       and returns a kernel mode wait object handle.  A reference is taken\r
111 *       on the object to prevent its destruction even if the user mode \r
112 *       application destroys it.\r
113 *                                                               \r
114 * SYNOPSIS\r
115 */\r
116 CL_EXPORT cl_waitobj_handle_t CL_API\r
117 cl_waitobj_ref(\r
118         IN      void                                    *h_user_wait_obj );\r
119 /* \r
120 * PARAMETERS\r
121 *       h_user_wait_obj\r
122 *               [in] A wait object handle passed from user mode. \r
123 *\r
124 * RETURN VALUES\r
125 *       Returns a kernel wait object handle upon success.  The returned handle \r
126 *       should only be used as parameters to kernel mode calls.\r
127 *\r
128 *       Returns NULL in case of failure.\r
129 *\r
130 * NOTES\r
131 *       This function is only available in kernel mode.\r
132 *\r
133 * SEE ALSO\r
134 *       Wait Object, cl_waitobj_handle_t, cl_waitobj_deref,\r
135 *       cl_waitobj_signal, cl_waitobj_reset, cl_waitobj_wait_on\r
136 ******/\r
137 \r
138 \r
139 /****f* Component Library: Wait Object/cl_waitobj_deref\r
140 * NAME\r
141 *       cl_waitobj_deref\r
142\r
143 * DESCRIPTION\r
144 *       The cl_waitobj_deref function release a reference on a kernel mode \r
145 *       wait object handle and allows the wait object to be destroyed.\r
146 *                                                               \r
147 * SYNOPSIS\r
148 */\r
149 CL_EXPORT void CL_API\r
150 cl_waitobj_deref(\r
151         IN      cl_waitobj_handle_t     h_kernel_wait_obj );\r
152 /* \r
153 * PARAMETERS\r
154 *       h_kernel_wait_obj\r
155 *               [in] A wait object handle returned by a previous call to cl_waitobj_ref. \r
156 *\r
157 * RETURN VALUES\r
158 *       This function does not return a value.\r
159 *\r
160 * NOTES\r
161 *       This function is only available in kernel mode.\r
162 *\r
163 * SEE ALSO\r
164 *       Wait Object, cl_waitobj_handle_t, cl_waitobj_ref, \r
165 *       cl_waitobj_signal, cl_waitobj_reset, cl_waitobj_wait_on\r
166 ******/\r
167 \r
168 #else   /* CL_KERNEL */\r
169 \r
170 /****f* Component Library: Wait Object/cl_waitobj_create\r
171 * NAME\r
172 *       cl_waitobj_create\r
173\r
174 * DESCRIPTION\r
175 *       The cl_waitobj_create function creates a wait object.\r
176 *\r
177 * SYNOPSIS\r
178 */\r
179 CL_EXPORT cl_status_t CL_API\r
180 cl_waitobj_create(\r
181         IN      const boolean_t                         manual_reset, \r
182         OUT     cl_waitobj_handle_t* const      ph_wait_obj );\r
183 /* \r
184 * PARAMETERS\r
185 *       manual_reset\r
186 *               [in] If FALSE, indicates that the event resets itself after releasing \r
187 *               a single waiter.  If TRUE, the event remains in the signalled state \r
188 *               until explicitly reset by a call to cl_event_reset.\r
189 *\r
190 *       ph_wait_obj\r
191 *               [out] Pointer to a wait object handle set upon successful creation.\r
192 *\r
193 * RETURN VALUES\r
194 *       CL_SUCCESS if the wait object was created successfully.\r
195 *\r
196 *       CL_ERROR if the wait object creation failed.\r
197 *\r
198 * NOTES\r
199 *       This function is only available in user mode.\r
200 *\r
201 * SEE ALSO\r
202 *       Wait Object, cl_waitobj_handle_t, cl_waitobj_destroy, \r
203 *       cl_waitobj_signal, cl_waitobj_reset, cl_waitobj_wait_on\r
204 ******/\r
205 \r
206 \r
207 /****f* Component Library: Wait Object/cl_waitobj_destroy\r
208 * NAME\r
209 *       cl_waitobj_destroy\r
210 *\r
211 * DESCRIPTION\r
212 *       The cl_waitobj_destroy function destroys a wait object.\r
213 *\r
214 * SYNOPSIS\r
215 */\r
216 CL_EXPORT cl_status_t CL_API\r
217 cl_waitobj_destroy(\r
218         IN      cl_waitobj_handle_t     h_wait_obj );\r
219 /* \r
220 * PARAMETERS\r
221 *       h_wait_obj\r
222 *               [in] A handle to the wait object to destroy, obtained by a pervious\r
223 *               call to cl_waitobj_create.\r
224 *\r
225 * RETURN VALUES\r
226 *       CL_SUCCESS if the wait object handle is destroyed.\r
227 *\r
228 *       CL_INVALID_PARAMETER if the wait object handle is invalid.\r
229 *\r
230 * NOTES\r
231 *       This function is only available in user mode.\r
232 *\r
233 * SEE ALSO\r
234 *       Wait Object, cl_waitobj_handle_t, cl_waitobj_create, \r
235 *       cl_waitobj_signal, cl_waitobj_reset, cl_waitobj_wait_on\r
236 *********/\r
237 \r
238 #endif  /* CL_KERNEL */\r
239 \r
240 /****f* Component Library: Wait Object/cl_waitobj_signal\r
241 * NAME\r
242 *       cl_waitobj_signal\r
243\r
244 * DESCRIPTION\r
245 *       The cl_waitobj_signal function sets a wait object to the signalled \r
246 *       state and releases one or more waiting threads.\r
247 *\r
248 * SYNOPSIS\r
249 */\r
250 CL_EXPORT cl_status_t CL_API\r
251 cl_waitobj_signal(\r
252         IN      cl_waitobj_handle_t     h_wait_obj );\r
253 /* \r
254 * PARAMETERS\r
255 *       h_wait_obj\r
256 *               [in] A handle to the wait object that needs to be signaled.\r
257\r
258 * RETURN VALUES\r
259 *       CL_SUCCESS if the event was successfully signalled.\r
260 *\r
261 *       CL_ERROR otherwise.\r
262 *\r
263 * NOTES\r
264 *       For auto-reset wait objects, the wait object is reset automatically once \r
265 *       a wait operation is satisfied. \r
266 *\r
267 *       Triggering the wait object multiple times does not guarantee that the same \r
268 *       number of wait operations are satisfied. This is because wait objects are \r
269 *       either in a signalled on non-signalled state, and triggering a wait object \r
270 *       that is already in the signalled state has no effect.\r
271 *\r
272 *       In kernel mode, a pointer to a cl_event_t can safely be used instead of\r
273 *       a wait object handle.\r
274 *\r
275 * SEE ALSO\r
276 *       Wait Object, cl_waitobj_create, cl_waitobj_destroy,\r
277 *       cl_waitobj_ref, cl_waitobj_deref,\r
278 *       cl_waitobj_reset, cl_waitobj_wait_on\r
279 *********/\r
280 \r
281 \r
282 /****f* Component Library: Wait Object/cl_waitobj_reset\r
283 * NAME\r
284 *       cl_waitobj_reset\r
285 *\r
286 * DESCRIPTION\r
287 *       The cl_waitobj_reset function sets an wait object to the non-signalled state.\r
288 *\r
289 * SYNOPSIS\r
290 */\r
291 CL_EXPORT cl_status_t CL_API\r
292 cl_waitobj_reset(\r
293         IN      cl_waitobj_handle_t     h_wait_obj );\r
294 /*\r
295 * PARAMETERS\r
296 *       h_wait_obj\r
297 *               [in] A handle to the wait object that needs to reset.\r
298 *\r
299 * RETURN VALUES\r
300 *       CL_SUCCESS if the wait object was successfully reset.\r
301 *\r
302 *       CL_ERROR otherwise.\r
303 *\r
304 * NOTES\r
305 *       In kernel mode, a pointer to a cl_event_t can safely be used instead of\r
306 *       a wait object handle.\r
307 *\r
308 * SEE ALSO\r
309 *       Wait Object, cl_waitobj_create, cl_waitobj_destroy,\r
310 *       cl_waitobj_ref, cl_waitobj_deref,\r
311 *       cl_waitobj_signal, cl_waitobj_wait_on\r
312 *********/\r
313 \r
314 \r
315 /****f* Component Library: Wait Object/cl_waitobj_wait_on\r
316 * NAME\r
317 *       cl_waitobj_wait_on\r
318 *\r
319 * DESCRIPTION\r
320 *       The cl_waitobj_wait_on function waits for the specified wait object to be \r
321 *       triggered for a minimum amount of time.\r
322 *\r
323 * SYNOPSIS\r
324 */\r
325 CL_EXPORT cl_status_t CL_API\r
326 cl_waitobj_wait_on(\r
327         IN      cl_waitobj_handle_t             h_wait_obj,\r
328         IN      const uint32_t                  wait_us,\r
329         IN      const boolean_t                 interruptible );\r
330 /*\r
331 * PARAMETERS\r
332 *       h_wait_obj\r
333 *               [in] A handle to the wait object on which to wait.\r
334 *\r
335 *       wait_us \r
336 *               [in] Number of microseconds to wait.\r
337 *\r
338 *       interruptible\r
339 *               [in] Indicates whether the wait operation can be interrupted\r
340 *               by external signals.\r
341 *\r
342 * RETURN VALUES\r
343 *       CL_SUCCESS if the wait operation succeeded in response to the wait object \r
344 *       being set.\r
345 *\r
346 *       CL_TIMEOUT if the specified time period elapses.\r
347 *\r
348 *       CL_NOT_DONE if the wait was interrupted by an external signal.\r
349 *\r
350 *       CL_ERROR if the wait operation failed.\r
351 *\r
352 * NOTES\r
353 *       If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the \r
354 *       wait object is triggered and never timeout.\r
355 *\r
356 *       If the timeout value is zero, this function simply tests the state of \r
357 *       the wait object.\r
358 *\r
359 *       If the wait object is already in the signalled state at the time of the call\r
360 *       to cl_waitobj_wait_on, the call completes immediately with CL_SUCCESS.\r
361 *\r
362 *       In kernel mode, a pointer to a cl_event_t can safely be used instead of\r
363 *       a wait object handle.\r
364 *\r
365 * SEE ALSO\r
366 *       Wait Object, cl_waitobj_create, cl_waitobj_destroy,\r
367 *       cl_waitobj_ref, cl_waitobj_deref, \r
368 *       cl_waitobj_signal, cl_waitobj_reset\r
369 *********/\r
370 \r
371 \r
372 #ifdef __cplusplus\r
373 }       /* extern "C" */\r
374 #endif  /* __cplusplus */\r
375 \r
376 \r
377 #endif  /* _CL_WAITOBJ_H_ */\r