PIC24 en:osa:ref:services

OSA services in alphabetical order

2010-06-12T16:34:53+03:00

OSA services in alphabetical order

OSA : Binary semaphores

2009-12-12T02:01:17+03:00

OSA : Binary semaphores

Binary semaphore is a system variable that can accept values 0 and 1. This is simplest way to exchange data between tasks and to synchronize them. All binary semaphores have size of one bit. Programmer can set number of binary semaphores by defining OS_BSEMS constant in OSAcfg.h and system will allocate necessary number of bytes. Therefore memory under binary semaphores reserved on compile stage and their number can't be changed in run-time.

Identification

When working with services controlling binary semaphores it is need to give them semaphore's ID from 0 to OS_BSEMS-1. It is comfortable to assign IDs using enum:

enum OSA_BINSEMS_ENUM
{
    BS_BUTTON_PRESSED,
    BS_USART_FREE,
    BS_WRITE_COMPLETE,
    . . .
};

When using enum we can be sure that each ID is unical.

Work with binary semaphores

After system initialization (OS_Init) all binary semaphores are reseted. Task wich waits binary semaphore will be put into waiting state until binary semaphore will be set.

Here is example of using binary semaphore to accessing common resource - external eeprom:

#include <osa.h>
 
enum OSA_BINSEMS_ENUM {
    BS_EEPROM_FREE
};
 
void Task1 (void)
{
    for (;;) {
        ...
        OS_Bsem_Wait(BS_EEPROM_FREE);     // Wait when EEPROM becames free of other tasks
        // After this service binary semaphore reset automatically
        // thus other task will not get this resource.
 
        // Here we know that EEPROM if free of other tasks.
        eeprom_read(1);
        eeprom_read(2);
        OS_Bsem_Set(BS_EEPROM_FREE);      // After work with EEPROM we free this resource
        ...
    }
}
 
void Task2 (void)
{
    for (;;) {
        ...
        OS_Bsem_Wait(BS_EEPROM_FREE);     // Wait when EEPROM becames free of other tasks
        // After this service binary semaphore reset automatically
        // thus other task will not get this resource.
 
        // Here we know that EEPROM if free of other tasks.
        eeprom_write(5, 10);
        OS_Delay(5);                     // Wait for end of write operation.
                                         // When waiting other tasks are executed. But since
                                         // binary semaphore is reset none of them can start
                                         // to work with EEPROM
        eeprom_write(6, 20);
        OS_Delay(5);
        OS_Bsem_Set(BS_EEPROM_FREE);      // After work with EEPROM we free this resource
        ...
    }
}

Allocation

You can select memory bank to allocate binary semaphores. To do it you need to set constant OS_BANK_BSEMS in OSAcfg.h.

Services for binary semaphores

Service	Arguments	Description
Menagement
OS_Bsem_Set	`(bsem)`	Signal binary semaphore
OS_Bsem_Reset	`(bsem)`	Reset binary semaphore
OS_Bsem_Switch	`(bsem)`	Change binary semaphore's state
Checking
`bool` OS_Bsem_Check	`(bsem)`	Check for binary semaphore is set
Waiting
OS_Bsem_Wait	`(bsem)`	Wait for binary semaphore is set
OS_Bsem_Wait_TO	`(bsem, timeout)`	Wait for binary semaphore is set. Exit if timeout expired.

ALL OSA SERVICES

2010-03-10T15:55:26+03:00

ALL OSA SERVICES

Alphabetical

Third column of table consist service's proprties:

	Service uses system timer
	Do not call from ISR
	Call from task only
	Allowed calls only from task and functions called by task (any deep)
	Switchs context
	Call from ISR only
	Have alternate service for work in ISR (suffix "_I")

System services

Service	Arguments	Description
System
OS_Sched		List all tasks, select ready task with highest priority and run it.
OS_Run		Run operating system's kernel. Calls OS_Sched() in infinite loop.
OS_Init		Init system vars
OS_Timer		Insrease all active timers.
Waiting
OS_Yield		Return to scheduler
OS_Delay	`(delaytime)`	Delay current task for delaytime system ticks
OS_Wait	`(condition)`	Wait for condition is true
OS_Wait_TO	`(condition, timeout)`	Wait for condition is true. Exit if timeout expired.
Checking
`bool` OS_IsTimeout		Return true if timeout occured in previos wait service.
`bool` OS_IsError		Check for error after task creating
`bool` OS_IsEventError		Check for error after work with events
`bool` OS_IsInCriticalSection		Return true if one of task is in critical section
Interrupts
OS_EnterInt		For PICC16 and PICC18: save FSR in the begin of ISR function
OS_LeaveInt		For PICC16 and PICC18: restore saved FSR in the end of ISR function
`char` OS_DI		Disable all interrupts and save previos state of GIEx flags
OS_EI		Enable all interrupts
OS_RI	`(char)`	Restore previosly saved by OS_DI service GIEx flags
OS_EnterCriticalSection		Enter critical section
OS_LeaveCriticalSection		Leave critical section

Task control

Service	Arguments	Description	Properties
Creating/Deleting
OS_Task_Define	`(TaskName)`	For CCS: Tell to compiler that function Taskname is a task and it will be called indirrectly. This service called from main() only	main
OS_Task_Create	`(priority, TaskName)`	Create task and add it to list of active tasks
OS_Task_Replace	`(priority, TaskName)`	Stop and delete current task and create new task
OS_Task_Delete	`(tp)`	Delete task
Menagement
`OST_TASK_POINTER` OS_Task_GetCur		Get pointer to currect task's descriptor
`OST_TASK_POINTER` OS_Task_GetCreated		Get pointer to just created task's descriptor
OS_Task_Pause	`(tp)`	Pause task
OS_Task_Continue	`(tp)`	Continue paused task
`char` OS_Task_GetPriority	`(tp)`	Get priority of task
OS_Task_SetPriority	`(tp, priority)`	Change task's priority
Checking
OS_Task_IsPaused	`(tp)`	Check for task s paused

Binary semaphores

Service	Arguments	Description
Menagement
OS_Bsem_Set	`(bsem)`	Signal binary semaphore
OS_Bsem_Reset	`(bsem)`	Reset binary semaphore
OS_Bsem_Switch	`(bsem)`	Change binary semaphore's state
Checking
`bool` OS_Bsem_Check	`(bsem)`	Check for binary semaphore is set
Waiting
OS_Bsem_Wait	`(bsem)`	Wait for binary semaphore is set
OS_Bsem_Wait_TO	`(bsem, timeout)`	Wait for binary semaphore is set. Exit if timeout expired.

Counting semaphores

Service	Arguments	Description
Creating
OS_Csem_Create	`(csem)`	Create and zero counting semaphore
Menagement
OS_Csem_Signal	`(csem)`	Increase counting semaphore's value by 1 (wait when overflow)
OS_Csem_Signal_Now	`(csem)`	Increase counting semaphore's value by 1 (don't wait when overflow)
OS_Csem_Set	`(csem)`	Set counting semaphore's value to 1.
OS_Csem_SetValue	`(csem, value)`	Set counting semaphore's value to given value.
OS_Csem_Reset	`(csem)`	Zero counting semaphore
Checking
`bool` OS_Csem_Check	`(csem)`	Check for counting semaphore is set (not eq. to 0)
OS_Csem_Accept	`(csem)`	Accept counting semaphore. Decrease it's value by 1.
Waiting
OS_Csem_Wait	`(csem)`	Wait for counting semaphore. Then decrease it's value by 1
OS_Csem_Wait_TO	`(csem, timeout)`	Wait for counting semaphore. Then decrease it's value by 1. Exit if timeout expired

Pointers to messages

Service	Arguments	Description
Creating
OS_Msg_Create	`(msg_cb)`	Create message and zero it.
Sending
OS_Msg_Send	`(msg_cb, message)`	Send message. If message is already exists then wait when it became free.
OS_Msg_Send_TO	`(msg_cb, message, timeout)`	Send message. If message is already exists then wait when it became free. Exit if timeout expired.
OS_Msg_Send_Now	`(msg_cb, message)`	Send message. If message is already exists then it will be overwritten.
Checking
`bool` OS_Msg_Check	`(msg_cb)`	Check for message exists
OS_Msg_Accept	`(msg_cb, os_msg_type_var)`	Accept existing message. After accepting message is set free.
Waiting
OS_Msg_Wait	`(msg_cb, os_msg_type_var)`	Wait for message. After waiting message is set free
OS_Msg_Wait_TO	`(msg_cb, os_msg_type_var, timeout)`	Wait for message. Exit if timeout expired.

Simple messages

Service	Arguments	Description
Creating
OS_Smsg_Create	`(smsg)`	Create and zero simple message
Sending
OS_Smsg_Send	`(smsg, smessage)`	Send simple message. If message already exists then wait when it became free.
OS_Smsg_Send_TO	`(smsg, smessage, timeout)`	Send simple message. If message already exists then wait when it became free. Exit if timeout expired.
OS_Smsg_Send_Now	`(smsg, smessage)`	Send simple message. If message already exists then it will be overwritten.
Checking
`bool` OS_Smsg_Check	`(smsg)`	Check for simple message exists
OS_Smsg_Accept	`(smsg, os_smsg_type_var)`	Accept existing simple message. After accepting message is cleared.
Waiting
OS_Smsg_Wait	`(smsg, os_smsg_type_var)`	Wait for simple message. After accepting simple message is cleared.
OS_Smsg_Wait_TO	`(smsg, os_smsg_type_var, timeout)`	Wait for simple message. After accepting simple message is cleared. Exit if timeout expired.

Queue of pointers to message

Service	Arguments	Description
Creating
OS_Queue_Create	`(queue, buffer, size)`	Create and clear queue.
Sending
OS_Queue_Send	`(queue, message)`	Send message via queue. If queue full then wait for free place
OS_Queue_Send_TO	`(queue, message, timeout)`	Send message via queue. If queue full then wait for free place. Exit if timeout expired.
OS_Queue_Send_Now	`(queue, message)`	Send message via queue. If queue is full then most rearly message will be pushed out.
Checking
`bool` OS_Queue_Check	`(queue)`	Check for there is any message in queue.
`bool` OS_Queue_IsFull	`(queue)`	Check for queue of messages is full.
`bool` OS_Queue_IsEmpty	`(queue)`	Check for queue of messages is empty.
Waiting
OS_Queue_Wait	`(queue, os_msg_type_var)`	Wait message from queue. After accepting message will be deleted from queue.
OS_Queue_Wait_TO	`(queue, os_msg_type_var, timeout)`	Wait message from queue. After accepting message will be deleted from queue. Exit if timeout expired.

Queue of simple messages

Service	Arguments	Description
Creating
OS_Squeue_Create	`(squeue, buffer, size)`	Create and clear queue.
Sending
OS_Squeue_Send	`(squeue, smessage)`	Send simple message via queue. If queue full then wait for free place
OS_Squeue_Send_TO	`(squeue, smessage, timeout)`	Send message via queue. If queue full then wait for free place. Exit if timeout expired.
OS_Squeue_Send_Now	`(squeue, smessage)`	Send message via queue. If queue is full then most rearly message will be pushed out.
Checking
`bool` OS_Squeue_Check	`(squeue)`	Check for there is any simple message in queue.
`bool` OS_Squeue_IsFull	`(squeue)`	Check for queue of simple messages is full.
`bool` OS_Squeue_IsEmpty	`(squeue)`	Check for queue of simple messages is empty.
Waiting
OS_Squeue_Wait	`(squeue, os_smsg_type_var)`	Wait message from queue. After accepting message will be deleted from queue.
OS_Squeue_Wait_TO	`(squeue, os_smsg_type_var, timeout)`	Wait message from queue. After accepting message will be deleted from queue. Exit if timeout expired.

Flags

Service	Arguments	Description
Creating
OS_Flag_Create	`(flags)`	(flag = 0) Create flag and clear all it's bits (flag = 0)
Menagement
OS_Flag_Init	`(flags, value)`	(flag = value) Set flag to givel value
OS_Flag_Set_1	`(flags, mask)`	(flag = flags \| mask) Set bits in flag by given mask
OS_Flag_Set_0	`(flags, mask)`	(flag &= ~mask) Clear bits in flag by given mask
Checking
`bool` OS_Flag_Check_11	`(flags, mask)`	( if ((flag & mask)==mask) ) Check for all bits in flags are set by given mask
`bool` OS_Flag_Check_1x	`(flags, mask)`	( if ((flag & mask)!=0) ) Check for any bit in flags is set by given mask
`bool` OS_Flag_Check_00	`(flags, mask)`	( if ((flag & mask)==0) ) Check for all bits in flag are cleared by given mask
`bool` OS_Flag_Check_0x	`(flags, mask)`	( if ((flag & mask)!=mask) ) Check for any bit in flag is cleared by given mask
Waiting
OS_Flag_Wait_11	`(flags, mask)`	( if ((flag & mask)==mask) ) Wait for all bits in flags are set by given mask
OS_Flag_Wait_1x	`(flags, mask)`	( wait ((flag & mask)!=0) ) Wait for any bit in flags is set by given mask
OS_Flag_Wait_00	`(flags, mask)`	( wait ((flag & mask)==0) ) Wait for all bits in flag are cleared by given mask
OS_Flag_Wait_0x	`(flags, mask)`	( wait ((flag & mask)!=mask) ) Wait for any bit in flag is cleared by given mask
OS_Flag_Wait_11_TO	`(flags, mask, timeout)`	( wait ((flag & mask)==mask) ) Wait for all bits in flags are set by given mask. Exit if timeout expired.
OS_Flag_Wait_1x_TO	`(flags, mask, timeout)`	( wait ((flag & mask)!=0) ) Wait for any bit in flags is set by given mask. Exit if timeout expired.
OS_Flag_Wait_00_TO	`(flags, mask, timeout)`	( wait ((flag & mask)==0) ) Wait for all bits in flag are cleared by given mask. Exit if timeout expired.
OS_Flag_Wait_0x_TO	`(flags, mask, timeout)`	( wait ((flag & mask)!=mask) ) Wait for any bit in flag is cleared by given mask. Exit if timeout expired.

Timers

Task timers

Service	Arguments	Description
Control
OS_Ttimer_Run	`(time)`	Start counting current task's timer
OS_Ttimer_Break	`()`	Stop and reset current task's timer. Timeout flag is set.
OS_Ttimer_Wait	`()`	Wait for current task's timer overflowed
OS_Ttimer_Delay	`(delay)`	Delay using current task's timer (same as OS_Delay)
Checking
`_OST_TTIMER` OS_Ttimer_Get	`()`	Get current task's timer's remaining time
`bool` OS_Ttimer_Check	`()`	Check for current task's timer overflowed
`bool` OS_Ttimer_IsRun	`()`	Check for current task's timer is counting
Additional
OS_Ttimer_Pause	`()`	Pause current task's timer. Overflow bit will be set.
OS_Ttimer_Continue	`()`	Continue counting after pause

Static timers

Service	Arguments	Description
Create/Delete
OS_Stimer_Alloc	`(var_stimer_id)`	Allocate static timer
OS_Stimer_Free	`(stimer_id)`	Free static timer
`bool` OS_Stimer_Found	`()`	Check for free timers enable to allocate
Control
OS_Stimer_Run	`(stimer_id, time)`	Start counting static timer
OS_Stimer_Break	`(stimer_id)`	Stop and reset static timer. Timeout flag is set.
OS_Stimer_Wait	`(stimer_id)`	Wait for static timer overflowed
OS_Stimer_Delay	`(stimer_id, delay)`	Delay current task using static timer
Checking
`_OST_STIMER` OS_Stimer_Get	`(stimer_id)`	Get static timer's remaining time
`bool` OS_Stimer_Check	`(stimer_id)`	Check for static timer overflowed
`bool` OS_Stimer_IsRun	`(stimer_id)`	Check for static timer is counting
Additional
OS_Stimer_Pause	`(stimer_id)`	Pause timer. Overflow bit will be set.
OS_Stimer_Continue	`(stimer_id)`	Continue counting after pause

Queue of timers

Service	Arguments	Description
Creating/Deleting
OS_Qtimer_Create	`(qtimer)`	Add timer in quque of active timers
OS_Qtimer_Delete	`(qtimer)`	Delete timer from queue of active timers
Control
OS_Qtimer_Run	`(qtimer, newtime)`	Start counting with given newtime. Timeout flag is cleared.
OS_Qtimer_Break	`(qtimer)`	Stop timer and delete it from queue. Timeout flag became set.
OS_Qtimer_Wait	`(qtimer)`	Wait for timer will be overflowed
OS_Qtimer_Delay	`(qtimer, delay)`	Delay current task using timer
Checking
`_OST_QTIMER` OS_Qtimer_Get	`(qtimer)`	Get dinamic timer's remaining time.
`bool` OS_Qtimer_Check	`(qtimer)`	Check for timer is overflowed
`bool` OS_Qtimer_IsRun	`(qtimer)`	Check for timer is counting

Old style timers

Dynamic timers

Service	Arguments	Description
Creating/Deleting
OS_Dtimer_Create	`(dtimer)`	Add dynamic timer in list of active timers
OS_Dtimer_Delete	`(dtimer)`	Delete dynamic timer from list of active timers
Control
OS_Dtimer_Run	`(dtimer, newtime)`	Start counting with given newtime. Timeout flag is cleared.
OS_Dtimer_Break	`(dtimer)`	Stop dynamic timer. Timeout flag became set.
OS_Dtimer_Wait	`(dtimer)`	Wait for dynamic timer overflowed
OS_Dtimer_Delay	`(dtimer, delay)`	Delay current task using dynamic timer
Checking
`_OST_DTIMER` OS_Dtimer_Get	`(dtimer)`	Get dinamic timer's remaining time.
`bool` OS_Dtimer_Check	`(dtimer)`	Check for dynamic timer overflowed
`bool` OS_Dtimer_IsRun	`(dtimer)`	Check for dynamic timer is counting
Additional
OS_Dtimer_Pause	`(dtimer)`	Stop/pause dynamic timer. Timeout flag remain unchanged.
OS_Dtimer_Continue	`(dtimer)`	Continue dinamic timer's counting after pause. Timeout flag remain unchanged.
OS_Dtimer_Update	`(dtimer, time)`	Re-run static timer for time time since last overflow. Timeout flag is cleared.
OS_Dtimer_Add	`(dtimer, addtime)`	Increase time of dinamic timer counter. Timeout flag remain unchanged.
`bool` OS_Dtimer_IsActive	`(dtimer)`	Check for dynamic timer present in list of active timers
`bool` OS_Dtimer_IsStopped	`(dtimer)`	Check for dynamic timer is stopped

Old style static timers (not recommended to use)

Service	Arguments	Description
Control
OS_Oldtimer_Run8	`(timer8_id, time)`	Start counting 8-bit timer
OS_Oldtimer_Run16	`(timer16_id, time)`	Start counting 16-bit timer
OS_Oldtimer_Run24	`(timer24_id, time)`	Start counting 24-bit timer
OS_Oldtimer_Run32	`(timer32_id, time)`	Start counting 32-bit timer
OS_Oldtimer_Stop	`(timer_id)`	Stop/pause static timer. Timeout flag is set.
Checking
`bool` OS_Oldtimer_Check	`(timer_id)`	Chek for static timer overflowed
Waiting
OS_Oldtimer_Wait	`(timer_id)`	Wait for static timer overflowed

OSA : Counting semaphores

2009-12-12T02:00:39+03:00

OSA : Counting semaphores

Intro

Counting semaphore is a system variable of type unsigned char, unsigned int or unsigned long (it depends of OS_CSEM_SIZE constant). To use counting semaphores in your program you must define OS_ENABLE_CSEM in OSAcfg.h

General difference between counting and binary semaphores is that counting semaphore can take any value in range from 0 to maximum type's value (255, 65535, 4294967295).

Definition

Here is an example of definition counting semaphore variable:

OST_CSEM  mycsem;

For HT-PICC16 it is allowed to allocate counting semaphores only in bank0 and bank1.

Work

To work with counting semaphore variable it must be created by service OS_Csem_Create. After creation semaphore is zeroed. The value of counting semaphore can be changed with any service of set value group (see below). When task is waiting for cointing semaphore, it will be put in wait mode while semaphore is zero. Once it's value becames non-zero, task will be switched in ready mode. After task will get control, semaphore's value will be decremented by 1.

Attention should be paid that there are two groups of services to change semaphore's value:

to work within task
to work within interrupt service routine (these service have prefix Int)

In order to call the services from interrupt, constant OS_ENABLE_INT should be defined in OSAcfg.h.

Few words about service OS_Csem_Signal. This service increases semaphore's value by 1. If semaphore already set at maxiumm, then its value will remain unchanged and bEventError flag will be set.

Services

Service	Arguments	Description
Creating
OS_Csem_Create	`(csem)`	Create and zero counting semaphore
Menagement
OS_Csem_Signal	`(csem)`	Increase counting semaphore's value by 1 (wait when overflow)
OS_Csem_Signal_Now	`(csem)`	Increase counting semaphore's value by 1 (don't wait when overflow)
OS_Csem_Set	`(csem)`	Set counting semaphore's value to 1.
OS_Csem_SetValue	`(csem, value)`	Set counting semaphore's value to given value.
OS_Csem_Reset	`(csem)`	Zero counting semaphore
Checking
`bool` OS_Csem_Check	`(csem)`	Check for counting semaphore is set (not eq. to 0)
OS_Csem_Accept	`(csem)`	Accept counting semaphore. Decrease it's value by 1.
Waiting
OS_Csem_Wait	`(csem)`	Wait for counting semaphore. Then decrease it's value by 1
OS_Csem_Wait_TO	`(csem, timeout)`	Wait for counting semaphore. Then decrease it's value by 1. Exit if timeout expired

OSA : Critical sections

2009-12-12T01:59:35+03:00

OSA : Critical sections

Intro

Critical sections are used to provide task with some resource inseparably when this resource is used by other tasks. For example some task works with EEPROM and entered critical section to avoid EEPROM data modifiation by other tasks.

In fact, this is rare situation for cooperative RTOS because the programmer switchs context manualy, but still this is possible. So OSA have services to protect critical sections of program.

To aviable work woth critical sections you must to define OS_ENABLE_CRITICAL_SECTION constant in OSAcfg.h.

There are two services to protect program's critical sections:

OS_EnterCriticalSection - to enter critical section
OS_LeaveCriticalSection - to leave critical section

When entering critical section, all interrupts are disabled (their current value stored in internal system flags). Only one task who called service OS_EnterCriticalSection can get control independent of priority, and all other tasks will be blocked until OS_LeaveCriticalSection will be called. When in critical section it still possible to return to schdeuler.

To work with critical sections you need to know some rules written below

GIEx saving

Service OS_EnterCriticaSection saves current GIEx values, and after saving these flags will be cleared. Thus if you call this service twice at one time, then saved GIEx's value at first call will be overwritten with zeroes at second call since after first call GIEx have been cleared. OS_LeaveCriticalSection in this situation will restore zeroed GIEx saved at second call.

Avoid calling service OS_EnterCriticalSection twice at one time.

Timers

You will be able to use task delays (OS_Delay) and waiting with timeout services only if OS_Timer is called not from interrupt (since interrupts are disabled while in critical section). There are two wais of solving this problem:

To enable interrupts manualy after entering critical section (if program architecture allows to use interrupts while in critical section)
To dublicate call of OS_Timer in main cycle (near OS_Sched). See example below:

void interrupt int_routine (void)
{
    OS_EnterInt();
    if (TMR2IF)       // This code will not work in critical section
    {
         TMR2IF = 0;
         OS_Timer();  // This service will be called only outside critical section
    }
    OS_LeaveInt();
}
 
void Task1 (void)
{
    for (;;) {
        . . .
        OS_EnterCriticalSection();
        OS_Delay(100);
        OS_LeaveCriticalSection();
        . . .
    }
}
 
void main (void)
{
    OS_Init();
    OS_Task_Create(0, Task1);
    for (;;)
    {
        OS_Sched();
        if (OS_IsInCriticalSection()) {
            if (TMR2IF) {
                TMR2IF = 0;
                OS_Timer();    // This service will be called within critical section
            }
        }
    }
}

Wait for events

All task except one (who called OS_EnterCriticalSection) are blocked even if their priority is highest and they are ready to run. Thus if task enters critical section and then waits for event that occures in other task, then system will be looped. To avoid this you can first awaiting an event and then enter critical section.

void Task1 (void)
{
    for (;;) {
        . . .
        // Incorrect
        OS_EnterCriticalSection();
        OS_Bsem_Wait(BS_USART_FREE);
        . . .
        // Correct
        OS_Bsem_Wait(BS_USART_FREE);
        OS_EnterCriticalSection();
        . . .
    }
}

Services

Service	Arguments	Description	Properties
`bool` OS_IsInCriticalSection		Return true if one of task is in critical section
OS_EnterCriticalSection		Enter critical section
OS_LeaveCriticalSection		Leave critical section

OSA : Flags

2010-02-27T09:03:52+03:00

OSA : Flags

Intro

Flags are similar to binary semaphores. There are two differences:

you can wait, check, set or reset several flags at one time;
after accepting flags their values do not change.

The using of flags can be usefull when task requires the results of several tasks. For example to calculate some physical parameters task needs information about the temperature, pressure and humidity. Each of these parameters is measured in it's own task and set flag when measuring is complete.

#include <osa.h>
 
OST_FLAG8   F_Sensors;
 
#define  TEMPERATURE_MEASURED   0x01
#define  PRESSURE_MEASURED      0x02
#define  HUMIDITY_MEASURED      0x04
 
void Task_Calc (void)
{
    for (;;) {
        // Wait for all measurings complete
        OS_Flag_Wait_11(F_Sensors, TEMPERATURE_MEASURED | PRESSURE_MEASURED | HUMIDITY_MEASURED);
        OS_Flag_Set_0(F_Sensors, TEMPERATURE_MEASURED | PRESSURE_MEASURED | HUMIDITY_MEASURED);
 
        // Now we can to calculate
        ...
    }
}

Definition

There are three types of flags: 8-, 16- and 32-bit.

OST_FLAG      MyFlag1;	//  8-bit flags
OST_FLAG16    MyFlag2;	// 16-bit flags
OST_FLAG32    MyFlag3;	// 32-bit flags

It is possible to use defferent size of flags at one time.

Flags can be allocated in any memory bank, i.e.:

bank2    OST_FLAG16   MyFlag;

Services

Service	Arguments	Description
Creating
OS_Flag_Create	`(flags)`	(flag = 0) Create flag and clear all it's bits (flag = 0)
Menagement
OS_Flag_Init	`(flags, value)`	(flag = value) Set flag to givel value
OS_Flag_Set_1	`(flags, mask)`	(flag = flags \| mask) Set bits in flag by given mask
OS_Flag_Set_0	`(flags, mask)`	(flag &= ~mask) Clear bits in flag by given mask
Checking
`bool` OS_Flag_Check_11	`(flags, mask)`	( if ((flag & mask)==mask) ) Check for all bits in flags are set by given mask
`bool` OS_Flag_Check_1x	`(flags, mask)`	( if ((flag & mask)!=0) ) Check for any bit in flags is set by given mask
`bool` OS_Flag_Check_00	`(flags, mask)`	( if ((flag & mask)==0) ) Check for all bits in flag are cleared by given mask
`bool` OS_Flag_Check_0x	`(flags, mask)`	( if ((flag & mask)!=mask) ) Check for any bit in flag is cleared by given mask
Waiting
OS_Flag_Wait_11	`(flags, mask)`	( if ((flag & mask)==mask) ) Wait for all bits in flags are set by given mask
OS_Flag_Wait_1x	`(flags, mask)`	( wait ((flag & mask)!=0) ) Wait for any bit in flags is set by given mask
OS_Flag_Wait_00	`(flags, mask)`	( wait ((flag & mask)==0) ) Wait for all bits in flag are cleared by given mask
OS_Flag_Wait_0x	`(flags, mask)`	( wait ((flag & mask)!=mask) ) Wait for any bit in flag is cleared by given mask
OS_Flag_Wait_11_TO	`(flags, mask, timeout)`	( wait ((flag & mask)==mask) ) Wait for all bits in flags are set by given mask. Exit if timeout expired.
OS_Flag_Wait_1x_TO	`(flags, mask, timeout)`	( wait ((flag & mask)!=0) ) Wait for any bit in flags is set by given mask. Exit if timeout expired.
OS_Flag_Wait_00_TO	`(flags, mask, timeout)`	( wait ((flag & mask)==0) ) Wait for all bits in flag are cleared by given mask. Exit if timeout expired.
OS_Flag_Wait_0x_TO	`(flags, mask, timeout)`	( wait ((flag & mask)!=mask) ) Wait for any bit in flag is cleared by given mask. Exit if timeout expired.

OSA : SERVICES

2010-10-07T13:58:41+03:00

OSA : Message queues

2009-12-12T02:05:45+03:00

OSA : Message queues

Intro

The message queue is most universal tool to data exchange between tasks. Queue allow to send next message before previous was received. There are two types of queues in OSA: for pointers to messages and for simple byte messages.

To use queues in you program you have to define constants in OSAcfg.h:

#define OS_ENABLE_QUEUE
                          // To use queues of pointers to messages
#define OS_ENABLE_SQUEUE
                          // To use queues of simple byte messages

When theese constants defined, compiler inserts functions to work with queue in you code.

Queues are declared through variables of queue type: OST_QUEUE and OST_SQUEUE:

OST_QUEUE  queue;    // Declare queue of pointer to messages
OST_SQUEUE squeue;   // Declare queue of simple byte messages

Variable of OST_QUEUE (or OST_SQUEUE) type contains information of queue size, number of existing messages and pointer to buffer of messages. Buffer of messages is an array in RAM where sent messages will be stored to:

OST_MSG   msg_queue[10];         // Buffer for 10 pointer to messages
OST_SMSG  smsg_queue[15];        // Buffer for 15 simple byte messages

To work with queue we have to create it by service OS_Queue_Create (or OS_Squeue_Create):

    OS_Queue_Create(queue, msg_queue, 10);  // Create queue of 10 pointer to messages.
                                         // Sent messages will be stored in msg_queue array

After creating queue we can send and accept messages through queue.

For PIC16 queue descriptor and message buffer can be allocated in bank0 and bank1 only.

Combination

When it is supposed that sizes of OST_MSG and OST_SMSG are same, we can to combine queue functions. This will reduce ROM usage. To do it we have to define constant in OSAcfg.h:

#define OS_QUEUE_SQUEUE_IDENTICAL

Services

Queue of pointers to message

Service	Arguments	Description
Creating
OS_Queue_Create	`(queue, buffer, size)`	Create and clear queue.
Sending
OS_Queue_Send	`(queue, message)`	Send message via queue. If queue full then wait for free place
OS_Queue_Send_TO	`(queue, message, timeout)`	Send message via queue. If queue full then wait for free place. Exit if timeout expired.
OS_Queue_Send_Now	`(queue, message)`	Send message via queue. If queue is full then most rearly message will be pushed out.
Checking
`bool` OS_Queue_Check	`(queue)`	Check for there is any message in queue.
`bool` OS_Queue_IsFull	`(queue)`	Check for queue of messages is full.
`bool` OS_Queue_IsEmpty	`(queue)`	Check for queue of messages is empty.
Waiting
OS_Queue_Wait	`(queue, os_msg_type_var)`	Wait message from queue. After accepting message will be deleted from queue.
OS_Queue_Wait_TO	`(queue, os_msg_type_var, timeout)`	Wait message from queue. After accepting message will be deleted from queue. Exit if timeout expired.

Queue of simple messages

Service	Arguments	Description
Creating
OS_Squeue_Create	`(squeue, buffer, size)`	Create and clear queue.
Sending
OS_Squeue_Send	`(squeue, smessage)`	Send simple message via queue. If queue full then wait for free place
OS_Squeue_Send_TO	`(squeue, smessage, timeout)`	Send message via queue. If queue full then wait for free place. Exit if timeout expired.
OS_Squeue_Send_Now	`(squeue, smessage)`	Send message via queue. If queue is full then most rearly message will be pushed out.
Checking
`bool` OS_Squeue_Check	`(squeue)`	Check for there is any simple message in queue.
`bool` OS_Squeue_IsFull	`(squeue)`	Check for queue of simple messages is full.
`bool` OS_Squeue_IsEmpty	`(squeue)`	Check for queue of simple messages is empty.
Waiting
OS_Squeue_Wait	`(squeue, os_smsg_type_var)`	Wait message from queue. After accepting message will be deleted from queue.
OS_Squeue_Wait_TO	`(squeue, os_smsg_type_var, timeout)`	Wait message from queue. After accepting message will be deleted from queue. Exit if timeout expired.

OSA : Messages

2010-02-01T19:36:03+03:00

OSA : Messages

Intro

Messages is one of way to exchange data between tasks. The message can contain any information: data from USART, external sensorv values, buttons and switches state, ect. There are two types of messages in OSA: pointers to messages and simple byte messages.

Pointer to messages are most universal. Through this type of messages user can send any information of any size. Task send only pointer to this information.

Simple byte messages can accept values form 1 to 255 (0 - message absent). This type of message is realized in OSA to reduce memory usage. Simple byte message needs 1 byte of RAM (pointer to message needs 2 bytes for PIC10, PIC12 and PIC16 and 3 bytes for other).

The message can be in on of two states: free (or absent) and busy (or existing). If message contains information, then it is existing, else it is free.

Pointers to messages

By default the type of pointer to message is void*. User can change it by defining OST_MSG type in OSAcfg.h.:

#define OS_MSG_TYPE   const char *

In this example we tell to compiller that pointer to message will point to data in ROM.

To work with pointer to message we have to create it by service OS_Msg_Create.

There are three services to send message: OS_Msg_Send, OS_Msg_Send_TO and OS_Msg_Send_Now.

OS_Msg_Send first checks for message is free. If it is busy (i.e. previous message was not received by another task yet) then task put in wait state while message will not became free. If message is free, then it can be sent immediately.

OS_Msg_Send_TO - same as OS_Msg_Send with exit if timeout expired while waiting for message is free.

OS_Msg_Send_Now sends message immediately regardless of current message state. If message was busy before calling this service, then it will be overwritten by new data, and system flag OS_IsEventError will be set.

Here is a small example of using pointer to message:

OST_MSG_CB    msg_cb;
 
void Task_USARTReceive (void)
{
    static char BUF[10];        // Buffer for received data from UART
    static char Message[10];    // Message body
 
    OS_Msg_Create(msg_cb);         // First we create message
    for (;;){
        ...
        // Receiving UART data
        ...
        // Wait for message became free
        OS_Cond_Wait(!OS_Msg_Check(msg_cb));
        // When we get here we can be sure that previous message was accepted by another task
        // and Message[] array does not contain any information.
 
        // Copying received data to message buffer
        memcpy(Message, BUF, 10);
        // and sending message
        OS_Msg_Send(msg_cb, (OST_MSG)Message);
        ...
    }
}
 
. . .
 
void Task_Work (void)
{
    OST_MSG msg;
    for (;;) {
        // Waiting for message
        OS_Msg_Wait(msg_cb, msg);
 
        // Now msg points to array Message from Task_USARTReceive
        // After service OS_Msg_Wait message msg_cb becames free
        ...
    }
}

Simple byte messages

By default type of simple byte message is unsigned char. However user can change type of message by defining OST_SMSG in OSAcfg.h:

#define OS_SMSG_TYPE    unsigned long  // change SMSG type

Changing type of simple message we lossing advantage in RAM usage. But it can be usefull in some cases. I.e. when we using pointer to message, we can't modify memory where body of message placed until message will be accepted (array Message[] in previous example). When we using simple message this restriction removed because body of message copied in message variable.

You can not use structures, arrays and unions as type of simple messages. Only enumerabletypes can be used: char, int, long, bit, float and double.

Work with simple messages is similar to pointer to messages. Here is an example of simple byte message using:

OST_SMSG  smsg_Buttons;
. . .
 
void Task_Buttons (void)
{
    OS_Smsg_Create(smsg_Buttons);
    for (;;) {
        . . .
        if (!RB0 || !RB1 || !RB2)
            OS_Smsg_Send(smsg_Buttons, (OST_SMSG)PORTB & 0x07);
        ...
    }
}
 
...
 
void Task_Work (void)
{
    OST_SMSG smsg;
    for (;;) {
        OS_Smsg_Wait(smsg_Buttons, smsg);
        // Processing pressed button
        if (smsg & 0x01) ...;
        if (smsg & 0x02) ...;
        if (smsg & 0x04) ...;
        ...
    }
}

Services

Pointers to messages

Service	Arguments	Description
Creating
OS_Msg_Create	`(msg_cb)`	Create message and zero it.
Sending
OS_Msg_Send	`(msg_cb, message)`	Send message. If message is already exists then wait when it became free.
OS_Msg_Send_TO	`(msg_cb, message, timeout)`	Send message. If message is already exists then wait when it became free. Exit if timeout expired.
OS_Msg_Send_Now	`(msg_cb, message)`	Send message. If message is already exists then it will be overwritten.
Checking
`bool` OS_Msg_Check	`(msg_cb)`	Check for message exists
OS_Msg_Accept	`(msg_cb, os_msg_type_var)`	Accept existing message. After accepting message is set free.
Waiting
OS_Msg_Wait	`(msg_cb, os_msg_type_var)`	Wait for message. After waiting message is set free
OS_Msg_Wait_TO	`(msg_cb, os_msg_type_var, timeout)`	Wait for message. Exit if timeout expired.

Simple messages

Service	Arguments	Description
Creating
OS_Smsg_Create	`(smsg)`	Create and zero simple message
Sending
OS_Smsg_Send	`(smsg, smessage)`	Send simple message. If message already exists then wait when it became free.
OS_Smsg_Send_TO	`(smsg, smessage, timeout)`	Send simple message. If message already exists then wait when it became free. Exit if timeout expired.
OS_Smsg_Send_Now	`(smsg, smessage)`	Send simple message. If message already exists then it will be overwritten.
Checking
`bool` OS_Smsg_Check	`(smsg)`	Check for simple message exists
OS_Smsg_Accept	`(smsg, os_smsg_type_var)`	Accept existing simple message. After accepting message is cleared.
Waiting
OS_Smsg_Wait	`(smsg, os_smsg_type_var)`	Wait for simple message. After accepting simple message is cleared.
OS_Smsg_Wait_TO	`(smsg, os_smsg_type_var, timeout)`	Wait for simple message. After accepting simple message is cleared. Exit if timeout expired.

OSA : System services

2009-12-12T01:57:48+03:00

OSA : System services

Common services

Service	Description	Properties
OS_Init()	Init system variables.

Clears all task descriptors, all binary semaphores and static timers. This service must be called before OS_Run().

Service	Description	Properties
OS_Timer()	Work with all timers

This service must be used if:

some tasks use OS_Delay();
some tasks wait events with timeout;
static or dinamic timers are used in program.

Calling this service is placed into periodical place in program (e.i. TMR0 inttertupt routine).

In this documentation we use a term system tick - period of OS_Timer calling. All delays and timeouts parameters in services are given in system ticks.

Every execution OS_Timer() all active timers are increased by 1 (except 24-bit old style static timers wich are increased 1 type per 256 ticks).

Example of using:

void interrupt isr()
{
 
    if (T0IE && T0IF) {
        TMR0 -= 250;
        T0IF = 0;
        OS_Timer();
    }
}

Service	Description	Properties
OS_Yield ()	Switch context

This service unconditionaly switchs cintext (returns to schoduler) to allow other task to be executed.

Wait services

Service	Description	Properties
OS_Delay (delaytime)	Delay current task by delaytime system ticks

Puts task in waiting state for time given in parameter delaytime.

For example task indicates temperature to the LCD one ime per second. Let OS_Timer period = 10 ms. Task will looks like:

void Task_Indicate (void)
{
    for (;;) {
        OS_Delay(100);	            // Delay = 100 * 10 ms = 1 sec
        IndicateTemerature();	      // Out data to LCD
    }
}

Using this service you must remember that OS_Timer is discrete. So accuracy of all delay is one system tick. If OS_Timer calling interval is 10 ms, then OS_Delay(1) may wait 10 ms, and may wait 0 ms (it depends of at what stage of OS_Timer period OS_Delay was called). Therefore you should either to be sure that length of delay is not important or to decrease system ticks and increase delay value. For example reduce the value of system tick to 1 ms and call OS_Delay(10). Here we can be sure that delay will last for 9-10 ms.

Service	Description	Properties
OS_Wait (condition)	Wait for condition became true

Puts task in waiting state while condition will not became true. Condition is any expression of boolean type. When conditin becames true task becames ready to execute.

    ...
    OS_Wait(m_nInPulseCounter >= 10 || m_bButtonPressed);
    ...

In thi example m_nInPulseCounter and m_bButtonPressed are some external variables that can be set anywhere in program. Task will be in waiting mode while m_nInPulseCounter less than 10 and button not pressed.

Service	Description	Properties
OS_Wait_TO (condition, timeout)	Same as OS_Wait() with exit if timeout expired

Puts task in waiting state while condition will not became true or while timeout will not expired. Timeout value is given in system ticks.

    ...
    OS_Wait_TO(m_bButtonPressed, 100);
    if (OS_IsTimeout()) ...;
    ...

Here we wait button event within 100 system ticks. After exit waiting we check was there timeout or not by service OS_IsTimeout.

System state

All services that check system state return 0 or 1 deending of system state flags.

Service	Description	Properties
bool OS_IsTimeout ()	Check for exit waiting with timeout

This service can be used after waitng some event with timeout to check the reason of exit waiting. If returns 1 then timeout expired and event was not occured. If returns 0 then event occured and there was not timeout.

Service	Description	Properties
bool OS_IsError ()	Check for system error

System errors are:

Task creation error (there is no free descriptor)

Service	Description	Properties
bool OS_IsEventError ()	Check for event error

Event errors are:

Increasing counting semaphore when it already has maximum value
Sending message when it allready exists
Sending message via queue that allready full

Service	Description	Properties
bool OS_IsInCriticalSection ()	Returns 1 if one of tasks is in critical section

Interrupt control services

Service	Description	Properties
OS_EnterInt ()	For PICC16 and PICC18: sould be called in the begin of intterupt routine (saves FSR value)
OS_LeaveInt ()	For PICC16 and PICC18: sould be called in the end of intterupt routine (restores FSR value)

OS_EnterInt calling inserted in the begin of interrupt routine just after definition of local variables. OS_LeaveInt() calling inserted in the end of interrupt just before closing '}'.

void interrupt int_routine (void)
{
    char  var1, var2;
    int   var3;
    OS_EnterInt();
    ...                //
    ...                //
    OS_LeaveInt();
}

Service	Description	Properties
char OS_DI ()	Disable interrupts. Returns current GIEx value
OS_EI ()	Enable all interrupts
OS_RI (char)	Restore GIEx value saved in OS_DI()

Service OS_RI restores only "1" but not "0". If before OS_DI() flag GIE == 0, and after OS_DI() GIE was set by OS_EI(), then OS_RI() will not restore zero value of GIE.

here is example of using these service to generate pulse in 5 cycles:

{
    char gie_temp;
    ...
    gie_temp = OS_DI();
    RB0 = 1;
    NOP();
    NOP();
    NOP();
    NOP();
    RB0 = 0;
    OS_RI(gie_temp);
    ...
}

All system services

Service	Arguments	Description
System
OS_Sched		List all tasks, select ready task with highest priority and run it.
OS_Run		Run operating system's kernel. Calls OS_Sched() in infinite loop.
OS_Init		Init system vars
OS_Timer		Insrease all active timers.
Waiting
OS_Yield		Return to scheduler
OS_Delay	`(delaytime)`	Delay current task for delaytime system ticks
OS_Wait	`(condition)`	Wait for condition is true
OS_Wait_TO	`(condition, timeout)`	Wait for condition is true. Exit if timeout expired.
Checking
`bool` OS_IsTimeout		Return true if timeout occured in previos wait service.
`bool` OS_IsError		Check for error after task creating
`bool` OS_IsEventError		Check for error after work with events
`bool` OS_IsInCriticalSection		Return true if one of task is in critical section
Interrupts
OS_EnterInt		For PICC16 and PICC18: save FSR in the begin of ISR function
OS_LeaveInt		For PICC16 and PICC18: restore saved FSR in the end of ISR function
`char` OS_DI		Disable all interrupts and save previos state of GIEx flags
OS_EI		Enable all interrupts
OS_RI	`(char)`	Restore previosly saved by OS_DI service GIEx flags
OS_EnterCriticalSection		Enter critical section
OS_LeaveCriticalSection		Leave critical section

OSA : Tasks

2010-03-10T15:57:00+03:00

OSA : Tasks

Intro

Task in OSA is C-function. This function must contain infinite loop wich has inside at least one service that switchs task context. Simple task can looks like:

void SimpleTask (void)
{
    for (;;) {      // Inifinite loop
        OS_Yield(); // Unconditional context switching
    }
}

When using mikroC PRO you must tell to linker that function will be called indirrectly by adding #paragma directive, e.g.:

#pragma funcall main SimpleTask

Each task can be in one of five states:

not created
waiting
ready
running
paused

Every task has priority. There are eight priority levels from 0 (highest) to 7 (lowest). Priority can be changed in runtime.(More about priorities and states).

To work with tasks OSA reserves RAM for task descriptors. Number of tasks wich can be active at one time is set by constant OS_TASKS in OSAcfg.h.

Pointer to TCB

Most operations on the task are making through pointer to it's descriptor called tcb (Task Control Block). Task descriptors can not be accessed directly. Bu you can to define a global variable of type OST_TASK_POINTER, wich will point to the descriptor of task.

OST_TASK_POINTER tp_MyTask;

To control task through this variable we must to initialize it by service OS_GetCurTask. Inside task this service returns pointer to current task's descriptor. It is recommended to call this service in the begin of task-function.

void MyTask (void)
{
    tp_MyTask = OS_GetCurTask();
    for (;;) {
        /*...*/
    }
}

Also it is possible to control task by itself. In this case you can use system macro this_task (or service OS_GetCurTask) as the parameter.

void MyTask (void)
{
    for (;;) {
        /*...*/
        OS_Task_SetPriority(this_task, 0);     // set highest priority for current task
        /*...*/
    }
}

Task creation

Task is created by service OS_Task_Create. For example:

#include <osa.h>
 
void Task1 (void)
{
    for (;;)
    {
        OS_Yield()
    }
}
 
...
 
void main (void)
{
    OS_Init();
    OS_Task_Create(7, Task1);
    ...
    for (;;) OS_Sched();
}

In this example we created task from C-function Task1() with lowest priority. After this service worked, operating system will know that function Task1() is a task and will give control to it when it will be ready.

We must to provide service OS_Task_Create with priority even if priority mode disabled (constant OS_DESABLE_PRIORITY is defined in OSAcfg.h).

After OS_Task_Create() executed you can get a pointer to descriptor of created task with service OS_Task_GetCreated (it is usefull when one task will control other task):

    OST_TASK_POINTER  tp;
 
    OS_Task_Create(0, MyTask);
    if (!OS_IsError) tp = OS_Task_GetCreated();

When using CCS all function-tasks should be defined in main() by service OS_Task_Define

Task creation error

If before calling service OS_Task_Create there is no free task descriptor, then task will not be created and system flag OS_IsError will be set.

    OS_Task_Create(7, Task1);
    if (OS_IsError()) ...	;	//

If OS_Task_Create() exits with error then you need to increase constant OS_TASKS in OSAcfg.h and then re-build project. If it is supposed that there must be free decriptor, then you need to serach error in program (e.g. some task had to be stopped but still running).

Task deleting

To delete task (to delete it from list of active task and to free descriptor) you can use service OS_Task_Delete. Before deleting task you should be sure that task free all resources. It is recommended to deleting task by itself only (but OSA services aloows to delete task from any place in program).

Be sure that deleting task free all resources.

After calling OS_Task_Delete task descriptor will be free. If this service called to delete current task (with this_task perameter) then system automatically switchs context. After OS_Task_Delete(this_task) no operators will be executed.

    ...
    OS_Task_Delete(this_task);
    Counter ++;
    ...

In this example variable counter will not be increased.

To stop current task and to run another, first we must to create a new task and after that we can delete current. Elsewere new task will not be created.

    . . .
    OS_Task_Create(1, Task_NewTask);
    OS_Task_Delete(this_task);
    . . .

But this method has a lack: we must have at least one free task descriptor at all times. For example, program of dictaphone consist of several tasks: buttons, indication, recording, playing, battary checking. Here we have 2 tasks that can not be active at one time: recording and playing. Thus at one time only 4 tasks can be active. When we switching from recording task to playing task, first we must to create playing task and than to stop recording. Thus we must have 5 task descriptors for 4 active tasks.

void Task_Play (void)
{
    . . .
    OS_Task_Create(1, Task_Record);
    OS_Task_Delete(this_task);
    . . .
}

In this case several bytes of RAM (used by fifth task descriptor) are not used most of the time. To avoid this problem we can use service OS_Task_Replace:

This service will stop current task and create new in just released descriptor.

    . . .
    OS_Task_Replace(1, Task_Record);
    . . .

Task priority change

We can change priority of tasks in real-time. There are two services to work with task priority: OS_Task_GetPriority and OS_Task_SetPriority.

Task local variables

All active (created) tasks are parallel processes, and you should remember that their local variables may intersect. Thus local variable's value may be lost (rewritten by parallel task) after context switching. To avoid loss of variable's value, it must be declared as static. I.e.:

void Task1 (void)
{
  static char s_cCounter;  // This variable will remain unchanged after context switching
  char i, j;               // Theese variables are temporary. They can be used only within one task
                           // session (from getting control to context switching)
  . . .
}

Services

Service	Arguments	Description	Properties
Creating/Deleting
OS_Task_Define	`(TaskName)`	For CCS: Tell to compiler that function Taskname is a task and it will be called indirrectly. This service called from main() only	main
OS_Task_Create	`(priority, TaskName)`	Create task and add it to list of active tasks
OS_Task_Replace	`(priority, TaskName)`	Stop and delete current task and create new task
OS_Task_Delete	`(tp)`	Delete task
Menagement
`OST_TASK_POINTER` OS_Task_GetCur		Get pointer to currect task's descriptor
`OST_TASK_POINTER` OS_Task_GetCreated		Get pointer to just created task's descriptor
OS_Task_Pause	`(tp)`	Pause task
OS_Task_Continue	`(tp)`	Continue paused task
`char` OS_Task_GetPriority	`(tp)`	Get priority of task
OS_Task_SetPriority	`(tp, priority)`	Change task's priority
Checking
OS_Task_IsPaused	`(tp)`	Check for task s paused

OSA : Timers

2009-12-12T02:07:11+03:00

OSA : Timers

Intro

Timers in OSA are used to simplify writing time-depended code. Using timers you can allocate quantum of time for task, or make delays or timeouts in functions that are not tasks. Timing in OSA is making by OS_Timer service. When calling this service, all active timers incremented by 1. If any timer will overflow, then corresponding timeout bit will be set.

Types of timers in OSA

There are two types of timers in OSA: dynamic and static. Main difference between them is that dinamic timers can be created and deleted in real-time and static are created once on compilation stage and can not be deleted.

The advantage of dinamic timers is that they can be declared in any place of program, thus they can be used in independed program modules. The disadvantage is that they use more RAM and ROM and work slowest than static timers.

The advantage of static timers is that they are fast and use little RAM and ROM. The disadvantage is that their number is fixed and must be set on project stage in OSAcfg.h.

In addition, important difference is that static timer after overflow stops, and dinamic continue counting.

Dynamic timers

Intro

To use dinamic timers in your program you have to define constant in OSAcfg.g:

#define OS_ENABLE_DTIMERS

This will include functions for working with dynamic timers in you code. Variables of dynamic timers are declared using OST_DTIMER type:

OST_DTIMER mytimer;

Variable mytimer contains timer counter, timer's state flags and pointer to next timer in list. Size of timer counter for dynamic timers is set by OS_DTIMER_SIZE constant in OSAcfg.h (By default this constant is equal to OS_TIMER_SIZE).

For PIC16 dynamic timers can be allocated in bank0 and bank1 only.

Timer's states

Dynamic timer can be in one of 4 states:

Not created (or deleted)	The timer is not in list of active timers. The system does not know about it and does not work with it
Active	The timer was created by service OS_Dtimer_Create and was put into list of active timers.
Counting	Every call of OS_Timer service timer's counter will increment by 1. To start counting you can use one of services: OS_Dtimer_Run or OS_Dtimer_Continue.
Stopped	The timer was stopped by OS_Dtimer_Stop service. It is still present in list of active timers, but not counting.

Example

Here is small example of using dynamic timer to generate pulse of given length and with frequency filling. (It supposed that system tick = 1 ms):

OST_SMSG smsg;
 
void Task1 (void)
{
    for (;;) {
        ...
        OS_Smsg_Send(smsg, 200);  // We need 200 ms pulse
        ...
    }
}
 
 
void Task2 (void)
{
    OST_SMSG msg;
    static OST_DTIMER myTimer;
    RB0 = 0;
    OS_Dtimer_Create(myTimer);                 // Create dynamic timer
    for (;;) {
        OS_Smsg_Wait(smsg, msg);               // Wait for message to start pulse
        OS_Dtimer_Run(myTimer, msg);           // Run timer with given value
        do {
            RB0 ^= 1;                         // Generate meander
            OS_Delay(5);	                // Filling frequency = 100 Hz
        } while (!OS_Dtimer_Check(myTimer));   // Wait for timeout
        RB0 = 0;
    }
}

Static timers

Intro

It is recomended to use static timers only when it is nessesary to reduce time of OS_Timer executing, RAM and/or ROM. In all other cases it is recomended to use dynamic timers.

To use static timers in your program you need to set number of timers you want to use in OSAcfg.h:

    #define OS_STIMERS	5

In this example array of 5 timers will be cteated. The size of static timers is set by OS_STIMER_SIZE constant in OSAcfg.h:

    #define OS_STIMER_SIZE   2

(By default this constant is equal to OS_TIMER_SIZE).

The most significant bit of every static timer shows current timers state: =1 - counting, =0 - stopped. Thus size of counter of static timer is 1 bit less then size of OS_STIMER_SIZE. For example, if OS_STIMER_SIZE = 2 bytes, then timer's counter size is 15 bits. You should to notice it when forming delays.

To work with static timers we provide all services by timer's identification number as parameter. It is comfortable to enumerate all static timers through enum:

enum OSA_STIMERS_ENUM
{
    ST_TIMER0,
    ST_TIMER1,
    ST_TIMER2,
    ST_TIMER3
}

The state and value of static timers are undefined after OS_Init() execution.

Example

Static timers can be applied to forming delays in low-RAM controllers. For example, we run 6 tasks under PIC10F222 and only 2 of them use service OS_Delay. If we use task's timers, then 4 variables (timers in four of si tasks) are not used. Thus we lose 4 (or more) bytes of memory. Using static timers we can avoid losing RAM. We can to declare only 2 static timers (one for each task). In this case we get the advantage of speed (OS_Timer will work with two timers instead 6), RAM (four task timers are deleted) and ROM (functions for task timers are deleted).

Note: this substitution is possible for forming delays only. Static timers can't be used for events waiting with timeouts.

Here is example of forming delay in task using static timer:

// OAScfg.h
#define OS_STIMERS  1
 
enum OS_STIMERS_ENUM {
   ST_MyTimer           // Static timer's ID
}
 
------------------------------------------------------------
 
// Fragment of program (it is supposed that system tick = 1 ms)
 
void Task1 (void)
{
  for (;;) {
    ...
    OS_Stimer_Delay(ST_MyTimer, 100);  // 100 ms delay
    ...
  }
}

Maximum delay values

Here are maximum possible time intervals that static timers can count for most often system ticks used:

OS_Timer's period	1 byte	2 bytes	4 bytes
Range:	0-128	0-32768	0-2147483648
1 ms	128 ms	32 sec	24 days
10 ms	1.2 sec	5 min	245 days
18.2 ms	4.6 sec	9 min	450 days
256 us	65 ms	8 sec	6 days
1024 us	260 ms	33 sec	25 days
8192 us	2 sec	4 min	200 days

Services

Dynamic timers

Service	Arguments	Description
Creating/Deleting
OS_Dtimer_Create	`(dtimer)`	Add dynamic timer in list of active timers
OS_Dtimer_Delete	`(dtimer)`	Delete dynamic timer from list of active timers
Menagement
OS_Dtimer_Run	`(dtimer, newtime)`	Start counting with given newtime. Timeout flag is cleared.
OS_Dtimer_Stop	`(dtimer)`	Stop/pause dynamic timer. Timeout flag remain unchanged.
OS_Dtimer_Pause	`(dtimer)`	Same as OS_Dtimer_Stop
OS_Dtimer_Break	`(dtimer)`	Stop dynamic timer. Timeout flag became set.
OS_Dtimer_Continue	`(dtimer)`	Continue dinamic timer's counting after pause. Timeout flag remain unchanged.
OS_Dtimer_Update	`(dtimer, time)`	Re-run static timer for time time since last overflow. Timeout flag is cleared.
OS_Dtimer_Add	`(dtimer, addtime)`	Increase time of dinamic timer counter. Timeout flag remain unchanged.
Checking
`_OST_DTIMER` OS_Dtimer_Get	`(dtimer)`	Get dinamic timer's remaining time.
`bool` OS_Dtimer_Check	`(dtimer)`	Check for dynamic timer overflowed
`bool` OS_Dtimer_IsActive	`(dtimer)`	Check for dynamic timer present in list of active timers
`bool` OS_Dtimer_IsStopped	`(dtimer)`	Check for dynamic timer is stopped
`bool` OS_Dtimer_IsRun	`(dtimer)`	Check for dynamic timer is counting
Waiting
OS_Dtimer_Wait	`(dtimer)`	Wait for dynamic timer overflowed
OS_Dtimer_Delay	`(dtimer, delay)`	Delay current task using dynamic timer

Static timers

Service	Arguments	Description
Menagement
OS_Stimer_Run	`(stimer_id, time)`	Start counting static timer
OS_Stimer_Stop	`(stimer_id)`	Stop/pause static timer. Timeout flag is set.
OS_Stimer_Pause	`(stimer_id)`	Same as OS_Stimer_Stop
OS_Stimer_Continue	`(stimer_id)`	Continue counting after pause
Checking
`_OST_STIMER` OS_Stimer_Get	`(stimer_id)`	Get static timer's remaining time
`bool` OS_Stimer_Check	`(stimer_id)`	Check for static timer overflowed
`bool` OS_Stimer_IsRun	`(stimer_id)`	Check for static timer is counting
Waiting
OS_Stimer_Wait	`(stimer_id)`	Wait for static timer overflowed
OS_Stimer_Delay	`(stimer_id, delay)`	Delay current task using static timer