cocoOS  4.0.0
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, 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 
92 @code
93 static void task(void) {
94  task_open();
95  ...
96  ...
97  task_close();
98 }
99 @endcode
100 
101 Such a task will be executed once only. If a task is intended to be executed "for ever", an endless loop
102 must be implemented.
103 
104 @code
105 static void hello_task(void) {
106  task_open();
107  for(;;) {
108  uart_send_string("Hello World!");
109  task_wait( 20 );
110  }
111  task_close();
112 }
113 
114 
115 
116 int main(void) {
117  /* Setup ports, clock... */
118  system_init();
119 
120  /* Create kernel objects */
121  task_create( hello_task, 1, NULL, 0, 0 );
122 
123  os_init();
124  clock_start();
125  os_start();
126 
127  /* Will never end up here */
128  return 0;
129 }
130 @endcode
131 
132 <b>Scheduling</b>@n
133 When a task has finished it gives the CPU control to another task by calling one of the scheduling
134 macros:
135 
136  - task_wait()
137  - event_wait()
140  - event_signal()
141  - sem_wait()
142  - sem_signal()
143  - msg_post()
144  - msg_post_in()
145  - msg_post_every()
146  - msg_receive()
147 
148 Normally the scheduler will give the cpu to the highest priority task ready for execution. It is possible to
149 choose a round robin scheduling algorithm by putting the following line in os_defines.h:@n
150 #define ROUND_ROBIN
151 
152 This will make the scheduler to scan the list of tasks and run the next found task in the ready state.
153 */
void os_start(void)
Definition: os_kernel.c:117
#define task_wait(x)
Definition: os_applAPI.h:112
void os_tick(void)
Definition: os_kernel.c:146
void os_init(void)
Definition: os_kernel.c:64
#define sem_wait(sem)
Definition: os_applAPI.h:402
#define msg_post_every(task, msg, period)
Definition: os_applAPI.h:706
#define msg_post(task, msg)
Definition: os_applAPI.h:520
uint8_t task_create(taskproctype taskproc, uint8_t prio, Msg_t *msgPool, uint8_t poolSize, uint16_t msgSize)
Definition: os_task.c:99
#define event_signal(event)
Definition: os_applAPI.h:351
#define msg_receive(task, pMsg)
Definition: os_applAPI.h:767
void os_sub_nTick(uint8_t id, uint16_t nTicks)
Definition: os_kernel.c:202
#define event_wait(event)
Definition: os_applAPI.h:263
#define event_wait_multiple(waitAll, args...)
Definition: os_applAPI.h:324
Sem_t sem_bin_create(uint8_t initial)
Definition: os_sem.c:88
#define task_wait_id(id, x)
Definition: os_applAPI.h:137
#define sem_signal(sem)
Definition: os_applAPI.h:429
#define task_open()
Definition: os_applAPI.h:67
#define msg_post_in(task, msg, delay)
Definition: os_applAPI.h:644
#define task_close()
Definition: os_applAPI.h:88
void os_sub_tick(uint8_t id)
Definition: os_kernel.c:173
#define event_wait_timeout(event, timeout)
Definition: os_applAPI.h:293