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 57BEGIN_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*/ 88void 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*/ 116cl_status_t 117cl_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*/ 153void 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*/ 181cl_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*/ 214cl_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*/ 239cl_status_t 240cl_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 278END_C_DECLS 279#endif /* _CL_EVENT_H_ */ 280