From c6b288f985bd8ea78fca5828a1bc4c7041e0b577 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 15 Dec 2010 21:02:07 +0000 Subject: [PATCH] Documentation related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2480 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/templates/chcore.h | 2 +- os/ports/GCC/ARM/chcore.h | 2 +- os/ports/GCC/ARMCMx/chcore_v6m.h | 2 +- os/ports/GCC/ARMCMx/chcore_v7m.h | 2 +- os/ports/GCC/AVR/chcore.h | 2 +- os/ports/GCC/MSP430/chcore.h | 2 +- os/ports/GCC/PPC/chcore.h | 2 +- os/ports/GCC/SIMIA32/chcore.h | 2 +- os/ports/IAR/ARMCMx/chcore.h | 111 +++++++++++++++++++++++-------- os/ports/IAR/ARMCMx/chcore_v6m.h | 48 +++++-------- os/ports/IAR/ARMCMx/chcore_v7m.h | 42 +++++------- os/ports/RC/STM8/chcore.h | 2 +- os/ports/cosmic/STM8/chcore.h | 2 +- 13 files changed, 127 insertions(+), 94 deletions(-) diff --git a/os/kernel/templates/chcore.h b/os/kernel/templates/chcore.h index e00677340..69c37b24d 100644 --- a/os/kernel/templates/chcore.h +++ b/os/kernel/templates/chcore.h @@ -76,7 +76,7 @@ struct context { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/ARM/chcore.h b/os/ports/GCC/ARM/chcore.h index 62edefac1..7e0e1e003 100644 --- a/os/ports/GCC/ARM/chcore.h +++ b/os/ports/GCC/ARM/chcore.h @@ -174,7 +174,7 @@ struct context { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/ARMCMx/chcore_v6m.h b/os/ports/GCC/ARMCMx/chcore_v6m.h index 5f45f581d..70447712c 100644 --- a/os/ports/GCC/ARMCMx/chcore_v6m.h +++ b/os/ports/GCC/ARMCMx/chcore_v6m.h @@ -72,7 +72,7 @@ struct intctx { #endif /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/ARMCMx/chcore_v7m.h b/os/ports/GCC/ARMCMx/chcore_v7m.h index 2c9dd0952..32b5a1361 100644 --- a/os/ports/GCC/ARMCMx/chcore_v7m.h +++ b/os/ports/GCC/ARMCMx/chcore_v7m.h @@ -60,7 +60,7 @@ struct intctx { #endif /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/AVR/chcore.h b/os/ports/GCC/AVR/chcore.h index a61b1a279..7f15ba50e 100644 --- a/os/ports/GCC/AVR/chcore.h +++ b/os/ports/GCC/AVR/chcore.h @@ -129,7 +129,7 @@ struct context { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/MSP430/chcore.h b/os/ports/GCC/MSP430/chcore.h index 4c8a56d65..35d9f71ef 100644 --- a/os/ports/GCC/MSP430/chcore.h +++ b/os/ports/GCC/MSP430/chcore.h @@ -104,7 +104,7 @@ struct context { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/PPC/chcore.h b/os/ports/GCC/PPC/chcore.h index b10b2ae62..6f45d5a82 100644 --- a/os/ports/GCC/PPC/chcore.h +++ b/os/ports/GCC/PPC/chcore.h @@ -167,7 +167,7 @@ struct context { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/GCC/SIMIA32/chcore.h b/os/ports/GCC/SIMIA32/chcore.h index bfb9c4cb5..87403d90e 100644 --- a/os/ports/GCC/SIMIA32/chcore.h +++ b/os/ports/GCC/SIMIA32/chcore.h @@ -84,7 +84,7 @@ struct context { #define APUSH(p, a) (p) -= sizeof(void *), *(void **)(p) = (void*)(a) /** - * Platform dependent part of the @p chThdInit() API. + * Platform dependent part of the @p chThdCreateI() API. * This code usually setup the context switching frame represented by a * @p intctx structure. */ diff --git a/os/ports/IAR/ARMCMx/chcore.h b/os/ports/IAR/ARMCMx/chcore.h index 2acba58a8..7644368be 100644 --- a/os/ports/IAR/ARMCMx/chcore.h +++ b/os/ports/IAR/ARMCMx/chcore.h @@ -36,10 +36,10 @@ /* Port constants. */ /*===========================================================================*/ -#define CORTEX_M0 0 /**< @brief Cortex-M0 variant. */ -#define CORTEX_M1 1 /**< @brief Cortex-M1 variant. */ -#define CORTEX_M3 3 /**< @brief Cortex-M3 variant. */ -#define CORTEX_M4 4 /**< @brief Cortex-M4 variant. */ +#define CORTEX_M0 0 /**< @brief Cortex-M0 variant. */ +#define CORTEX_M1 1 /**< @brief Cortex-M1 variant. */ +#define CORTEX_M3 3 /**< @brief Cortex-M3 variant. */ +#define CORTEX_M4 4 /**< @brief Cortex-M4 variant. */ /* Inclusion of the Cortex-Mx implementation specific parameters.*/ #include "cmparams.h" @@ -59,26 +59,26 @@ /** * @brief Total priority levels. */ -#define CORTEX_PRIORITY_LEVELS (1 << CORTEX_PRIORITY_BITS) +#define CORTEX_PRIORITY_LEVELS (1 << CORTEX_PRIORITY_BITS) /** * @brief Minimum priority level. * @details This minimum priority level is calculated from the number of * priority bits supported by the specific Cortex-Mx implementation. */ -#define CORTEX_MINIMUM_PRIORITY (CORTEX_PRIORITY_LEVELS - 1) +#define CORTEX_MINIMUM_PRIORITY (CORTEX_PRIORITY_LEVELS - 1) /** * @brief Maximum priority level. * @details The maximum allowed priority level is always zero. */ -#define CORTEX_MAXIMUM_PRIORITY 0 +#define CORTEX_MAXIMUM_PRIORITY 0 /** * @brief Disabled value for BASEPRI register. * @note ARMv7-M architecture only. */ -#define CORTEX_BASEPRI_DISABLED 0 +#define CORTEX_BASEPRI_DISABLED 0 /*===========================================================================*/ /* Port macros. */ @@ -93,7 +93,8 @@ /** * @brief Priority level to priority mask conversion macro. */ -#define CORTEX_PRIORITY_MASK(n) ((n) << (8 - CORTEX_PRIORITY_BITS)) +#define CORTEX_PRIORITY_MASK(n) \ + ((n) << (8 - CORTEX_PRIORITY_BITS)) /*===========================================================================*/ /* Port configurable parameters. */ @@ -103,7 +104,7 @@ * @brief Enables the use of the WFI instruction in the idle thread loop. */ #ifndef CORTEX_ENABLE_WFI_IDLE -#define CORTEX_ENABLE_WFI_IDLE FALSE +#define CORTEX_ENABLE_WFI_IDLE FALSE #endif /** @@ -112,7 +113,7 @@ * level in the middle of the numeric priorities range. */ #ifndef CORTEX_PRIORITY_SYSTICK -#define CORTEX_PRIORITY_SYSTICK (CORTEX_PRIORITY_LEVELS >> 1) +#define CORTEX_PRIORITY_SYSTICK (CORTEX_PRIORITY_LEVELS >> 1) #else /* If it is externally redefined then better perform a validity check on it.*/ #if !CORTEX_IS_VALID_PRIORITY(CORTEX_PRIORITY_SYSTICK) @@ -130,7 +131,7 @@ * to user in the ARMv6-M port. */ #ifndef CORTEX_PRIORITY_SVCALL -#define CORTEX_PRIORITY_SVCALL (CORTEX_MAXIMUM_PRIORITY + 1) +#define CORTEX_PRIORITY_SVCALL (CORTEX_MAXIMUM_PRIORITY + 1) #else /* If it is externally redefined then better perform a validity check on it.*/ #if !CORTEX_IS_VALID_PRIORITY(CORTEX_PRIORITY_SVCALL) @@ -148,7 +149,7 @@ * the minimum priority level. */ #ifndef CORTEX_PRIORITY_PENDSV -#define CORTEX_PRIORITY_PENDSV CORTEX_MINIMUM_PRIORITY +#define CORTEX_PRIORITY_PENDSV CORTEX_MINIMUM_PRIORITY #else /* If it is externally redefined then better perform a validity check on it.*/ #if !CORTEX_IS_VALID_PRIORITY(CORTEX_PRIORITY_PENDSV) @@ -163,7 +164,19 @@ * @note ARMv7-M architecture only. */ #ifndef CORTEX_BASEPRI_KERNEL -#define CORTEX_BASEPRI_KERNEL CORTEX_PRIORITY_MASK(CORTEX_PRIORITY_SVCALL+1) +#define CORTEX_BASEPRI_KERNEL \ + CORTEX_PRIORITY_MASK(CORTEX_PRIORITY_SVCALL+1) +#endif + +/** + * @brief Stack alignment enforcement. + * @note The default value is 64 in order to comply with EABI, reducing + * the value to 32 can save some RAM space if you don't care about + * binary compatibility with EABI compiled libraries. + * @note Allowed values are 32 or 64. + */ +#ifndef CORTEX_STACK_ALIGNMENT +#define CORTEX_STACK_ALIGNMENT 64 #endif /*===========================================================================*/ @@ -178,34 +191,53 @@ #if defined(__DOXYGEN__) /** * @brief Macro defining the specific ARM architecture. + * @note This macro is for documentation only, the real name changes + * depending on the selected architecture, the possible names are: + * - CH_ARCHITECTURE_ARM_v6M. + * - CH_ARCHITECTURE_ARM_v7M. + * . */ #define CH_ARCHITECTURE_ARM_vxm /** * @brief Name of the implemented architecture. + * @note The value is for documentation only, the real value changes + * depending on the selected architecture, the possible values are: + * - "ARMv6-M". + * - "ARMv7-M". + * - "ARMv7-ME". + * . */ -#define CH_ARCHITECTURE_NAME "ARMvx-M" +#define CH_ARCHITECTURE_NAME "ARMvx-M" /** * @brief Name of the architecture variant (optional). + * @note The value is for documentation only, the real value changes + * depending on the selected architecture, the possible values are: + * - "Cortex-M0" + * - "Cortex-M1" + * - "Cortex-M3" + * - "Cortex-M4" + * . */ -#define CH_CORE_VARIANT_NAME "Cortex-Mx" +#define CH_CORE_VARIANT_NAME "Cortex-Mx" + #elif CORTEX_MODEL == CORTEX_M4 #define CH_ARCHITECTURE_ARM_v7M -#define CH_ARCHITECTURE_NAME "ARMv7-ME" -#define CH_CORE_VARIANT_NAME "Cortex-M4" +#define CH_ARCHITECTURE_NAME "ARMv7-ME" +#define CH_CORE_VARIANT_NAME "Cortex-M4" #elif CORTEX_MODEL == CORTEX_M3 #define CH_ARCHITECTURE_ARM_v7M -#define CH_ARCHITECTURE_NAME "ARMv7-M" -#define CH_CORE_VARIANT_NAME "Cortex-M3" +#define CH_ARCHITECTURE_NAME "ARMv7-M" +#define CH_CORE_VARIANT_NAME "Cortex-M3" #elif CORTEX_MODEL == CORTEX_M1 #define CH_ARCHITECTURE_ARM_v6M -#define CH_ARCHITECTURE_NAME "ARMv6-M" -#define CH_CORE_VARIANT_NAME "Cortex-M1" +#define CH_ARCHITECTURE_NAME "ARMv6-M" +#define CH_CORE_VARIANT_NAME "Cortex-M1" #elif CORTEX_MODEL == CORTEX_M0 #define CH_ARCHITECTURE_ARM_v6M -#define CH_ARCHITECTURE_NAME "ARMv6-M" -#define CH_CORE_VARIANT_NAME "Cortex-M0" +#define CH_ARCHITECTURE_NAME "ARMv6-M" +#define CH_CORE_VARIANT_NAME "Cortex-M0" #endif /*===========================================================================*/ @@ -213,16 +245,42 @@ /*===========================================================================*/ /** - * @brief 32 bits stack and memory alignment enforcement. + * @brief Stack and memory alignment enforcement. */ +#if (CORTEX_STACK_ALIGNMENT == 64) || defined(__DOXYGEN__) +typedef uint64_t stkalign_t; +#elif CORTEX_STACK_ALIGNMENT == 32 typedef uint32_t stkalign_t; +#else +#error "invalid stack alignment selected" +#endif /** * @brief Generic ARM register. */ typedef void *regarm_t; -#if !defined(__DOXYGEN__) +#if defined(__DOXYGEN__) +/** + * @brief Interrupt saved context. + * @details This structure represents the stack frame saved during a + * preemption-capable interrupt handler. + * @note It is implemented to match the Cortex-Mx exception context. + */ +struct extctx { + /* Dummy definition, just for Doxygen.*/ +}; + +/** + * @brief System saved context. + * @details This structure represents the inner stack frame during a context + * switching. + */ +struct intctx { + /* Dummy definition, just for Doxygen.*/ +}; +#endif + /** * @brief Platform dependent part of the @p Thread structure. * @details In this port the structure just holds a pointer to the @p intctx @@ -231,7 +289,6 @@ typedef void *regarm_t; struct context { struct intctx *r13; }; -#endif /** * @brief Enforces a correct alignment for a stack area size value. diff --git a/os/ports/IAR/ARMCMx/chcore_v6m.h b/os/ports/IAR/ARMCMx/chcore_v6m.h index 92a667e3d..5f45f581d 100644 --- a/os/ports/IAR/ARMCMx/chcore_v6m.h +++ b/os/ports/IAR/ARMCMx/chcore_v6m.h @@ -47,11 +47,6 @@ struct cmxctx { }; #if !defined(__DOXYGEN__) -/** - * @brief Interrupt saved context. - * @details This structure represents the stack frame saved during a - * preemption-capable interrupt handler. - */ struct extctx { regarm_t xpsr; regarm_t r12; @@ -62,14 +57,7 @@ struct extctx { regarm_t r3; regarm_t pc; }; -#endif -#if !defined(__DOXYGEN__) -/** - * @brief System saved context. - * @details This structure represents the inner stack frame during a context - * switching. - */ struct intctx { regarm_t r8; regarm_t r9; @@ -92,9 +80,9 @@ struct intctx { tp->p_ctx.r13 = (struct intctx *)((uint8_t *)workspace + \ wsize - \ sizeof(struct intctx)); \ - tp->p_ctx.r13->r4 = (void *)pf; \ + tp->p_ctx.r13->r4 = pf; \ tp->p_ctx.r13->r5 = arg; \ - tp->p_ctx.r13->lr = (void *)_port_thread_start; \ + tp->p_ctx.r13->lr = _port_thread_start; \ } /** @@ -102,11 +90,12 @@ struct intctx { * @details This size depends on the idle thread implementation, usually * the idle thread should take no more space than those reserved * by @p INT_REQUIRED_STACK. - * @note In this port it is set to 4 because the idle thread does have - * a stack frame when compiling without optimizations. + * @note In this port it is set to 8 because the idle thread does have + * a stack frame when compiling without optimizations. You may + * reduce this value to zero when compiling with optimizations. */ #ifndef IDLE_THREAD_STACK_SIZE -#define IDLE_THREAD_STACK_SIZE 4 +#define IDLE_THREAD_STACK_SIZE 8 #endif /** @@ -116,11 +105,12 @@ struct intctx { * This value can be zero on those architecture where there is a * separate interrupt stack and the stack space between @p intctx and * @p extctx is known to be zero. - * @note This port requires some extra stack space for interrupt handling - * representing the frame of the function @p chSchDoRescheduleI(). + * @note In this port it is conservatively set to 16 because the function + * @p chSchDoRescheduleI() can have a stack frame, expecially with + * compiler optimizations disabled. */ #ifndef INT_REQUIRED_STACK -#define INT_REQUIRED_STACK 8 +#define INT_REQUIRED_STACK 16 #endif /** @@ -157,16 +147,14 @@ struct intctx { * @note @p id can be a function name or a vector number depending on the * port implementation. */ -#define PORT_IRQ_HANDLER(id) \ - void id(void) +#define PORT_IRQ_HANDLER(id) void id(void) /** * @brief Fast IRQ handler function declaration. * @note @p id can be a function name or a vector number depending on the * port implementation. */ -#define PORT_FAST_IRQ_HANDLER(id) \ - void id(void) +#define PORT_FAST_IRQ_HANDLER(id) void id(void) /** * @brief Port-related initialization code. @@ -183,14 +171,14 @@ struct intctx { * @details Usually this function just disables interrupts but may perform * more actions. */ -#define port_lock() asm volatile ("cpsid i") +#define port_lock() asm volatile ("cpsid i" : : : "memory") /** * @brief Kernel-unlock action. * @details Usually this function just disables interrupts but may perform * more actions. */ -#define port_unlock() asm volatile ("cpsie i") +#define port_unlock() asm volatile ("cpsie i" : : : "memory") /** * @brief Kernel-lock action from an interrupt handler. @@ -213,17 +201,17 @@ struct intctx { /** * @brief Disables all the interrupt sources. */ -#define port_disable() asm volatile ("cpsid i") +#define port_disable() asm volatile ("cpsid i" : : : "memory") /** * @brief Disables the interrupt sources below kernel-level priority. */ -#define port_suspend() asm volatile ("cpsid i") +#define port_suspend() asm volatile ("cpsid i" : : : "memory") /** * @brief Enables all the interrupt sources. */ -#define port_enable() asm volatile ("cpsie i") +#define port_enable() asm volatile ("cpsie i" : : : "memory") /** * @brief Enters an architecture-dependent IRQ-waiting mode. @@ -234,7 +222,7 @@ struct intctx { * @note Implemented as an inlined @p WFI instruction. */ #if CORTEX_ENABLE_WFI_IDLE || defined(__DOXYGEN__) -#define port_wait_for_interrupt() asm volatile ("wfi") +#define port_wait_for_interrupt() asm volatile ("wfi" : : : "memory") #else #define port_wait_for_interrupt() #endif diff --git a/os/ports/IAR/ARMCMx/chcore_v7m.h b/os/ports/IAR/ARMCMx/chcore_v7m.h index aa00a8afd..e43ebbd76 100644 --- a/os/ports/IAR/ARMCMx/chcore_v7m.h +++ b/os/ports/IAR/ARMCMx/chcore_v7m.h @@ -18,10 +18,10 @@ */ /** - * @file ARMCMx/chcore_v7m.h + * @file IAR/ARMCMx/chcore_v7m.h * @brief ARMv7-M architecture port macros and structures. * - * @addtogroup ARMCMx_V7M_CORE + * @addtogroup IAR_ARMCMx_V7M_CORE * @{ */ @@ -33,12 +33,6 @@ /*===========================================================================*/ #if !defined(__DOXYGEN__) -/** - * @brief Interrupt saved context. - * @details This structure represents the stack frame saved during a - * preemption-capable interrupt handler. - * @note It is implemented to match the Cortex-Mx exception context. - */ struct extctx { regarm_t r0; regarm_t r1; @@ -49,14 +43,7 @@ struct extctx { regarm_t pc; regarm_t xpsr; }; -#endif -#if !defined(__DOXYGEN__) -/** - * @brief System saved context. - * @details This structure represents the inner stack frame during a context - * switching. - */ struct intctx { regarm_t r4; regarm_t r5; @@ -81,9 +68,9 @@ struct intctx { tp->p_ctx.r13 = (struct intctx *)((uint8_t *)workspace + \ wsize - \ sizeof(struct intctx)); \ - tp->p_ctx.r13->r4 = (void *)pf; \ + tp->p_ctx.r13->r4 = pf; \ tp->p_ctx.r13->r5 = arg; \ - tp->p_ctx.r13->lr = (void *)_port_thread_start; \ + tp->p_ctx.r13->lr = _port_thread_start; \ } /** @@ -91,11 +78,12 @@ struct intctx { * @details This size depends on the idle thread implementation, usually * the idle thread should take no more space than those reserved * by @p INT_REQUIRED_STACK. - * @note In this port it is set to 4 because the idle thread does have - * a stack frame when compiling without optimizations. + * @note In this port it is set to 8 because the idle thread does have + * a stack frame when compiling without optimizations. You may + * reduce this value to zero when compiling with optimizations. */ #ifndef IDLE_THREAD_STACK_SIZE -#define IDLE_THREAD_STACK_SIZE 4 +#define IDLE_THREAD_STACK_SIZE 8 #endif /** @@ -105,10 +93,12 @@ struct intctx { * This value can be zero on those architecture where there is a * separate interrupt stack and the stack space between @p intctx and * @p extctx is known to be zero. - * @note This port requires no extra stack space for interrupt handling. + * @note In this port it is conservatively set to 16 because the function + * @p chSchDoRescheduleI() can have a stack frame, expecially with + * compiler optimizations disabled. */ #ifndef INT_REQUIRED_STACK -#define INT_REQUIRED_STACK 0 +#define INT_REQUIRED_STACK 16 #endif /** @@ -130,16 +120,14 @@ struct intctx { * @note @p id can be a function name or a vector number depending on the * port implementation. */ -#define PORT_IRQ_HANDLER(id) \ - void id(void) +#define PORT_IRQ_HANDLER(id) void id(void) /** * @brief Fast IRQ handler function declaration. * @note @p id can be a function name or a vector number depending on the * port implementation. */ -#define PORT_FAST_IRQ_HANDLER(id) \ - void id(void) +#define PORT_FAST_IRQ_HANDLER(id) void id(void) /** * @brief Port-related initialization code. @@ -222,7 +210,7 @@ struct intctx { * @note Implemented as an inlined @p WFI instruction. */ #if CORTEX_ENABLE_WFI_IDLE || defined(__DOXYGEN__) -#define port_wait_for_interrupt() +#define port_wait_for_interrupt() asm ("wfi") #else #define port_wait_for_interrupt() #endif diff --git a/os/ports/RC/STM8/chcore.h b/os/ports/RC/STM8/chcore.h index b550b20ac..55c5d3ac0 100644 --- a/os/ports/RC/STM8/chcore.h +++ b/os/ports/RC/STM8/chcore.h @@ -127,7 +127,7 @@ struct stm8_startctx { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */ diff --git a/os/ports/cosmic/STM8/chcore.h b/os/ports/cosmic/STM8/chcore.h index ebf13d0ac..f5fde8fb1 100644 --- a/os/ports/cosmic/STM8/chcore.h +++ b/os/ports/cosmic/STM8/chcore.h @@ -125,7 +125,7 @@ struct stm8_startctx { }; /** - * @brief Platform dependent part of the @p chThdInit() API. + * @brief Platform dependent part of the @p chThdCreateI() API. * @details This code usually setup the context switching frame represented * by an @p intctx structure. */