diff options
| -rw-r--r-- | demos/ARM7-AT91SAM7X-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARM7-AT91SAM7X-LWIP-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARM7-AT91SAM7X-UIP-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARM7-LPC214x-FATFS-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARM7-LPC214x-G++/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARM7-LPC214x-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARMCM3-STM32F103-FATFS-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/ARMCM3-STM32F103-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/AVR-AT90CANx-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/AVR-ATmega128-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/MSP430-MSP430x1611-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/PPC-SPC563-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/Posix-GCC/chconf.h | 215 | ||||
| -rw-r--r-- | demos/STM8S-STM8S208-RC/chconf.h | 1 | ||||
| -rw-r--r-- | demos/Win32-MinGW/chconf.h | 215 | ||||
| -rw-r--r-- | os/kernel/include/chschd.h | 34 | ||||
| -rw-r--r-- | os/kernel/src/chschd.c | 9 | ||||
| -rw-r--r-- | os/kernel/src/chsys.c | 3 | ||||
| -rw-r--r-- | os/ports/GCC/ARMCM3/chcore.c | 10 | ||||
| -rw-r--r-- | readme.txt | 4 | ||||
| -rw-r--r-- | test/coverage/chconf.h | 215 | ||||
| -rw-r--r-- | testhal/STM32/chconf.h | 215 |
22 files changed, 1838 insertions, 1663 deletions
diff --git a/demos/ARM7-AT91SAM7X-GCC/chconf.h b/demos/ARM7-AT91SAM7X-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARM7-AT91SAM7X-GCC/chconf.h +++ b/demos/ARM7-AT91SAM7X-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARM7-AT91SAM7X-LWIP-GCC/chconf.h b/demos/ARM7-AT91SAM7X-LWIP-GCC/chconf.h index 47f38904b..367215352 100644 --- a/demos/ARM7-AT91SAM7X-LWIP-GCC/chconf.h +++ b/demos/ARM7-AT91SAM7X-LWIP-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -435,11 +444,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -449,12 +458,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -463,7 +472,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARM7-AT91SAM7X-UIP-GCC/chconf.h b/demos/ARM7-AT91SAM7X-UIP-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARM7-AT91SAM7X-UIP-GCC/chconf.h +++ b/demos/ARM7-AT91SAM7X-UIP-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARM7-LPC214x-FATFS-GCC/chconf.h b/demos/ARM7-LPC214x-FATFS-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARM7-LPC214x-FATFS-GCC/chconf.h +++ b/demos/ARM7-LPC214x-FATFS-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARM7-LPC214x-G++/chconf.h b/demos/ARM7-LPC214x-G++/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARM7-LPC214x-G++/chconf.h +++ b/demos/ARM7-LPC214x-G++/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARM7-LPC214x-GCC/chconf.h b/demos/ARM7-LPC214x-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARM7-LPC214x-GCC/chconf.h +++ b/demos/ARM7-LPC214x-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARMCM3-STM32F103-FATFS-GCC/chconf.h b/demos/ARMCM3-STM32F103-FATFS-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARMCM3-STM32F103-FATFS-GCC/chconf.h +++ b/demos/ARMCM3-STM32F103-FATFS-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/ARMCM3-STM32F103-GCC/chconf.h b/demos/ARMCM3-STM32F103-GCC/chconf.h index 300a85579..046d28300 100644 --- a/demos/ARMCM3-STM32F103-GCC/chconf.h +++ b/demos/ARMCM3-STM32F103-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/AVR-AT90CANx-GCC/chconf.h b/demos/AVR-AT90CANx-GCC/chconf.h index c32d36bdc..2cda27e83 100644 --- a/demos/AVR-AT90CANx-GCC/chconf.h +++ b/demos/AVR-AT90CANx-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 128
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/AVR-ATmega128-GCC/chconf.h b/demos/AVR-ATmega128-GCC/chconf.h index c32d36bdc..2cda27e83 100644 --- a/demos/AVR-ATmega128-GCC/chconf.h +++ b/demos/AVR-ATmega128-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 128
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/MSP430-MSP430x1611-GCC/chconf.h b/demos/MSP430-MSP430x1611-GCC/chconf.h index 5629c38e3..2a40e33e2 100644 --- a/demos/MSP430-MSP430x1611-GCC/chconf.h +++ b/demos/MSP430-MSP430x1611-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 10
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 512
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/PPC-SPC563-GCC/chconf.h b/demos/PPC-SPC563-GCC/chconf.h index 557c2a5a1..046d28300 100644 --- a/demos/PPC-SPC563-GCC/chconf.h +++ b/demos/PPC-SPC563-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,22 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
* disables the preemption for threads with equal priority and the
* round robin becomes cooperative. Note that higher priority
* threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling the round robin preemption makes the kernel more compact
- * and generally faster.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -64,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -90,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -126,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
+ * @brief Atomic semaphore API.
* @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -349,73 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
- * @note The default failure mode is to halt the system with the global
- * @p panic_msg variable set to @p NULL.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -426,20 +431,22 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
#define THREAD_EXT_FIELDS \
- /* Add threads custom fields here.*/
+struct { \
+ /* Add threads custom fields here.*/ \
+};
#endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -448,12 +455,12 @@ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -462,7 +469,7 @@ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/Posix-GCC/chconf.h b/demos/Posix-GCC/chconf.h index 2f45fb0f3..dd249746f 100644 --- a/demos/Posix-GCC/chconf.h +++ b/demos/Posix-GCC/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0x20000
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/demos/STM8S-STM8S208-RC/chconf.h b/demos/STM8S-STM8S208-RC/chconf.h index 26d33b883..5643c94e7 100644 --- a/demos/STM8S-STM8S208-RC/chconf.h +++ b/demos/STM8S-STM8S208-RC/chconf.h @@ -24,6 +24,7 @@ * contains the application specific kernel settings.
*
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
diff --git a/demos/Win32-MinGW/chconf.h b/demos/Win32-MinGW/chconf.h index 2f45fb0f3..dd249746f 100644 --- a/demos/Win32-MinGW/chconf.h +++ b/demos/Win32-MinGW/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0x20000
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/os/kernel/include/chschd.h b/os/kernel/include/chschd.h index d1b69cad5..3847c948e 100644 --- a/os/kernel/include/chschd.h +++ b/os/kernel/include/chschd.h @@ -92,11 +92,33 @@ typedef struct { extern ReadyList rlist;
#endif /* !defined(PORT_OPTIMIZED_RLIST_EXT) */
-#ifdef CH_CURRP_REGISTER_CACHE
-register Thread *currp asm(CH_CURRP_REGISTER_CACHE);
-#else
+/**
+ * @brief Current thread pointer access macro. + * @note This macro is not meant to be used in the application code but
+ * only from within the kernel, use the @p chThdSelf() API instead.
+ * @note It is forbidden to use this macro in order to change the pointer
+ * (currp = something), use @p setcurrp() instead.
+ */
+#if !defined(PORT_OPTIMIZED_CURRP) || defined(__DOXYGEN__)
+#if !defined(CH_CURRP_REGISTER_CACHE) || defined(__DOXYGEN__)
#define currp rlist.r_current
-#endif
+#else /* defined(CH_CURRP_REGISTER_CACHE) */
+register Thread *currp asm(CH_CURRP_REGISTER_CACHE);
+#endif /* defined(CH_CURRP_REGISTER_CACHE) */
+#endif /* !defined(PORT_OPTIMIZED_CURRP) */
+
+/**
+ * @brief Current thread pointer change macro.
+ * @note This macro is not meant to be used in the application code but
+ * only from within the kernel.
+ */
+#if !defined(PORT_OPTIMIZED_SETCURRP) || defined(__DOXYGEN__)
+#if !defined(CH_CURRP_REGISTER_CACHE) || defined(__DOXYGEN__)
+#define setcurrp(tp) (rlist.r_current = (tp))
+#else /* defined(CH_CURRP_REGISTER_CACHE) */
+(currp = (tp))
+#endif /* defined(CH_CURRP_REGISTER_CACHE) */
+#endif /* !defined(PORT_OPTIMIZED_SETCURRP) */
/*
* Scheduler APIs.
@@ -135,7 +157,7 @@ extern "C" { * @details This function returns @p TRUE if there is a ready thread with
* higher priority.
*/
-#if !defined(PORT_OPTIMIZED_ISRESCHREQUIREDI) && !defined(__DOXYGEN__)
+#if !defined(PORT_OPTIMIZED_ISRESCHREQUIREDI) || defined(__DOXYGEN__)
#define chSchIsRescRequiredI() (firstprio(&rlist.r_queue) > currp->p_prio)
#endif /* !defined(PORT_OPTIMIZED_ISRESCHREQUIREDI) */
@@ -144,7 +166,7 @@ extern "C" { * @details This function returns @p TRUE if there is a ready thread with
* equal or higher priority.
*/
-#if !defined(PORT_OPTIMIZED_CANYIELDS) && !defined(__DOXYGEN__)
+#if !defined(PORT_OPTIMIZED_CANYIELDS) || defined(__DOXYGEN__)
#define chSchCanYieldS() (firstprio(&rlist.r_queue) >= currp->p_prio)
#endif /* !defined(PORT_OPTIMIZED_CANYIELDS) */
diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c index d5c8a0a5a..7170fb0ec 100644 --- a/os/kernel/src/chschd.c +++ b/os/kernel/src/chschd.c @@ -96,7 +96,8 @@ void chSchGoSleepS(tstate_t newstate) { Thread *otp;
(otp = currp)->p_state = newstate;
- (currp = fifo_remove(&rlist.r_queue))->p_state = THD_STATE_CURRENT;
+ setcurrp(fifo_remove(&rlist.r_queue));
+ currp->p_state = THD_STATE_CURRENT;
#if CH_TIME_QUANTUM > 0
rlist.r_preempt = CH_TIME_QUANTUM;
#endif
@@ -196,7 +197,8 @@ void chSchWakeupS(Thread *ntp, msg_t msg) { #if CH_TIME_QUANTUM > 0
rlist.r_preempt = CH_TIME_QUANTUM;
#endif
- (currp = ntp)->p_state = THD_STATE_CURRENT;
+ setcurrp(ntp);
+ ntp->p_state = THD_STATE_CURRENT;
chDbgTrace(ntp, otp);
chSysSwitchI(ntp, otp);
}
@@ -217,7 +219,8 @@ void chSchDoRescheduleI(void) { #endif
otp = currp;
/* Picks the first thread from the ready queue and makes it current.*/
- (currp = ntp = fifo_remove(&rlist.r_queue))->p_state = THD_STATE_CURRENT;
+ (ntp = fifo_remove(&rlist.r_queue))->p_state = THD_STATE_CURRENT;
+ setcurrp(ntp);
chSchReadyI(otp);
chDbgTrace(ntp, otp);
chSysSwitchI(ntp, otp);
diff --git a/os/kernel/src/chsys.c b/os/kernel/src/chsys.c index eeed4a998..1a66c8e98 100644 --- a/os/kernel/src/chsys.c +++ b/os/kernel/src/chsys.c @@ -80,7 +80,8 @@ void chSysInit(void) { #endif
/* Now this instructions flow becomes the main thread.*/
- (currp = init_thread(&mainthread, NORMALPRIO))->p_state = THD_STATE_CURRENT;
+ setcurrp(init_thread(&mainthread, NORMALPRIO));
+ currp->p_state = THD_STATE_CURRENT;
chSysEnable();
/* This thread has the lowest priority in the system, its role is just to
diff --git a/os/ports/GCC/ARMCM3/chcore.c b/os/ports/GCC/ARMCM3/chcore.c index e2caea969..f800c2fb7 100644 --- a/os/ports/GCC/ARMCM3/chcore.c +++ b/os/ports/GCC/ARMCM3/chcore.c @@ -144,7 +144,7 @@ void SVCallVector(Thread *ntp, Thread *otp) { __attribute__((naked))
#endif
void PendSVVector(void) {
- Thread *otp;
+ Thread *otp, *ntp;
register struct intctx *sp_thd asm("r12");
chSysLockFromIsr();
@@ -152,14 +152,16 @@ void PendSVVector(void) { PUSH_CONTEXT(sp_thd);
(otp = currp)->p_ctx.r13 = sp_thd;
- (currp = fifo_remove(&rlist.r_queue))->p_state = THD_STATE_CURRENT;
+ ntp = fifo_remove(&rlist.r_queue);
+ setcurrp(ntp);
+ ntp->p_state = THD_STATE_CURRENT;
chSchReadyI(otp);
#if CH_TIME_QUANTUM > 0
/* Set the round-robin time quantum.*/
rlist.r_preempt = CH_TIME_QUANTUM;
#endif
- chDbgTrace(otp, currp);
- sp_thd = currp->p_ctx.r13;
+ chDbgTrace(ntp, otp);
+ sp_thd = ntp->p_ctx.r13;
POP_CONTEXT(sp_thd);
}
diff --git a/readme.txt b/readme.txt index 915f7c498..1fc79adf2 100644 --- a/readme.txt +++ b/readme.txt @@ -87,6 +87,10 @@ - CHANGE: The module documentation has been moved from the kernel.dox file
to the various source code files in order to make it easier to maintain
and double as source comments.
+- CHANGE: Removed the support for the CH_CURRP_REGISTER_CACHE optimization
+ in the configuration files and in the scheduler header. It will be
+ reintroduced as an architecture-specific optimization using the new
+ capture mechanism (among other optimizations).
*** 1.5.3 ***
- FIX: Removed C99-style variables declarations (bug 2964418)(backported
diff --git a/test/coverage/chconf.h b/test/coverage/chconf.h index 988a6fd64..65ac31b4f 100644 --- a/test/coverage/chconf.h +++ b/test/coverage/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS TRUE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0x20000
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED FALSE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE TRUE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK TRUE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS TRUE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
diff --git a/testhal/STM32/chconf.h b/testhal/STM32/chconf.h index 300a85579..046d28300 100644 --- a/testhal/STM32/chconf.h +++ b/testhal/STM32/chconf.h @@ -18,9 +18,13 @@ */
/**
- * @file templates/chconf.h
- * @brief Configuration file template.
+ * @file templates/chconf.h
+ * @brief Configuration file template.
+ * @details A copy of this file must be placed in each project directory, it
+ * contains the application specific kernel settings.
+ *
* @addtogroup config
+ * @details Kernel related settings and hooks.
* @{
*/
@@ -32,7 +36,7 @@ /*===========================================================================*/
/**
- * @brief System tick frequency.
+ * @brief System tick frequency.
* @details Frequency of the system timer that drives the system ticks. This
* setting also defines the system tick time unit.
*/
@@ -41,20 +45,22 @@ #endif
/**
- * @brief Round robin interval.
+ * @brief Round robin interval.
* @details This constant is the number of system ticks allowed for the
* threads before preemption occurs. Setting this value to zero
- * disables the round robin mechanism.
+ * disables the preemption for threads with equal priority and the
+ * round robin becomes cooperative. Note that higher priority
+ * threads can still preempt, the kernel is always preemptive.
*
- * @note Disabling round robin makes the kernel more compact and generally
- * faster but forbids multiple threads at the same priority level.
+ * @note Disabling the round robin preemption makes the kernel more compact
+ * and generally faster.
*/
#if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)
#define CH_TIME_QUANTUM 20
#endif
/**
- * @brief Nested locks.
+ * @brief Nested locks.
* @details If enabled then the use of nested @p chSysLock() / @p chSysUnlock()
* operations is allowed.<br>
* For performance and code size reasons the recommended setting
@@ -62,22 +68,22 @@ * You may use this option if you need to merge ChibiOS/RT with
* external libraries that require nested lock/unlock operations.
*
- * @note The default is @p FALSE.
+ * @note T he default is @p FALSE.
*/
#if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)
#define CH_USE_NESTED_LOCKS FALSE
#endif
/**
- * @brief Managed RAM size.
+ * @brief Managed RAM size.
* @details Size of the RAM area to be managed by the OS. If set to zero
* then the whole available RAM is used. The core memory is made
* available to the heap allocator and/or can be used directly through
* the simplified core memory allocator.
*
- * @note In order to let the OS manage the whole RAM the linker script must
- * provide the @p __heap_base__ and @p __heap_end__ symbols.
- * @note Requires @p CH_USE_COREMEM.
+ * @note In order to let the OS manage the whole RAM the linker script must
+ * provide the @p __heap_base__ and @p __heap_end__ symbols.
+ * @note Requires @p CH_USE_COREMEM.
*/
#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)
#define CH_MEMCORE_SIZE 0
@@ -88,32 +94,32 @@ /*===========================================================================*/
/**
- * @brief OS optimization.
+ * @brief OS optimization.
* @details If enabled then time efficient rather than space efficient code
* is used when two possible implementations exist.
*
- * @note This is not related to the compiler optimization options.
- * @note The default is @p TRUE.
+ * @note This is not related to the compiler optimization options.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)
#define CH_OPTIMIZE_SPEED TRUE
#endif
/**
- * @brief Exotic optimization.
+ * @brief Exotic optimization.
* @details If defined then a CPU register is used as storage for the global
* @p currp variable. Caching this variable in a register greatly
* improves both space and time OS efficiency. A side effect is that
* one less register has to be saved during the context switch
* resulting in lower RAM usage and faster context switch.
*
- * @note This option is only usable with the GCC compiler and is only useful
- * on processors with many registers like ARM cores.
- * @note If this option is enabled then ALL the libraries linked to the
- * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
- * -ffixed-@<reg@>.
- * @note This option must be enabled in the Makefile, it is listed here for
- * documentation only.
+ * @note This option is only usable with the GCC compiler and is only useful
+ * on processors with many registers like ARM cores.
+ * @note If this option is enabled then ALL the libraries linked to the
+ * ChibiOS/RT code <b>must</b> be recompiled with the GCC option @p
+ * -ffixed-@<reg@>.
+ * @note This option must be enabled in the Makefile, it is listed here for
+ * documentation only.
*/
#if defined(__DOXYGEN__)
#define CH_CURRP_REGISTER_CACHE "reg"
@@ -124,219 +130,220 @@ /*===========================================================================*/
/**
- * @brief Threads registry APIs.
+ * @brief Threads registry APIs.
* @details If enabled then the registry APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_REGISTRY) || defined(__DOXYGEN__)
#define CH_USE_REGISTRY TRUE
#endif
/**
- * @brief Threads synchronization APIs.
+ * @brief Threads synchronization APIs.
* @details If enabled then the @p chThdWait() function is included in
* the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)
#define CH_USE_WAITEXIT TRUE
#endif
/**
- * @brief Semaphores APIs.
+ * @brief Semaphores APIs.
* @details If enabled then the Semaphores APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES TRUE
#endif
/**
- * @brief Semaphores queuing mode.
+ * @brief Semaphores queuing mode.
* @details If enabled then the threads are enqueued on semaphores by
* priority rather than in FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMAPHORES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_SEMAPHORES_PRIORITY FALSE
#endif
/**
- * @brief Atomic semaphore API.
- * @details If enabled then the semaphores the @p chSemWaitSignal() API
+ * @brief Atomic semaphore API.
+ * @details If enabled then the semaphores the @p chSemSignalWait() API
* is included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_SEMSW) || defined(__DOXYGEN__)
#define CH_USE_SEMSW TRUE
#endif
/**
- * @brief Mutexes APIs.
+ * @brief Mutexes APIs.
* @details If enabled then the mutexes APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)
#define CH_USE_MUTEXES TRUE
#endif
/**
- * @brief Conditional Variables APIs.
+ * @brief Conditional Variables APIs.
* @details If enabled then the conditional variables APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_MUTEXES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_MUTEXES.
*/
#if !defined(CH_USE_CONDVARS) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS TRUE
#endif
/**
- * @brief Conditional Variables APIs with timeout.
+ * @brief Conditional Variables APIs with timeout.
* @details If enabled then the conditional variables APIs with timeout
* specification are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_CONDVARS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_CONDVARS.
*/
#if !defined(CH_USE_CONDVARS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_CONDVARS_TIMEOUT TRUE
#endif
/**
- * @brief Events Flags APIs.
+ * @brief Events Flags APIs.
* @details If enabled then the event flags APIs are included in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)
#define CH_USE_EVENTS TRUE
#endif
/**
- * @brief Events Flags APIs with timeout.
+ * @brief Events Flags APIs with timeout.
* @details If enabled then the events APIs with timeout specification
* are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_EVENTS.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_EVENTS.
*/
#if !defined(CH_USE_EVENTS_TIMEOUT) || defined(__DOXYGEN__)
#define CH_USE_EVENTS_TIMEOUT TRUE
#endif
/**
- * @brief Synchronous Messages APIs.
+ * @brief Synchronous Messages APIs.
* @details If enabled then the synchronous messages APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES TRUE
#endif
/**
- * @brief Synchronous Messages queuing mode.
+ * @brief Synchronous Messages queuing mode.
* @details If enabled then messages are served by priority rather than in
* FIFO order.
*
- * @note The default is @p FALSE. Enable this if you have special requirements.
- * @note Requires @p CH_USE_MESSAGES.
+ * @note The default is @p FALSE. Enable this if you have special requirements.
+ * @note Requires @p CH_USE_MESSAGES.
*/
#if !defined(CH_USE_MESSAGES_PRIORITY) || defined(__DOXYGEN__)
#define CH_USE_MESSAGES_PRIORITY FALSE
#endif
/**
- * @brief Mailboxes APIs.
+ * @brief Mailboxes APIs.
* @details If enabled then the asynchronous messages (mailboxes) APIs are
* included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)
#define CH_USE_MAILBOXES TRUE
#endif
/**
- * @brief I/O Queues APIs.
+ * @brief I/O Queues APIs.
* @details If enabled then the I/O queues APIs are included in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_SEMAPHORES.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_SEMAPHORES.
*/
#if !defined(CH_USE_QUEUES) || defined(__DOXYGEN__)
#define CH_USE_QUEUES TRUE
#endif
/**
- * @brief Core Memory Manager APIs.
+ * @brief Core Memory Manager APIs.
* @details If enabled then the core memory manager APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMCORE) || defined(__DOXYGEN__)
#define CH_USE_MEMCORE TRUE
#endif
/**
- * @brief Heap Allocator APIs.
+ * @brief Heap Allocator APIs.
* @details If enabled then the memory heap allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
- * @p CH_USE_SEMAPHORES.
- * @note Mutexes are recommended.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_COREMEM and either @p CH_USE_MUTEXES or
+ * @p CH_USE_SEMAPHORES.
+ * @note Mutexes are recommended.
*/
#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)
#define CH_USE_HEAP TRUE
#endif
/**
- * @brief C-runtime allocator.
+ * @brief C-runtime allocator.
* @details If enabled the the heap allocator APIs just wrap the C-runtime
* @p malloc() and @p free() functions.
*
- * @note The default is @p FALSE.
- * @note Requires @p CH_USE_HEAP.
- * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
- * appropriate documentation.
+ * @note The default is @p FALSE.
+ * @note Requires @p CH_USE_HEAP.
+ * @note The C-runtime may or may not require @p CH_USE_COREMEM, see the
+ * appropriate documentation.
*/
#if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)
#define CH_USE_MALLOC_HEAP FALSE
#endif
/**
- * @brief Memory Pools Allocator APIs.
+ * @brief Memory Pools Allocator APIs.
* @details If enabled then the memory pools allocator APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
+ * @note The default is @p TRUE.
*/
#if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)
#define CH_USE_MEMPOOLS TRUE
#endif
/**
- * @brief Dynamic Threads APIs.
+ * @brief Dynamic Threads APIs.
* @details If enabled then the dynamic threads creation APIs are included
* in the kernel.
*
- * @note The default is @p TRUE.
- * @note Requires @p CH_USE_WAITEXIT.
+ * @note The default is @p TRUE.
+ * @note Requires @p CH_USE_WAITEXIT.
+ * @note Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.
*/
#if !defined(CH_USE_DYNAMIC) || defined(__DOXYGEN__)
#define CH_USE_DYNAMIC TRUE
@@ -347,71 +354,73 @@ /*===========================================================================*/
/**
- * @brief Debug option, parameters checks.
+ * @brief Debug option, parameters checks.
* @details If enabled then the checks on the API functions input
* parameters are activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_CHECKS FALSE
#endif
/**
- * @brief Debug option, consistency checks.
+ * @brief Debug option, consistency checks.
* @details If enabled then all the assertions in the kernel code are
* activated. This includes consistency checks inside the kernel,
* runtime anomalies and port-defined checks.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_ASSERTS FALSE
#endif
/**
- * @brief Debug option, trace buffer.
+ * @brief Debug option, trace buffer.
* @details If enabled then the context switch circular trace buffer is
* activated.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_TRACE FALSE
#endif
/**
- * @brief Debug option, stack checks.
+ * @brief Debug option, stack checks.
* @details If enabled then a runtime stack check is performed.
*
- * @note The default is @p FALSE.
- * @note The stack check is performed in a architecture/port dependent way. It
- * may not be implemented or some ports.
+ * @note The default is @p FALSE.
+ * @note The stack check is performed in a architecture/port dependent way.
+ * It may not be implemented or some ports.
+ * @note The default failure mode is to halt the system with the global
+ * @p panic_msg variable set to @p NULL.
*/
#if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)
#define CH_DBG_ENABLE_STACK_CHECK FALSE
#endif
/**
- * @brief Debug option, stacks initialization.
+ * @brief Debug option, stacks initialization.
* @details If enabled then the threads working area is filled with a byte
* value when a thread is created. This can be useful for the
* runtime measurement of the used stack.
*
- * @note The default is @p FALSE.
+ * @note The default is @p FALSE.
*/
#if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)
#define CH_DBG_FILL_THREADS FALSE
#endif
/**
- * @brief Debug option, threads profiling.
+ * @brief Debug option, threads profiling.
* @details If enabled then a field is added to the @p Thread structure that
* counts the system ticks occurred while executing the thread.
*
- * @note The default is @p TRUE.
- * @note This debug option is defaulted to TRUE because it is required by
- * some test cases into the test suite.
+ * @note The default is @p TRUE.
+ * @note This debug option is defaulted to TRUE because it is required by
+ * some test cases into the test suite.
*/
#if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)
#define CH_DBG_THREADS_PROFILING TRUE
@@ -422,7 +431,7 @@ /*===========================================================================*/
/**
- * @brief Threads descriptor structure hook.
+ * @brief Threads descriptor structure hook.
* @details User fields added to the end of the @p Thread structure.
*/
#if !defined(THREAD_EXT_FIELDS) || defined(__DOXYGEN__)
@@ -433,11 +442,11 @@ struct { \ #endif
/**
- * @brief Threads initialization hook.
+ * @brief Threads initialization hook.
* @details User initialization code added to the @p chThdInit() API.
*
- * @note It is invoked from within @p chThdInit() and implicitily from all
- * the threads creation APIs.
+ * @note It is invoked from within @p chThdInit() and implicitily from all
+ * the threads creation APIs.
*/
#if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)
#define THREAD_EXT_INIT(tp) { \
@@ -446,12 +455,12 @@ struct { \ #endif
/**
- * @brief Threads finalization hook.
+ * @brief Threads finalization hook.
* @details User finalization code added to the @p chThdExit() API.
*
- * @note It is inserted into lock zone.
- * @note It is also invoked when the threads simply return in order to
- * terminate.
+ * @note It is inserted into lock zone.
+ * @note It is also invoked when the threads simply return in order to
+ * terminate.
*/
#if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)
#define THREAD_EXT_EXIT(tp) { \
@@ -460,7 +469,7 @@ struct { \ #endif
/**
- * @brief Idle Loop hook.
+ * @brief Idle Loop hook.
* @details This hook is continuously invoked by the idle thread loop.
*/
#if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)
|