====== OSA : Flags ======

===== Intro =====

Flags are similar to binary semaphores. There are two differences:
  - you can wait, check, set or reset several flags at one time;
  - after accepting flags their values do not change.

Flags can be useful when a task requires the results of several tasks. For example: to calculate some physical parameters a task needs information about the temperature, pressure and humidity. Each of these parameters is measured in its own task which sets a flag when measurement is complete.

<code cpp>
#include <osa.h>

OST_FLAG8   F_Sensors;

#define  TEMPERATURE_MEASURED   0x01
#define  PRESSURE_MEASURED      0x02
#define  HUMIDITY_MEASURED      0x04

void Task_Calc (void)
{
    for (;;) {
        // Wait for all measurements complete
        OS_Flag_Wait_AllOn(F_Sensors, TEMPERATURE_MEASURED | PRESSURE_MEASURED | HUMIDITY_MEASURED);
        OS_Flag_Clear(F_Sensors, TEMPERATURE_MEASURED | PRESSURE_MEASURED | HUMIDITY_MEASURED);

        // Now we can calculate
        ...
    }
}
</code>

~~UP~~

===== Definition =====

There are three types of flags: 8-, 16- and 32-bit.

<code cpp>
OST_FLAG      MyFlag1;	//  8-bit flags
OST_FLAG16    MyFlag2;	// 16-bit flags
OST_FLAG32    MyFlag3;	// 32-bit flags
</code>

It is possible to use different size of flags at the same time.

Flags can be allocated in any memory bank, e.g.:

<code cpp>
bank2    OST_FLAG16   MyFlag;
</code>

~~UP~~

===== Services =====

^  Service  ^  Arguments  ^  Description  ^  Properties  ^
| **Creating**    ||||
| ##[[en:osa:ref:allservices:OS_Flag_Create|OS_Flag_Create]]##  |  ''(flag)''  | (**flag = 0**) Create flag and clear all its bits  |   |
| **Management** ||||
| ##[[en:osa:ref:allservices:OS_Flag_Init|OS_Flag_Init]]##  |  ''(flag, value)''  | (**flag = value**) Set flag to given value  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Set|OS_Flag_Set]]##  |  ''(flag, mask)''  | (**flag = flag** %%|%% **mask**) Set bits in flag according to mask  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Clear|OS_Flag_Clear]]##  |  ''(flag, mask)''  | (**flag &= ~mask**) Clear bits in flag according to mask  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Checking**    ||||
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Flag_Check_AllOn|OS_Flag_Check_AllOn]]##  |  ''(flag, mask)''  | (** if ((flag & mask)==mask) **) Check if all bits in flag specified by mask are set  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Flag_Check_On|OS_Flag_Check_On]]##  |  ''(flag, mask)''  | (** if ((flag & mask)!=0) **) Check if any bit in flags specified by mask is set  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Flag_Check_AllOff|OS_Flag_Check_AllOff]]##  |  ''(flag, mask)''  | (** if ((flag & mask)==0) **) Check if all bits in flag specified by mask are clear  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Flag_Check_Off|OS_Flag_Check_Off]]##  |  ''(flag, mask)''  | (** if ((flag & mask)!=mask) **) Check if any bit in flag specified by mask is clear  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Waiting**     ||||
| ##[[en:osa:ref:allservices:OS_Flag_Wait_AllOn|OS_Flag_Wait_AllOn]]##  |  ''(flag, mask)''  | (** if ((flag & mask)==mask) **) Wait until all bits in flag specified by mask are set  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_On|OS_Flag_Wait_On]]##  |  ''(flag, mask)''  | (** wait ((flag & mask)!=0) **) Wait until any bit in flag specified by mask is set  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_AllOff|OS_Flag_Wait_AllOff]]##  |  ''(flag, mask)''  | (** wait ((flag & mask)==0) **) Wait until all bits in flag specified by mask are clear  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_Off|OS_Flag_Wait_Off]]##  |  ''(flag, mask)''  | (** wait ((flag & mask)!=mask) **) Wait until any bit in flag specified by mask is clear  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_AllOn_TO|OS_Flag_Wait_AllOn_TO]]##  |  ''(flag, mask, timeout)''  | (** wait ((flag & mask)==mask) **) Wait until all bits in flags specified by mask are set. Exit if timeout expired  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_On_TO|OS_Flag_Wait_On_TO]]##  |  ''(flag, mask, timeout)''  | (** wait ((flag & mask)!=0) **) Wait until any bit in flags specified by mask is set. Exit if timeout expired  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_AllOff_TO|OS_Flag_Wait_AllOff_TO]]##  |  ''(flag, mask, timeout)''  | (** wait ((flag & mask)==0) **) Wait until all bits in flag specified by mask are clear. Exit if timeout expired  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |
| ##[[en:osa:ref:allservices:OS_Flag_Wait_Off_TO|OS_Flag_Wait_Off_TO]]##  |  ''(flag, mask, timeout)''  | (** wait ((flag & mask)!=mask) **) Wait until any bit in flag specified by mask is clear. Exit if timeout expired  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |

~~UP~~