引言

大家在裸機編程中很可能經常用到flag這種變數，用來標志一下某個事件的發生，然后在回圈中判斷這些標志是否發生，如果是等待多個事件的話，還可能會if((xxx_flag)&&(xxx_flag))這樣子做判斷，當然，如果聰明一點的同學就會拿flag的某些位做標志，比如這個變數的第一位表示A事件，第二位表示B事件，當這兩個事件都發生的時候，就判斷flag&0x03的值是多少，從而判斷出哪個事件發生了，

但在作業系統中又將如何實作呢？

事件

在作業系統中，事件是一種內核資源，主要用于任務與任務間、中斷與任務間的同步，不提供資料傳輸功能！

與使用信號量同步有細微的差別：事件它可以實作一對多，多對多的同步，即一個任務可以等待多個事件的發生：可以是任意一個事件發生時喚醒任務進行事件處理；也可以是幾個事件都發生后才喚醒任務進行事件處理，同樣，也可以是多個任務同步多個事件，

每一個事件組只需要極少的RAM空間來保存事件旗標，一個事件（控制塊）中包含了一個旗標，這個旗標的每一位表示一個“事件”，旗標存盤在一個k_event_flag_t型別的變數中（名字叫flag，旗標簡單理解就是事件標記變數），該變數在事件控制塊中被定義，每一位代表一個事件，任務通過“邏輯與”或“邏輯或”與一個或多個事件建立關聯，在事件發生時任務將被喚醒，

事件“邏輯或”是獨立型同步，指的是任務所等待的若干事件中任意一個事件發生即可被喚醒；
事件“邏輯與”則是關聯型同步，指的是任務所等待的若干事件中全部都發生時才被喚醒，

事件是一種實作任務間通信的機制，可用于實作任務間的同步，但事件無資料傳輸，多任務環境下，任務、中斷之間往往需要同步操作，一個事件發生會告知等待中的任務，即形成一個任務與任務、中斷與任務間的同步，

事件無排隊性，即多次向任務設定同一事件(如果任務還未來得及讀走)，等效于只設定一次，

此外事件可以提供一對多、多對多的同步操作，

一對多同步模型：一個任務等待多個事件的觸發，這種情況是比較常見的；
多對多同步模型：多個任務等待多個事件的觸發，任務可以通過設定事件位來實作事件的觸發和等待操作，

事件資料結構

事件控制塊

TencentOS tiny 通過事件控制塊操作事件，其資料型別為k_event_t，事件控制塊由多個元素組成，

pend_obj有點類似于面向物件的繼承，繼承一些屬性，里面有描述內核資源的型別（如互斥鎖、佇列、互斥量等，同時還有一個等待串列list），
flag是旗標，一個32位的變數，因此每個事件控制塊最多只能標識32個事件發生！

typedef struct k_event_st {
    pend_obj_t      pend_obj;
    k_event_flag_t  flag;
} k_event_t;

任務控制塊與事件相關的資料結構

typedef struct k_task_st {
	···
    k_opt_t             opt_event_pend;     /**< 等待事件的的操作型別：TOS_OPT_EVENT_PEND_ANY 、 TOS_OPT_EVENT_PEND_ALL */
    k_event_flag_t      flag_expect;        /**< 期待發生的事件 */
    k_event_flag_t     *flag_match;         /**< 等待到的事件（匹配的事件） */
	···
} k_task_t;

與事件相關的宏定義

在tos_config.h中，配置事件開關的宏定義是TOS_CFG_EVENT_EN

#define TOS_CFG_EVENT_EN            1u

在tos_event.h中，存在一些宏定義是用于操作事件的（opt選項）：

// if we are pending an event, for any flag we expect is set is ok, this flag should be passed to tos_event_pend 
#define TOS_OPT_EVENT_PEND_ANY          (k_opt_t)0x0001

// if we are pending an event, must all the flag we expect is set is ok, this flag should be passed to tos_event_pend 
#define TOS_OPT_EVENT_PEND_ALL          (k_opt_t)0x0002

#define TOS_OPT_EVENT_PEND_CLR          (k_opt_t)0x0004

TOS_OPT_EVENT_PEND_ANY：任務在等待任意一個事件發生，即“邏輯或”！
TOS_OPT_EVENT_PEND_ALL：任務在等待所有事件發生，即“邏輯與”！
TOS_OPT_EVENT_PEND_CLR：清除等待到的事件旗標，可以與TOS_OPT_EVENT_PEND_ANY、TOS_OPT_EVENT_PEND_ALL混合使用（通過“|”運算子），

除此之外還有一個列舉型別的資料結構，用于發送事件時的選項操作，可以在發送事件時清除事件旗標的其他位（即覆寫，影響其他事件），也可以保持原本旗標中的其他位（不覆寫，不影響其他事件），

typedef enum opt_event_post_en {
    OPT_EVENT_POST_KEP,
    OPT_EVENT_POST_CLR,
} opt_event_post_t;

創建事件

系統中每個事件都有對應的事件控制塊，事件控制塊中包含了事件的所有資訊，比如它的等待串列、它的資源型別，以及它的事件旗標值，那么可以想象一下，創建事件的本質是不是就是對事件控制塊進行初始化呢？很顯然就是這樣子的，因為在后續對事件的操作都是通過事件控制塊來操作的，如果控制塊沒有資訊，那怎么能操作嘛~

創建事件函式是tos_event_create()，傳入一個事件控制塊的指標*event，除此之外還可以指定事件初始值init_flag，

事件的創建實際上就是呼叫pend_object_init()函式將事件控制塊中的event->pend_obj成員變數進行初始化，它的資源型別被標識為PEND_TYPE_EVENT，然后將event->flag成員變數設定為事件旗標初始值init_flag，

__API__ k_err_t tos_event_create(k_event_t *event, k_event_flag_t init_flag)
{
    TOS_PTR_SANITY_CHECK(event);

    pend_object_init(&event->pend_obj, PEND_TYPE_EVENT);
    event->flag = init_flag;
    return K_ERR_NONE;
}

銷毀事件

事件銷毀函式是根據事件控制塊直接銷毀的，銷毀之后事件的所有資訊都會被清除，而且不能再次使用這個事件，當事件被銷毀時，其等待串列中存在任務，系統有必要將這些等待這些任務喚醒，并告知任務事件已經被銷毀了PEND_STATE_DESTROY，然后產生一次任務調度以切換到最高優先級任務執行，

TencentOS tiny 對事件銷毀的處理流程如下：

呼叫pend_is_nopending()函式判斷一下是否有任務在等待事件
如果有任務在等待事件則呼叫pend_wakeup_all()函式將這些任務喚醒，并且告知等待任務事件已經被銷毀了（即設定任務控制塊中的等待狀態成員變數pend_state為PEND_STATE_DESTROY），
呼叫pend_object_deinit()函式將事件控制塊中的內容清除，最主要的是將控制塊中的資源型別設定為PEND_TYPE_NONE，這樣子就無法使用這個事件了，
將event->flag成員變數恢復為默認值0，
進行任務調度knl_sched()

注意：如果事件控制塊的RAM是由編譯器靜態分配的，所以即使是銷毀了事件，這個記憶體也是沒辦法釋放的，當然你也可以使用動態記憶體為事件控制塊分配記憶體，只不過在銷毀后要將這個記憶體釋放掉，避免記憶體泄漏，

__API__ k_err_t tos_event_destroy(k_event_t *event)
{
    TOS_CPU_CPSR_ALLOC();

    TOS_PTR_SANITY_CHECK(event);

#if TOS_CFG_OBJECT_VERIFY_EN > 0u
    if (!pend_object_verify(&event->pend_obj, PEND_TYPE_EVENT)) {
        return K_ERR_OBJ_INVALID;
    }
#endif

    TOS_CPU_INT_DISABLE();

    if (!pend_is_nopending(&event->pend_obj)) {
        pend_wakeup_all(&event->pend_obj, PEND_STATE_DESTROY);
    }

    pend_object_deinit(&event->pend_obj);
    event->flag = (k_event_flag_t)0u;

    TOS_CPU_INT_ENABLE();
    knl_sched();

    return K_ERR_NONE;
}

等待事件

tos_event_pend()函式用于獲取事件，通過這個函式，就可以知道事件旗標中的哪一位被置1，即哪一個事件發生了，然后任務可以對等待的事件指定“邏輯與”、“邏輯或”進行等待操作（opt_pend選項），

并且這個函式實作了等待超時機制，且僅當任務等待的事件發生時，任務才能等待到事件，當事件未發生的時候，等待事件的任務會進入阻塞態，阻塞時間timeout由用戶指定，在這段時間中，如果事件一直沒發生，該任務將保持阻塞狀態以等待事件發生，當其它任務或中斷服務程式往其等待的事件旗標設定對應的標志位，該任務將自動由阻塞態轉為就緒態，當任務等待的時間超過了指定的阻塞時間，即使事件還未發生，任務也會自動從阻塞態轉移為就緒態，這樣子很有效的體現了作業系統的實時性，

任務獲取了某個事件時，可以選擇清除事件操作，

等待事件的操作不允許在中斷背景關系環境運行！

等待事件的程序如下：

首先檢測傳入的引數是否正確，，注意opt_pend的選項必須存在TOS_OPT_EVENT_PEND_ALL 或者 TOS_OPT_EVENT_PEND_ANY 之一，且二者不允許同時存在（互斥），
呼叫event_is_match()函式判斷等待的事件是否已發生（即任務等待的事件與事件控制塊中的旗標是否匹配），
在event_is_match()函式中會根據等待選項opt_pend是等待任意一個事件（TOS_OPT_EVENT_PEND_ANY）還是等待所有事件（TOS_OPT_EVENT_PEND_ANY）做出是否匹配的判斷，如果是匹配了則回傳K_TRUE，反之回傳K_FALSE，同時等待到的事件通過flag_match變數回傳（已發生匹配），對于等待所有時間的選項，當且僅當所有事件都發生是才算匹配：(event & flag_expect) == flag_expect)，對于等待任意一個事件的選項，有其中一個事件發生都算匹配：(event & flag_expect)，
如果事件未發生則可能會阻塞當前獲取的任務，看一下用戶指定的阻塞時間timeout是否為不阻塞TOS_TIME_NOWAIT，如果不阻塞則直接回傳K_ERR_PEND_NOWAIT錯誤代碼，
如果調度器被鎖了knl_is_sched_locked()，則無法進行等待操作，回傳錯誤代碼K_ERR_PEND_SCHED_LOCKED，畢竟需要切換任務，調度器被鎖則無法切換任務，
將任務控制塊中關于事件的變數設定一下，即設定任務期望等待的事件k_curr_task->flag_expect，任務匹配的事件k_curr_task->flag_match，以及任務等待事件的選項k_curr_task->opt_event_pend，
呼叫pend_task_block()函式將任務阻塞，該函式實際上就是將任務從就緒串列中移除k_rdyq.task_list_head[task_prio]，并且插入到等待串列中object->list，如果等待的時間不是永久等待TOS_TIME_FOREVER，還會將任務插入時間串列中k_tick_list，阻塞時間為timeout，然后進行一次任務調度knl_sched()，
當程式能繼續往下執行時，則表示任務等待到事件，又或者等待發生了超時，任務就不需要等待事件了，此時將任務控制塊中的內容清空，即清空任務期望等待的事件k_curr_task->flag_expect，任務匹配的事件k_curr_task->flag_match，以及任務等待事件的選項k_curr_task->opt_event_pend，同時還呼叫pend_state2errno()函式獲取一下任務的等待狀態，看一下是哪種情況導致任務恢復運行，并且將結果回傳給呼叫等待事件函式的任務，

注意：當等待事件的任務能從阻塞中恢復運行，也不一定是等待到事件發生，也有可能是發生了超時，因此在寫程式的時候必須要判斷一下等待的事件狀態，如果是K_ERR_NONE則表示獲取成功！

代碼如下：

__STATIC__ int event_is_match(k_event_flag_t event, k_event_flag_t flag_expect, k_event_flag_t *flag_match, k_opt_t opt_pend)
{
    if (opt_pend & TOS_OPT_EVENT_PEND_ALL) {
        if ((event & flag_expect) == flag_expect) {
            *flag_match = flag_expect;
            return K_TRUE;
        }
    } else if (opt_pend & TOS_OPT_EVENT_PEND_ANY) {
        if (event & flag_expect) {
            *flag_match = event & flag_expect;
            return K_TRUE;
        }
    }
    return K_FALSE;
}

__API__ k_err_t tos_event_pend(k_event_t *event, k_event_flag_t flag_expect, k_event_flag_t *flag_match, k_tick_t timeout, k_opt_t opt_pend)
{
    TOS_CPU_CPSR_ALLOC();

    TOS_PTR_SANITY_CHECK(event);
    TOS_PTR_SANITY_CHECK(flag_match);
    TOS_IN_IRQ_CHECK();

#if TOS_CFG_OBJECT_VERIFY_EN > 0u
    if (!pend_object_verify(&event->pend_obj, PEND_TYPE_EVENT)) {
        return K_ERR_OBJ_INVALID;
    }
#endif

    if (!(opt_pend & TOS_OPT_EVENT_PEND_ALL) && !(opt_pend & TOS_OPT_EVENT_PEND_ANY)) {
        return K_ERR_EVENT_PEND_OPT_INVALID;
    }

    if ((opt_pend & TOS_OPT_EVENT_PEND_ALL) && (opt_pend & TOS_OPT_EVENT_PEND_ANY)) {
        return K_ERR_EVENT_PEND_OPT_INVALID;
    }

    TOS_CPU_INT_DISABLE();

    if (event_is_match(event->flag, flag_expect, flag_match, opt_pend)) {
        if (opt_pend & TOS_OPT_EVENT_PEND_CLR) { // destroy the bridge after get across the river
            event->flag = (k_event_flag_t)0u;
        }
        TOS_CPU_INT_ENABLE();
        return K_ERR_NONE;
    }

    if (timeout == TOS_TIME_NOWAIT) {
        TOS_CPU_INT_ENABLE();
        return K_ERR_PEND_NOWAIT;
    }

    if (knl_is_sched_locked()) {
        TOS_CPU_INT_ENABLE();
        return K_ERR_PEND_SCHED_LOCKED;
    }

    k_curr_task->flag_expect      = flag_expect;
    k_curr_task->flag_match       = flag_match;
    k_curr_task->opt_event_pend   = opt_pend;

    pend_task_block(k_curr_task, &event->pend_obj, timeout);

    TOS_CPU_INT_ENABLE();
    knl_sched();

    k_curr_task->flag_expect      = (k_event_flag_t)0u;
    k_curr_task->flag_match       = (k_event_flag_t *)K_NULL;
    k_curr_task->opt_event_pend   = (k_opt_t)0u;

    return pend_state2errno(k_curr_task->pend_state);
}

發送事件

TencentOS tiny 提供兩個函式發送事件，分別是：tos_event_post()與tos_event_post_keep()，兩個函式本質上都是呼叫同一個函式event_do_post()去實作發送事件的操作的，只不過選項是不同而已，使用tos_event_post()函式會覆寫寫入指定的事件，可能影響其他已發生的事件，而tos_event_post_keep()函式則可以保持其他事件位不改變的同時發生事件，在實際情況中后者更常用，

此函式用于將已發生的事件寫入事件旗標中指定的位，當對應的位被置1之后，等待事件的任務將可能被恢復，此時需要遍歷等待在事件物件上的事件等待串列，判斷是否有任務期望的事件與當前事件旗標的值匹配，如果有，則喚醒該任務，

簡單來說，就是設定自己定義的事件標志位為1，并且看看有沒有任務在等待這個事件，有的話就喚醒它，

TencentOS tiny 中設計的很好的地方就是簡單與低耦合，這兩個api介面本質上都是呼叫event_do_post()函式去發生事件，只是通過opt_post引數不同選擇不同的處理方法，

在event_do_post()函式中的處理也是非常簡單明了的，其執行思路如下：

首先判斷一下發生事件的方式opt_post，如果是OPT_EVENT_POST_KEP則采用或運算“|”寫入事件旗標，否則直接賦值，
使用TOS_LIST_FOR_EACH_SAFE遍歷等待在事件物件上的事件等待串列，通過event_is_match()函式判斷是否有任務期望的事件與當前事件旗標的值匹配，如果有則呼叫pend_task_wakeup()函式喚醒對應的任務，
如果喚醒的等待任務指定了清除對應的事件，那么將清除事件的旗標值，
最后進行一次任務調度knl_sched()，

__STATIC__ k_err_t event_do_post(k_event_t *event, k_event_flag_t flag, opt_event_post_t opt_post)
{
    TOS_CPU_CPSR_ALLOC();
    k_task_t *task;
    k_list_t *curr, *next;

#if TOS_CFG_OBJECT_VERIFY_EN > 0u
    if (!pend_object_verify(&event->pend_obj, PEND_TYPE_EVENT)) {
        return K_ERR_OBJ_INVALID;
    }
#endif

    if (opt_post == OPT_EVENT_POST_KEP) {
        event->flag |= flag;
    } else {
        event->flag = flag;
    }

    TOS_CPU_INT_DISABLE();

    TOS_LIST_FOR_EACH_SAFE(curr, next, &event->pend_obj.list) {
        task = TOS_LIST_ENTRY(curr, k_task_t, pend_list);

        if (event_is_match(event->flag, task->flag_expect, task->flag_match, task->opt_event_pend)) {
            pend_task_wakeup(TOS_LIST_ENTRY(curr, k_task_t, pend_list), PEND_STATE_POST);

            // if anyone pending the event has set the TOS_OPT_EVENT_PEND_CLR, then no wakeup for the others pendig for the event.
            if (task->opt_event_pend & TOS_OPT_EVENT_PEND_CLR) {
                event->flag = (k_event_flag_t)0u;
                break;
            }
        }
    }

    TOS_CPU_INT_ENABLE();
    knl_sched();

    return K_ERR_NONE;
}

__API__ k_err_t tos_event_post(k_event_t *event, k_event_flag_t flag)
{
    TOS_PTR_SANITY_CHECK(event);

    return event_do_post(event, flag, OPT_EVENT_POST_CLR);
}

__API__ k_err_t tos_event_post_keep(k_event_t *event, k_event_flag_t flag)
{
    TOS_PTR_SANITY_CHECK(event);

    return event_do_post(event, flag, OPT_EVENT_POST_KEP);
}