/* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, 2011,2012 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 ARMCMx ARM Cortex-Mx * @details ARM Cortex-Mx port for the GCC compiler. * * @section ARMCMx_INTRO Introduction * This port supports all the cores implementing the ARMv6-M and ARMv7-M * architectures. * * @section ARMCMx_MODES Kernel Modes * The Cortex-Mx port supports two distinct kernel modes: * - Advanced Kernel mode. In this mode the kernel only masks * interrupt sources with priorities below or equal to the * @p CORTEX_BASEPRI_KERNEL level. Higher priorities are not affected by * the kernel critical sections and can be used for fast interrupts. * This mode is not available in the ARMv6-M architecture which does not * support priority masking. * - Compact Kernel mode. In this mode the kernel handles IRQ priorities * in a simplified way, all interrupt sources are disabled when the kernel * enters into a critical zone and re-enabled on exit. This is simple and * adequate for most applications, this mode results in a more compact and * faster kernel. * . * The selection of the mode is performed using the port configuration option * @p CORTEX_SIMPLIFIED_PRIORITY. Apart from the different handling of * interrupts there are no other differences between the two modes. The * kernel API is exactly the same. * * @section ARMCMx_STATES_A System logical states in Compact Kernel mode * The ChibiOS/RT logical @ref system_states are mapped as follow in Compact * Kernel mode: * - 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 interrupts are enabled. The processor * is running in thread-privileged mode. * - Suspended. In this state the interrupt sources are globally * disabled. The processor is running in thread-privileged mode. In this * mode this state is not different from the Disabled state. * - Disabled. In this state the interrupt sources are globally * disabled. The processor is running in thread-privileged mode. In this * mode this state is not different from the Suspended state. * - Sleep. This state is entered with the execution of the specific * instruction @p wfi. * - S-Locked. In this state the interrupt sources are globally * disabled. The processor is running in thread-privileged mode. * - I-Locked. In this state the interrupt sources are globally * disabled. 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. Not implemented in compact kernel mode. * - Serving Non-Maskable Interrupt. The Cortex-Mx has a specific * asynchronous NMI vector and several synchronous fault vectors that can * be considered belonging to 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 ARMCMx_STATES_B System logical states in Advanced Kernel mode * The ChibiOS/RT logical @ref system_states are mapped as follow in the * Advanced Kernel mode: * - 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-Mx has the BASEPRI register * set at @p CORTEX_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 CORTEX_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 CORTEX_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 CORTEX_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. Fast interrupts are defined as interrupt * sources having higher priority level than the kernel * (@p CORTEX_BASEPRI_KERNEL). In this state is not possible to switch to * the I-Locked state because fast interrupts can preempt the kernel * critical zone.
* This state is not implemented in the ARMv6-M implementation because * priority masking is not present in this architecture. * - Serving Non-Maskable Interrupt. The Cortex-Mx has a specific * asynchronous NMI vector and several synchronous fault vectors that can * be considered belonging to 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 ARMCMx_NOTES ARM Cortex-Mx/GCC 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. * - The threads are started in thread-privileged mode. * - Interrupt nesting and the other advanced core/NVIC features are supported. * - The Cortex-Mx port is perfectly generic, support for more devices can be * easily added by adding a subdirectory under ./os/ports/GCC/ARMCMx * and giving it the name of the new device, then copy the files from another * device into the new directory and customize them for the new device. * . * @ingroup gcc */ /** * @defgroup ARMCMx_CONF Configuration Options * @details ARM Cortex-Mx Configuration Options. The ARMCMx port allows some * architecture-specific configurations settings that can be overridden * by redefining them in @p chconf.h. Usually there is no need to change * the default values. * - @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. * - @p IDLE_THREAD_STACK_SIZE, stack area size to be assigned to the IDLE * thread. Usually there is no need to change this value unless inserting * code in the IDLE thread using the @p IDLE_LOOP_HOOK hook macro. * - @p CORTEX_PRIORITY_SYSTICK, priority of the SYSTICK handler. * - @p CORTEX_PRIORITY_PENDSV, priority of the PENDSV handler. * - @p CORTEX_ENABLE_WFI_IDLE, if set to @p TRUE enables the use of the * @p wfi instruction from within the idle loop. This option is * defaulted to FALSE because it can create problems with some debuggers. * Setting this option to TRUE reduces the system power requirements. * . * @section ARMCMx_CONF_1 ARMv6-M specific options * The following options are specific for the ARMv6-M architecture: * - @p CORTEX_ALTERNATE_SWITCH, when activated makes the OS use the PendSV * exception instead of NMI as preemption handler. * . * @section ARMCMx_CONF_2 ARMv7-M specific options * The following options are specific for the ARMv6-M architecture: * - @p CORTEX_PRIORITY_SVCALL, priority of the SVCALL handler. * - @p CORTEX_SIMPLIFIED_PRIORITY, when enabled activates the Compact kernel * mode. * . * @ingroup ARMCMx */ /** * @defgroup ARMCMx_CORE Core Port Implementation * @details ARM Cortex-Mx specific port code, structures and macros. * * @ingroup ARMCMx */ /** * @defgroup ARMCMx_V6M_CORE ARMv6-M Specific Implementation * @details ARMv6-M specific port code, structures and macros. * * @ingroup ARMCMx_CORE */ /** * @defgroup ARMCMx_V7M_CORE ARMv7-M Specific Implementation * @details ARMv7-M specific port code, structures and macros. * * @ingroup ARMCMx_CORE */ /** * @defgroup ARMCMx_STARTUP Startup 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. * * @section ARMCMx_STARTUP_1 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 (also known as scatter file). * -# The CPU state is switched to Privileged and the PSP stack is used. * -# An early initialization routine @p __early_init() is invoked, if the * symbol is not defined then an empty default routine is executed * (weak symbol). * -# DATA and BSS segments are initialized. * -# Constructors are invoked. * -# The @p main() function is invoked with no parameters. * -# Destructors are invoked. * -# A branch is performed to the weak symbol @p _default_exit(). The * default code is an endless empty loop. * . * @section ARMCMx_STARTUP_2 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__, end of RAM. * - @p __main_stack_base__, main stack lower boundary. * - @p __main_stack_end__, main stack initial position. * - @p __process_stack_base__, process stack lower boundary. * - @p __process_stack_end__, process stack initial position. * - @p _textdata, address of the data segment source read only data. * - @p _data, start of the data segment. * - @p _edata, end of the data segment end location. * - @p _bss_start, start of the BSS. * - @p _bss_end, end of the BSS segment. * - @p __init_array_start, start of the constructors array. * - @p __init_array_end, end of the constructors array. * - @p __fini_array_start, start of the destructors array. * - @p __fini_array_end, end of the destructors array. * . * Additionally the kernel expects the following symbols: * - @p __main_thread_stack_base__, this symbol is required when the * stack checking is enabled (CH_DBG_ENABLE_STACK_CHECK==TRUE), * it is an alias of @p __process_stack_base__ in this port. * - @p __heap_base__ and @p __heap_end__, those symbols are required * if the memory core manager is enabled (CH_USE_MEMCORE==TRUE) * with a default core size set to zero (CH_MEMCORE_SIZE==0). * . * @ingroup ARMCMx */ /** * @defgroup ARMCMx_NVIC NVIC Support * @details ARM Cortex-Mx NVIC support. * * @ingroup ARMCMx */ /** * @defgroup ARMCMx_SPECIFIC Specific Implementations * @details Platform-specific port code. * * @ingroup ARMCMx */