esp-idf/components/esp32/include/xtensa/xos_event.h

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