Page Comparison

Image Added

typedef struct {
    INT8U     OSFlagType;      (1)
    void     *OSFlagWaitList;  (2)
    OS_FLAGS  OSFlagFlags;     (3)
} OS_FLAG_GRP;

(1) OSFlagType is a variable which is used to make sure that you are pointing to an event flag group. This field is the first field of the structure because it allows µC/OS-II services to ‘validate’ the type of structure being pointed to. For example, if you were to pass a pointer to an event flag group to OSSemPend(), µC/OS-II would return an error code indicating that you are not passing the proper ‘object’ to the semaphore pend call. You should note that an ECB (Event Control Block) also has its first byte containing the type of OS object (i.e. semaphore, mutex, message mailbox or message queue).

(2) OSFlagWaitList contains a list of tasks waiting for events.

(3) OSFlagFlags is a series of flags (i.e. bits) that holds the current status of events. The number of bits used is decided at compile time and can either be 8, 16 or 32 depending on the data type you assign to OS_FLAGS in OS_CFG.H.

Image Added

typedef struct {
    void     *OSFlagNodeNext;             (1)
    void     *OSFlagNodePrev;    
    void     *OSFlagNodeTCB;              (2)
    void     *OSFlagNodeFlagGrp;          (3)
    OS_FLAGS  OSFlagNodeFlags;            (4)
    INT8U     OSFlagNodeWaitType;         (5)
} OS_FLAG_NODE;

(1) The OSFlagNodeNext and OSFlagNodePrev are used to maintain a doubly linked list of OS_FLAG_NODEs. The doubly linked list allows us to easily insert and especially remove nodes from the wait list.

(2) OSFlagNodeTCB is used to point to the TCB of the task waiting on flags belonging to the event flag group. In other words, this pointer allows us to know which tasks is waiting for the specified flags.

(3) OSFlagNodeFlagGrp allows a link back to the event flag group. This pointer is used when removing the node from the doubly linked list and is needed by OSTaskDel() when the pended task needs to be deleted.

(4) The OSFlagNodeFlags contains the bit-pattern of the flags that the task is waiting for. For example, your task might have performed an OSFlagPend() and specified that the task wants to wait for bits 0, 4, 6 and 7 (bit 0 is the rightmost bit). In this case, OSFlagNodeFlags would contain 0xD1. Depending on the size of the data type OS_FLAGS, OSFlagNodeFlags is either 8, 16 or 32 bits. OS_FLAGS is specified in your application configuration file (i.e., OS_CFG.H). Because µC/OS-II and the ports are provided in source form, you can easily change the number of bits in an event flag group to satisfy your requirements for a specific application or product. The reason you would limit the number of bits to 8 is to reduce both RAM and ROM for your application. However, for maximum portability of your applications, you should set OS_FLAGS to an INT32U data type.

(5) The last member of the OS_FLAG_NODE data structure is OSFlagNodeWaitType which determines whether the task is waiting for ALL (AND wait) the bits in the event flag group that matches OSFlagNodeFlags or, ANY (OR wait) of the bits in the event flag group that matches OSFlagNodeFlags. OSFlagNodeWaitType can be set to:

OS_FLAG_WAIT_CLR_ALL      
OS_FLAG_WAIT_CLR_AND      
OS_FLAG_WAIT_CLR_ANY      
OS_FLAG_WAIT_CLR_OR 
OS_FLAG_WAIT_SET_ALL 
OS_FLAG_WAIT_SET_AND      
OS_FLAG_WAIT_SET_ANY      
OS_FLAG_WAIT_SET_OR

OS_FLAG_GRP  *OSFlagCreate (OS_FLAGS flags, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                         
    OS_CPU_SR    cpu_sr;
#endif    
    OS_FLAG_GRP *pgrp;


    if (OSIntNesting > 0) {                         (1)
        *err = OS_ERR_CREATE_ISR;                   
        return ((OS_FLAG_GRP *)0);               
    }
    OS_ENTER_CRITICAL();
    pgrp = OSFlagFreeList;                          (2)
    if (pgrp != (OS_FLAG_GRP *)0) {                 (3)
                                                    (4)
        OSFlagFreeList       = (OS_FLAG_GRP *)OSFlagFreeList->OSFlagWaitList;
        pgrp->OSFlagType     = OS_EVENT_TYPE_FLAG;  (5)
        pgrp->OSFlagFlags    = flags;               (6)
        pgrp->OSFlagWaitList = (void *)0;           (7)
        OS_EXIT_CRITICAL();
        *err                 = OS_NO_ERR;
    } else {
        OS_EXIT_CRITICAL();
        *err                 = OS_FLAG_GRP_DEPLETED;
    }
    return (pgrp);                                  (8)
}

(1) OSFlagCreate() starts by making sure it’s not called from an ISR because that’s not allowed.

(2) OSFlagCreate() then attempts to get a free Event Flag Group (i.e., an OS_FLAG_GRP) from the free list.

(3) An non-NULL pointer indicates that an event flag group is available.

(4) Once a group is allocated, the free list pointer is adjusted. Note that the number of Event Flag Groups that you can create is determined by the #define constant OS_MAX_FLAGS which is defined in OS_CFG.H in your application.

(5) OSFlagCreate() then fills in the fields in the event flag group. OS_EVENT_TYPE_FLAG indicates that this control block is an event flag group. Because this is the first field in the data structure, it’s at offset zero. In µC/OS-II, the first byte of an event flag group or an event control block used for semaphores, mailboxes, queues and mutexes indicates the type of kernel object. This allows us to check that we are pointing to the proper object.

(6) OSFlagCreate() then stores the initial value of the event flags into the event flag group. Typically, you would initialize the flags to all 0s but, if you are checking for CLEARED bits then, you could initialize the flags to all 1s.

(7) Because we are creating the group, there are no tasks waiting on the group and thus, the wait list pointer is initialized to NULL.

(8) The pointer to the created event flag group is returned. If there were no more groups available, OSFlagCreate() would return a NULL pointer.

OS_FLAG_GRP  *OSFlagDel (OS_FLAG_GRP *pgrp, INT8U opt, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                                
    OS_CPU_SR     cpu_sr;
#endif    
    BOOLEAN       tasks_waiting;
    OS_FLAG_NODE *pnode;


    if (OSIntNesting > 0) {                                 (1)
        *err = OS_ERR_DEL_ISR;                             
        return (pgrp);
    }
#if OS_ARG_CHK_EN > 0
    if (pgrp == (OS_FLAG_GRP *)0) {                         (2)
        *err = OS_FLAG_INVALID_PGRP;
        return (pgrp);
    }
    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG) {           (3)
        *err = OS_ERR_EVENT_TYPE;
        return (pgrp);
    }
#endif
    OS_ENTER_CRITICAL();
    if (pgrp->OSFlagWaitList != (void *)0) {                (4)
        tasks_waiting = TRUE;                              
    } else {
        tasks_waiting = FALSE;                             
    }
    switch (opt) {
        case OS_DEL_NO_PEND:                                (5)
             if (tasks_waiting == FALSE) {
                 pgrp->OSFlagType     = OS_EVENT_TYPE_UNUSED;
                 pgrp->OSFlagWaitList = (void *)OSFlagFreeList;   (6)
                 OSFlagFreeList       = pgrp;
                 OS_EXIT_CRITICAL();
                 *err                 = OS_NO_ERR;
                 return ((OS_FLAG_GRP *)0);                 (7) 
             } else {
                 OS_EXIT_CRITICAL();
                 *err                 = OS_ERR_TASK_WAITING;
                 return (pgrp);
             }

        case OS_DEL_ALWAYS:                                 (8) 
             pnode = pgrp->OSFlagWaitList;
             while (pnode != (OS_FLAG_NODE *)0) {           (9) 
                 OS_FlagTaskRdy(pnode, (OS_FLAGS)0);
                 pnode = pnode->OSFlagNodeNext;
             }
             pgrp->OSFlagType     = OS_EVENT_TYPE_UNUSED;
             pgrp->OSFlagWaitList = (void *)OSFlagFreeList; (10)
             OSFlagFreeList       = pgrp;
             OS_EXIT_CRITICAL();
             if (tasks_waiting == TRUE) {                   (11)
                 OS_Sched();                               
             }
             *err = OS_NO_ERR;
             return ((OS_FLAG_GRP *)0);                     (12)

        default:
             OS_EXIT_CRITICAL();
             *err = OS_ERR_INVALID_OPT;
             return (pgrp);
    }
}

(1) OSFlagDel() starts by making sure that this function is not called from an ISR because that’s not allowed.

(2) & (3) We then validate the arguments passed to OSFlagDel() . First, we make sure that pgrp is not a NULL pointer and pgrp points to point to an event flag group. Note that this code is conditionally compiled and thus, if OS_ARG_CHK_EN is set to 0 then this code is NOT compiled. This is done to allow you to reduce the amount of code space needed by this module.

(4) OSFlagDel() then determines whether there are any tasks waiting on the event flag group and sets the local BOOLEAN variable tasks_waiting accordingly.

Based on the option (i.e. opt) passed in the call, OSFlagDel() will either delete the event flag group only if no tasks are pending on the event flag group (opt == OS_DEL_NO_PEND) or, delete the event flag group even if tasks are waiting (opt == OS_DEL_ALWAYS).

(5) & (6) When opt is set to OS_DEL_NO_PEND and there is no task waiting on the event flag group, OSFlagDel() marks the group as unused and the event flag group is returned to the free list of groups. This will allow another event flag group to be created by reusing this event flag group.

(7) You will note that OSFlagDel() returns a NULL pointer since, at this point, the event flag group should no longer be accessed through the original pointer.

(8) & (9) When opt is set to OS_DEL_ALWAYS then all tasks waiting on the event flag group will be readied. Each task will think the event(s) that the task was waiting for occurred. We will discuss OS_FlagTaskRdy() when we look at the code for OSFlagPost() .

(10) Once all pending tasks are readied, OSFlagDel() marks the event flag group as unused and the group is returned to the free list of groups.

(11) The scheduler is called only if there were tasks waiting on the event flag group.

(12) You will note that OSFlagDel() returns a NULL pointer since, at this point, the event flag group should no longer be accessed through the original pointer.

OS_FLAGS  OSFlagPend (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U wait_type, INT16U timeout, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                                
    OS_CPU_SR     cpu_sr;
#endif    
    OS_FLAG_NODE  node;
    OS_FLAGS      flags_cur;
    OS_FLAGS      flags_rdy;
    BOOLEAN       consume;
 
 
    if (OSIntNesting > 0) {                                (1)
        *err = OS_ERR_PEND_ISR;                            
        return ((OS_FLAGS)0);
    }
#if OS_ARG_CHK_EN > 0
    if (pgrp == (OS_FLAG_GRP *)0) {                        (2)
        *err = OS_FLAG_INVALID_PGRP;
        return ((OS_FLAGS)0);
    }
    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG) {          (3)
        *err = OS_ERR_EVENT_TYPE;
        return ((OS_FLAGS)0);
    }
#endif
    if (wait_type & OS_FLAG_CONSUME) {                     (4)
        wait_type &= ~OS_FLAG_CONSUME;
        consume    = TRUE;
    } else {
        consume    = FALSE;
    }
    OS_ENTER_CRITICAL();
    switch (wait_type) {                                   (5)
        case OS_FLAG_WAIT_SET_ALL:                         
             flags_rdy = pgrp->OSFlagFlags & flags;        (6)
             if (flags_rdy == flags) {                     (7)
                 if (consume == TRUE) {                    (8)
                     pgrp->OSFlagFlags &= ~flags_rdy;      (9)
                 }
                 flags_cur = pgrp->OSFlagFlags;            (10)
                 OS_EXIT_CRITICAL();                       
                 *err      = OS_NO_ERR;
                 return (flags_cur);                       (11)
             } else {                                      (12)
                 OS_FlagBlock(pgrp, &node, flags, wait_type, timeout); 
                 OS_EXIT_CRITICAL();
             }
             break;
 
        case OS_FLAG_WAIT_SET_ANY:
             flags_rdy = pgrp->OSFlagFlags & flags;        (13) 
             if (flags_rdy != (OS_FLAGS)0) {               (14) 
                 if (consume == TRUE) {                    (15) 
                     pgrp->OSFlagFlags &= ~flags_rdy;      (16) 
                 }
                 flags_cur = pgrp->OSFlagFlags;            (17) 
                 OS_EXIT_CRITICAL();                       
                 *err      = OS_NO_ERR;
                 return (flags_cur);                       (18) 
             } else {                                      (19) 
                 OS_FlagBlock(pgrp, &node, flags, wait_type, timeout); 
                 OS_EXIT_CRITICAL();
             }
             break;
 
#if OS_FLAG_WAIT_CLR_EN > 0
        case OS_FLAG_WAIT_CLR_ALL:                         
             flags_rdy = ~pgrp->OSFlagFlags & flags;       
             if (flags_rdy == flags) {                     
                 if (consume == TRUE) {                    
                     pgrp->OSFlagFlags |= flags_rdy;       
                 }
                 flags_cur = pgrp->OSFlagFlags;            
                 OS_EXIT_CRITICAL();                       
                 *err      = OS_NO_ERR;
                 return (flags_cur);
             } else {                                      
                 OS_FlagBlock(pgrp, &node, flags, wait_type, timeout); 
                 OS_EXIT_CRITICAL();
             }
             break;
 
        case OS_FLAG_WAIT_CLR_ANY:
             flags_rdy = ~pgrp->OSFlagFlags & flags;       
             if (flags_rdy != (OS_FLAGS)0) {               
                 if (consume == TRUE) {                    
                     pgrp->OSFlagFlags |= flags_rdy;       
                 }
                 flags_cur = pgrp->OSFlagFlags;            
                 OS_EXIT_CRITICAL();                       
                 *err      = OS_NO_ERR;
                 return (flags_cur);
             } else {                                      
                 OS_FlagBlock(pgrp, &node, flags, wait_type, timeout); 
                 OS_EXIT_CRITICAL();
             }
             break;
#endif
 
        default:
             OS_EXIT_CRITICAL();
             flags_cur = (OS_FLAGS)0;
             *err      = OS_FLAG_ERR_WAIT_TYPE;
             return (flags_cur);
    }
    OS_Sched();                                            (20)
    OS_ENTER_CRITICAL();
    if (OSTCBCur->OSTCBStat & OS_STAT_FLAG) {              (21)
        OS_FlagUnlink(&node);                              (22)
        OSTCBCur->OSTCBStat = OS_STAT_RDY;                 
        OS_EXIT_CRITICAL();
        flags_cur           = (OS_FLAGS)0;
        *err                = OS_TIMEOUT;                  
    } else {
        if (consume == TRUE) {                             (23)
            switch (wait_type) {
                case OS_FLAG_WAIT_SET_ALL:
                case OS_FLAG_WAIT_SET_ANY:                 (24)
                     pgrp->OSFlagFlags &= ~OSTCBCur->OSTCBFlagsRdy;
                     break;
                     
                case OS_FLAG_WAIT_CLR_ALL:
                case OS_FLAG_WAIT_CLR_ANY:                 
                     pgrp->OSFlagFlags |= OSTCBCur->OSTCBFlagsRdy;
                     break;
            }
        }
        flags_cur = pgrp->OSFlagFlags;                     (25)
        OS_EXIT_CRITICAL();
        *err      = OS_NO_ERR;                             
    }
    return (flags_cur);
}

(1) Like all µC/OS-II pend calls, OSFlagPend() cannot be called from an ISR and thus, OSFlagPend() checks for this condition first.

(2) & (3) Assuming that the configuration constant OS_ARG_CHK_EN is set to 1, OSFlagPend() makes sure that the ‘handle’ pgrp is not a NULL pointer and that pgrp points to an event flag group that should have been created by OSFlagCreate() .

OSFlagPend() allows you to specify whether you will SET or CLEAR flags once they satisfy the condition you are waiting for. This is accomplished by ADDing (or ORing) OS_FLAG_CONSUME to the wait_type argument during the call to OSFlagPend(). For example, if you want to wait for BIT0 to be SET in the event flag group and if BIT0 is in fact SET, it will be CLEARED by OSFlagPend() if you ADD OS_FLAG_CONSUME to the type of wait desired as shown below:

OSFlagPend(OSFlagMyGrp, 
	(OS_FLAGS)0x01, 
	FLAG_WAIT_SET_ANY + OS_FLAG_CONSUME,
	0,
	&err);

(4) Because the ‘consumption’ of the flag(s) is done later in the code, OSFlagPend() saves the ‘consume’ option in the BOOLEAN variable called consume.

(5) OSFlagPend() then executes code based on the wait type specified in the function called. There are four choices:

1. wait for ALL bits specified to be SET in the event flag group
2. wait for ANY bit specified to be SET in the event flag group
3. wait for ALL bits specified to be CLEARED in the event flag group
4. wait for ANY bit specified to be CLEARED in the event flag group

The last two choices are identical to the first two choices except that OSFlagPend() ‘looks’ for the bits specified to be CLEARED (i.e. 0) instead for them being SET (i.e. 1). For this reason, I will only discuss the first two choices. In fact, in order to conserve ROM, you may not need to look for bits to be cleared and thus, you can ‘compile-out’ all the corresponding code out by setting OS_FLAG_WAIT_CLR_EN to 0 in OS_CFG.H.

Wait for ALL of the specified bits to be SET:

(6) When wait_type is set to either OS_FLAG_WAIT_SET_ALL or OS_FLAG_WAIT_SET_AND, OSFlagPend() will ‘extract’ the desired bits in the event flag group which are specified in the flags argument.

(7) If all the bits extracted matches the bits that you specified in the flags argument then, the event flags that the task wants are all set and thus, the PEND call would return to the caller.

(8) & (9) Before we return, we need to determine whether we need to ‘consume’ the flags and if so, we will CLEAR all the flags that satisfied the condition.

(10) & (11) The new value of the event flag group is obtained and returned to the caller.

(12) If ALL the desired bits in the event flag group were not SET then the calling task will block (i.e. suspend) until ALL the bits are either SET or a timeout occurs. Instead of repeating code for all four types of wait, I created a function (OS_FlagBlock()) to handle the details of blocking the calling task (described later).

Wait for ANY of the specified bits to be SET:

(13) When wait_type is set to either OS_FLAG_WAIT_SET_ANY or OS_FLAG_WAIT_SET_OR, OSFlagPend() will ‘extract’ the desired bits in the event flag group which are specified in the flags argument.

(14) If any of the bits extracted matches the bits that you specified in the flags argument then the PEND call will return to the caller.

(15) & (16) Before we return, we need to determine whether we need to ‘consume’ the flag(s) and if so, we need to CLEAR all the flag(s) that satisfied the condition.

(17) & (18) The new value of the event flag group is obtained and returned to the caller.

(19) If NONE of the desired bits in the event flag group were not SET then the calling task will block (i.e. suspend) until ANY of the bits is either SET or a timeout occurs.

Image Added

static void OS_FlagBlock (OS_FLAG_GRP *pgrp, OS_FLAG_NODE *pnode, OS_FLAGS flags, INT8U wait_type, INT16U timeout)
{
    OS_FLAG_NODE  *pnode_next;
 
 
    OSTCBCur->OSTCBStat      |= OS_STAT_FLAG;         (1)
    OSTCBCur->OSTCBDly        = timeout;              
#if OS_TASK_DEL_EN > 0
    OSTCBCur->OSTCBFlagNode   = pnode;                (2)
#endif
    pnode->OSFlagNodeFlags    = flags;                (3)
    pnode->OSFlagNodeWaitType = wait_type;            
    pnode->OSFlagNodeTCB      = (void *)OSTCBCur;     (4)
    pnode->OSFlagNodeNext     = pgrp->OSFlagWaitList; (5)
    pnode->OSFlagNodePrev     = (void *)0;            (6)
    pnode->OSFlagNodeFlagGrp  = (void *)pgrp;         (7)
    pnode_next                = pgrp->OSFlagWaitList; 
    if (pnode_next != (void *)0) {                    
        pnode_next->OSFlagNodePrev = pnode;           (8)
    } 
    pgrp->OSFlagWaitList = (void *)pnode;             (9) 
                                                      (10)
    if ((OSRdyTbl[OSTCBCur->OSTCBY] &= ~OSTCBCur->OSTCBBitX) == 0) {
        OSRdyGrp &= ~OSTCBCur->OSTCBBitY;
    }
}

The notes below apply both and simultaneously to Listing 9.6 and Figure 9.4. When reading each numbered note, refer to both the listing and the figure.

(1) OS_FlagBlock() starts by setting the appropriate fields in the task control block. You should note that an OS_FLAG_NODE is allocated on the stack of the calling task (see OSFlagPend() , L9.5). This means that we don’t need to keep a separate ‘free list’ of OS_FLAG_NODE since these data structures can simply be allocated on the stack of the calling task. That being said, the calling task must have sufficient stack space to allocate this structure on its stack.

(2) We then link the OS_FLAG_NODE to the TCB, but only if OS_TASK_DEL_EN is set to 1. This link allows OSTaskDel() to remove the task being suspended from the wait list should another task decide to delete this task.

(3) Next, OS_FlagBlock() saves the flags that the task is waiting for as well as the wait type in the OS_FLAG_NODE structure.

(4) We then link the TCB to the OS_FLAG_NODE .

(5) The OS_FLAG_NODE is then linked to the other OS_FLAG_NODEs in the wait list.

(6) You should note that the OS_FLAG_NODE is simply inserted at the beginning of the doubly-linked list for simplicity sake.

(7) We then link the event flag group to the OS_FLAG_NODE . This is again done to allow us to delete the task that is being added to the wait list of the event flag group.

(8) OS_FlagBlock() then links the previous ‘first’ node in the wait list to the new OS_FLAG_NODE .

(9) & (10) Finally, the pointer of the beginning of the wait list is updated to point to the new OS_FLAG_NODE and, the calling task is made NOT ready-to-run.

You should note that interrupts are disabled during the process of blocking the calling task.

(20) When OS_FlagBlock() returns, the scheduler is called because, of course, the calling task is no longer able to run since the event(s) it was looking for did not occur.

(21) When µC/OS-II resumes the calling task, OSFlagPend() checks HOW the task was readied. If the status field in the TCB still indicates that the task is still waiting for event flags to be either set or cleared then, the task MUST have been readied because of a timeout.

(22) In this case, the OS_FLAG_NODE is removed from the wait list by calling OS_FlagUnlink() and, an error code is returned to the caller indicating the outcome of the call. The code for OS_FlagUnlink() is shown in Listing 9.7 and should be quite obvious since we are simply removing a node from a doubly linked list. The code provided on the CD-ROM contains comments so you can easily follow what’s going on.

(23) & (24) If the calling task is NOT resumed because of a timeout then, it MUST have been resumed because the event flags that it was waiting for have been either set or cleared. In this case, we determine whether the calling task wanted to consume the event flags. If this is the case, the appropriate flags are either set or cleared based on the wait type.

(25) Finally, OSFlagPend() obtains the current value of the event flags in the group in order to return this information to the caller.

OS_FLAGS  OSFlagPost (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U opt, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                          
    OS_CPU_SR     cpu_sr;
#endif    
    OS_FLAG_NODE *pnode;
    BOOLEAN       sched;
    OS_FLAGS      flags_cur;
    OS_FLAGS      flags_rdy;


#if OS_ARG_CHK_EN > 0
    if (pgrp == (OS_FLAG_GRP *)0) {                  (1)
        *err = OS_FLAG_INVALID_PGRP;
        return ((OS_FLAGS)0);
    }
    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG) {    (2)         
        *err = OS_ERR_EVENT_TYPE;
        return ((OS_FLAGS)0);
    }
#endif
    OS_ENTER_CRITICAL();
    switch (opt) {                                   (3)
        case OS_FLAG_CLR:
             pgrp->OSFlagFlags &= ~flags;            (4)
             break;
             
        case OS_FLAG_SET:
             pgrp->OSFlagFlags |=  flags;            (5)
             break;
          
        default:
             OS_EXIT_CRITICAL();                     
             *err = OS_FLAG_INVALID_OPT;
             return ((OS_FLAGS)0);
    }
    sched = FALSE;                                   (6)
    pnode = pgrp->OSFlagWaitList;                
    while (pnode != (OS_FLAG_NODE *)0) {             (7)
        switch (pnode->OSFlagNodeWaitType) {
            case OS_FLAG_WAIT_SET_ALL:               (8)
                 flags_rdy = pgrp->OSFlagFlags & pnode->OSFlagNodeFlags;
                 if (flags_rdy == pnode->OSFlagNodeFlags) {          (9) 
                     if (OS_FlagTaskRdy(pnode, flags_rdy) == TRUE) { (10)
                         sched = TRUE;                               (11)
                     }
                 }
                 break;

            case OS_FLAG_WAIT_SET_ANY:               
                 flags_rdy = pgrp->OSFlagFlags & pnode->OSFlagNodeFlags;
                 if (flags_rdy != (OS_FLAGS)0) {    
                     if (OS_FlagTaskRdy(pnode, flags_rdy) == TRUE) {
                         sched = TRUE;                              
                     }
                 }
                 break;

#if OS_FLAG_WAIT_CLR_EN > 0
            case OS_FLAG_WAIT_CLR_ALL:               
                 flags_rdy = ~pgrp->OSFlagFlags & pnode->OSFlagNodeFlags;
                 if (flags_rdy == pnode->OSFlagNodeFlags) {     
                     if (OS_FlagTaskRdy(pnode, flags_rdy) == TRUE) {
                         sched = TRUE;                              
                     }
                 }
                 break;

            case OS_FLAG_WAIT_CLR_ANY:               
                 flags_rdy = ~pgrp->OSFlagFlags & pnode->OSFlagNodeFlags;
                 if (flags_rdy != (OS_FLAGS)0) {    
                     if (OS_FlagTaskRdy(pnode, flags_rdy) == TRUE) {
                         sched = TRUE;                              
                     }
                 }
                 break;
#endif                 
        }
        pnode = pnode->OSFlagNodeNext;               (12)
    }
    OS_EXIT_CRITICAL();
    if (sched == TRUE) {                             (13)
        OS_Sched();                                  (14)
    }
    OS_ENTER_CRITICAL();
    flags_cur = pgrp->OSFlagFlags;                   (15)
    OS_EXIT_CRITICAL();
    *err      = OS_NO_ERR;
    return (flags_cur);                              (16)
}

(1) & (2) Assuming that the configuration constant OS_ARG_CHK_EN is set to 1, OSFlagPost() makes sure that the ‘handle’ pgrp is not a NULL pointer and that pgrp points to an event flag group that should have been created by OSFlagCreate() .

(3) & (4) & (5) Depending on the option you specified in the opt argument of OSFlagPost() , the flags specified in the flags argument will either be SET ( when opt == OS_FLAG_SET ) or CLEARED ( when opt == OS_FLAG_CLR ). If opt is not one of the two choices, the call is aborted and an error code is returned to the caller.

(6) We next start by assuming that POSTing doesn’t make a higher priority task ready-to-run and thus, we set the BOOLEAN variable sched to FALSE. If this assumption is not verified because we will make a higher-priority-task ready-to-run then sched will simply be set to TRUE.

(7) We then go through the wait list to see if any task is waiting on one or more events.

(15) & (16) If the wait list is empty, we simply get the current state of the event flag bits and return this information to the caller.

(8) If there is one or more tasks waiting on the event flag group, we go through the list of OS_FLAG_NODEs to see if the new event flag bits now satisfies any of the waiting task conditions. Each one of the tasks can be waiting for one of four conditions:

1. ALL of the bits specified in the PEND call to be set.
2. ANY of the bits specified in the PEND call to be set.
3. ALL of the bits specified in the PEND call to be cleared.
4. ANY of the bits specified in the PEND call to be cleared.

(9) & (10) Note that the last two condition can be ‘compiled-out’ by setting OS_FLAG_WAIT_CLR_EN to 0 (see OS_CFG.H ). You would do this if you didn’t need the functionality of waiting for cleared bits and/or you need to reduce the amount of ROM in your product. When a waiting task’s condition is satisfied, the waiting task is readied by calling OS_FlagTaskRdy() (see Listing 9.9). I will only discuss the first wait condition because the other cases are similar enough.

(11) Because a task is made ready-to-run, the scheduler will have to be called. However, we will only do this after going through all waiting tasks because, there is no need to call the scheduler every time a task is made ready-to-run.

(12) We proceed to the next node by following the linked list.

You should note that interrupts are disabled while we are going through the wait list. The implication is that OSFlagPost() can potentially disable interrupts for a long period of time, especially if multiple tasks are made ready-to-run. However, execution time is bounded and still deterministic.

(13) & (14) When we have gone through the whole waiting list, we examine the sched flag to see if we need to run the scheduler and thus possibly perform a context switch to a higher priority task that just received the event flag(s) it was waiting for.

(15) & (16) OSFlagPost() returns the current state of the event flag group.

static  BOOLEAN  OS_FlagTaskRdy (OS_FLAG_NODE *pnode, OS_FLAGS flags_rdy)
{
    OS_TCB   *ptcb;
    BOOLEAN   sched;
          
                                                        
    ptcb                = (OS_TCB *)pnode->OSFlagNodeTCB;
    ptcb->OSTCBDly      = 0;                             
    ptcb->OSTCBFlagsRdy = flags_rdy;                     
    ptcb->OSTCBStat    &= ~OS_STAT_FLAG;
    if (ptcb->OSTCBStat == OS_STAT_RDY) {                  (1)                
        OSRdyGrp               |= ptcb->OSTCBBitY;
        OSRdyTbl[ptcb->OSTCBY] |= ptcb->OSTCBBitX;
        sched                   = TRUE;                    (2)
    } else {
        sched                   = FALSE;                   (3)
    }
    OS_FlagUnlink(pnode);                                  (4)
    return (sched);
}

(1) & (2) & (3) Note that even though this function ‘removes’ the waiting task from the event flag group wait list, the task could still be suspended and may not be ready-to-run. This is why the BOOLEAN variable sched is used and returned to the caller.

(4) This is a standard procedure in µC/OS-II (see section 6.02, Making a Task Ready) except for the fact that the OS_FLAG_NODE needs to be unlinked from the waiting list of the event flag group as well as the task’s OS_TCB.

void  OS_FlagUnlink (OS_FLAG_NODE *pnode)
{
#if OS_TASK_DEL_EN > 0
    OS_TCB       *ptcb;
#endif
    OS_FLAG_GRP  *pgrp;
    OS_FLAG_NODE *pnode_prev;
    OS_FLAG_NODE *pnode_next;
    
    
    pnode_prev = pnode->OSFlagNodePrev;                                (1)
    pnode_next = pnode->OSFlagNodeNext;                                (2)
    if (pnode_prev == (OS_FLAG_NODE *)0) {                             (3)
        pgrp                 = pnode->OSFlagNodeFlagGrp;               (4)
        pgrp->OSFlagWaitList = (void *)pnode_next;                     (5)
        if (pnode_next != (OS_FLAG_NODE *)0) {                         (6)
            pnode_next->OSFlagNodePrev = (OS_FLAG_NODE *)0;            (7)
        }
    } else {                                                              
        pnode_prev->OSFlagNodeNext = pnode_next;                       (8)
        if (pnode_next != (OS_FLAG_NODE *)0) {                         (9)
            pnode_next->OSFlagNodePrev = pnode_prev;                  (10)
        }
    }
#if OS_TASK_DEL_EN > 0
    ptcb                = (OS_TCB *)pnode->OSFlagNodeTCB;             (11)
    ptcb->OSTCBFlagNode = (void *)0;                                  (12)
#endif
}

(1) & (2) OS_FlagUnlink() starts off by setting up two local pointers: pnode_next and pnode_prev which point to the next and previous OS_FLAG_NODE in the wait list, respectively.

(3) & F9.5(A, B) The previous pointer is examined to see if we have the first two cases of figure 9.6 (an OS_FLAG_NODE which is the first node in the wait list).

(4) & (5) If the OS_FLAG_NODE is the first node, the wait list pointer of the event flag group will need to point to the node immediately after the OS_FLAG_NODE to remove.

(6) & (7)

F9.5(B) If there is an OS_FLAG_NODE to the right of the node to delete then, that node will now point to where the previous pointer of the node to delete is pointing to which is of course a NULL pointer since the node to remove was the first one.

(8) & F9.5(C, D) Because the node to delete is not the first node in the wait list, the node to the left of the node to delete must now point to the node to the right of the node to delete.

(9) & (10) If there is a node to the right of the node to delete, the previous pointer of that node must now point to the previous node of the node to delete.

(11) & (12) In all cases, the .OSTCBFlagNode field must now point to NULL because the node to be deleted will no longer exist once it’s deallocated from the task that created the node in the first place.

Image Added

Image Added

Image Added

Image Added

Image Added

OS_FLAGS  OSFlagAccept (OS_FLAG_GRP *pgrp, OS_FLAGS flags, INT8U wait_type, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3      
    OS_CPU_SR     cpu_sr;
#endif    
    OS_FLAGS      flags_cur;
    OS_FLAGS      flags_rdy;
    BOOLEAN consume;
#if OS_ARG_CHK_EN > 0
    if (pgrp == (OS_FLAG_GRP *)0) {    
  *err = OS_FLAG_INVALID_PGRP;
  return ((OS_FLAGS)0);
    }
    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG) {   
  *err = OS_ERR_EVENT_TYPE;
  return ((OS_FLAGS)0);
    }
#endif
    if (wait_type & OS_FLAG_CONSUME) { 
  wait_type &= ~OS_FLAG_CONSUME;
  consume    = TRUE;
    } else {
  consume    = FALSE;
    }
    OS_ENTER_CRITICAL();
    switch (wait_type) {
  case OS_FLAG_WAIT_SET_ALL:     
      flags_rdy = pgrp->OSFlagFlags & flags; 
       if (flags_rdy == flags) { 
           if (consume == TRUE) {      
       pgrp->OSFlagFlags &= ~flags_rdy;      
   }
    flags_cur = pgrp->OSFlagFlags;     
           OS_EXIT_CRITICAL();   
           *err      = OS_NO_ERR;
      } else {
   flags_cur = pgrp->OSFlagFlags;
   OS_EXIT_CRITICAL();
   *err      = OS_FLAG_ERR_NOT_RDY;
      }
      break;
  case OS_FLAG_WAIT_SET_ANY:
      flags_rdy = pgrp->OSFlagFlags & flags; 
       if (flags_rdy != (OS_FLAGS)0) { 
     if (consume == TRUE) {      
       pgrp->OSFlagFlags &= ~flags_rdy;      
          }
    flags_cur = pgrp->OSFlagFlags;     
           OS_EXIT_CRITICAL();   
   *err      = OS_NO_ERR;
      } else {
   flags_cur = pgrp->OSFlagFlags;
   OS_EXIT_CRITICAL();
   *err      = OS_FLAG_ERR_NOT_RDY;
      }
      break;
#if OS_FLAG_WAIT_CLR_EN > 0
  case OS_FLAG_WAIT_CLR_ALL:     
      flags_rdy = ~pgrp->OSFlagFlags & flags; 
             if (flags_rdy == flags) { 
     if (consume == TRUE) {      
       pgrp->OSFlagFlags |= flags_rdy; 
   }
    flags_cur = pgrp->OSFlagFlags;     
           OS_EXIT_CRITICAL();   
   *err      = OS_NO_ERR;
      } else {
   flags_cur = pgrp->OSFlagFlags;
   OS_EXIT_CRITICAL();
   *err      = OS_FLAG_ERR_NOT_RDY;
      }
      break;
  case OS_FLAG_WAIT_CLR_ANY:
      flags_rdy = ~pgrp->OSFlagFlags & flags; 
       if (flags_rdy != (OS_FLAGS)0) { 
     if (consume == TRUE) {      
                     pgrp->OSFlagFlags |= flags_rdy; 
   }
    flags_cur = pgrp->OSFlagFlags;     
           OS_EXIT_CRITICAL();   
   *err      = OS_NO_ERR;
      } else {
   flags_cur = pgrp->OSFlagFlags;
   OS_EXIT_CRITICAL();
   *err      = OS_FLAG_ERR_NOT_RDY;
      }
      break;
#endif
  default:
      OS_EXIT_CRITICAL();
      flags_cur = (OS_FLAGS)0;
      *err      = OS_FLAG_ERR_WAIT_TYPE;
      break;
    }
    return (flags_cur);
}

OS_FLAGS  OSFlagQuery (OS_FLAG_GRP *pgrp, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                
    OS_CPU_SR  cpu_sr;
#endif    
    OS_FLAGS   flags;
#if OS_ARG_CHK_EN > 0
    if (pgrp == (OS_FLAG_GRP *)0) { (1) 
  *err = OS_FLAG_INVALID_PGRP;
  return ((OS_FLAGS)0);
    }
    if (pgrp->OSFlagType != OS_EVENT_TYPE_FLAG) { (2) 
  *err = OS_ERR_EVENT_TYPE;
  return ((OS_FLAGS)0);
    }
#endif    
    OS_ENTER_CRITICAL();
    flags = pgrp->OSFlagFlags;      (3) 
    OS_EXIT_CRITICAL();
    *err = OS_NO_ERR;
    return (flags);                        (4) 
}

(1) & (2) As with all µC/OS-II calls, OSFlagQuery() performs argument checking if this feature is enabled when OS_ARG_CHK_EN is set to 1 in OS_CFG.H .

(3) & (4) If there are no errors, OSFlagQuery() obtains the current state of the event flags and returns this to the caller.