1 /* 2 * Copyright (c) 2004, 2005 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 event abstraction. 39 */ 40 41 #ifndef _CL_EVENT_H_ 42 #define _CL_EVENT_H_ 43 44 /* Indicates that waiting on an event should never timeout */ 45 #define EVENT_NO_TIMEOUT 0xFFFFFFFF 46 47 #include <complib/cl_event_osd.h> 48 49 #ifdef __cplusplus 50 # define BEGIN_C_DECLS extern "C" { 51 # define END_C_DECLS } 52 #else /* !__cplusplus */ 53 # define BEGIN_C_DECLS 54 # define END_C_DECLS 55 #endif /* __cplusplus */ 56 57 BEGIN_C_DECLS 58 /****h* Component Library/Event 59 * NAME 60 * Event 61 * 62 * DESCRIPTION 63 * The Event provides the ability to suspend and wakeup a thread. 64 * 65 * The event functions operates on a cl_event_t structure which should be 66 * treated as opaque and should be manipulated only through the provided 67 * functions. 68 * 69 * SEE ALSO 70 * Structures: 71 * cl_event_t 72 * 73 * Initialization/Destruction: 74 * cl_event_construct, cl_event_init, cl_event_destroy 75 * 76 * Manipulation: 77 * cl_event_signal, cl_event_reset, cl_event_wait_on 78 *********/ 79 /****f* Component Library: Event/cl_event_construct 80 * NAME 81 * cl_event_construct 82 * 83 * DESCRIPTION 84 * The cl_event_construct function constructs an event. 85 * 86 * SYNOPSIS 87 */ 88 void cl_event_construct(IN cl_event_t * const p_event); 89 /* 90 * PARAMETERS 91 * p_event 92 * [in] Pointer to an cl_event_t structure to construct. 93 * 94 * RETURN VALUE 95 * This function does not return a value. 96 * 97 * NOTES 98 * Allows calling cl_event_destroy without first calling cl_event_init. 99 * 100 * Calling cl_event_construct is a prerequisite to calling any other event 101 * function except cl_event_init. 102 * 103 * SEE ALSO 104 * Event, cl_event_init, cl_event_destroy 105 *********/ 106 107 /****f* Component Library: Event/cl_event_init 108 * NAME 109 * cl_event_init 110 * 111 * DESCRIPTION 112 * The cl_event_init function initializes an event for use. 113 * 114 * SYNOPSIS 115 */ 116 cl_status_t 117 cl_event_init(IN cl_event_t * const p_event, IN const boolean_t manual_reset); 118 /* 119 * PARAMETERS 120 * p_event 121 * [in] Pointer to an cl_event_t structure to initialize. 122 * 123 * manual_reset 124 * [in] If FALSE, indicates that the event resets itself after releasing 125 * a single waiter. If TRUE, the event remains in the signalled state 126 * until explicitly reset by a call to cl_event_reset. 127 * 128 * RETURN VALUES 129 * CL_SUCCESS if event initialization succeeded. 130 * 131 * CL_ERROR otherwise. 132 * 133 * NOTES 134 * Allows calling event manipulation functions, such as cl_event_signal, 135 * cl_event_reset, and cl_event_wait_on. 136 * 137 * The event is initially in a reset state. 138 * 139 * SEE ALSO 140 * Event, cl_event_construct, cl_event_destroy, cl_event_signal, 141 * cl_event_reset, cl_event_wait_on 142 *********/ 143 144 /****f* Component Library: Event/cl_event_destroy 145 * NAME 146 * cl_event_destroy 147 * 148 * DESCRIPTION 149 * The cl_event_destroy function performs any necessary cleanup of an event. 150 * 151 * SYNOPSIS 152 */ 153 void cl_event_destroy(IN cl_event_t * const p_event); 154 155 /* 156 * PARAMETERS 157 * p_event 158 * [in] Pointer to an cl_event_t structure to destroy. 159 * 160 * RETURN VALUE 161 * This function does not return a value. 162 * 163 * NOTES 164 * This function should only be called after a call to cl_event_construct 165 * or cl_event_init. 166 * 167 * SEE ALSO 168 * Event, cl_event_construct, cl_event_init 169 *********/ 170 171 /****f* Component Library: Event/cl_event_signal 172 * NAME 173 * cl_event_signal 174 * 175 * DESCRIPTION 176 * The cl_event_signal function sets an event to the signalled state and 177 * releases at most one waiting thread. 178 * 179 * SYNOPSIS 180 */ 181 cl_status_t cl_event_signal(IN cl_event_t * const p_event); 182 /* 183 * PARAMETERS 184 * p_event 185 * [in] Pointer to an cl_event_t structure to set. 186 * 187 * RETURN VALUES 188 * CL_SUCCESS if the event was successfully signalled. 189 * 190 * CL_ERROR otherwise. 191 * 192 * NOTES 193 * For auto-reset events, the event is reset automatically once a wait 194 * operation is satisfied. 195 * 196 * Triggering the event multiple times does not guarantee that the same 197 * number of wait operations are satisfied. This is because events are 198 * either in a signalled on non-signalled state, and triggering an event 199 * that is already in the signalled state has no effect. 200 * 201 * SEE ALSO 202 * Event, cl_event_reset, cl_event_wait_on 203 *********/ 204 205 /****f* Component Library: Event/cl_event_reset 206 * NAME 207 * cl_event_reset 208 * 209 * DESCRIPTION 210 * The cl_event_reset function sets an event to the non-signalled state. 211 * 212 * SYNOPSIS 213 */ 214 cl_status_t cl_event_reset(IN cl_event_t * const p_event); 215 /* 216 * PARAMETERS 217 * p_event 218 * [in] Pointer to an cl_event_t structure to reset. 219 * 220 * RETURN VALUES 221 * CL_SUCCESS if the event was successfully reset. 222 * 223 * CL_ERROR otherwise. 224 * 225 * SEE ALSO 226 * Event, cl_event_signal, cl_event_wait_on 227 *********/ 228 229 /****f* Component Library: Event/cl_event_wait_on 230 * NAME 231 * cl_event_wait_on 232 * 233 * DESCRIPTION 234 * The cl_event_wait_on function waits for the specified event to be 235 * triggered for a minimum amount of time. 236 * 237 * SYNOPSIS 238 */ 239 cl_status_t 240 cl_event_wait_on(IN cl_event_t * const p_event, 241 IN const uint32_t wait_us, IN const boolean_t interruptible); 242 /* 243 * PARAMETERS 244 * p_event 245 * [in] Pointer to an cl_event_t structure on which to wait. 246 * 247 * wait_us 248 * [in] Number of microseconds to wait. 249 * 250 * interruptible 251 * [in] Indicates whether the wait operation can be interrupted 252 * by external signals. 253 * 254 * RETURN VALUES 255 * CL_SUCCESS if the wait operation succeeded in response to the event 256 * being set. 257 * 258 * CL_TIMEOUT if the specified time period elapses. 259 * 260 * CL_NOT_DONE if the wait was interrupted by an external signal. 261 * 262 * CL_ERROR if the wait operation failed. 263 * 264 * NOTES 265 * If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the 266 * event is triggered and never timeout. 267 * 268 * If the timeout value is zero, this function simply tests the state of 269 * the event. 270 * 271 * If the event is already on the signalled state at the time of the call 272 * to cl_event_wait_on, the call completes immediately with CL_SUCCESS. 273 * 274 * SEE ALSO 275 * Event, cl_event_signal, cl_event_reset 276 *********/ 277 278 END_C_DECLS 279 #endif /* _CL_EVENT_H_ */ 280