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
|
/*
ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
ChibiOS/RT is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
ChibiOS/RT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* @mainpage ChibiOS/RT
* @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
*
* <h2>Chibi ?</h2>
* I didn't want a serious name for this project. 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">ちび</span>OS/RT) @endhtmlonly
* means small Real Time Operating System.
* Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.
*
* <h2>Features</h2>
* - Free software, GPL3 licensed. Stable releases include a exception clause
* to the GPL.
* - Designed for realtime applications.
* - Easily portable.
* - Preemptive scheduling.
* - 128 priority levels. Multiple threads at the same priority level allowed.
* - Round robin scheduling for threads at the same priority level.
* - Offers threads, virtual timers, semaphores, mutexes, condvars,
* event flags, messages, I/O queues.
* - No static setup at compile time, there is no need to configure a maximum
* number of all the above objects.
* - PC simulator target included, the development can be done on the PC
* using MinGW.<br>
* 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 demo available.
* - No *need* for a memory allocator, all the kernel structures are static
* and declaratively allocated.
* - Optional, thread safe, Heap Allocator subsystem.
* - Optional, thread safe, Memory Pools Allocator subsystem.
* - Blocking and non blocking I/O channels with timeout and events generation
* capability.
* - 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.
* - Almost totally written in C with little ASM code required for ports.
* .
* <h2>Related pages</h2>
* - @subpage lic_faq
* - @subpage goals
* - @subpage concepts
* - @subpage articles
* .
*/
/**
* @defgroup Ports Ports
* @{
* This section describes the technical details for the various supported
* ChibiOS/RT ports.
*/
/** @} */
/**
* @defgroup Kernel Kernel
* @{
*/
/** @} */
/**
* @defgroup Config Configuration
* @{
* In @p chconf.h are defined the required subsystems for your application.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Core Generic Port Code Templates
* @{
* Non portable code templates.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Types Types
* @{
* System types and macros.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup System System Management
* @{
* Initialization, Locks, Interrupt Handling, Power Management, Abnormal
* Termination.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Inline Inline
* @{
* System inline-able code.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Debug Debug
* @{
* Debug APIs and procedures.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Scheduler Scheduler
* @{
* ChibiOS/RT scheduler.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup ThreadLists Thread Lists and Queues
* @{
* ChibiOS/RT thread lists and queues utilities.
* @ingroup Kernel
*/
/** @} */
/**
* @defgroup Threads Threads
* @{
* Threads creation and termination APIs.
*/
/** @} */
/**
* @defgroup Time Time and Virtual Timers
* @{
* Time and Virtual Timers related APIs.
*/
/** @} */
/**
* @defgroup Heap Heap
* @{
* Heap Allocator related APIs.
* <h2>Operation mode</h2>
* 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.
*/
/** @} */
/**
* @defgroup MemoryPools Memory Pools
* @{
* Memory Pools related APIs.
* <h2>Operation mode</h2>
* 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.
*/
/** @} */
/**
* @defgroup Semaphores Semaphores
* @{
* Semaphores and threads synchronization.
* <h2>Operation mode</h2>
* A semaphore is a threads synchronization object, some operations
* are defined on semaphores:
* - <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.
* - <b>Wait</b>: The semaphore counter is decreased and if the result
* becomes negative the thread is queued in the semaphore and suspended.
* - <b>Reset</b>: The semaphore counter is reset to a non-negative value
* and all the threads in the queue are released.
* .
* Semaphores can be used as guards for mutual exclusion code zones (note that
* mutexes are recommended for this kind of use) but also have other uses,
* queues guards and counters as example.<br>
* Semaphores usually use FIFO queues but it is possible to make them
* order threads by priority by specifying CH_USE_SEMAPHORES_PRIORITY in
* @p chconf.h.<br>
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES
* option must be specified in @p chconf.h.<br><br>
*/
/** @} */
/**
* @defgroup Mutexes Mutexes
* @{
* Mutexes and threads synchronization.
* <h2>Operation mode</h2>
* A mutex is a threads synchronization object, some operations are defined
* on mutexes:
* - <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.
* - <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.
* .
* In order to use the Event APIs the @p CH_USE_MUTEXES option must be
* specified in @p chconf.h.<br>
*
* <h2>Constraints</h2>
* 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.
*
* <h2>The priority inversion problem</h2>
* 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.
*/
/** @} */
/**
* @defgroup CondVars Condition Variables
* @{
* Condition Variables and threads synchronization.
* <h2>Operation mode</h2>
* The condition variable is a synchronization object meant to be used inside
* a zone protected by a @p Mutex. Mutexes and CondVars together can implement
* a Monitor construct.<br>
* In order to use the Condition Variables APIs the @p CH_USE_CONDVARS
* option must be specified in @p chconf.h.<br><br>
*/
/** @} */
/**
* @defgroup Events Events
* @{
* Event Sources and Event Listeners.
* <h2>Operation mode</h2>
* 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 a @p chEvtWaitXXX()
* 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 a @p chEvtWaitXXX().<br>
* In order to use the Event APIs the @p CH_USE_EVENTS option must be
* specified in @p chconf.h.
*/
/** @} */
/**
* @defgroup Messages Messages
* @{
* Synchronous inter-thread messages.
* <h2>Operation Mode</h2>
* 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 carried in both directions. Data is not copied 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.
*/
/** @} */
/**
* @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>
* - <b>Input queue</b>, unidirectional queue where the writer is the
* lower side and the reader is the upper side.
* - <b>Output queue</b>, unidirectional queue where the writer is the
* upper side and the reader is the lower side.
* - <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.
* - <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.
* .
* 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.
*/
/** @} */
/**
* @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.
*/
/** @} */
/**
* @defgroup utilities_library Utilities Library
* @{
* @brief Utilities Library.
* @details This is a collection of useful library code that is not part of
* the base kernel services.
* <h2>Notes</h2>
* The library code does not follow the same naming convention of the
* system APIs in order to make very clear that it is not "core" code.<br>
* The main difference is that library code is not formally tested in the
* test suite but through usage in the various demo applications.
*/
/** @} */
/**
* @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.
*
* @ingroup utilities_library
*/
/** @} */
/**
* @defgroup event_timer Events Generator Timer
* @{
* @brief Event Generator Timer.
* @details This timer generates an event at regular intervals. The
* listening threads can use the event to perform time related activities.
* Multiple threads can listen to the same timer.
*
* @ingroup utilities_library
*/
/** @} */
|