This document gives an overview of the uCos.  To use uCos 4
files must be included, common.h (compiler specific and common
defines and typedefs), ucos.h (operating system files), 196.h
(or the processor specific include file) and apitsk.h (or the
application specific include file).  If OSReplce is not used the
196.h file is not needed.

#include "common.h" 
#include "ucos.h" 
#include "196.h" 
#include "jijitsk.h"

The following describes all the system calls available with some
examples.

Please Note: The routines marked with a (@) CAN NOT be used in
an ISR.


System Initialization
void OSInit(void); @--------	Initialize uCos
void OSStart(void); @-------	Start Multitasking

Example of  system initialization and starting:
int cmain(void) 
{ 
   DISABLE
   init_io();          /* hardware init */
   OSInit();           /* uCos init and also enables interrupts*/
   init_module1();     /* each module init and loads tasks needed */
   init_module2();     /* each module init and loads tasks needed */
   init_module3();     /* each module init and loads tasks needed */
   init_module4();     /* each module init and loads tasks needed */
   ENABLE   
   OSStart();          /* Starts uCos and never returns to main */ 
}



Task Management

BYTE OSTaskCreate(void(*task)(void *pd),void *pdata,void
*pstk,BYTE prio); @

task is the task to be created.

pdata is not used for T/Rs version and should be a zero.

pstk is the pointer to the stack area.

prio is the priority of the task to be created.

BYTE OSTaskDel(BYTE p); @------ Delete Task

p is the priority of the task to be deleted.

BYTE OSTaskChangePrio(BYTE oldp, BYTE newp); ------ Change Task
Priority

oldp is the old priority.

newp is the new priority.

void OSReplace(void ( *task)(void *pd), void *pstk );

task is the new task to be started.

pstk is the pointer to the top of the stack area.

void OSSchedLock(void); ----	Prevent Task Switching

void OSSchedUnlock(void); --	Allow Task Switching

Example:

void init_module1(void)

{
   OSTaskCreate((void *)TaskX,(void *)0,(void*)&Tsk1Stk[TSK1_STK_SIZE],TSK1_PRI);
   SSema1 = OSSemCreate(0);   
   SSema2 = OSSemCreate(0); 
   TSK1Mbox = OSMboxCreate((void *)0);
}
void TaskX(void)
{
   OSSchedLock();
   user_code();
   OSSchedUnlock();
   OSReplace((void *)TaskY,(void *)&TaskStk[STK_SIZE]);
}
void TaskY(void)
{
   user_code();
   if(z > y) 
      OSReplace((void *)TaskX,(void *)&TaskStk[STK_SIZE]);
   else
      OSTaskDel(TSK1_PRI);
}


Interrupt Management

void OSIntEnter(void); ------	Must be called on Interrupt entry.
 Keeps track of interrupt nesting.

void OSIntExit(void); -------	Must be called on Interrupt exit.
Does task switch if needed.

Time Management

void OSTimeDly(WORD ticks); @--- Delay task ticks number of system clock cycles. 
                      (if system tick=10msec and ticks=3, time of delay=30msec)

void OSTimeTick(void); ---------- System Clock routine.  This must be called 
                        to keep the system time clock.

void OSTimeSet(LONG ticks); --- Set system time to ticks.

LONG OSTimeGet(void); -------- Get current system time.

Example:

void stimer_irq( void )
{
   int_mask = gint_mask & ~(SWTIME);
   imask1 = gimask1 & ~(SER_RECV);
   OSIntEnter();
   ENABLE
   Mios1 |= ios1;
   if( (Mios1 & TIMER_0) ) /*  T I M E R 0  is system clock */
   {
	   Mios1 &= ~(TIMER_0);
      while( ios0 & HSO_HOLD_FULL ) {} /* wait for hso register to free*/
      sys_acc += TEN_MSEC;
      DISABLE
      hso_command = SWTIMER0;
      hso_time = sys_acc;
      ENABLE
      OSTimeTick();                         /* uCos system tick */
      if( Mios1 & (TIMER_1|TIMER_2|TIMER_3) )
         int_pending |= SWTIME;
   }
   OSIntExit();
}

Semaphore Management

OS_EVENT *OSSemCreate(SWORD value);@---- Create a Semaphore.

value is the initial value between 0 and 32767 of the semaphore.
 If a semaphore's initial value equals one then the first time
OSSemPend is called it will return immediately.  If however the
value equals zero then OSSemPend will wait for the first
occurrence of the semaphore.

BYTE OSSemPost(OS_EVENT *pevent);---- Signal a Semaphore. 
pevent is a pointer to a Semaphore.

void OSSemPend(OS_EVENT *pevent, WORD timeout, BYTE *err);@---- Wait for 
Semaphore.
pevent is a pointer to a Semaphore.
timeout is the value of system clock ticks before pending is
discontinued.
err  is the location for error information which is set by the
routine.

void OSSetSema(OS_EVENT *pevent, SWORD value);---- Set Semaphore
to value.
pevent is a pointer to a Semaphore.
value can be set between -32767 and 32767.  A negative number
means a task is waiting for this semaphore.  If the value equals
-3 then 3 task are pending on this semaphore.

Example:
void init_module1(void)
{
   OSTaskCreate((void *)Task1,(void *)0,(void*)&Tsk1Stk[TSK1_STK_SIZE],TSK1_PRI);
   OSTaskCreate((void *)Task2,(void *)0,(void*)&Tsk2Stk[TSK2_STK_SIZE],TSK1_PRI);
   SSema1 = OSSemCreate(0);   
   TSK2Mbox = OSMboxCreate((void *)0);
}
void Task1(void)
{
   while(1)
   {
      OSSemPost(SSema1);
      user_code();
      OSTimeDly(THIRTY_MSEC);
   }
}
void Task2(void)
{
   while(1)
   {
      user_code();
      OSSetSema(SSema1,-1);        /* sync to next SSema1 */
      OSSemPend(SSema1, 0, &err);
      user_code();
   }
}

Mail Management

OS_EVENT *OSMboxCreate(void *msg);@---- Create a mailbox.

void OSMboxPost(OS_EVENT *pmail, void *msg, BYTE p, BYTE
useAck);@---- Send message to a mailbox.  It will wait until the
mailbox is empty before sending the message and returning to the
sending task.
pmail is pointer to a mailbox.
msg is pointer to message to be sent.
p is priority of the sender ( this is only used when using ack ).
useAck is to indicate the use of acking a mail message.

void *OSMboxPend(OS_EVENT *pevent, WORD timeout, BYTE*err);@---- Waits for mail to be received.
pevent is pointer to a mailbox.
timeout is the value of system clock ticks before pending is
discontinued.
err  is the location for error information which is set by the
routine.

void *OSMboxAccept(OS_EVENT *pmail);@---- Checks the mailbox but
does not wait if it is empty.
pmail is pointer to a mailbox

void OSMailAck(OS_EVENT *pmail);@---- Wakes up task which is
waiting for message acknowledgment or does nothing if an ack is
not to be used.
pmail is pointer to a mailbox

Example:
CMD_MSG tsk2_mail_buf;

void init_module1(void)
{
   OSTaskCreate((void *)Task1,(void *)0,(void*)&Tsk1Stk[TSK1_STK_SIZE],TSK1_PRI);
   OSTaskCreate((void *)Task2,(void *)0,(void*)&Tsk2Stk[TSK2_STK_SIZE],TSK2_PRI);
   TSK1Mbox = OSMboxCreate((void *)0);
   TSK2Mbox = OSMboxCreate((void *)0);
}
void Task1(void)
{
   while(1)
   {
      tsk2_mail_buf.cmd = TEST1;
      OSMboxPost(Tsk2Mbox, &tsk2_mail_buf, TSK1_PRI, OS_USE_ACK);
      user_code();
      if( msg = OSMboxAccept(Tsk1Mbox) )
         switch(msg->cmd)
         {
            case CMD1:
               user_code();
            break;
         }
   }
}
void Task2(void)
{
BYTE err;
CMD_MSG *msg;

   while(1)
   {
      msg = OSMboxPend(Tsk2Mbox, 0, &err);
      decode_msg(msg);
      OSMailAck(Tsk2Mbox);
   }
}

Queue Management

OS_EVENT *OSQCreate(void **start, BYTE size);@---- Create a Queue.
start is the location of the first byte in the queue.
size is the number of bytes in the queue.

BYTE OSQPost(OS_EVENT *pevent, void *msg);---- Send message to queue.
pevent is a pointer to a Queue.
msg is message to be sent.

void *OSQPend(OS_EVENT *pevent, WORD timeout, BYTE *err);@---- Wait for 
message from queue.
pevent is a pointer to a Queue.
timeout is the value of system clock ticks before pending is discontinued.
err  is the location for error information which is set by the routine.

Multi-Event Management

void *OSEventPend(OS_EVENT *psema,OS_EVENT *pmail,WORD timeout,BYTE *err); 
@ Waits for either mail or a semaphore to occur before waking up the pending 
task.  It can also be used to pend on just a semaphore or mailbox.
psema is a pointer to a Semaphore.
pmail is pointer to a mailbox.
timeout is the value of system clock ticks before pending is discontinued.
err  is the location for error information which is set by the routine.
Example:

A) Mail Only
void Task(void)
{
BYTE err;
   msg = OSEventPend(0,Task1Mbox,0,&err);
   switch(msg->cmd)
   {
      case CMD1:
	break;
      case CMD2:
	break;
   }
}
	
B) Semaphore Only
void Task(void)
{
BYTE err;
   OSEventPend(Ssema1,0,0,&err);
   user_code_for_sema1();
}

C) Mail and Semaphore
void Task(void)
{
BYTE err;
   if(msg = OSEventPend(Ssema1,Task1Mbox,0,&err) == 0)
   {						/* semaphore occurred */
      user_code_for_sema1();
   } else					/* mail received */
   {
      switch(msg->cmd)
      {
         case CMD1:
	   break;
         case CMD2:
	   break;
      }
   }
}
The following file (ucoscfg.h) is to configure ucos to the users
application and reduce the RAM and ROM size.  The file as seen
below does not use queues, change priority routine and the debug
information.  It does uses the mail, semaphores and the multi
event routines.
/*==========================================================================*/
/*                U C O S C F G . H                                        */
/*==========================================================================*/
/* Changed < ucoscfg.h >  6-21-1994   4:56 PM   T/R Systems                */
/*==========================================================================*/
/* To comment out any of the following defines is to not use that section of*/
/* code described.                                                          */
/* Comment out              Aprox. Code Saving in bytes (on 80C196)         */
/* -----------              ---------------------------                     */
/*  USE_MAIL                   986                                          */
/*  USE_QUEUE                  848                                          */
/*  USE_SEMA                   572                                          */
/*  USE_CHG_PRIORITY           524                                          */
/*  USE_MULTI_EVENTS           350                                          */
/*  USE_DEBUG                   76                                          */
/*                                                                          */
/*                                                                          */
/* When USE_MULTI_EVENTS is set OSMboxPend and OSSemPend should not be used.*/
/* Instead use OSEventPend placing a 0 in place of the mailbox or semaphore.*/
/* Also note OSMboxPend and OSSemPend are not compilied which reduces the   */ 
/* code size by 378 and 292 bytes respectively.                             */
/*==========================================================================*/
/*==========================================================================*/
#define USE_MAIL 1                                       /* Use Mail system */
#define USE_SEMA 1                                        /* Use Semaphores */
#define USE_MULTI_EVENTS 1                  /* Use multi-event pend routine */
/*#define USE_QUEUE 1*/                                       /* Use Queues */
/*#define USE_CHG_PRIORITY 1*/               /* Use Change priority routine */
/*#define USE_DEBUG 1*/  /* Use for debug counters OSCtxSwCtr and OSIdleCtr */


#if USE_MULTI_EVENTS   /* mail and sema MUST be defined if multievents used */
#define USE_MAIL 1                                       /* Use Mail system */
#define USE_SEMA 1                                        /* Use Semaphores */
#endif