cocoOS  4.0.0
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_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, msg)   OS_MSG_Q_POST(task, msg, 0, 0, 0)
 
#define msg_post_async(task, msg)   OS_MSG_Q_POST(task, msg, 0, 0, 1)
 
#define msg_post_in(task, msg, delay)   OS_MSG_Q_POST(task, msg, delay, 0, 0)
 
#define msg_post_every(task, msg, period)   OS_MSG_Q_POST(task, msg, period, period, 0)
 
#define msg_receive(task, pMsg)   OS_MSG_Q_RECEIVE( task, pMsg, 0 )
 
#define msg_receive_async(task, pMsg)   OS_MSG_Q_RECEIVE( task, 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 task_create (taskproctype taskproc, uint8_t prio, Msg_t *msgPool, uint8_t poolSize, uint16_t msgSize)
 
TaskState_t task_state_get (taskproctype taskproc)
 
uint8_t task_id_get (taskproctype taskproc)
 
void task_kill (taskproctype taskproc)
 
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)
 
void os_cbkSleep (void)
 

Detailed Description

cocoOS API header file

Macro Definition Documentation

#define event_ISR_signal (   event)    OS_INT_SIGNAL_EVENT(event)

Macro for signalling an event from an ISR

Parameters
eventthe event to be signalled
Remarks
Usage:
1 Evt_t evRxChar;
2 main() {
3  ...
4  evRxChar = event_create();
5  ...
6 }
7 
8 ISR (SIG_UART_RECV) {
9  rx.data[ rx.head ] = UDR;
10  event_ISR_signal( evRxChar );
11 }
#define event_signal (   event)    OS_SIGNAL_EVENT(event)

Macro for signalling an event.

Parameters
eventthe event to be signalled
Remarks
Usage:
1 Evt_t myEvent;
2 main() {
3  ...
4  myEvent = event_create();
5  ...
6 }
7 
8 static void myTask(void) {
9  task_open();
10  ...
11  event_signal( myEvent );
12  ...
13  task_close();
14 }
#define event_wait (   event)    OS_WAIT_SINGLE_EVENT(event,0)

Macro for wait for a single event.

Parameters
eventthe event to wait for
Remarks
Usage:
1 Evt_t myEvent;
2 main() {
3  ...
4  myEvent = event_create();
5  ...
6 }
7 
8 static void myTask(void) {
9  task_open();
10  ...
11  event_wait( myEvent );
12  ...
13  task_close();
14 }
#define event_wait_multiple (   waitAll,
  args... 
)    OS_WAIT_MULTIPLE_EVENTS( waitAll, args)

Macro for wait for multiple events.

Parameters
waitAll1 if wait for all, 0 if wait for any event
argslist of Evt_t type events
Remarks
Usage:
1 Evt_t myEvent1;
2 Evt_t myEvent2;
3 Evt_t myEvent3;
4 main() {
5  ...
6  myEvent1 = event_create();
7  myEvent2 = event_create();
8  myEvent3 = event_create();
9  ...
10 }
11 
12 static void myTask(void) {
13  task_open();
14  ...
15  event_wait_multiple(1, myEvent1, myEvent2, myEvent3);
16  ...
17  task_close();
18 }
#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
eventthe event to wait for
timeoutmaximum 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:
1 Evt_t myEvent;
2 main() {
3  ...
4  myEvent = event_create();
5  ...
6 }
7 
8 static void myTask(void) {
9  task_open();
10  ...
11  event_wait_timeout( myEvent, 100 );
12  ...
13  task_close();
14 }
#define msg_post (   task,
  msg 
)    OS_MSG_Q_POST(task, msg, 0, 0, 0)

Posts a message to the message queue of a task.

Parameters
tasktask procedure of the task that will receive the message
msgthe 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:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task1(void) {
22  static LedMsg_t ledMsg;
23 
24  ledMsg.super.signal = LED_SIG;
25  ledMsg.led = 5;
26 
27  task_open();
28 
29  for (;;) {
30 
31  task_wait( 3000 );
32 
33  msg_post( task2, ledMsg );
34 
35  }
36 
37  task_close();
38 
39 }
#define msg_post_async (   task,
  msg 
)    OS_MSG_Q_POST(task, 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
tasktask procedure of the task that will receive the message
msgthe message to post
Returns
None
Usage:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task1(void) {
22  static LedMsg_t ledMsg;
23 
24  ledMsg.super.signal = LED_SIG;
25  ledMsg.led = 5;
26 
27  task_open();
28 
29  for (;;) {
30 
31  task_wait( 3000 );
32 
33  msg_post_async( task2, ledMsg );
34 
35  }
36 
37  task_close();
38 
39 }
#define msg_post_every (   task,
  msg,
  period 
)    OS_MSG_Q_POST(task, 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
tasktask procedure of the task that will receive the message
msgthe message to post
periodperiod time in master clock ticks
Returns
None
Usage:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task1(void) {
22  static LedMsg_t ledMsg;
23 
24  ledMsg.super.signal = LED_SIG;
25  ledMsg.led = 5;
26 
27  msg_post_every( task2, ledMsg, 100 );
28 
29  task_open();
30 
31  for (;;) {
32  ...
33  ...
34  task_wait( 3000 );
35  }
36 
37  task_close();
38 
39 }
#define msg_post_in (   task,
  msg,
  delay 
)    OS_MSG_Q_POST(task, 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
tasktask procedure of the task that will receive the message
msgthe message to post
delaypost delay time in master clock ticks
Returns
None
Usage:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task1(void) {
22  static LedMsg_t ledMsg;
23 
24  ledMsg.super.signal = LED_SIG;
25  ledMsg.led = 5;
26 
27  task_open();
28 
29  for (;;) {
30 
31  task_wait( 3000 );
32 
33  msg_post_in( task2, ledMsg, 100 );
34 
35  }
36 
37  task_close();
38 
39 }
#define msg_receive (   task,
  pMsg 
)    OS_MSG_Q_RECEIVE( task, pMsg, 0 )

Receives a message from the queue

Parameters
tasktask procedure of the current task
pMsgpointer 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:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task2(void) {
22  static LedMsg_t msg;
23  uint8_t led;
24  task_open();
25 
26  for (;;) {
27 
28  msg_receive( task2, &msg );
29 
30  if ( msg.super.signal == LED_SIG ) {
31  led = msg.led;
32  LED_TOGGLE( led );
33  }
34  }
35 
36  task_close();
37 
38 }
#define msg_receive_async (   task,
  pMsg 
)    OS_MSG_Q_RECEIVE( task, pMsg, 1 )

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

Parameters
tasktask procedure of the current task
pMsgpointer 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:
1 typedef struct {
2  Msg_t super;
3  uint8_t led;
4 } LedMsg_t;
5 
6 
7 static LedMsg_t msgpool_1[ 16 ];
8 
9 
10 int main(void)
11 {
12  ...
13  task_create( task1, 1, NULL, 0 );
14  task_create( task2, 2, msgpool_1, 16, sizeof(LedMsg_t) );
15  ...
16  os_start();
17  return 0;
18 }
19 
20 
21 static void task2(void) {
22  static LedMsg_t msg;
23  uint8_t led;
24  task_open();
25 
26  for (;;) {
27 
28  task_wait( 3000 );
29 
30  msg_receive_async( task2, &msg );
31 
32  if ( msg.super.signal == LED_SIG ) {
33  led = msg.led;
34  LED_TOGGLE( led );
35  }
36  else if ( msg.super.signal == NO_MSG_ID ) {
37 
38  }
39  }
40 
41  task_close();
42 
43 }
#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
semSemaphore.
Remarks
Usage:
1 Sem_t mySem;
2 main() {
3  ...
4  mySem = sem_create( 0 );
5  ...
6 }
7 
8 ISR(void) {
9 
10  ...
11  sem_ISR_signal( mySem );
12  ...
13 
14 }
#define sem_signal (   sem)    OS_SIGNAL_SEM(sem)

Macro for releasing a semaphore.

Parameters
semSemaphore.
Remarks
Usage:
1 Sem_t mySem;
2 main() {
3  ...
4  mySem = sem_create( 0 );
5  ...
6 }
7 
8 static void myTask(void) {
9  task_open();
10  ...
11  sem_signal( mySem );
12  ...
13  task_close();
14 }
#define sem_wait (   sem)    OS_WAIT_SEM(sem)

Macro for aquiring a semaphore.

Parameters
semSemaphore.
Remarks
Usage:
1 Sem_t mySem;
2 main() {
3  ...
4  mySem = sem_create( 0 );
5  ...
6 }
7 
8 static void myTask(void) {
9  task_open();
10  ...
11  sem_wait( mySem );
12  ...
13  task_close();
14 }
#define task_close ( )    OS_END

Macro for definition of task end.

Remarks
Usage: Should be placed at the end of the task procedure
1 static void myTask(void) {
2  static uint8_t i;
3  task_open();
4  ...
5  task_wait( 10 );
6  ...
7  task_close();
8 }
#define task_open ( )    OS_BEGIN

Macro for definition of task beginning.

Remarks
Usage: Should be placed at the beginning of the task procedure
1 static void myTask(void) {
2  static uint8_t i;
3  task_open();
4  ...
5  task_wait( 10 );
6  ...
7  task_close();
8 }
#define task_resume (   id)    OS_RESUME_TASK( id )

Macro for resuming a task

Parameters
idof 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:
1 uint8_t ledTask_id;
2 
3 static void led_task(void) {
4  task_open();
5  for(;;) {
6  led_toggle();
7  task_wait( 100 );
8  }
9  task_close();
10 }
11 
12 
13 static void button_task(void) {
14  task_open();
15  for (;;) {
16  if ( button_1_Pressed ) {
17  task_suspend( ledTask_id );
18  }
19  else if ( button_2_Pressed ){
20  task_resume( ledTask_id );
21  }
22  }
23  task_close();
24 }
25 
26 
27 int main( void ) {
28  ...
29  ledTask_id = task_create( led_task, 1, msgPool, POOL_SIZE, sizeof(Msg_t) );
30  task_create( button_task, 2, NULL, 0, 0 );
31  ...
32 }
#define task_suspend (   id)    OS_SUSPEND_TASK( id )

Macro for suspending a task

Parameters
idof 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:
1 static Msg_t msgPool[ POOL_SIZE ];
2 uint8_t task1_id;
3 uint8_t task2_id;
4 
5 static void led_task(void) {
6  task_open();
7  for(;;) {
8  led_toggle();
9  task_wait( 100 );
10  }
11  task_close();
12 }
13 
14 
15 static void button_task(void) {
16  task_open();
17  for (;;) {
18  if ( buttonPressed ) {
19  task_suspend( task1_id );
20  }
21  task_wait(10);
22  }
23  task_close();
24 }
25 
26 
27 int main( void ) {
28  ...
29  task1_id = task_create( led_task, 1, msgPool, POOL_SIZE, sizeof(Msg_t) );
30  task2_id = task_create( button_task, 2, NULL, 0, 0 );
31  ...
32 }
#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
xNumber of master clock ticks to wait.
Remarks
Usage:
1 static void myTask(void) {
2  task_open();
3  ...
4  task_wait( 10 );
5  ...
6  task_close();
7 }
#define task_wait_id (   id,
 
)    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
idSub clock id. Valid range 1-255.
xNumber of sub clock ticks to wait, 16 bit value.
Remarks
Usage:
1 static void myTask(void) {
2  task_open();
3  ...
4  task_wait_id( 2, 10 );
5  ...
6  task_close();
7 }

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.
1 Evt_t myEvent;
2 myEvent = event_create();
uint8_t event_signaling_taskId_get ( Evt_t  ev)

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

Parameters
evevent
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.
1 event_wait(event);
2 signalingTask = event_signaling_taskId_get(event);
3 if ( signalingTask == Task2_id ) {
4  ...
5 }
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
1 int main(void) {
2 system_init();
3 os_init();
4 ...
5 }
void os_start ( void  )

Starts the task scheduling

Returns
None.
Remarks
Usage:
Should be the last line of main.
1 int main(void) {
2  system_init();
3  os_init();
4  task_create( myTaskProc, 1, NULL, 0, 0 );
5  ...
6  os_start();
7  return 0;
8 }
void os_sub_nTick ( uint8_t  id,
uint16_t  nTicks 
)

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

Parameters
idsub clock id, allowed range 1-255.
nTicksincrement 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.
1 ISR(SIG_OVERFLOW0) {
2  ...
3  os_sub_nTick( 2, 10 );
4 }
void os_sub_tick ( uint8_t  id)

Tick function driving the sub clocks

Parameters
idsub 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.
1 ISR(SIG_OVERFLOW0) {
2  ...
3  os_sub_tick(2);
4 }
void os_tick ( void  )

Tick function driving the kernel

Returns
None.
Remarks
Usage:
Should be called periodically. Preferably from the clock tick ISR.
1 ISR(SIG_OVERFLOW0) {
2  ...
3  os_tick();
4 }
Sem_t sem_bin_create ( uint8_t  initial)

Creates and initializes a new binary semaphore.

Parameters
initialvalue 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.
1 Sem_t mySem;
2 mySem = sem_bin_create(0);
Sem_t sem_counting_create ( uint8_t  max,
uint8_t  initial 
)

Creates and initializes a new counting semaphore.

Parameters
maxvalue of the semaphore
initialvalue 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.
1 Sem_t mySem;
2 mySem = sem_counting_create(5,0);
uint8_t task_create ( taskproctype  taskproc,
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
taskprocFunction pointer to the task procedure.
prioTask priority on a scale 0-255 where 0 is the highest priority.
msgPoolPointer to the message pool, containing messages. Ignored if poolSize is 0.
poolSizeSize of the message pool. Set to 0 if no message pool needed for the task
msgSizeSize 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.
1  static uint8_t taskId;
2  static Msg_t msgpool_1[ POOL_SIZE ];
3 
4 int main(void) {
5  system_init();
6  os_init();
7  taskId = task_create( myTaskProc, 1, msgpool_1, POOL_SIZE, sizeof(Msg_t) );
8  ...
9 }
uint8_t task_id_get ( taskproctype  taskproc)

Gets the task id of the task associated with the specified task procedure

Parameters
taskprocFunction pointer to the task procedure.
Returns
TaskId of the task
1 static void waitingTask(void)
2 {
3  task_open()
4 
5  event_wait( event );
6 
7  if ( event_signaling_taskId_get( event ) == task_id_get( signalingTask1 ) ) {
8  ...
9  }
10 
11  task_close();
12 
13 }
14 
15 
16 static void signalingTask1(void)
17 {
18  task_open();
19 
20  task_wait( 900 );
21 
22  event_signal(event);
23 
24  task_close();
25 
26 }
void task_kill ( taskproctype  taskproc)

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

Parameters
taskprocFunction pointer to the task procedure.
Returns
None
1 static void waitingTask(void)
2 {
3  task_open();
4 
5  event_wait( event );
6 
7  if ( event_signaling_taskId_get( event ) == task_id_get( signalingTask1 ) ) {
8  task_kill( signalingTask1 );
9  }
10 
11  task_close();
12 
13 }
14 
15 
16 static void signalingTask1(void)
17 {
18  task_open();
19 
20  task_wait( 900 );
21 
22  event_signal(event);
23 
24  task_close();
25 
26 }
TaskState_t task_state_get ( taskproctype  taskproc)

Gets the current state of the task associated with the specified procedure

Parameters
taskprocFunction pointer to the task procedure.
Returns
State of the task
1 static void led_task500(void)
2 {
3  task_open();
4 
5  for (;;) {
6  LED_TOGGLE(0);
7 
8  task_wait( 500 );
9  }
10 
11  task_close();
12 }
13 
14 
15 static void led_task1000(void)
16 {
17  task_open();
18 
19  for (;;) {
20  sem_wait( buttonSem );
21 
22  if ( buttonPressed ) {
23  if ( SUSPENDED < task_state_get( led_task500 ) ) {
24  task_suspend( led_task500 );
25  }
26 
27  }
28  else {
29  if ( SUSPENDED == task_state_get( led_task500 ) ) {
30  task_resume( led_task500 );
31  }
32  }
33 
34  sem_signal( buttonSem );
35 
36  LED_TOGGLE(1);
37 
38 
39  task_wait( 900 );
40  }
41 
42  task_close();
43 
44 }