1/*
2 *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
3 *
4 *  Licensed under the Apache License, Version 2.0 (the "License");
5 *  you may not use this file except in compliance with the License.
6 *  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *  Unless required by applicable law or agreed to in writing, software
11 *  distributed under the License is distributed on an "AS IS" BASIS,
12 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 *  See the License for the specific language governing permissions and
14 *  limitations under the License.
15 */
16
17/*
18 *  ======== sync.h ========
19 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
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
60extern "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