Reformatted the kernel port template files.

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

4 files changed, 238 insertions, 196 deletions

diff --git a/os/kernel/templates/chconf.h b/os/kernel/templates/chconf.h
index 4cb12bd74..6f8233b7f 100644
--- a/os/kernel/templates/chconf.h
+++ b/os/kernel/templates/chconf.h
@@ -18,8 +18,11 @@
 */

 

 /**

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

  * @{

  */

@@ -32,7 +35,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 +44,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 +67,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 +93,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,220 +129,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 Requires @p CH_USE_HEAP and/or @p CH_USE_MEMPOOLS.

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

@@ -350,73 +353,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

@@ -427,7 +430,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__)

@@ -438,11 +441,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) {                                           \

@@ -451,12 +454,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) {                                           \

@@ -465,7 +468,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/templates/chcore.c b/os/kernel/templates/chcore.c
index f8495dddb..ba163569c 100644
--- a/os/kernel/templates/chcore.c
+++ b/os/kernel/templates/chcore.c
@@ -18,97 +18,96 @@
 */

 

 /**

- * @file templates/chcore.c

- * @brief Port related template code.

+ * @file    templates/chcore.c

+ * @brief   Port related template code.

+ * @details This file is a template of the system driver functions provided by

+ *          a port. Some of the following functions may be implemented as

+ *          macros in chcore.h if the implementer decides that there is an

+ *          advantage in doing so, as example because performance concerns.

+ *

  * @addtogroup core

  * @{

  */

 

 #include "ch.h"

 

-/*

- * This file is a template of the system driver functions provided by a port.

- * Some of the following functions may be implemented as macros in chcore.h if

- * the implementer decides that there is an advantage in doing so, as example

- * because performance concerns.

- */

-

 /**

- * @brief Port-related initialization code.

- *

- * @note This function is usually empty.
+ * @brief   Port-related initialization code.

+ * @note    This function is usually empty.
  */

 void port_init(void){

 }

 

 /**

- * @brief Kernel-lock action.

+ * @brief   Kernel-lock action.

  * @details Usually this function just disables interrupts but may perform more

- * actions.
+ *          actions.
  */

 void port_lock(void) {

 }

 

 /**

- * @brief Kernel-unlock action.

+ * @brief   Kernel-unlock action.

  * @details Usually this function just disables interrupts but may perform more

- * actions.

+ *          actions.

  */

 void port_unlock(void) {

 }

 

 /**

- * @brief Kernel-lock action from an interrupt handler.

+ * @brief   Kernel-lock action from an interrupt handler.

  * @details This function is invoked before invoking I-class APIs from

- * interrupt handlers. The implementation is architecture dependent, in its

- * simplest form it is void.

+ *          interrupt handlers. The implementation is architecture dependent,

+ *          in its simplest form it is void.

  */

 void port_lock_from_isr(void) {

 }

 

 /**

- * @brief Kernel-unlock action from an interrupt handler.

+ * @brief   Kernel-unlock action from an interrupt handler.

  * @details This function is invoked after invoking I-class APIs from interrupt

- * handlers. The implementation is architecture dependent, in its simplest form

- * it is void.

+ *          handlers. The implementation is architecture dependent, in its

+ *          simplest form it is void.

  */

 void port_unlock_from_isr(void) {

 }

 

 /**

- * @brief Disables all the interrupt sources.

- *

- * @note Of course non maskable interrupt sources are not included.
+ * @brief   Disables all the interrupt sources.

+ * @note    Of course non maskable interrupt sources are not included.
  */

 void port_disable() {

 }

 

 /**

- * @brief Disables the interrupt sources that are not supposed to preempt the kernel.
+ * @brief   Disables the interrupt sources that are not supposed to preempt

+ *          the kernel.
  */

 void port_suspend(void) {

 }

 

 /**

- * @brief Enables all the interrupt sources.
+ * @brief   Enables all the interrupt sources.
  */

 void port_enable(void) {

 }

 

 /**

- * @brief Enters an architecture-dependent halt mode.

+ * @brief   Enters an architecture-dependent halt mode.

  * @details The function is meant to return when an interrupt becomes pending.

- * The simplest implementation is an empty function but this will not take

- * advantage of architecture-specific power saving modes.
+ *          The simplest implementation is an empty function or macro but this

+ *          would not take advantage of architecture-specific power saving

+ *          modes.
  */

 void port_wait_for_interrupt(void) {

 }

 

 /**

- * @brief Halts the system.

+ * @brief   Halts the system.

  * @details This function is invoked by the operating system when an

- * unrecoverable error is detected (as example because a programming error in

- * the application code that triggers an assertion while in debug mode).
+ *          unrecoverable error is detected (as example because a programming

+ *          error in the application code that triggers an assertion while in

+ *          debug mode).
  */

 void port_halt(void) {

 

@@ -118,14 +117,14 @@ void port_halt(void) {
 }

 

 /**

- * @brief Performs a context switch between two threads.

+ * @brief   Performs a context switch between two threads.

  * @details This is the most critical code in any port, this function

- * is responsible for the context switch between 2 threads.

+ *          is responsible for the context switch between 2 threads.

+ * @note    The implementation of this code affects <b>directly</b> the context

+ *          switch performance so optimize here as much as you can.

  *

- * @param otp the thread to be switched out

- * @param ntp the thread to be switched in

- * @note The implementation of this code affects <b>directly</b> the context

- *       switch performance so optimize here as much as you can.

+ * @param otp   the thread to be switched out

+ * @param ntp   the thread to be switched in

  */

 void port_switch(Thread *otp, Thread *ntp) {

 }

diff --git a/os/kernel/templates/chcore.h b/os/kernel/templates/chcore.h
index 92595aee6..821296bc3 100644
--- a/os/kernel/templates/chcore.h
+++ b/os/kernel/templates/chcore.h
@@ -18,8 +18,11 @@
 */

 

 /**

- * @file templates/chcore.h

- * @brief Port related template macros and structures.

+ * @file    templates/chcore.h

+ * @brief   Port related template macros and structures.

+ * @details This file is a template of the system driver macros provided by

+ *          a port.

+ *

  * @addtogroup core

  * @{

  */

@@ -28,83 +31,84 @@
 #define _CHCORE_H_

 

 /**

- * Unique macro for the implemented architecture.

+ * @brief   Unique macro for the implemented architecture.

  */

 #define CH_ARCHITECTURE_XXX

 

 /**

- * Name of the implemented architecture.
+ * @brief   Name of the implemented architecture.

  */

 #define CH_ARCHITECTURE_NAME ""

 

 /**

- * Base type for stack alignment.
- * This type is used only for stack alignment reasons thus can be anything from

- * a char to a double.

+ * @brief   Base type for stack alignment.

+ * @details This type is used only for stack alignment reasons thus can be

+ *          anything from a char to a double.

  */

 typedef uint8_t stkalign_t;

 

 /**

- * @brief Interrupt saved context.

+ * @brief   Interrupt saved context.

  * @details This structure represents the stack frame saved during a

- * preemption-capable interrupt handler.

+ *          preemption-capable interrupt handler.

  */

 struct extctx {

 };

 

 /**

- * @brief System saved context.

+ * @brief   System saved context.

  * @details This structure represents the inner stack frame during a context

- * switching.

+ *          switching.

  */

 struct intctx {

 };

 

 /**

- * @brief Platform dependent part of the @p Thread structure.

+ * @brief   Platform dependent part of the @p Thread structure.

  * @details This structure usually contains just the saved stack pointer

- * defined as a pointer to a @p intctx structure.

+ *          defined as a pointer to a @p intctx structure.

  */

 struct context {

   struct intctx *sp;

 };

 

 /**

- * Platform dependent part of the @p chThdInit() API.

- * This code usually setup the context switching frame represented by a

- * @p intctx structure.

+ * @brief   Platform dependent part of the @p chThdInit() API.

+ * @details This code usually setup the context switching frame represented

+ *          by an @p intctx structure.

  */

 #define SETUP_CONTEXT(workspace, wsize, pf, arg) {                      \

 }

 

 /**

- * Stack size for the system idle thread.

- * This size depends on the idle thread implementation, usually the idle

- * thread should take no more space than those reserved

- * by @p INT_REQUIRED_STACK.

+ * @brief   Stack size for the system idle thread.

+ * @details This size depends on the idle thread implementation, usually

+ *          the idle thread should take no more space than those reserved

+ *          by @p INT_REQUIRED_STACK.

  */

 #ifndef IDLE_THREAD_STACK_SIZE

 #define IDLE_THREAD_STACK_SIZE 0

 #endif

 

 /**

- * Per-thread stack overhead for interrupts servicing, it is used in the

- * calculation of the correct working area size.

- * This value can be zero on those architecture where there is a separate

- * interrupt stack and the stack space between @p intctx and @p extctx is

- * known to be zero.

+ * @brief   Per-thread stack overhead for interrupts servicing.

+ * @details This constant is used in the calculation of the correct working

+ *          area size.

+ *          This value can be zero on those architecture where there is a

+ *          separate interrupt stack and the stack space between @p intctx and

+ *          @p extctx is known to be zero.

  */

 #ifndef INT_REQUIRED_STACK

 #define INT_REQUIRED_STACK 0

 #endif

 

 /**

- * Enforces a correct alignment for a stack area size value.

+ * @brief   Enforces a correct alignment for a stack area size value.

  */

 #define STACK_ALIGN(n) ((((n) - 1) | (sizeof(stkalign_t) - 1)) + 1)

 

 /**

- * Computes the thread working area global size.

+ * @brief   Computes the thread working area global size.

  */

 #define THD_WA_SIZE(n) STACK_ALIGN(sizeof(Thread) +                     \

                                    sizeof(struct intctx) +              \

@@ -112,27 +116,30 @@ struct context {
                                   (n) + (INT_REQUIRED_STACK))

 

 /**

- * Macro used to allocate a thread working area aligned as both position and

- * size.

+ * @brief   Static working area allocation.

+ * @details This macro is used to allocate a static thread working area

+ *          aligned as both position and size.

  */

 #define WORKING_AREA(s, n) stkalign_t s[THD_WA_SIZE(n) / sizeof(stkalign_t)];

 

 /**

- * IRQ prologue code, inserted at the start of all IRQ handlers enabled to

- * invoke system APIs.
+ * @brief   IRQ prologue code.

+ * @details This macro must be inserted at the start of all IRQ handlers

+ *          enabled to invoke system APIs.

  */

 #define PORT_IRQ_PROLOGUE()

 

 /**

- * IRQ epilogue code, inserted at the end of all IRQ handlers enabled to

- * invoke system APIs.

+ * @brief   IRQ epilogue code.

+ * @details This macro must be inserted at the end of all IRQ handlers

+ *          enabled to invoke system APIs.

  */

 #define PORT_IRQ_EPILOGUE()

 

 /**

- * IRQ handler function declaration.

- * @note @p id can be a function name or a vector number depending on the

- *       port implementation.
+ * @brief   IRQ handler function declaration.

+ * @note    @p id can be a function name or a vector number depending on the

+ *          port implementation.
  */

 #define PORT_IRQ_HANDLER(id) void id(void)

 

diff --git a/os/kernel/templates/chtypes.h b/os/kernel/templates/chtypes.h
index 362e1d291..f790d847c 100644
--- a/os/kernel/templates/chtypes.h
+++ b/os/kernel/templates/chtypes.h
@@ -18,8 +18,13 @@
 */

 

 /**

- * @file templates/chtypes.h

- * @brief System types template.

+ * @file    templates/chtypes.h

+ * @brief   System types template.

+ * @details The types defined in this file may change depending on the target

+ *          architecture. You may also try to optimize the size of the various

+ *          types in order to privilege size or performance, be careful in

+ *          doing so.

+ *

  * @addtogroup types

  * @{

  */

@@ -35,46 +40,74 @@
 #include <stdint.h>

 #endif

 

-/** Boolean, recommended the fastest signed. */

+/**

+ * @brief   Boolean, recommended the fastest signed.

+ */

 typedef int32_t         bool_t;

 

-/** Thread mode flags, uint8_t is ok. */

+/**

+ * @brief   Thread mode flags, uint8_t is ok.

+ */

 typedef uint8_t         tmode_t;

 

-/** Thread state, uint8_t is ok. */

+/**

+ * @brief   Thread state, uint8_t is ok.

+ */

 typedef uint8_t         tstate_t;

 

-/** Thread references counter, uint8_t is ok. */

+/**

+ * @brief   Thread references counter, uint8_t is ok.

+ */

 typedef uint8_t         trefs_t;

 

-/** Priority, use the fastest unsigned type. */

+/**

+ * @brief   Priority, use the fastest unsigned type.

+ */

 typedef uint32_t        tprio_t;

 

-/** Message, use signed pointer equivalent.*/

+/**

+ * @brief   Message, use signed pointer equivalent.

+ */

 typedef int32_t         msg_t;

 

-/** Event Id, use fastest signed.*/

+/**

+ * @brief   Event Id, use fastest signed.

+ */

 typedef int32_t         eventid_t;

 

-/** Event Mask, recommended fastest unsigned.*/

+/**

+ * @brief   Event Mask, recommended fastest unsigned.

+ */

 typedef uint32_t        eventmask_t;

 

-/** System Time, recommended fastest unsigned.*/

+/**

+ * @brief   System Time, recommended fastest unsigned.

+ */

 typedef uint32_t        systime_t;

 

-/** Counter, recommended fastest signed.*/

+/**

+ * @brief   Counter, recommended fastest signed.

+ */

 typedef int32_t         cnt_t;

 

-/** Inline function modifier. */

-#define INLINE      inline

+/**

+ * @brief   Inline function modifier.

+ */

+#define INLINE inline

 

-/** Packed structure modifier (within). */

+/**

+ * @brief   Packed structure modifier (within).

+ */

 #define PACK_STRUCT_STRUCT __attribute__((packed))

 

-/** Packed structure modifier (before). */

+/**

+ * @brief   Packed structure modifier (before).

+ */

 #define PACK_STRUCT_BEGIN

 

-/** Packed structure modifier (after). */

+/**

+ * @brief   Packed structure modifier (after).

+ */

 #define PACK_STRUCT_END

 

 #endif /* _CHTYPES_H_ */