uC/OS-51 - Documentation

Author: Gianpaolo Macario <gianpi@geocities.com>

$Id: ucos51.htm,v 1.3 1997/07/14 13:19:55 gianpi Exp $

File Structure

Filename	Description
includes.h	Included by Test Programs
readme.txt	Original documentation by Jean Labrosse (was read.me)
test1.c	Test Program #1 (MS-DOS)
test2.c	Test Program #2 (MS-DOS)
ucos.c	Target-independent uC/OS Functions (Ansi C)
ucos.h	Constants and prototypes for ucos.c
ucos186a.asm	Target-dependent (80x86) uC/OS Functions (ASM-86)
ucos186c.c	Target-dependent (80x86) uC/OS Functions (Borland C)
ucos186c.h	Constants and prototypes for ucos186a.asm and ucos186c.c
ucos51.htm	Documentation for uC/OS-51 (this file)
ucos51a.asm	Target-dependent (8051) uC/OS Functions (ASM-51)
ucos51c.c	Target-dependent (8051) uC/OS Functions (CC51)
ucos51c.h	Constants and prototypes for ucos51a.asm and ucos51c.c

uC/OS Limits

Maximum number of tasks: 64
Each task must have a different priority

uC/OS System Declarations

#define OS_LO_PRIO 63 /* IDLE task priority */

OS_Task_Status

#define OS_STAT_RDY  0x00 /* Ready to run */
#define OS_STAT_MBOX 0x01 /* Pending on mailbox */
#define OS_STAT_SEM  0x02 /* Pending on semaphore */
#define OS_STAT_Q    0x04 /* Pending on queue */ 
#define OS_STAT_RES1 0x08 /* Reserved */
#define OS_STAT_RES2 0x10 /* Reserved */
#define OS_STAT_RES3 0x20 /* Reserved */
#define OS_STAT_RES4 0x40 /* Reserved */
#define OS_STAT_RES5 0x80 /* Reserved */

OS_Error_Code

#define OS_NO_ERR      0 
#define OS_TIMEOUT    10 
#define OS_MBOX_FULL  20 
#define OS_Q_FULL     30
#define OS_PRIO_EXIST 40 
#define OS_SEM_ERR    50 
#define OS_SEM_OVF    51

uC/OS Task Control Block Data Structure

This structure must be accessed by assembler code as well (at least for OSTCBStkPtr), so OSTCBStkPtr must be allocated as the first field in structure.

typedef struct os_tcb {
    void          *OSTCBStkPtr;
    UBYTE          OSTCBStat;         /* According to OS_Task_Status */
    UBYTE          OSTCBPrio; 
    UWORD          OSTCBDly;          /* Delay in system ticks */
    struct os_tcb *OSTCBNext; 
    struct os_tcb *OSTCBPrev; 
} OS_TCB;

Semaphore Data Structure

typedef struct os_sem {
    WORD  OSSemCnt; 
    UBYTE OSSemGrp; 
    UBYTE OSSemTbl[8]; 
} OS_SEM;

Mailbox Data Structure

typedef struct os_mbox {
    void  *OSMboxMsg;
    UBYTE  OSMboxGrp; 
    UBYTE  OSMboxTbl[8]; 
} OS_MBOX;

Queue Data Structure

typedef struct os_q { 
    void **OSQStart; 
    void **OSQEnd; 
    void **OSQIn; 
    void **OSQOut; 
    UBYTE  OSQSize; 
    UBYTE  OSQEntries; 
    UBYTE  OSQGrp; 
    UBYTE  OSQTbl[8]; 
} OS_Q;

uC/OS Global Variables

extern BOOLEAN  OSRunning;            /* TRUE if a task is running             */

extern OS_TCB  *OSTCBCur;             /* Ptr to TCB of Current Running task    */

extern OS_TCB  *OSTCBHighRdy;         /* Ptr to TCB of Highest Priority Task   */

extern UBYTE    OSRdyGrp;             /* Bitmap with a 1 for each ready group  */

extern UBYTE    OSRdyTbl[];           /* Bitmap with a 1 for each ready Task   */

extern OS_TCB  *OSTCBPrioTbl[];       /* Priority Table (OS_MAX_PRIO elements) */

extern OS_TCB   OSTCBTbl[];           /* TCB Table (OS_MAX_TASKS elements)     */

extern OS_TCB  *OSTCBList;            /* List of Task Control Blocks           */

extern UBYTE    OSLockNesting;        /* Lock nesting level                    */

extern UBYTE    OSIntNesting;         /* Interrupt nesting level               */

extern OS_TCB  *OSTCBFreeList;        /* List of Free TCBs                     */

extern UBYTE _rom OSMapTbl[];         /* Table to quickly get...               */

extern UBYTE _rom OSUnMapTbl[];       /* ... the Highest Priority Task         */

uC/OS Macros

Invoke the Task Switcher

OS_TASK_SW()

Enter a critical region (disable interrupts)

OS_ENTER_CRITICAL()

Exit a critical region (enable interrupts)

OS_EXIT_CRITICAL()

uCOS Functions - Alphabetical

OSChangePrio
OSCtxSw
OSInit
OSIntCtxSw
OSIntEnter
OSIntExit
OSLock
OSMboxInit
OSMboxPend
OSMboxPost
OSQInit
OSQPend
OSQPost
OSSched
OSSemInit
OSSemPend
OSSemPost
OSStart
OSStartHighRdy
OSTCBGetFree
OSTCBPutFree
OSTaskCreate
OSTaskDelete
OSTickISR
OSTimeDly
OSTimeTick
OSUnlock

uC/OS Function Descriptions

uC/OS Initialization

ucos-186 (ucos.c):

void OSInit(void *idle_stk, UBYTE maxtasks);

ucos-i386 (ucos.c):

void OSInit(void *idle_stk, UBYTE maxtasks);

Start Multitasking

ucos-186 (ucos.c):

void OSStart(void);

ucos-i386 (ucos.c):

void OSStart(void);

Create Task

Parameters:

task: Pointer to function implementing task
datap: Pointer to user data
pstk: Pointer to user stack
prio: Task priority

Return OS_Error_Code

ucos-6811 (ucos11c.c):

UBYTE OSTaskCreate(
      void (far *task)(void *dptr),
      void *data,
      void *pstk,
      UBYTE p);

ucos-cpu32 (ucosc32c.c):

UBYTE OSTaskCreate(
      void (*task)(void *dptr),
      void *data,
      void *pstk,
      UBYTE p);

ucos-i386 (ucos186c.c):

UBYTE OSTaskCreate(
      void (far *task)(void *dptr),
      void *data,
      void *pstk,
      UBYTE p);

Delay Task 'n' Ticks (n = 1..65535)

ucos-186 (ucos.c):

void OSTimeDly(UWORD ticks);

ucos-i386 (ucos.c):

void OSTimeDly(UWORD ticks);

Process System Tick

ucos-186 (ucos.c):

void OSTimeTick(void);

ucos-i386 (ucos.c):

void OSTimeTick(void);

Enter ISR

ucos-186 (ucos.c):

void OSIntEnter(void);

ucos-i386 (ucos.c):

void OSIntEnter(void);

Exit ISR

ucos-186 (ucos.c):

void OSIntExit(void);

ucos-i386 (ucos.c):

void OSIntExit(void);

Perform a Context Switch (From task level)

ucos-6811 (ucos11a.asm):

void OSCtxSw(void);

ucos-cpu32 (ucosc32a.asm):

void OSCtxSw(void);

ucos-i386 (ucos186a.asm):

void far OSCtxSw(void);

Perform a Context Switch (From an ISR)

ucos-6811 (ucos11a.asm):

void OSIntCtxSw(void);

ucos-cpu32 (ucosc32a.asm):

void OSIntCtxSw(void);

ucos-i386 (ucos186a.asm):

void OSIntCtxSw(void);

Handle Tick ISR

ucos-6811 (ucos11a.asm):

void far OSTickISR(void);

ucos-cput32 (ucosc32a.asm):

void OSTickISR(void);

ucos-i386 (ucos186a.asm):

void far OSTickISR(void);

Run Highest Priority Task (Low-level)

ucos-6811 (ucos11a.s):

void OSStartHighRdy(void);

ucos-cpu32 (ucosc32a.asm):

void OSStartHighRdy(void);

ucos-i386 (ucos186a.asm):

void OSStartHighRdy(void);

Run Highest Priority Task

ucos-186 (ucos.c):

void OSSched(void);

ucos-i386 (ucos.c):

void OSSched(void);

Get TCB From Free TCB List

ucos-186 (ucos.c):

OS_TCB *OSTCBGetFree(void);

ucos-i386 (ucos.c):

OS_TCB *OSTCBGetFree(void);

Change Priority of Running Task

ucos-186 (ucos.c):

UBYTE OSChangePrio(UBYTE newp);

ucos-i386 (ucos.c):

UBYTE OSChangePrio(UBYTE newp);

Delete Running Task

ucos-186 (ucos.c):

void OSTaskDelete(void);

ucos-i386 (ucos.c):

void OSTaskDelete(void);

Prevent Scheduling

ucos-186 (ucos.c):

void OSLock(void);

ucos-i386 (ucos.c):

void OSLock(void);

Enable Scheduling

ucos-186 (ucos.c):

void OSUnlock(void);

ucos-i386 (ucos.c):

void OSUnlock(void);

Initialize Semaphore

ucos-186 (ucos.c):

UBYTE OSSemInit(OS_SEM *psem, WORD cnt);

ucos-i386 (ucos.c):

UBYTE OSSemInit(OS_SEM *psem, WORD cnt);

Post to a Semaphore

ucos-186 (ucos.c):

UBYTE OSSemPost(OS_SEM *psem);

ucos-i386 (ucos.c):

UBYTE OSSemPost(OS_SEM *psem);

Pend on Semaphore

ucos-186 (ucos.c):

UBYTE OSSemPend(OS_SEM *psem, UWORD timeout);

ucos-i386 (ucos.c):

UBYTE OSSemPend(OS_SEM *psem, UWORD timeout);

Initialize Mailbox

ucos-186 (ucos.c):

UBYTE OSMboxInit(OS_MBOX *pmbox, void *msg);

ucos-i386 (ucos.c):

UBYTE OSMboxInit(OS_MBOX *pmbox, void *msg);

Post to a Mailbox

ucos-186 (ucos.c):

UBYTE OSMboxPost(OS_MBOX *pmbox, void *msg);

ucos-i386 (ucos.c):

UBYTE OSMboxPost(OS_MBOX *pmbox, void *msg);

Pend on Mailbox

ucos-186 (ucos.c):

void *OSMboxPend(OS_MBOX *pmbox, UWORD timeout, UBYTE *err);

ucos-i386 (ucos.c):

void *OSMboxPend(OS_MBOX *pmbox, UWORD timeout, UBYTE *err);

Initialize Queue

ucos-186 (ucos.c):

UBYTE OSQInit(OS_Q *pq, void **start, UBYTE size);

ucos-i386 (ucos.c):

UBYTE OSQInit(OS_Q *pq, void **start, UBYTE size);

Post to a Queue

ucos-186 (ucos.c):

UBYTE OSQPost(OS_Q *pq, void *msg);

ucos-i386 (ucos.c):

UBYTE OSQPost(OS_Q *pq, void *msg);

Pend on a Queue

ucos-186 (ucos.c):

void *OSQPend(OS_Q *pq, UWORD timeout, UBYTE *err);

ucos-i386 (ucos.c):

void *OSQPend(OS_Q *pq, UWORD timeout, UBYTE *err);

Put TCB To Free TCB List

Not implemented (coded in OSTaskDelete).

void OSTCBPutFree(OS_TCB *ptcb);

References

Real-Time Systems List by Frank Miller.
http://www.cs.umd.edu/~fwmiller/etc/realtime/code.html
Cygnus FTP site: ftp://ftp.cygnus.com/pub/embedded/ucos
Article in "Embedded System Programming Magazine" - May 1992
Article in "Embedded System Programming Magazine" - June 1992
Book: Jean Labrosse - "uC/OS, The Real-Time Kernel". R&D Books, 1992. ISBN 0-13-031352-1
http://www.rdbooks.com/microcos.htm
266 pages, 8 x 10.
Book with disk: Product code W62, $49.95
Disk only: Product code W60D, $24.95
Upgrade disk (v 1.08 7/21/95): Product code W60UP, $9.95 (requires prior ownership)
Book: Jean Labrosse - "Embedded Systems Building Blocks". R&D Books, 1995. ISBN 0-13-35779-2
http://www.rdbooks.com/emb_sys.htm
600 pages, 8 x 10. Includes 3-1/2" disk.
Product Code V74
Jean Labrosse email: 72644.3724@compuserve.com
R&D Publications
http://www.rdbooks.com
Suite 200 - 1601 West 23rd Street
Lawrence, KS 66046
Phone: (913) 841-1631
Fax: (913) 841-2624