/****************************************************************************
*
* Copyright (c) 2017, Danilo Pucci Smokovitz (dnlps@hotmail.com)
*
* This file is part of the FreeRTOS Add-ons project.
*
* Source Code:
* https://github.com/michaelbecker/freertos-addons
*
* Project Page:
* http://michaelbecker.github.io/freertos-addons/
*
* On-line Documentation:
* http://michaelbecker.github.io/freertos-addons/docs/html/index.html
*
* 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.
* + Credit is appreciated, but not required, if you find this project
* useful enough to include in your application, product, device, etc.
*
* 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.
*
***************************************************************************/
#ifndef EVENT_GROUPS_HPP_
#define EVENT_GROUPS_HPP_
/**
* C++ exceptions are used by default when constructors fail.
* If you do not want this behavior, define the following in your makefile
* or project. Note that in most / all cases when a constructor fails,
* it's a fatal error. In the cases when you've defined this, the new
* default behavior will be to issue a configASSERT() instead.
*/
#ifndef CPP_FREERTOS_NO_EXCEPTIONS
#include <exception>
#include <string>
#include <cstdio>
#ifdef CPP_FREERTOS_NO_CPP_STRINGS
#error "FreeRTOS-Addons require C++ Strings if you are using exceptions"
#endif
#endif
#include "FreeRTOS.h"
#include "event_groups.h"
namespace cpp_freertos {
#ifndef CPP_FREERTOS_NO_EXCEPTIONS
/**
* This is the exception that is thrown if an EventGroup constructor fails.
*/
class EventGroupCreateException : public std::exception {
public:
/**
* Create the exception.
*/
EventGroupCreateException()
{
sprintf(errorString, "Event Group Constructor Failed");
}
/**
* Create the exception.
*/
explicit EventGroupCreateException(const char *info)
{
snprintf(errorString, sizeof(errorString),
"Event Group Constructor Failed %s", info);
}
/**
* Get what happened as a string.
* We are overriding the base implementation here.
*/
virtual const char *what() const throw()
{
return errorString;
}
private:
/**
* A text string representing what failed.
*/
char errorString[80];
};
#endif
/**
* @todo - document this class
*/
class EventGroup {
/////////////////////////////////////////////////////////////////////////
//
// Public API
//
/////////////////////////////////////////////////////////////////////////
public:
/**
* Construct a Event Group
*/
EventGroup();
#if( configSUPPORT_STATIC_ALLOCATION == 1 )
/**
* Construct a Event Group with static allocation
*/
EventGroup(StaticEventGroup_t *pxEventGroupBuffer);
#endif
/**
* Allow two or more tasks to use an event group to sync each other.
*
* @param uxBitsToSet A bit mask that specifies the event bit, or
* event bits, to set 1 in the event group. The value of the event
* groups is updated by bitwise ORing the event group's existing
* value with the passed in uxBitsToSet.
*
* @param uxBitsToWaitFor The bit or bits to set in the event
* group before determining if (and possibly waiting for), all the
* bits specified by the uxBitsToWait parameter are set.
*
* @param xTicksToWait The maximum amount of time (specified in
* 'ticks') to wait for all the bits specified by the
* uxBitsToWaitFor parameter value to become set.
*
* @return If EventGroup::Sync returned because all the bits it
* was waiting for were set then the returned value is the event
* group value before any bits were automatically cleared.
* If EventGroup::Sync returned because its timeout expired then
* not all the bits being waited for will be set.
*/
EventBits_t Sync( const EventBits_t uxBitsToSet,
const EventBits_t uxBitsToWaitFor,
TickType_t xTicksToWait);
/**
* Read bits within an RTOS event group, optionally entering the
* Blocked state (with a timeout) to wait for a bit or group of
* bits to become set.
*
* @param uxBitsToWaitFor A bitwise value that indicates the bit
* or bits to test inside the event group.
*
* @param xClearOnExit If xClearOnExit is set to true then any bits
* set in the value passed as the uxBitsToWaitFor parameter will be
* cleared in the event group before EventGroup::WaitBits returns
* if EventGroup::WaitBits returns for any reason other than a
* timeout. The timeout value is set by the xTicksToWait parameter.
* If xClearOnExit is set to false then the bits set in the event
* group are not altered when the call to EventGroup::WaitBits
* returns.
*
* @param xWaitForAllBits is used to create either a logical AND
* test (where all bits must be set) or a logical OR test (where
* one or more bits must be set) as follows:
*
* @par If xWaitForAllBits is set to true then
* EventGroup::WaitBits will return when either all the
* bits set in the value passed as the uxBitsToWaitFor
* parameter are set in the event group or the specified
* block time expires.
*
* @par If xWaitForAllBits is set to false then
* EventGroup::WaitBits will return when any of the bits
* set in the value passed as the uxBitsToWaitFor
* parameter are set in the event group or the specified
* block time expires.
*
* @param xTicksToWait The maximum amount of time (specified in
* 'ticks') to wait for one/all (depending on the xWaitForAllBits
* value) of the bits specified by uxBitsToWaitFor to become set.
*
* @return The value of the event group at the time either the event
* bits being waited for became set, or the block time expired. The
* current value of the event bits in an event group will be
* different to the returned value if a higher priority task or
* interrupt changed the value of an event bit between the calling
* task leaving the Blocked state and exiting the
* EventGroup::WaitBits function. Test the return value to know
* which bits were set. If EventGroup::WaitBits returned because its
* timeout expired then not all the bits being waited for will be
* set. If EventGroup::WaitBits returned because the bits it was
* waiting for were set then the returned value is the event group
* value before any bits were automatically cleared because the
* xClearOnExit parameter was set to true.
*/
EventBits_t WaitBits( const EventBits_t uxBitsToWaitFor,
bool xClearOnExit,
bool xWaitForAllBits,
TickType_t xTicksToWait);
/**
* Clear bits (flags) within an event group.
*
* @param uxBitsToClear A bitwise value that indicates the bit or
* bits to clear in the event group.
*
* @return The value of the event group before the specified bits
* were cleared.
*/
EventBits_t ClearBits(const EventBits_t uxBitsToClear);
/**
* Clear bits (flags) within an event group from ISR context.
*
* @param uxBitsToClear A bitwise value that indicates the bit or
* bits to clear in the event group.
*
* @return The value of the event group before the specified bits
* were cleared.
*/
BaseType_t ClearBitsFromISR(const EventBits_t uxBitsToClear);
/**
* Returns the current value of the event bits (event flags) in an
* event group.
*
* @return The value of the event bits in the event group at the time
* EventGroup::GetBitsFromISR was called.
*/
EventBits_t GetBits();
/**
* Returns the current value of the event bits (event flags) in an
* event group from ISR context.
*
* @return The value of the event bits in the event group at the
* time EventGroup::GetBitsFromISR was called.
*/
EventBits_t GetBitsFromISR();
/**
* Set bits (flags) within an event group.
*
* @param uxBitsToSet A bitwise value that indicates the bit or bits
* to set in the event group.
*
* @return The value of the event group at the time the call to
* EventGroup::SetBits returns
*/
EventBits_t SetBits(const EventBits_t uxBitsToSet);
#if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) )
/**
* Set bits (flags) within an event group from ISR context.
*
* @param uxBitsToSet A bitwise value that indicates the bit or bits
* to set in the event group.
*
* @param pxHigherPriorityTaskWoken A bitwise value that indicates
* the bit or bits to set in the event group.
*
* @return Calling this function will result in a message being sent
* to the RTOS daemon task. If the priority of the daemon task is
* higher than the priority of the currently running task (the
* task the interrupt interrupted) then *pxHigherPriorityTaskWoken
* will be set to true by EventGroupSetBitsFromISR, indicating that
* a context switch should be requested before the interrupt exits.
* For that reason *pxHigherPriorityTaskWoken must be initialised
* to false.
*/
BaseType_t SetBitsFromISR( const EventBits_t uxBitsToSet,
BaseType_t *pxHigherPriorityTaskWoken);
#endif
/**
* Our destructor
*/
virtual ~EventGroup();
/////////////////////////////////////////////////////////////////////////
//
// Protected API
// Not intended for use by application code.
//
/////////////////////////////////////////////////////////////////////////
protected:
/**
* FreeRTOS Event Group handle.
*/
EventGroupHandle_t handle;
};
}
#endif