Available Languages?:

OSA : System services

Common services

Service Description Properties
OS_Init() Initialize 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:

  • any task uses OS_Delay();
  • any task waits for events with timeout;
  • static or dynamic timers are used in the program.

This service should be called from e.g. the TMR0 interrupt routine.

In this documentation we use the term system tick to mean the period between calls to OS_Timer. All delay and timeout parameters in services are given in system ticks.

At every execution of OS_Timer() all active timers are increased by 1 (except 24-bit old style static timers which are increased by 1 per 256 ticks).

Example of usage:

void interrupt isr()
{
    if (T0IE && T0IF) {
        TMR0 -= 250;
        T0IF = 0;
        OS_Timer();
    }
}
Service Description Properties
OS_Yield () Switch context

This service unconditionally switches context (returns to the scheduler) to allow other tasks to be executed.

Wait services

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

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

For example, a task indicates temperature to the LCD once per second. Let OS_Timer period = 10 ms. Task will look like:

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

Using this service you must remember that OS_Timer is discrete. So the resolution of all delays is one system tick. If the OS_Timer calling interval is 10 ms, then OS_Delay(1) may wait 10 ms, or may wait 0 ms (depending on what time within the OS_Timer period OS_Delay was called).

Therefore you should either be sure that the length of delay is not important or decrease the size of a system tick and increase the delay value. For example, you could reduce the size of a 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 to become true

Puts task in waiting state while condition is false. The condition is any expression of boolean type. When the condition becomes true, the task becomes ready to execute.

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

In this example m_nInPulseCounter and m_bButtonPressed are external variables that can be set anywhere in the program. The task will be in waiting state while m_nInPulseCounter is less than 10 and the button is not pressed.


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

Puts task in wait state while condition is false and timeout has not expired. Timeout value is given in system ticks.

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

Here we wait for a button event within 100 system ticks. After exiting the wait, we check if there was a timeout or not by using the service OS_IsTimeout.

System state

All services that check system state return 0 or 1 depending on system state flags.

Service Description Properties
bool OS_IsTimeout () Check if exit from wait was due to timeout

This service can be used after waiting for some event with timeout, to check why the exit occurred. If it returns 1 then the timeout expired and event did not occur. If it returns 0 then the event occurred and there was no timeout.

Service Description Properties
bool OS_IsError () Check if system error

System errors are:

  • Task creation error (there is no free descriptor)
Service Description Properties
bool OS_IsEventError () Check if event error

Event errors are:

  • Increasing counting semaphore when it already has maximum value
  • Sending message when it already exists
  • Sending message via queue that is already full
Service Description Properties
bool OS_IsInCriticalSection () Returns 1 if any task is in critical section

Interrupt control services

Service Description Properties
OS_EnterInt () For PICC16 and PICC18: should be called at the beginning of interrupt routine (saves FSR value)
OS_LeaveInt () For PICC16 and PICC18: should be called at the end of interrupt routine (restores FSR value)

A call to OS_EnterInt should be inserted at the start of an interrupt routine, just after definition of local variables. A call to OS_LeaveInt() should be inserted at the end of an interrupt routine, just before the 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 by OS_DI()

Service OS_RI restores only "1" bits, not "0" bits. 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 an example of using these services to generate a pulse of 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 Properties
System
OS_Sched Scan all tasks, select ready task with the highest priority and run it
OS_Run Run operating system's kernel. Calls OS_Sched() in infinite loop
OS_Init Initialize system variables Not allowed in interrupt
OS_Timer Increase all active timers
Waiting
OS_Yield Return to the scheduler Allowed only in taskSwitches context
OS_Delay (delaytime) Delay current task for delaytime system ticks Allowed only in taskSwitches contextService uses system timer
OS_Wait (condition) Wait for condition to become true Allowed only in taskSwitches context
OS_Wait_TO (condition, timeout) Wait for condition to become true. Exit if timeout expired Allowed only in taskSwitches contextService uses system timer
Checking
bool
OS_IsTimeout
Return true if timeout occurred in previous wait service Service uses system timer
bool
OS_IsError
Check if error after task creation
bool
OS_IsEventError
Check if error after using events
bool
OS_IsInCriticalSection
Return true if any task is in critical section
Interrupts
OS_EnterInt For PICC16 and PICC18: save FSR at the beginning of an ISR function Only inside interrupt
OS_LeaveInt For PICC16 and PICC18: restore saved FSR at the end of an ISR function Only inside interrupt
char
OS_DI
Disable all interrupts and save previous state of GIEx flags Not allowed in interrupt
OS_EI Enable all interrupts Not allowed in interrupt
OS_RI (char) Restore GIEx flags previously saved by OS_DI service Not allowed in interrupt
OS_EnterCriticalSection Enter critical section Allowed only in task
OS_LeaveCriticalSection Leave critical section Allowed only in task
 
en/osa/ref/services/system_services.txt · Last modified: 07.10.2010 13:58 (external edit)
 
Creative Commons License Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki