Event Flags

• Tasks can call all the functions.
• ISRs can only call Accept, Post, and Query.
• Managed as a group of flags.
• Event Flag Group
  • OSFlagType - for type checking by functions.
  • OSFlagWaitList - the list of waiting tasks.
  • OSFlagFlags - 8, 16, or 32 bits used as flags.
• Event Flag Group Node
  • Event flag group nodes are used to track the tasks waiting on the flags. Each node contains the bit pattern its task is waiting on and whether it is and AND or OR wait.
  • The node also points to the task’s TCB. The TCB has a pointer back to the flag node.

OSFlagCreate

OS_FLAG_GRP *OSFlagCreate(OS_FLAGS flags, INT8U *perr);

• Must be called from a task.
• Task a free event flag group form the free list if available. If not it returns 0.
• The number of flag events is set by OS_MAX_FLAGS in os_cfg.h
• Sets flags to initial value passed in. Typically 0.
• Returns pointer to the OS_FLAG_GRP, the event flag group.

OSFlagDel

OS_FLAG_GRP *OSFlagDel(OS_FLAG_GRP *pgrp, INT8U opt, INT8U *perr);

• Must be called from a task.
• Frees the Event Flag Group used by the flag.
• Requires an option
  • OS_DEL_NO_PEND - don’t delete if tasks are waiting on the flag.
  • OS_DEL_ALWAYS - always delete.
• If called with OS_DEL_ALWAYS, the queue will be deleted even if tasks are waiting on it.
  • All the waiting tasks will become ready.
  • Each task will think the condition occurred.
• Best practice is to first delete all tasks that use the flag group before deleting it.

OSFlagPend

OS_FLAGS OSFlagPend(OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U wait_type, INT16U timeout, INT8U *perr);

• Must be called form a task.
• Flags are the bit pattern the task is interested in.
• The wait types are:
  • OS_FLAG_WAIT_SET_ALL - wait for all bits specified to be set.
  • OS_FLAG_WAIT_SET_ANY - wait for any bits specified to be set.
  • OS_FLAG_WAIT_CLR_ALL - wait for all bits specified to be cleared.
  • OS_FLAG_WAIT_CLR_ANY - wait for any bits specified to be cleared.
• Wait type can be modified to specify if you want the flags changed on success, or “consumed”. That is if you wait for set then they can be cleared, or if you wait for clear then they can be set.
• To set the consume option add the OS_FLAG_CONSUME option to the wait type. Such as: FLAG_WAIT_SET_ALL + OS_FLAG_CONSUME
• Returns if flag matches the criteria
• If not it blocks. The task goes to the waiting list.

OSFlagAccept

OS_FLAGS OSFlagAccept(OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U wait_type, INT8U *perr);

• Can be called from a task or an ISR.
• Flags is the bit pattern of interest.
• The wait types are:
  • OS_FLAG_WAIT_SET_ALL - wait for all bits specified to be set.
  • OS_FLAG_WAIT_SET_ANY - wait for any bits specified to be set.
  • OS_FLAG_WAIT_CLR_ALL - wait for all bits specified to be cleared.
  • OS_FLAG_WAIT_CLR_ANY - wait for any bits specified to be cleared.
• Accept can consume the bits if the wait type includes the OS_FLAG_CONSUME option. The set bits will be cleared or cleared bits will be set depending on the type of wait.
• Does not block.
• Caller needs to check the error code to see if the call succeeded.

OSFlagPost

OS_FLAGS OSFlagPost(OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U opt, INT8U *perr);

• Can be called from a task or an ISR.
• Requires a flag pattern to be set or cleared.
• Requires an option.
  • OS_FLAG_SET - the bits in the pattern are set.
  • OS_FLAG_CLEAR - the bits in the pattern are cleared. flags &= ~flags
• Walks the list of waiting tasks and compares the new flag settings to the what the task is waiting for. Each task can be waiting for one of the following.
  • All bits specified in Pend are set
  • Any bits specified in Pend are set
  • All bits specified in Pend are clear
  • Any bits specified in Pend are clear
• If the criteria matches the task is moved to the ready list.
• If a task was made ready it calls the scheduler.

OSFlagQuery

OS_FLAGS OSFlagQuery(OS_FLAG_GRP *pgrp, INT8U *perr);

• Can be called from a task or an ISR.
• Returns the current value of the flags.

OSFlagPendGetFlagsRdy

OS_FLAGS OSFlagPendGetFlagsRdy(void);

• Called to get the flags that caused the task to become ready to run. In other words, this function allows you to tell “Who done it!”.

OSFlagNameSet

void OSFlagNameSet(OS_FLAG_GRP *pgrp, INT8U *pname, INT8U *perr);

• Assigns a name to an event flag group.

OSFlagNameGet

INT8U OSFlagNameGet(OS_FLAG_GRP *pgrp, INT8U *pname, INT8U *perr);

• Get the name assigned to an event flag group