/*
*********************************************************************************************************
*                                                uC/OS-II
*                                          The Real-Time Kernel
*
*                           (c) Copyright 1992-2002, Jean J. Labrosse, Weston, FL
*                                           All Rights Reserved
*
*                                               EXAMPLE #1
*********************************************************************************************************
*/

#include "includes.h"
/*這里只有一句簡單的#include語句，這是因為所有相關的頭文件都放在了一個主控頭文件includes.h中。
每個文件通常都包含這個主控頭文件，這樣就無須考慮每個文件應該包含哪些相應的頭文件，這些文件通過includes.h包含進來了。
可以使用文本編譯軟件查看includes.h文件的內容，這個文件也在SOURCE目錄下。
{#include    <stdio.h>
#include    <string.h>
#include    <ctype.h>
#include    <stdlib.h>
#include    <conio.h>
#include    <dos.h>
#include    <setjmp.h>

#include    "\software\ucos-ii\ix86l\bc45\os_cpu.h"
#include    "os_cfg.h"
#include    "\software\ucos-ii\source\ucos_ii.h"
#include    "\software\blocks\pc\bc45\pc.h"
}*/

/*
*********************************************************************************************************
*                                               CONSTANTS
*********************************************************************************************************
*/

#define  TASK_STK_SIZE                 512       /* Size of each task's stacks (# of WORDs) 每個任務的堆棧的個數*/
#define  N_TASKS                        10       /* Number of identical tasks （identical同一的 同樣的）*/

/*
*********************************************************************************************************
*                                               VARIABLES
*********************************************************************************************************
*/

OS_STK        TaskStk[N_TASKS][TASK_STK_SIZE];        /* Tasks stacks                                  */
OS_STK        TaskStartStk[TASK_STK_SIZE];            /*如果移植在x86上的話 因為x86上OS_STK為16位變量所以堆棧的
                                                      大小為512*16%8B  1024B  */
char          TaskData[N_TASKS];                      /* Parameters(參數, 參量, <口>起限定作用的因素) to
                                                                       pass to each task               */
OS_EVENT     *RandomSem;

/*
*********************************************************************************************************
*                                           FUNCTION PROTOTYPES
*********************************************************************************************************
*/

        void  Task(void *data);                       /* Function prototypes(原型) of tasks之所以返回參數類型設置
        成為void，是因為當任務開始執行時，會有一個參數傳遞給用戶任務代碼。這個參數是一個指向void的指針，以允許
        用戶應用程序向該任務傳遞任何類型的參數。這個指針實際上是一個萬能的車子，用于裝載傳遞給任務的參數，這個參數
        可以是一個變量的地址，一個數據結構，后者，如果有必要，甚至可以是一個函數的入口地址。也可以建立許多相同的任務
        ，所有任務都是用同一個函數或者說是同一個任務程序代碼*/
        void  TaskStart(void *data);                  /* Function prototypes of Startup task           */
static  void  TaskStartCreateTasks(void);
static  void  TaskStartDispInit(void);
static  void  TaskStartDisp(void);

/*$PAGE*/
/*
*********************************************************************************************************
*                                                MAIN
*********************************************************************************************************
*/

void  main (void)
{
    PC_DispClrScr(DISP_FGND_WHITE + DISP_BGND_BLACK);      /* Clear the screen從清屏開始，位的是保證屏幕
     生不留下以前的DOS下的顯示。PC_DispClrScr()函數可以在PC.C文件中找到，在\SOFTWARE\BLOCKS\PC\BC45下。*/

    OSInit();                                              /* Initialize（初始化） uC/OS-II在使用UCOS提供
    的任何功能之前必須調用OSInit() 該函數建立了兩個任務 一個是空閑任務 在其他任務為就緒時運行；另一個統計
    任務 計算CPU的利用率。*/

    PC_DOSSaveReturn();                                    /* Save environment to return to DOS調用該函數
    保存當前的DOS環境。這使得用戶可以返回到沒有運行UCOS之前的DOS環境*/
    PC_VectSet(uCOS, OSCtxSw);                             /* Install uC/OS-II's context switch vector（向
    量）指定UCOS中的任務切換處理函數。任務級的任務切換通過80x86的INT指令引發中斷，通過向量地址調用指定的處
    理函數這里使用了0x80的向量(128),因為DOS和BIOS都沒有使用這個向量 */

    RandomSem   = OSSemCreate(1);                          /* Random（隨意, 任意） number semaphore（旗語）
    建立一個信號量，用以保護BORLANDC\C++庫中產生隨機數的函數。信號量是UCOS提供的一種機制，用于防止多個任務
    同時訪問同一個資源（本例中資源為產生隨機數的函數）。之所以使用信號量，是因為假設產生隨機數的函數不具備
    可重入性（這是一種安全的做發）信號量的初值設置為1，通知UCOS在某一時刻只有一個任務可一調用隨機數產生的函
    數OSSemCreate(1)建立了該信號量，并指點了信號量的初始值，該函數返回一個指向信號量的指針
    OS_EVENT  *RandomSem 接下來對該信號量的操作都通過這個指針來實現*/

    OSTaskCreate(TaskStart, (void *)0, &TaskStartStk[TASK_STK_SIZE - 1], 0);
                                                /* Start multitasking（多(重)任務處理）在開始多
    任務之前必須至少建立一個任務。在這個范例中，建立了一個叫做TaskStart（）的任務，這個任務有四個參數：第一
    個參數是指向該任務運行代碼的指針，在這個范例中不需要任何初始化數據，所以傳遞了一個空NULL在范例四中會討論
    這個任務初始化的用法；第三個參數是任務的堆棧棧頂TOS（TOP-OF-STACK），對UCOS和絕大多數可剝奪型內核來說，
    每個任務都有各自的堆棧空間，在UCOS中每個任務的堆棧容量可以單獨指定，在這個范例中，為了簡化起見，都定義成
    了相同的容量  在80x86處理器上，堆棧是從高地址向低地址遞減的，所以必須把堆棧的高地址TOS傳遞給OSTaskCreate()
    函數。在這個范例中，堆棧空間被定義為TaskStarStk[]，并在編譯時確定。堆棧必須定義為OS_STK變量類型 如果移植
    在x86上的話 因為x86上OS_STK為16位變量所以堆棧的大小為512*16%8B  1024B 最后的參數指定了建立的任務的優先級。
    這個參數值越小，任務的優先級越高（這一點非常重要哦）前文提到UCOS允許建立多達63個用戶任務。必須給這些任務
    分配 不同的優先級。0是最高的優先級。
    睡眠態:task dormant指的是任務駐留在程序空間ROM或者RAM。還沒有由UCOS來管理。把任務交給UCOS，是通過調用下述兩個
    函數之一OSTaskCreate或OSTaskCreateExt實現的。這些調用只是用于告訴UCOS，任務的其實地址在哪里；任務建立時，用
    戶給任務賦予的優先級是多少；任務要使用多少棧空間等等*/
    OSStart();/* 調用OSStart()，將控制權交給UCOS內核，開始運行多任務。在啟動多任務OSStart()之前，至少要先建立一
    個任務。否則應用程序就會崩潰。實際上，如果希望計算CPU的利用率時，也須先建立一個任務這個函數的作用是最重要的