From 1362b7a6d067d26e0409b226947f676016ee7135 Mon Sep 17 00:00:00 2001 From: Alex Ivanov Date: Tue, 8 Jan 2013 11:39:08 -0600 Subject: score: Doxygen Clean Up Task #4 --- cpukit/score/cpu/h8300/rtems/asm.h | 49 +- cpukit/score/cpu/h8300/rtems/score/cpu.h | 10 +- cpukit/score/cpu/h8300/rtems/score/h8300.h | 11 +- cpukit/score/cpu/h8300/rtems/score/types.h | 10 +- cpukit/score/cpu/lm32/rtems/asm.h | 58 +- cpukit/score/cpu/lm32/rtems/score/cpu.h | 1231 ++++++++++++------------ cpukit/score/cpu/lm32/rtems/score/cpu_asm.h | 12 +- cpukit/score/cpu/lm32/rtems/score/lm32.h | 15 +- cpukit/score/cpu/lm32/rtems/score/types.h | 10 +- cpukit/score/cpu/m32c/rtems/score/m32c.h | 16 +- cpukit/score/cpu/m32c/varvects.h | 70 +- cpukit/score/cpu/mips/rtems/asm.h | 21 +- cpukit/score/cpu/sparc/rtems/asm.h | 21 +- cpukit/score/cpu/sparc/rtems/score/cpu.h | 654 ++++++------- cpukit/score/cpu/sparc/rtems/score/sparc.h | 95 +- cpukit/score/cpu/sparc/rtems/score/types.h | 14 +- cpukit/score/cpu/sparc64/rtems/asm.h | 21 +- cpukit/score/cpu/sparc64/rtems/score/cpu.h | 64 +- cpukit/score/cpu/sparc64/rtems/score/sparc64.h | 49 +- cpukit/score/cpu/sparc64/rtems/score/types.h | 10 +- 20 files changed, 1256 insertions(+), 1185 deletions(-) diff --git a/cpukit/score/cpu/h8300/rtems/asm.h b/cpukit/score/cpu/h8300/rtems/asm.h index 0f4adee915..a9fad26252 100644 --- a/cpukit/score/cpu/h8300/rtems/asm.h +++ b/cpukit/score/cpu/h8300/rtems/asm.h @@ -1,17 +1,20 @@ /** - * @file rtems/asm.h + * @file * - * This include file attempts to address the problems - * caused by incompatible flavors of assemblers and - * toolsets. It primarily addresses variations in the - * use of leading underscores on symbols and the requirement - * that register names be preceded by a %. + * @brief Address the Problems Caused by Incompatible Flavor of + * Assemblers and Toolsets + * + * This include file attempts to address the problems + * caused by incompatible flavors of assemblers and + * toolsets. It primarily addresses variations in the + * use of leading underscores on symbols and the requirement + * that register names be preceded by a %. + * + * NOTE: The spacing in the use of these macros + * is critical to them working as advertised. */ /* - * NOTE: The spacing in the use of these macros - * is critical to them working as advertised. - * * COPYRIGHT: * * This file is based on similar code found in newlib available @@ -69,23 +72,23 @@ */ #define r0 REG(r0) #define r1 REG(r1) -#define r2 REG(r2) -#define r3 REG(r3) -#define r4 REG(r4) -#define r5 REG(r5) -#define r6 REG(r6) -#define r7 REG(r7) +#define r2 REG(r2) +#define r3 REG(r3) +#define r4 REG(r4) +#define r5 REG(r5) +#define r6 REG(r6) +#define r7 REG(r7) #define er0 REG(er0) #define er1 REG(er1) -#define er2 REG(er2) -#define er3 REG(er3) -#define er4 REG(er4) -#define er5 REG(er5) -#define er6 REG(er6) -#define er7 REG(er7) - -#define sp REG(sp) +#define er2 REG(er2) +#define er3 REG(er3) +#define er4 REG(er4) +#define er5 REG(er5) +#define er6 REG(er6) +#define er7 REG(er7) + +#define sp REG(sp) /* * Define macros to handle section beginning and ends. diff --git a/cpukit/score/cpu/h8300/rtems/score/cpu.h b/cpukit/score/cpu/h8300/rtems/score/cpu.h index f8f41a821e..6031f9689b 100644 --- a/cpukit/score/cpu/h8300/rtems/score/cpu.h +++ b/cpukit/score/cpu/h8300/rtems/score/cpu.h @@ -1,11 +1,13 @@ /** - * @file rtems/score/cpu.h + * @file + * + * @brief Hitachi H8300 CPU Department Source + * + * This include file contains information pertaining to the H8300 + * processor. */ /* - * This include file contains information pertaining to the H8300 - * processor. - * * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/h8300/rtems/score/h8300.h b/cpukit/score/cpu/h8300/rtems/score/h8300.h index dd7a3ec11b..3b5e87d626 100644 --- a/cpukit/score/cpu/h8300/rtems/score/h8300.h +++ b/cpukit/score/cpu/h8300/rtems/score/h8300.h @@ -1,11 +1,14 @@ /** - * @file rtems/score/h8300.h + * @file + * + * @brief Information Required to Build RTEMS for a Particular Member + * of the Hitachi H8/300 Family + * + * This file contains information pertaining to the Hitachi H8/300 + * processor family. */ /* - * This file contains information pertaining to the Hitachi H8/300 - * processor family. - * * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/h8300/rtems/score/types.h b/cpukit/score/cpu/h8300/rtems/score/types.h index fae136ab45..f832c186fe 100644 --- a/cpukit/score/cpu/h8300/rtems/score/types.h +++ b/cpukit/score/cpu/h8300/rtems/score/types.h @@ -1,11 +1,13 @@ /** - * @file rtems/score/types.h + * @file + * + * @brief Hitachi H8300 CPU Type Definitions + * + * This include file contains type definitions pertaining to the Hitachi + * h8300 processor family. */ /* - * This include file contains type definitions pertaining to the Hitachi - * h8300 processor family. - * * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/lm32/rtems/asm.h b/cpukit/score/cpu/lm32/rtems/asm.h index df16e4efdc..15046df81c 100644 --- a/cpukit/score/cpu/lm32/rtems/asm.h +++ b/cpukit/score/cpu/lm32/rtems/asm.h @@ -1,17 +1,20 @@ /** - * @file rtems/asm.h + * @file * - * This include file attempts to address the problems - * caused by incompatible flavors of assemblers and - * toolsets. It primarily addresses variations in the - * use of leading underscores on symbols and the requirement - * that register names be preceded by a %. + * @brief Address the Problems Caused by Incompatible Flavor of + * Assemblers and Toolsets + * + * This include file attempts to address the problems + * caused by incompatible flavors of assemblers and + * toolsets. It primarily addresses variations in the + * use of leading underscores on symbols and the requirement + * that register names be preceded by a %. + * + * NOTE: The spacing in the use of these macros + * is critical to them working as advertised. */ /* - * NOTE: The spacing in the use of these macros - * is critical to them working as advertised. - * * COPYRIGHT: * * This file is based on similar code found in newlib available @@ -38,24 +41,24 @@ #ifndef __USER_LABEL_PREFIX__ /** - * Recent versions of GNU cpp define variables which indicate the - * need for underscores and percents. If not using GNU cpp or - * the version does not support this, then you will obviously - * have to define these as appropriate. + * Recent versions of GNU cpp define variables which indicate the + * need for underscores and percents. If not using GNU cpp or + * the version does not support this, then you will obviously + * have to define these as appropriate. * - * This symbol is prefixed to all C program symbols. + * This symbol is prefixed to all C program symbols. */ #define __USER_LABEL_PREFIX__ _ #endif #ifndef __REGISTER_PREFIX__ /** - * Recent versions of GNU cpp define variables which indicate the - * need for underscores and percents. If not using GNU cpp or - * the version does not support this, then you will obviously - * have to define these as appropriate. + * Recent versions of GNU cpp define variables which indicate the + * need for underscores and percents. If not using GNU cpp or + * the version does not support this, then you will obviously + * have to define these as appropriate. * - * This symbol is prefixed to all register names. + * This symbol is prefixed to all register names. */ #define __REGISTER_PREFIX__ #endif @@ -95,8 +98,9 @@ #define BEGIN_DATA /** This macro is used to denote the end of a data section. */ #define END_DATA -/** This macro is used to denote the beginning of the - * unitialized data section. +/** + * This macro is used to denote the beginning of the + * unitialized data section. */ #define BEGIN_BSS /** This macro is used to denote the end of the unitialized data section. */ @@ -105,18 +109,18 @@ #define END /** - * This macro is used to declare a public global symbol. + * This macro is used to declare a public global symbol. * - * @note This must be tailored for a particular flavor of the C compiler. - * They may need to put underscores in front of the symbols. + * NOTE: This must be tailored for a particular flavor of the C compiler. + * They may need to put underscores in front of the symbols. */ #define PUBLIC(sym) .globl SYM (sym) /** - * This macro is used to prototype a public global symbol. + * This macro is used to prototype a public global symbol. * - * @note This must be tailored for a particular flavor of the C compiler. - * They may need to put underscores in front of the symbols. + * NOTE: This must be tailored for a particular flavor of the C compiler. + * They may need to put underscores in front of the symbols. */ #define EXTERN(sym) .globl SYM (sym) diff --git a/cpukit/score/cpu/lm32/rtems/score/cpu.h b/cpukit/score/cpu/lm32/rtems/score/cpu.h index 7f10a53820..865b19f523 100644 --- a/cpukit/score/cpu/lm32/rtems/score/cpu.h +++ b/cpukit/score/cpu/lm32/rtems/score/cpu.h @@ -1,10 +1,10 @@ /** - * @file rtems/score/cpu.h - */ - -/* - * This include file contains information pertaining to the LM32 - * processor. + * @file + * + * @brief LM32 CPU Department Source + * + * This include file contains information pertaining to the LM32 + * processor. */ /* @@ -29,363 +29,365 @@ extern "C" { /* conditional compilation parameters */ /** - * Should the calls to @ref _Thread_Enable_dispatch be inlined? + * Should the calls to @ref _Thread_Enable_dispatch be inlined? * - * If TRUE, then they are inlined. - * If FALSE, then a subroutine call is made. + * If TRUE, then they are inlined. + * If FALSE, then a subroutine call is made. * - * This conditional is an example of the classic trade-off of size - * versus speed. Inlining the call (TRUE) typically increases the - * size of RTEMS while speeding up the enabling of dispatching. + * This conditional is an example of the classic trade-off of size + * versus speed. Inlining the call (TRUE) typically increases the + * size of RTEMS while speeding up the enabling of dispatching. * - * @note In general, the @ref _Thread_Dispatch_disable_level will - * only be 0 or 1 unless you are in an interrupt handler and that - * interrupt handler invokes the executive.] When not inlined - * something calls @ref _Thread_Enable_dispatch which in turns calls - * @ref _Thread_Dispatch. If the enable dispatch is inlined, then - * one subroutine call is avoided entirely. + * NOTE: In general, the @ref _Thread_Dispatch_disable_level will + * only be 0 or 1 unless you are in an interrupt handler and that + * interrupt handler invokes the executive.] When not inlined + * something calls @ref _Thread_Enable_dispatch which in turns calls + * @ref _Thread_Dispatch. If the enable dispatch is inlined, then + * one subroutine call is avoided entirely. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_INLINE_ENABLE_DISPATCH FALSE /** - * Should the body of the search loops in _Thread_queue_Enqueue_priority - * be unrolled one time? In unrolled each iteration of the loop examines - * two "nodes" on the chain being searched. Otherwise, only one node - * is examined per iteration. + * Should the body of the search loops in _Thread_queue_Enqueue_priority + * be unrolled one time? In unrolled each iteration of the loop examines + * two "nodes" on the chain being searched. Otherwise, only one node + * is examined per iteration. * - * If TRUE, then the loops are unrolled. - * If FALSE, then the loops are not unrolled. + * If TRUE, then the loops are unrolled. + * If FALSE, then the loops are not unrolled. * - * The primary factor in making this decision is the cost of disabling - * and enabling interrupts (_ISR_Flash) versus the cost of rest of the - * body of the loop. On some CPUs, the flash is more expensive than - * one iteration of the loop body. In this case, it might be desirable - * to unroll the loop. It is important to note that on some CPUs, this - * code is the longest interrupt disable period in RTEMS. So it is - * necessary to strike a balance when setting this parameter. + * The primary factor in making this decision is the cost of disabling + * and enabling interrupts (_ISR_Flash) versus the cost of rest of the + * body of the loop. On some CPUs, the flash is more expensive than + * one iteration of the loop body. In this case, it might be desirable + * to unroll the loop. It is important to note that on some CPUs, this + * code is the longest interrupt disable period in RTEMS. So it is + * necessary to strike a balance when setting this parameter. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_UNROLL_ENQUEUE_PRIORITY TRUE /** - * Does RTEMS manage a dedicated interrupt stack in software? + * Does RTEMS manage a dedicated interrupt stack in software? * - * If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization. - * If FALSE, nothing is done. + * If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization. + * If FALSE, nothing is done. * - * If the CPU supports a dedicated interrupt stack in hardware, - * then it is generally the responsibility of the BSP to allocate it - * and set it up. + * If the CPU supports a dedicated interrupt stack in hardware, + * then it is generally the responsibility of the BSP to allocate it + * and set it up. * - * If the CPU does not support a dedicated interrupt stack, then - * the porter has two options: (1) execute interrupts on the - * stack of the interrupted task, and (2) have RTEMS manage a dedicated - * interrupt stack. + * If the CPU does not support a dedicated interrupt stack, then + * the porter has two options: (1) execute interrupts on the + * stack of the interrupted task, and (2) have RTEMS manage a dedicated + * interrupt stack. * - * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE. + * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE. * - * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and - * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is - * possible that both are FALSE for a particular CPU. Although it - * is unclear what that would imply about the interrupt processing - * procedure on that CPU. + * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and + * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is + * possible that both are FALSE for a particular CPU. Although it + * is unclear what that would imply about the interrupt processing + * procedure on that CPU. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_HAS_SOFTWARE_INTERRUPT_STACK TRUE /** - * Does the CPU follow the simple vectored interrupt model? + * Does the CPU follow the simple vectored interrupt model? * - * If TRUE, then RTEMS allocates the vector table it internally manages. - * If FALSE, then the BSP is assumed to allocate and manage the vector - * table + * If TRUE, then RTEMS allocates the vector table it internally manages. + * If FALSE, then the BSP is assumed to allocate and manage the vector + * table * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_SIMPLE_VECTORED_INTERRUPTS TRUE /** - * Does this CPU have hardware support for a dedicated interrupt stack? + * Does this CPU have hardware support for a dedicated interrupt stack? * - * If TRUE, then it must be installed during initialization. - * If FALSE, then no installation is performed. + * If TRUE, then it must be installed during initialization. + * If FALSE, then no installation is performed. * - * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE. + * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE. * - * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and - * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is - * possible that both are FALSE for a particular CPU. Although it - * is unclear what that would imply about the interrupt processing - * procedure on that CPU. + * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and + * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is + * possible that both are FALSE for a particular CPU. Although it + * is unclear what that would imply about the interrupt processing + * procedure on that CPU. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_HAS_HARDWARE_INTERRUPT_STACK FALSE /** - * Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager? + * Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager? * - * If TRUE, then the memory is allocated during initialization. - * If FALSE, then the memory is allocated during initialization. + * If TRUE, then the memory is allocated during initialization. + * If FALSE, then the memory is allocated during initialization. * - * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE. + * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_ALLOCATE_INTERRUPT_STACK TRUE /** - * Does the RTEMS invoke the user's ISR with the vector number and - * a pointer to the saved interrupt frame (1) or just the vector - * number (0)? + * Does the RTEMS invoke the user's ISR with the vector number and + * a pointer to the saved interrupt frame (1) or just the vector + * number (0)? * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_ISR_PASSES_FRAME_POINTER 1 /** - * @def CPU_HARDWARE_FP + * @def CPU_HARDWARE_FP * - * Does the CPU have hardware floating point? + * Does the CPU have hardware floating point? * - * If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported. - * If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored. + * If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported. + * If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored. * - * If there is a FP coprocessor such as the i387 or mc68881, then - * the answer is TRUE. + * If there is a FP coprocessor such as the i387 or mc68881, then + * the answer is TRUE. * - * The macro name "NO_CPU_HAS_FPU" should be made CPU specific. - * It indicates whether or not this CPU model has FP support. For - * example, it would be possible to have an i386_nofp CPU model - * which set this to false to indicate that you have an i386 without - * an i387 and wish to leave floating point support out of RTEMS. + * The macro name "NO_CPU_HAS_FPU" should be made CPU specific. + * It indicates whether or not this CPU model has FP support. For + * example, it would be possible to have an i386_nofp CPU model + * which set this to false to indicate that you have an i386 without + * an i387 and wish to leave floating point support out of RTEMS. */ /** - * @def CPU_SOFTWARE_FP + * @def CPU_SOFTWARE_FP * - * Does the CPU have no hardware floating point and GCC provides a - * software floating point implementation which must be context - * switched? + * Does the CPU have no hardware floating point and GCC provides a + * software floating point implementation which must be context + * switched? * - * This feature conditional is used to indicate whether or not there - * is software implemented floating point that must be context - * switched. The determination of whether or not this applies - * is very tool specific and the state saved/restored is also - * compiler specific. + * This feature conditional is used to indicate whether or not there + * is software implemented floating point that must be context + * switched. The determination of whether or not this applies + * is very tool specific and the state saved/restored is also + * compiler specific. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_HARDWARE_FP FALSE #define CPU_SOFTWARE_FP FALSE /** - * Are all tasks RTEMS_FLOATING_POINT tasks implicitly? + * Are all tasks RTEMS_FLOATING_POINT tasks implicitly? * - * If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed. - * If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed. + * If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed. + * If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed. * - * So far, the only CPUs in which this option has been used are the - * HP PA-RISC and PowerPC. On the PA-RISC, The HP C compiler and - * gcc both implicitly used the floating point registers to perform - * integer multiplies. Similarly, the PowerPC port of gcc has been - * seen to allocate floating point local variables and touch the FPU - * even when the flow through a subroutine (like vfprintf()) might - * not use floating point formats. + * So far, the only CPUs in which this option has been used are the + * HP PA-RISC and PowerPC. On the PA-RISC, The HP C compiler and + * gcc both implicitly used the floating point registers to perform + * integer multiplies. Similarly, the PowerPC port of gcc has been + * seen to allocate floating point local variables and touch the FPU + * even when the flow through a subroutine (like vfprintf()) might + * not use floating point formats. * - * If a function which you would not think utilize the FP unit DOES, - * then one can not easily predict which tasks will use the FP hardware. - * In this case, this option should be TRUE. + * If a function which you would not think utilize the FP unit DOES, + * then one can not easily predict which tasks will use the FP hardware. + * In this case, this option should be TRUE. * - * If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well. + * If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_ALL_TASKS_ARE_FP FALSE /** - * Should the IDLE task have a floating point context? + * Should the IDLE task have a floating point context? * - * If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task - * and it has a floating point context which is switched in and out. - * If FALSE, then the IDLE task does not have a floating point context. + * If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task + * and it has a floating point context which is switched in and out. + * If FALSE, then the IDLE task does not have a floating point context. * - * Setting this to TRUE negatively impacts the time required to preempt - * the IDLE task from an interrupt because the floating point context - * must be saved as part of the preemption. + * Setting this to TRUE negatively impacts the time required to preempt + * the IDLE task from an interrupt because the floating point context + * must be saved as part of the preemption. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_IDLE_TASK_IS_FP FALSE /** - * Should the saving of the floating point registers be deferred - * until a context switch is made to another different floating point - * task? + * Should the saving of the floating point registers be deferred + * until a context switch is made to another different floating point + * task? * - * If TRUE, then the floating point context will not be stored until - * necessary. It will remain in the floating point registers and not - * disturned until another floating point task is switched to. + * If TRUE, then the floating point context will not be stored until + * necessary. It will remain in the floating point registers and not + * disturned until another floating point task is switched to. * - * If FALSE, then the floating point context is saved when a floating - * point task is switched out and restored when the next floating point - * task is restored. The state of the floating point registers between - * those two operations is not specified. + * If FALSE, then the floating point context is saved when a floating + * point task is switched out and restored when the next floating point + * task is restored. The state of the floating point registers between + * those two operations is not specified. * - * If the floating point context does NOT have to be saved as part of - * interrupt dispatching, then it should be safe to set this to TRUE. + * If the floating point context does NOT have to be saved as part of + * interrupt dispatching, then it should be safe to set this to TRUE. * - * Setting this flag to TRUE results in using a different algorithm - * for deciding when to save and restore the floating point context. - * The deferred FP switch algorithm minimizes the number of times - * the FP context is saved and restored. The FP context is not saved - * until a context switch is made to another, different FP task. - * Thus in a system with only one FP task, the FP context will never - * be saved or restored. + * Setting this flag to TRUE results in using a different algorithm + * for deciding when to save and restore the floating point context. + * The deferred FP switch algorithm minimizes the number of times + * the FP context is saved and restored. The FP context is not saved + * until a context switch is made to another, different FP task. + * Thus in a system with only one FP task, the FP context will never + * be saved or restored. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_USE_DEFERRED_FP_SWITCH TRUE /** - * Does this port provide a CPU dependent IDLE task implementation? + * Does this port provide a CPU dependent IDLE task implementation? * - * If TRUE, then the routine @ref _CPU_Thread_Idle_body - * must be provided and is the default IDLE thread body instead of - * @ref _CPU_Thread_Idle_body. + * If TRUE, then the routine @ref _CPU_Thread_Idle_body + * must be provided and is the default IDLE thread body instead of + * @ref _CPU_Thread_Idle_body. * - * If FALSE, then use the generic IDLE thread body if the BSP does - * not provide one. + * If FALSE, then use the generic IDLE thread body if the BSP does + * not provide one. * - * This is intended to allow for supporting processors which have - * a low power or idle mode. When the IDLE thread is executed, then - * the CPU can be powered down. + * This is intended to allow for supporting processors which have + * a low power or idle mode. When the IDLE thread is executed, then + * the CPU can be powered down. * - * The order of precedence for selecting the IDLE thread body is: + * The order of precedence for selecting the IDLE thread body is: * - * -# BSP provided - * -# CPU dependent (if provided) - * -# generic (if no BSP and no CPU dependent) + * -# BSP provided + * -# CPU dependent (if provided) + * -# generic (if no BSP and no CPU dependent) * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_PROVIDES_IDLE_THREAD_BODY TRUE /** - * Does the stack grow up (toward higher addresses) or down - * (toward lower addresses)? + * Does the stack grow up (toward higher addresses) or down + * (toward lower addresses)? * - * If TRUE, then the grows upward. - * If FALSE, then the grows toward smaller addresses. + * If TRUE, then the grows upward. + * If FALSE, then the grows toward smaller addresses. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_STACK_GROWS_UP FALSE /** - * The following is the variable attribute used to force alignment - * of critical RTEMS structures. On some processors it may make - * sense to have these aligned on tighter boundaries than - * the minimum requirements of the compiler in order to have as - * much of the critical data area as possible in a cache line. + * The following is the variable attribute used to force alignment + * of critical RTEMS structures. On some processors it may make + * sense to have these aligned on tighter boundaries than + * the minimum requirements of the compiler in order to have as + * much of the critical data area as possible in a cache line. * - * The placement of this macro in the declaration of the variables - * is based on the syntactically requirements of the GNU C - * "__attribute__" extension. For example with GNU C, use - * the following to force a structures to a 32 byte boundary. + * The placement of this macro in the declaration of the variables + * is based on the syntactically requirements of the GNU C + * "__attribute__" extension. For example with GNU C, use + * the following to force a structures to a 32 byte boundary. * - * __attribute__ ((aligned (32))) + * __attribute__ ((aligned (32))) * - * @note Currently only the Priority Bit Map table uses this feature. - * To benefit from using this, the data must be heavily - * used so it will stay in the cache and used frequently enough - * in the executive to justify turning this on. + * NOTE: Currently only the Priority Bit Map table uses this feature. + * To benefit from using this, the data must be heavily + * used so it will stay in the cache and used frequently enough + * in the executive to justify turning this on. * - * Port Specific Information: + * Port Specific Information: * - * L2 cache lines are 32 bytes in Milkymist SoC + * L2 cache lines are 32 bytes in Milkymist SoC */ #define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32))) #define CPU_TIMESTAMP_USE_INT64_INLINE TRUE /** - * @defgroup CPUEndian Processor Dependent Endianness Support + * @defgroup CPUEndian Processor Dependent Endianness Support * - * This group assists in issues related to processor endianness. + * This group assists in issues related to processor endianness. + * + * @{ */ /** - * @ingroup CPUEndian - * Define what is required to specify how the network to host conversion - * routines are handled. + * Define what is required to specify how the network to host conversion + * routines are handled. * - * @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the - * same values. + * NOTE: @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the + * same values. * - * @see CPU_LITTLE_ENDIAN + * @see CPU_LITTLE_ENDIAN * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_BIG_ENDIAN TRUE /** - * @ingroup CPUEndian - * Define what is required to specify how the network to host conversion - * routines are handled. + * Define what is required to specify how the network to host conversion + * routines are handled. * - * @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the - * same values. + * NOTE: @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the + * same values. * - * @see CPU_BIG_ENDIAN + * @see CPU_BIG_ENDIAN * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_LITTLE_ENDIAN FALSE +/** @} */ + /** - * @ingroup CPUInterrupt - * The following defines the number of bits actually used in the - * interrupt field of the task mode. How those bits map to the - * CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level. + * @ingroup CPUInterrupt + * The following defines the number of bits actually used in the + * interrupt field of the task mode. How those bits map to the + * CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_MODES_INTERRUPT_MASK 0x00000001 @@ -402,50 +404,51 @@ extern "C" { /** * @defgroup CPUContext Processor Dependent Context Management * - * From the highest level viewpoint, there are 2 types of context to save. + * From the highest level viewpoint, there are 2 types of context to save. * - * -# Interrupt registers to save - * -# Task level registers to save + * -# Interrupt registers to save + * -# Task level registers to save * - * Since RTEMS handles integer and floating point contexts separately, this - * means we have the following 3 context items: + * Since RTEMS handles integer and floating point contexts separately, this + * means we have the following 3 context items: * - * -# task level context stuff:: Context_Control - * -# floating point task stuff:: Context_Control_fp - * -# special interrupt level context :: CPU_Interrupt_frame + * -# task level context stuff:: Context_Control + * -# floating point task stuff:: Context_Control_fp + * -# special interrupt level context :: CPU_Interrupt_frame * - * On some processors, it is cost-effective to save only the callee - * preserved registers during a task context switch. This means - * that the ISR code needs to save those registers which do not - * persist across function calls. It is not mandatory to make this - * distinctions between the caller/callee saves registers for the - * purpose of minimizing context saved during task switch and on interrupts. - * If the cost of saving extra registers is minimal, simplicity is the - * choice. Save the same context on interrupt entry as for tasks in - * this case. + * On some processors, it is cost-effective to save only the callee + * preserved registers during a task context switch. This means + * that the ISR code needs to save those registers which do not + * persist across function calls. It is not mandatory to make this + * distinctions between the caller/callee saves registers for the + * purpose of minimizing context saved during task switch and on interrupts. + * If the cost of saving extra registers is minimal, simplicity is the + * choice. Save the same context on interrupt entry as for tasks in + * this case. * - * Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then - * care should be used in designing the context area. + * Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then + * care should be used in designing the context area. * - * On some CPUs with hardware floating point support, the Context_Control_fp - * structure will not be used or it simply consist of an array of a - * fixed number of bytes. This is done when the floating point context - * is dumped by a "FP save context" type instruction and the format - * is not really defined by the CPU. In this case, there is no need - * to figure out the exact format -- only the size. Of course, although - * this is enough information for RTEMS, it is probably not enough for - * a debugger such as gdb. But that is another problem. + * On some CPUs with hardware floating point support, the Context_Control_fp + * structure will not be used or it simply consist of an array of a + * fixed number of bytes. This is done when the floating point context + * is dumped by a "FP save context" type instruction and the format + * is not really defined by the CPU. In this case, there is no need + * to figure out the exact format -- only the size. Of course, although + * this is enough information for RTEMS, it is probably not enough for + * a debugger such as gdb. But that is another problem. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate + * + * @{ */ /** - * @ingroup CPUContext Management - * This defines the minimal set of integer and processor state registers - * that must be saved during a voluntary context switch from one thread - * to another. + * This defines the minimal set of integer and processor state registers + * that must be saved during a voluntary context switch from one thread + * to another. */ typedef struct { uint32_t r11; @@ -472,30 +475,27 @@ typedef struct { } Context_Control; /** - * @ingroup CPUContext Management * - * This macro returns the stack pointer associated with @a _context. + * This macro returns the stack pointer associated with @a _context. * - * @param[in] _context is the thread context area to access + * @param[in] _context is the thread context area to access * - * @return This method returns the stack pointer. + * @return This method returns the stack pointer. */ #define _CPU_Context_Get_SP( _context ) \ (_context)->sp /** - * @ingroup CPUContext Management - * This defines the complete set of floating point registers that must - * be saved during any context switch from one thread to another. + * This defines the complete set of floating point registers that must + * be saved during any context switch from one thread to another. */ typedef struct { } Context_Control_fp; /** - * @ingroup CPUContext Management - * This defines the set of integer and processor state registers that must - * be saved during an interrupt. This set does not include any which are - * in @ref Context_Control. + * This defines the set of integer and processor state registers that must + * be saved during an interrupt. This set does not include any which are + * in @ref Context_Control. */ typedef struct { uint32_t r1; @@ -514,173 +514,176 @@ typedef struct { } CPU_Interrupt_frame; /** - * This variable is optional. It is used on CPUs on which it is difficult - * to generate an "uninitialized" FP context. It is filled in by - * @ref _CPU_Initialize and copied into the task's FP context area during - * @ref _CPU_Context_Initialize. + * This variable is optional. It is used on CPUs on which it is difficult + * to generate an "uninitialized" FP context. It is filled in by + * @ref _CPU_Initialize and copied into the task's FP context area during + * @ref _CPU_Context_Initialize. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #if 0 SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context; #endif +/** @} */ + /** - * @defgroup CPUInterrupt Processor Dependent Interrupt Management + * @defgroup CPUInterrupt Processor Dependent Interrupt Management * - * On some CPUs, RTEMS supports a software managed interrupt stack. - * This stack is allocated by the Interrupt Manager and the switch - * is performed in @ref _ISR_Handler. These variables contain pointers - * to the lowest and highest addresses in the chunk of memory allocated - * for the interrupt stack. Since it is unknown whether the stack - * grows up or down (in general), this give the CPU dependent - * code the option of picking the version it wants to use. + * On some CPUs, RTEMS supports a software managed interrupt stack. + * This stack is allocated by the Interrupt Manager and the switch + * is performed in @ref _ISR_Handler. These variables contain pointers + * to the lowest and highest addresses in the chunk of memory allocated + * for the interrupt stack. Since it is unknown whether the stack + * grows up or down (in general), this give the CPU dependent + * code the option of picking the version it wants to use. * - * @note These two variables are required if the macro - * @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE. + * NOTE: These two variables are required if the macro + * @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate + * + * @{ */ /* - * Nothing prevents the porter from declaring more CPU specific variables. + * Nothing prevents the porter from declaring more CPU specific variables. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ /* XXX: if needed, put more variables here */ /** - * @ingroup CPUContext - * The size of the floating point context area. On some CPUs this - * will not be a "sizeof" because the format of the floating point - * area is not defined -- only the size is. This is usually on - * CPUs with a "floating point save context" instruction. + * @ingroup CPUContext + * The size of the floating point context area. On some CPUs this + * will not be a "sizeof" because the format of the floating point + * area is not defined -- only the size is. This is usually on + * CPUs with a "floating point save context" instruction. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp ) /** - * Amount of extra stack (above minimum stack size) required by - * MPCI receive server thread. Remember that in a multiprocessor - * system this thread must exist and be able to process all directives. + * Amount of extra stack (above minimum stack size) required by + * MPCI receive server thread. Remember that in a multiprocessor + * system this thread must exist and be able to process all directives. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0 /** - * @ingroup CPUInterrupt - * This defines the number of entries in the @ref _ISR_Vector_table managed - * by RTEMS. + * This defines the number of entries in the @ref _ISR_Vector_table managed + * by RTEMS. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_INTERRUPT_NUMBER_OF_VECTORS 32 /** - * @ingroup CPUInterrupt - * This defines the highest interrupt vector number for this port. + * This defines the highest interrupt vector number for this port. */ #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1) /** - * @ingroup CPUInterrupt - * This is defined if the port has a special way to report the ISR nesting - * level. Most ports maintain the variable @a _ISR_Nest_level. + * This is defined if the port has a special way to report the ISR nesting + * level. Most ports maintain the variable @a _ISR_Nest_level. */ #define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE +/** @} */ + /** - * @ingroup CPUContext - * Should be large enough to run all RTEMS tests. This ensures - * that a "reasonable" small application should not have any problems. + * @ingroup CPUContext + * Should be large enough to run all RTEMS tests. This ensures + * that a "reasonable" small application should not have any problems. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_STACK_MINIMUM_SIZE (1024*4) #define CPU_SIZEOF_POINTER 4 /** - * CPU's worst alignment requirement for data types on a byte boundary. This - * alignment does not take into account the requirements for the stack. + * CPU's worst alignment requirement for data types on a byte boundary. This + * alignment does not take into account the requirements for the stack. * - * Port Specific Information: - * The LM32 architecture manual simply states: "All memory accesses must be - * aligned to the size of the access", and there is no hardware support - * whatsoever for 64-bit numbers. - * (lm32_archman.pdf, July 2009, p. 15) + * Port Specific Information: + * The LM32 architecture manual simply states: "All memory accesses must be + * aligned to the size of the access", and there is no hardware support + * whatsoever for 64-bit numbers. + * (lm32_archman.pdf, July 2009, p. 15) */ #define CPU_ALIGNMENT 4 /** - * This number corresponds to the byte alignment requirement for the - * heap handler. This alignment requirement may be stricter than that - * for the data types alignment specified by @ref CPU_ALIGNMENT. It is - * common for the heap to follow the same alignment requirement as - * @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is strict enough for - * the heap, then this should be set to @ref CPU_ALIGNMENT. + * This number corresponds to the byte alignment requirement for the + * heap handler. This alignment requirement may be stricter than that + * for the data types alignment specified by @ref CPU_ALIGNMENT. It is + * common for the heap to follow the same alignment requirement as + * @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is strict enough for + * the heap, then this should be set to @ref CPU_ALIGNMENT. * - * @note This does not have to be a power of 2 although it should be - * a multiple of 2 greater than or equal to 2. The requirement - * to be a multiple of 2 is because the heap uses the least - * significant field of the front and back flags to indicate - * that a block is in use or free. So you do not want any odd - * length blocks really putting length data in that bit. + * NOTE: This does not have to be a power of 2 although it should be + * a multiple of 2 greater than or equal to 2. The requirement + * to be a multiple of 2 is because the heap uses the least + * significant field of the front and back flags to indicate + * that a block is in use or free. So you do not want any odd + * length blocks really putting length data in that bit. * - * On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will - * have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that - * elements allocated from the heap meet all restrictions. + * On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will + * have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that + * elements allocated from the heap meet all restrictions. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT /** - * This number corresponds to the byte alignment requirement for memory - * buffers allocated by the partition manager. This alignment requirement - * may be stricter than that for the data types alignment specified by - * @ref CPU_ALIGNMENT. It is common for the partition to follow the same - * alignment requirement as @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is - * strict enough for the partition, then this should be set to - * @ref CPU_ALIGNMENT. + * This number corresponds to the byte alignment requirement for memory + * buffers allocated by the partition manager. This alignment requirement + * may be stricter than that for the data types alignment specified by + * @ref CPU_ALIGNMENT. It is common for the partition to follow the same + * alignment requirement as @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is + * strict enough for the partition, then this should be set to + * @ref CPU_ALIGNMENT. * - * @note This does not have to be a power of 2. It does have to - * be greater or equal to than @ref CPU_ALIGNMENT. + * NOTE: This does not have to be a power of 2. It does have to + * be greater or equal to than @ref CPU_ALIGNMENT. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT /** - * This number corresponds to the byte alignment requirement for the - * stack. This alignment requirement may be stricter than that for the - * data types alignment specified by @ref CPU_ALIGNMENT. + * This number corresponds to the byte alignment requirement for the + * stack. This alignment requirement may be stricter than that for the + * data types alignment specified by @ref CPU_ALIGNMENT. * * - * Port Specific Information: + * Port Specific Information: * - * Stack is software-managed + * Stack is software-managed */ #define CPU_STACK_ALIGNMENT CPU_ALIGNMENT @@ -689,76 +692,76 @@ SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context; */ /** - * @ingroup CPUInterrupt - * Support routine to initialize the RTEMS vector table after it is allocated. + * @addtogroup CPUInterrupt * - * Port Specific Information: + * @{ + */ + +/** + * Support routine to initialize the RTEMS vector table after it is allocated. * - * XXX document implementation including references if appropriate + * Port Specific Information: + * + * XXX document implementation including references if appropriate */ #define _CPU_Initialize_vectors() /** - * @ingroup CPUInterrupt - * Disable all interrupts for an RTEMS critical section. The previous - * level is returned in @a _isr_cookie. + * Disable all interrupts for an RTEMS critical section. The previous + * level is returned in @a _isr_cookie. * - * @param[out] _isr_cookie will contain the previous level cookie + * @param[out] _isr_cookie will contain the previous level cookie * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_ISR_Disable( _isr_cookie ) \ lm32_disable_interrupts( _isr_cookie ); /** - * @ingroup CPUInterrupt - * Enable interrupts to the previous level (returned by _CPU_ISR_Disable). - * This indicates the end of an RTEMS critical section. The parameter - * @a _isr_cookie is not modified. + * Enable interrupts to the previous level (returned by _CPU_ISR_Disable). + * This indicates the end of an RTEMS critical section. The parameter + * @a _isr_cookie is not modified. * - * @param[in] _isr_cookie contain the previous level cookie + * @param[in] _isr_cookie contain the previous level cookie * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_ISR_Enable( _isr_cookie ) \ lm32_enable_interrupts( _isr_cookie ); /** - * @ingroup CPUInterrupt - * This temporarily restores the interrupt to @a _isr_cookie before immediately - * disabling them again. This is used to divide long RTEMS critical - * sections into two or more parts. The parameter @a _isr_cookie is not - * modified. + * This temporarily restores the interrupt to @a _isr_cookie before immediately + * disabling them again. This is used to divide long RTEMS critical + * sections into two or more parts. The parameter @a _isr_cookie is not + * modified. * - * @param[in] _isr_cookie contain the previous level cookie + * @param[in] _isr_cookie contain the previous level cookie * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_ISR_Flash( _isr_cookie ) \ lm32_flash_interrupts( _isr_cookie ); /** - * @ingroup CPUInterrupt - * - * This routine and @ref _CPU_ISR_Get_level - * Map the interrupt level in task mode onto the hardware that the CPU - * actually provides. Currently, interrupt levels which do not - * map onto the CPU in a generic fashion are undefined. Someday, - * it would be nice if these were "mapped" by the application - * via a callout. For example, m68k has 8 levels 0 - 7, levels - * 8 - 255 would be available for bsp/application specific meaning. - * This could be used to manage a programmable interrupt controller - * via the rtems_task_mode directive. + * This routine and @ref _CPU_ISR_Get_level + * Map the interrupt level in task mode onto the hardware that the CPU + * actually provides. Currently, interrupt levels which do not + * map onto the CPU in a generic fashion are undefined. Someday, + * it would be nice if these were "mapped" by the application + * via a callout. For example, m68k has 8 levels 0 - 7, levels + * 8 - 255 would be available for bsp/application specific meaning. + * This could be used to manage a programmable interrupt controller + * via the rtems_task_mode directive. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_ISR_Set_level( new_level ) \ { \ @@ -766,52 +769,53 @@ SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context; } /** - * @ingroup CPUInterrupt - * Return the current interrupt disable level for this task in - * the format used by the interrupt level portion of the task mode. + * Return the current interrupt disable level for this task in + * the format used by the interrupt level portion of the task mode. * - * @note This routine usually must be implemented as a subroutine. + * NOTE: This routine usually must be implemented as a subroutine. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ uint32_t _CPU_ISR_Get_level( void ); /* end of ISR handler macros */ +/** @} */ + /* Context handler macros */ /** - * @ingroup CPUContext - * Initialize the context to a state suitable for starting a - * task after a context restore operation. Generally, this - * involves: - * - * - setting a starting address - * - preparing the stack - * - preparing the stack and frame pointers - * - setting the proper interrupt level in the context - * - initializing the floating point context - * - * This routine generally does not set any unnecessary register - * in the context. The state of the "general data" registers is - * undefined at task start time. - * - * @param[in] _the_context is the context structure to be initialized - * @param[in] _stack_base is the lowest physical address of this task's stack - * @param[in] _size is the size of this task's stack - * @param[in] _isr is the interrupt disable level - * @param[in] _entry_point is the thread's entry point. This is - * always @a _Thread_Handler - * @param[in] _is_fp is TRUE if the thread is to be a floating - * point thread. This is typically only used on CPUs where the - * FPU may be easily disabled by software such as on the SPARC - * where the PSR contains an enable FPU bit. + * @ingroup CPUContext + * Initialize the context to a state suitable for starting a + * task after a context restore operation. Generally, this + * involves: * - * Port Specific Information: + * - setting a starting address + * - preparing the stack + * - preparing the stack and frame pointers + * - setting the proper interrupt level in the context + * - initializing the floating point context * - * XXX document implementation including references if appropriate + * This routine generally does not set any unnecessary register + * in the context. The state of the "general data" registers is + * undefined at task start time. + * + * @param[in] _the_context is the context structure to be initialized + * @param[in] _stack_base is the lowest physical address of this task's stack + * @param[in] _size is the size of this task's stack + * @param[in] _isr is the interrupt disable level + * @param[in] _entry_point is the thread's entry point. This is + * always @a _Thread_Handler + * @param[in] _is_fp is TRUE if the thread is to be a floating + * point thread. This is typically only used on CPUs where the + * FPU may be easily disabled by software such as on the SPARC + * where the PSR contains an enable FPU bit. + * + * Port Specific Information: + * + * XXX document implementation including references if appropriate */ extern char _gp[]; @@ -826,44 +830,44 @@ extern char _gp[]; } while ( 0 ) /** - * This routine is responsible for somehow restarting the currently - * executing task. If you are lucky, then all that is necessary - * is restoring the context. Otherwise, there will need to be - * a special assembly routine which does something special in this - * case. For many ports, simply adding a label to the restore path - * of @ref _CPU_Context_switch will work. On other ports, it may be - * possibly to load a few arguments and jump to the restore path. It will - * not work if restarting self conflicts with the stack frame - * assumptions of restoring a context. + * This routine is responsible for somehow restarting the currently + * executing task. If you are lucky, then all that is necessary + * is restoring the context. Otherwise, there will need to be + * a special assembly routine which does something special in this + * case. For many ports, simply adding a label to the restore path + * of @ref _CPU_Context_switch will work. On other ports, it may be + * possibly to load a few arguments and jump to the restore path. It will + * not work if restarting self conflicts with the stack frame + * assumptions of restoring a context. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_Context_Restart_self( _the_context ) \ _CPU_Context_restore( (_the_context) ); /** - * @ingroup CPUContext - * The purpose of this macro is to allow the initial pointer into - * a floating point context area (used to save the floating point - * context) to be at an arbitrary place in the floating point - * context area. + * @ingroup CPUContext + * The purpose of this macro is to allow the initial pointer into + * a floating point context area (used to save the floating point + * context) to be at an arbitrary place in the floating point + * context area. * - * This is necessary because some FP units are designed to have - * their context saved as a stack which grows into lower addresses. - * Other FP units can be saved by simply moving registers into offsets - * from the base of the context area. Finally some FP units provide - * a "dump context" instruction which could fill in from high to low - * or low to high based on the whim of the CPU designers. + * This is necessary because some FP units are designed to have + * their context saved as a stack which grows into lower addresses. + * Other FP units can be saved by simply moving registers into offsets + * from the base of the context area. Finally some FP units provide + * a "dump context" instruction which could fill in from high to low + * or low to high based on the whim of the CPU designers. * - * @param[in] _base is the lowest physical address of the floating point - * context area - * @param[in] _offset is the offset into the floating point area + * @param[in] _base is the lowest physical address of the floating point + * context area + * @param[in] _offset is the offset into the floating point area * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_Context_Fp_start( _base, _offset ) #if 0 @@ -871,22 +875,22 @@ extern char _gp[]; #endif /** - * This routine initializes the FP context area passed to it to. - * There are a few standard ways in which to initialize the - * floating point context. The code included for this macro assumes - * that this is a CPU in which a "initial" FP context was saved into - * @a _CPU_Null_fp_context and it simply copies it to the destination - * context passed to it. + * This routine initializes the FP context area passed to it to. + * There are a few standard ways in which to initialize the + * floating point context. The code included for this macro assumes + * that this is a CPU in which a "initial" FP context was saved into + * @a _CPU_Null_fp_context and it simply copies it to the destination + * context passed to it. * - * Other floating point context save/restore models include: - * -# not doing anything, and - * -# putting a "null FP status word" in the correct place in the FP context. + * Other floating point context save/restore models include: + * -# not doing anything, and + * -# putting a "null FP status word" in the correct place in the FP context. * - * @param[in] _destination is the floating point context area + * @param[in] _destination is the floating point context area * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_Context_Initialize_fp( _destination ) #if 0 @@ -900,13 +904,13 @@ extern char _gp[]; /* Fatal Error manager macros */ /** - * This routine copies _error into a known place -- typically a stack - * location or a register, optionally disables interrupts, and - * halts/stops the CPU. + * This routine copies _error into a known place -- typically a stack + * location or a register, optionally disables interrupts, and + * halts/stops the CPU. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #define _CPU_Fatal_halt( _error ) \ { \ @@ -917,68 +921,67 @@ extern char _gp[]; /* Bitfield handler macros */ /** - * @defgroup CPUBitfield Processor Dependent Bitfield Manipulation + * @defgroup CPUBitfield Processor Dependent Bitfield Manipulation + * + * This set of routines are used to implement fast searches for + * the most important ready task. * - * This set of routines are used to implement fast searches for - * the most important ready task. + * @{ */ /** - * @ingroup CPUBitfield - * This definition is set to TRUE if the port uses the generic bitfield - * manipulation implementation. + * This definition is set to TRUE if the port uses the generic bitfield + * manipulation implementation. */ #define CPU_USE_GENERIC_BITFIELD_CODE TRUE /** - * @ingroup CPUBitfield - * This definition is set to TRUE if the port uses the data tables provided - * by the generic bitfield manipulation implementation. - * This can occur when actually using the generic bitfield manipulation - * implementation or when implementing the same algorithm in assembly - * language for improved performance. It is unlikely that a port will use - * the data if it has a bitfield scan instruction. + * This definition is set to TRUE if the port uses the data tables provided + * by the generic bitfield manipulation implementation. + * This can occur when actually using the generic bitfield manipulation + * implementation or when implementing the same algorithm in assembly + * language for improved performance. It is unlikely that a port will use + * the data if it has a bitfield scan instruction. */ #define CPU_USE_GENERIC_BITFIELD_DATA TRUE /** - * @ingroup CPUBitfield - * This routine sets @a _output to the bit number of the first bit - * set in @a _value. @a _value is of CPU dependent type - * @a Priority_bit_map_Control. This type may be either 16 or 32 bits - * wide although only the 16 least significant bits will be used. - * - * There are a number of variables in using a "find first bit" type - * instruction. - * - * -# What happens when run on a value of zero? - * -# Bits may be numbered from MSB to LSB or vice-versa. - * -# The numbering may be zero or one based. - * -# The "find first bit" instruction may search from MSB or LSB. - * - * RTEMS guarantees that (1) will never happen so it is not a concern. - * (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and - * @ref _CPU_Priority_bits_index. These three form a set of routines - * which must logically operate together. Bits in the _value are - * set and cleared based on masks built by @ref _CPU_Priority_Mask. - * The basic major and minor values calculated by @ref _Priority_Major - * and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index - * to properly range between the values returned by the "find first bit" - * instruction. This makes it possible for @ref _Priority_Get_highest to - * calculate the major and directly index into the minor table. - * This mapping is necessary to ensure that 0 (a high priority major/minor) - * is the first bit found. - * - * This entire "find first bit" and mapping process depends heavily - * on the manner in which a priority is broken into a major and minor - * components with the major being the 4 MSB of a priority and minor - * the 4 LSB. Thus (0 << 4) + 0 corresponds to priority 0 -- the highest - * priority. And (15 << 4) + 14 corresponds to priority 254 -- the next - * to the lowest priority. - * - * If your CPU does not have a "find first bit" instruction, then - * there are ways to make do without it. Here are a handful of ways - * to implement this in software: + * This routine sets @a _output to the bit number of the first bit + * set in @a _value. @a _value is of CPU dependent type + * @a Priority_bit_map_Control. This type may be either 16 or 32 bits + * wide although only the 16 least significant bits will be used. + * + * There are a number of variables in using a "find first bit" type + * instruction. + * + * -# What happens when run on a value of zero? + * -# Bits may be numbered from MSB to LSB or vice-versa. + * -# The numbering may be zero or one based. + * -# The "find first bit" instruction may search from MSB or LSB. + * + * RTEMS guarantees that (1) will never happen so it is not a concern. + * (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and + * @ref _CPU_Priority_bits_index. These three form a set of routines + * which must logically operate together. Bits in the _value are + * set and cleared based on masks built by @ref _CPU_Priority_Mask. + * The basic major and minor values calculated by @ref _Priority_Major + * and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index + * to properly range between the values returned by the "find first bit" + * instruction. This makes it possible for @ref _Priority_Get_highest to + * calculate the major and directly index into the minor table. + * This mapping is necessary to ensure that 0 (a high priority major/minor) + * is the first bit found. + * + * This entire "find first bit" and mapping process depends heavily + * on the manner in which a priority is broken into a major and minor + * components with the major being the 4 MSB of a priority and minor + * the 4 LSB. Thus (0 << 4) + 0 corresponds to priority 0 -- the highest + * priority. And (15 << 4) + 14 corresponds to priority 254 -- the next + * to the lowest priority. + * + * If your CPU does not have a "find first bit" instruction, then + * there are ways to make do without it. Here are a handful of ways + * to implement this in software: * @verbatim - a series of 16 bit test instructions @@ -995,15 +998,15 @@ extern char _gp[]; _number += bit_set_table[ _value ] @endverbatim - * where bit_set_table[ 16 ] has values which indicate the first - * bit set + * where bit_set_table[ 16 ] has values which indicate the first + * bit set * - * @param[in] _value is the value to be scanned - * @param[in] _output is the first bit set + * @param[in] _value is the value to be scanned + * @param[in] _output is the first bit set * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE) @@ -1015,14 +1018,16 @@ extern char _gp[]; /* end of Bitfield handler macros */ +/** @} */ + /** - * This routine builds the mask which corresponds to the bit fields - * as searched by @ref _CPU_Bitfield_Find_first_bit. See the discussion - * for that routine. + * This routine builds the mask which corresponds to the bit fields + * as searched by @ref _CPU_Bitfield_Find_first_bit. See the discussion + * for that routine. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE) @@ -1032,17 +1037,17 @@ extern char _gp[]; #endif /** - * @ingroup CPUBitfield - * This routine translates the bit numbers returned by - * @ref _CPU_Bitfield_Find_first_bit into something suitable for use as - * a major or minor component of a priority. See the discussion - * for that routine. + * @ingroup CPUBitfield + * This routine translates the bit numbers returned by + * @ref _CPU_Bitfield_Find_first_bit into something suitable for use as + * a major or minor component of a priority. See the discussion + * for that routine. * - * @param[in] _priority is the major or minor number to translate + * @param[in] _priority is the major or minor number to translate * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE) @@ -1056,26 +1061,31 @@ extern char _gp[]; /* functions */ /** - * This routine performs CPU dependent initialization. + * This routine performs CPU dependent initialization. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_Initialize(void); /** - * @ingroup CPUInterrupt - * This routine installs a "raw" interrupt handler directly into the - * processor's vector table. + * @addtogroup CPUInterrupt * - * @param[in] vector is the vector number - * @param[in] new_handler is the raw ISR handler to install - * @param[in] old_handler is the previously installed ISR Handler + * @{ + */ + +/** + * This routine installs a "raw" interrupt handler directly into the + * processor's vector table. * - * Port Specific Information: + * @param[in] vector is the vector number + * @param[in] new_handler is the raw ISR handler to install + * @param[in] old_handler is the previously installed ISR Handler * - * XXX document implementation including references if appropriate + * Port Specific Information: + * + * XXX document implementation including references if appropriate */ void _CPU_ISR_install_raw_handler( uint32_t vector, @@ -1084,16 +1094,15 @@ void _CPU_ISR_install_raw_handler( ); /** - * @ingroup CPUInterrupt - * This routine installs an interrupt vector. + * This routine installs an interrupt vector. * - * @param[in] vector is the vector number - * @param[in] new_handler is the RTEMS ISR handler to install - * @param[in] old_handler is the previously installed ISR Handler + * @param[in] vector is the vector number + * @param[in] new_handler is the RTEMS ISR handler to install + * @param[in] old_handler is the previously installed ISR Handler * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_ISR_install_vector( uint32_t vector, @@ -1102,40 +1111,41 @@ void _CPU_ISR_install_vector( ); /** - * @ingroup CPUInterrupt - * This routine installs the hardware interrupt stack pointer. + * This routine installs the hardware interrupt stack pointer. * - * @note It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK - * is TRUE. + * NOTE: It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK + * is TRUE. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_Install_interrupt_stack( void ); +/** @} */ + /** - * This routine is the CPU dependent IDLE thread body. + * This routine is the CPU dependent IDLE thread body. * - * @note It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY - * is TRUE. + * NOTE: It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY + * is TRUE. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void *_CPU_Thread_Idle_body( uintptr_t ignored ); /** - * @ingroup CPUContext - * This routine switches from the run context to the heir context. + * @ingroup CPUContext + * This routine switches from the run context to the heir context. * - * @param[in] run points to the context of the currently executing task - * @param[in] heir points to the context of the heir task + * @param[in] run points to the context of the currently executing task + * @param[in] heir points to the context of the heir task * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_Context_switch( Context_Control *run, @@ -1143,90 +1153,95 @@ void _CPU_Context_switch( ); /** - * @ingroup CPUContext - * This routine is generally used only to restart self in an - * efficient manner. It may simply be a label in @ref _CPU_Context_switch. + * @addtogroup CPUContext * - * @param[in] new_context points to the context to be restored. + * @{ + */ + +/** + * This routine is generally used only to restart self in an + * efficient manner. It may simply be a label in @ref _CPU_Context_switch. * - * @note May be unnecessary to reload some registers. + * @param[in] new_context points to the context to be restored. * - * Port Specific Information: + * NOTE: May be unnecessary to reload some registers. * - * XXX document implementation including references if appropriate + * Port Specific Information: + * + * XXX document implementation including references if appropriate */ void _CPU_Context_restore( Context_Control *new_context ) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE; /** - * @ingroup CPUContext - * This routine saves the floating point context passed to it. + * This routine saves the floating point context passed to it. * - * @param[in] fp_context_ptr is a pointer to a pointer to a floating - * point context area + * @param[in] fp_context_ptr is a pointer to a pointer to a floating + * point context area * - * @return on output @a *fp_context_ptr will contain the address that - * should be used with @ref _CPU_Context_restore_fp to restore this context. + * @return on output @a *fp_context_ptr will contain the address that + * should be used with @ref _CPU_Context_restore_fp to restore this context. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_Context_save_fp( Context_Control_fp **fp_context_ptr ); /** - * @ingroup CPUContext - * This routine restores the floating point context passed to it. + * This routine restores the floating point context passed to it. * - * @param[in] fp_context_ptr is a pointer to a pointer to a floating - * point context area to restore + * @param[in] fp_context_ptr is a pointer to a pointer to a floating + * point context area to restore * - * @return on output @a *fp_context_ptr will contain the address that - * should be used with @ref _CPU_Context_save_fp to save this context. + * @return on output @a *fp_context_ptr will contain the address that + * should be used with @ref _CPU_Context_save_fp to save this context. * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ void _CPU_Context_restore_fp( Context_Control_fp **fp_context_ptr ); +/** @} */ + /* FIXME */ typedef CPU_Interrupt_frame CPU_Exception_frame; void _CPU_Exception_frame_print( const CPU_Exception_frame *frame ); /** - * @ingroup CPUEndian - * The following routine swaps the endian format of an unsigned int. - * It must be static because it is referenced indirectly. + * @ingroup CPUEndian + * The following routine swaps the endian format of an unsigned int. + * It must be static because it is referenced indirectly. * - * This version will work on any processor, but if there is a better - * way for your CPU PLEASE use it. The most common way to do this is to: + * This version will work on any processor, but if there is a better + * way for your CPU PLEASE use it. The most common way to do this is to: * - * swap least significant two bytes with 16-bit rotate - * swap upper and lower 16-bits - * swap most significant two bytes with 16-bit rotate + * swap least significant two bytes with 16-bit rotate + * swap upper and lower 16-bits + * swap most significant two bytes with 16-bit rotate * - * Some CPUs have special instructions which swap a 32-bit quantity in - * a single instruction (e.g. i486). It is probably best to avoid - * an "endian swapping control bit" in the CPU. One good reason is - * that interrupts would probably have to be disabled to ensure that - * an interrupt does not try to access the same "chunk" with the wrong - * endian. Another good reason is that on some CPUs, the endian bit - * endianness for ALL fetches -- both code and data -- so the code - * will be fetched incorrectly. + * Some CPUs have special instructions which swap a 32-bit quantity in + * a single instruction (e.g. i486). It is probably best to avoid + * an "endian swapping control bit" in the CPU. One good reason is + * that interrupts would probably have to be disabled to ensure that + * an interrupt does not try to access the same "chunk" with the wrong + * endian. Another good reason is that on some CPUs, the endian bit + * endianness for ALL fetches -- both code and data -- so the code + * will be fetched incorrectly. * - * @param[in] value is the value to be swapped - * @return the value after being endian swapped + * @param[in] value is the value to be swapped + * @return the value after being endian swapped * - * Port Specific Information: + * Port Specific Information: * - * XXX document implementation including references if appropriate + * XXX document implementation including references if appropriate */ static inline uint32_t CPU_swap_u32( uint32_t value @@ -1244,11 +1259,11 @@ static inline uint32_t CPU_swap_u32( } /** - * @ingroup CPUEndian - * This routine swaps a 16 bir quantity. + * @ingroup CPUEndian + * This routine swaps a 16 bir quantity. * - * @param[in] value is the value to be swapped - * @return the value after being endian swapped + * @param[in] value is the value to be swapped + * @return the value after being endian swapped */ static inline uint16_t CPU_swap_u16(uint16_t v) { diff --git a/cpukit/score/cpu/lm32/rtems/score/cpu_asm.h b/cpukit/score/cpu/lm32/rtems/score/cpu_asm.h index 7eada7827d..49d0aed5f3 100644 --- a/cpukit/score/cpu/lm32/rtems/score/cpu_asm.h +++ b/cpukit/score/cpu/lm32/rtems/score/cpu_asm.h @@ -1,12 +1,14 @@ /** - * @file rtems/score/cpu_asm.h + * @file + * + * @brief LM32 CPU Assembly File + * + * Very loose template for an include file for the cpu_asm.? file + * if it is implemented as a ".S" file (preprocessed by cpp) instead + * of a ".s" file (preprocessed by gm4 or gasp). */ /* - * Very loose template for an include file for the cpu_asm.? file - * if it is implemented as a ".S" file (preprocessed by cpp) instead - * of a ".s" file (preprocessed by gm4 or gasp). - * * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/lm32/rtems/score/lm32.h b/cpukit/score/cpu/lm32/rtems/score/lm32.h index b1d5edd688..4d03d953ed 100644 --- a/cpukit/score/cpu/lm32/rtems/score/lm32.h +++ b/cpukit/score/cpu/lm32/rtems/score/lm32.h @@ -1,11 +1,14 @@ -/* lm32.h - * - * This file sets up basic CPU dependency settings based on - * compiler settings. For example, it can determine if - * floating point is available. This particular implementation - * is specified to the NO CPU port. +/** + * @file * + * @brief LM32 Set up Basic CPU Dependency Settings Based on Compiler Settings * + * This file sets up basic CPU dependency settings based on + * compiler settings. For example, it can determine if + * floating point is available. This particular implementation + * is specified to the NO CPU port. + */ +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/lm32/rtems/score/types.h b/cpukit/score/cpu/lm32/rtems/score/types.h index aee9f923c1..7caae46e61 100644 --- a/cpukit/score/cpu/lm32/rtems/score/types.h +++ b/cpukit/score/cpu/lm32/rtems/score/types.h @@ -1,11 +1,13 @@ /** - * @file rtems/score/types.h + * @file + * + * @brief LM32 CPU Type Definitions + * + * This include file contains type definitions pertaining to the + * Lattice lm32 processor family. */ /* - * This include file contains type definitions pertaining to the - * Lattice lm32 processor family. - * * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/m32c/rtems/score/m32c.h b/cpukit/score/cpu/m32c/rtems/score/m32c.h index 5cd3e71103..9be83e71e4 100644 --- a/cpukit/score/cpu/m32c/rtems/score/m32c.h +++ b/cpukit/score/cpu/m32c/rtems/score/m32c.h @@ -1,9 +1,15 @@ -/* - * This file sets up basic CPU dependency settings based on - * compiler settings. For example, it can determine if - * floating point is available. This particular implementation - * is specified to the NO CPU port. +/** + * @file + * + * @brief M32C Set up Basic CPU Dependency Settings Based on Compiler Settings * + * This file sets up basic CPU dependency settings based on + * compiler settings. For example, it can determine if + * floating point is available. This particular implementation + * is specified to the NO CPU port. + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/cpu/m32c/varvects.h b/cpukit/score/cpu/m32c/varvects.h index 30884edbd8..7168482b54 100644 --- a/cpukit/score/cpu/m32c/varvects.h +++ b/cpukit/score/cpu/m32c/varvects.h @@ -1,37 +1,41 @@ -/* - -Copyright (c) 2008 Red Hat Incorporated. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. +/** + * @file + * + * @brief M32C Built-in Variable Vector Table Interface + * + * This file defines the interface to the built-in variable vector + * table in R8C/M16C/M32C chips. + */ - The name of Red Hat Incorporated may not be used to endorse - or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL RED HAT INCORPORATED BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -*/ - -/* This file defines the interface to the built-in variable vector - table in R8C/M16C/M32C chips. */ +/* + * Copyright (c) 2008 Red Hat Incorporated. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * The name of Red Hat Incorporated may not be used to endorse + * or promote products derived from this software without specific + * prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL RED HAT INCORPORATED BE LIABLE FOR ANY + * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ #ifndef _VARVECTS_H_ #define _VARVECTS_H_ diff --git a/cpukit/score/cpu/mips/rtems/asm.h b/cpukit/score/cpu/mips/rtems/asm.h index 73e4366b87..9c84f61990 100644 --- a/cpukit/score/cpu/mips/rtems/asm.h +++ b/cpukit/score/cpu/mips/rtems/asm.h @@ -1,17 +1,20 @@ /** - * @file rtems/asm.h + * @file * - * This include file attempts to address the problems - * caused by incompatible flavors of assemblers and - * toolsets. It primarily addresses variations in the - * use of leading underscores on symbols and the requirement - * that register names be preceded by a %. + * @brief Address the Problems Caused by Incompatible Flavor of + * Assemblers and Toolsets + * + * This include file attempts to address the problems + * caused by incompatible flavors of assemblers and + * toolsets. It primarily addresses variations in the + * use of leading underscores on symbols and the requirement + * that register names be preceded by a %. + * + * NOTE: The spacing in the use of these macros + * is critical to them working as advertised. */ /* - * NOTE: The spacing in the use of these macros - * is critical to them working as advertised. - * * COPYRIGHT: * * This file is based on similar code found in newlib available diff --git a/cpukit/score/cpu/sparc/rtems/asm.h b/cpukit/score/cpu/sparc/rtems/asm.h index 530197eeb8..a2b11f63fc 100644 --- a/cpukit/score/cpu/sparc/rtems/asm.h +++ b/cpukit/score/cpu/sparc/rtems/asm.h @@ -1,17 +1,20 @@ /** - * @file rtems/asm.h + * @file * - * This include file attempts to address the problems - * caused by incompatible flavors of assemblers and - * toolsets. It primarily addresses variations in the - * use of leading underscores on symbols and the requirement - * that register names be preceded by a %. + * @brief Address the Problems Caused by Incompatible Flavor of + * Assemblers and Toolsets + * + * This include file attempts to address the problems + * caused by incompatible flavors of assemblers and + * toolsets. It primarily addresses variations in the + * use of leading underscores on symbols and the requirement + * that register names be preceded by a %. + * + * NOTE: The spacing in the use of these macros + * is critical to them working as advertised. */ /* - * NOTE: The spacing in the use of these macros - * is critical to them working as advertised. - * * COPYRIGHT: * * This file is based on similar code found in newlib available diff --git a/cpukit/score/cpu/sparc/rtems/score/cpu.h b/cpukit/score/cpu/sparc/rtems/score/cpu.h index 686d0e25d0..327b06254c 100644 --- a/cpukit/score/cpu/sparc/rtems/score/cpu.h +++ b/cpukit/score/cpu/sparc/rtems/score/cpu.h @@ -1,8 +1,10 @@ /** - * @file rtems/score/cpu.h + * @file * - * This include file contains information pertaining to the port of - * the executive to the SPARC processor. + * @brief SPARC CPU Department Source + * + * This include file contains information pertaining to the port of + * the executive to the SPARC processor. */ /* @@ -27,94 +29,94 @@ extern "C" { /* conditional compilation parameters */ /** - * Should the calls to _Thread_Enable_dispatch be inlined? + * Should the calls to _Thread_Enable_dispatch be inlined? * - * - If TRUE, then they are inlined. - * - If FALSE, then a subroutine call is made. + * - If TRUE, then they are inlined. + * - If FALSE, then a subroutine call is made. * - * On this port, it is faster to inline _Thread_Enable_dispatch. + * On this port, it is faster to inline _Thread_Enable_dispatch. */ #define CPU_INLINE_ENABLE_DISPATCH TRUE /** - * Should the body of the search loops in _Thread_queue_Enqueue_priority - * be unrolled one time? In unrolled each iteration of the loop examines - * two "nodes" on the chain being searched. Otherwise, only one node - * is examined per iteration. + * Should the body of the search loops in _Thread_queue_Enqueue_priority + * be unrolled one time? In unrolled each iteration of the loop examines + * two "nodes" on the chain being searched. Otherwise, only one node + * is examined per iteration. * - * - If TRUE, then the loops are unrolled. - * - If FALSE, then the loops are not unrolled. + * - If TRUE, then the loops are unrolled. + * - If FALSE, then the loops are not unrolled. * - * This parameter could go either way on the SPARC. The interrupt flash - * code is relatively lengthy given the requirements for nops following - * writes to the psr. But if the clock speed were high enough, this would - * not represent a great deal of time. + * This parameter could go either way on the SPARC. The interrupt flash + * code is relatively lengthy given the requirements for nops following + * writes to the psr. But if the clock speed were high enough, this would + * not represent a great deal of time. */ #define CPU_UNROLL_ENQUEUE_PRIORITY TRUE /** - * Does the executive manage a dedicated interrupt stack in software? + * Does the executive manage a dedicated interrupt stack in software? * - * If TRUE, then a stack is allocated in _ISR_Handler_initialization. - * If FALSE, nothing is done. + * If TRUE, then a stack is allocated in _ISR_Handler_initialization. + * If FALSE, nothing is done. * - * The SPARC does not have a dedicated HW interrupt stack and one has - * been implemented in SW. + * The SPARC does not have a dedicated HW interrupt stack and one has + * been implemented in SW. */ #define CPU_HAS_SOFTWARE_INTERRUPT_STACK TRUE /** - * Does the CPU follow the simple vectored interrupt model? + * Does the CPU follow the simple vectored interrupt model? * - * - If TRUE, then RTEMS allocates the vector table it internally manages. - * - If FALSE, then the BSP is assumed to allocate and manage the vector - * table + * - If TRUE, then RTEMS allocates the vector table it internally manages. + * - If FALSE, then the BSP is assumed to allocate and manage the vector + * table * - * THe SPARC is a simple vectored architecture. Usually there is no - * PIC and the CPU directly vectors the interrupts. + * THe SPARC is a simple vectored architecture. Usually there is no + * PIC and the CPU directly vectors the interrupts. */ #define CPU_SIMPLE_VECTORED_INTERRUPTS TRUE -/** - * Does this CPU have hardware support for a dedicated interrupt stack? +/** + * Does this CPU have hardware support for a dedicated interrupt stack? * - * - If TRUE, then it must be installed during initialization. - * - If FALSE, then no installation is performed. + * - If TRUE, then it must be installed during initialization. + * - If FALSE, then no installation is performed. * - * The SPARC does not have a dedicated HW interrupt stack. + * The SPARC does not have a dedicated HW interrupt stack. */ #define CPU_HAS_HARDWARE_INTERRUPT_STACK FALSE /** - * Do we allocate a dedicated interrupt stack in the Interrupt Manager? + * Do we allocate a dedicated interrupt stack in the Interrupt Manager? * - * - If TRUE, then the memory is allocated during initialization. - * - If FALSE, then the memory is allocated during initialization. + * - If TRUE, then the memory is allocated during initialization. + * - If FALSE, then the memory is allocated during initialization. * - * The SPARC does not have hardware support for switching to a - * dedicated interrupt stack. The port includes support for doing this - * in software. + * The SPARC does not have hardware support for switching to a + * dedicated interrupt stack. The port includes support for doing this + * in software. * */ #define CPU_ALLOCATE_INTERRUPT_STACK TRUE /** - * Does the RTEMS invoke the user's ISR with the vector number and - * a pointer to the saved interrupt frame (1) or just the vector - * number (0)? + * Does the RTEMS invoke the user's ISR with the vector number and + * a pointer to the saved interrupt frame (1) or just the vector + * number (0)? * - * The SPARC port does not pass an Interrupt Stack Frame pointer to - * interrupt handlers. + * The SPARC port does not pass an Interrupt Stack Frame pointer to + * interrupt handlers. */ #define CPU_ISR_PASSES_FRAME_POINTER 0 /** - * Does the CPU have hardware floating point? + * Does the CPU have hardware floating point? * - * - If TRUE, then the FLOATING_POINT task attribute is supported. - * - If FALSE, then the FLOATING_POINT task attribute is ignored. + * - If TRUE, then the FLOATING_POINT task attribute is supported. + * - If FALSE, then the FLOATING_POINT task attribute is ignored. * - * This is set based upon the multilib settings. + * This is set based upon the multilib settings. */ #if ( SPARC_HAS_FPU == 1 ) #define CPU_HARDWARE_FP TRUE @@ -123,123 +125,123 @@ extern "C" { #endif /** - * The SPARC GCC port does not have a software floating point library - * that requires RTEMS assistance. + * The SPARC GCC port does not have a software floating point library + * that requires RTEMS assistance. */ #define CPU_SOFTWARE_FP FALSE /** - * Are all tasks FLOATING_POINT tasks implicitly? + * Are all tasks FLOATING_POINT tasks implicitly? * - * - If TRUE, then the FLOATING_POINT task attribute is assumed. - * - If FALSE, then the FLOATING_POINT task attribute is followed. + * - If TRUE, then the FLOATING_POINT task attribute is assumed. + * - If FALSE, then the FLOATING_POINT task attribute is followed. * - * The SPARC GCC port does not implicitly use floating point registers. + * The SPARC GCC port does not implicitly use floating point registers. */ #define CPU_ALL_TASKS_ARE_FP FALSE /** - * Should the IDLE task have a floating point context? + * Should the IDLE task have a floating point context? * - * - If TRUE, then the IDLE task is created as a FLOATING_POINT task - * and it has a floating point context which is switched in and out. - * - If FALSE, then the IDLE task does not have a floating point context. + * - If TRUE, then the IDLE task is created as a FLOATING_POINT task + * and it has a floating point context which is switched in and out. + * - If FALSE, then the IDLE task does not have a floating point context. * - * The IDLE task does not have to be floating point on the SPARC. + * The IDLE task does not have to be floating point on the SPARC. */ #define CPU_IDLE_TASK_IS_FP FALSE /** - * Should the saving of the floating point registers be deferred - * until a context switch is made to another different floating point - * task? + * Should the saving of the floating point registers be deferred + * until a context switch is made to another different floating point + * task? * - * - If TRUE, then the floating point context will not be stored until - * necessary. It will remain in the floating point registers and not - * disturned until another floating point task is switched to. + * - If TRUE, then the floating point context will not be stored until + * necessary. It will remain in the floating point registers and not + * disturned until another floating point task is switched to. * - * - If FALSE, then the floating point context is saved when a floating - * point task is switched out and restored when the next floating point - * task is restored. The state of the floating point registers between - * those two operations is not specified. + * - If FALSE, then the floating point context is saved when a floating + * point task is switched out and restored when the next floating point + * task is restored. The state of the floating point registers between + * those two operations is not specified. * - * On the SPARC, we can disable the FPU for integer only tasks so - * it is safe to defer floating point context switches. + * On the SPARC, we can disable the FPU for integer only tasks so + * it is safe to defer floating point context switches. */ #define CPU_USE_DEFERRED_FP_SWITCH TRUE /** - * Does this port provide a CPU dependent IDLE task implementation? + * Does this port provide a CPU dependent IDLE task implementation? * - * - If TRUE, then the routine _CPU_Thread_Idle_body - * must be provided and is the default IDLE thread body instead of - * _CPU_Thread_Idle_body. + * - If TRUE, then the routine _CPU_Thread_Idle_body + * must be provided and is the default IDLE thread body instead of + * _CPU_Thread_Idle_body. * - * - If FALSE, then use the generic IDLE thread body if the BSP does - * not provide one. + * - If FALSE, then use the generic IDLE thread body if the BSP does + * not provide one. * - * The SPARC architecture does not have a low power or halt instruction. - * It is left to the BSP and/or CPU specific code to provide an IDLE - * thread body which is aware of low power modes. + * The SPARC architecture does not have a low power or halt instruction. + * It is left to the BSP and/or CPU specific code to provide an IDLE + * thread body which is aware of low power modes. */ #define CPU_PROVIDES_IDLE_THREAD_BODY FALSE /** - * Does the stack grow up (toward higher addresses) or down - * (toward lower addresses)? + * Does the stack grow up (toward higher addresses) or down + * (toward lower addresses)? * - * - If TRUE, then the grows upward. - * - If FALSE, then the grows toward smaller addresses. + * - If TRUE, then the grows upward. + * - If FALSE, then the grows toward smaller addresses. * - * The stack grows to lower addresses on the SPARC. + * The stack grows to lower addresses on the SPARC. */ #define CPU_STACK_GROWS_UP FALSE /** - * The following is the variable attribute used to force alignment - * of critical data structures. On some processors it may make - * sense to have these aligned on tighter boundaries than - * the minimum requirements of the compiler in order to have as - * much of the critical data area as possible in a cache line. + * The following is the variable attribute used to force alignment + * of critical data structures. On some processors it may make + * sense to have these aligned on tighter boundaries than + * the minimum requirements of the compiler in order to have as + * much of the critical data area as possible in a cache line. * - * The SPARC does not appear to have particularly strict alignment - * requirements. This value was chosen to take advantages of caches. + * The SPARC does not appear to have particularly strict alignment + * requirements. This value was chosen to take advantages of caches. */ #define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (16))) #define CPU_TIMESTAMP_USE_INT64_INLINE TRUE /** - * Define what is required to specify how the network to host conversion - * routines are handled. + * Define what is required to specify how the network to host conversion + * routines are handled. * - * The SPARC is big endian. + * The SPARC is big endian. */ #define CPU_BIG_ENDIAN TRUE /** - * Define what is required to specify how the network to host conversion - * routines are handled. + * Define what is required to specify how the network to host conversion + * routines are handled. * - * The SPARC is NOT little endian. + * The SPARC is NOT little endian. */ #define CPU_LITTLE_ENDIAN FALSE /** - * The following defines the number of bits actually used in the - * interrupt field of the task mode. How those bits map to the - * CPU interrupt levels is defined by the routine _CPU_ISR_Set_level(). + * The following defines the number of bits actually used in the + * interrupt field of the task mode. How those bits map to the + * CPU interrupt levels is defined by the routine _CPU_ISR_Set_level(). * - * The SPARC has 16 interrupt levels in the PIL field of the PSR. + * The SPARC has 16 interrupt levels in the PIL field of the PSR. */ #define CPU_MODES_INTERRUPT_MASK 0x0000000F #ifndef ASM /** - * This structure represents the organization of the minimum stack frame - * for the SPARC. More framing information is required in certain situaions - * such as when there are a large number of out parameters or when the callee - * must save floating point registers. + * This structure represents the organization of the minimum stack frame + * for the SPARC. More framing information is required in certain situaions + * such as when there are a large number of out parameters or when the callee + * must save floating point registers. */ typedef struct { /** This is the offset of the l0 register. */ @@ -278,8 +280,8 @@ typedef struct { void *structure_return_address; /* - * The following are for the callee to save the register arguments in - * should this be necessary. + * The following are for the callee to save the register arguments in + * should this be necessary. */ /** This is the offset of the register for saved argument 0. */ uint32_t saved_arg0; @@ -354,37 +356,37 @@ typedef struct { /** * @defgroup Contexts SPARC Context Structures * - * @ingroup Score + * @ingroup Score + * + * Generally there are 2 types of context to save. + * + Interrupt registers to save + * + Task level registers to save * - * Generally there are 2 types of context to save. - * + Interrupt registers to save - * + Task level registers to save + * This means we have the following 3 context items: + * + task level context stuff:: Context_Control + * + floating point task stuff:: Context_Control_fp + * + special interrupt level context :: Context_Control_interrupt * - * This means we have the following 3 context items: - * + task level context stuff:: Context_Control - * + floating point task stuff:: Context_Control_fp - * + special interrupt level context :: Context_Control_interrupt + * On the SPARC, we are relatively conservative in that we save most + * of the CPU state in the context area. The ET (enable trap) bit and + * the CWP (current window pointer) fields of the PSR are considered + * system wide resources and are not maintained on a per-thread basis. * - * On the SPARC, we are relatively conservative in that we save most - * of the CPU state in the context area. The ET (enable trap) bit and - * the CWP (current window pointer) fields of the PSR are considered - * system wide resources and are not maintained on a per-thread basis. + * @{ */ #ifndef ASM /** - * @brief SPARC Basic Context + * @brief SPARC basic context. * - * @ingroup Contexts - * - * This structure defines the basic integer and processor state context - * for the SPARC architecture. + * This structure defines the basic integer and processor state context + * for the SPARC architecture. */ typedef struct { /** - * Using a double g0_g1 will put everything in this structure on a - * double word boundary which allows us to use double word loads - * and stores safely in the context switch. + * Using a double g0_g1 will put everything in this structure on a + * double word boundary which allows us to use double word loads + * and stores safely in the context switch. */ double g0_g1; /** This will contain the contents of the g2 register. */ @@ -462,9 +464,9 @@ typedef struct { } Context_Control; /** - * This macro provides a CPU independent way for RTEMS to access the - * stack pointer in a context structure. The actual name and offset is - * CPU architecture dependent. + * This macro provides a CPU independent way for RTEMS to access the + * stack pointer in a context structure. The actual name and offset is + * CPU architecture dependent. */ #define _CPU_Context_Get_SP( _context ) \ (_context)->o6_sp @@ -553,11 +555,9 @@ typedef struct { #ifndef ASM /** - * @brief SPARC Basic Context - * - * @ingroup Contexts + * @brief SPARC basic context. * - * This structure defines floating point context area. + * This structure defines floating point context area. */ typedef struct { /** This will contain the contents of the f0 and f1 register. */ @@ -642,13 +642,15 @@ typedef struct { #ifndef ASM +/** @} */ + /** - * @brief Interrupt Stack Frame (ISF) + * @brief Interrupt stack frame (ISF). * - * Context saved on stack for an interrupt. + * Context saved on stack for an interrupt. * - * @note The PSR, PC, and NPC are only saved in this structure for the - * benefit of the user's handler. + * NOTE: The PSR, PC, and NPC are only saved in this structure for the + * benefit of the user's handler. */ typedef struct { /** On an interrupt, we must save the minimum stack frame. */ @@ -750,27 +752,27 @@ typedef struct { #ifndef ASM /** - * This variable is contains the initialize context for the FP unit. - * It is filled in by _CPU_Initialize and copied into the task's FP - * context area during _CPU_Context_Initialize. + * This variable is contains the initialize context for the FP unit. + * It is filled in by _CPU_Initialize and copied into the task's FP + * context area during _CPU_Context_Initialize. */ SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context CPU_STRUCTURE_ALIGNMENT; /** - * This flag is context switched with each thread. It indicates - * that THIS thread has an _ISR_Dispatch stack frame on its stack. - * By using this flag, we can avoid nesting more interrupt dispatching - * attempts on a previously interrupted thread's stack. + * This flag is context switched with each thread. It indicates + * that THIS thread has an _ISR_Dispatch stack frame on its stack. + * By using this flag, we can avoid nesting more interrupt dispatching + * attempts on a previously interrupted thread's stack. */ SCORE_EXTERN volatile uint32_t _CPU_ISR_Dispatch_disable; /** - * The following type defines an entry in the SPARC's trap table. + * The following type defines an entry in the SPARC's trap table. * - * @note The instructions chosen are RTEMS dependent although one is - * obligated to use two of the four instructions to perform a - * long jump. The other instructions load one register with the - * trap type (a.k.a. vector) and another with the psr. + * NOTE: The instructions chosen are RTEMS dependent although one is + * obligated to use two of the four instructions to perform a + * long jump. The other instructions load one register with the + * trap type (a.k.a. vector) and another with the psr. */ typedef struct { /** This will contain a "mov %psr, %l0" instruction. */ @@ -784,52 +786,52 @@ typedef struct { } CPU_Trap_table_entry; /** - * This is the set of opcodes for the instructions loaded into a trap - * table entry. The routine which installs a handler is responsible - * for filling in the fields for the _handler address and the _vector - * trap type. + * This is the set of opcodes for the instructions loaded into a trap + * table entry. The routine which installs a handler is responsible + * for filling in the fields for the _handler address and the _vector + * trap type. * - * The constants following this structure are masks for the fields which - * must be filled in when the handler is installed. + * The constants following this structure are masks for the fields which + * must be filled in when the handler is installed. */ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; /** - * The size of the floating point context area. + * The size of the floating point context area. */ #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp ) #endif /** - * Amount of extra stack (above minimum stack size) required by - * MPCI receive server thread. Remember that in a multiprocessor - * system this thread must exist and be able to process all directives. + * Amount of extra stack (above minimum stack size) required by + * MPCI receive server thread. Remember that in a multiprocessor + * system this thread must exist and be able to process all directives. */ #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 1024 /** - * This defines the number of entries in the ISR_Vector_table managed - * by the executive. - * - * On the SPARC, there are really only 256 vectors. However, the executive - * has no easy, fast, reliable way to determine which traps are synchronous - * and which are asynchronous. By default, synchronous traps return to the - * instruction which caused the interrupt. So if you install a software - * trap handler as an executive interrupt handler (which is desirable since - * RTEMS takes care of window and register issues), then the executive needs - * to know that the return address is to the trap rather than the instruction - * following the trap. - * - * So vectors 0 through 255 are treated as regular asynchronous traps which - * provide the "correct" return address. Vectors 256 through 512 are assumed - * by the executive to be synchronous and to require that the return address - * be fudged. - * - * If you use this mechanism to install a trap handler which must reexecute - * the instruction which caused the trap, then it should be installed as - * an asynchronous trap. This will avoid the executive changing the return - * address. + * This defines the number of entries in the ISR_Vector_table managed + * by the executive. + * + * On the SPARC, there are really only 256 vectors. However, the executive + * has no easy, fast, reliable way to determine which traps are synchronous + * and which are asynchronous. By default, synchronous traps return to the + * instruction which caused the interrupt. So if you install a software + * trap handler as an executive interrupt handler (which is desirable since + * RTEMS takes care of window and register issues), then the executive needs + * to know that the return address is to the trap rather than the instruction + * following the trap. + * + * So vectors 0 through 255 are treated as regular asynchronous traps which + * provide the "correct" return address. Vectors 256 through 512 are assumed + * by the executive to be synchronous and to require that the return address + * be fudged. + * + * If you use this mechanism to install a trap handler which must reexecute + * the instruction which caused the trap, then it should be installed as + * an asynchronous trap. This will avoid the executive changing the return + * address. */ #define CPU_INTERRUPT_NUMBER_OF_VECTORS 256 @@ -840,18 +842,18 @@ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER 511 /** - * This is the bit step in a vector number to indicate it is being installed - * as a synchronous trap. + * This is the bit step in a vector number to indicate it is being installed + * as a synchronous trap. */ #define SPARC_SYNCHRONOUS_TRAP_BIT_MASK 0x100 /** - * This macro indicates that @a _trap as an asynchronous trap. + * This macro indicates that @a _trap as an asynchronous trap. */ #define SPARC_ASYNCHRONOUS_TRAP( _trap ) (_trap) /** - * This macro indicates that @a _trap as a synchronous trap. + * This macro indicates that @a _trap as a synchronous trap. */ #define SPARC_SYNCHRONOUS_TRAP( _trap ) ((_trap) + 256 ) @@ -861,69 +863,69 @@ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; #define SPARC_REAL_TRAP_NUMBER( _trap ) ((_trap) % 256) /** - * This is defined if the port has a special way to report the ISR nesting - * level. Most ports maintain the variable _ISR_Nest_level. + * This is defined if the port has a special way to report the ISR nesting + * level. Most ports maintain the variable _ISR_Nest_level. */ #define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE /** - * Should be large enough to run all tests. This ensures - * that a "reasonable" small application should not have any problems. + * Should be large enough to run all tests. This ensures + * that a "reasonable" small application should not have any problems. * - * This appears to be a fairly generous number for the SPARC since - * represents a call depth of about 20 routines based on the minimum - * stack frame. + * This appears to be a fairly generous number for the SPARC since + * represents a call depth of about 20 routines based on the minimum + * stack frame. */ #define CPU_STACK_MINIMUM_SIZE (1024*4) #define CPU_SIZEOF_POINTER 4 /** - * CPU's worst alignment requirement for data types on a byte boundary. This - * alignment does not take into account the requirements for the stack. + * CPU's worst alignment requirement for data types on a byte boundary. This + * alignment does not take into account the requirements for the stack. * - * On the SPARC, this is required for double word loads and stores. + * On the SPARC, this is required for double word loads and stores. */ #define CPU_ALIGNMENT 8 /** - * This number corresponds to the byte alignment requirement for the - * heap handler. This alignment requirement may be stricter than that - * for the data types alignment specified by CPU_ALIGNMENT. It is - * common for the heap to follow the same alignment requirement as - * CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the heap, - * then this should be set to CPU_ALIGNMENT. + * This number corresponds to the byte alignment requirement for the + * heap handler. This alignment requirement may be stricter than that + * for the data types alignment specified by CPU_ALIGNMENT. It is + * common for the heap to follow the same alignment requirement as + * CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the heap, + * then this should be set to CPU_ALIGNMENT. * - * @note This does not have to be a power of 2. It does have to - * be greater or equal to than CPU_ALIGNMENT. + * NOTE: This does not have to be a power of 2. It does have to + * be greater or equal to than CPU_ALIGNMENT. */ #define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT /** - * This number corresponds to the byte alignment requirement for memory - * buffers allocated by the partition manager. This alignment requirement - * may be stricter than that for the data types alignment specified by - * CPU_ALIGNMENT. It is common for the partition to follow the same - * alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict - * enough for the partition, then this should be set to CPU_ALIGNMENT. + * This number corresponds to the byte alignment requirement for memory + * buffers allocated by the partition manager. This alignment requirement + * may be stricter than that for the data types alignment specified by + * CPU_ALIGNMENT. It is common for the partition to follow the same + * alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict + * enough for the partition, then this should be set to CPU_ALIGNMENT. * - * @note This does not have to be a power of 2. It does have to - * be greater or equal to than CPU_ALIGNMENT. + * NOTE: This does not have to be a power of 2. It does have to + * be greater or equal to than CPU_ALIGNMENT. */ #define CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT /** - * This number corresponds to the byte alignment requirement for the - * stack. This alignment requirement may be stricter than that for the - * data types alignment specified by CPU_ALIGNMENT. If the CPU_ALIGNMENT - * is strict enough for the stack, then this should be set to 0. + * This number corresponds to the byte alignment requirement for the + * stack. This alignment requirement may be stricter than that for the + * data types alignment specified by CPU_ALIGNMENT. If the CPU_ALIGNMENT + * is strict enough for the stack, then this should be set to 0. * - * @note This must be a power of 2 either 0 or greater than CPU_ALIGNMENT. + * NOTE: This must be a power of 2 either 0 or greater than CPU_ALIGNMENT. * - * The alignment restrictions for the SPARC are not that strict but this - * should unsure that the stack is always sufficiently alignment that the - * window overflow, underflow, and flush routines can use double word loads - * and stores. + * The alignment restrictions for the SPARC are not that strict but this + * should unsure that the stack is always sufficiently alignment that the + * window overflow, underflow, and flush routines can use double word loads + * and stores. */ #define CPU_STACK_ALIGNMENT 16 @@ -934,49 +936,49 @@ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; */ /** - * Support routine to initialize the RTEMS vector table after it is allocated. + * Support routine to initialize the RTEMS vector table after it is allocated. */ #define _CPU_Initialize_vectors() /** - * Disable all interrupts for a critical section. The previous - * level is returned in _level. + * Disable all interrupts for a critical section. The previous + * level is returned in _level. */ #define _CPU_ISR_Disable( _level ) \ (_level) = sparc_disable_interrupts() /** - * Enable interrupts to the previous level (returned by _CPU_ISR_Disable). - * This indicates the end of a critical section. The parameter - * _level is not modified. + * Enable interrupts to the previous level (returned by _CPU_ISR_Disable). + * This indicates the end of a critical section. The parameter + * _level is not modified. */ #define _CPU_ISR_Enable( _level ) \ sparc_enable_interrupts( _level ) /** - * This temporarily restores the interrupt to _level before immediately - * disabling them again. This is used to divide long critical - * sections into two or more parts. The parameter _level is not - * modified. + * This temporarily restores the interrupt to _level before immediately + * disabling them again. This is used to divide long critical + * sections into two or more parts. The parameter _level is not + * modified. */ #define _CPU_ISR_Flash( _level ) \ sparc_flash_interrupts( _level ) /** - * Map interrupt level in task mode onto the hardware that the CPU - * actually provides. Currently, interrupt levels which do not - * map onto the CPU in a straight fashion are undefined. + * Map interrupt level in task mode onto the hardware that the CPU + * actually provides. Currently, interrupt levels which do not + * map onto the CPU in a straight fashion are undefined. */ #define _CPU_ISR_Set_level( _newlevel ) \ sparc_enable_interrupts( _newlevel << 8) /** - * @brief Obtain the Current Interrupt Disable Level + * @brief Obtain the current interrupt disable level. * - * This method is invoked to return the current interrupt disable level. + * This method is invoked to return the current interrupt disable level. * - * @return This method returns the current interrupt disable level. - */ + * @return This method returns the current interrupt disable level. + */ uint32_t _CPU_ISR_Get_level( void ); /* end of ISR handler macros */ @@ -984,15 +986,15 @@ uint32_t _CPU_ISR_Get_level( void ); /* Context handler macros */ /** - * Initialize the context to a state suitable for starting a - * task after a context restore operation. Generally, this - * involves: + * Initialize the context to a state suitable for starting a + * task after a context restore operation. Generally, this + * involves: * - * - setting a starting address - * - preparing the stack - * - preparing the stack and frame pointers - * - setting the proper interrupt level in the context - * - initializing the floating point context + * - setting a starting address + * - preparing the stack + * - preparing the stack and frame pointers + * - setting the proper interrupt level in the context + * - initializing the floating point context * * @param[in] the_context points to the context area * @param[in] stack_base is the low address of the allocated stack area @@ -1001,7 +1003,7 @@ uint32_t _CPU_ISR_Get_level( void ); * @param[in] entry_point is the task's entry point * @param[in] is_fp is set to TRUE if the task is a floating point task * - * @note Implemented as a subroutine for the SPARC port. + * NOTE: Implemented as a subroutine for the SPARC port. */ void _CPU_Context_Initialize( Context_Control *the_context, @@ -1013,17 +1015,17 @@ void _CPU_Context_Initialize( ); /** - * This macro is invoked from _Thread_Handler to do whatever CPU - * specific magic is required that must be done in the context of - * the thread when it starts. + * This macro is invoked from _Thread_Handler to do whatever CPU + * specific magic is required that must be done in the context of + * the thread when it starts. * - * On the SPARC, this is setting the frame pointer so GDB is happy. - * Make GDB stop unwinding at _Thread_Handler, previous register window - * Frame pointer is 0 and calling address must be a function with starting - * with a SAVE instruction. If return address is leaf-function (no SAVE) - * GDB will not look at prev reg window fp. + * On the SPARC, this is setting the frame pointer so GDB is happy. + * Make GDB stop unwinding at _Thread_Handler, previous register window + * Frame pointer is 0 and calling address must be a function with starting + * with a SAVE instruction. If return address is leaf-function (no SAVE) + * GDB will not look at prev reg window fp. * - * _Thread_Handler is known to start with SAVE. + * _Thread_Handler is known to start with SAVE. */ #define _CPU_Context_Initialization_at_thread_begin() \ do { \ @@ -1031,30 +1033,30 @@ void _CPU_Context_Initialize( } while (0) /** - * This routine is responsible for somehow restarting the currently - * executing task. + * This routine is responsible for somehow restarting the currently + * executing task. * - * On the SPARC, this is is relatively painless but requires a small - * amount of wrapper code before using the regular restore code in - * of the context switch. + * On the SPARC, this is is relatively painless but requires a small + * amount of wrapper code before using the regular restore code in + * of the context switch. */ #define _CPU_Context_Restart_self( _the_context ) \ _CPU_Context_restore( (_the_context) ); /** - * The FP context area for the SPARC is a simple structure and nothing - * special is required to find the "starting load point" + * The FP context area for the SPARC is a simple structure and nothing + * special is required to find the "starting load point" */ #define _CPU_Context_Fp_start( _base, _offset ) \ ( (void *) _Addresses_Add_offset( (_base), (_offset) ) ) /** - * This routine initializes the FP context area passed to it to. + * This routine initializes the FP context area passed to it to. * - * The SPARC allows us to use the simple initialization model - * in which an "initial" FP context was saved into _CPU_Null_fp_context - * at CPU initialization and it is simply copied into the destination - * context. + * The SPARC allows us to use the simple initialization model + * in which an "initial" FP context was saved into _CPU_Null_fp_context + * at CPU initialization and it is simply copied into the destination + * context. */ #define _CPU_Context_Initialize_fp( _destination ) \ do { \ @@ -1066,9 +1068,9 @@ void _CPU_Context_Initialize( /* Fatal Error manager macros */ /** - * This routine copies _error into a known place -- typically a stack - * location or a register, optionally disables interrupts, and - * halts/stops the CPU. + * This routine copies _error into a known place -- typically a stack + * location or a register, optionally disables interrupts, and + * halts/stops the CPU. */ #define _CPU_Fatal_halt( _error ) \ do { \ @@ -1085,14 +1087,14 @@ void _CPU_Context_Initialize( #if ( SPARC_HAS_BITSCAN == 0 ) /** - * The SPARC port uses the generic C algorithm for bitfield scan if the - * CPU model does not have a scan instruction. + * The SPARC port uses the generic C algorithm for bitfield scan if the + * CPU model does not have a scan instruction. */ #define CPU_USE_GENERIC_BITFIELD_CODE TRUE /** - * The SPARC port uses the generic C algorithm for bitfield scan if the - * CPU model does not have a scan instruction. Thus is needs the generic - * data table used by that algorithm. + * The SPARC port uses the generic C algorithm for bitfield scan if the + * CPU model does not have a scan instruction. Thus is needs the generic + * data table used by that algorithm. */ #define CPU_USE_GENERIC_BITFIELD_DATA TRUE #else @@ -1104,21 +1106,21 @@ void _CPU_Context_Initialize( /* functions */ /** - * @brief SPARC Specific Initialization + * @brief SPARC specific initialization. * - * This routine performs CPU dependent initialization. + * This routine performs CPU dependent initialization. */ void _CPU_Initialize(void); /** - * @brief SPARC Specific Raw ISR Installer + * @brief SPARC specific raw ISR installer. * - * This routine installs @a new_handler to be directly called from the trap - * table. + * This routine installs @a new_handler to be directly called from the trap + * table. * - * @param[in] vector is the vector number - * @param[in] new_handler is the new ISR handler - * @param[in] old_handler will contain the old ISR handler + * @param[in] vector is the vector number + * @param[in] new_handler is the new ISR handler + * @param[in] old_handler will contain the old ISR handler */ void _CPU_ISR_install_raw_handler( uint32_t vector, @@ -1127,13 +1129,13 @@ void _CPU_ISR_install_raw_handler( ); /** - * @brief SPARC Specific RTEMS ISR Installer + * @brief SPARC specific RTEMS ISR installer. * - * This routine installs an interrupt vector. + * This routine installs an interrupt vector. * - * @param[in] vector is the vector number - * @param[in] new_handler is the new ISR handler - * @param[in] old_handler will contain the old ISR handler + * @param[in] vector is the vector number + * @param[in] new_handler is the new ISR handler + * @param[in] old_handler will contain the old ISR handler */ void _CPU_ISR_install_vector( @@ -1143,12 +1145,12 @@ void _CPU_ISR_install_vector( ); /** - * @brief SPARC Specific Context Switch + * @brief SPARC specific context switch. * - * This routine switches from the run context to the heir context. + * This routine switches from the run context to the heir context. * - * @param[in] run is the currently executing thread - * @param[in] heir will become the currently executing thread + * @param[in] run is the currently executing thread + * @param[in] heir will become the currently executing thread */ void _CPU_Context_switch( Context_Control *run, @@ -1156,12 +1158,12 @@ void _CPU_Context_switch( ); /** - * @brief SPARC Specific Context Restore + * @brief SPARC specific context restore. * - * This routine is generally used only to restart self in an - * efficient manner. + * This routine is generally used only to restart self in an + * efficient manner. * - * @param[in] new_context is the context to restore + * @param[in] new_context is the context to restore */ void _CPU_Context_restore( Context_Control *new_context @@ -1169,14 +1171,14 @@ void _CPU_Context_restore( #if defined(RTEMS_SMP) /** - * @brief SPARC Specific Method to Switch to First Task + * @brief SPARC specific method to switch to first task. * - * This routine is only used to switch to the first task on a - * secondary core in an SMP configuration. We do not need to - * flush all the windows and, in fact, this can be dangerous - * as they may or may not be initialized properly. + * This routine is only used to switch to the first task on a + * secondary core in an SMP configuration. We do not need to + * flush all the windows and, in fact, this can be dangerous + * as they may or may not be initialized properly. * - * @param[in] new_context is the context to restore + * @param[in] new_context is the context to restore */ void _CPU_Context_switch_to_first_task_smp( Context_Control *new_context @@ -1185,7 +1187,7 @@ void _CPU_Context_restore( /** * Macro to access memory and bypass the cache. * - * @note address space 1 is uncacheable + * NOTE: address space 1 is uncacheable */ #define SMP_CPU_SWAP( _address, _value, _previous ) \ do { \ @@ -1202,22 +1204,22 @@ void _CPU_Context_restore( #endif /** - * @brief SPARC Specific Save FPU Method + * @brief SPARC specific save FPU method. * - * This routine saves the floating point context passed to it. + * This routine saves the floating point context passed to it. * - * @param[in] fp_context_ptr is the area to save into + * @param[in] fp_context_ptr is the area to save into */ void _CPU_Context_save_fp( Context_Control_fp **fp_context_ptr ); /** - * @brief SPARC Specific Rstore FPU Method + * @brief SPARC specific restore FPU method. * - * This routine restores the floating point context passed to it. + * This routine restores the floating point context passed to it. * - * @param[in] fp_context_ptr is the area to restore from + * @param[in] fp_context_ptr is the area to restore from */ void _CPU_Context_restore_fp( Context_Control_fp **fp_context_ptr @@ -1238,24 +1240,24 @@ static inline void _CPU_Exception_frame_print( } /** - * @brief SPARC Specific Method to Endian Swap an uint32_t + * @brief SPARC specific method to endian swap an uint32_t. * - * The following routine swaps the endian format of an unsigned int. - * It must be static because it is referenced indirectly. + * The following routine swaps the endian format of an unsigned int. + * It must be static because it is referenced indirectly. * - * @param[in] value is the value to endian swap + * @param[in] value is the value to endian swap * - * This version will work on any processor, but if you come across a better - * way for the SPARC PLEASE use it. The most common way to swap a 32-bit - * entity as shown below is not any more efficient on the SPARC. + * This version will work on any processor, but if you come across a better + * way for the SPARC PLEASE use it. The most common way to swap a 32-bit + * entity as shown below is not any more efficient on the SPARC. * - * - swap least significant two bytes with 16-bit rotate - * - swap upper and lower 16-bits - * - swap most significant two bytes with 16-bit rotate + * - swap least significant two bytes with 16-bit rotate + * - swap upper and lower 16-bits + * - swap most significant two bytes with 16-bit rotate * - * It is not obvious how the SPARC can do significantly better than the - * generic code. gcc 2.7.0 only generates about 12 instructions for the - * following code at optimization level four (i.e. -O4). + * It is not obvious how the SPARC can do significantly better than the + * generic code. gcc 2.7.0 only generates about 12 instructions for the + * following code at optimization level four (i.e. -O4). */ static inline uint32_t CPU_swap_u32( uint32_t value @@ -1273,11 +1275,11 @@ static inline uint32_t CPU_swap_u32( } /** - * @brief SPARC Specific Method to Endian Swap an uint16_t + * @brief SPARC specific method to endian swap an uint16_t. * - * The following routine swaps the endian format of a uint16_t. + * The following routine swaps the endian format of a uint16_t. * - * @param[in] value is the value to endian swap + * @param[in] value is the value to endian swap */ #define CPU_swap_u16( value ) \ (((value&0xff) << 8) | ((value >> 8)&0xff)) diff --git a/cpukit/score/cpu/sparc/rtems/score/sparc.h b/cpukit/score/cpu/sparc/rtems/score/sparc.h index 6b7936f2e5..7436cb8d2d 100644 --- a/cpukit/score/cpu/sparc/rtems/score/sparc.h +++ b/cpukit/score/cpu/sparc/rtems/score/sparc.h @@ -1,5 +1,8 @@ /** - * @file rtems/score/sparc.h + * @file + * + * @brief Information Required to Build RTEMS for a Particular Member + * of the SPARC Family * * This file contains the information required to build * RTEMS for a particular member of the SPARC family. It does @@ -42,25 +45,25 @@ extern "C" { */ /** - * Some higher end SPARCs have a bitscan instructions. It would - * be nice to take advantage of them. Right now, there is no - * port to a CPU model with this feature and no (untested) code - * that is based on this feature flag. + * Some higher end SPARCs have a bitscan instructions. It would + * be nice to take advantage of them. Right now, there is no + * port to a CPU model with this feature and no (untested) code + * that is based on this feature flag. */ #define SPARC_HAS_BITSCAN 0 /** - * This should be OK until a port to a higher end SPARC processor - * is made that has more than 8 register windows. If this cannot - * be determined based on multilib settings (v7/v8/v9), then the - * cpu_asm.S code that depends on this will have to move to libcpu. + * This should be OK until a port to a higher end SPARC processor + * is made that has more than 8 register windows. If this cannot + * be determined based on multilib settings (v7/v8/v9), then the + * cpu_asm.S code that depends on this will have to move to libcpu. */ #define SPARC_NUMBER_OF_REGISTER_WINDOWS 8 /** - * This macro indicates whether this multilib variation has hardware - * floating point or not. We use the gcc cpp predefine _SOFT_FLOAT - * to determine that. + * This macro indicates whether this multilib variation has hardware + * floating point or not. We use the gcc cpp predefine _SOFT_FLOAT + * to determine that. */ #if defined(_SOFT_FLOAT) #define SPARC_HAS_FPU 0 @@ -69,8 +72,8 @@ extern "C" { #endif /** - * This macro contains a string describing the multilib variant being - * build. + * This macro contains a string describing the multilib variant being + * build. */ #if SPARC_HAS_FPU #define CPU_MODEL_NAME "w/FPU" @@ -79,7 +82,7 @@ extern "C" { #endif /** - * Define the name of the CPU family. + * Define the name of the CPU family. */ #define CPU_NAME "SPARC" @@ -88,9 +91,9 @@ extern "C" { */ /** - * PSR masks and starting bit positions + * PSR masks and starting bit positions * - * @note Reserved bits are ignored. + * NOTE: Reserved bits are ignored. */ #if (SPARC_NUMBER_OF_REGISTER_WINDOWS == 8) #define SPARC_PSR_CWP_MASK 0x07 /* bits 0 - 4 */ @@ -145,7 +148,7 @@ extern "C" { #ifndef ASM /** - * This macro is a standard nop instruction. + * This macro is a standard nop instruction. */ #define nop() \ do { \ @@ -153,9 +156,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Obtain the PSR + * @brief Macro to obtain the PSR. * - * This macro returns the current contents of the PSR register in @a _psr. + * This macro returns the current contents of the PSR register in @a _psr. */ #define sparc_get_psr( _psr ) \ do { \ @@ -164,9 +167,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Set the PSR + * @brief Macro to set the PSR. * - * This macro sets the PSR register to the value in @a _psr. + * This macro sets the PSR register to the value in @a _psr. */ #define sparc_set_psr( _psr ) \ do { \ @@ -177,9 +180,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Obtain the TBR + * @brief Macro to obtain the TBR. * - * This macro returns the current contents of the TBR register in @a _tbr. + * This macro returns the current contents of the TBR register in @a _tbr. */ #define sparc_get_tbr( _tbr ) \ do { \ @@ -188,9 +191,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Set the TBR + * @brief Macro to set the TBR. * - * This macro sets the TBR register to the value in @a _tbr. + * This macro sets the TBR register to the value in @a _tbr. */ #define sparc_set_tbr( _tbr ) \ do { \ @@ -198,9 +201,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Obtain the WIM + * @brief Macro to obtain the WIM. * - * This macro returns the current contents of the WIM field in @a _wim. + * This macro returns the current contents of the WIM field in @a _wim. */ #define sparc_get_wim( _wim ) \ do { \ @@ -208,9 +211,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Set the WIM + * @brief Macro to set the WIM. * - * This macro sets the WIM field to the value in @a _wim. + * This macro sets the WIM field to the value in @a _wim. */ #define sparc_set_wim( _wim ) \ do { \ @@ -221,9 +224,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Obtain the Y Register + * @brief Macro to obtain the Y register. * - * This macro returns the current contents of the Y register in @a _y. + * This macro returns the current contents of the Y register in @a _y. */ #define sparc_get_y( _y ) \ do { \ @@ -231,9 +234,9 @@ extern "C" { } while ( 0 ) /** - * @brief Macro to Set the Y Register + * @brief Macro to set the Y register. * - * This macro sets the Y register to the value in @a _y. + * This macro sets the Y register to the value in @a _y. */ #define sparc_set_y( _y ) \ do { \ @@ -241,29 +244,29 @@ extern "C" { } while ( 0 ) /** - * @brief SPARC Disable Processor Interrupts + * @brief SPARC disable processor interrupts. * - * This method is invoked to disable all maskable interrupts. + * This method is invoked to disable all maskable interrupts. * - * @return This method returns the entire PSR contents. + * @return This method returns the entire PSR contents. */ uint32_t sparc_disable_interrupts(void); /** - * @brief SPARC Enable Processor Interrupts + * @brief SPARC enable processor interrupts. * - * This method is invoked to enable all maskable interrupts. + * This method is invoked to enable all maskable interrupts. * - * @param[in] psr is the PSR returned by @ref sparc_disable_interrupts. + * @param[in] psr is the PSR returned by @ref sparc_disable_interrupts. */ void sparc_enable_interrupts(uint32_t psr); /** - * @brief SPARC Flash Processor Interrupts + * @brief SPARC flash processor interrupts. * - * This method is invoked to temporarily enable all maskable interrupts. + * This method is invoked to temporarily enable all maskable interrupts. * - * @param[in] _psr is the PSR returned by @ref sparc_disable_interrupts. + * @param[in] _psr is the PSR returned by @ref sparc_disable_interrupts. */ #define sparc_flash_interrupts( _psr ) \ do { \ @@ -272,11 +275,11 @@ void sparc_enable_interrupts(uint32_t psr); } while ( 0 ) /** - * @brief SPARC Obtain Interrupt Level + * @brief SPARC obtain interrupt level. * - * This method is invoked to obtain the current interrupt disable level. + * This method is invoked to obtain the current interrupt disable level. * - * @param[in] _level is the PSR returned by @ref sparc_disable_interrupts. + * @param[in] _level is the PSR returned by @ref sparc_disable_interrupts. */ #define sparc_get_interrupt_level( _level ) \ do { \ diff --git a/cpukit/score/cpu/sparc/rtems/score/types.h b/cpukit/score/cpu/sparc/rtems/score/types.h index a8e56b73b2..c684763d1a 100644 --- a/cpukit/score/cpu/sparc/rtems/score/types.h +++ b/cpukit/score/cpu/sparc/rtems/score/types.h @@ -1,5 +1,7 @@ /** - * @file rtems/score/types.h + * @file + * + * @brief SPARC CPU Type Definitions * * This include file contains type definitions pertaining to the * SPARC processor family. @@ -26,7 +28,7 @@ extern "C" { #endif /** - * @brief Priority Bit Map Type + * @brief Priority bit map type. * * On the SPARC, there is no bitscan instruction and no penalty associated * for using 16-bit variables. With no overriding architectural factors, @@ -35,16 +37,16 @@ extern "C" { typedef uint16_t Priority_bit_map_Control; /** - * @brief SPARC ISR Handler Return Type + * @brief SPARC ISR handler return type. * - * This is the type which SPARC ISR Handlers return. + * This is the type which SPARC ISR Handlers return. */ typedef void sparc_isr; /** - * @brief SPARC ISR Handler Prototype + * @brief SPARC ISR handler prototype. * - * This is the prototype for SPARC ISR Handlers. + * This is the prototype for SPARC ISR Handlers. */ typedef void ( *sparc_isr_entry )( void ); diff --git a/cpukit/score/cpu/sparc64/rtems/asm.h b/cpukit/score/cpu/sparc64/rtems/asm.h index d670fc6149..f4448b03a5 100644 --- a/cpukit/score/cpu/sparc64/rtems/asm.h +++ b/cpukit/score/cpu/sparc64/rtems/asm.h @@ -1,17 +1,20 @@ /** - * @file rtems/asm.h + * @file * - * This include file attempts to address the problems - * caused by incompatible flavors of assemblers and - * toolsets. It primarily addresses variations in the - * use of leading underscores on symbols and the requirement - * that register names be preceded by a %. + * @brief Address the Problems Caused by Incompatible Flavor of + * Assemblers and Toolsets + * + * This include file attempts to address the problems + * caused by incompatible flavors of assemblers and + * toolsets. It primarily addresses variations in the + * use of leading underscores on symbols and the requirement + * that register names be preceded by a %. + * + * NOTE: The spacing in the use of these macros + * is critical to them working as advertised. */ /* - * NOTE: The spacing in the use of these macros - * is critical to them working as advertised. - * * COPYRIGHT: * * This file is based on similar code found in newlib available diff --git a/cpukit/score/cpu/sparc64/rtems/score/cpu.h b/cpukit/score/cpu/sparc64/rtems/score/cpu.h index f78400f564..36c7144a19 100644 --- a/cpukit/score/cpu/sparc64/rtems/score/cpu.h +++ b/cpukit/score/cpu/sparc64/rtems/score/cpu.h @@ -1,15 +1,19 @@ /** - * @file rtems/score/cpu.h + * @file + * + * @brief SPARC64 CPU Department Source + * + * This include file contains information pertaining to the port of + * the executive to the SPARC64 processor. */ /* - * This include file contains information pertaining to the port of - * the executive to the SPARC64 processor. + * * * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * - * This file is based on the SPARC cpu.h file. Modifications are made + * This file is based on the SPARC cpu.h file. Modifications are made * to support the SPARC64 processor. * COPYRIGHT (c) 2010. Gedare Bloom. * @@ -103,7 +107,7 @@ extern "C" { /* * Does the RTEMS invoke the user's ISR with the vector number and - * a pointer to the saved interrupt frame (1) or just the vector + * a pointer to the saved interrupt frame (1) or just the vector * number (0)? */ @@ -191,10 +195,10 @@ extern "C" { * the minimum requirements of the compiler in order to have as * much of the critical data area as possible in a cache line. * - * The SPARC does not appear to have particularly strict alignment + * The SPARC does not appear to have particularly strict alignment * requirements. This value (16) was chosen to take advantages of caches. * - * SPARC 64 requirements on floating point alignment is at least 8, + * SPARC 64 requirements on floating point alignment is at least 8, * and is 16 if quad-word fp instructions are available (e.g. LDQF). */ @@ -221,7 +225,7 @@ extern "C" { #define CPU_MODES_INTERRUPT_MASK 0x0000000F /* - * This structure represents the organization of the minimum stack frame + * This structure represents the organization of the minimum stack frame * for the SPARC. More framing information is required in certain situaions * such as when there are a large number of out parameters or when the callee * must save floating point registers. @@ -490,7 +494,7 @@ typedef struct { * NOTE: The tstate, tpc, and tnpc are saved in this structure * to allow resetting the TL while still being able to return * from a trap later. The PIL is saved because - * if this is an external interrupt, we will mask lower + * if this is an external interrupt, we will mask lower * priority interrupts until finishing. Even though the y register * is deprecated, gcc still uses it. */ @@ -549,11 +553,11 @@ typedef struct { #define ISF_O7_OFFSET CPU_MINIMUM_STACK_FRAME_SIZE + 0x98 #define ISF_TVEC_OFFSET CPU_MINIMUM_STACK_FRAME_SIZE + 0xA0 -#define CONTEXT_CONTROL_INTERRUPT_FRAME_SIZE CPU_MINIMUM_STACK_FRAME_SIZE + 0xA8 +#define CONTEXT_CONTROL_INTERRUPT_FRAME_SIZE CPU_MINIMUM_STACK_FRAME_SIZE + 0xA8 #ifndef ASM /* * This variable is contains the initialize context for the FP unit. - * It is filled in by _CPU_Initialize and copied into the task's FP + * It is filled in by _CPU_Initialize and copied into the task's FP * context area during _CPU_Context_Initialize. */ @@ -592,9 +596,9 @@ SCORE_EXTERN volatile uint32_t _CPU_ISR_Dispatch_disable; * long jump. The other instructions load one register with the * trap type (a.k.a. vector) and another with the psr. */ -/* For SPARC V9, we must use 6 of these instructions to perform a long - * jump, because the _handler value is now 64-bits. We also need to store - * temporary values in the global register set at this trap level. Because +/* For SPARC V9, we must use 6 of these instructions to perform a long + * jump, because the _handler value is now 64-bits. We also need to store + * temporary values in the global register set at this trap level. Because * the handler runs at TL > 0 with GL > 0, it should be OK to use g2 and g3 * to pass parameters to ISR_Handler. * @@ -614,7 +618,7 @@ typedef struct { uint32_t jmp_to_low_of_handler_plus_g3; /* jmp %g3 + %lo(_handler) */ uint32_t mov_vector_g2; /* mov _vector, %g2 */ } CPU_Trap_table_entry; - + /* * This is the set of opcodes for the instructions loaded into a trap * table entry. The routine which installs a handler is responsible @@ -624,11 +628,11 @@ typedef struct { * The constants following this structure are masks for the fields which * must be filled in when the handler is installed. */ - + extern const CPU_Trap_table_entry _CPU_Trap_slot_template; /* - * The size of the floating point context area. + * The size of the floating point context area. */ #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp ) @@ -666,7 +670,7 @@ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; * an asynchronous trap. This will avoid the executive changing the return * address. */ -/* On SPARC v9, there are 512 vectors. The same philosophy applies to +/* On SPARC v9, there are 512 vectors. The same philosophy applies to * vector installation and use, we just provide a larger table. */ #define CPU_INTERRUPT_NUMBER_OF_VECTORS 512 @@ -796,14 +800,14 @@ extern const CPU_Trap_table_entry _CPU_Trap_slot_template; /* * Map interrupt level in task mode onto the hardware that the CPU * actually provides. Currently, interrupt levels which do not - * map onto the CPU in a straight fashion are undefined. + * map onto the CPU in a straight fashion are undefined. */ #define _CPU_ISR_Set_level( _newlevel ) \ sparc_enable_interrupts( _newlevel) uint32_t _CPU_ISR_Get_level( void ); - + /* end of ISR handler macros */ /* Context handler macros */ @@ -839,7 +843,7 @@ void _CPU_Context_Initialize( * On the SPARC, this is setting the frame pointer so GDB is happy. * Make GDB stop unwinding at _Thread_Handler, previous register window * Frame pointer is 0 and calling address must be a function with starting - * with a SAVE instruction. If return address is leaf-function (no SAVE) + * with a SAVE instruction. If return address is leaf-function (no SAVE) * GDB will not look at prev reg window fp. * * _Thread_Handler is known to start with SAVE. @@ -852,7 +856,7 @@ void _CPU_Context_Initialize( /* * This routine is responsible for somehow restarting the currently - * executing task. + * executing task. * * On the SPARC, this is is relatively painless but requires a small * amount of wrapper code before using the regular restore code in @@ -874,7 +878,7 @@ void _CPU_Context_Initialize( * This routine initializes the FP context area passed to it to. * * The SPARC allows us to use the simple initialization model - * in which an "initial" FP context was saved into _CPU_Null_fp_context + * in which an "initial" FP context was saved into _CPU_Null_fp_context * at CPU initialization and it is simply copied into the destination * context. */ @@ -950,7 +954,7 @@ void _CPU_Initialize(void); * This routine installs new_handler to be directly called from the trap * table. */ - + void _CPU_ISR_install_raw_handler( uint32_t vector, proc_ptr new_handler, @@ -970,14 +974,14 @@ void _CPU_ISR_install_vector( ); #if (CPU_PROVIDES_IDLE_THREAD_BODY == TRUE) - + /* * _CPU_Thread_Idle_body * * Some SPARC implementations have low power, sleep, or idle modes. This * tries to take advantage of those models. */ - + void *_CPU_Thread_Idle_body( uintptr_t ignored ); #endif /* CPU_PROVIDES_IDLE_THREAD_BODY */ @@ -1036,7 +1040,7 @@ void _CPU_Exception_frame_print( const CPU_Exception_frame *frame ); * It must be static because it is referenced indirectly. * * This version will work on any processor, but if you come across a better - * way for the SPARC PLEASE use it. The most common way to swap a 32-bit + * way for the SPARC PLEASE use it. The most common way to swap a 32-bit * entity as shown below is not any more efficient on the SPARC. * * swap least significant two bytes with 16-bit rotate @@ -1047,18 +1051,18 @@ void _CPU_Exception_frame_print( const CPU_Exception_frame *frame ); * generic code. gcc 2.7.0 only generates about 12 instructions for the * following code at optimization level four (i.e. -O4). */ - + static inline uint32_t CPU_swap_u32( uint32_t value ) { uint32_t byte1, byte2, byte3, byte4, swapped; - + byte4 = (value >> 24) & 0xff; byte3 = (value >> 16) & 0xff; byte2 = (value >> 8) & 0xff; byte1 = value & 0xff; - + swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4; return( swapped ); } diff --git a/cpukit/score/cpu/sparc64/rtems/score/sparc64.h b/cpukit/score/cpu/sparc64/rtems/score/sparc64.h index b7ac2c5137..b2df9c17a5 100644 --- a/cpukit/score/cpu/sparc64/rtems/score/sparc64.h +++ b/cpukit/score/cpu/sparc64/rtems/score/sparc64.h @@ -1,15 +1,18 @@ /** - * @file rtems/score/sparc64.h + * @file + * + * @brief Information Required to Build RTEMS for a Particular Member + * of the SPARC Family + * + * This include file contains information pertaining to the SPARC + * processor family. */ /* - * This include file contains information pertaining to the SPARC - * processor family. - * * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * - * This file is based on the SPARC sparc.h file. Modifications are made + * This file is based on the SPARC sparc.h file. Modifications are made * to support the SPARC64 processor. * COPYRIGHT (c) 2010. Gedare Bloom. * @@ -34,19 +37,19 @@ extern "C" { * * Currently recognized feature flags: * - * + SPARC_HAS_FPU + * + SPARC_HAS_FPU * 0 - no HW FPU * 1 - has HW FPU (assumed to be compatible w/90C602) * - * + SPARC_HAS_BITSCAN + * + SPARC_HAS_BITSCAN * 0 - does not have scan instructions * 1 - has scan instruction (not currently implemented) - * + * * + SPARC_NUMBER_OF_REGISTER_WINDOWS * 8 is the most common number supported by SPARC implementations. * SPARC_PSR_CWP_MASK is derived from this value. */ - + /* * Some higher end SPARCs have a bitscan instructions. It would * be nice to take advantage of them. Right now, there is no @@ -67,9 +70,9 @@ extern "C" { */ #define SPARC_NUMBER_OF_REGISTER_WINDOWS 8 - + /* - * This should be determined based on some soft float derived + * This should be determined based on some soft float derived * cpp predefine but gcc does not currently give us that information. */ @@ -96,7 +99,7 @@ extern "C" { * Miscellaneous constants */ -/* +/* * The PSR is deprecated and deleted. * * The following registers represent fields of the PSR: @@ -145,7 +148,7 @@ extern "C" { #ifdef ASM -/* +/* * To enable the FPU we need to set both PSTATE.pef and FPRS.fef */ @@ -237,9 +240,9 @@ extern "C" { /* * read the stick register * - * Note: + * Note: * stick asr=24, mnemonic=stick - * Note: stick does not appear to be a valid ASR for US3, although it is + * Note: stick does not appear to be a valid ASR for US3, although it is * implemented in US3i. */ #define sparc64_read_stick( _stick ) \ @@ -249,11 +252,11 @@ extern "C" { } while ( 0 ) /* - * write the stick_cmpr register + * write the stick_cmpr register * - * Note: + * Note: * stick_cmpr asr=25, mnemonic=stick_cmpr - * Note: stick_cmpr does not appear to be a valid ASR for US3, although it is + * Note: stick_cmpr does not appear to be a valid ASR for US3, although it is * implemented in US3i. */ #define sparc64_write_stick_cmpr( _stick_cmpr ) \ @@ -280,7 +283,7 @@ extern "C" { : "0" (_tick_cmpr) ); \ } while ( 0 ) -/* +/* * Clear the softint register. * * sun4u and sun4v: softint_clr asr = 21, with mnemonic clear_softint @@ -296,12 +299,12 @@ extern "C" { /* * Get and set the Y */ - + #define sparc_get_y( _y ) \ do { \ __asm__ volatile( "rd %%y, %0" : "=r" (_y) : "0" (_y) ); \ } while ( 0 ) - + #define sparc_set_y( _y ) \ do { \ __asm__ volatile( "wr %0, %%y" : "=r" (_y) : "0" (_y) ); \ @@ -310,12 +313,12 @@ extern "C" { /************* /DEPRECATED ****************/ /* - * Manipulate the interrupt level in the pstate + * Manipulate the interrupt level in the pstate */ uint32_t sparc_disable_interrupts(void); void sparc_enable_interrupts(uint32_t); - + #define sparc_flash_interrupts( _level ) \ do { \ register uint32_t _ignored = 0; \ diff --git a/cpukit/score/cpu/sparc64/rtems/score/types.h b/cpukit/score/cpu/sparc64/rtems/score/types.h index 3d289a586a..06b7844042 100644 --- a/cpukit/score/cpu/sparc64/rtems/score/types.h +++ b/cpukit/score/cpu/sparc64/rtems/score/types.h @@ -1,11 +1,13 @@ /** - * @file rtems/score/types.h + * @file + * + * @brief SPARC64 CPU Type Definitions + * + * This include file contains type definitions pertaining to the + * SPARC-v9 processor family. */ /* - * This include file contains type definitions pertaining to the - * SPARC-v9 processor family. - * * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * -- cgit v1.2.3