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

4 files changed, 75 insertions, 18 deletions

diff --git a/docs/ch.txt b/docs/ch.txt
index bd17db657..82789c4b7 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -445,8 +445,8 @@
  * @{

  * Non portable code.

  * @ingroup Kernel

- * @file templates/chcore.c Non portable code.

- * @file templates/chcore.h Non portable macros and structures.

+ * @file src/templates/chcore.c Non portable code template file.

+ * @file src/templates/chcore.h Non portable macros and structures template file.

  */

 /** @} */

 

diff --git a/ports/ARM7/chtypes.h b/ports/ARM7/chtypes.h
index ab0dc36c8..387ce6413 100644
--- a/ports/ARM7/chtypes.h
+++ b/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 uint8_t         tmode_t;

-typedef uint8_t         tstate_t;

-typedef uint16_t        tid_t;

-typedef uint32_t        tprio_t;

-typedef int32_t         msg_t;

-typedef int32_t         eventid_t;

-typedef uint32_t        eventmask_t;

-typedef uint32_t        systime_t;

-typedef int32_t         cnt_t;

+typedef int32_t         bool_t;         /**< Fast boolean type. */

+typedef uint8_t         tmode_t;        /**< Thread flags. */

+typedef uint8_t         tstate_t;       /**< Thread state. */

+typedef uint16_t        tid_t;          /**< Thread sequential Id. */

+typedef uint32_t        tprio_t;        /**< Thread priority. */

+typedef int32_t         msg_t;          /**< Inter-thread message. */

+typedef int32_t         eventid_t;      /**< Event Id. */

+typedef uint32_t        eventmask_t;    /**< Events mask. */

+typedef uint32_t        systime_t;      /**< System time. */

+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_ */

+

+/** @} */

diff --git a/ports/ARM7/port.dox b/ports/ARM7/port.dox
index 8b699febe..cf3532f96 100644
--- a/ports/ARM7/port.dox
+++ b/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

@@ -39,10 +78,10 @@
  * make sure your code saves them or does not use them (this happens

  * because in the ARM7 port all the OS interrupt handler functions are declared

  * naked).<br>

- * Function-trashed registers (R0-R3,R12,LR,SR) are saved/restored by the

+ * 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 interrupt handler, the function code will save all the required

+ * The easiest way to ensure this is to just invoke a normal function from

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

+ */

+/** @} */

diff --git a/src/templates/chconf.h b/src/templates/chconf.h
index c97c00a86..f1b7f1b17 100644
--- a/src/templates/chconf.h
+++ b/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.