| /* |
| * Copyright 2001-2008 Texas Instruments - http://www.ti.com/ |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /* |
| * ======== sync.h ======== |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * Purpose: |
| * Provide synchronization services. |
| * |
| * Public Functions: |
| * SYNC_CloseEvent |
| * SYNC_DeleteCS |
| * SYNC_EnterCS |
| * SYNC_Exit |
| * SYNC_Init |
| * SYNC_InitializeCS |
| * SYNC_LeaveCS |
| * SYNC_OpenEvent |
| * SYNC_PostMessage |
| * SYNC_ResetEvent |
| * SYNC_SetEvent |
| * SYNC_WaitOnEvent |
| * SYNC_WaitOnMultipleEvents |
| * |
| *! Revision History: |
| *! ================ |
| *! 05-Oct-2000 jeh Added SYNC_WaitOnMultipleEvents(). |
| *! 01-Dec-1999 ag: Added #define SYNC_MAXNAMELENGTH. |
| *! 04-Nov-1999 kc: Added critical section functions and objects to SYNC. |
| *! 29-Oct-1999 kc: Cleaned up for code review. |
| *! 24-Sep-1999 kc: Added WinCE notes. |
| *! 20-Oct-1997 gp: Removed unused SYNC_ critical section and must complete fxns |
| *! Added SYNC_HOBJECT, SYNC_ATTRS, and object validation, and |
| *! merged SYNC_DestroyEvent into SYNC_CloseEvent, and merged |
| *! SYNC_CreateEvent into SYNC_OpenEvent. |
| *! 07-Oct-1997 gp: Added SYNC_Create/DestroyEvent (for NT testing). |
| *! 06-Oct-1997 gp: Added SYNC_OpenEvent. |
| *! 03-Jun-1997 gp: Added SYNC_{Begin|End}CritSection() functions. |
| *! 03-Jan-1997 gp: Added SYNC_INFINITE define. |
| *! 05-Aug-1996 gp: Created. |
| */ |
| |
| #ifndef _SYNC_H |
| #define _SYNC_H |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <dspapi.h> |
| |
| /* Special timeout value indicating an infinite wait: */ |
| #define SYNC_INFINITE 0xffffffff |
| |
| /* Maximum string length of a named event */ |
| #define SYNC_MAXNAMELENGTH 32 |
| |
| /* Generic SYNC object: */ |
| struct SYNC_OBJECT; |
| /*typedef struct SYNC_OBJECT *SYNC_HOBJECT;*/ |
| |
| /* Generic SYNC CS object: */ |
| struct SYNC_CSOBJECT; |
| /*typedef struct SYNC_CSOBJECT *SYNC_HCSOBJECT;*/ |
| |
| /* Used SYNC_CSOBJECT instead of SYNC_DPCCSOBJECT to avoid warnings */ |
| /*typedef struct SYNC_CSOBJECT *SYNC_HDPCCSOBJECT;*/ |
| |
| /* SYNC object attributes: */ |
| struct SYNC_ATTRS { |
| HANDLE hUserEvent; /* Platform's User Mode synch. object. */ |
| HANDLE hKernelEvent; /* Platform's Kernel Mode sync. object. */ |
| DWORD dwReserved1; /* For future expansion. */ |
| DWORD dwReserved2; /* For future expansion. */ |
| } ; |
| |
| /* |
| * ======== SYNC_CloseEvent ======== |
| * Purpose: |
| * Close this event handle, freeing resources allocated in SYNC_OpenEvent |
| * if necessary. |
| * Parameters: |
| * hEvent: Handle to a synchronization event, created/opened in |
| * SYNC_OpenEvent. |
| * Returns: |
| * DSP_SOK: Success; |
| * DSP_EFAIL: Failed to close event handle. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * SYNC initialized. |
| * Ensures: |
| * Any subsequent usage of hEvent would be invalid. |
| */ |
| extern DSP_STATUS SYNC_CloseEvent(IN struct SYNC_OBJECT* hEvent); |
| |
| /* |
| * ======== SYNC_DeleteCS ======== |
| * Purpose: |
| * Delete a critical section. |
| * Parameters: |
| * hCSObj: critical section handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_DeleteCS(IN struct SYNC_CSOBJECT* hCSObj); |
| |
| /* |
| * ======== SYNC_EnterCS ======== |
| * Purpose: |
| * Enter the critical section. |
| * Parameters: |
| * hCSObj: critical section handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_EnterCS(IN struct SYNC_CSOBJECT* hCSObj); |
| |
| /* |
| * ======== SYNC_Exit ======== |
| * Purpose: |
| * Discontinue usage of module; free resources when reference count |
| * reaches 0. |
| * Parameters: |
| * Returns: |
| * Requires: |
| * SYNC initialized. |
| * Ensures: |
| * Resources used by module are freed when cRef reaches zero. |
| */ |
| extern VOID SYNC_Exit(); |
| |
| /* |
| * ======== SYNC_Init ======== |
| * Purpose: |
| * Initializes private state of SYNC module. |
| * Parameters: |
| * Returns: |
| * TRUE if initialized; FALSE if error occured. |
| * Requires: |
| * Ensures: |
| * SYNC initialized. |
| */ |
| extern bool SYNC_Init(); |
| |
| /* |
| * ======== SYNC_InitializeCS ======== |
| * Purpose: |
| * Initialize the critical section. |
| * Parameters: |
| * hCSObj: critical section handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EMEMORY: Out of memory. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_InitializeCS(OUT struct SYNC_CSOBJECT* * phCSObj); |
| |
| /* |
| * ======== SYNC_InitializeDPCCS ======== |
| * Purpose: |
| * Initialize the critical section between process context and DPC. |
| * Parameters: |
| * hCSObj: critical section handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EMEMORY: Out of memory. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_InitializeDPCCS(OUT struct SYNC_CSOBJECT** phCSObj); |
| |
| /* |
| * ======== SYNC_LeaveCS ======== |
| * Purpose: |
| * Leave the critical section. |
| * Parameters: |
| * hCSObj: critical section handle. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_LeaveCS(IN struct SYNC_CSOBJECT* hCSObj); |
| |
| /* |
| * ======== SYNC_OpenEvent ======== |
| * Purpose: |
| * Create/open and initialize an event object for thread synchronization, |
| * which is initially in the non-signalled state. |
| * Parameters: |
| * phEvent: Pointer to location to receive the event object handle. |
| * pAttrs: Pointer to SYNC_ATTRS object containing initial SYNC |
| * SYNC_OBJECT attributes. If this pointer is NULL, then |
| * SYNC_OpenEvent will create and manage an OS specific |
| * syncronization object. |
| * pAttrs->hUserEvent: Platform's User Mode synchronization object. |
| * |
| * The behaviour of the SYNC methods depend on the value of |
| * the hUserEvent attr: |
| * |
| * 1. (hUserEvent == NULL): |
| * A user mode event is created. |
| * 2. (hUserEvent != NULL): |
| * A user mode event is supplied by the caller of SYNC_OpenEvent(). |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: Unable to create user mode event. |
| * DSP_EMEMORY: Insufficient memory. |
| * DSP_EINVALIDARG SYNC_ATTRS values are invalid. |
| * Requires: |
| * - SYNC initialized. |
| * - phEvent != NULL. |
| * Ensures: |
| * If function succeeded, pEvent->hEvent must be a valid event handle. |
| */ |
| extern DSP_STATUS SYNC_OpenEvent(OUT struct SYNC_OBJECT* * phEvent, |
| IN OPTIONAL struct SYNC_ATTRS * pAttrs); |
| |
| /* |
| * ========= SYNC_PostMessage ======== |
| * Purpose: |
| * To post a windows message |
| * Parameters: |
| * hWindow: Handle to the window |
| * uMsg: Message to be posted |
| * Returns: |
| * DSP_SOK: Success |
| * DSP_EFAIL: Post message failed |
| * DSP_EHANDLE: Invalid Window handle |
| * Requires: |
| * SYNC initialized |
| * Ensures |
| */ |
| extern DSP_STATUS SYNC_PostMessage(IN HANDLE hWindow, IN UINT uMsg); |
| |
| /* |
| * ======== SYNC_ResetEvent ======== |
| * Purpose: |
| * Reset a syncronization event object state to non-signalled. |
| * Parameters: |
| * hEvent: Handle to a sync event. |
| * Returns: |
| * DSP_SOK: Success; |
| * DSP_EFAIL: Failed to reset event. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * SYNC initialized. |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_ResetEvent(IN struct SYNC_OBJECT* hEvent); |
| |
| /* |
| * ======== SYNC_SetEvent ======== |
| * Purpose: |
| * Signal the event. Will unblock one waiting thread. |
| * Parameters: |
| * hEvent: Handle to an event object. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EFAIL: Failed to signal event. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * SYNC initialized. |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_SetEvent(IN struct SYNC_OBJECT* hEvent); |
| |
| /* |
| * ======== SYNC_WaitOnEvent ======== |
| * Purpose: |
| * Wait for an event to be signalled, up to the specified timeout. |
| * Parameters: |
| * hEvent: Handle to an event object. |
| * dwTimeOut: The time-out interval, in milliseconds. |
| * The function returns if the interval elapses, even if |
| * the object's state is nonsignaled. |
| * If zero, the function tests the object's state and |
| * returns immediately. |
| * If SYNC_INFINITE, the function's time-out interval |
| * never elapses. |
| * Returns: |
| * DSP_SOK: The object was signalled. |
| * DSP_EHANDLE: Invalid handle. |
| * SYNC_E_FAIL: Wait failed, possibly because the process terminated. |
| * SYNC_E_TIMEOUT: Timeout expired while waiting for event to be signalled. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_WaitOnEvent(IN struct SYNC_OBJECT* hEvent, |
| IN DWORD dwTimeOut); |
| |
| /* |
| * ======== SYNC_WaitOnMultipleEvents ======== |
| * Purpose: |
| * Wait for any of an array of events to be signalled, up to the |
| * specified timeout. |
| * Note: dwTimeOut must be SYNC_INFINITE to signal infinite wait. |
| * Parameters: |
| * hSyncEvents: Array of handles to event objects. |
| * uCount: Number of event handles. |
| * dwTimeOut: The time-out interval, in milliseconds. |
| * The function returns if the interval elapses, even if |
| * no event is signalled. |
| * If zero, the function tests the object's state and |
| * returns immediately. |
| * If SYNC_INFINITE, the function's time-out interval |
| * never elapses. |
| * puIndex: Location to store index of event that was signalled. |
| * Returns: |
| * DSP_SOK: The object was signalled. |
| * SYNC_E_FAIL: Wait failed, possibly because the process terminated. |
| * SYNC_E_TIMEOUT: Timeout expired before event was signalled. |
| * DSP_EMEMORY: Memory allocation failed. |
| * Requires: |
| * Ensures: |
| */ |
| extern DSP_STATUS SYNC_WaitOnMultipleEvents(IN struct SYNC_OBJECT** |
| hSyncEvents, IN UINT uCount, |
| IN DWORD dwTimeout, |
| OUT UINT * puIndex); |
| |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| #endif /* _SYNC_H */ |
