git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1223 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 170 insertions, 83 deletions

diff --git a/demos/ARM7-LPC214x-GCC-minimal/chconf.h b/demos/ARM7-LPC214x-GCC-minimal/chconf.h
index 08663fea3..fd2e6f6ad 100644
--- a/demos/ARM7-LPC214x-GCC-minimal/chconf.h
+++ b/demos/ARM7-LPC214x-GCC-minimal/chconf.h
@@ -18,9 +18,9 @@
 */

 

 /**

- * @file src/templates/chconf.h

+ * @file templates/chconf.h

  * @brief Configuration file template.

- * @addtogroup Config

+ * @addtogroup config

  * @{

  */

 

@@ -32,29 +32,36 @@
 /*===========================================================================*/

 

 /**

- * Frequency of the system timer that drives the system ticks. This also

- * defines the system tick time unit.

+ * @brief System tick frequency.

+ * @details Frequency of the system timer that drives the system ticks. This

+ *          setting also defines the system tick time unit.

  */

 #if !defined(CH_FREQUENCY) || defined(__DOXYGEN__)

 #define CH_FREQUENCY                    1000

 #endif

 

 /**

- * This constant is the number of system ticks allowed for the threads before

- * preemption occurs. This option is only meaningful if the option

- * @p CH_USE_ROUNDROBIN is also active.

+ * @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.

+ *

+ * @note Disabling round robin makes the kernel more compact and generally

+ *       faster but forbids multiple threads at the same priority level.

  */

 #if !defined(CH_TIME_QUANTUM) || defined(__DOXYGEN__)

 #define CH_TIME_QUANTUM                 20

 #endif

 

 /**

- * If enabled then the use of nested @p chSysLock() / @p chSysUnlock()

- * operations is allowed.<br>

- * For performance and code size reasons the recommended setting is to leave

- * this option disabled.<br>

- * You can use this option if you need to merge ChibiOS/RT with external

- * libraries that require nested lock/unlock operations.

+ * @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

+ *          is to leave this option disabled.<br>

+ *          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.

  */

 #if !defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)

@@ -62,23 +69,18 @@
 #endif

 

 /**

- * If specified then the kernel performs the round robin scheduling algorithm

- * on threads of equal priority.

- * @note The default is @p TRUE.

- */

-#if !defined(CH_USE_ROUNDROBIN) || defined(__DOXYGEN__)

-#define CH_USE_ROUNDROBIN               FALSE

-#endif

-

-/**

- * Number of RAM bytes to use as system heap. If set to zero then the whole

- * available RAM is used as system heap.

- * @note In order to use the whole RAM as system heap the linker script must

+ * @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_HEAP.

+ * @note Requires @p CH_USE_COREMEM.

  */

-#if !defined(CH_HEAP_SIZE) || defined(__DOXYGEN__)

-#define CH_HEAP_SIZE                    0

+#if !defined(CH_MEMCORE_SIZE) || defined(__DOXYGEN__)

+#define CH_MEMCORE_SIZE                 0

 #endif

 

 /*===========================================================================*/

@@ -86,8 +88,10 @@
 /*===========================================================================*/

 

 /**

- * If specified then time efficient rather than space efficient code is used

- * when two possible implementations exist.

+ * @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.

  */

@@ -96,18 +100,20 @@
 #endif

 

 /**

- * If enabled defines a CPU register to be used as storage for the global

- * @p currp variable. Caching this variable in a register can greatly

- * improve both space and time efficiency of the generated code. Another side

- * effect is that one less register has to be saved during the context switch

- * resulting in lower RAM usage and faster code.

+ * @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.

+ *       documentation only.

  */

 #if defined(__DOXYGEN__)

 #define CH_CURRP_REGISTER_CACHE         "reg"

@@ -118,7 +124,10 @@
 /*===========================================================================*/

 

 /**

- * If specified then the @p chThdWait() function is included in the kernel.

+ * @brief Threads synchronization APIs.

+ * @details If enabled then the @p chThdWait() function is included in

+ *          the kernel.

+ *

  * @note The default is @p TRUE.

  */

 #if !defined(CH_USE_WAITEXIT) || defined(__DOXYGEN__)

@@ -126,7 +135,9 @@
 #endif

 

 /**

- * If specified then the Semaphores APIs are included in the kernel.

+ * @brief Semaphores APIs.

+ * @details If enabled then the Semaphores APIs are included in the kernel.

+ *

  * @note The default is @p TRUE.

  */

 #if !defined(CH_USE_SEMAPHORES) || defined(__DOXYGEN__)

@@ -134,8 +145,10 @@
 #endif

 

 /**

- * If enabled then the threads are enqueued on semaphores by priority rather

- * than FIFO order.

+ * @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.

  */

@@ -144,8 +157,10 @@
 #endif

 

 /**

- * If specified then the Semaphores the @p chSemWaitSignal() API is included

- * in the kernel.

+ * @brief Atomic semaphore API.

+ * @details If enabled then the semaphores the @p chSemWaitSignal() API

+ *          is included in the kernel.

+ *

  * @note The default is @p TRUE.

  * @note Requires @p CH_USE_SEMAPHORES.

  */

@@ -154,7 +169,9 @@
 #endif

 

 /**

- * If specified then the Mutexes APIs are included in the kernel.

+ * @brief Mutexes APIs.

+ * @details If enabled then the mutexes APIs are included in the kernel.

+ *

  * @note The default is @p TRUE.

  */

 #if !defined(CH_USE_MUTEXES) || defined(__DOXYGEN__)

@@ -162,7 +179,10 @@
 #endif

 

 /**

- * If specified then the Conditional Variables APIs are included in the kernel.

+ * @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.

  */

@@ -171,7 +191,10 @@
 #endif

 

 /**

- * If specified then the Conditional Variables APIs are included in the kernel.

+ * @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.

  */

@@ -180,7 +203,9 @@
 #endif

 

 /**

- * If specified then the Event flags APIs are included in the kernel.

+ * @brief Events Flags APIs.

+ * @details If enabled then the event flags APIs are included in the kernel.

+ *

  * @note The default is @p TRUE.

  */

 #if !defined(CH_USE_EVENTS) || defined(__DOXYGEN__)

@@ -188,8 +213,10 @@
 #endif

 

 /**

- * If specified then the @p chEvtWaitXXXTimeout() functions are included in

- * the kernel.

+ * @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.

  */

@@ -198,7 +225,10 @@
 #endif

 

 /**

- * If specified then the Synchronous Messages APIs are included in the kernel.

+ * @brief Synchronous Messages APIs.

+ * @details If enabled then the synchronous messages APIs are included

+ *          in the kernel.

+ *

  * @note The default is @p TRUE.

  */

 #if !defined(CH_USE_MESSAGES) || defined(__DOXYGEN__)

@@ -206,7 +236,10 @@
 #endif

 

 /**

- * If enabled then messages are served by priority rather than in FIFO order.

+ * @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.

  */

@@ -215,16 +248,21 @@
 #endif

 

 /**

- * If specified then the Asynchronous Messages (Mailboxes) APIs are included

- * in the kernel.

+ * @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.

  */

 #if !defined(CH_USE_MAILBOXES) || defined(__DOXYGEN__)

 #define CH_USE_MAILBOXES                FALSE

 #endif

 

 /**

- * If specified then the I/O queues APIs are included in the kernel.

+ * @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.

  */

@@ -233,9 +271,24 @@
 #endif

 

 /**

- * If specified then the memory heap allocator APIs are included in the kernel.

+ * @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.

+ */

+#if !defined(CH_USE_HEAP) || defined(__DOXYGEN__)

+#define CH_USE_MEMCORE                  FALSE

+#endif

+

+/**

+ * @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_MUTEXES or @p CH_USE_SEMAPHORES.

+ * @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__)

@@ -243,18 +296,24 @@
 #endif

 

 /**

- * If enabled enforces the use of the C-runtime @p malloc() and @p free()

- * functions as backend for the system heap 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.

  */

 #if !defined(CH_USE_MALLOC_HEAP) || defined(__DOXYGEN__)

 #define CH_USE_MALLOC_HEAP              FALSE

 #endif

 

 /**

- * If specified then the memory pools allocator APIs are included in the

- * kernel.

+ * @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.

  */

 #if !defined(CH_USE_MEMPOOLS) || defined(__DOXYGEN__)

@@ -262,8 +321,10 @@
 #endif

 

 /**

- * If specified then the dynamic threads creation APIs are included in the

- * kernel.

+ * @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.

  */

@@ -276,8 +337,10 @@
 /*===========================================================================*/

 

 /**

- * Debug option, if enabled then the checks on the API functions input

- * parameters are activated.

+ * @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.

  */

 #if !defined(CH_DBG_ENABLE_CHECKS) || defined(__DOXYGEN__)

@@ -285,9 +348,11 @@
 #endif

 

 /**

- * Debug option, 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.

+ * @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.

  */

 #if !defined(CH_DBG_ENABLE_ASSERTS) || defined(__DOXYGEN__)

@@ -295,8 +360,10 @@
 #endif

 

 /**

- * Debug option, if enabled the context switch circular trace buffer is

- * activated.

+ * @brief Debug option, trace buffer.

+ * @details If enabled then the context switch circular trace buffer is

+ *          activated.

+ *

  * @note The default is @p FALSE.

  */

 #if !defined(CH_DBG_ENABLE_TRACE) || defined(__DOXYGEN__)

@@ -304,25 +371,37 @@
 #endif

 

 /**

- * Debug option, if enabled a runtime stack check is performed.

+ * @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 at all.

+ *       may not be implemented or some ports.

  */

 #if !defined(CH_DBG_ENABLE_STACK_CHECK) || defined(__DOXYGEN__)

 #define CH_DBG_ENABLE_STACK_CHECK       FALSE

 #endif

 

 /**

- * Debug option, if enabled the threads working area is filled with a byte

- * pattern when a thread is created.
+ * @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.

  */

 #if !defined(CH_DBG_FILL_THREADS) || defined(__DOXYGEN__)

 #define CH_DBG_FILL_THREADS             FALSE

 #endif

 

 /**

- * Debug option, if enabled a field is added to the @p Thread structure that

- * counts the system ticks occurred while executing the thread.

+ * @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.

  */

 #if !defined(CH_DBG_THREADS_PROFILING) || defined(__DOXYGEN__)

 #define CH_DBG_THREADS_PROFILING        FALSE

@@ -333,38 +412,46 @@
 /*===========================================================================*/

 

 /**

- * User fields added to the end of the @p Thread structure.

+ * @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                                               \

 struct {                                                                \

-  /* Add thread custom fields here.*/                                   \

+  /* Add threads custom fields here.*/                                  \

 };

 #endif

 

 /**

- * User initialization code added to the @p chThdInit() API.

- * @note It is invoked from within @p chThdInit().

+ * @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.

  */

 #if !defined(THREAD_EXT_INIT) || defined(__DOXYGEN__)

 #define THREAD_EXT_INIT(tp) {                                           \

-  /* Add thread initialization code here.*/                             \

+  /* Add threads initialization code here.*/                            \

 }

 #endif

 

 /**

- * User finalization code added to the @p chThdExit() API.

+ * @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.

  */

 #if !defined(THREAD_EXT_EXIT) || defined(__DOXYGEN__)

 #define THREAD_EXT_EXIT(tp) {                                           \

-  /* Add thread finalization code here.*/                               \

+  /* Add threads finalization code here.*/                              \

 }

 #endif

 

 /**

- * Code inserted inside the idle thread loop immediately after an interrupt

- * resumed execution.
+ * @brief Idle Loop hook.

+ * @details This hook is continuously invoked by the idle thread loop.

  */

 #if !defined(IDLE_LOOP_HOOK) || defined(__DOXYGEN__)

 #define IDLE_LOOP_HOOK() {                                              \