/** @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__