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

1 files changed, 170 insertions, 0 deletions

diff --git a/os/ports/GCC/ARMCM3/port.dox b/os/ports/GCC/ARMCM3/port.dox
new file mode 100644
index 000000000..6ec32f56f
--- /dev/null
+++ b/os/ports/GCC/ARMCM3/port.dox
@@ -0,0 +1,170 @@
+/*

+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.

+

+    This file is part of ChibiOS/RT.

+

+    ChibiOS/RT is free software; you can redistribute it and/or modify

+    it under the terms of the GNU General Public License as published by

+    the Free Software Foundation; either version 3 of the License, or

+    (at your option) any later version.

+

+    ChibiOS/RT is distributed in the hope that it will be useful,

+    but WITHOUT ANY WARRANTY; without even the implied warranty of

+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+    GNU General Public License for more details.

+

+    You should have received a copy of the GNU General Public License

+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

+*/

+

+/**

+ * @defgroup ARMCMx ARM Cortex-Mx

+ * @details This port supports the ARM Cortex-Mx architectures, specifically

+ *          the Cortex-M0 and the Cortex-M3.

+ *

+ * @section ARMCMx_STATES Mapping of the System States in the ARM Cortex-Mx port

+ * The ChibiOS/RT logical @ref system_states are mapped as follow in the ARM

+ * Cortex-Mx port:

+ * - <b>Init</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.

+ * - <b>Normal</b>. This is the state the system has after executing

+ *   @p chSysInit(). In this state the ARM Cortex-Mx has the BASEPRI register

+ *   set at @p CORTEX_BASEPRI_USER level, interrupts are not masked. The

+ *   processor is running in thread-privileged mode.

+ * - <b>Suspended</b>. In this state the interrupt sources are not globally

+ *   masked but the BASEPRI register is set to @p CORTEX_BASEPRI_KERNEL thus

+ *   masking any interrupt source with lower or equal priority. The processor

+ *   is running in thread-privileged mode.

+ * - <b>Disabled</b>. Interrupt sources are globally masked. The processor

+ *   is running in thread-privileged mode.

+ * - <b>Sleep</b>. This state is entered with the execution of the specific

+ *   instruction @p <b>wfi</b>.

+ * - <b>S-Locked</b>. In this state the interrupt sources are not globally

+ *   masked but the BASEPRI register is set to @p CORTEX_BASEPRI_KERNEL thus

+ *   masking any interrupt source with lower or equal priority. The processor

+ *   is running in thread-privileged mode.

+ * - <b>I-Locked</b>. In this state the interrupt sources are not globally

+ *   masked but the BASEPRI register is set to @p CORTEX_BASEPRI_KERNEL thus

+ *   masking any interrupt source with lower or equal priority. The processor

+ *   is running in exception-privileged mode.

+ * - <b>Serving Regular Interrupt</b>. In this state the interrupt sources are

+ *   not globally masked but only interrupts with higher priority can preempt

+ *   the current handler. The processor is running in exception-privileged mode.

+ * - <b>Serving Fast Interrupt</b>. It is basically the same of the SRI state

+ *   but it is not possible to switch to the I-Locked state because fast

+ *   interrupts can preempt the kernel critical zone.

+ * - <b>Serving Non-Maskable Interrupt</b>. The Cortex-Mx has a specific

+ *   asynchronous NMI vector and several synchronous fault vectors that can

+ *   be considered to be in this category.

+ * - <b>Halted</b>. Implemented as an infinite loop after globally masking all

+ *   the maskable interrupt sources. The ARM state is whatever the processor

+ *   was running when @p chSysHalt() was invoked.

+ * .

+ * @section ARMCMx_NOTES The ARM Cortex-Mx port notes

+ * The ARM Cortex-Mx port is organized as follow:

+ * - The @p main() function is invoked in thread-privileged mode.

+ * - Each thread has a private process stack, the system has a single main

+ *   stack where all the interrupts and exceptions are processed.

+ * - Only the 4 MSb of the priority level are used, the 4 LSb are assumed

+ *   to be zero.

+ * - The threads are started in thread-privileged mode with BASEPRI level

+ *   0x00 (disabled).

+ * - The kernel raises its BASEPRI level to @p CORTEX_BASEPRI_KERNEL in order

+ *   to protect the kernel data structures.

+ * - Interrupt nesting and the other advanced NVIC features are supported.

+ * - The SVC instruction and vector, with parameter #0,  is internally used

+ *   for commanded context switching.<br>

+ *   It is possible to share the SVC handler at the cost of slower context

+ *   switching.

+ * - The PendSV vector is internally used for preemption context switching.

+ * .

+ * @ingroup ports

+ */

+

+/**

+ * @defgroup ARMCMx_CONF Configuration Options

+ * @brief ARM Cortex-Mx Configuration Options.

+ * @details The ARMCMx port allows some architecture-specific configurations

+ * settings that can be specified externally, as example on the compiler

+ * command line:

+ * - @p INT_REQUIRED_STACK, this value represent the amount of stack space used

+ *   by an interrupt handler between the @p extctx and @p intctx

+ *   structures.<br>

+ *   In the current implementation this value is guaranteed to be zero so

+ *   there is no need to modify this value unless changes are done at the

+ *   interrupts handling code.

+ * - @p CORTEX_BASEPRI_USER, this is the @p BASEPRI value for the user threads.

+ *   The default value is @p 0 (disabled).<br>

+ *   Usually there is no need to change this value, please refer to the

+ *   Cortex-Mx technical reference manual for a detailed description.

+ * - @p CORTEX_BASEPRI_KERNEL, this is the @p BASEPRI value for the kernel lock

+ *   code.<br>

+ *   Code running at higher priority levels must not invoke any OS API.<br>

+ *   Usually there is no need to change this value, please refer to the

+ *   Cortex-Mx technical reference manual for a detailed description.

+ * - @p ENABLE_WFI_IDLE, if set to @p 1 enables the use of the @p <b>wfi</b>

+ *   instruction from within the idle loop. This is defaulted to 0 because

+ *   it can create problems with some debuggers. Setting this option to 1

+ *   reduces the system power requirements.

+ * .

+ * @ingroup ARMCMx

+ */

+

+/**

+ * @defgroup ARMCMx_CORE Core Port Implementation

+ * @brief ARM Cortex-Mx specific port code, structures and macros.

+ *

+ * @ingroup ARMCMx

+ */

+

+/**

+ * @defgroup ARMCMx_STARTUP Startup Support

+ * @brief ARM Cortex-Mx startup code support.

+ * @details ChibiOS/RT provides its own generic startup file for the ARM

+ * Cortex-Mx port.

+ * Of course it is not mandatory to use it but care should be taken about the

+ * startup phase details.

+ *

+ * <h2>Startup Process</h2>

+ * The startup process, as implemented, is the following:

+ * -# Interrupts are masked globally.

+ * -# The two stacks are initialized by assigning them the sizes defined in the

+ *    linker script (usually named @p ch.ld). Stack areas are allocated from

+ *    the highest RAM location downward.

+ * -# An early initialization routine @p hwinit0 is invoked, if the symbol is

+ *    not defined then an empty default routine is executed (weak symbol).

+ * -# DATA and BSS segments are initialized.

+ * -# The CPU state is switched to Privileged and the PSP stack is used.

+ * -# A late initialization routine @p hwinit1 is invoked, if the symbol not

+ *    defined then an empty default routine is executed (weak symbol).<br>

+ *    This late initialization function is also the proper place for a

+ *    @a bootloader, if your application requires one.

+ * -# The @p main() function is invoked with the parameters @p argc and @p argv

+ *    set to zero.

+ * -# Should the @p main() function return a branch is performed to the weak

+ *    symbol MainExitHandler. The default code is an endless empty loop.

+ * .

+ * <h2>Expected linker symbols</h2>

+ * The startup code starts at the symbol @p ResetHandler and expects the

+ * following symbols to be defined in the linker script:

+ * - @p __ram_end__ RAM end location +1.

+ * - @p __main_stack_size__ Exception stack size.

+ * - @p __process_stack_size__ Process stack size. This is the stack area used

+ *      by the @p main() function.

+ * - @p _textdata address of the data segment source read only data.

+ * - @p _data data segment start location.

+ * - @p _edata data segment end location +1.

+ * - @p _bss_start BSS start location.

+ * - @p _bss_end BSS end location +1.

+ * .

+ * @ingroup ARMCMx

+ * @file ARMCMx/crt0.s Startup code.

+ */

+

+/**

+ * @defgroup ARMCMx_NVIC NVIC Support

+ * @brief ARM Cortex-Mx NVIC support.

+ *

+ * @ingroup ARMCMx

+ */