Scheduling events for future execution. See Event Scheduling for documentation.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.

/***************************************************************************/
#ifndef SILABS_EVENT_H
#define SILABS_EVENT_H

#ifdef EZSP_HOST
// Hosts do not support processor idling
  #define EMBER_NO_IDLE_SUPPORT
#endif

// Controlling events

// Possible event status values. Having zero as the 'inactive' value
// causes events to initially be inactive.
//

#define emberEventControlSetInactive(control) \
  do { (control).status = EMBER_EVENT_INACTIVE; } while (0)

#define emberEventControlGetActive(control) \
  ((control).status != EMBER_EVENT_INACTIVE)

#define emberEventControlSetActive(control) \
  do { emEventControlSetActive(&(control)); } while (0)

void emEventControlSetActive(EmberEventControl *event);

#define EMBER_MAX_EVENT_CONTROL_DELAY_MS (HALF_MAX_INT32U_VALUE - 1)

#define emberEventControlSetDelayMS(control, delay) \
  do { emEventControlSetDelayMS(&(control), (delay)); } while (0)

void emEventControlSetDelayMS(EmberEventControl*event, uint32_t delay);

#define EMBER_MAX_EVENT_CONTROL_DELAY_QS (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)

#define emberEventControlSetDelayQS(control, delay) \
  do { emEventControlSetDelayMS(&(control), (delay) << 8); } while (0)

#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)

#define emberEventControlSetDelayMinutes(control, delay) \
  do { emEventControlSetDelayMS(&(control), (delay) << 16); } while (0)

#define emberEventControlGetRemainingMS(control) \
  (emEventControlGetRemainingMS(&(control)))

uint32_t emEventControlGetRemainingMS(EmberEventControl *event);

// Running events

void emberRunEvents(EmberEventData *events);

void emberRunTask(EmberTaskId taskid);

uint32_t emberMsToNextEvent(EmberEventData *events, uint32_t maxMs);

uint32_t emberMsToNextEventExtended(EmberEventData *events, uint32_t maxMs, uint8_t* returnIndex);

uint32_t emberMsToNextStackEvent(void);

EmberTaskId emberTaskInit(EmberEventData *events);

bool emberMarkTaskIdle(EmberTaskId taskid);

#ifndef EMBER_NO_IDLE_SUPPORT

  #define emberTaskEnableIdling(allow) \
  do { emTaskEnableIdling((allow)); } while (0)

void emTaskEnableIdling(bool allow);

  #define emberMarkTaskActive(taskid) \
  do { emMarkTaskActive((taskid)); } while (0)

void emMarkTaskActive(EmberTaskId taskid);
#else
  #define emberTaskEnableIdling(allow)  do {} while (0)
  #define emberMarkTaskActive(taskid)   do {} while (0)
#endif // EMBER_NO_IDLE_SUPPORT

EmberEventControl* emGetCurrentlyRunningEventControl(void);

// @} END addtogroup

#endif // SILABS_EVENT_H

Macros#

#define

Sets this EmberEventControl as inactive (no pending event).

#define

Returns true if the event is active, false otherwise.

#define

Sets this EmberEventControl to run at the next available opportunity.

#define
EMBER_MAX_EVENT_CONTROL_DELAY_MS (HALF_MAX_INT32U_VALUE - 1)

The maximum delay that may be passed to emberEventControlSetDelayMS.

#define

Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.

#define
EMBER_MAX_EVENT_CONTROL_DELAY_QS (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)

The maximum delay that may be passed to emberEventControlSetDelayQS.

#define

Sets this EmberEventControl to run "delay" quarter seconds in the future. The 'quarter seconds' are actually 256 milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_QS.

#define
EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)

The maximum delay that may be passed to emberEventControlSetDelayMinutes.

#define

Sets this EmberEventControl to run "delay" minutes in the future. The 'minutes' are actually 65536 (0x10000) milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES.

#define

Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.

#define

Call this to indicate that an application supports processor idling.

#define

Indicates that a task has something to do, so the CPU should not be idled until emberMarkTaskIdle is next called on this task.

Functions#

void
emEventControlSetActive(EmberEventControl *event)

Sets this EmberEventControl to run at the next available opportunity.

void
emEventControlSetDelayMS(EmberEventControl *event, uint32_t delay)

Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.

uint32_t
emEventControlGetRemainingMS(EmberEventControl *event)

Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.

void
emberRunEvents(EmberEventData *events)

An application typically creates an array of events along with their handlers.

void
emberRunTask(EmberTaskId taskid)

If an application has initialized a task via emberTaskInit, it should call emberRunTask() instead of emberRunEvents() to run the events associated with that task.

uint32_t
emberMsToNextEvent(EmberEventData *events, uint32_t maxMs)

Returns the number of milliseconds before the next event is scheduled to expire, or maxMs if no event is scheduled to expire within that time. NOTE: If any events are modified within an interrupt, it must be called with interrupts disabled or from within an ATOMIC() block in order to guarantee the accuracy of this API.

uint32_t
emberMsToNextEventExtended(EmberEventData *events, uint32_t maxMs, uint8_t *returnIndex)

This function does the same as emberMsToNextEvent() with the following addition. If the returnIndex is non-NULL, it will set the value pointed to by the pointer to be equal to the index of the event that is ready to fire next. If no events are active, then it returns 0xFF.

uint32_t

Returns the number of milliseconds before the next stack event is scheduled to expire.

emberTaskInit(EmberEventData *events)

Initializes a task to be used for managing events and processor idling state. Returns the EmberTaskId, which represents the newly created task.

bool
emberMarkTaskIdle(EmberTaskId taskid)

Indicates that a task has nothing to do (unless any events are pending) and that it would be safe to idle the CPU if all other tasks also have nothing to do. This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning. Returns true if the processor was idled, false if idling was not permitted because some other task has something to do.

void
emTaskEnableIdling(bool allow)
void
emMarkTaskActive(EmberTaskId taskid)

Returns the event control pointer of the currently running event. NULL if no event is running.

Macro Definition Documentation#

emberEventControlSetInactive#

#define emberEventControlSetInactive
Value:
(control)

Sets this EmberEventControl as inactive (no pending event).


Definition at line 140 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlGetActive#

#define emberEventControlGetActive
Value:
(control)

Returns true if the event is active, false otherwise.


Definition at line 145 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlSetActive#

#define emberEventControlSetActive
Value:
(control)

Sets this EmberEventControl to run at the next available opportunity.


Definition at line 151 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

EMBER_MAX_EVENT_CONTROL_DELAY_MS#

#define EMBER_MAX_EVENT_CONTROL_DELAY_MS
Value:
(HALF_MAX_INT32U_VALUE - 1)

The maximum delay that may be passed to emberEventControlSetDelayMS.


Definition at line 162 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlSetDelayMS#

#define emberEventControlSetDelayMS
Value:
(control, delay)

Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.


Definition at line 168 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

EMBER_MAX_EVENT_CONTROL_DELAY_QS#

#define EMBER_MAX_EVENT_CONTROL_DELAY_QS
Value:
(EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)

The maximum delay that may be passed to emberEventControlSetDelayQS.


Definition at line 180 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlSetDelayQS#

#define emberEventControlSetDelayQS
Value:
(control, delay)

Sets this EmberEventControl to run "delay" quarter seconds in the future. The 'quarter seconds' are actually 256 milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_QS.


Definition at line 187 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES#

#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES
Value:
(EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)

The maximum delay that may be passed to emberEventControlSetDelayMinutes.


Definition at line 193 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlSetDelayMinutes#

#define emberEventControlSetDelayMinutes
Value:
(control, delay)

Sets this EmberEventControl to run "delay" minutes in the future. The 'minutes' are actually 65536 (0x10000) milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES.


Definition at line 200 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberEventControlGetRemainingMS#

#define emberEventControlGetRemainingMS
Value:
(control)

Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.


Definition at line 206 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberTaskEnableIdling#

#define emberTaskEnableIdling
Value:
(allow)

Call this to indicate that an application supports processor idling.


Definition at line 270 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberMarkTaskActive#

#define emberMarkTaskActive
Value:
(taskid)

Indicates that a task has something to do, so the CPU should not be idled until emberMarkTaskIdle is next called on this task.


Definition at line 278 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

Function Documentation#

emEventControlSetActive#

void emEventControlSetActive (EmberEventControl * event)

Sets this EmberEventControl to run at the next available opportunity.

Parameters
N/Aevent

Definition at line 157 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emEventControlSetDelayMS#

void emEventControlSetDelayMS (EmberEventControl * event, uint32_t delay)

Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.

Parameters
N/Aevent
N/Adelay

Definition at line 175 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emEventControlGetRemainingMS#

uint32_t emEventControlGetRemainingMS (EmberEventControl * event)

Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.

Parameters
N/Aevent

Definition at line 212 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberRunEvents#

void emberRunEvents (EmberEventData * events)

An application typically creates an array of events along with their handlers.

Parameters
N/Aevents

The main loop passes the array to emberRunEvents() in order to call the handlers of any events whose time has arrived.


Definition at line 222 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberRunTask#

void emberRunTask (EmberTaskId taskid)

If an application has initialized a task via emberTaskInit, it should call emberRunTask() instead of emberRunEvents() to run the events associated with that task.

Parameters
N/Ataskid

Definition at line 228 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberMsToNextEvent#

uint32_t emberMsToNextEvent (EmberEventData * events, uint32_t maxMs)

Returns the number of milliseconds before the next event is scheduled to expire, or maxMs if no event is scheduled to expire within that time. NOTE: If any events are modified within an interrupt, it must be called with interrupts disabled or from within an ATOMIC() block in order to guarantee the accuracy of this API.

Parameters
N/Aevents
N/AmaxMs

Definition at line 237 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberMsToNextEventExtended#

uint32_t emberMsToNextEventExtended (EmberEventData * events, uint32_t maxMs, uint8_t * returnIndex)

This function does the same as emberMsToNextEvent() with the following addition. If the returnIndex is non-NULL, it will set the value pointed to by the pointer to be equal to the index of the event that is ready to fire next. If no events are active, then it returns 0xFF.

Parameters
N/Aevents
N/AmaxMs
N/AreturnIndex

Definition at line 244 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberMsToNextStackEvent#

uint32_t emberMsToNextStackEvent (void )

Returns the number of milliseconds before the next stack event is scheduled to expire.

Parameters
N/A

Definition at line 249 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberTaskInit#

EmberTaskId emberTaskInit (EmberEventData * events)

Initializes a task to be used for managing events and processor idling state. Returns the EmberTaskId, which represents the newly created task.

Parameters
N/Aevents

Definition at line 255 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emberMarkTaskIdle#

bool emberMarkTaskIdle (EmberTaskId taskid)

Indicates that a task has nothing to do (unless any events are pending) and that it would be safe to idle the CPU if all other tasks also have nothing to do. This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning. Returns true if the processor was idled, false if idling was not permitted because some other task has something to do.

Parameters
N/Ataskid

Definition at line 265 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emTaskEnableIdling#

void emTaskEnableIdling (bool allow)
Parameters
N/Aallow

Definition at line 273 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emMarkTaskActive#

void emMarkTaskActive (EmberTaskId taskid)
Parameters
N/Ataskid

Definition at line 281 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h

emGetCurrentlyRunningEventControl#

EmberEventControl* emGetCurrentlyRunningEventControl (void )

Returns the event control pointer of the currently running event. NULL if no event is running.

Parameters
N/A

Definition at line 290 of file /mnt/raid/workspaces/ws.0wy4DfJrj/overlay/gsdk/util/silicon_labs/silabs_core/event_control/event.h