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

1 files changed, 89 insertions, 0 deletions

diff --git a/ports/ARM7/port.dox b/ports/ARM7/port.dox
new file mode 100644
index 000000000..8b699febe
--- /dev/null
+++ b/ports/ARM7/port.dox
@@ -0,0 +1,89 @@
+/**

+ * @defgroup ARM7 ARM7TDMI

+ * @{

+ * @section ARM7_NOTES The ARM7 port notes

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

+ *   in ARM mode, see the Makefiles.

+ * - Pure THUMB mode, this is the preferred mode for code size. In this mode

+ *   the execution speed is slower than the ARM mode. This mode is enabled

+ *   when all the modules are compiled in THUMB mode, see the Makefiles.

+ * - Interworking mode, when in the system there are ARM modules mixed with

+ *   THUMB modules then the interworking compiler option is enabled. This is

+ *   usually the slowest mode and the code size is not as good as in pure

+ *   THUMB mode.

+ *

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

+ *   interrupt stack where all the interrupts are processed.

+ * - The threads are started in system mode.

+ * - The threads code can run in system mode or user mode, however the

+ *   code running in user mode cannot invoke the ChibiOS/RT APIs directly

+ *   because privileged instructions are used inside.<br>

+ *   The kernel APIs can be eventually invoked by using a SWI entry point

+ *   that handles the switch in system mode and the return in user mode.

+ * - Other modes are not preempt-able because the system code assumes the

+ *   threads running in system mode. When running in supervisor or other

+ *   modes make sure that the interrupts are globally disabled.

+ * - Interrupts nesting is not supported in the ARM7 code because their

+ *   implementation, even if possible, is not really efficient in this

+ *   architecture.

+ * - FIQ sources can preempt the kernel (by design) so it is not possible to

+ *   invoke the kernel APIs from inside a FIQ handler. FIQ handlers are not

+ *   affected by the kernel activity so there is not added jitter.

+ *

+ * @section ARM7_IH ARM7 Interrupt Handlers

+ * ARM7 Interrupt handlers do not save function-saved registers so you need to

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

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

+ * registers.<br>

+ * Example:

+ * @code

+ * CH_IRQ_HANDLER void irq_handler(void) {

+ *   CH_IRQ_PROLOGUE();

+ *

+ *   serve_interrupt();

+ *

+ *   VICVectAddr = 0; // This is LPC214x-specific.

+ *   CH_IRQ_EPILOGUE();

+ * }

+ * @endcode

+ * This is not a bug but an implementation choice, this solution allows to

+ * have interrupt handlers compiled in thumb mode without have to use an

+ * interworking mode (the mode switch is hidden in the macros), this

+ * greatly improves code efficiency and size. You can look at the serial

+ * driver for real examples of interrupt handlers.

+ *

+ * @ingroup Ports

+ */

+/** @} */

+

+/**

+ * @defgroup ARM7CONF Configuration Options

+ * @{

+ * @brief ARM7 specific configuration options.

+ * @details The ARM7 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 practice this value is the stack space used by the chSchDoReschedule()

+ *   stack frame.<br>

+ *   This value can be affected by a variety of external things like compiler

+ *   version, compiler options, kernel settings (speed/size) and so on.<br>

+ *   The default for this value is @p 0x10 which should be a safe value, you

+ *   can trim this down by defining the macro externally. This would save

+ *   some valuable RAM space for each thread present in the system.<br>

+ *   The default value is set into <b>./ports/ARM7/chcore.h</b>.

+ *

+ * @ingroup ARM7

+ */

+/** @} */