os_applAPI.h File Reference

#include "cocoos.h"

Go to the source code of this file.

Macros
#define	task_open()   OS_BEGIN
#define	task_close()   OS_END
#define	task_wait(x)   OS_WAIT_TICKS(x,0)
#define	task_wait_id(id, x)   OS_WAIT_TICKS(x,id)
#define	task_suspend(id)   OS_SUSPEND_TASK( id )
#define	task_resume(id)   OS_RESUME_TASK( id )
#define	event_wait(event)   OS_WAIT_SINGLE_EVENT(event,0)
#define	event_wait_timeout(event, timeout)   OS_WAIT_SINGLE_EVENT(event,timeout)
#define	event_get_timeout()   OS_GET_TASK_TIMEOUT_VALUE()
#define	event_wait_multiple(waitAll, args...)   OS_WAIT_MULTIPLE_EVENTS( waitAll, args)
#define	event_signal(event)   OS_SIGNAL_EVENT(event)
#define	event_ISR_signal(event)   OS_INT_SIGNAL_EVENT(event)
#define	sem_wait(sem)   OS_WAIT_SEM(sem)
#define	sem_signal(sem)   OS_SIGNAL_SEM(sem)
#define	sem_ISR_signal(sem)   OS_SIGNAL_SEM_NO_SCHEDULE(sem)
#define	msg_post(task_id, msg)   OS_MSG_Q_POST(task_id, msg, 0, 0, 0)
#define	msg_post_async(task_id, msg)   OS_MSG_Q_POST(task_id, msg, 0, 0, 1)
#define	msg_post_in(task_id, msg, delay)   OS_MSG_Q_POST(task_id, msg, delay, 0, 0)
#define	msg_post_every(task_id, msg, period)   OS_MSG_Q_POST(task_id, msg, period, period, 0)
#define	msg_receive(task_id, pMsg)   OS_MSG_Q_RECEIVE( task_id, pMsg, 0 )
#define	msg_receive_async(task_id, pMsg)   OS_MSG_Q_RECEIVE( task_id, pMsg, 1 )

Functions
void	os_init (void)
void	os_start (void)
void	os_tick (void)
void	os_sub_tick (uint8_t id)
void	os_sub_nTick (uint8_t id, uint16_t nTicks)
uint8_t	os_get_running_tid (void)
uint8_t	task_create (taskproctype taskproc, void *data, uint8_t prio, Msg_t *msgPool, uint8_t poolSize, uint16_t msgSize)
void	task_kill (uint8_t tid)
void *	task_get_data ()
Sem_t	sem_bin_create (uint8_t initial)
Sem_t	sem_counting_create (uint8_t max, uint8_t initial)
Evt_t	event_create (void)
uint8_t	event_signaling_taskId_get (Evt_t ev)
TaskState_t	task_state_get (uint8_t tid)
void	os_cbkSleep (void)

Detailed Description

cocoOS API header file

Macro Definition Documentation

#define event_get_timeout

(

)

OS_GET_TASK_TIMEOUT_VALUE()

Get the timeout value from the task when we wait for an event with timeout. That way we know if this is due to a timeout (value == 0) or actual event (value != 0)

Remarks

Usage:

Evt_t myEvent;
main() {
 ...
 myEvent = event_create();
 ...
}

static void myTask(void) {
 task_open();
  ...
  event_wait_timeout( myEvent, 100 );
  if( event_get_timeout() == 0 ) {
    // timeout - the event was not signaled.
  }
  else {
    // the event was signaled
  }

  ...
 task_close();
}

#define event_ISR_signal

(

event

)

OS_INT_SIGNAL_EVENT(event)

Macro for signalling an event from an ISR

Parameters

event

the event to be signalled

Remarks

Usage:

Evt_t evRxChar;
main() {
 ...
 evRxChar = event_create();
 ...
}

ISR (SIG_UART_RECV) {   
    rx.data[ rx.head ] = UDR;
    event_ISR_signal( evRxChar );
}

#define event_signal

(

event

)

OS_SIGNAL_EVENT(event)

Macro for signalling an event.

Parameters

event

the event to be signalled

Remarks

Usage:

Evt_t myEvent;
main() {
 ...
 myEvent = event_create();
 ...
}

static void myTask(void) {
 task_open();   
  ...
  event_signal( myEvent );
  ...
 task_close();
}

#define event_wait

(

event

)

OS_WAIT_SINGLE_EVENT(event,0)

Macro for wait for a single event.

Parameters

event

the event to wait for

Remarks

Usage:

Evt_t myEvent;
main() {
 ...
 myEvent = event_create();
 ...
}

static void myTask(void) {
 task_open();   
  ...
  event_wait( myEvent );
  ...
 task_close();
}

#define event_wait_multiple	(		waitAll,
			args...
	)		OS_WAIT_MULTIPLE_EVENTS( waitAll, args)

Macro for wait for multiple events.

Parameters

waitAll	1 if wait for all, 0 if wait for any event
args	list of Evt_t type events

Remarks

Usage:

Evt_t myEvent1;
Evt_t myEvent2;
Evt_t myEvent3;
main() {
 ...
 myEvent1 = event_create();
 myEvent2 = event_create();
 myEvent3 = event_create();
 ...
}

static void myTask(void) {
 task_open();   
  ...
  event_wait_multiple(1, myEvent1, myEvent2, myEvent3);
  ...
 task_close();
}

#define event_wait_timeout	(		event,
			timeout
	)		OS_WAIT_SINGLE_EVENT(event,timeout)

Macro for wait for a single event to be signaled or a timeout to occur.

Parameters

event	the event to wait for
timeout	maximum wait time in main clock ticks, 16bit value. If timeout = 0, no timeout will be used, and the task will wait forever until the event is signaled.

Remarks

Usage:

Evt_t myEvent;
main() {
 ...
 myEvent = event_create();
 ...
}

static void myTask(void) {
 task_open();   
  ...
  event_wait_timeout( myEvent, 100 );
  ...
 task_close();
}

#define msg_post	(		task_id,
			msg
	)		OS_MSG_Q_POST(task_id, msg, 0, 0, 0)

Posts a message to the message queue of a task.

Parameters

task_id	id of the task that will receive the message
msg	the message to post

Returns

None

Remarks

Performs synchronized message posting, i.e the first task waits for the queue to be available before posting. If the message queue is full, the queue is released and the task wait until it becomes non-full.
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;

 
static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task1(void) {
    static LedMsg_t ledMsg;

    ledMsg.super.signal = LED_SIG;
    ledMsg.led = 5;
    
    task_open();
    
    for (;;) {
        
        task_wait( 3000 );

        msg_post( taskId2, ledMsg );

    }

    task_close();

}

#define msg_post_async	(		task_id,
			msg
	)		OS_MSG_Q_POST(task_id, msg, 0, 0, 1)

Posts a message to the message queue of a task. If the queue is full, the message is not posted and the task continues execution, i.e. it will not wait for the queue to be non-full.

Parameters

task_id	id of the task that will receive the message
msg	the message to post

Returns

None
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;


static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task1(void) {
    static LedMsg_t ledMsg;

    ledMsg.super.signal = LED_SIG;
    ledMsg.led = 5;

    task_open();

    for (;;) {

        task_wait( 3000 );

        msg_post_async( taskId2, ledMsg );

    }

    task_close();

}

#define msg_post_every	(		task_id,
			msg,
			period
	)		OS_MSG_Q_POST(task_id, msg, period, period, 0)

Posts a periodic message to the message queue of a task. The message will be delivered to the receiver task each time the timer expires. The period is related to the master clock.

Parameters

task_id	id of the task that will receive the message
msg	the message to post
period	period time in master clock ticks

Returns

None
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;

 
static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task1(void) {
    static LedMsg_t ledMsg;

    ledMsg.super.signal = LED_SIG;
    ledMsg.led = 5;

    msg_post_every( taskId2, ledMsg, 100 );
  
    task_open();
    
    for (;;) {
        ...
        ...
        task_wait( 3000 );
    }

    task_close();

}

#define msg_post_in	(		task_id,
			msg,
			delay
	)		OS_MSG_Q_POST(task_id, msg, delay, 0, 0)

Posts a message to the message queue of a task. The message will be received by the receiver task when the delay has expired. The delay is related to the master clock.

Parameters

task_id	id of the task that will receive the message
msg	the message to post
delay	post delay time in master clock ticks

Returns

None
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;

 
static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task1(void) {
    static LedMsg_t ledMsg;

    ledMsg.super.signal = LED_SIG;
    ledMsg.led = 5;
    
    task_open();
    
    for (;;) {
        
        task_wait( 3000 );

        msg_post_in( taskId2, ledMsg, 100 );

    }

    task_close();

}

#define msg_receive	(		task_id,
			pMsg
	)		OS_MSG_Q_RECEIVE( task_id, pMsg, 0 )

Receives a message from the queue

Parameters

task_id	id of the current task
pMsg	pointer to a message that will receive a message from the queue

Returns

None

Remarks

Performs synchronized message receiveing. The task first waits for the message queue to be available. Then it checks for a message. If the queue is empty, the queue is released and the tasks waits for a message to be posted by another task.
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;

 
static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task2(void) {
    static LedMsg_t msg;
    uint8_t led;
    task_open();
    
    for (;;) {
        
        msg_receive( taskId2, &msg );

        if ( msg.super.signal == LED_SIG ) {
            led = msg.led;
            LED_TOGGLE( led );
        } 
    }

    task_close();

}

#define msg_receive_async	(		task_id,
			pMsg
	)		OS_MSG_Q_RECEIVE( task_id, pMsg, 1 )

Receives a message from the queue but returns immediately if queue is empty.

Parameters

task_id	id of the current task
pMsg	pointer to a message that will receive a message from the queue. If queue is empty, the signal member of the message pointed at by pMsg will be set to NO_MSG_ID.

Returns

None
Usage:

typedef struct {
    Msg_t super;
    uint8_t led;
} LedMsg_t;


static LedMsg_t msgpool_1[ 16 ];
static uint8_t taskId1;
static uint8_t taskId2;

int main(void)
{
    ...
    taskId1 = task_create( task1, 1, NULL, 0 );
    taskId2 = task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
    ...
    os_start();
    return 0;
}


static void task2(void) {
    static LedMsg_t msg;
    uint8_t led;
    task_open();

    for (;;) {

        task_wait( 3000 );

        msg_receive_async( taskId2, &msg );

        if ( msg.super.signal == LED_SIG ) {
            led = msg.led;
            LED_TOGGLE( led );
        }
        else if ( msg.super.signal == NO_MSG_ID ) {
            
        }
    }

    task_close();

}

#define sem_ISR_signal

(

sem

)

OS_SIGNAL_SEM_NO_SCHEDULE(sem)

Macro for releasing a semaphore from within an ISR. The semaphore is signalled and waiting tasks will be set to ready state, but scheduling will not be done. Scheduling will be performed when the ISR has finished and the interrupted task calls a scheduling function.

Parameters

sem	Semaphore.

Remarks

Usage:

Sem_t mySem;
main() {
 ...
 mySem = sem_create( 0 );
 ...
}

ISR(void) {

  ...
  sem_ISR_signal( mySem );
  ...

}

#define sem_signal

(

sem

)

OS_SIGNAL_SEM(sem)

Macro for releasing a semaphore.

Parameters

sem	Semaphore.

Remarks

Usage:

Sem_t mySem;
main() {
 ...
 mySem = sem_create( 0 );
 ...
}

static void myTask(void) {
 task_open();   
  ...
  sem_signal( mySem );
  ...
 task_close();
}

#define sem_wait

(

sem

)

OS_WAIT_SEM(sem)

Macro for aquiring a semaphore.

Parameters

sem	Semaphore.

Remarks

Usage:

Sem_t mySem;
main() {
 ...
 mySem = sem_create( 0 );
 ...
}

static void myTask(void) {
 task_open();   
  ...
  sem_wait( mySem );
  ...
 task_close();
}

#define task_close

(

)

OS_END

Macro for definition of task end.

Remarks

Usage: Should be placed at the end of the task procedure

static void myTask(void) {
 static uint8_t i;
 task_open();   
  ...
  task_wait( 10 );
  ...
 task_close();
}

#define task_open

(

)

OS_BEGIN

Macro for definition of task beginning.

Remarks

Usage: Should be placed at the beginning of the task procedure

static void myTask(void) {
 static uint8_t i;
 task_open();   
  ...
  task_wait( 10 );
  ...
 task_close();
}

#define task_resume

(

id

)

OS_RESUME_TASK( id )

Macro for resuming a task

Parameters

id	of the task to resume

Remarks

The macro has no effect if the task is not in the SUSPENDED state. If the task was waiting for a semaphore when it was suspended, the task will be reset and execution will restart from the task procedure top.
Usage:

uint8_t ledTask_id;

static void led_task(void) {
 task_open();   
  for(;;) {
    led_toggle();
    task_wait( 100 );
  }
 task_close();
}


static void button_task(void) {
 task_open();
 for (;;) {
     if ( button_1_Pressed ) {
       task_suspend( ledTask_id );
     }
     else if ( button_2_Pressed ){
       task_resume( ledTask_id );
     }
 }
 task_close();
}


int main( void ) {
    ...
    ledTask_id = task_create( led_task, 1, msgPool, POOL_SIZE, sizeof(Msg_t) );
    task_create( button_task, 2, NULL, 0, 0 );
    ...
}

#define task_suspend

(

id

)

OS_SUSPEND_TASK( id )

Macro for suspending a task

Parameters

id	of the task to suspend

Remarks

If the task to suspend is the same as the current running task, the task is immediately suspended and other tasks are scheduled to execute. If the task to suspend is another than the current task, that task is immediately put in suspended state, and the current task continues to execute.
Usage:

static Msg_t msgPool[ POOL_SIZE ];
uint8_t task1_id;
uint8_t task2_id;

static void led_task(void) {
 task_open();   
  for(;;) {
    led_toggle();
    task_wait( 100 );
  }
 task_close();
}


static void button_task(void) {
 task_open();
 for (;;) {
    if ( buttonPressed ) {
        task_suspend( task1_id );
    }
    task_wait(10);
 }
 task_close();
}


int main( void ) {
    ...
    task1_id = task_create( led_task, 1, msgPool, POOL_SIZE, sizeof(Msg_t) );
    task2_id = task_create( button_task, 2, NULL, 0, 0 );
    ...
}

#define task_wait

(

x

)

OS_WAIT_TICKS(x,0)

Macro for suspending a task a specified amount of ticks of the master clock. When the wait time has expired, the task is ready to execute again and will continue at the next statement when the task is scheduled to run.

Parameters

x	Number of master clock ticks to wait.

Remarks

Usage:

static void myTask(void) {
 task_open();   
  ...
  task_wait( 10 );
  ...
 task_close();
}

#define task_wait_id	(		id,
			x
	)		OS_WAIT_TICKS(x,id)

Macro for suspending a task a specified amount of ticks of a sub clock. When the wait time has expired, the task is ready to execute again and will continue at the next statement when the task is scheduled to run.

Parameters

id	Sub clock id. Valid range 1-255.
x	Number of sub clock ticks to wait, 16 bit value.

Remarks

Usage:

static void myTask(void) {
 task_open();   
  ...
  task_wait_id( 2, 10 );
  ...
 task_close();
}

Function Documentation

Evt_t event_create

(

void

)

Creates an event.

Returns

Returns an event.

Remarks

Usage:
An event is created by declaring a variable of type Evt_t and then assigning the event_create() return value to that variable.

Evt_t myEvent;
myEvent = event_create();

uint8_t event_signaling_taskId_get

(

Evt_t

ev

)

Gets the Task Id of the task that signaled the event.

Parameters

ev

event

Returns

Id of task that signaled the event.

NO_TID if a timeout occurred before the event was signaled.

Remarks

Usage:
A task can make a call to this function when it has resumed execution after waiting for an event to find out which other task signaled the event.

event_wait(event);
signalingTask = event_signaling_taskId_get(event);
if ( signalingTask == Task2_id ) {
  ...
}

void os_cbkSleep

(

void

)

Callback called by the os kernel when all tasks are in waiting state. Here you can put the MCU to low power mode. Remember to keep the clock running so we can wake up from sleep.

void os_init

(

void

)

Initializes the scheduler.

Returns

None.

Remarks

Usage:
Should be called early in system setup, before starting the task execution

int main(void) {
system_init();
os_init();
...
}

void os_start

(

void

)

Starts the task scheduling

Returns

None.

Remarks

Usage:
Should be the last line of main.

int main(void) {
  system_init();
  os_init();
  task_create( myTaskProc, 1, NULL, 0, 0 );
  ...
  os_start();
  return 0;
}

void os_sub_nTick	(	uint8_t	id,
		uint16_t	nTicks
	)

Tick function driving the sub clocks. Increments the tick count with nTicks.

Parameters

id	sub clock id, allowed range 1-255.
nTicks	increment size, 16 bit value.

Returns

None.

Remarks

Usage:
Could be called at any desired rate to trigger timeouts. Called from a task or from an interrupt ISR.

ISR(SIG_OVERFLOW0) {
  ...
  os_sub_nTick( 2, 10 );
}

void os_sub_tick

(

uint8_t

id

)

Tick function driving the sub clocks

Parameters

id	sub clock id, allowed range 1-255

Returns

None.

Remarks

Usage:
Could be called at any desired rate to trigger timeouts. Called from a task or from an interrupt ISR.

ISR(SIG_OVERFLOW0) {
  ...
  os_sub_tick(2);
}

void os_tick

(

void

)

Tick function driving the kernel

Returns

None.

Remarks

Usage:
Should be called periodically. Preferably from the clock tick ISR.

ISR(SIG_OVERFLOW0) {
  ...
  os_tick();
}

Sem_t sem_bin_create

(

uint8_t

initial

)

Creates and initializes a new binary semaphore.

Parameters

initial

value of the semaphore

Returns

Returns the created semaphore.

Remarks

Usage:
A semaphore is created by declaring a variable of type Sem_t and then assigning the sem_bin_create(value) return value to that variable.

Sem_t mySem;
mySem = sem_bin_create(0);

Sem_t sem_counting_create	(	uint8_t	max,
		uint8_t	initial
	)

Creates and initializes a new counting semaphore.

Parameters

max	value of the semaphore
initial	value of the semaphore

Returns

Returns the created semaphore.

Remarks

Usage:
A semaphore is created by declaring a variable of type Sem_t and then assigning the sem_create(max, 0) return value to that variable.

Sem_t mySem;
mySem = sem_counting_create(5,0);

uint8_t task_create	(	taskproctype	taskproc,
		void *	data,
		uint8_t	prio,
		Msg_t *	msgPool,
		uint8_t	poolSize,
		uint16_t	msgSize
	)

Creates a task scheduled by the os. The task is put in the ready state.

Parameters

taskproc	Function pointer to the task procedure.
data	[optional] Pointer to task data
prio	Task priority on a scale 0-255 where 0 is the highest priority.
msgPool	[optional] Pointer to the message pool, containing messages. Ignored if poolSize is 0.
poolSize	[optional] Size, in nr of messages, of the message pool. Set to 0 if no message pool needed for the task
msgSize	[optional] Size of the message type held in the message queue

Returns

Task id of the created task.

Remarks

Usage:
Should be called early in system setup, before starting the task execution. Only one task per priority level is allowed.

    static uint8_t taskId;
    static Msg_t msgpool_1[ POOL_SIZE ];

int main(void) {
    system_init();
    os_init();
    taskId = task_create( myTaskProc, 0, 1, msgpool_1, POOL_SIZE, sizeof(Msg_t) );
    ...
}

void* task_get_data

(

)

Gets a pointer to the data structure associated with the task

Returns

pointer to task data

static uint32_t taskData;

static void taskProc(void)
{
  task_open();
  for (;;) {
    task_wait( 100 );
    uint32_t *data = (uint32_t*)task_get_data();
    *data++;
  }
  task_close();
}

int main() {
   ...
   task_create(taskProc, (void*)&taskData, ...);
   ...
}

void task_kill

(

uint8_t

tid

)

Puts the task associated with the specified id in the killed state. A killed task, cannot be resumed.

Parameters

task_id

id of the task.

Returns

None

static uint8_t taskId;

static void waitingTask(void)
{
    task_open();

    event_wait( event );

    if ( event_signaling_taskId_get( event ) == taskId ) {
        task_kill( taskId );
    }

    task_close();

}


static void signalingTask1(void)
{
    task_open();    
    
    task_wait( 900 );
       
    event_signal(event);

    task_close();

}

int main() {
   ...
   taskId = task_create(signalingTask1, ...);
   ...
}