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

docs/ch.txt

@@ -445,8 +445,8 @@
  * @{
  * Non portable code.
  * @ingroup Kernel
- * @file templates/chcore.c Non portable code.
+ * @file src/templates/chcore.c Non portable code template file.
- * @file templates/chcore.h Non portable macros and structures.
+ * @file src/templates/chcore.h Non portable macros and structures template file.
  */
 /** @} */
 

ports/ARM7/chtypes.h

@@ -17,6 +17,11 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @addtogroup ARM7_CORE
+ * @{
+ */
+
 #ifndef _CHTYPES_H_
 #define _CHTYPES_H_
 
@@ -29,16 +34,16 @@
 #include <stdint.h>
 #endif
 
-typedef int32_t         bool_t;
+typedef int32_t         bool_t;         /**< Fast boolean type. */
-typedef uint8_t         tmode_t;
+typedef uint8_t         tmode_t;        /**< Thread flags. */
-typedef uint8_t         tstate_t;
+typedef uint8_t         tstate_t;       /**< Thread state. */
-typedef uint16_t        tid_t;
+typedef uint16_t        tid_t;          /**< Thread sequential Id. */
-typedef uint32_t        tprio_t;
+typedef uint32_t        tprio_t;        /**< Thread priority. */
-typedef int32_t         msg_t;
+typedef int32_t         msg_t;          /**< Inter-thread message. */
-typedef int32_t         eventid_t;
+typedef int32_t         eventid_t;      /**< Event Id. */
-typedef uint32_t        eventmask_t;
+typedef uint32_t        eventmask_t;    /**< Events mask. */
-typedef uint32_t        systime_t;
+typedef uint32_t        systime_t;      /**< System time. */
-typedef int32_t         cnt_t;
+typedef int32_t         cnt_t;          /**< Resources counter. */
 
 #define INLINE inline
 #define PACK_STRUCT_STRUCT __attribute__((packed))
@@ -46,3 +51,5 @@ typedef int32_t         cnt_t;
 #define PACK_STRUCT_END
 
 #endif /* _CHTYPES_H_ */
+
+/** @} */

ports/ARM7/port.dox

@@ -1,7 +1,10 @@
 /**
  * @defgroup ARM7 ARM7TDMI
  * @{
- * @section ARM7_NOTES The ARM7 port notes
+ * @details The ARM7 architecture is quite complex for a microcontroller and
+ * some explanations are required about the port choices.
+ *
+ * @section ARM7_NOTES The ARM7 modes
  * The ARM7 port supports three modes:
  * - Pure ARM mode, this is the preferred mode for code speed. The code size
  *   is larger however. This mode is enabled when all the modules are compiled
@@ -14,6 +17,42 @@
  *   usually the slowest mode and the code size is not as good as in pure
  *   THUMB mode.
  *
+ * @section ARM7_STATES Mapping of the System States in the ARM7 port
+ * The ChibiOS/RT logical @ref system_states are mapped as follow in the ARM7
+ * port:
+ * - <b>Initialization</b>. This state is represented by the startup code and
+ *   the initialization code before @p chSysInit() is executed. It has not a
+ *   special hardware state associated, usually the CPU goes through several
+ *   hardware states during the startup phase.
+ * - <b>Normal</b>. This is the state the system has after executing
+ *   @p chSysInit(). In this state the ARM7TDMI has both the interrupt sources
+ *   (IRQ and FIQ) enabled and is running in ARM System Mode.
+ * - <b>Suspended</b>. In this state the IRQ sources are disabled but the FIQ
+ *   sources are served, the core is running in ARM System Mode.
+ * - <b>Disabled</b>. Both the IRQ and FIQ sources are disabled, the core is
+ *   running in ARM System Mode.
+ * - <b>Sleep</b>. The ARM7 code does not have any built-in low power mode but
+ *   there are clock stop modes implemented in custom ways by the various
+ *   silicon vendors. This state is implemented in each microcontroller support
+ *   code in a different way, the core is running (or freezed...) in ARM
+ *   System Mode.
+ * - <b>S-Locked</b>. IRQ sources disabled, core running in ARM System Mode.
+ * - <b>I-Locked</b>. IRQ sources disabled, core running in ARM IRQ Mode. Note
+ *   that this state is not different from the SRI state in this port, the
+ *   @p chSysLockI() and @p chSysUnlockI() APIs do nothing (still use them in
+ *   order to formally change state because this may change).
+ * - <b>Serving Regular Interrupt</b>. IRQ sources disabled, core running in
+ *   ARM IRQ Mode. See also the I-Locked state.
+ * - <b>Serving Fast Interrupt</b>. IRQ and FIQ sources disabled, core running
+ *   in ARM FIQ Mode.
+ * - <b>Serving Non-Maskable Interrupt</b>. There are no asynchronous NMI
+ *   sources in ARM7 architecture but synchronous SVC, ABT and UND exception
+ *   handlers can be seen as belonging to this category.
+ * - <b>Halted</b>. Implemented as an infinite loop after disabling both IRQ
+ *   and FIQ sources. The ARM state is whatever the processor was running when
+ *   @p chSysHalt() was invoked.
+ * 
+ * @section ARM7_NOTES The ARM7 port notes
  * The ARM7 port makes some assumptions on the application code organization:
  * - The @p main() function is invoked in system mode.
  * - Each thread has a private user/system stack, the system has a single
@@ -41,8 +80,8 @@
  * naked).<br>
  * Function-trashed registers (R0-R3, R12, LR, SR) are saved/restored by the
  * system macros @p CH_IRQ_PROLOGUE() and @p CH_IRQ_EPILOGUE().<br>
- * The easiest way to ensure this is to just invoke a function from within
+ * The easiest way to ensure this is to just invoke a normal function from
- * the interrupt handler, the function code will save all the required
+ * within the interrupt handler, the function code will save all the required
  * registers.<br>
  * Example:
  * @code
@@ -87,3 +126,14 @@
  * @ingroup ARM7
  */
 /** @} */
+
+/**
+ * @defgroup ARM7_CORE ARM7 Core Implementation
+ * @{
+ * @brief ARM7 specific port code, structures and macros.
+ *
+ * @ingroup ARM7
+ * @file ports/ARM7/chcore.h Port related structures and macros.
+ * @file ports/ARM7/chtypes.h Port types.
+ */
+/** @} */

src/templates/chconf.h

@@ -35,9 +35,9 @@
  *  that this is not related to the compiler optimization options.*/
 #define CH_OPTIMIZE_SPEED
 
-/** Configuration option: If enabled then the used of nested @p chSysLock() /
+/** Configuration option: 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 leave
+ *  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.