282 lines
10 KiB
C
282 lines
10 KiB
C
|
/** @file */
|
||
|
|
|
||
|
|
// xos_event.h - XOS Event API interface and data structures.
|
||
|
|
|
||
|
|
// Copyright (c) 2003-2015 Cadence Design Systems, Inc.
|
||
|
|
//
|
||
|
|
// Permission is hereby granted, free of charge, to any person obtaining
|
||
|
|
// a copy of this software and associated documentation files (the
|
||
|
|
// "Software"), to deal in the Software without restriction, including
|
||
|
|
// without limitation the rights to use, copy, modify, merge, publish,
|
||
|
|
// distribute, sublicense, and/or sell copies of the Software, and to
|
||
|
|
// permit persons to whom the Software is furnished to do so, subject to
|
||
|
|
// the following conditions:
|
||
|
|
//
|
||
|
|
// The above copyright notice and this permission notice shall be included
|
||
|
|
// in all copies or substantial portions of the Software.
|
||
|
|
//
|
||
|
|
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||
|
|
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
|
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||
|
|
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||
|
|
// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||
|
|
// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||
|
|
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||
|
|
|
||
|
|
// NOTE: Do not include this file directly in your application. Including
|
||
|
|
// xos.h will automatically include this file.
|
||
|
|
|
||
|
|
#ifndef __XOS_EVENT_H__
|
||
|
|
#define __XOS_EVENT_H__
|
||
|
|
|
||
|
|
#include "xos_types.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
// Defines.
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
#define XOS_EVENT_BITS_ALL 0xFFFFFFFF
|
||
|
|
#define XOS_EVENT_BITS_NONE 0
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
// Event flags.
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Event object.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
typedef struct XosEvent {
|
||
|
|
XosThreadQueue waitq; ///< Queue of waiters.
|
||
|
|
uint32_t bits; ///< Event bits
|
||
|
|
uint32_t mask; ///< Specifies which bits are valid
|
||
|
|
uint16_t flags; ///< Properties.
|
||
|
|
uint16_t pad; ///< Padding
|
||
|
|
#if XOS_EVENT_DEBUG
|
||
|
|
uint32_t sig; // Valid signature indicates inited.
|
||
|
|
#endif
|
||
|
|
} XosEvent;
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Initialize an event object before first use.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param mask Mask of active bits. Only these bits can be signaled.
|
||
|
|
///
|
||
|
|
/// \param flags Creation flags (currently ignored, should be zero).
|
||
|
|
///
|
||
|
|
/// \return Returns nothing.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
void
|
||
|
|
xos_event_create(XosEvent * event, uint32_t mask, uint32_t flags);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Destroy an event object. Must have been previously created by calling
|
||
|
|
/// xos_event_create().
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \return Returns nothing.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
void
|
||
|
|
xos_event_delete(XosEvent * event);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Set the specified bits in the specified event. Propagates the bit states
|
||
|
|
/// to all waiting threads and wakes them if needed.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to set. Bits not set in the mask
|
||
|
|
/// will not be modified by this call. To set all
|
||
|
|
/// the bits in the event, use the constant
|
||
|
|
/// XOS_EVENT_BITS_ALL.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_set(XosEvent * event, uint32_t bits);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Clear the specified bits in the specified event. Propagates the bit states
|
||
|
|
/// to all waiting threads and wakes them if needed.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to clear. Every bit that is set in
|
||
|
|
/// the mask will be cleared from the event. Bits
|
||
|
|
/// not set in the mask will not be modified by this
|
||
|
|
/// call. To clear all the bits in an event use the
|
||
|
|
/// constant XOS_EVENT_BITS_ALL.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_clear(XosEvent * event, uint32_t bits);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Clear and set the specified bits in the specified event. The two steps are
|
||
|
|
/// combined into one update, so this is faster than calling xos_event_clear()
|
||
|
|
/// and xos_event_set() separately. Only one update is sent out to waiting
|
||
|
|
/// threads.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param clr_bits Mask of bits to clear. The clear operation
|
||
|
|
/// happens before the set operation.
|
||
|
|
///
|
||
|
|
/// \param set_bits Mask of bits to set.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_clear_and_set(XosEvent * event, uint32_t clr_bits, uint32_t set_bits);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Get the current state of the event object. This is a snapshot of the state
|
||
|
|
/// of the event at this time.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param pstate Pointer to a uint32_t variable where the state
|
||
|
|
/// will be returned.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_get(XosEvent * event, uint32_t * pstate);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Wait until all the specified bits in the wait mask become set in the given
|
||
|
|
/// event object.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to test.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_wait_all(XosEvent * event, uint32_t bits);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Wait until all the specified bits in the wait mask become set in the given
|
||
|
|
/// event object, or the timeout expires.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to test.
|
||
|
|
///
|
||
|
|
/// \param to_cycles Timeout in cycles. Convert from time to cycles
|
||
|
|
/// using the helper functions provided in xos_timer.
|
||
|
|
/// A value of zero indicates no timeout.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, XOS_ERR_TIMEOUT on timeout, else
|
||
|
|
/// error code.
|
||
|
|
///
|
||
|
|
/// NOTE: If XOS_OPT_WAIT_TIMEOUT is not enabled, then the timeout value is
|
||
|
|
/// ignored, and no timeout will occur.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_wait_all_timeout(XosEvent * event, uint32_t bits, uint64_t to_cycles);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Wait until any of the specified bits in the wait mask become set in the
|
||
|
|
/// given event object.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to test.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_wait_any(XosEvent * event, uint32_t bits);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Wait until any of the specified bits in the wait mask become set in the
|
||
|
|
/// event object, or the timeout expires.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param bits Mask of bits to test.
|
||
|
|
///
|
||
|
|
/// \param to_cycles Timeout in cycles. Convert from time to cycles
|
||
|
|
/// using the helper functions provided in xos_timer.
|
||
|
|
/// A value of zero indicates no timeout.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, XOS_ERR_TIMEOUT on timeout, else
|
||
|
|
/// error code.
|
||
|
|
///
|
||
|
|
/// NOTE: If XOS_OPT_WAIT_TIMEOUT is not enabled, then the timeout value is
|
||
|
|
/// ignored, and no timeout will occur.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_wait_any_timeout(XosEvent * event, uint32_t bits, uint64_t to_cycles);
|
||
|
|
|
||
|
|
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
///
|
||
|
|
/// Atomically set a specified group of bits, then wait for another specified
|
||
|
|
/// group of bits to become set.
|
||
|
|
///
|
||
|
|
/// \param event Pointer to event object.
|
||
|
|
///
|
||
|
|
/// \param set_bits Group of bits to set.
|
||
|
|
///
|
||
|
|
/// \param wait_bits Group of bits to wait on. All the bits in the
|
||
|
|
/// group will have to get set before the wait is
|
||
|
|
/// satisfied.
|
||
|
|
///
|
||
|
|
/// \return Returns XOS_OK on success, else error code.
|
||
|
|
///
|
||
|
|
//-----------------------------------------------------------------------------
|
||
|
|
int32_t
|
||
|
|
xos_event_set_and_wait(XosEvent * event, uint32_t set_bits, uint32_t wait_bits);
|
||
|
|
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif // __XOS_EVENT_H__
|
||
|
|
|