<< Previous | Index | Next >>

> ## 5. Multitasking with Dynamic C

> In a multitasking environment, more than one task (each representing a sequence of operations) can appear to execute in parallel. In reality, a single processor can only execute one instruction at a time. If an application has multiple tasks to perform, multitasking software can usually take advantage of natural delays in each task to increase the overall performance of the system. Each task can do some of its work while the other tasks are waiting for an event, or for something to do. In this way, the tasks execute almost in parallel.

> There are two types of multitasking available for developing applications in Dynamic C: preemptive and cooperative. In a cooperative multitasking environment, each well-behaved task voluntarily gives up control when it is waiting, allowing other tasks to execute. Dynamic C has language extensions, costatements and cofunctions, to support cooperative multitasking.

> Preemptive multitasking is supported by the slice statement, which allows a computation to be divided into small slices of a few milliseconds each, and by the µC/OS-II real-time kernel.

> ### 5.1 Cooperative Multitasking

> In the absence of a preemptive multitasking kernel or operating system, a programmer given a real-time programming problem that involves running separate tasks on different time scales will often come up with a solution that can be described as a big loop driving state machines.

> Figure 5-1 Big Loop

> Within this endless loop, tasks are accomplished by small fragments of a program that cycle through a series of states. The state is typically encoded as numerical values in C variables.

> State machines can become quite complicated, involving a large number of state variables and a large number of states. The advantage of the state machine is that it avoids busy waiting, which is waiting in a loop until a condition is satisfied. In this way, one big loop can service a large number of state machines, each performing its own task, and no one is busy waiting.

> The cooperative multitasking language extensions added to Dynamic C use the big loop and state machine concept, but C code is used to implement the state machine rather than C variables. The state of a task is remembered by a statement pointer that records the place where execution of the block of statements has been paused to wait for an event.

> To multitask using Dynamic C language extensions, most application programs will have some flavor of this simple structure:

>     main() {
>        int i;
>        while(1) {       // endless loop for multitasking framework
>           costate {     // task 1
>              . . .      // body of costatement
>           }
>           costate {     // task 2
>              ...        // body of costatement
>           }
>        }
>     }

> ### 5.2 A Real-Time Problem

> The following sequence of events is common in real-time programming.

> Start:

> 1. Wait for a pushbutton to be pressed.
> 2. Turn on the first device.
> 3. Wait 60 seconds.
> 4. Turn on the second device.
> 5. Wait 60 seconds.
> 6. Turn off both devices.
> 7. Go back to the start.

> The most rudimentary way to perform this function is to idle ("busy wait") in a tight loop at each of the steps where waiting is specified. But most of the computer time will used waiting for the task, leaving no execution time for other tasks.

> #### 5.2.1 Solving the Real-Time Problem with a State Machine

> Here is what a state machine solution might look like.

>     task1state = 1;                  // initialization:
>     while(1){
>        switch(task1state){

>           case 1:
>              if( buttonpushed() ){
>                 task1state=2;   turnondevice1();
>                 timer1 = time;        // time incremented every second
>              }
>              break;

>           case 2:
>              if( (time-timer1) >= 60L){
>                 task1state=3;   turnondevice2();
>                 timer2=time;
>              }
>              break;

>           case 3:
>              if( (time-timer2) >= 60L){
>                 task1state=1;   turnoffdevice1();
>                 turnoffdevice2();
>              }
>              break;
>        }
>        /* other tasks or state machines */
>     }

> If there are other tasks to be run, this control problem can be solved better by creating a loop that processes a number of tasks. Now each task can relinquish control when it is waiting, thereby allowing other tasks to proceed. Each task then does its work in the idle time of the other tasks.

> ### 5.3 Costatements

> Costatements are Dynamic C extensions to the C language which simplify implementation of state machines. Costatements are cooperative because their execution can be voluntarily suspended and later resumed. The body of a costatement is an ordered list of operations to perform -- a task. Each costatement has its own statement pointer to keep track of which item on the list will be performed when the costatement is given a chance to run. As part of the startup initialization, the pointer is set to point to the first statement of the costatement.

> The statement pointer is effectively a state variable for the costatement or cofunction. It specifies the statement where execution is to begin when the program execution thread hits the start of the costatement.

> All costatements in the program, except those that use pointers as their names, are initialized when the function chain `_GLOBAL_INIT` is called. `_GLOBAL_INIT` is called automatically by `premain` before `main` is called. Calling `_GLOBAL_INIT` from an application program will cause reinitialization of anything that was initialized in the call made by `premain`.

> #### 5.3.1 Solving the Real-Time Problem with Costatements

> The Dynamic C costatement provides an easier way to control the tasks. It is relatively easy to add a task that checks for the use of an emergency stop button and then behaves accordingly.

>     while(1){
>        costate{ ... }                                                  // task 1

>        costate{                                                      // task 2
>           waitfor( buttonpushed() );
>           turnondevice1();
>           waitfor( DelaySec(60L) );
>           turnondevice2();
>           waitfor( DelaySec(60L) );
>           turnoffdevice1();
>           turnoffdevice2();
>        }

>        costate{ ... }                                                  // task n
>     }

> The solution is elegant and simple. Note that the second costatement looks much like the original description of the problem. All the branching, nesting and variables within the task are hidden in the implementation of the costatement and its `waitfor` statements.

> #### 5.3.2 Costatement Syntax

> The keyword `costate` identifies the statements enclosed in the curly braces that follow as a costatement.

>     costate [ name [state] ] { [ statement | yield; | abort; |
>     waitfor( expression ); ] . . .}

> `name` can be one of the following:

> - A valid C name not previously used. This results in the creation of a structure of type `CoData` of the same name.

> - The name of a local or global `CoData` structure that has already been defined

> - A pointer to an existing structure of type `CoData`

> Costatements can be named or unnamed. If `name` is absent the compiler creates an unnamed structure of type `CoData` for the costatement.

> `state` can be one of the following:

> - `always_on`

>   The costatement is always active. This means the costatement will execute every time it is encountered in the execution thread, unless it is made inactive by `CoPause()`. It may be made active again by `CoResume()`.

> - `init_on`

>   The costatement is initially active and will automatically execute the first time it is encountered in the execution thread. The costatement becomes inactive after it completes (or aborts). The costatement can be made inactive by `CoPause()`.

> If `state` is absent, a named costatement is initialized in a paused `init_on` condition. This means that the costatement will not execute until `CoBegin()` or `CoResume()` is executed. It will then execute once and become inactive again.

> Unnamed costatements are `always_on`. You cannot specify `init_on` without specifying a costatement name.

> #### 5.3.3 Control Statements

> This section describes the control statements identified by the keywords: waitfor, yield and abort.

> #### waitfor ( expression );

> The keyword `waitfor` indicates a special `waitfor` statement and not a function call. Each time `waitfor` is executed, expression is evaluated. If true (non-zero), execution proceeds to the next statement; otherwise a jump is made to the closing brace of the costatement or cofunction, with the statement pointer continuing to point to the `waitfor` statement. Any valid C function that returns a value can be used in a `waitfor` statement.

> Figure 5-2 shows the execution thread through a costatement when a `waitfor` evaluates to false. The diagram on the left side shows which statements are executed the first time through the costatement. The diagram on the right shows that when the execution thread again reaches the costatement the only statement executed is the `waitfor`. As long as the `waitfor` continues to evaluate to false, it will be the only statement executed within the costatement.

> Figure 5-2 Execution thread when waitfor evaluates to false``

> Figure 5-3 shows the execution thread through a costatement when a `waitfor` evaluates to true.

> Figure 5-3 Execution thread when waitfor evaluates to true

> #### yield

> The `yield` statement makes an unconditional exit from a costatement or a cofunction. Execution continues at the statement following `yield` the next time the costatement or cofunction is encountered by the execution thread.

> Figure 5-4 Execution thread with yield statement

> #### abort

> The `abort` statement causes the costatement or cofunction to terminate execution. If a costatement is `always_on`, the next time the program reaches it, it will restart from the top. If the costatement is not `always_on`, it becomes inactive and will not execute again until turned on by some other software.

> Figure 5-5 Execution thread with abort statement

> A costatement can have as many C statements, including `abort`, `yield`, and `waitfor` statements, as needed. Costatements can be nested.

> ### 5.4 Advanced Costatement Topics

> Each costatement has a structure of type `CoData`. This structure contains state and timing information. It also contains the address inside the costatement that will execute the next time the program thread reaches the costatement. A value of zero in the address location indicates the beginning of the costatement.

> #### 5.4.1 The CoData Structure

>     typedef struct {
>        char CSState;
>        unsigned int lastlocADDR;
>        char lastlocCBR;
>        char ChkSum;
>        char firsttime;
>        union{
>           unsigned long ul;
>           struct {
>              unsigned int u1;
>              unsigned int u2;
>           } us;
>        } content;
>        char ChkSum2;
>     } CoData;

> #### 5.4.2 CoData Fields

> This section describes the fields of the CoData structure.

> #### CSState

> The `CSState` field contains two flags, `STOPPED` and `INIT`. The possible flag values and their meaning are in the table below.

> Table 5-1. Flags that Specify the Run Status of a Costatement
> STOPPED | INIT | State of Costatement
> yes | yes | Done, or has been initialized to run, but set to inactive. Set by `CoReset()`.
> yes | no | Paused, waiting to resume. Set by `CoPause()`.
> no | yes | Initialized to run. Set by `CoBegin()`.
> no | no | Running. `CoResume()` will return the flags to this state.

> The function `isCoDone()` returns true (1) if both the `STOPPED` and `INIT` flags are set. The function `isCoRunning()` returns true (1) if the `STOPPED` flag is not set.

> The `CSState` field applies only if the costatement has a name. The `CSState` flag has no meaning for unnamed costatements or cofunctions.

> #### Last Location

> The two fields `lastlocADDR` and `lastlocCBR` represent the 24-bit address of the location at which to resume execution of the costatement. If `lastlocADDR` is zero (as it is when initialized), the costatement executes from the beginning, subject to the `CSState` flag. If `lastlocADDR` is nonzero, the costatement resumes at the 24-bit address represented by `lastlocADDR` and `lastlocCBR`.

> These fields are zeroed whenever one of the following is true:

> - the `CoData` structure is initialized by a call to _`GLOBAL_INIT`, `CoBegin` or `CoReset`

> - the costatement is executed to completion

> - the costatement is aborted.

> #### Check Sum

> The `ChkSum` field is a one-byte check sum of the address. (It is the exclusive-or result of the bytes in `lastlocADDR` and `lastlocCBR`.) If `ChkSum` is not consistent with the address, the program will generate a run-time error and reset. The check sum is maintained automatically. It is initialized by `_GLOBAL_INIT`, `CoBegin` and `CoReset`.

> #### First Time

> The `firsttime` field is a flag that is used by a `waitfor`, or `waitfordone` statement. It is set to 1 before the statement is evaluated the first time. This aids in calculating elapsed time for the functions `DelayMs`, `DelaySec`, `DelayTicks`, `IntervalTick`, `IntervalMs`, and `IntervalSec`.

> #### Content

> The `content` field (a union) is used by the costatement or cofunction delay routines to store a delay count.

> #### Check Sum 2

> The `ChkSum2` field is currently unused.

> #### 5.4.3 Pointer to CoData Structure

> To obtain a pointer to a named costatement's CoData structure, do the following:

>     static CoData   cost1;         // allocate memory for a CoData struct
>     static CoData    *pcost1;

>     pcost1 = &cost1;               // get pointer to the CoData struct
>     ...
>     CoBegin (pcost1);              // initialize CoData struct
>     costate pcost1 {               // pcost1 is the costatement name and also a
>        ...                         //   pointer to its CoData structure.
>     }

> The storage class of a named CoData structure must be `static`.

> #### 5.4.4 Functions for Use With Named Costatements

> For detailed function descriptions, please see the Dynamic C Function Reference Manual or select Function Lookup/Insert from Dynamic C's Help menu (keyboard shortcut is <Ctrl-H>).

> All of these functions are in `COSTATE.LIB`. Each one takes a pointer to a `CoData` struct as its only parameter.

> #### int isCoDone(CoData* p);

> This function returns true if the costatement pointed to by `p` has completed.

> #### int isCoRunning(CoData* p);

> This function returns true if the costatement pointed to by `p` will run if given a continuation call.

> #### void CoBegin(CoData* p);

> This function initializes a costatement's `CoData` structure so that the costatement will be executed next time it is encountered.

> #### void CoPause(CoData* p);

> This function will change `CoData` so that the associated costatement is paused. When a costatement is called in this state it does an implicit yield until it is released by a call from `CoResume` or `CoBegin`.

> #### void CoReset(CoData* p);

> This function initializes a costatement's CoData structure so that the costatement will not be executed the next time it is encountered unless the costatement is declared `always_on`.

> #### void CoResume(CoData* p);

> This function unpauses a paused costatement. The costatement resumes the next time it is called.

> #### 5.4.5 Firsttime Functions

> In a function definition, the keyword `firsttime` causes the function to have an implicit first parameter: a pointer to the CoData structure of the costatement that calls it. User-defined `firsttime` functions are allowed.

> The following `firsttime` functions are defined in `COSTATE.LIB`.

> `DelayMs(), DelaySec(), DelayTicks()
> IntervalMs(), IntervalSec(), IntervalTick()`

> For more information see the Dynamic C Function Reference Manual. These functions should be called inside a `waitfor` statement because they do not yield while waiting for the desired time to elapse, but instead return 0 to indicate that the desired time has not yet elapsed.

> #### 5.4.6 Shared Global Variables

> The variables `SEC_TIMER`, `MS_TIMER` and `TICK_TIMER` are shared, making them atomic when being updated. They are defined and initialized in `VDRIVER.LIB`. They are updated by the periodic interrupt and are used by `firsttime` functions. They should not be modified by an application program. Costatements and cofunctions depend on these timer variables being valid for use in `waitfor` statements that call functions that read them. For example, the following statement will access `SEC_TIMER`.

>     waitfor(DelaySec(3));

> ### 5.5 Cofunctions

> Cofunctions, like costatements, are used to implement cooperative multitasking. But, unlike costatements, they have a form similar to functions in that arguments can be passed to them and a value can be returned (but not a structure).

> The default storage class for a cofunction's variables is `Instance`. An `instance` variable behaves like a `static` variable, i.e., its value persists between function calls. Each instance of an Indexed Cofunction has its own set of instance variables. The compiler directive `#class` does not change the default storage class for a cofunction's variables.

> All cofunctions in the program are initialized when the function chain `_GLOBAL_INIT` is called. This call is made by `premain`.

> #### 5.5.1 Cofunction Syntax

> A cofunction definition is similar to the definition of a C function.

>     cofunc|scofunc type [name][[dim]]([type arg1, ..., type argN])
>      { [ statement | yield; | abort; | waitfor(expression);]... }

> #### cofunc, scofunc

> The keywords `cofunc` or `scofunc` (a single-user cofunction) identify the statements enclosed in curly braces that follow as a cofunction.

> #### type

> Whichever keyword (`cofunc` or `scofunc`)`` is used is followed by the data type returned (`void`, `int`, etc.).

> #### name

> A `name` can be any valid C name not previously used. This results in the creation of a structure of type `CoData` of the same name.

> #### dim

> The cofunction `name` may be followed by a dimension if an indexed cofunction is being defined.

> #### cofunction arguments (arg1, . . ., argN)

> As with other Dynamic C functions, cofunction arguments are passed by value.

> #### cofunction body

> A cofunction can have as many C statements, including `abort`, `yield`, `waitfor`, and `waitfordone` statements, as needed. Cofunctions can contain calls to other cofunctions.

> #### 5.5.2 Calling Restrictions

> You cannot assign a cofunction to a function pointer then call it via the pointer.

> Cofunctions are called using a `waitfordone` statement. Cofunctions and the `waitfordone` statement may return an argument value as in the following example.

>     int j,k,x,y,z;
>     j = waitfordone x = Cofunc1;
>     k = waitfordone{ y=Cofunc2(...); z=Cofunc3(...); }

> The keyword `waitfordone` (can be abbreviated to the keyword `wfd`) must be inside a costatement or cofunction. Since a cofunction must be called from inside a `wfd` statement, ultimately a `wfd` statement must be inside a costatement. If only one cofunction is being called by `wfd` the curly braces are not needed.

> The `wfd` statement executes cofunctions and `firsttime` functions. When all the cofunctions and `firsttime` functions listed in the `wfd` statement are complete (or one of them aborts), execution proceeds to the statement following `wfd`. Otherwise a jump is made to the ending brace of the costatement or cofunction where the `wfd` statement appears and when the execution thread comes around again control is given back to `wfd`.

> In the example above, `x`, `y` and `z` must be set by `return` statements inside the called cofunctions. Executing a return statement in a cofunction has the same effect as executing the end brace. In the example above, the variable `k` is a status variable that is set according to the following scheme. If no abort has taken place in any cofunction, `k` is set to 1, 2, ..., n to indicate which cofunction inside the braces finished executing last. If an abort takes place, `k` is set to -1, -2, ..., -n to indicate which cofunction caused the abort.

> ##### 5.5.2.1 Costate Within a Cofunc

> In all but trivial cases (where the costate is really not necessary), a costate within a cofunc causes execution problems ranging from never completing the cofunc to unexpected interrupts or target lockups. To avoid these problems, do not introduce costates with nested wfd cofuncs into a cofunc. If you find yourself coding such a thing, consider these alternatives:

> 1. Intermediate regular functions can be used between the cofuncs to isolate them.

> 2. A regular `waitfor(function)` can be substituted for the top level costate's `wfd` cofunction.

> 3. The nested costates with wfd cofuncs can be moved up into the body of the calling function, replacing the top-level costate with the wfd cofunc.

> A compiler error will be generated if a costate is found within a cofunction.

> ##### 5.5.2.2 Using the IX Register

> Functions called from within a cofunction may use the IX register if they restore it before the cofunction is exited, which includes an exit via an incomplete `waitfordone` statement.

> In the case of an application that uses the #useix directive, the IX register will be corrupted when any stack-variable using function is called from within a cofunction, or if a stack-variable using function contains a call to a cofunction.

> #### 5.5.3 CoData Structure

> The CoData structure discussed in Section 5.4.1 applies to cofunctions; each cofunction has an associated CoData structure.

> #### 5.5.4 Firsttime Functions

> The `firsttime` functions discussed in Firsttime Functions can also be used inside cofunctions. They should be called inside a `waitfor` statement. If you call these functions from inside a `wfd` statement, no compiler error is generated, but, since these delay functions do not yield while waiting for the desired time to elapse, but instead return 0 to indicate that the desired time has not yet elapsed, the `wfd` statement will consider a return value to be completion of the `firsttime` function and control will pass to the statement following the `wfd`.

> #### 5.5.5 Types of Cofunctions

> There are three types of cofunctions: simple, indexed and single-user. Which one to use depends on the problem that is being solved. A single-user, indexed cofunction is not valid.

> ##### 5.5.5.1 Simple Cofunction

> A simple cofunction has only one instance and is similar to a regular function with a costate taking up most of the function's body.

> ##### 5.5.5.2 Indexed Cofunction

> An indexed cofunction allows the body of a cofunction to be called more than once with different parameters and local variables. The parameters and the local variable that are not declared static have a special lifetime that begins at a first time call of a cofunction instance and ends when the last curly brace of the cofunction is reached or when an `abort` or `return` is encountered.

> The indexed cofunction call is a cross between an array access and a normal function call, where the array access selects the specific instance to be run.

> Typically this type of cofunction is used in a situation where N identical units need to be controlled by the same algorithm. For example, a program to control the door latches in a building could use indexed cofunctions. The same cofunction code would read the key pad at each door, compare the passcode to the approved list, and operate the door latch. If there are 25 doors in the building, then the indexed cofunction would use an index ranging from 0 to 24 to keep track of which door is currently being tested. An indexed cofunction has an index similar to an array index.

>     waitfordone{ ICofunc[n](...); ICofunc2[m](...); }

> The value between the square brackets must be positive and less than the maximum number of instances for that cofunction. There is no runtime checking on the instance selected, so, like arrays, the programmer is responsible for keeping this value in the proper range.

> ##### 5.5.5.2.1 Indexed Cofunction Restrictions

> Costatements are not supported inside indexed cofunctions. Single user cofunctions can not be indexed.

> ##### 5.5.5.3 Single User Cofunction

> Since cofunctions are executing in parallel, the same cofunction normally cannot be called at the same time from two places in the same big loop. For example, the following statement containing two simple cofunctions will generally cause a fatal error.

>     waitfordone{ cofunc_nameA(); cofunc_nameA();}

> This is because the same cofunction is being called from the second location after it has already started, but not completed, execution for the call from the first location. The cofunction is a state machine and it has an internal statement pointer that cannot point to two statements at the same time.

> Single-user cofunctions can be used instead. They can be called simultaneously because the second and additional callers are made to wait until the first call completes. The following statement, which contains two calls to single-user cofunction, is okay.

>     waitfordone( scofunc_nameA(); scofunc_nameA();}

> #### loopinit()

> This function should be called in the beginning of a program that uses single-user cofunctions. It initializes internal data structures that are used by `loophead().`

> #### loophead()

> This function should be called within the "big loop" in your program. It is necessary for proper single-user cofunction abandonment handling.

> #### Example

>     // echoes characters
>     main() {
>        int c;
>        serAopen(19200);
>        loopinit();
>        while (1) {
>           loophead();
>           costate {
>              wfd c = cof_serAgetc();
>              wfd cof_serAputc(c);
>           }
>        }
>        serAclose();
>     }

> #### 5.5.6 Types of Cofunction Calls

> A `wfd` statement makes one of three types of calls to a cofunction.

> ##### 5.5.6.1 First Time Call

> A first time call happens when a `wfd` statement calls a cofunction for the first time in that statement. After the first time, only the original `wfd` statement can give this cofunction instance continuation calls until either the instance is complete or until the instance is given another first time call from a different statement. The lifetime of a cofunction instance stretches from a first time call until its terminal call or until its next first time call.

> ##### 5.5.6.2 Continuation Call

> A continuation call is when a cofunction that has previously yielded is given another chance to run by the enclosing `wfd` statement. These statements can only call the cofunction if it was the last statement to give the cofunction a first time call or a continuation call.

> ##### 5.5.6.3 Terminal Call

> A terminal call ends with a cofunction returning to its `wfd` statement without yielding to another cofunction. This can happen when it reaches the end of the cofunction and does an implicit return, when the cofunction does an explicit return, or when the cofunction aborts.

> #### 5.5.7 Special Code Blocks

> The following special code blocks can appear inside a cofunction.

> #### everytime`` { statements }

> This must be the first statement in the cofunction. The everytime statement block will be executed on every `cofunc` continuation call no matter where the statement pointer is pointing. After the everytime statement block is executed, control will pass to the statement pointed to by the cofunction's statement pointer.

> The everytime statement block will not be executed during the initial `cofunc` entry call.

> #### abandon { statements }

> This keyword applies to single-user cofunctions only and must be the first statement in the body of the cofunction. The statements inside the curly braces will be executed if the single-user cofunction is forcibly abandoned. A call to `loophead()` (defined in `COFUNC.LIB`) is necessary for abandon statements to execute.

> #### Example

> `Samples/COFUNC/` `COFABAND`.`C` illustrates the use of `abandon`.

>     scofunc SCofTest(int i){
>        abandon {
>           printf("CofTest was abandoned\n");
>        }
>        while(i>0) {
>           printf("CofTest(%d)\n",i);
>           yield;
>        }
>     }

>     main(){
>        int x;
>        for(x=0;x<=10;x++) {
>           loophead();
>           if(x<5) {
>              costate {
>                 wfd SCofTest(1);       // first caller
>              }
>           }
>           costate {
>              wfd SCofTest(2);          // second caller
>           }
>        }
>     }

> In this example two tasks in `main()` are requesting access to `SCofTest`. The first request is honored and the second request is held. When `loophead()` notices that the first caller is not being called each time around the loop, it cancels the request, calls the abandonment code and allows the second caller in.

> #### 5.5.8 Solving the Real-Time Problem with Cofunctions

> Cofunctions, with their ability to receive arguments and return values, provide more flexibility and specificity than our previous solutions.

>     for(;;){
>        costate{                            // task 1
>           wfd emergencystop();
>           for (i=0; i<MAX_DEVICES; i++)
>              wfd turnoffdevice(i);
>        }

>        costate{                            // task 2
>           wfd x = buttonpushed();
>           wfd turnondevice(x);
>           waitfor( DelaySec(60L) );
>           wfd turnoffdevice(x);
>        }
>        ...
>        costate{ ... }                       // task n
>     }

> Using cofunctions, new machines can be added with only trivial code changes. Making `buttonpushed()` a cofunction allows more specificity because the value returned can indicate a particular button in an array of buttons. Then that value can be passed as an argument to the cofunctions `turnondevice` and `turnoffdevice`.

> ### 5.6 Patterns of Cooperative Multitasking

> Sometimes a task may be something that has a beginning and an end. For example, a cofunction to transmit a string of characters via the serial port begins when the cofunction is first called, and continues during successive calls as control cycles around the big loop. The end occurs after the last character has been sent and the `waitfordone` condition is satisified. This type of a call to a cofunction might look like this:

>     waitfordone{ SendSerial("string of characters"); }
>     [ next statement ]

> The next statement will execute after the last character is sent.

> Some tasks may not have an end. They are endless loops. For example, a task to control a servo loop may run continuously to regulate the temperature in an oven. If there are a a number of tasks that need to run continuously, then they can be called using a single `waitfordone` statement as shown below.

>     costate {
>        waitfordone { Task1(); Task2(); Task3(); Task4(); }
>        [ to come here is an error ]
>     }

> Each task will receive some execution time and, assuming none of the tasks is completed, they will continue to be called. If one of the cofunctions should abort, then the waitfordone statement will abort, and corrective action can be taken.

> ### 5.7 Timing Considerations

> In most instances, costatements and cofunctions are grouped as periodically executed tasks. They can be part of a real-time task, which executes every n milliseconds as shown below using costatements.

> Figure 5-6 Costatement as Part of Real-Time Task

> If all goes well, the first costatement will be executed at the periodic rate. The second costatement will, however, be delayed by the first costatement. The third will be delayed by the second, and so on. The frequency of the routine and the time it takes to execute comprise the granularity of the routine.

> If the routine executes every 25 milliseconds and the entire group of costatements executes in 5 to 10 milliseconds, then the granularity is 30 to 35 milliseconds. Therefore, the delay between the occurrence of a `waitfor` event and the statement following the `waitfor` can be as much as the granularity, 30 to 35 ms. The routine may also be interrupted by higher priority tasks or interrupt routines, increasing the variation in delay.

> The consequences of such variations in the time between steps depends on the program's objective. Suppose that the typical delay between an event and the controller's response to the event is 25 ms, but under unusual circumstances the delay may reach 50 ms. An occasional slow response may have no consequences whatsoever. If a delay is added between the steps of a process where the time scale is measured in seconds, then the result may be a very slight reduction in throughput.

> If there is a delay between sensing a defective product on a moving belt and activating the reject solenoid that pushes the object into the reject bin, the delay could be serious. If a critical delay cannot exceed 40 ms, then a system will sometimes fail if its worst-case delay is 50 ms.

> #### 5.7.1 waitfor Accuracy Limits

> If an idle loop is used to implement a delay, the processor continues to execute statements almost immediately (within nanoseconds) after the delay has expired. In other words, idle loops give precise delays. Such precision cannot be achieved with `waitfor` delays.

> A particular application may not need very precise delay timing. Suppose the application requires a 60-second delay with only 100 ms of delay accuracy; that is, an actual delay of 60.1 seconds is considered acceptable. Then, if the processor guarantees to check the delay every 50 ms, the delay would be at most 60.05 seconds, and the accuracy requirement is satisfied.

> ### 5.8 Overview of Preemptive Multitasking

> In a preemptive multitasking environment, tasks do not voluntarily relinquish control. Tasks are scheduled to run by priority level and/or by being given a certain amount of time.

> There are two ways to accomplish preemptive multitasking using Dynamic C. The first way is via a Dynamic C construct called the "slice" statement (described in Section 5.9). The second way is µC/OS-II, a real-time, preemptive kernel that runs on the Rabbit microprocessor and is fully supported by Dynamic C (described in Section 5.10).

> ### 5.9 Slice Statements

> The `slice` statement, based on the costatement language construct, allows the programmer to run a block of code for a specific amount of time.

> #### 5.9.1 Slice Syntax

>     slice ([context_buffer,] context_buffer_size, time_slice) [name]{[statement|yield;|abort;|waitfor(expression);]}

> #### context_buffer_size

> This value must evaluate to a constant integer. The value specifies the number of bytes for the buffer `context_buffer`. It needs to be large enough for worst-case stack usage by the user program and interrupt routines.

> #### time_slice

> The amount of time in ticks for the slice to run. One tick = 1/1024 second.

> #### name

> When defining a named `slice` statement, you supply a context buffer as the first argument. When you define an unnamed `slice` statement, this structure is allocated by the compiler.

> #### [statement | yield; | abort; | waitfor(expression);]

> The body of a `slice` statement may contain:

> - Regular C statements

> - `yield` statements to make an unconditional exit.

> - `abort` statements to make an execution jump to the very end of the statement.

> - `waitfor` statements to suspend progress of the slice statement pending some condition indicated by the expression.

> #### 5.9.2 Usage

> The `slice` statement can run both cooperatively and preemptively all in the same framework. A slice statement, like costatements and cofunctions, can suspend its execution with an `abort`, `yield`, or `waitfor`. It can also suspend execution with an implicit `yield` determined by the `time_slice` parameter that was passed to it. A routine called from the periodic interrupt forms the basis for scheduling slice statements. It counts down the ticks and changes the `slice` statement's context.

> #### 5.9.3 Restrictions

> Since a `slice` statement has its own stack, local auto variables and parameters cannot be accessed while in the context of a `slice` statement. Any function called from the slice statement performs normally.

> Only one `slice` statement can be active at any time, which eliminates the possibility of nesting `slice` statements or using a `slice` statement inside a function that is either directly or indirectly called from a `slice` statement. The only methods supported for leaving a `slice` statement are completely executing the last statement in the `slice`, or executing an `abort`, `yield` or `waitfor` statement.

> The `return`, `continue`, `break`, and `goto` statements are not supported.

> Slice statements cannot be used with µC/OS-II or TCP/IP.

> #### 5.9.4 Slice Data Structure

> Internally, the `slice` statement uses two structures to operate. When defining a named `slice` statement, you supply a context buffer as the first argument. When you define an unnamed `slice` statement, this structure is allocated by the compiler. Internally, the context buffer is represented by the `SliceBuffer` structure below.

>     struct SliceData {
>        int time_out;
>        void* my_sp;
>        void* caller_sp;
>        CoData codata;
>     }

>     struct SliceBuffer {
>        SliceData slice_data;
>        char stack[];            // fills rest of the slice buffer
>     };

> #### 5.9.5 Slice Internals

> When a `slice` statement is given control, it saves the current context and switches to a context associated with the `slice` statement. After that, the driving force behind the `slice` statement is the timer interrupt. Each time the timer interrupt is called, it checks to see if a `slice` statement is active. If a `slice` statement is active, the timer interrupt decrements the `time_out` field in the `slice`'s `SliceData`. When the field is decremented to zero, the timer interrupt saves the `slice` statement's context into the `SliceBuffer` and restores the previous context. Once the timer interrupt completes, the flow of control is passed to the statement directly following the `slice` statement. A similar set of events takes place when the `slice` statement does an explicit `yield`/`abort`/`waitfor`.

> ##### 5.9.5.1 Example 1

> Two `slice` statements and a costatement will appear to run in parallel. Each block will run independently, but the `slice` statement blocks will suspend their operation after 20 ticks for `slice_a` and 40 ticks for `slice_b`. Costate a will not release control until it either explicitly yields, aborts, or completes. In contrast, `slice_a` will run for at most 20 ticks, then `slice_b` will begin running. Costate a will get its next opportunity to run about 60 ticks after it relinquishes control.

>     main () {
>        int x, y, z;
>        ...
>        for (;;) {
>           costate a {
>              ...
>           }
>           slice(500, 20) {     // slice_a
>              ...
>           }
>           slice(500, 40) {     // slice_b
>              ...
>           }
>        }
>     }

> ##### 5.9.5.2 Example 2

> This code guarantees that the first slice starts on `TICK_TIMER` evenly divisible by 80 and the second starts on `TICK_TIMER` evenly divisible by 105.

>     main() {
>        for(;;) {
>           costate {
>              slice(500,20) {                // slice_a
>                 waitfor(IntervalTick(80));
>                 ...
>              }
>              slice(500,50) {                // slice_b
>                 waitfor(IntervalTick(105);
>                 ...
>              }
>           }
>        }
>     }

> ##### 5.9.5.3 Example 3

> This approach is more complicated, but will allow you to spend the idle time doing a low-priority background task.

>     main() {
>        int time_left;
>        long start_time;
>        for(;;) {
>           start_time = TICK_TIMER;
>           slice(500,20) {                             // slice_a
>              waitfor(IntervalTick(80));
>                 ...
>           }
>           slice(500,50) {                             // slice_b
>              waitfor(IntervalTick(105));
>                 ...
>           }
>           time_left = 75-(TICK_TIMER-start_time);
>           if(time_left>0) {
>              slice(500,75-(TICK_TIMER-start_time)) {  // slice_c
>                 ...
>              }
>           }
>        }

>     }

> ### 5.10 µC/OS-II

> µC/OS-II is a simple, clean, efficient, easy-to-use real-time operating system that runs on the Rabbit microprocessor and is fully supported by the Dynamic C development environment. With Dynamic C, there is no fee to pay for the "Object Code Distribution License" that is usually required for embedding µC/OS-II in a product.

> µC/OS-II is capable of intertask communication and synchronization via the use of semaphores, mailboxes, and queues. User-definable system hooks are supplied for added system and configuration control during task creation, task deletion, context switches, and time ticks.

> For more information on µC/OS-II, please refer to Jean J. Labrosse's book, MicroC/OS-II, The Real-Time Kernel (ISBN: 0-87930-543-6). The data structures (e.g., Event Control Block) referenced in the Dynamic C µC/OS-II function descriptions are fully explained in Labrosse's book. It can be purchased at the Rabbit store, www.rabbit.com/store/, or at http://www.ucos-ii.com/.

> The Dynamic C version of µC/OS-II has the new features and API changes available in version 2.51 of µC/OS-II. The documentation for these changes will be in the `/Samples/UCos-II` directory. The file `Newv251.pdf` contains all of the features added since version 2.00 and `Relv251.pdf` contains release notes for version 2.51.

> The remainder of this section discusses the following:

> - Dynamic C enhancements to µC/OS-II

> - Tasking aware ISRs

> - Dynamic C library reentrancy

> - How to get a µC/OS-II application running

> - TCP/IP compatibility

> - API function descriptions

> - Debugging tips

> #### 5.10.1 Changes to µC/OS-II

> Minor changes have been made to µC/OS-II to take full advantage of services provided by Dynamic C.

> #### 5.10.1.1 Ticks per Second

> In most implementations of µC/OS-II, `OS_TICKS_PER_SEC` informs the operating system of the rate at which `OSTimeTick` is called; this macro is used as a constant to match the rate of the periodic interrupt. In µC/OS-II for the Rabbit, however, changing this macro will change the tick rate of the operating system set up during `OSInit`. Usually, a real-time operating system has a tick rate of 10 Hz to 100 Hz, or 10-100 ticks per second. Since the periodic interrupt on the Rabbit occurs at a rate of 2 kHz, it is recommended that the tick rate be a power of 2 (e.g., 16, 32, or 64). Keep in mind that the higher the tick rate, the more overhead the system will incur.

> In the Rabbit version of µC/OS-II, the number of ticks per second defaults to 64. The actual number of ticks per second may be slightly different than the desired ticks per second if `TicksPerSec` does not evenly divide 2048.

> Changing the default tick rate is done by simply defining `OS_TICKS_PER_SEC` to the desired tick rate before calling `OSInit()`. For example, to change the tick rate to 32 ticks per second:

>     #define OS_TICKS_PER_SEC 32
>     ...
>     OSInit();
>     ...
>     OSStart();

> #### 5.10.1.2 Task Creation

> In a µC/OS-II application, stacks are declared as static arrays, and the address of either the top or bottom (depending on the CPU) of the stack is passed to `OSTaskCreate`. In a Rabbit-based system, the Dynamic C development environment provides a superior stack allocation mechanism that µC/OS-II incorporates. Rather than declaring stacks as static arrays, the number of stacks of particular sizes are declared, and when a task is created using either `OSTaskCreate` or `OSTaskCreateExt,` only the size of the stack is passed, not the memory address. This mechanism allows a large number of stacks to be defined without using up root RAM.

> There are five macros located in `ucos2.lib` that define the number of stacks needed of five different sizes. To have three 256-byte stacks, one 512-byte stack, two 1024-byte stacks, one 2048-byte stack, and no 4096-byte stacks, the following macro definitions would be used:

>     #define STACK_CNT_256      3    // number of 256 byte stacks
>     #define STACK_CNT_512      1    // number of 512 byte stacks
>     #define STACK_CNT_1K       2    // number of 1K stacks
>     #define STACK_CNT_2K       1    // number of 2K stacks
>     #define STACK_CNT_4K       0    // number of 4K stacks

> These macros can be placed into each µC/OS-II application so that the number of each size stack can be customized based on the needs of the application. Suppose that an application needs 5 tasks, and each task has a consecutively larger stack. The macros and calls to `OSTaskCreate` would look as follows

>     #define STACK_CNT_256     2     // number of 256 byte stacks
>     #define STACK_CNT_512     2     // number of 512 byte stacks
>     #define STACK_CNT_1K      1     // number of 1K stacks
>     #define STACK_CNT_2K      1     // number of 2K stacks
>     #define STACK_CNT_4K      1     // number of 4K stacks

>     OSTaskCreate(task1, NULL, 256, 0);
>     OSTaskCreate(task2, NULL, 512, 1);
>     OSTaskCreate(task3, NULL, 1024, 2);
>     OSTaskCreate(task4, NULL, 2048, 3);
>     OSTaskCreate(task5, NULL, 4096, 4);

> Note that `STACK_CNT_256` is set to 2 instead of 1. µC/OS-II always creates an idle task which runs when no other tasks are in the ready state. Note also that there are two 512 byte stacks instead of one. This is because the program is given a 512 byte stack. If the application utilizes the µC/OS-II statistics task, then the number of 512 byte stacks would have to be set to 3. (Statistic task creation can be enabled and disabled via the macro `OS_TASK_STAT_EN` which is located in `ucos2.lib`). If only 6 stacks were declared, one of the calls to `OSTaskCreate` would fail.

> If an application uses `OSTaskCreateExt`, which enables stack checking and allows an extension of the Task Control Block, fewer parameters are needed in the Rabbit version of µC/OS-II. Using the macros in the example above, the tasks would be created as follows:

>     OSTaskCreateExt(task1, NULL, 0, 0, 256, NULL, OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR);

>     OSTaskCreateExt(task2, NULL, 1, 1, 512, NULL, OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR);

>     OSTaskCreateExt(task3, NULL, 2, 2, 1024, NULL, OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR);

>     OSTaskCreateExt(task4, NULL, 3, 3, 2048, NULL, OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR);

>     OSTaskCreateExt(task5, NULL, 4, 4, 4096, NULL, OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR);

> #### 5.10.1.3 Restrictions

> At the time of this writing, µC/OS-II for Dynamic C is not compatible with the use of slice statements. Also, see the function description for `OSTimeTickHook()` for important information about preserving registers if that stub function is replaced by a user-defined function.

> Due to Dynamic C's stack allocation scheme, special care should be used when posting messages to either a mailbox or a queue. A message is simply a void pointer, allowing the application to determine its meaning. Since tasks can have their stacks in different segments, auto pointers declared on the stack of the task posting the message should not be used since the pointer may be invalid in another task with a different stack segment.

> #### 5.10.2 Tasking Aware Interrupt Service Routines (TA-ISR)

> Special care must be taken when writing an interrupt service routine (ISR) that will be used in conjunction with µC/OS-II so that µC/OS-II scheduling will be performed at the proper time.

> #### 5.10.2.1 Interrupt Priority Levels

> µC/OS-II for the Rabbit reserves interrupt priority levels 2 and 3 for interrupts outside of the kernel. Since the kernel is unaware of interrupts above priority level 1, interrupt service routines for interrupts that occur at interrupt priority levels 2 and 3 should not be written to be tasking aware. Also, a µC/OS-II application should only disable interrupts by setting the interrupt priority level to 1, and should never raise the interrupt priority level above 1.

> #### 5.10.2.2 Possible ISR Scenarios

> There are several different scenarios that must be considered when writing an ISR for use with µC/OS-II. Depending on the use of the ISR, it may or may not have to be written so that it is tasking aware. Consider the scenario in Figure 5-7. In this situation, the ISR for Interrupt X does not have to be tasking aware since it does not re-enable interrupts before completion and it does not post to a semaphore, mailbox, or queue.

> Figure 5-7 Type 1 ISR

> If, however, an ISR needs to signal a task to the ready state, then the ISR must be tasking aware. In the example in Figure 5-8, the TA-ISR increments the interrupt nesting counter, does the work necessary for the ISR, readies a higher priority task, decrements the nesting count, and returns to the higher priority task.

> Figure 5-8 Type 2 ISR

> It may seem as though the ISR in Figure 5-8 does not have to increment and decrement the nesting count. However, this is very important. If the ISR for Interrupt X is called during an ISR that re-enables interrupts before completion, scheduling should not be performed when Interrupt X completes; scheduling should instead be deferred until the least nested ISR completes. Figure 5-9 shows an example of this situation.

> Figure 5-9 Type 2 ISR Nested Inside Type 3 ISR

> As can be seen here, although the ISR for interrupt Z does not signal any tasks by posting to a semaphore, mailbox, or queue, it must increment and decrement the interrupt nesting count since it re-enables interrupts (`ipres`) prior to finishing all of its work.

> #### 5.10.2.3 General Layout of a TA-ISR

> A TA-ISR is just like a standard ISR except that it does some extra checking and house-keeping. The following table summarizes when to use a TA-ISR.

> Table 5-2. Use of TA-ISR
> | µC/OS-II Application
> | Type 11 | Type 22 | Type 33
> TA-ISR Required? | No | Yes | Yes

> 1 Type 1--Leaves interrupts disabled and does not signal task to ready state 2 Type 2--Leaves interrupts disabled and signals task to ready state 3 Type 3--Reenables interrupts before completion

> Figure 5-10 shows the logical flow of a TA-ISR.

> Figure 5-10 Logical Flow of a TA-ISR

> ##### 5.10.2.3.1 Sample Code for a TA-ISR

> Fortunately, the Rabbit BIOS and libraries provide all of the necessary flags to make TA-ISRs work. With the code found in Listing 1, minimal work is needed to make a TA-ISR function correctly with µC/OS-II. TA-ISRs allow µC/OS-II the ability to have ISRs that communicate with tasks as well as the ability to let ISRs nest, thereby reducing interrupt latency.

> Just like a standard ISR, the first thing a TA-ISR does is to save the registers that it is going to use (1). Once the registers are saved, the interrupt source is cleared (2) and the nesting counter is incremented (3). Note that `bios_intnesting` is a global interrupt nesting counter provided in the Dynamic C libraries specifically for tracking the interrupt nesting level. If an `ipres` instruction is executed (4) other interrupts can occur before this ISR is completed, making it necessary for this ISR to be a TA-ISR.

> If it is possible for the ISR to execute before µC/OS-II has been fully initialized and started multi-tasking, a check should be made (5) to insure that µC/OS-II is in a known state, especially if the TA-ISR signals a task to the ready state (6).

> After the TA-ISR has done its necessary work (which may include making a higher priority task than is currently running ready to run), `OSIntExit` must be called (7). This µC/OS-II function determines the highest priority task ready to run, sets it as the currently running task, and sets the global flag `bios_swpend` if a context switch needs to take place. Interrupts are disabled since a context switch is treated as a critical section (8).

> If the TA-ISR decrements the nesting counter and the count does not go to zero, then the nesting level is saved in `bios_intnesting` (9), the registers used by the TA-ISR are restored, interrupts are re-enabled (if not already done in (4)), and the TA-ISR returns (12). However, if decrementing the nesting counter in (9) causes the counter to become zero, then `bios_swpend` must be checked to see if a context switch needs to occur (10).

> If a context switch is not pending, then the nesting level is set (9) and the TA-ISR exits (12). If a context switch is pending, then the remaining context of the previous task is saved and a long call, which insures that the `xpc` is saved and restored properly, is made to `bios_intexit` (11). `bios_intexit` is responsible for switching to the stack of the task that is now ready to run and executing a long call to switch to the new task. The remainder of (11) is executed when a previously preempted task is allowed to run again.

> ##### Listing 1

> `#asm
> taskaware_isr::
> push af ;push regs needed by isr (1)
> push hl ;clear interrupt source (2)
> ld hl,bios_intnesting ;increase the nesting count (3)
> inc (hl)
> ; ipres (optional) (4)
> ; do processing necessary for interrupt
> ld a,(OSRunning) ;MCOS multitasking yet? (5)
> or a
> jr z,taisr_decnesting` `; possibly signal task to become ready (6)
> call OSIntExit ;sets bios_swpend if higher
> ; prio ready (7)
> ` `taisr_decnesting:
> push ip (8)
> ipset 1` `ld hl,bios_intnesting ; nesting counter == 1?
> dec (hl) (9)
> jr nz,taisr_noswitch` `ld a,(bios_swpend) ; switch pending? (10)
> or a
> jr z,taisr_noswitch` `push de (11)
> push bc
> ex af,af'
> push af
> exx
> push hl
> push de
> push bc
> push iy` `lcall bios_intexit` `pop iy
> pop bc
> pop de
> pop hl
> exx
> pop af
> ex af,af'
> pop bc
> pop de` `taisr_noswitch:
> pop ip` `taisr_done:
> pop hl (12)
> pop af
> ipres
> ret
> #endasm`

> #### 5.10.3 Library Reentrancy

> When writing a µC/OS-II application, it is important to know which Dynamic C library functions are non-reentrant. If a function is non-reentrant, then only one task may access the function at a time, and access to the function should be controlled with a µC/OS-II semaphore. The following is a list of Dynamic C functions that are non-reentrant.

> Table 5-3. Dynamic C Non-Reentrant Functions
> Library | Non-Reentrant Functions
> MATH.LIB | randg, randb, rand
> RS232.LIB | All
> RTCLOCK.LIB | write_rtc, tm_wr
> STDIO.LIB | kbhit, getchar, gets, getswf, selectkey
> STRING.LIB | atof1, atoi1, strtok
> SYS.LIB | clockDoublerOn, clockDoublerOff, useMainOsc, useClockDivider, use32kHzOsc
> VDRIVER.LIB | VdGetFreeWd, VdReleaseWd
> XMEM.LIB | WriteFlash
> JRIO.LIB | digOut, digOn, digOff, jrioInit, anaIn, anaOut, cof_anaIn
> JR485.LIB | All

> 1 reentrant but sets the global `_xtoxErr` flag

> The Dynamic C serial port functions (`RS232.LIB` functions) should be used in a restricted manner with µC/OS-II. Two tasks can use the same port as long as both are not reading, or both are not writing; i.e., one task can read from serial port X and another task can write to serial port X at the same time without conflict.

> #### 5.10.4 How to Get a µC/OS-II Application Running

> µC/OS-II is a highly configureable, real-time operating system. It can be customized using as many or as few of the operating system's features as needed. This section outlines:

> - The configuration constants used in µC/OS-II

> - How to override the default configuration supplied in `UCOS2.LIB`

> - The necessary steps to get an application running

> It is assumed that the reader has a familiarity with µC/OS-II or has a µC/OS-II reference (MicroC/OS-II, The Real-Time Kernel by Jean J. Labrosse is highly recommended).

> #### 5.10.4.1 Default Configuration

> µC/OS-II usually relies on the include file `os_cfg.h` to get values for the configuration constants. In the Dynamic C implementation of µC/OS-II, these constants, along with their default values, are in `os_cfg.lib`. A default stack configuration is also supplied in `os_cfg.lib`. µC/OS-II for the Rabbit uses a more intelligent stack allocation scheme than other µC/OS-II implementations to take better advantage of unused memory.

> The default configuration allows up to 10 normally created application tasks running at 64 ticks per second. Each task has a 512-byte stack. There are 2 queues specified, and 10 events. An event is a queue, mailbox or semaphore. You can define any combination of these three for a total of 10. If you want more than 2 queues, however, you must change the default value of `OS_MAX_QS`.

> Some of the default configuration constants are:

> OS_MAX_EVENTS

> Max number of events (semaphores, queues, mailboxes)
> Default is 10

> OS_MAX_TASKS

> Maximum number of tasks (less stat and idle tasks)
> Default is 10

> OS_MAX_QS

> Max number of queues in system
> Default is 2

> OS_MAX_MEM_PART

> Max number of memory partitions
> Default is 1

> OS_TASK_CREATE_EN

> Enable normal task creation
> Default is 1

> OS_TASK_CREATE_EXT_EN

> Disable extended task creation
> Default is 0

> OS_TASK_DEL_EN

> Disable task deletion
> Default is 0

> OS_TASK_STAT_EN

> Disable statistics task creation
> Default is 0

> OS_Q_EN

> Enable queue usage
> Default is 1

> OS_MEM_EN

> Disable memory manager
> Default is 0

> OS_MBOX_EN

> Enable mailboxes
> Default is 1

> OS_SEM_EN

> Enable semaphores
> Default is 1

> OS_TICKS_PER_SEC

> Number of ticks in one second
> Default is 64

> STACK_CNT_256

> Number of 256 byte stacks (idle task stack)
> Default is 1

> STACK_CNT_512

> Number of 512-byte stacks
> (task stacks + initial program stack)
> Default is `OS_MAX_TASKS`+1 (11)

> If a particular portion of µC/OS-II is disabled, the code for that portion will not be compiled, making the overall size of the operating system smaller. Take advantage of this feature by customizing µC/OS-II based on the needs of each application.

> #### 5.10.4.2 Custom Configuration

> In order to customize µC/OS-II by enabling and disabling components of the operating system, simply redefine the configuration constants as necessary for the application.

>     #define OS_MAX_EVENTS          2
>     #define OS_MAX_TASKS          20
>     #define OS_MAX_QS              1
>     #define OS_MAX_MEM_PART       15
>     #define OS_TASK_STAT_EN        1
>     #define OS_Q_EN                0
>     #define OS_MEM_EN              1
>     #define OS_MBOX_EN             0
>     #define OS_TICKS_PER_SEC      64

> If a custom stack configuration is needed also, define the necessary macros for the counts of the different stack sizes needed by the application.

>     #define STACK_CNT_256 1  // idle task stack
>     #define STACK_CNT_512 2  // initial program + stat task stack
>     #define STACK_CNT_1K 10  // task stacks
>     #define STACK_CNT_2K 10  // number of 2K stacks

> In the application code, follow the µC/OS-II and stack configuration constants with a `#use "ucos2.lib"` statement. This ensures that the definitions supplied outside of the library are used, rather than the defaults in the library.

> This configuration uses 20 tasks, two semaphores, up to 15 memory partitions that the memory manager will control, and makes use of the statistics task. Note that the configuration constants for task creation, task deletion, and semaphores are not defined, as the library defaults will suffice. Also note that ten of the application tasks will each have a 1024 byte stack, ten will each have a 2048 byte stack, and an extra stack is declared for the statistics task.

> #### 5.10.4.3 Examples

> The following sample programs demonstrate the use of the default configuration supplied in `UCOS2.LIB` and a custom configuration which overrides the defaults.

> ##### Example 1

> In this application, ten tasks are created and one semaphore is created. Each task pends on the semaphore, gets a random number, posts to the semaphore, displays its random number, and finally delays itself for three seconds.

> Looking at the code for this short application, there are several things to note. First, since µC/OS-II and slice statements are mutually exclusive (both rely on the periodic interrupt for a "heartbeat"), `#use "ucos2.lib"` must be included in every µC/OS-II application (1). In order for each of the tasks to have access to the random number generator semaphore, it is declared as a global variable (2). In most cases, all mailboxes, queues, and semaphores will be declared with global scope. Next, `OSInit()` must be called before any other µC/OS-II function to ensure that the operating system is properly initialized (3). Before µC/OS-II can begin running, at least one application task must be created. In this application, all tasks are created before the operating system begins running (4). It is perfectly acceptable for tasks to create other tasks. Next, the semaphore each task uses is created (5). Once all of the initialization is done, `OSStart()` is called to start µC/OS-II running (6). In the code that each of the tasks run, it is important to note the variable declarations. Each task runs as an infinite loop and once this application is started, µC/OS-II will run indefinitely.

>     // 1. Explicitly use µC/OS-II library
>     #use "ucos2.lib"

>     void RandomNumberTask(void *pdata);

>     // 2. Declare semaphore global so all tasks have access
>     OS_EVENT* RandomSem;

>     void main(){
>        int i;

>        // 3. Initialize OS internals
>        OSInit();

>        for(i = 0; i < OS_MAX_TASKS; i++)

>           // 4. Create each of the system tasks
>           OSTaskCreate(RandomNumberTask, NULL, 512, i);

>        // 5. semaphore to control access to random number generator
>        RandomSem = OSSemCreate(1);

>        // 6. Begin multitasking
>        OSStart();
>     }

>     void RandomNumberTask(void *pdata)
>     {
>        OS_TCB data;
>        INT8U  err;
>        INT16U RNum;

>        OSTaskQuery(OS_PRIO_SELF, &data);
>        while(1)
>        {
>           // Rand is not reentrant, so access must be controlled via a semaphore.
>           OSSemPend(RandomSem, 0, &err);
>           RNum = (int)(rand() * 100);
>           OSSemPost(RandomSem);
>           printf("Task%d's random #: %d\n",data.OSTCBPrio,RNum);

>           // Wait 3 seconds in order to view output from each task.
>           OSTimeDlySec(3);
>        }
>     }

> ##### Example 2

> This application runs exactly the same code as Example 1, except that each of the tasks are created with 1024-byte stacks. The main difference between the two is the configuration of µC/OS-II.

> First, each configuration constant that differs from the library default is defined. The configuration in this example differs from the default in that it allows only two events (the minimum needed when using only one semaphore), 20 tasks, no queues, no mailboxes, and the system tick rate is set to 32 ticks per second (1). Next, since this application uses tasks with 1024 byte stacks, it is necessary to define the configuration constants differently than the library default (2). Notice that one 512 byte stack is declared. Every Dynamic C program starts with an initial stack, and defining `STACK_CNT_512` is crucial to ensure that the application has a stack to use during initialization and before multi-tasking begins. Finally `ucos2.lib` is explicitly used (3). This ensures that the definitions in (1 and 2) are used rather than the library defaults. The last step in initialization is to set the number of ticks per second via `OSSetTicksPerSec` (4). The rest is identical to example 1 and is explained in the previous section.

>     // 1. Define necessary configuration constants for uC/OS-II
>     #define OS_MAX_EVENTS          2
>     #define OS_MAX_TASKS          20
>     #define OS_MAX_QS              0
>     #define OS_Q_EN                0
>     #define OS_MBOX_EN             0
>     #define OS_TICKS_PER_SEC      32

>     // 2. Define necessary stack configuration constants
>     #define STACK_CNT_512 1              // initial program stack
>     #define STACK_CNT_1K OS_MAX_TASKS    // task stacks

>     // 3. This ensures that the above definitions are used
>     #use "ucos2.lib"

>     void RandomNumberTask(void *pdata);

>     // Declare semaphore global so all tasks have access
>     OS_EVENT* RandomSem;

>     void main(){
>        int i;

>        // Initialize OS internals
>        OSInit();

>        for(i = 0; i < OS_MAX_TASKS; i++){

>           // Create each of the system tasks
>           OSTaskCreate(RandomNumberTask, NULL, 1024, i);

>        }
>        // semaphore to control access to random number generator
>        RandomSem = OSSemCreate(1);

>        // 4. Set number of system ticks per second
>        OSSetTicksPerSec(OS_TICKS_PER_SEC);

>        // Begin multi-tasking
>        OSStart();
>     }

>     void RandomNumberTask(void *pdata)
>     {
>        // Declare as auto to ensure reentrancy.
>        auto OS_TCB data;
>        auto INT8U  err;
>        auto INT16U RNum;

>        OSTaskQuery(OS_PRIO_SELF, &data);
>        while(1)
>        {
>           // Rand is not reentrant, so access must be controlled via a semaphore.
>           OSSemPend(RandomSem, 0, &err);
>           RNum = (int)(rand() * 100);
>           OSSemPost(RandomSem);

>           printf("Task%02d's random #: %d\n",data.OSTCBPrio,RNum);

>           // Wait 3 seconds in order to view output from each task.
>           OSTimeDlySec(3);
>        }
>     }

> #### 5.10.5 Compatibility with TCP/IP

> The TCP/IP stack is reentrant and may be used with the µC/OS real-time kernel. The line

>     #use ucos2.lib

> must appear before the line

>     #use dcrtcp.lib

> A call to `OSInit()` must be made before calling `sock_init()`.

> #### 5.10.5.1 Socket Locks

> Each socket used in a µC/OS-II application program has an associated socket lock. Each socket lock uses one semaphore of type `OS_EVENT`. Therefore, the macro `MAX_OS_EVENTS` must take into account each of the socket locks, plus any events that the application program may be using (semaphores, queues, mailboxes, event flags, or mutexes).

> Determining `OS_MAX_EVENTS` may get a little tricky, but it isn't too bad if you know what your program is doing. Since `MAX_SOCKET_LOCKS` is defined as:

>     #define MAX_SOCKET_LOCKS (MAX_TCP_SOCKET_BUFFERS + MAX_UDP_SOCKET_BUFFERS)

> `OS_MAX_EVENTS` may be defined as:

>     #define OS_MAX_EVENTS MAX_TCP_SOCKET_BUFFERS + MAX_UDP_SOCKET_BUFFERS + 2 + z

> The constant "2" is included for the two global locks used by TCP/IP, and "`z`" is the number of `OS_EVENTS` (semaphores, queues, mailboxes, event flags, or mutexes) required by the program.

> If either `MAX_TCP_SOCKET_BUFFERS` or `MAX_UDP_SOCKET_BUFFERS` is not defined by the application program prior to the #use statements for `ucos.lib` and `dcrtcp.lib`, default values will be assigned.

> If`MAX_TCP_SOCKET_BUFFERS` is not defined in the application program, it will be defined as `MAX_SOCKETS`. If, however, `MAX_SOCKETS` is not defined in the application program, `MAX_TCP_SOCKET_BUFFERS` will be 4.

> If `MAX_UDP_SOCKET_BUFFERS` is not defined in the application program, it will be defined as 1 if `USE_DHCP` is defined, or 0 otherwise.

> For more information about TCP/IP, please see the Dynamic C TCP/IP User's Manual, Volumes 1 and 2, available online at rabbit.com.

> #### 5.10.6 Debugging Tips

> Single stepping may be limited to the currently running task by using the F8 key (Step over). If the task is suspended, single stepping will also be suspended. When the task is put back in a running state, single stepping will continue at the statement following the statement that suspended execution of the task.

> Pressing the F7 key (Trace into) at a statement that suspends execution of the current task will cause the program to step into the next active task that has debug information. It may be useful to put a watch on the global variable `OSPrioCur` to see which task is currently running.

> For example, if the current task is going to call `OSSemPend()` on a semaphore that is not in the signaled state, the task will be suspended and other tasks will run. If F8 is pressed at the statement that calls `OSSemPend()`, the debugger will not single step in the other running tasks that have debug information; single stepping will continue at the statement following the call to `OSSemPend()`. If F7 is pressed at the statement that calls `OSSemPend()` instead of F8, the debugger will single step in the next task with debug information that is put into the running state.

> ### 5.11 Summary

> Although multitasking may actually decrease processor throughput slightly, it is an important concept. A controller is often connected to more than one external device. A multitasking approach makes it possible to write a program controlling multiple devices without having to think about all the devices at the same time. In other words, multitasking is an easier way to think about the system.

Dynamic C User's Manual | << Previous | Index | Next>> | rabbit.com