aboutsummaryrefslogtreecommitdiffstats
path: root/docs/ch.txt
blob: 90a92c294145a519813d30a0a8db1950182abb25 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
/**
 * @mainpage ChibiOS/RT
 * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
 * @section Chibi Chibi ?
 * It is the Japanese word for small as in small child. So ChibiOS/RT
 * \htmlonly (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">&#12385;&#12403;</span>OS/RT) \endhtmlonly
 * means small Real Time Operating System.
 * Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.
 * @section ch_features Features
 * <ul>
 * <li>Free software, GPL3 licensed.</li>
 * <li>Designed for realtime applications.</li>
 * <li>Easily portable.</li>
 * <li>Mixed programming model:</li>
 *   <ul>
 *   <li>Synchronous, using semaphores/mutexes and/or messages.</li>
 *   <li>Asynchronous, using event sources.</li>
 *   <li>Mix of the above models, multiple threads listening to multiple event
 *       sources while serving message queues.</li>
 *   </ul>
 * <li>PC simulator target included, the development can be done on the PC
 *     using MinGW or VS.
 *     Timers, I/O channels and other HW resources are simulated in a
 *     Win32 process and the application code does not need to be aware of it.
 *     MinGW and VS demos available and ready to go, use them as templates for
 *     your application.</li>
 * <li>Preemptive scheduling.</li>
 * <li>128 priority levels.</li>
 * <li>Multiple threads at the same priorily level allowed.</li>
 * <li>Round robin scheduling for threads at the same priority level.</li>
 * <li>Unlimited number of threads.</li>
 * <li>Unlimited number of virtual timers.</li>
 * <li>Unlimited number of semaphores.</li>
 * <li>Unlimited number of mutexes.</li>
 * <li>Unlimited number of event sources.</li>
 * <li>Unlimited number of messages in queue.</li>
 * <li>Unlimited number of I/O queues.</li>
 * <li>No static setup at compile time, there is no need to configure a maximum
 *     number of all the above resources.</li>
 * <li>No *need* for a memory allocator, all the kernel structures are static
 *     and declaratively allocated.</li>
 * <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
 *     runtime.</li>
 * <li>Optional, thread safe, Heap Allocator subsystem.</li>
 * <li>Optional, thread safe, Memory Pools Allocator subsystem.</li>
 * <li>Blocking and non blocking I/O channels with timeout and events generation
 *     capability.</li>
 * <li>Minimal system requirements: about 8KiB ROM with all options enabled and
 *     speed optimizations on. The size can shrink under 2KiB by disabling the
 *     the unused subsystems and optimizing for size.</li>
 * <li>Small memory footprint, unused subsystems can be excluded by the
 *     memory image.</li>
 * <li>Almost totally written in C with little ASM code required for ports.</li>
 * </ul>
 *
 * ChibiOS/RT architecture:<br><br>
 * @subpage Concepts
 */

/**
 * @page Concepts Concepts
 * @{
 * @section naming Naming Conventions
 * ChibiOS/RT APIs are all named following this convention:
 * \a ch\<group\>\<action\>\<suffix\>().
 * The possible groups are: \a Sys, \a Sch, \a VT, \a Thd, \a Sem, \a Mtx,
 * \a Evt, \a Msg, \a IQ, \a OQ, \a HQ,\a FDD, \a HDD, \a Dbg.
 * The suffix is not present for normal APIs but can be one of
 * the following: "I" for APIs meant to be invoked within the system mutex 
 * zone, "S" for APIs only useable from within the system mutex zone but not
 * from interrupt handlers.<br>
 * The APIs without suffix can be invoked only from the user code outsize the
 * system mutex zone and not from interrupt handlers unless differently
 * specified.<br>
 * Examples: \p chThdCreate(), \p chSemSignalI(), \p chIQGetTimeout().
 *
 * @section scheduling Scheduling
 * The strategy is very simple the currently ready thread with the highest
 * priority is executed. If more than one thread with equal priority are
 * eligible for execution then they are executed in a round-robin way, the
 * CPU time slice constant is configurable. The ready list is a double linked
 * list of threads ordered by priority.
 * @image html readylist.png
 * Note that the currently running thread is not in the ready list, the list
 * only contains the threads ready to be executed but still actually waiting.
 *
 * @section states Threads States Diagram
 * The image shows how threads can change their state in ChibiOS/RT.<br>
 * @image html states.png
 *
 * @section warea Thread Working Area
 * Each thread has its own stack, a Thread structure and a registers dump
 * structure. All the structures are allocated into a "Thread working area",
 * a thread private heap, usually allocated in a char array declared in your
 * code, there is not a central threads table or list, this means you can
 * have as many threads you want as long you have enough available RAM
 * memory. The threads do not use any memory outside the allocated working
 * area.<br>
 * @image html workspace.png
 * <br>
 * Note that the registers dump is only present when the Thread is not
 * running, the context switching is done by pushing the registers on the
 * stack of the switched-out thread and popping the registers of the
 * switched-in thread from its stack.
 *
 * @section sysmutex System Mutex Zone
 * It is the code within the OS that cannot be preempted, this code is
 * everything between the \p chSysLock() and \p chSysUnlock() API calls.
 * The implementation of the APIs in most cases just enables/disables the
 * interrupts. Of course the code in the system mutex zone must be as short
 * and efficient possible as it affects the RT performance of the whole
 * system. The worst case response time is affected by the longest code
 * path in the system mutex zone or interrupt handler.
 * @code
 * // User code, not critical, preemption possible.
 * chSysLock();
 * ...
 * // System critical code, preemption delayed.
 * ...
 * chSysUnlock();
 * // User code, preemption possible again.
 * @endcode
 * Applications usually do not need to put code into the system mutex zone
 * unless you are implementing device drivers or special synchronization
 * primitives, everything else can be implemented by using semaphores,
 * mutexes, messages or events.
 */
/** @} */

/**
 * @defgroup Ports Ports
 * @{
 * This section describes the technical details for the various supported
 * ChibiOS/RT ports.
 */
/** @} */

/**
 * @defgroup ARM7 ARM7TDMI
 * @{
 * <p>
 * The ARM7 port makes some assumptions on the application code organization:
 * <ul>
 * <li>The \p main() function is invoked in system mode.</li>
 * <li>Each thread has a private user/system stack, the system has a single
 *     interrupt stack where all the interrupts are processed.</li>
 * <li>The threads are started in system mode.</li>
 * <li>The threads code can run in system mode or user mode, however the
 *     code running in user mode cannot invoke the ChibiOS/RT APIs directly
 *     because privileged instructions are used inside.<br>
 *     The kernel APIs can be eventually invoked by using a SWI entry point
 *     that handles the switch in system mode and the return in user mode.</li>
 * <li>Other modes are not preempt-able because the system code assumes the
 *     threads running in system mode. When running in supervisor or other
 *     modes make sure that the interrupts are globally disabled.</li>
 * <li>Interrupts nesting is not supported in the ARM7 code because their
 *     implementation, even if possible, is not really efficient in this
 *     architecture.</li>
 * <li>FIQ sources can preempt the kernel (by design) so it is not possible to
 *     invoke the kernel APIs from inside a FIQ handler.</li>
 * </ul>
 * </p>
 * <p>
 * The ARM7 port is shared by multiple demos targeted to various implementations:
 * </p>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup LPC214x LPC214x Support
 * @{
 * <p>
 * The LPC214x support includes:
 * <ul>
 * <li>VIC support code.</li>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>SSP driver.</li>
 * <li>A MMC/SD demo driver.</li>
 * <li>A buzzer demo driver.</li>
 * <li>A minimal demo, useful as project template.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * <li>A C++ demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARM7
 */
/** @} */

/**
 * @defgroup AT91SAM7X AT91SAM7X Support
 * @{
 * <p>
 * The AT91SAM7X support includes:
 * <ul>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARM7
 */
/** @} */

/**
 * @defgroup ARMCM3 ARM Cortex-M3
 * @{
 * <p>
 * The ARM Cortex-M3 port is organized as follow:
 * </p>
 * <ul>
 * <li>The \p main() function is invoked in thread-privileged mode.</li>
 * <li>Each thread has a private process stack, the system has a single main
 *     stack where all the interrupts and exceptions are processed.</li>
 * <li>Only the 4 MSb of the priority level are used, the 4 LSb are assumed
 *     to be zero.</li>
 * <li>The threads are started in thread-privileged mode with BASEPRI level
 *     0x00 (disabled).</li>
 * <li>The kernel raises its BASEPRI level to 0x10 in order to protect the
 *     system mutex zones. Note that exceptions with level 0x00 can preempt
 *     the kernel, such exception handlers cannot invoke kernel APIs directly.</li>
 * <li>Interrupt nesting and the other advanced NVIC features are supported.</li>
 * <li>The SVC instruction and vector, with parameter #0,  is internally used
 *     for commanded context switching.<br>
 *     It is possible to share the SVC handler at the cost of slower context
 *     switching.</li>
 * <li>The PendSV vector is internally used for preemption context switching.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup STM32F103 STM32F103 Support
 * @{
 * <p>
 * The STM32F103 support includes:
 * <ul>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARMCM3
 */
/** @} */

/**
 * @defgroup AVR MegaAVR
 * @{
 * <p>
 * Notes about the AVR port:
 * </p>
 * <ul>
 * <li>The AVR does not have a dedicated interrupt stack, make sure to reserve
 *     enough stack space for interrupts in each thread stack. This can be done
 *     by modifying the \p INT_REQUIRED_STACK macro into \p ports/AVR/chcore.h.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup MSP430 MSP430
 * @{
 * <p>
 * Notes about the MSP430 port:
 * </p>
 * <ul>
 * <li>In the current version the MSP430 port is still untested.</li>
 * <li>The MSP430 does not have a dedicated interrupt stack, make sure to reserve
 *     enough stack space for interrupts in each thread stack. This can be done
 *     by modifying the \p INT_REQUIRED_STACK macro into \p ports/MSP430/chcore.h.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup Kernel Kernel
 * @{
 */
/** @} */

/**
 * @defgroup Config Configuration
 * @{
 * In \p chconf.h are defined the required subsystems for your application.
 * @ingroup Kernel
 * @file chconf.h ChibiOS/RT configuration file.
 */
/** @} */

/**
 * @defgroup Core Core
 * @{
 * Non portable code.
 * @ingroup Kernel
 * @file chcore.c Non portable code.
 */
/** @} */

/**
 * @defgroup Initialization Initialization
 * @{
 * Initialization APIs and procedures.
 * @ingroup Kernel
 * @file ch.h ChibiOS/RT main include file, it includes everything else.
 * @file chinit.c ChibiOS/RT Initialization code.
 */
/** @} */

/**
 * @defgroup Debug Debug
 * @{
 * Debug APIs and procedures.
 * @ingroup Kernel
 * @file debug.h Debug macros and structures.
 * @file chdebug.c ChibiOS/RT Debug code.
 */
/** @} */

/**
 * @defgroup Scheduler Scheduler
 * @{
 * ChibiOS/RT scheduler.
 * @ingroup Kernel
 * @file chschd.c Scheduler code.
 * @file scheduler.h Scheduler macros and structures.
 */
/** @} */

/**
 * @defgroup ThreadLists Thread Lists and Queues
 * @{
 * ChibiOS/RT thread lists and queues utilities.
 * @ingroup Kernel
 * @file chlists.c Lists and queues code.
 * @file lists.h Lists and queues macros and structures.
 */
/** @} */

/**
 * @defgroup Threads Threads
 * @{
 * Threads creation and termination APIs.
 * @file threads.h Threads structures, macros and functions.
 * @file chthreads.c Threads code.
 */
/** @} */

/**
 * @defgroup Time Time and Virtual Timers
 * @{
 * Time and Virtual Timers related APIs.
 * @file include/vt.h Time macros and structures.
 * @file chvt.c Time functions.
 */
/** @} */

/**
 * @defgroup Heap Heap
 * @{
 * Heap Allocator related APIs.
 * <b>Operation mode</b><br><br>
 * The heap allocator implements a first-fit strategy and its APIs are
 * functionally equivalent to the usual \p malloc() and \p free(). The main
 * difference is that the heap APIs are thread safe.<br>
 * By enabling the \p CH_USE_MALLOC_HEAP option the heap manager will use the
 * runtime-provided \p malloc() and \p free() as backend for the heap APIs
 * instead of the system provided allocator.<br>
 * In order to use the heap APIs the \p CH_USE_HEAP option must be specified
 * in \p chconf.h.
 * @file include/heap.h Heap macros and structures.
 * @file chheap.c Heap functions.
 */
/** @} */

/**
 * @defgroup MemoryPools Memory Pools
 * @{
 * Memory Pools related APIs.
 * <b>Operation mode</b><br><br>
 * The Memory Pools APIs allow to allocate/free fixed size objects in
 * <b>constant time</b> and reliably without memory fragmentation problems.<br>
 * In order to use the Time APIs the \p CH_USE_MEMPOOLS option must be
 * specified in \p chconf.h.
 * @file include/mempools.h Memory Pools macros and structures.
 * @file chmempools.c Memory Pools functions.
 */
/** @} */

/**
 * @defgroup Semaphores Semaphores
 * @{
 * Semaphores and threads synchronization.
 * <b>Operation mode</b><br><br>
 * A semaphore is a threads synchronization object, some operations
 * are defined on semaphores:<br>
 * <ul>
 *   <li><b>Signal</b>: The semaphore counter is increased and if the result
 *     is non-positive then a waiting thread is removed from the semaphore
 *     queue and made ready for execution.
 *   </li>
 *   <li><b>Wait</b>: The semaphore counter is decreased and if the result
 *     becomes negative the thread is queued in the semaphore and suspended.
 *   </li>
 *   <li><b>Reset</b>: The semaphore counter is reset to a non-negative value
 *     and all the threads in the queue are released.
 *   </li>
 * </ul>
 * Semaphores can be used as guards for mutual exclusion code zones but
 * also have other uses, queues guards and counters as example.<br>
 * In order to use the Semaphores APIs the \p CH_USE_SEMAPHORES
 * option must be specified in \p chconf.h.<br><br>
 * @file semaphores.h Semaphores macros and structures.
 * @file chsem.c Semaphores code.
 */
/** @} */

/**
 * @defgroup Mutexes Mutexes
 * @{
 * Mutexes and threads synchronization.
 * <b>Operation mode</b><br><br>
 * A mutex is a threads synchronization object, some operations are defined
 * on mutexes:<br>
 * <ul>
 *   <li><b>Lock</b>: The mutex is checked, if the mutex is not owned by some
 *     other thread then it is locked else the current thread is queued on the
 *     mutex in a list ordered by priority.
 *   </li>
 *   <li><b>Unlock</b>: The mutex is released by the owner and the highest
 *     priority thread waiting in the queue, if any, is resumed and made owner
 *     of the mutex.
 *   </li>
 * </ul>
 * In order to use the Event APIs the \p CH_USE_MUTEXES option must be
 * specified in \p chconf.h.<br>
 *
 * <b>Constraints</b><br><br>
 * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse
 * order. The Unlock API does not even have a parameter, the mutex to unlock
 * is taken from an internal stack of owned mutexes.
 * This both improves the performance and is required by the priority
 * inheritance mechanism.
 *
 * <b>The priority inversion problem</b><br><br>
 * The mutexes in ChibiOS/RT implements the <b>full</b> priority
 * inheritance mechanism in order handle the priority inversion problem.<br>
 * When a thread is queued on a mutex, any thread, directly or indirectly,
 * holding the mutex gains the same priority of the waiting thread (if their
 * priority was not already equal or higher). The mechanism works with any
 * number of nested mutexes and any number of involved threads. The algorithm
 * complexity (worst case) is N with N equal to the number of nested mutexes.
 * @file mutexes.h Mutexes macros and structures.
 * @file chmtx.c Mutexes functions.
 */
/** @} */

/**
 * @defgroup Events Events
 * @{
 * Event Sources and Event Listeners.<br>
 * <b>Operation mode</b><br><br>
 * An Event Source is a special object that can be signaled by a thread or
 * an interrupt service routine. Signaling an Event Source has the effect
 * that all the threads registered on the Event Source will receive
 * and serve the event.<br>
 * An unlimited number of Event Sources can exists in a system and each
 * thread can listen on an unlimited number of them.<br>
 * Note that the events can be asynchronously generated but are synchronously
 * served, a thread can serve event by calling the \p chEvtWait()
 * API. If an event is generated while a listening thread is not ready to
 * serve it then the event becomes "pending" and will be served as soon the
 * thread invokes the \p chEvtWait().<br>
 * In order to use the Event APIs the \p CH_USE_EVENTS option must be
 * specified in \p chconf.h.
 * @file events.h Events macros and structures.
 * @file chevents.c Events functions.
 */
/** @} */

/**
 * @defgroup Messages Messages
 * @{
 * Synchronous Messages.<br>
 * <b>Operation Mode</b><br><br>
 * Messages are an easy to use and fast IPC mechanism, threads can both serve
 * messages and send messages to other threads, the mechanism allows data to
 * be carryed in both directions. Data is not copyed between the client and
 * server threads but just a pointer passed so the exchange is very time
 * efficient.<br>
 * Messages are usually processed in FIFO order but it is possible to process
 * them in priority order by specifying CH_USE_MESSAGES_PRIORITY 
 * in \p chconf.h.<br>
 * Threads do not need to allocate space for message queues, the mechanism
 * just requires two extra pointers in the \p Thread structure (the message
 * queue header).<br>
 * In order to use the Messages APIs the \p CH_USE_MESSAGES option must be
 * specified in \p chconf.h.
 * @file messages.h	Messages macros and structures.
 * @file chmsg.c Messages functions.
 */
/** @} */

/**
 * @defgroup IOQueues I/O Queues
 * @{
 * ChibiOS/RT supports several kinds of queues. The queues are mostly used
 * in serial-like device drivers. The device drivers are usually designed to
 * have a lower side (lower driver, it is usually an interrupt service
 * routine) and an upper side (upper driver, accessed by the application
 * threads).<br>
 * There are several kind of queues:<br>
 * <ul>
 * <li><b>Input queue</b>, monodirectional queue where the writer is the
 *     lower side and the reader is the upper side.</li>
 * <li><b>Output queue</b>, monodirectional queue where the writer is the
 *     upper side and the reader is the lower side.</li>
 * <li><b>Half duplex queue</b>, bidirectional queue where the buffer is shared
 *     between a receive and a transmit queues. This means that concurrent
 *     buffered input and output operations are not possible, this is perfectly
 *     acceptable for a lot of applications however, as example an RS485 driver.
 * <li><b>Full duplex queue</b>, bidirectional queue where read and write
 *     operations can happen at the same time. Full duplex queues
 *     are implemented by pairing an input queue and an output queue together.
 * </ul>
 * In order to use the I/O queues the \p CH_USE_QUEUES option must
 * be specified in \p chconf.h.<br>
 * In order to use the half duplex queues the \p CH_USE_QUEUES_HALFDUPLEX
 * option must be specified in \p chconf.h.
 * @file queues.h I/O Queues macros and structures.
 * @file chqueues.c I/O Queues code.
 */
/** @} */

/**
 * @defgroup Serial Serial Drivers
 * @{
 * This module implements a generic full duplex serial driver and a generic
 * half duplex serial driver. It uses the I/O Queues for communication between
 * the upper and the lower driver and events to notify the application about
 * incoming data, outcoming data and other I/O events.
 * The  module also contains functions that make the implementation of the
 * interrupt service routines much easier.<br>
 * In order to use the serial full duplex driver the
 * \p CH_USE_SERIAL_FULLDUPLEX option must be specified in \p chconf.h.<br>
 * In order to use the serial half duplex driver the
 * \p CH_USE_SERIAL_HALFDUPLEX option must be specified in \p chconf.h.
 * @file serial.h Serial Drivers macros and structures.
 * @file chserial.c Serial Drivers code.
 */
/** @} */

/**
 * @defgroup CPlusPlusLibrary C++ Wrapper
 * @{
 * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities
 * from C++ as classes and objects rather the traditional "C" APIs.
 * @file ch.hpp C++ wrapper classes and definitions.
 * @file ch.cpp C++ wrapper code.
 */
/** @} */