1 /* 2 * dspbridge/mpu_api/inc/sync.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2007 Texas Instruments, Inc. 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation version 2.1 of the License. 11 * 12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, 13 * whether express or implied; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 */ 17 18 /* 19 * ======== sync.h ======== 20 * Purpose: 21 * Provide synchronization services. 22 * 23 * Public Functions: 24 * SYNC_CloseEvent 25 * SYNC_DeleteCS 26 * SYNC_EnterCS 27 * SYNC_Exit 28 * SYNC_Init 29 * SYNC_InitializeCS 30 * SYNC_LeaveCS 31 * SYNC_OpenEvent 32 * SYNC_PostMessage 33 * SYNC_ResetEvent 34 * SYNC_SetEvent 35 * SYNC_WaitOnEvent 36 * SYNC_WaitOnMultipleEvents 37 * 38 *! Revision History: 39 *! ================ 40 *! 05-Oct-2000 jeh Added SYNC_WaitOnMultipleEvents(). 41 *! 01-Dec-1999 ag: Added #define SYNC_MAXNAMELENGTH. 42 *! 04-Nov-1999 kc: Added critical section functions and objects to SYNC. 43 *! 29-Oct-1999 kc: Cleaned up for code review. 44 *! 24-Sep-1999 kc: Added WinCE notes. 45 *! 20-Oct-1997 gp: Removed unused SYNC_ critical section and must complete fxns 46 *! Added SYNC_HOBJECT, SYNC_ATTRS, and object validation, and 47 *! merged SYNC_DestroyEvent into SYNC_CloseEvent, and merged 48 *! SYNC_CreateEvent into SYNC_OpenEvent. 49 *! 07-Oct-1997 gp: Added SYNC_Create/DestroyEvent (for NT testing). 50 *! 06-Oct-1997 gp: Added SYNC_OpenEvent. 51 *! 03-Jun-1997 gp: Added SYNC_{Begin|End}CritSection() functions. 52 *! 03-Jan-1997 gp: Added SYNC_INFINITE define. 53 *! 05-Aug-1996 gp: Created. 54 */ 55 56 #ifndef _SYNC_H 57 #define _SYNC_H 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 #include <dspapi.h> 64 65 /* Special timeout value indicating an infinite wait: */ 66 #define SYNC_INFINITE 0xffffffff 67 68 /* Maximum string length of a named event */ 69 #define SYNC_MAXNAMELENGTH 32 70 71 /* Generic SYNC object: */ 72 struct SYNC_OBJECT; 73 /*typedef struct SYNC_OBJECT *SYNC_HOBJECT;*/ 74 75 /* Generic SYNC CS object: */ 76 struct SYNC_CSOBJECT; 77 /*typedef struct SYNC_CSOBJECT *SYNC_HCSOBJECT;*/ 78 79 /* Used SYNC_CSOBJECT instead of SYNC_DPCCSOBJECT to avoid warnings */ 80 /*typedef struct SYNC_CSOBJECT *SYNC_HDPCCSOBJECT;*/ 81 82 /* SYNC object attributes: */ 83 struct SYNC_ATTRS { 84 HANDLE hUserEvent; /* Platform's User Mode synch. object. */ 85 HANDLE hKernelEvent; /* Platform's Kernel Mode sync. object. */ 86 DWORD dwReserved1; /* For future expansion. */ 87 DWORD dwReserved2; /* For future expansion. */ 88 } ; 89 90 /* 91 * ======== SYNC_CloseEvent ======== 92 * Purpose: 93 * Close this event handle, freeing resources allocated in SYNC_OpenEvent 94 * if necessary. 95 * Parameters: 96 * hEvent: Handle to a synchronization event, created/opened in 97 * SYNC_OpenEvent. 98 * Returns: 99 * DSP_SOK: Success; 100 * DSP_EFAIL: Failed to close event handle. 101 * DSP_EHANDLE: Invalid handle. 102 * Requires: 103 * SYNC initialized. 104 * Ensures: 105 * Any subsequent usage of hEvent would be invalid. 106 */ 107 extern DSP_STATUS SYNC_CloseEvent(IN struct SYNC_OBJECT* hEvent); 108 109 /* 110 * ======== SYNC_DeleteCS ======== 111 * Purpose: 112 * Delete a critical section. 113 * Parameters: 114 * hCSObj: critical section handle. 115 * Returns: 116 * DSP_SOK: Success. 117 * DSP_EHANDLE: Invalid handle. 118 * Requires: 119 * Ensures: 120 */ 121 extern DSP_STATUS SYNC_DeleteCS(IN struct SYNC_CSOBJECT* hCSObj); 122 123 /* 124 * ======== SYNC_EnterCS ======== 125 * Purpose: 126 * Enter the critical section. 127 * Parameters: 128 * hCSObj: critical section handle. 129 * Returns: 130 * DSP_SOK: Success. 131 * DSP_EHANDLE: Invalid handle. 132 * Requires: 133 * Ensures: 134 */ 135 extern DSP_STATUS SYNC_EnterCS(IN struct SYNC_CSOBJECT* hCSObj); 136 137 /* 138 * ======== SYNC_Exit ======== 139 * Purpose: 140 * Discontinue usage of module; free resources when reference count 141 * reaches 0. 142 * Parameters: 143 * Returns: 144 * Requires: 145 * SYNC initialized. 146 * Ensures: 147 * Resources used by module are freed when cRef reaches zero. 148 */ 149 extern VOID SYNC_Exit(); 150 151 /* 152 * ======== SYNC_Init ======== 153 * Purpose: 154 * Initializes private state of SYNC module. 155 * Parameters: 156 * Returns: 157 * TRUE if initialized; FALSE if error occured. 158 * Requires: 159 * Ensures: 160 * SYNC initialized. 161 */ 162 extern bool SYNC_Init(); 163 164 /* 165 * ======== SYNC_InitializeCS ======== 166 * Purpose: 167 * Initialize the critical section. 168 * Parameters: 169 * hCSObj: critical section handle. 170 * Returns: 171 * DSP_SOK: Success. 172 * DSP_EMEMORY: Out of memory. 173 * Requires: 174 * Ensures: 175 */ 176 extern DSP_STATUS SYNC_InitializeCS(OUT struct SYNC_CSOBJECT* * phCSObj); 177 178 /* 179 * ======== SYNC_InitializeDPCCS ======== 180 * Purpose: 181 * Initialize the critical section between process context and DPC. 182 * Parameters: 183 * hCSObj: critical section handle. 184 * Returns: 185 * DSP_SOK: Success. 186 * DSP_EMEMORY: Out of memory. 187 * Requires: 188 * Ensures: 189 */ 190 extern DSP_STATUS SYNC_InitializeDPCCS(OUT struct SYNC_CSOBJECT** phCSObj); 191 192 /* 193 * ======== SYNC_LeaveCS ======== 194 * Purpose: 195 * Leave the critical section. 196 * Parameters: 197 * hCSObj: critical section handle. 198 * Returns: 199 * DSP_SOK: Success. 200 * DSP_EHANDLE: Invalid handle. 201 * Requires: 202 * Ensures: 203 */ 204 extern DSP_STATUS SYNC_LeaveCS(IN struct SYNC_CSOBJECT* hCSObj); 205 206 /* 207 * ======== SYNC_OpenEvent ======== 208 * Purpose: 209 * Create/open and initialize an event object for thread synchronization, 210 * which is initially in the non-signalled state. 211 * Parameters: 212 * phEvent: Pointer to location to receive the event object handle. 213 * pAttrs: Pointer to SYNC_ATTRS object containing initial SYNC 214 * SYNC_OBJECT attributes. If this pointer is NULL, then 215 * SYNC_OpenEvent will create and manage an OS specific 216 * syncronization object. 217 * pAttrs->hUserEvent: Platform's User Mode synchronization object. 218 * 219 * The behaviour of the SYNC methods depend on the value of 220 * the hUserEvent attr: 221 * 222 * 1. (hUserEvent == NULL): 223 * A user mode event is created. 224 * 2. (hUserEvent != NULL): 225 * A user mode event is supplied by the caller of SYNC_OpenEvent(). 226 * Returns: 227 * DSP_SOK: Success. 228 * DSP_EFAIL: Unable to create user mode event. 229 * DSP_EMEMORY: Insufficient memory. 230 * DSP_EINVALIDARG SYNC_ATTRS values are invalid. 231 * Requires: 232 * - SYNC initialized. 233 * - phEvent != NULL. 234 * Ensures: 235 * If function succeeded, pEvent->hEvent must be a valid event handle. 236 */ 237 extern DSP_STATUS SYNC_OpenEvent(OUT struct SYNC_OBJECT* * phEvent, 238 IN OPTIONAL struct SYNC_ATTRS * pAttrs); 239 240 /* 241 * ========= SYNC_PostMessage ======== 242 * Purpose: 243 * To post a windows message 244 * Parameters: 245 * hWindow: Handle to the window 246 * uMsg: Message to be posted 247 * Returns: 248 * DSP_SOK: Success 249 * DSP_EFAIL: Post message failed 250 * DSP_EHANDLE: Invalid Window handle 251 * Requires: 252 * SYNC initialized 253 * Ensures 254 */ 255 extern DSP_STATUS SYNC_PostMessage(IN HANDLE hWindow, IN UINT uMsg); 256 257 /* 258 * ======== SYNC_ResetEvent ======== 259 * Purpose: 260 * Reset a syncronization event object state to non-signalled. 261 * Parameters: 262 * hEvent: Handle to a sync event. 263 * Returns: 264 * DSP_SOK: Success; 265 * DSP_EFAIL: Failed to reset event. 266 * DSP_EHANDLE: Invalid handle. 267 * Requires: 268 * SYNC initialized. 269 * Ensures: 270 */ 271 extern DSP_STATUS SYNC_ResetEvent(IN struct SYNC_OBJECT* hEvent); 272 273 /* 274 * ======== SYNC_SetEvent ======== 275 * Purpose: 276 * Signal the event. Will unblock one waiting thread. 277 * Parameters: 278 * hEvent: Handle to an event object. 279 * Returns: 280 * DSP_SOK: Success. 281 * DSP_EFAIL: Failed to signal event. 282 * DSP_EHANDLE: Invalid handle. 283 * Requires: 284 * SYNC initialized. 285 * Ensures: 286 */ 287 extern DSP_STATUS SYNC_SetEvent(IN struct SYNC_OBJECT* hEvent); 288 289 /* 290 * ======== SYNC_WaitOnEvent ======== 291 * Purpose: 292 * Wait for an event to be signalled, up to the specified timeout. 293 * Parameters: 294 * hEvent: Handle to an event object. 295 * dwTimeOut: The time-out interval, in milliseconds. 296 * The function returns if the interval elapses, even if 297 * the object's state is nonsignaled. 298 * If zero, the function tests the object's state and 299 * returns immediately. 300 * If SYNC_INFINITE, the function's time-out interval 301 * never elapses. 302 * Returns: 303 * DSP_SOK: The object was signalled. 304 * DSP_EHANDLE: Invalid handle. 305 * SYNC_E_FAIL: Wait failed, possibly because the process terminated. 306 * SYNC_E_TIMEOUT: Timeout expired while waiting for event to be signalled. 307 * Requires: 308 * Ensures: 309 */ 310 extern DSP_STATUS SYNC_WaitOnEvent(IN struct SYNC_OBJECT* hEvent, 311 IN DWORD dwTimeOut); 312 313 /* 314 * ======== SYNC_WaitOnMultipleEvents ======== 315 * Purpose: 316 * Wait for any of an array of events to be signalled, up to the 317 * specified timeout. 318 * Note: dwTimeOut must be SYNC_INFINITE to signal infinite wait. 319 * Parameters: 320 * hSyncEvents: Array of handles to event objects. 321 * uCount: Number of event handles. 322 * dwTimeOut: The time-out interval, in milliseconds. 323 * The function returns if the interval elapses, even if 324 * no event is signalled. 325 * If zero, the function tests the object's state and 326 * returns immediately. 327 * If SYNC_INFINITE, the function's time-out interval 328 * never elapses. 329 * puIndex: Location to store index of event that was signalled. 330 * Returns: 331 * DSP_SOK: The object was signalled. 332 * SYNC_E_FAIL: Wait failed, possibly because the process terminated. 333 * SYNC_E_TIMEOUT: Timeout expired before event was signalled. 334 * DSP_EMEMORY: Memory allocation failed. 335 * Requires: 336 * Ensures: 337 */ 338 extern DSP_STATUS SYNC_WaitOnMultipleEvents(IN struct SYNC_OBJECT** 339 hSyncEvents, IN UINT uCount, 340 IN DWORD dwTimeout, 341 OUT UINT * puIndex); 342 343 344 #ifdef __cplusplus 345 } 346 #endif 347 #endif /* _SYNC_H */ 348