Rev Author Line No. Line
2971 jichapav 1 /*
2 ChibiOS/RT - Copyright (C) 2006-2013 Giovanni Di Sirio
3  
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7  
8 http://www.apache.org/licenses/LICENSE-2.0
9  
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16  
17 /**
18 * @file templates/chconf.h
19 * @brief Configuration file template.
20 * @details A copy of this file must be placed in each project directory, it
21 * contains the application specific kernel settings.
22 *
23 * @addtogroup config
24 * @details Kernel related settings and hooks.
25 * @{
26 */
27  
28 #ifndef _CHCONF_H_
29 #define _CHCONF_H_
30  
31 /*===========================================================================*/
32 /**
33 * @name Kernel parameters and options
34 * @{
35 */
36 /*===========================================================================*/
37  
38 /**
39 * @brief System tick frequency.
40 * @details Frequency of the system timer that drives the system ticks. This
41 * setting also defines the system tick time unit.
42 */
43 #if !defined(CH_FREQUENCY) || defined(__DOXYGEN__)
44 #define CH_FREQUENCY 1000
45 #endif
46  
47 /**
48 * @brief Round robin interval.
49 * @details This constant is the number of system ticks allowed for the
50 * threads before preemption occurs. Setting this value to zero
51 * disables the preemption for threads with equal priority and the
52 * round robin becomes cooperative. Note that higher priority
53 * threads can still preempt, the kernel is always preemptive.
54 *
55 * @note Disabling the round robin preemption makes the kernel more compact
56 * and generally faster.
57 */
58 #if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
59 #define CH_TIME_QUANTUM 20
60 #endif
61  
62 /**
63 * @brief Managed RAM size.
64 * @details Size of the RAM area to be managed by the OS. If set to zero
65 * then the whole available RAM is used. The core memory is made
66 * available to the heap allocator and/or can be used directly through
67 * the simplified core memory allocator.
68 *
69 * @note In order to let the OS manage the whole RAM the linker script must
70 * provide the @p __heap_base__ and @p __heap_end__ symbols.
71 * @note Requires @p CH_USE_MEMCORE.
72 */
73 #if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
74 #define CH_MEMCORE_SIZE 0
75 #endif
76  
77 /**
78 * @brief Idle thread automatic spawn suppression.
79 * @details When this option is activated the function @p chSysInit()
80 * does not spawn the idle thread automatically. The application has
81 * then the responsibility to do one of the following:
82 * - Spawn a custom idle thread at priority @p IDLEPRIO.
83 * - Change the main() thread priority to @p IDLEPRIO then enter
84 * an endless loop. In this scenario the @p main() thread acts as
85 * the idle thread.
86 * .
87 * @note Unless an idle thread is spawned the @p main() thread must not
88 * enter a sleep state.
89 */
90 #if !defined(CH_NO_IDLE_THREAD) || defined(__DOXYGEN__)
91 #define CH_NO_IDLE_THREAD FALSE
92 #endif
93  
94 /** @} */
95  
96 /*===========================================================================*/
97 /**
98 * @name Performance options
99 * @{
100 */
101 /*===========================================================================*/
102  
103 /**
104 * @brief OS optimization.
105 * @details If enabled then time efficient rather than space efficient code
106 * is used when two possible implementations exist.
107 *
108 * @note This is not related to the compiler optimization options.
109 * @note The default is @p TRUE.
110 */
111 #if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
112 #define CH_OPTIMIZE_SPEED TRUE
113 #endif
114  
115 /** @} */
116  
117 /*===========================================================================*/
118 /**
119 * @name Subsystem options
120 * @{
121 */
122 /*===========================================================================*/
123  
124 /**
125 * @brief Threads registry APIs.
126 * @details If enabled then the registry APIs are included in the kernel.
127 *
128 * @note The default is @p TRUE.
129 */
130 #if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
131 #define CH_USE_REGISTRY TRUE
132 #endif
133  
134 /**
135 * @brief Threads synchronization APIs.
136 * @details If enabled then the @p chThdWait() function is included in
137 * the kernel.
138 *
139 * @note The default is @p TRUE.
140 */
141 #if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
142 #define CH_USE_WAITEXIT TRUE
143 #endif
144  
145 /**
146 * @brief Semaphores APIs.
147 * @details If enabled then the Semaphores APIs are included in the kernel.
148 *
149 * @note The default is @p TRUE.
150 */
151 #if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
152 #define CH_USE_SEMAPHORES TRUE
153 #endif
154  
155 /**
156 * @brief Semaphores queuing mode.
157 * @details If enabled then the threads are enqueued on semaphores by
158 * priority rather than in FIFO order.
159 *
160 * @note The default is @p FALSE. Enable this if you have special requirements.
161 * @note Requires @p CH_USE_SEMAPHORES.
162 */
163 #if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
164 #define CH_USE_SEMAPHORES_PRIORITY FALSE
165 #endif
166  
167 /**
168 * @brief Atomic semaphore API.
169 * @details If enabled then the semaphores the @p chSemSignalWait() API
170 * is included in the kernel.
171 *
172 * @note The default is @p TRUE.
173 * @note Requires @p CH_USE_SEMAPHORES.
174 */
175 #if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
176 #define CH_USE_SEMSW TRUE
177 #endif
178  
179 /**
180 * @brief Mutexes APIs.
181 * @details If enabled then the mutexes APIs are included in the kernel.
182 *
183 * @note The default is @p TRUE.
184 */
185 #if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
186 #define CH_USE_MUTEXES TRUE
187 #endif
188  
189 /**
190 * @brief Conditional Variables APIs.
191 * @details If enabled then the conditional variables APIs are included
192 * in the kernel.
193 *
194 * @note The default is @p TRUE.
195 * @note Requires @p CH_USE_MUTEXES.
196 */
197 #if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
198 #define CH_USE_CONDVARS TRUE
199 #endif
200  
201 /**
202 * @brief Conditional Variables APIs with timeout.
203 * @details If enabled then the conditional variables APIs with timeout
204 * specification are included in the kernel.
205 *
206 * @note The default is @p TRUE.
207 * @note Requires @p CH_USE_CONDVARS.
208 */
209 #if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
210 #define CH_USE_CONDVARS_TIMEOUT TRUE
211 #endif
212  
213 /**
214 * @brief Events Flags APIs.
215 * @details If enabled then the event flags APIs are included in the kernel.
216 *
217 * @note The default is @p TRUE.
218 */
219 #if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
220 #define CH_USE_EVENTS TRUE
221 #endif
222  
223 /**
224 * @brief Events Flags APIs with timeout.
225 * @details If enabled then the events APIs with timeout specification
226 * are included in the kernel.
227 *
228 * @note The default is @p TRUE.
229 * @note Requires @p CH_USE_EVENTS.
230 */
231 #if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
232 #define CH_USE_EVENTS_TIMEOUT TRUE
233 #endif
234  
235 /**
236 * @brief Synchronous Messages APIs.
237 * @details If enabled then the synchronous messages APIs are included
238 * in the kernel.
239 *
240 * @note The default is @p TRUE.
241 */
242 #if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
243 #define CH_USE_MESSAGES TRUE
244 #endif
245  
246 /**
247 * @brief Synchronous Messages queuing mode.
248 * @details If enabled then messages are served by priority rather than in
249 * FIFO order.
250 *
251 * @note The default is @p FALSE. Enable this if you have special requirements.
252 * @note Requires @p CH_USE_MESSAGES.
253 */
254 #if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
255 #define CH_USE_MESSAGES_PRIORITY FALSE
256 #endif
257  
258 /**
259 * @brief Mailboxes APIs.
260 * @details If enabled then the asynchronous messages (mailboxes) APIs are
261 * included in the kernel.
262 *
263 * @note The default is @p TRUE.
264 * @note Requires @p CH_USE_SEMAPHORES.
265 */
266 #if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
267 #define CH_USE_MAILBOXES TRUE
268 #endif
269  
270 /**
271 * @brief I/O Queues APIs.
272 * @details If enabled then the I/O queues APIs are included in the kernel.
273 *
274 * @note The default is @p TRUE.
275 */
276 #if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
277 #define CH_USE_QUEUES TRUE
278 #endif
279  
280 /**
281 * @brief Core Memory Manager APIs.
282 * @details If enabled then the core memory manager APIs are included
283 * in the kernel.
284 *
285 * @note The default is @p TRUE.
286 */
287 #if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
288 #define CH_USE_MEMCORE TRUE
289 #endif
290  
291 /**
292 * @brief Heap Allocator APIs.
293 * @details If enabled then the memory heap allocator APIs are included
294 * in the kernel.
295 *
296 * @note The default is @p TRUE.
297 * @note Requires @p CH_USE_MEMCORE and either @p CH_USE_MUTEXES or
298 * @p CH_USE_SEMAPHORES.
299 * @note Mutexes are recommended.
300 */
301 #if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
302 #define CH_USE_HEAP TRUE
303 #endif
304  
305 /**
306 * @brief C-runtime allocator.
307 * @details If enabled the the heap allocator APIs just wrap the C-runtime
308 * @p malloc() and @p free() functions.
309 *
310 * @note The default is @p FALSE.
311 * @note Requires @p CH_USE_HEAP.
312 * @note The C-runtime may or may not require @p CH_USE_MEMCORE, see the
313 * appropriate documentation.
314 */
315 #if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
316 #define CH_USE_MALLOC_HEAP FALSE
317 #endif
318  
319 /**
320 * @brief Memory Pools Allocator APIs.
321 * @details If enabled then the memory pools allocator APIs are included
322 * in the kernel.
323 *
324 * @note The default is @p TRUE.
325 */
326 #if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
327 #define CH_USE_MEMPOOLS TRUE
328 #endif
329  
330 /**
331 * @brief Dynamic Threads APIs.
332 * @details If enabled then the dynamic threads creation APIs are included
333 * in the kernel.
334 *
335 * @note The default is @p TRUE.
336 * @note Requires @p CH_USE_WAITEXIT.
337 * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
338 */
339 #if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
340 #define CH_USE_DYNAMIC TRUE
341 #endif
342  
343 /** @} */
344  
345 /*===========================================================================*/
346 /**
347 * @name Debug options
348 * @{
349 */
350 /*===========================================================================*/
351  
352 /**
353 * @brief Debug option, system state check.
354 * @details If enabled the correct call protocol for system APIs is checked
355 * at runtime.
356 *
357 * @note The default is @p FALSE.
358 */
359 #if !defined(CH_DBG_SYSTEM_STATE_CHECK) || defined(__DOXYGEN__)
360 #define CH_DBG_SYSTEM_STATE_CHECK FALSE
361 #endif
362  
363 /**
364 * @brief Debug option, parameters checks.
365 * @details If enabled then the checks on the API functions input
366 * parameters are activated.
367 *
368 * @note The default is @p FALSE.
369 */
370 #if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
371 #define CH_DBG_ENABLE_CHECKS FALSE
372 #endif
373  
374 /**
375 * @brief Debug option, consistency checks.
376 * @details If enabled then all the assertions in the kernel code are
377 * activated. This includes consistency checks inside the kernel,
378 * runtime anomalies and port-defined checks.
379 *
380 * @note The default is @p FALSE.
381 */
382 #if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
383 #define CH_DBG_ENABLE_ASSERTS FALSE
384 #endif
385  
386 /**
387 * @brief Debug option, trace buffer.
388 * @details If enabled then the context switch circular trace buffer is
389 * activated.
390 *
391 * @note The default is @p FALSE.
392 */
393 #if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
394 #define CH_DBG_ENABLE_TRACE FALSE
395 #endif
396  
397 /**
398 * @brief Debug option, stack checks.
399 * @details If enabled then a runtime stack check is performed.
400 *
401 * @note The default is @p FALSE.
402 * @note The stack check is performed in a architecture/port dependent way.
403 * It may not be implemented or some ports.
404 * @note The default failure mode is to halt the system with the global
405 * @p panic_msg variable set to @p NULL.
406 */
407 #if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
408 #define CH_DBG_ENABLE_STACK_CHECK FALSE
409 #endif
410  
411 /**
412 * @brief Debug option, stacks initialization.
413 * @details If enabled then the threads working area is filled with a byte
414 * value when a thread is created. This can be useful for the
415 * runtime measurement of the used stack.
416 *
417 * @note The default is @p FALSE.
418 */
419 #if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
420 #define CH_DBG_FILL_THREADS FALSE
421 #endif
422  
423 /**
424 * @brief Debug option, threads profiling.
425 * @details If enabled then a field is added to the @p Thread structure that
426 * counts the system ticks occurred while executing the thread.
427 *
428 * @note The default is @p TRUE.
429 * @note This debug option is defaulted to TRUE because it is required by
430 * some test cases into the test suite.
431 */
432 #if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
433 #define CH_DBG_THREADS_PROFILING TRUE
434 #endif
435  
436 /** @} */
437  
438 /*===========================================================================*/
439 /**
440 * @name Kernel hooks
441 * @{
442 */
443 /*===========================================================================*/
444  
445 /**
446 * @brief Threads descriptor structure extension.
447 * @details User fields added to the end of the @p Thread structure.
448 */
449 #if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
450 #define THREAD_EXT_FIELDS \
451 /* Add threads custom fields here.*/
452 #endif
453  
454 /**
455 * @brief Threads initialization hook.
456 * @details User initialization code added to the @p chThdInit() API.
457 *
458 * @note It is invoked from within @p chThdInit() and implicitly from all
459 * the threads creation APIs.
460 */
461 #if !defined(THREAD_EXT_INIT_HOOK) || defined(__DOXYGEN__)
462 #define THREAD_EXT_INIT_HOOK(tp) { \
463 /* Add threads initialization code here.*/ \
464 }
465 #endif
466  
467 /**
468 * @brief Threads finalization hook.
469 * @details User finalization code added to the @p chThdExit() API.
470 *
471 * @note It is inserted into lock zone.
472 * @note It is also invoked when the threads simply return in order to
473 * terminate.
474 */
475 #if !defined(THREAD_EXT_EXIT_HOOK) || defined(__DOXYGEN__)
476 #define THREAD_EXT_EXIT_HOOK(tp) { \
477 /* Add threads finalization code here.*/ \
478 }
479 #endif
480  
481 /**
482 * @brief Context switch hook.
483 * @details This hook is invoked just before switching between threads.
484 */
485 #if !defined(THREAD_CONTEXT_SWITCH_HOOK) || defined(__DOXYGEN__)
486 #define THREAD_CONTEXT_SWITCH_HOOK(ntp, otp) { \
487 /* System halt code here.*/ \
488 }
489 #endif
490  
491 /**
492 * @brief Idle Loop hook.
493 * @details This hook is continuously invoked by the idle thread loop.
494 */
495 #if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
496 #define IDLE_LOOP_HOOK() { \
497 /* Idle loop code here.*/ \
498 }
499 #endif
500  
501 /**
502 * @brief System tick event hook.
503 * @details This hook is invoked in the system tick handler immediately
504 * after processing the virtual timers queue.
505 */
506 #if !defined(SYSTEM_TICK_EVENT_HOOK) || defined(__DOXYGEN__)
507 #define SYSTEM_TICK_EVENT_HOOK() { \
508 /* System tick event code here.*/ \
509 }
510 #endif
511  
512 /**
513 * @brief System halt hook.
514 * @details This hook is invoked in case to a system halting error before
515 * the system is halted.
516 */
517 #if !defined(SYSTEM_HALT_HOOK) || defined(__DOXYGEN__)
518 #define SYSTEM_HALT_HOOK() { \
519 /* System halt code here.*/ \
520 }
521 #endif
522  
523 /** @} */
524  
525 /*===========================================================================*/
526 /* Port-specific settings (override port settings defaulted in chcore.h). */
527 /*===========================================================================*/
528  
529 #endif /* _CHCONF_H_ */
530  
531 /** @} */