cocoOS  5.0.1
docFundamentals.h
Go to the documentation of this file.
1 
44  system_init();
45 
46  os_init();
47 
48  /* Create kernel objects */
49  task_create( myTaskProc, 0, 1, NULL, 0, 0 );
50  mySem = sem_bin_create( 1 );
51 
52  os_start();
53 
54  /* Will never end up here */
55  return 0;
56 }
57 @endcode
58 
59 
60 This is the preferred order of initialization. It is crucial that the clock tick is not started before the tasks
61 are created and the kernel is initialized. The os_start() calls the macro os_enable_interrupts() which can be defined
62 to start the clock tick driving the OS.
63 
64 <b>Time </b>@n
65 cocoOS keeps track of time by counting ticks and you must feed the counting with a call to os_tick() periodically
66 from the clock tick ISR.
67 
68 A system of one main clock and several sub clocks is used in cocoOS. The main clock is typically realized
69 using one of the hardware timers within your target microcontroller which calls the os_tick() function that
70 decrements the timers used for task_wait(), msg_post_in() and msg_post_every().
71 If your application does not need more than a single time base, the main clock fed by the os_tick() call is
72 all you need. @n
73 
74 In case your application has to react to events in another time resolution than what is provided by the main
75 clock, you can use the sub clocks. The sub clocks are typically not associated with a hardware timer, but is
76 instead "ticked" by calling os_sub_tick(id) from within your application code.
77 
78 Sub clocks can also be advanced with a step greater than one using os_sub_nTick(id, nTicks). There is one
79 task function associated with the sub clocks: task_wait_id(id,ticks). id is a value in the range 1-255
80 assigned by the application, and ticks is the number of ticks to wait. An example of the use of sub clocks
81 could be a task that should be run after 64 bytes has been received on the UART. The task starts the wait by
82 calling task_wait_id( 1, 64 ). And in the UART rx ISR os_sub_tick(1) is called for each received character.
83 
84 <b>Tasks </b>@n
85 An application is built up by a number of tasks. Each task is a associated with a (preferably short)
86 procedure with a well defined purpose. The execution of the tasks, is managed by the os kernel, by letting
87 the highest priority task among all execution ready tasks to execute. All tasks have to make at least
88 one blocking call to a sheduling kernel function. This gives lower priority tasks a chance to execute.
89 
90 The task procedure must enclose its code with the task_open() and task_close() macros, as shown below.
91 Several tasks can use the same task procedure. This is done by giving the same procedure as argument when
92 creating the tasks.
93 
94 @code
95 static void task(void) {
96  task_open();
97  ...
98  ...
99  task_close();
100 }
101 @endcode
102 
103 Such a task will be executed once only. If a task is intended to be executed "for ever", an endless loop
104 must be implemented.
105 
106 @code
107 static void hello_task(void) {
108  task_open();
109  for(;;) {
110  uart_send_string("Hello World!");
111  task_wait( 20 );
112  }
113  task_close();
114 }
115 
116 
117 
118 int main(void) {
119  /* Setup ports, clock... */
120  system_init();
121 
122  /* Create kernel objects */
123  task_create( hello_task, 0, 1, NULL, 0, 0 );
124 
125  os_init();
126  clock_start();
127  os_start();
128 
129  /* Will never end up here */
130  return 0;
131 }
132 @endcode
133 
134 <b>Scheduling</b>@n
135 When a task has finished it gives the CPU control to another task by calling one of the scheduling
136 macros:
137 
138  - task_wait()
139  - event_wait()
142  - event_signal()
143  - sem_wait()
144  - sem_signal()
145  - msg_post()
146  - msg_post_in()
147  - msg_post_every()
148  - msg_receive()
149 
150 Normally the scheduler will give the cpu to the highest priority task ready for execution. It is possible to
151 choose a round robin scheduling algorithm by putting the following line in os_defines.h:@n
152 #define ROUND_ROBIN
153 
154 This will make the scheduler to scan the list of tasks and run the next found task in the ready state.
155 */
void os_start(void)
Definition: os_kernel.c:121
#define msg_post_every(task_id, msg, period)
Definition: os_applAPI.h:742
#define task_wait(x)
Definition: os_applAPI.h:112
void os_tick(void)
Definition: os_kernel.c:149
void os_init(void)
Definition: os_kernel.c:64
#define msg_post(task_id, msg)
Definition: os_applAPI.h:553
TaskState_t state
current runstate
Definition: os_task.c:43
#define sem_wait(sem)
Definition: os_applAPI.h:434
uint8_t task_create(taskproctype taskproc, void *data, uint8_t prio, Msg_t *msgPool, uint8_t poolSize, uint16_t msgSize)
Definition: os_task.c:134
#define event_signal(event)
Definition: os_applAPI.h:383
void os_sub_nTick(uint8_t id, uint16_t nTicks)
Definition: os_kernel.c:205
#define event_wait(event)
Definition: os_applAPI.h:263
#define msg_post_in(task_id, msg, delay)
Definition: os_applAPI.h:679
#define event_wait_multiple(waitAll, args...)
Definition: os_applAPI.h:356
Sem_t sem_bin_create(uint8_t initial)
Definition: os_sem.c:95
#define msg_receive(task_id, pMsg)
Definition: os_applAPI.h:804
#define task_wait_id(id, x)
Definition: os_applAPI.h:137
#define sem_signal(sem)
Definition: os_applAPI.h:461
#define task_open()
Definition: os_applAPI.h:67
#define task_close()
Definition: os_applAPI.h:88
void os_sub_tick(uint8_t id)
Definition: os_kernel.c:176
#define event_wait_timeout(event, timeout)
Definition: os_applAPI.h:293