PIC24 en:osa:ref:description

OSA : Data types

2010-03-10T14:33:43+03:00

OSA : Data types

System

__osa_uint8

Platform independed unsigned 8-bit integer.

__osa_uint16

Platform independed unsigned 16-bit integer.

__osa_uint32

Platform independed unsigned 32-bit integer.

__osa_word

Platform depended unsigned integer. Has width of controller's data bus.

Common

OST_CSEM

Counting semaphore's type.

Definition

    typedef __osa_uint8 OST_CSEM;

This type is aviable only when OS_ENABLE_CSEM constant is defined in OSAcfg.h.

Redefining

You can redefine this type by changing size of CSEM in file OSAcfg.h:

#define OS_CSEM_SIZE    4

Allowed values of OS_CSEM_SIZE:

1	__osa_uint8 (0..2^8-1)
2	__osa_uint16 (0..2^16-1)
4	__osa_uint32 (0..2^32-1)

OST_MSG

Pointer to message.

Definition

typedef void * OST_MSG;

Redefining

You can redefine this type by defining OS_MSG_TYPE constant in OSAcfg.h. For example:

typedef stuct {
    char * Name;
    char Age;
} MyType;
 
#define OS_MSG_TYPE MyType *

Allowed all types (for example const char * - pointer to ROM).

OST_MSG_CB

Descriptor of pointer to message. Contains pointer to message and message' state flag (free/busy).

Definition

typedef struct {
    char      status;     // Message's state flag (=0 - free, =1 - busy)
    OST_MSG   msg;        // Pointer to message body
} OST_MSG_CB;

Redefining

You can redefine only pointer to message type OST_MSG by defining it manuale in OSAcfg.h.

OST_DTIMER

Dinamic timer.

Definition

typedef struct
{
    OST_DTIMER_FLAGS Flags;
    void *           Next;
    _OST_DTIMER      Timer;     // Timer's counter
} OST_DTIMER;

State flags are used to tell timer routine (OS_Timer) how to work with this timer (is it run or stopped, is it active, is there next timer in list):

Flags	Timer's state flags (see OST_DTIMER_FLAGS)
Next	Pointer to next timer in list of active timers
Timer	Counter. Size of counter is set by OS_DTIMER_SIZE constant (default = 2)

Redefining

You can redefine only counter's size constant OS_DTIMER_SIZE in OSAcfg.h:

#define OS_DTIMER_SIZE       4

Allowed values of OS_DTIMER_SIZE:

1	__osa_uint8 (0..2^8-1)
2	__osa_uint16 (0..2^16-1)
4	__osa_uint32 (0..2^32-1)

OST_QTIMER

Timer in queue of timers.

Definition

typedef struct
{
    OST_QTIMER_FLAGS Flags;
    void *           Next;
    _OST_QTIMER      Timer;     // Timer's counter
} OST_QTIMER;

State flags are used to tell timer routine (OS_Timer) how to work with this timer (is it run or stopped, is it active, is there next timer in list):

Flags	Timer's state flags (see OST_QTIMER_FLAGS)
Next	Pointer to next timer in list of active timers
Timer	Counter. Size of counter is set by OS_QTIMER_SIZE constant (default = 2)

Redefining

You can redefine only counter's size constant OS_QTIMER_SIZE in OSAcfg.h:

#define OS_QTIMER_SIZE       4

Allowed values of OS_QTIMER_SIZE:

1	__osa_uint8 (0..2^8-1)
2	__osa_uint16 (0..2^16-1)
4	__osa_uint32 (0..2^32-1)

OST_QUEUE

Queue of poiner to messages.

Definition

typedef struct {
    OST_QUEUE_CONTROL Q;
    OST_MSG *pMsg;
} OST_QUEUE;

Q - queue control block. pMsg - pointer to buffer where pointers to message will be stored to.

OST_SQUEUE

Queue of simple messages.

Definition

typedef struct {
    OST_QUEUE_CONTROL Q;
    OST_SMSG *pSMsg;
} OST_SQUEUE;

Q - queue control block. pSMsg - pointer to buffer where message pointers will be stored to.

OST_SMSG

Simple byte message. Used to reduce RAM usage when there is no need to use pointers to messages.

Definition

typedef __osa_uint8   OST_SMSG;

Redefining

You can redefine this type by defining OS_SMSG_TYPE constant in OSAcfg.h. For example:

#define OS_SMSG_TYPE unsigned long

Allowed any counting type. You should bear in mind that simple message type havn't separate flag indicating busy state. This state is indicated by mesasge's body: if simple message is zero, then it is free, else it is busy. Thus you may exchange only non zero simple messages between tasks.

OST_TASK_POINTER

Variables of this type are used to control tasks from any place in program. Task descriptors are not accessible directly, so these variables are used to access to task descriptors via pointers.

Definition

typedef OS_TASKS_BANK OST_TCB *  OST_TASK_POINTER;

Note that prefix OS_TASKS_BANK used.

Redefining

Not allowed

Internal (for information)

OST_DTIMER_FLAGS

Contains state flags for dynamic timers (OST_DTIMER).

Definition

typedef struct {
    char   bTimeout:1;
    char   bActive:1;
    char   bIsRun:1;
    char   bNextEnable:1;
} OST_DTIMER_FLAGS;

bTimeout	indicates whether the timer overflow
bActive	shows is timer active (=1) or not (=0). When timer is active (created by OS_Dtimer_Create) it will be processed every OS_Timer call.
bIsRun	indicates whether the timer is counting (=1) or stopped (=0). If =1 then timer increases by 1 every call of OS_Timer.
bNextEnable	indicates is there next timer in list of dynamic timers. If =1 then field Next points to next dynamic timer in list. If =0 then this timer is last in list.

OST_QTIMER_FLAGS

Contains state flags for timer in queue of timers (OST_QTIMER).

Definition

typedef struct {
    char   bTimeout:1;
    char   bActive:1;
    char   bIsRun:1;
    char   bNextEnable:1;
} OST_QTIMER_FLAGS;

bTimeout	indicates whether the timer overflow
bActive	shows is timer active (=1) or not (=0).
bIsRun	not used
bNextEnable	indicates is there next timer in queue of timers. If =1 then field Next points to next timer in queue. If =0 then this timer is last in queue.

OST_QUEUE_CONTROL

Queue of messages control block.

Definition

typedef struct {
    __osa_word      cSize;
    __osa_word      cBegin;
    __osa_word      cFilled;
} OST_QUEUE_CONTROL;

cSize	Size of buffer (in messages)
cBegin	Position of first message in queue
cFilled	Number of messages in queue (=0 - queue is empty, =cSize - queue is full)

OST_TCB

Task control block.

Definition

typedef struct {
    OST_TASK_STATE State;
    OST_CODE_POINTER pTaskPointer;
    #ifdef __OSA18__
        unsigned char  cTempFSR1;
    #endif
    #ifdef __OSA30__
        unsigned int    W8_Temp;
        unsigned int    W9_Temp;
        unsigned int    W10_Temp;
        unsigned int    W11_Temp;
        unsigned int    W12_Temp;
        unsigned int    W13_Temp;
        unsigned int    W14_Temp;
        unsigned int    W15_Temp;
    #endif
    #ifdef OS_ENABLE_TIMER
        _OST_TTIMER Timer;
    #endif
} OST_TCB;

State	Taks state flags (see. OST_TASK_STATE)
pTaskPointer	Pointer to task return point.
cTempFSR1	Only for MCC18: saved FSR1 value.
Wx_Temp	Only MCC30: Saved W8..W15 registers
Timer	Task timer counter. Type _OST_TTIMER, size OS_TTIMER_SIZE. Added in OST_TCB only when constant OS_ENABLE_TIMER defined.

OST_TASK_STATE

Definition

typedef struct {
    __osa_word    cPriority:3;
    __osa_word    bReady:1;
    __osa_word    bDelay:1;
    __osa_word    bCanContinue:1;
    __osa_word    bEnable:1;
} OST_TASK_STATE;

cPriority	Task priority (0..7)
bReady	Ready flag. Tells to scheduler that task is ready to run.
bDelay	Task is delayed or waiting event with timeout. (See bCanContinue)
bCanContinue	When bDelay==1: =1 - task waits event with timeout; =0 - task delayed by OS_Delay
bEnable	=1 - descriptor is used by some task, =0 - descriptor is free.

_OST_DTIMER

Type of dynamic timer's counter.

Definition

#if   OS_DTIMER_SIZE == 1
    #define _OST_DTIMER __osa_uint8
#elif OS_DTIMER_SIZE == 2
    #define _OST_DTIMER __osa_uint16
#elif OS_DTIMER_SIZE == 4
    #define _OST_DTIMER __osa_uint32
#endif

If constant OS_DTIMER_SIZE not defined, then set to default value OS_TIMER_SIZE.

_OST_STIMER

Type of static timer's counter.

Definition

#if   OS_STIMER_SIZE == 1
    #define _OST_STIMER __osa_uint8
#elif OS_STIMER_SIZE == 2
    #define _OST_STIMER __osa_uint16
#elif OS_STIMER_SIZE == 4
    #define _OST_STIMER __osa_uint32
#endif

If constant OS_STIMER_SIZE not defined, then set to default value OS_TIMER_SIZE.

_OST_TTIMER

Type of task timer's counter.

Definition

#if   OS_TTIMER_SIZE == 1
    #define _OST_TTIMER __osa_uint8
#elif OS_TTIMER_SIZE == 2
    #define _OST_TTIMER __osa_uint16
#elif OS_TTIMER_SIZE == 4
    #define _OST_TTIMER __osa_uint32
#endif

If constant OS_TTIMER_SIZE not defined, then set to default value OS_TIMER_SIZE.

_OST_QTIMER

Type of queue timer's counter.

Definition

#if   OS_QTIMER_SIZE == 1
    #define _OST_QTIMER __osa_uint8
#elif OS_QTIMER_SIZE == 2
    #define _OST_QTIMER __osa_uint16
#elif OS_QTIMER_SIZE == 4
    #define _OST_QTIMER __osa_uint32
#endif

If constant OS_QTIMER_SIZE not defined, then set to default value OS_TIMER_SIZE.

OSA : Events and priority

2010-09-24T17:25:47+03:00

OSA : Events and priority

Task states

To synchronize tasks, the system uses events. For example, we have two active tasks (created by service OS_Task_Create): one of them measures temperature, and the other displays the measured value on a screen. The second task cannot display data if there is no measured value. While the first task makes measurements, the second task waits. After the temperature is measured (in other words, the event has taken place), the second task becomes ready to run. And then the second task can be executed.

Thus all tasks can have one of five states:

not active	task was not created or was deleted
waiting	task is waiting for some event
ready	the expected event occurred but the task did not get control yet
running	task is executing
paused	task is paused. It is still active but can't get control.

In order for a task to get control, two conditions must be met:

the event expected by the task occurs (task becomes ready);
the task's priority must be higher than the priorities of other ready tasks.

Events

Events in OSA:

semaphore (binary or counting);
message (pointer to a message body or a simple byte message);
flags combination;
timeout;
any boolean expression.

Each of the first four types is described in its own section. The fifth type is optional and allows a task to wait for some non-system event, e.g.:

OS_Wait(TMR1IF);                   // Wait for TMR1 overflow
or
OS_Wait_TO(ReadADC(0) > 128);      // Wait for input voltage to be greater than Vdd/2

These two services are described in the section system services.

Priority

All task have a priority from 0 (highest) to 7 (lowest).

There are three priority modes (levels):

disabled priorities - all assigned priorities are ignored. This is the fastest and compact mode. But it does not allow to assign higher priority for more important tasks.
normal priorities - each task have it's own priority. If there are several ready tasks, then the task with the highest priority will get control. If several ready tasks have the same priority, then they will be run in round-robin mode. This mode has two disadvantages:
1. when there is an always ready task with high priority, no low priority tasks will get control;
2. when two or more tasks have the same priority and they wait for the same event, only one of them allways will get the control;
extended priorities NEW - all tasks get control according to their priority. For example, if there are two always ready tasks with priorities 3 and 4, then one of them will get 55-60% of control (with priority 4) and other - 40-45%. The advantage of this mode is that all tasks guarantly will get the control. But in this mode system requires 2 addition bytes of RAM per each task.

Read SPeed characteristics to learn more about speed of scheduler in different modes.

The priority mode is defined once on the compilation stage by setting constant OS_PRIORITY_LEVEL in osacfg.h:

#define OS_PRIORITY_LEVEL    OS_PRIORITY_DISABLE    // For disable priorities

#define OS_PRIORITY_LEVEL    OS_PRIORITY_NORMAL     // For normal priorities

#define OS_PRIORITY_LEVEL    OS_PRIORITY_EXTENDED   // For extended priorities

By default OS_PRIORITY_NORMAL is set.

Priority competition

There are times whan several tasks are waiting for the same event. For example they can wait for some internal resource (UART, ADC, SPI) or some external resource (EEPROM, LCD etc). How will the system behave in this case? After the event occurs, all tasks that waited for this event will become ready. The kernel will find the task with the highest priority and run it. If, after this task executes, the event is cleared (for example, all tasks waited for a semaphore, and the executed task reset it) all tasks become waiting again.

When working under extended priority mode, the tasks who was ready but did not get the control (because of more priority task has reset the event) will rise it's priority. This will give to it more chance to get the control next time event occured.

OSA : Description

2008-10-18T19:35:00+03:00

OSA : Description

OSA : Predefined constants

2010-09-22T16:23:31+03:00

OSA : Predefined constants

Constant name	Notes
System
__OSA_VERISON__	Current OSA version in format: YYMMDD YY, MM and DD are year month and date of release
Chip type
__OSA_PIC12__	PIC10 or 12-bit PIC12
__OSA_PIC16__	PIC16 or 14-bit PIC12
__OSA_PIC16E__	PIC12F1xxx or PIC16F1xxx
__OSA_PIC18__
__OSA_DSPIC__	dsPIC30 or dsPIC33
__OSA_PIC24__	PIC24F, PIC24FK or PIC24H
__OSA_PIC24F__
__OSA_PIC24FK__
__OSA_PIC24H__
__OSA_DSPIC30__
__OSA_DSPIC33__
__OSA_AVR__	8-bit AVR
__OSA_STM8__
Compiler type
__OSA_CCS__	CCS PICC
__OSA_HTPICC__	HiTech PICC STD
__OSA_HTPICC_PRO__	HiTech PICC PRO
__OSA_MPLABC__	MPLABC18 or MPLABC30
__OSA_MIKROC__	MikroC PRO (ver 3.0 and greater)
__OSA_WINAVR__	WinVAR
__OSA_IAR__	IAR
__OSA_COSMIC__	Cosmic
Chip and compiler
__OSA_PIC12_HTPICC__
__OSA_PIC16_CCS__
__OSA_PIC16_HTPICC__
__OSA_PIC16_MIKROC__
__OSA_PIC16E_HTPICC_PRO__
__OSA_PIC18_HTPICC__
__OSA_PIC18_MPLABC__
__OSA_PIC18_MPLABC_EXT__
__OSA_PIC18_CCS__
__OSA_PIC18_MIKROC__
__OSA_PIC24_MPLABC__	Same as __OS_DSPIC_MPLABC__
__OSA_DSPIC_MPLABC__	Same as __OS_PIC24_MPLABC__
__OSA_AVR_WINAVR__
__OSA_AVR_IAR__
__OSA_STM8_COSMIC__

OSA : Project

2011-03-09T17:36:36+03:00

OSA : Project

Creating a project

To use OSA in your application you need to do the following:

Create a project using IDE. In addition to all your project files add the file osa.c to your project (it contains all system variables and function prototypes);
In your project folder create the file OSAcfg.h. This file is used to specify OSA compilation parameters (like number of tasks, timer type etc). In the simplest case this file can be empty. You can use the program OSAcfg_Tool to create/modify this file;
Insert the line "include <osa.h>" into all files that will use OSA services;
Add two "Include search paths" to project options:
- the path to OSAcfg.h for your current project
- the path to osa.h;
At the beginning of function main() insert a call to the OS_Init() service;
At the end of function main() insert a call to the OS_Run() service;

Notes for different IDEs and platforms

MPLAB

To add the osa.c file click right button in Workspace window, and select the "Add file…"
Include-paths are set through project options: menu "Project/Build options/Project…", tab "Directories".

MPLAB and HT-PICC

Old versions of mplab plug-ins for HTPICC did not support the relative paths in Include Directories list, only absolute.
for PRO-version: To provide the compiler with the correct information on call tree, all task functions shpuld be declared in main with the service OS_Task_Define()

void main (void)
{
    OS_Init();
    ...
    OS_Task_Define(Task_Buttons);
    OS_Task_Define(Task_LEDs);
    OS_Task_Define(Task_LCD);
    ...
    OS_Task_Create(Task_Buttons);
    OS_Task_Create(Task_LEDs);
    OS_Task_Create(Task_LCD);
 
}

MPLAB and Mplab C18

Set the library path: menu "Project/Build options/Progect…", tab "Directories", combo "Library Search Path". Enter the path for library files (e.g. c:\mcc18\lib).
In the project options window select the tab "MPLAB C18", category "Optimization" and check off the "Procedural absraction"
Don't forget to add the linker script file: right mouse button on "Linker Script" folder in "Workspace" window and select the .lkr file for your controller (see "MCC18\lkr")

MPLAB and Mplab C30

In the project options window select the tab "MPLAB C30", category "Optimization" and check off the "Procedural absraction"

CCS

don't add the osa.c file into the project
To provide the compiler with the correct information on call tree, all task functions shpuld be declared in main with the service OS_Task_Define()

void main (void)
{
    OS_Init();
    ...
    OS_Task_Define(Task_Buttons);
    OS_Task_Define(Task_LEDs);
    OS_Task_Define(Task_LCD);
    ...
    OS_Task_Create(Task_Buttons);
    OS_Task_Create(Task_LEDs);
    OS_Task_Create(Task_LCD);
 
}

mikroC PRO IDE

To add the osa.c file select menu "Project/Add File To Project…"
Include-path arre set througth menu "Project/Edit Search Paths…". In dialog box there are two path lists: Source Files and Header Files. We need the "Header files". Press "green plus" icon to add include-paths.
The linker must be informed about functions that will be used as tasks:

#pragma funcall main Task_Buttons       // Tell linker that function will be
                                        // called indirectly
 
void Task_Buttons (void)
{
    ...
}

AVR Studio and WinAVR

to add the osa.c file into project do right-click in Workspace window (AVR GCC) on "Source Files" folder and select "Add Existing Source File(s)…"
include-path are set througth menu "Project/Configuration options", tab "Include Directories"

IAR

To add the osa.c file select menu "Project/Add files…"
include-path are set througth menu "Project/Options", category "C/C++ compiler", tab "preprocessor", field "Additional include directories"
Than in tab "Optimization" check off "Cross call"

IAR and STM8

In addition to all requirements described before, add the file "osa\port\stm8\osa_stm_iar.s" into the project

STVD and STM8

to add the osa.c file into project do right-click in Workspace window on the "Source" folder and select "Add Files To Folder…"
include-path are set througth menu "Project/Options", category "C compiler", tab "preprocessor", field "Additional include directories"

Raisonance and STM8

to add the osa.c file select menu "Project/Add Item…"
include-path are set througth menu "Project/Properties", folder "Application Optios", sub-folder "Directories"

OSA : Scheduler

2010-03-10T14:24:18+03:00

OSA : Scheduler

Service OS_Run() - is a macro, that contains infinite loop with scheduler working. This service should be called at the end of main() function. It gives full control to OSA kernel. The scheduler lists all active tasks and looks for ready task with highest priority. When task is found scheduler execute it.

Since OS_Run() is a macro that contains global labels, it can be called in program only once.

Thus you program can be looks like:

void main (void)
{
    OS_Init();
    OS_Task_Create(...);
    OS_Task_Create(...);
    // Create all tasks you need
    // ...
 
    OS_Run();
}

The sheduler lists all active (created by service OS_Task_Create) tasks and finds all ready to execute. Then shedulers compares priorities of all ready tasks and give control to most priority of them. There is one exception: when one of task is in critical section only this task can get control, other tasks are skipped by scheduler in this case.

If while listing all tasks scheduler founds ready task with priority = 0 (highest) then scheduler stops search and give control to this task. This increases speed of scheduler's work (see Inconveniences and Speed characteristics)