From e72ad7fd5ff84ac96c646d93e140c47497cd1607 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 22 Mar 2010 12:53:09 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1770 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/ports/GCC/ARMCMx/port.dox | 170 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 os/ports/GCC/ARMCMx/port.dox (limited to 'os/ports/GCC/ARMCMx/port.dox') diff --git a/os/ports/GCC/ARMCMx/port.dox b/os/ports/GCC/ARMCMx/port.dox new file mode 100644 index 000000000..e0c1ce350 --- /dev/null +++ b/os/ports/GCC/ARMCMx/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 . +*/ + +/** + * @defgroup ARMCM3 ARM Cortex-M3 + * @details The ARM Cortex-M3 architecture is quite complex for a + * microcontroller and some explanations are required about the port choices. + * + * @section ARMCM3_STATES Mapping of the System States in the ARM Cortex-M3 port + * The ChibiOS/RT logical @ref system_states are mapped as follow in the ARM + * Cortex-M3 port: + * - Init. 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. + * - Normal. This is the state the system has after executing + * @p chSysInit(). In this state the ARM Cortex-M3 has the BASEPRI register + * set at @p BASEPRI_USER level, interrupts are not masked. The processor + * is running in thread-privileged mode. + * - Suspended. In this state the interrupt sources are not globally + * masked but the BASEPRI register is set to @p BASEPRI_KERNEL thus masking + * any interrupt source with lower or equal priority. The processor + * is running in thread-privileged mode. + * - Disabled. Interrupt sources are globally masked. The processor + * is running in thread-privileged mode. + * - Sleep. This state is entered with the execution of the specific + * instruction @p wfi. + * - S-Locked. In this state the interrupt sources are not globally + * masked but the BASEPRI register is set to @p BASEPRI_KERNEL thus masking + * any interrupt source with lower or equal priority. The processor + * is running in thread-privileged mode. + * - I-Locked. In this state the interrupt sources are not globally + * masked but the BASEPRI register is set to @p BASEPRI_KERNEL thus masking + * any interrupt source with lower or equal priority. The processor + * is running in exception-privileged mode. + * - Serving Regular Interrupt. 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. + * - Serving Fast Interrupt. 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. + * - Serving Non-Maskable Interrupt. The Cortex-M3 has a specific + * asynchronous NMI vector and several synchronous fault vectors that can + * be considered to be in this category. + * - Halted. 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 ARMCM3_NOTES The ARM Cortex-M3 port notes + * The ARM Cortex-M3 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 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.
+ * 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 ARMCM3_CONF Configuration Options + * @brief ARM Cortex-M3 Configuration Options. + * @details The ARMCM3 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.
+ * 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 BASEPRI_USER, this is the @p BASEPRI value for the user threads. The + * default value is @p 0 (disabled).
+ * Usually there is no need to change this value, please refer to the + * Cortex-M3 technical reference manual for a detailed description. + * - @p BASEPRI_KERNEL, this is the @p BASEPRI value for the kernel lock code. + * The default value is 0x40.
+ * Code running at higher priority levels must not invoke any OS API.
+ * Usually there is no need to change this value, please refer to the + * Cortex-M3 technical reference manual for a detailed description. + * - @p ENABLE_WFI_IDLE, if set to @p 1 enables the use of the @p wfi + * 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 ARMCM3 + */ + +/** + * @defgroup ARMCM3_CORE Core Port Implementation + * @brief ARM Cortex-M3 specific port code, structures and macros. + * + * @ingroup ARMCM3 + */ + +/** + * @defgroup ARMCM3_STARTUP Startup Support + * @brief ARM Cortex-M3 startup code support. + * @details ChibiOS/RT provides its own generic startup file for the ARM + * Cortex-M3 port. + * Of course it is not mandatory to use it but care should be taken about the + * startup phase details. + * + *

Startup Process

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

Expected linker symbols

+ * 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 ARMCM3 + * @file ARMCM3/crt0.s Startup code. + */ + +/** + * @defgroup ARMCM3_NVIC NVIC Support + * @brief ARM Cortex-M3 NVIC support. + * + * @ingroup ARMCM3 + */ -- cgit v1.2.3