Changeset 4f5740f in rtems


Ignore:
Timestamp:
Jan 8, 2013, 7:36:13 PM (7 years ago)
Author:
Alex Ivanov <alexivanov97@…>
Branches:
4.11, master
Children:
1f0d013
Parents:
f597cc1
git-author:
Alex Ivanov <alexivanov97@…> (01/08/13 19:36:13)
git-committer:
Jennifer Averett <jennifer.averett@…> (01/08/13 19:36:58)
Message:

score: Doxygen Clean Up Task #16

Location:
cpukit/score/cpu
Files:
19 edited

Legend:

Unmodified
Added
Removed
  • cpukit/score/cpu/bfin/rtems/asm.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/asm.h
     2 * @file
    33 *
    4  *  This include file attempts to address the problems
    5  *  caused by incompatible flavors of assemblers and
    6  *  toolsets.  It primarily addresses variations in the
    7  *  use of leading underscores on symbols and the requirement
    8  *  that register names be preceded by a %.
     4 * @brief Address the Problems Caused by Incompatible Flavor of
     5 * Assemblers and Toolsets
     6 *
     7 * This include file attempts to address the problems
     8 * caused by incompatible flavors of assemblers and
     9 * toolsets.  It primarily addresses variations in the
     10 * use of leading underscores on symbols and the requirement
     11 * that register names be preceded by a %.
     12 *
     13 * @note The spacing in the use of these macros
     14 *       is critical to them working as advertised.
    915 */
    1016
    1117/*
    12  *  NOTE: The spacing in the use of these macros
    13  *        is critical to them working as advertised.
    14  *
    1518 *  COPYRIGHT:
    1619 *
     
    3942#ifndef __USER_LABEL_PREFIX__
    4043/**
    41  *  Recent versions of GNU cpp define variables which indicate the
    42  *  need for underscores and percents.  If not using GNU cpp or
    43  *  the version does not support this, then you will obviously
    44  *  have to define these as appropriate.
     44 * Recent versions of GNU cpp define variables which indicate the
     45 * need for underscores and percents.  If not using GNU cpp or
     46 * the version does not support this, then you will obviously
     47 * have to define these as appropriate.
    4548 *
    46  *  This symbol is prefixed to all C program symbols.
     49 * This symbol is prefixed to all C program symbols.
    4750 */
    4851#define __USER_LABEL_PREFIX__ _
     
    5154#ifndef __REGISTER_PREFIX__
    5255/**
    53  *  Recent versions of GNU cpp define variables which indicate the
    54  *  need for underscores and percents.  If not using GNU cpp or
    55  *  the version does not support this, then you will obviously
    56  *  have to define these as appropriate.
     56 * Recent versions of GNU cpp define variables which indicate the
     57 * need for underscores and percents.  If not using GNU cpp or
     58 * the version does not support this, then you will obviously
     59 * have to define these as appropriate.
    5760 *
    58  *  This symbol is prefixed to all register names.
     61 * This symbol is prefixed to all register names.
    5962 */
    6063#define __REGISTER_PREFIX__
     
    9699/** This macro is used to denote the end of a data section. */
    97100#define END_DATA
    98 /** This macro is used to denote the beginning of the
    99  *  unitialized data section.
     101/**
     102 * This macro is used to denote the beginning of the
     103 * unitialized data section.
    100104 */
    101105#define BEGIN_BSS
     
    106110
    107111/**
    108  *  This macro is used to declare a public global symbol.
     112 * This macro is used to declare a public global symbol.
    109113 *
    110  *  @note This must be tailored for a particular flavor of the C compiler.
    111  *  They may need to put underscores in front of the symbols.
     114 * @note This must be tailored for a particular flavor of the C compiler.
     115 * They may need to put underscores in front of the symbols.
    112116 */
    113117#define PUBLIC(sym) .globl SYM (sym)
    114118
    115119/**
    116  *  This macro is used to prototype a public global symbol.
     120 * This macro is used to prototype a public global symbol.
    117121 *
    118  *  @note This must be tailored for a particular flavor of the C compiler.
    119  *  They may need to put underscores in front of the symbols.
     122 * @note This must be tailored for a particular flavor of the C compiler.
     123 * They may need to put underscores in front of the symbols.
    120124 */
    121125#define EXTERN(sym) .globl SYM (sym)
  • cpukit/score/cpu/bfin/rtems/bfin/bf52x.h

    rf597cc1 r4f5740f  
    11/**
    2  *@file bf52x.h
    3  *
    4  *  This file defines basic MMR for the Blackfin 52x CPU.
    5  *  The MMR have been taken from the ADSP-BF52x Blackfin Processor
    6  *  Hardware Reference from Analog Devices. Mentioned Chapters
    7  *  refer to this Documentation.
    8  *
    9  *      Based on bf533.h
    10  *
     2 * @file
     3 *
     4 * @brief Basic MMR for the Blackfin 52x CPU
     5 *
     6 * This file defines basic MMR for the Blackfin 52x CPU.
     7 * The MMR have been taken from the ADSP-BF52x Blackfin Processor
     8 * Hardware Reference from Analog Devices. Mentioned Chapters
     9 * refer to this Documentation.
     10 *
     11 * Based on bf533.h
     12 */
     13
     14/*
    1115 *  COPYRIGHT (c) 2006.
    1216 *  Atos Automacao Industrial LTDA.
     
    1923 *
    2024 *
    21  * @author    Rohan Kangralkar, ECE Department Northeastern University
    22  * @date          02/15/2011
    23  *
    24  * HISTORY:
    25  *
     25 * Author:    Rohan Kangralkar, ECE Department Northeastern University
     26 * Date:          02/15/2011
    2627 */
    2728
  • cpukit/score/cpu/bfin/rtems/bfin/bf533.h

    rf597cc1 r4f5740f  
    1 /*  bfin.h
    2  *
    3  *  This file defines basic MMR for the Blackfin 531/532/533 CPU.
    4  *  The MMR have been taken from the ADSP-BF533 Blackfin Processor
    5  *  Hardware Reference from Analog Devices. Mentioned Chapters
    6  *  refer to this Documentation.
    7  *
    8  *  The Blackfins MMRs are divided into core MMRs (0xFFE0 0000–0xFFFF FFFF)
    9  *  and System MMRs (0xFFC0 0000–0xFFE0 0000). The core MMRs are defined
    10  *  in bfin.h which is included.
    11  *
     1/**
     2 * @file
     3 *
     4 * @brief Basic MMR for the Blackfin 531/532/533 CPU
     5 *
     6 * This file defines basic MMR for the Blackfin 531/532/533 CPU.
     7 * The MMR have been taken from the ADSP-BF533 Blackfin Processor
     8 * Hardware Reference from Analog Devices. Mentioned Chapters
     9 * refer to this Documentation.
     10 *
     11 * The Blackfins MMRs are divided into core MMRs (0xFFE0 0000–0xFFFF FFFF)
     12 * and System MMRs (0xFFC0 0000–0xFFE0 0000). The core MMRs are defined
     13 * in bfin.h which is included.
     14 */
     15/*
    1216 *  COPYRIGHT (c) 2006.
    1317 *  Atos Automacao Industrial LTDA.
  • cpukit/score/cpu/bfin/rtems/bfin/bfin.h

    rf597cc1 r4f5740f  
    1 /*  bfin.h
     1/**
     2 * @file
    23 *
    3  *  This file defines Macros for MMR register common to all Blackfin
    4  *  Processors.
     4 * @brief Macros for MMR register common to all Blackfin Processors
    55 *
     6 * This file defines Macros for MMR register common to all Blackfin
     7 * Processors.
     8 */
     9/*
    610 *  COPYRIGHT (c) 2006 by Atos Automacao Industrial Ltda.
    711 *             modified by Alain Schaefer <alain.schaefer@easc.ch>
  • cpukit/score/cpu/bfin/rtems/score/bfin.h

    rf597cc1 r4f5740f  
    1 /*  bfin.h
     1/**
     2 * @file
    23 *
    3  *  This file sets up basic CPU dependency settings based on
    4  *  compiler settings.  For example, it can determine if
    5  *  floating point is available.  This particular implementation
    6  *  is specified to the Blackfin port.
     4 * @brief Blackfin Set up Basic CPU Dependency Settings Based on
     5 * Compiler Settings
    76 *
     7 * This file sets up basic CPU dependency settings based on
     8 * compiler settings.  For example, it can determine if
     9 * floating point is available.  This particular implementation
     10 * is specified to the Blackfin port.
     11 */
     12
     13/*
    814 *
    915 *  COPYRIGHT (c) 1989-2006.
  • cpukit/score/cpu/bfin/rtems/score/cpu.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/cpu.h
     2 * @file
     3 *
     4 * @brief Blackfin CPU Department Source
     5 *
     6 * This include file contains information pertaining to the Blackfin
     7 * processor.
    38 */
    49
    510/*
    6  *  This include file contains information pertaining to the Blackfin
    7  *  processor.
    8  *
    911 *  COPYRIGHT (c) 1989-2006.
    1012 *  On-Line Applications Research Corporation (OAR).
     
    3032
    3133/**
    32  *  Should the calls to @ref _Thread_Enable_dispatch be inlined?
    33  *
    34  *  If TRUE, then they are inlined.
    35  *  If FALSE, then a subroutine call is made.
    36  *
    37  *  This conditional is an example of the classic trade-off of size
    38  *  versus speed.  Inlining the call (TRUE) typically increases the
    39  *  size of RTEMS while speeding up the enabling of dispatching.
    40  *
    41  *  @note In general, the @ref _Thread_Dispatch_disable_level will
    42  *  only be 0 or 1 unless you are in an interrupt handler and that
    43  *  interrupt handler invokes the executive.]  When not inlined
    44  *  something calls @ref _Thread_Enable_dispatch which in turns calls
    45  *  @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
    46  *  one subroutine call is avoided entirely.
    47  *
    48  *  Port Specific Information:
    49  *
    50  *  XXX document implementation including references if appropriate
     34 * Should the calls to @ref _Thread_Enable_dispatch be inlined?
     35 *
     36 * If TRUE, then they are inlined.
     37 * If FALSE, then a subroutine call is made.
     38 *
     39 * This conditional is an example of the classic trade-off of size
     40 * versus speed.  Inlining the call (TRUE) typically increases the
     41 * size of RTEMS while speeding up the enabling of dispatching.
     42 *
     43 * @note In general, the @ref _Thread_Dispatch_disable_level will
     44 * only be 0 or 1 unless you are in an interrupt handler and that
     45 * interrupt handler invokes the executive.]  When not inlined
     46 * something calls @ref _Thread_Enable_dispatch which in turns calls
     47 * @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
     48 * one subroutine call is avoided entirely.
     49 *
     50 * Port Specific Information:
     51 *
     52 * XXX document implementation including references if appropriate
    5153 */
    5254#define CPU_INLINE_ENABLE_DISPATCH       FALSE
    5355
    5456/**
    55  *  Should the body of the search loops in _Thread_queue_Enqueue_priority
    56  *  be unrolled one time?  In unrolled each iteration of the loop examines
    57  *  two "nodes" on the chain being searched.  Otherwise, only one node
    58  *  is examined per iteration.
    59  *
    60  *  If TRUE, then the loops are unrolled.
    61  *  If FALSE, then the loops are not unrolled.
    62  *
    63  *  The primary factor in making this decision is the cost of disabling
    64  *  and enabling interrupts (_ISR_Flash) versus the cost of rest of the
    65  *  body of the loop.  On some CPUs, the flash is more expensive than
    66  *  one iteration of the loop body.  In this case, it might be desirable
    67  *  to unroll the loop.  It is important to note that on some CPUs, this
    68  *  code is the longest interrupt disable period in RTEMS.  So it is
    69  *  necessary to strike a balance when setting this parameter.
    70  *
    71  *  Port Specific Information:
    72  *
    73  *  XXX document implementation including references if appropriate
     57 * Should the body of the search loops in _Thread_queue_Enqueue_priority
     58 * be unrolled one time?  In unrolled each iteration of the loop examines
     59 * two "nodes" on the chain being searched.  Otherwise, only one node
     60 * is examined per iteration.
     61 *
     62 * If TRUE, then the loops are unrolled.
     63 * If FALSE, then the loops are not unrolled.
     64 *
     65 * The primary factor in making this decision is the cost of disabling
     66 * and enabling interrupts (_ISR_Flash) versus the cost of rest of the
     67 * body of the loop.  On some CPUs, the flash is more expensive than
     68 * one iteration of the loop body.  In this case, it might be desirable
     69 * to unroll the loop.  It is important to note that on some CPUs, this
     70 * code is the longest interrupt disable period in RTEMS.  So it is
     71 * necessary to strike a balance when setting this parameter.
     72 *
     73 * Port Specific Information:
     74 *
     75 * XXX document implementation including references if appropriate
    7476 */
    7577#define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
    7678
    7779/**
    78  *  Does RTEMS manage a dedicated interrupt stack in software?
    79  *
    80  *  If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
    81  *  If FALSE, nothing is done.
    82  *
    83  *  If the CPU supports a dedicated interrupt stack in hardware,
    84  *  then it is generally the responsibility of the BSP to allocate it
    85  *  and set it up.
    86  *
    87  *  If the CPU does not support a dedicated interrupt stack, then
    88  *  the porter has two options: (1) execute interrupts on the
    89  *  stack of the interrupted task, and (2) have RTEMS manage a dedicated
    90  *  interrupt stack.
    91  *
    92  *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    93  *
    94  *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    95  *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    96  *  possible that both are FALSE for a particular CPU.  Although it
    97  *  is unclear what that would imply about the interrupt processing
    98  *  procedure on that CPU.
    99  *
    100  *  Port Specific Information:
    101  *
    102  *  XXX document implementation including references if appropriate
     80 * Does RTEMS manage a dedicated interrupt stack in software?
     81 *
     82 * If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
     83 * If FALSE, nothing is done.
     84 *
     85 * If the CPU supports a dedicated interrupt stack in hardware,
     86 * then it is generally the responsibility of the BSP to allocate it
     87 * and set it up.
     88 *
     89 * If the CPU does not support a dedicated interrupt stack, then
     90 * the porter has two options: (1) execute interrupts on the
     91 * stack of the interrupted task, and (2) have RTEMS manage a dedicated
     92 * interrupt stack.
     93 *
     94 * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     95 *
     96 * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     97 * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     98 * possible that both are FALSE for a particular CPU.  Although it
     99 * is unclear what that would imply about the interrupt processing
     100 * procedure on that CPU.
     101 *
     102 * Port Specific Information:
     103 *
     104 * XXX document implementation including references if appropriate
    103105 */
    104106#define CPU_HAS_SOFTWARE_INTERRUPT_STACK TRUE
     
    131133
    132134/**
    133  *  Does this CPU have hardware support for a dedicated interrupt stack?
    134  *
    135  *  If TRUE, then it must be installed during initialization.
    136  *  If FALSE, then no installation is performed.
    137  *
    138  *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    139  *
    140  *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    141  *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    142  *  possible that both are FALSE for a particular CPU.  Although it
    143  *  is unclear what that would imply about the interrupt processing
    144  *  procedure on that CPU.
    145  *
    146  *  Port Specific Information:
    147  *
    148  *  XXX document implementation including references if appropriate
     135 * Does this CPU have hardware support for a dedicated interrupt stack?
     136 *
     137 * If TRUE, then it must be installed during initialization.
     138 * If FALSE, then no installation is performed.
     139 *
     140 * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     141 *
     142 * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     143 * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     144 * possible that both are FALSE for a particular CPU.  Although it
     145 * is unclear what that would imply about the interrupt processing
     146 * procedure on that CPU.
     147 *
     148 * Port Specific Information:
     149 *
     150 * XXX document implementation including references if appropriate
    149151 */
    150152#define CPU_HAS_HARDWARE_INTERRUPT_STACK FALSE
    151153
    152154/**
    153  *  Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
    154  *
    155  *  If TRUE, then the memory is allocated during initialization.
    156  *  If FALSE, then the memory is allocated during initialization.
    157  *
    158  *  This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
    159  *
    160  *  Port Specific Information:
    161  *
    162  *  XXX document implementation including references if appropriate
     155 * Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
     156 *
     157 * If TRUE, then the memory is allocated during initialization.
     158 * If FALSE, then the memory is allocated during initialization.
     159 *
     160 * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
     161 *
     162 * Port Specific Information:
     163 *
     164 * XXX document implementation including references if appropriate
    163165 */
    164166#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
    165167
    166168/**
    167  *  Does the RTEMS invoke the user's ISR with the vector number and
    168  *  a pointer to the saved interrupt frame (1) or just the vector
    169  *  number (0)?
    170  *
    171  *  Port Specific Information:
    172  *
    173  *  XXX document implementation including references if appropriate
     169 * Does the RTEMS invoke the user's ISR with the vector number and
     170 * a pointer to the saved interrupt frame (1) or just the vector
     171 * number (0)?
     172 *
     173 * Port Specific Information:
     174 *
     175 * XXX document implementation including references if appropriate
    174176 */
    175177#define CPU_ISR_PASSES_FRAME_POINTER 1
    176178
    177179/**
    178  *  @def CPU_HARDWARE_FP
    179  *
    180  *  Does the CPU have hardware floating point?
    181  *
    182  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
    183  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
    184  *
    185  *  If there is a FP coprocessor such as the i387 or mc68881, then
    186  *  the answer is TRUE.
    187  *
    188  *  The macro name "NO_CPU_HAS_FPU" should be made CPU specific.
    189  *  It indicates whether or not this CPU model has FP support.  For
    190  *  example, it would be possible to have an i386_nofp CPU model
    191  *  which set this to false to indicate that you have an i386 without
    192  *  an i387 and wish to leave floating point support out of RTEMS.
    193  */
    194 
    195 /**
    196  *  @def CPU_SOFTWARE_FP
    197  *
    198  *  Does the CPU have no hardware floating point and GCC provides a
    199  *  software floating point implementation which must be context
    200  *  switched?
    201  *
    202  *  This feature conditional is used to indicate whether or not there
    203  *  is software implemented floating point that must be context
    204  *  switched.  The determination of whether or not this applies
    205  *  is very tool specific and the state saved/restored is also
    206  *  compiler specific.
    207  *
    208  *  Port Specific Information:
    209  *
    210  *  XXX document implementation including references if appropriate
     180 * @def CPU_HARDWARE_FP
     181 *
     182 * Does the CPU have hardware floating point?
     183 *
     184 * If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
     185 * If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
     186 *
     187 * If there is a FP coprocessor such as the i387 or mc68881, then
     188 * the answer is TRUE.
     189 *
     190 * The macro name "NO_CPU_HAS_FPU" should be made CPU specific.
     191 * It indicates whether or not this CPU model has FP support.  For
     192 * example, it would be possible to have an i386_nofp CPU model
     193 * which set this to false to indicate that you have an i386 without
     194 * an i387 and wish to leave floating point support out of RTEMS.
     195 */
     196
     197/**
     198 * @def CPU_SOFTWARE_FP
     199 *
     200 * Does the CPU have no hardware floating point and GCC provides a
     201 * software floating point implementation which must be context
     202 * switched?
     203 *
     204 * This feature conditional is used to indicate whether or not there
     205 * is software implemented floating point that must be context
     206 * switched.  The determination of whether or not this applies
     207 * is very tool specific and the state saved/restored is also
     208 * compiler specific.
     209 *
     210 * Port Specific Information:
     211 *
     212 * XXX document implementation including references if appropriate
    211213 */
    212214#if ( BLACKFIN_CPU_HAS_FPU == 1 )
     
    218220
    219221/**
    220  *  Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
    221  *
    222  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
    223  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
    224  *
    225  *  So far, the only CPUs in which this option has been used are the
    226  *  HP PA-RISC and PowerPC.  On the PA-RISC, The HP C compiler and
    227  *  gcc both implicitly used the floating point registers to perform
    228  *  integer multiplies.  Similarly, the PowerPC port of gcc has been
    229  *  seen to allocate floating point local variables and touch the FPU
    230  *  even when the flow through a subroutine (like vfprintf()) might
    231  *  not use floating point formats.
    232  *
    233  *  If a function which you would not think utilize the FP unit DOES,
    234  *  then one can not easily predict which tasks will use the FP hardware.
    235  *  In this case, this option should be TRUE.
    236  *
    237  *  If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
    238  *
    239  *  Port Specific Information:
    240  *
    241  *  XXX document implementation including references if appropriate
     222 * Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
     223 *
     224 * If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
     225 * If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
     226 *
     227 * So far, the only CPUs in which this option has been used are the
     228 * HP PA-RISC and PowerPC.  On the PA-RISC, The HP C compiler and
     229 * gcc both implicitly used the floating point registers to perform
     230 * integer multiplies.  Similarly, the PowerPC port of gcc has been
     231 * seen to allocate floating point local variables and touch the FPU
     232 * even when the flow through a subroutine (like vfprintf()) might
     233 * not use floating point formats.
     234 *
     235 * If a function which you would not think utilize the FP unit DOES,
     236 * then one can not easily predict which tasks will use the FP hardware.
     237 * In this case, this option should be TRUE.
     238 *
     239 * If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
     240 *
     241 * Port Specific Information:
     242 *
     243 * XXX document implementation including references if appropriate
    242244 */
    243245#define CPU_ALL_TASKS_ARE_FP     FALSE
    244246
    245247/**
    246  *  Should the IDLE task have a floating point context?
    247  *
    248  *  If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
    249  *  and it has a floating point context which is switched in and out.
    250  *  If FALSE, then the IDLE task does not have a floating point context.
    251  *
    252  *  Setting this to TRUE negatively impacts the time required to preempt
    253  *  the IDLE task from an interrupt because the floating point context
    254  *  must be saved as part of the preemption.
    255  *
    256  *  Port Specific Information:
    257  *
    258  *  XXX document implementation including references if appropriate
     248 * Should the IDLE task have a floating point context?
     249 *
     250 * If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
     251 * and it has a floating point context which is switched in and out.
     252 * If FALSE, then the IDLE task does not have a floating point context.
     253 *
     254 * Setting this to TRUE negatively impacts the time required to preempt
     255 * the IDLE task from an interrupt because the floating point context
     256 * must be saved as part of the preemption.
     257 *
     258 * Port Specific Information:
     259 *
     260 * XXX document implementation including references if appropriate
    259261 */
    260262#define CPU_IDLE_TASK_IS_FP      FALSE
    261263
    262264/**
    263  *  Should the saving of the floating point registers be deferred
    264  *  until a context switch is made to another different floating point
    265  *  task?
    266  *
    267  *  If TRUE, then the floating point context will not be stored until
    268  *  necessary.  It will remain in the floating point registers and not
    269  *  disturned until another floating point task is switched to.
    270  *
    271  *  If FALSE, then the floating point context is saved when a floating
    272  *  point task is switched out and restored when the next floating point
    273  *  task is restored.  The state of the floating point registers between
    274  *  those two operations is not specified.
    275  *
    276  *  If the floating point context does NOT have to be saved as part of
    277  *  interrupt dispatching, then it should be safe to set this to TRUE.
    278  *
    279  *  Setting this flag to TRUE results in using a different algorithm
    280  *  for deciding when to save and restore the floating point context.
    281  *  The deferred FP switch algorithm minimizes the number of times
    282  *  the FP context is saved and restored.  The FP context is not saved
    283  *  until a context switch is made to another, different FP task.
    284  *  Thus in a system with only one FP task, the FP context will never
    285  *  be saved or restored.
    286  *
    287  *  Port Specific Information:
    288  *
    289  *  XXX document implementation including references if appropriate
     265 * Should the saving of the floating point registers be deferred
     266 * until a context switch is made to another different floating point
     267 * task?
     268 *
     269 * If TRUE, then the floating point context will not be stored until
     270 * necessary.  It will remain in the floating point registers and not
     271 * disturned until another floating point task is switched to.
     272 *
     273 * If FALSE, then the floating point context is saved when a floating
     274 * point task is switched out and restored when the next floating point
     275 * task is restored.  The state of the floating point registers between
     276 * those two operations is not specified.
     277 *
     278 * If the floating point context does NOT have to be saved as part of
     279 * interrupt dispatching, then it should be safe to set this to TRUE.
     280 *
     281 * Setting this flag to TRUE results in using a different algorithm
     282 * for deciding when to save and restore the floating point context.
     283 * The deferred FP switch algorithm minimizes the number of times
     284 * the FP context is saved and restored.  The FP context is not saved
     285 * until a context switch is made to another, different FP task.
     286 * Thus in a system with only one FP task, the FP context will never
     287 * be saved or restored.
     288 *
     289 * Port Specific Information:
     290 *
     291 * XXX document implementation including references if appropriate
    290292 */
    291293#define CPU_USE_DEFERRED_FP_SWITCH       TRUE
    292294
    293295/**
    294  *  Does this port provide a CPU dependent IDLE task implementation?
    295  *
    296  *  If TRUE, then the routine @ref _CPU_Thread_Idle_body
    297  *  must be provided and is the default IDLE thread body instead of
    298  *  @ref _CPU_Thread_Idle_body.
    299  *
    300  *  If FALSE, then use the generic IDLE thread body if the BSP does
    301  *  not provide one.
    302  *
    303  *  This is intended to allow for supporting processors which have
    304  *  a low power or idle mode.  When the IDLE thread is executed, then
    305  *  the CPU can be powered down.
    306  *
    307  *  The order of precedence for selecting the IDLE thread body is:
    308  *
    309  *    -#  BSP provided
    310  *    -#  CPU dependent (if provided)
    311  *    -#  generic (if no BSP and no CPU dependent)
    312  *
    313  *  Port Specific Information:
    314  *
    315  *  XXX document implementation including references if appropriate
     296 * Does this port provide a CPU dependent IDLE task implementation?
     297 *
     298 * If TRUE, then the routine @ref _CPU_Thread_Idle_body
     299 * must be provided and is the default IDLE thread body instead of
     300 * @ref _CPU_Thread_Idle_body.
     301 *
     302 * If FALSE, then use the generic IDLE thread body if the BSP does
     303 * not provide one.
     304 *
     305 * This is intended to allow for supporting processors which have
     306 * a low power or idle mode.  When the IDLE thread is executed, then
     307 * the CPU can be powered down.
     308 *
     309 * The order of precedence for selecting the IDLE thread body is:
     310 *
     311 *   -#  BSP provided
     312 *   -#  CPU dependent (if provided)
     313 *   -#  generic (if no BSP and no CPU dependent)
     314 *
     315 * Port Specific Information:
     316 *
     317 * XXX document implementation including references if appropriate
    316318 */
    317319#define CPU_PROVIDES_IDLE_THREAD_BODY    TRUE
    318320
    319321/**
    320  *  Does the stack grow up (toward higher addresses) or down
    321  *  (toward lower addresses)?
    322  *
    323  *  If TRUE, then the grows upward.
    324  *  If FALSE, then the grows toward smaller addresses.
    325  *
    326  *  Port Specific Information:
    327  *
    328  *  XXX document implementation including references if appropriate
     322 * Does the stack grow up (toward higher addresses) or down
     323 * (toward lower addresses)?
     324 *
     325 * If TRUE, then the grows upward.
     326 * If FALSE, then the grows toward smaller addresses.
     327 *
     328 * Port Specific Information:
     329 *
     330 * XXX document implementation including references if appropriate
    329331 */
    330332#define CPU_STACK_GROWS_UP               FALSE
    331333
    332334/**
    333  *  The following is the variable attribute used to force alignment
    334  *  of critical RTEMS structures.  On some processors it may make
    335  *  sense to have these aligned on tighter boundaries than
    336  *  the minimum requirements of the compiler in order to have as
    337  *  much of the critical data area as possible in a cache line.
    338  *
    339  *  The placement of this macro in the declaration of the variables
    340  *  is based on the syntactically requirements of the GNU C
    341  *  "__attribute__" extension.  For example with GNU C, use
    342  *  the following to force a structures to a 32 byte boundary.
    343  *
    344  *      __attribute__ ((aligned (32)))
    345  *
    346  *  @note Currently only the Priority Bit Map table uses this feature.
    347  *        To benefit from using this, the data must be heavily
    348  *        used so it will stay in the cache and used frequently enough
    349  *        in the executive to justify turning this on.
    350  *
    351  *  Port Specific Information:
    352  *
    353  *  XXX document implementation including references if appropriate
     335 * The following is the variable attribute used to force alignment
     336 * of critical RTEMS structures.  On some processors it may make
     337 * sense to have these aligned on tighter boundaries than
     338 * the minimum requirements of the compiler in order to have as
     339 * much of the critical data area as possible in a cache line.
     340 *
     341 * The placement of this macro in the declaration of the variables
     342 * is based on the syntactically requirements of the GNU C
     343 * "__attribute__" extension.  For example with GNU C, use
     344 * the following to force a structures to a 32 byte boundary.
     345 *
     346 *     __attribute__ ((aligned (32)))
     347 *
     348 * @note Currently only the Priority Bit Map table uses this feature.
     349 *       To benefit from using this, the data must be heavily
     350 *       used so it will stay in the cache and used frequently enough
     351 *       in the executive to justify turning this on.
     352 *
     353 * Port Specific Information:
     354 *
     355 * XXX document implementation including references if appropriate
    354356 */
    355357#define CPU_STRUCTURE_ALIGNMENT
     
    358360
    359361/**
    360  *  @defgroup CPUEndian Processor Dependent Endianness Support
    361  *
    362  *  This group assists in issues related to processor endianness.
    363  */
    364 
    365 /**
    366  *  @ingroup CPUEndian
    367  *  Define what is required to specify how the network to host conversion
    368  *  routines are handled.
    369  *
    370  *  @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
    371  *  same values.
    372  *
    373  *  @see CPU_LITTLE_ENDIAN
    374  *
    375  *  Port Specific Information:
    376  *
    377  *  XXX document implementation including references if appropriate
     362 * @defgroup CPUEndian Processor Dependent Endianness Support
     363 *
     364 * This group assists in issues related to processor endianness.
     365 *
     366 * @{
     367 */
     368
     369/**
     370 * Define what is required to specify how the network to host conversion
     371 * routines are handled.
     372 *
     373 * @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
     374 * same values.
     375 *
     376 * @see CPU_LITTLE_ENDIAN
     377 *
     378 * Port Specific Information:
     379 *
     380 * XXX document implementation including references if appropriate
    378381 */
    379382#define CPU_BIG_ENDIAN                           FALSE
    380383
    381384/**
    382  *  @ingroup CPUEndian
    383  *  Define what is required to specify how the network to host conversion
    384  *  routines are handled.
    385  *
    386  *  @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
    387  *  same values.
    388  *
    389  *  @see CPU_BIG_ENDIAN
    390  *
    391  *  Port Specific Information:
    392  *
    393  *  XXX document implementation including references if appropriate
     385 * Define what is required to specify how the network to host conversion
     386 * routines are handled.
     387 *
     388 * @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
     389 * same values.
     390 *
     391 * @see CPU_BIG_ENDIAN
     392 *
     393 * Port Specific Information:
     394 *
     395 * XXX document implementation including references if appropriate
    394396 */
    395397#define CPU_LITTLE_ENDIAN                        TRUE
    396398
    397 /**
    398  *  @ingroup CPUInterrupt
    399  *  The following defines the number of bits actually used in the
    400  *  interrupt field of the task mode.  How those bits map to the
    401  *  CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
    402  *
    403  *  Port Specific Information:
    404  *
    405  *  XXX document implementation including references if appropriate
     399/** @} */
     400
     401/**
     402 * @ingroup CPUInterrupt
     403 * The following defines the number of bits actually used in the
     404 * interrupt field of the task mode.  How those bits map to the
     405 * CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
     406 *
     407 * Port Specific Information:
     408 *
     409 * XXX document implementation including references if appropriate
    406410 */
    407411#define CPU_MODES_INTERRUPT_MASK   0x00000001
     
    420424 * @defgroup CPUContext Processor Dependent Context Management
    421425 *
    422  *  From the highest level viewpoint, there are 2 types of context to save.
    423  *
    424  *     -# Interrupt registers to save
    425  *     -# Task level registers to save
    426  *
    427  *  Since RTEMS handles integer and floating point contexts separately, this
    428  *  means we have the following 3 context items:
    429  *
    430  *     -# task level context stuff::  Context_Control
    431  *     -# floating point task stuff:: Context_Control_fp
    432  *     -# special interrupt level context :: CPU_Interrupt_frame
    433  *
    434  *  On some processors, it is cost-effective to save only the callee
    435  *  preserved registers during a task context switch.  This means
    436  *  that the ISR code needs to save those registers which do not
    437  *  persist across function calls.  It is not mandatory to make this
    438  *  distinctions between the caller/callee saves registers for the
    439  *  purpose of minimizing context saved during task switch and on interrupts.
    440  *  If the cost of saving extra registers is minimal, simplicity is the
    441  *  choice.  Save the same context on interrupt entry as for tasks in
    442  *  this case.
    443  *
    444  *  Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then
    445  *  care should be used in designing the context area.
    446  *
    447  *  On some CPUs with hardware floating point support, the Context_Control_fp
    448  *  structure will not be used or it simply consist of an array of a
    449  *  fixed number of bytes.   This is done when the floating point context
    450  *  is dumped by a "FP save context" type instruction and the format
    451  *  is not really defined by the CPU.  In this case, there is no need
    452  *  to figure out the exact format -- only the size.  Of course, although
    453  *  this is enough information for RTEMS, it is probably not enough for
    454  *  a debugger such as gdb.  But that is another problem.
    455  *
    456  *  Port Specific Information:
    457  *
    458  *  XXX document implementation including references if appropriate
     426 * From the highest level viewpoint, there are 2 types of context to save.
     427 *
     428 *    -# Interrupt registers to save
     429 *    -# Task level registers to save
     430 *
     431 * Since RTEMS handles integer and floating point contexts separately, this
     432 * means we have the following 3 context items:
     433 *
     434 *    -# task level context stuff::  Context_Control
     435 *    -# floating point task stuff:: Context_Control_fp
     436 *    -# special interrupt level context :: CPU_Interrupt_frame
     437 *
     438 * On some processors, it is cost-effective to save only the callee
     439 * preserved registers during a task context switch.  This means
     440 * that the ISR code needs to save those registers which do not
     441 * persist across function calls.  It is not mandatory to make this
     442 * distinctions between the caller/callee saves registers for the
     443 * purpose of minimizing context saved during task switch and on interrupts.
     444 * If the cost of saving extra registers is minimal, simplicity is the
     445 * choice.  Save the same context on interrupt entry as for tasks in
     446 * this case.
     447 *
     448 * Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then
     449 * care should be used in designing the context area.
     450 *
     451 * On some CPUs with hardware floating point support, the Context_Control_fp
     452 * structure will not be used or it simply consist of an array of a
     453 * fixed number of bytes.   This is done when the floating point context
     454 * is dumped by a "FP save context" type instruction and the format
     455 * is not really defined by the CPU.  In this case, there is no need
     456 * to figure out the exact format -- only the size.  Of course, although
     457 * this is enough information for RTEMS, it is probably not enough for
     458 * a debugger such as gdb.  But that is another problem.
     459 *
     460 * Port Specific Information:
     461 *
     462 * XXX document implementation including references if appropriate
     463 *
     464 * @{
    459465 */
    460466
     
    462468
    463469/**
    464  *  @ingroup CPUContext Management
    465  *  This defines the minimal set of integer and processor state registers
    466  *  that must be saved during a voluntary context switch from one thread
    467  *  to another.
     470 * This defines the minimal set of integer and processor state registers
     471 * that must be saved during a voluntary context switch from one thread
     472 * to another.
    468473 */
    469474
     
    491496
    492497/**
    493  *  @ingroup CPUContext Management
    494  *  This defines the complete set of floating point registers that must
    495  *  be saved during any context switch from one thread to another.
     498 * This defines the complete set of floating point registers that must
     499 * be saved during any context switch from one thread to another.
    496500 */
    497501typedef struct {
     
    501505
    502506/**
    503  *  @ingroup CPUContext Management
    504  *  This defines the set of integer and processor state registers that must
    505  *  be saved during an interrupt.  This set does not include any which are
    506  *  in @ref Context_Control.
     507 * This defines the set of integer and processor state registers that must
     508 * be saved during an interrupt.  This set does not include any which are
     509 * in @ref Context_Control.
    507510 */
    508511typedef struct {
    509512    /** This field is a hint that a port will have a number of integer
    510      *  registers that need to be saved when an interrupt occurs or
    511      *  when a context switch occurs at the end of an ISR.
     513     * registers that need to be saved when an interrupt occurs or
     514     * when a context switch occurs at the end of an ISR.
    512515     */
    513516    /*uint32_t   special_interrupt_register;*/
     
    515518
    516519/**
    517  *  This variable is optional.  It is used on CPUs on which it is difficult
    518  *  to generate an "uninitialized" FP context.  It is filled in by
    519  *  @ref _CPU_Initialize and copied into the task's FP context area during
    520  *  @ref _CPU_Context_Initialize.
    521  *
    522  *  Port Specific Information:
    523  *
    524  *  XXX document implementation including references if appropriate
     520 * This variable is optional.  It is used on CPUs on which it is difficult
     521 * to generate an "uninitialized" FP context.  It is filled in by
     522 * @ref _CPU_Initialize and copied into the task's FP context area during
     523 * @ref _CPU_Context_Initialize.
     524 *
     525 * Port Specific Information:
     526 *
     527 * XXX document implementation including references if appropriate
    525528 */
    526529SCORE_EXTERN Context_Control_fp  _CPU_Null_fp_context;
    527530
    528 /**
    529  *  @defgroup CPUInterrupt Processor Dependent Interrupt Management
    530  *
    531  *  On some CPUs, RTEMS supports a software managed interrupt stack.
    532  *  This stack is allocated by the Interrupt Manager and the switch
    533  *  is performed in @ref _ISR_Handler.  These variables contain pointers
    534  *  to the lowest and highest addresses in the chunk of memory allocated
    535  *  for the interrupt stack.  Since it is unknown whether the stack
    536  *  grows up or down (in general), this give the CPU dependent
    537  *  code the option of picking the version it wants to use.
    538  *
    539  *  @note These two variables are required if the macro
    540  *        @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
    541  *
    542  *  Port Specific Information:
    543  *
    544  *  XXX document implementation including references if appropriate
     531/** @} */
     532
     533/**
     534 * @defgroup CPUInterrupt Processor Dependent Interrupt Management
     535 *
     536 * On some CPUs, RTEMS supports a software managed interrupt stack.
     537 * This stack is allocated by the Interrupt Manager and the switch
     538 * is performed in @ref _ISR_Handler.  These variables contain pointers
     539 * to the lowest and highest addresses in the chunk of memory allocated
     540 * for the interrupt stack.  Since it is unknown whether the stack
     541 * grows up or down (in general), this give the CPU dependent
     542 * code the option of picking the version it wants to use.
     543 *
     544 * @note These two variables are required if the macro
     545 *       @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
     546 *
     547 * Port Specific Information:
     548 *
     549 * XXX document implementation including references if appropriate
     550 *
     551 * @{
    545552 */
    546553
     
    556563
    557564/**
    558  *  @ingroup CPUContext
    559  *  The size of the floating point context area.  On some CPUs this
    560  *  will not be a "sizeof" because the format of the floating point
    561  *  area is not defined -- only the size is.  This is usually on
    562  *  CPUs with a "floating point save context" instruction.
    563  *
    564  *  Port Specific Information:
    565  *
    566  *  XXX document implementation including references if appropriate
     565 * @ingroup CPUContext
     566 * The size of the floating point context area.  On some CPUs this
     567 * will not be a "sizeof" because the format of the floating point
     568 * area is not defined -- only the size is.  This is usually on
     569 * CPUs with a "floating point save context" instruction.
     570 *
     571 * Port Specific Information:
     572 *
     573 * XXX document implementation including references if appropriate
    567574 */
    568575#define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
     
    571578
    572579/**
    573  *  Amount of extra stack (above minimum stack size) required by
    574  *  MPCI receive server thread.  Remember that in a multiprocessor
    575  *  system this thread must exist and be able to process all directives.
    576  *
    577  *  Port Specific Information:
    578  *
    579  *  XXX document implementation including references if appropriate
     580 * Amount of extra stack (above minimum stack size) required by
     581 * MPCI receive server thread.  Remember that in a multiprocessor
     582 * system this thread must exist and be able to process all directives.
     583 *
     584 * Port Specific Information:
     585 *
     586 * XXX document implementation including references if appropriate
    580587 */
    581588#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
    582589
    583590/**
    584  *  @ingroup CPUInterrupt
    585  *  This defines the number of entries in the @ref _ISR_Vector_table managed
    586  *  by RTEMS.
    587  *
    588  *  Port Specific Information:
    589  *
    590  *  XXX document implementation including references if appropriate
     591 * @ingroup CPUInterrupt
     592 * This defines the number of entries in the @ref _ISR_Vector_table managed
     593 * by RTEMS.
     594 *
     595 * Port Specific Information:
     596 *
     597 * XXX document implementation including references if appropriate
    591598 */
    592599#define CPU_INTERRUPT_NUMBER_OF_VECTORS      16
    593600
    594601/**
    595  *  @ingroup CPUInterrupt
    596  *  This defines the highest interrupt vector number for this port.
     602 * @ingroup CPUInterrupt
     603 * This defines the highest interrupt vector number for this port.
    597604 */
    598605#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER  (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
    599606
    600607/**
    601  *  @ingroup CPUInterrupt
    602  *  This is defined if the port has a special way to report the ISR nesting
    603  *  level.  Most ports maintain the variable @a _ISR_Nest_level.
     608 * @ingroup CPUInterrupt
     609 * This is defined if the port has a special way to report the ISR nesting
     610 * level.  Most ports maintain the variable @a _ISR_Nest_level.
    604611 */
    605612#define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
    606613
    607 /**
    608  *  @ingroup CPUContext
    609  *  Should be large enough to run all RTEMS tests.  This ensures
    610  *  that a "reasonable" small application should not have any problems.
    611  *
    612  *  Port Specific Information:
    613  *
    614  *  XXX document implementation including references if appropriate
     614/** @} */
     615
     616/**
     617 * @ingroup CPUContext
     618 * Should be large enough to run all RTEMS tests.  This ensures
     619 * that a "reasonable" small application should not have any problems.
     620 *
     621 * Port Specific Information:
     622 *
     623 * XXX document implementation including references if appropriate
    615624 */
    616625#define CPU_STACK_MINIMUM_SIZE          (1024*8)
     
    619628
    620629/**
    621  *  CPU's worst alignment requirement for data types on a byte boundary.  This
    622  *  alignment does not take into account the requirements for the stack.
    623  *
    624  *  Port Specific Information:
    625  *
    626  *  XXX document implementation including references if appropriate
     630 * CPU's worst alignment requirement for data types on a byte boundary.  This
     631 * alignment does not take into account the requirements for the stack.
     632 *
     633 * Port Specific Information:
     634 *
     635 * XXX document implementation including references if appropriate
    627636 */
    628637#define CPU_ALIGNMENT              8
    629638
    630639/**
    631  *  This number corresponds to the byte alignment requirement for the
    632  *  heap handler.  This alignment requirement may be stricter than that
    633  *  for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
    634  *  common for the heap to follow the same alignment requirement as
    635  *  @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
    636  *  the heap, then this should be set to @ref CPU_ALIGNMENT.
    637  *
    638  *  @note  This does not have to be a power of 2 although it should be
    639  *         a multiple of 2 greater than or equal to 2.  The requirement
    640  *         to be a multiple of 2 is because the heap uses the least
    641  *         significant field of the front and back flags to indicate
    642  *         that a block is in use or free.  So you do not want any odd
    643  *         length blocks really putting length data in that bit.
    644  *
    645  *         On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
    646  *         have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
    647  *         elements allocated from the heap meet all restrictions.
    648  *
    649  *  Port Specific Information:
    650  *
    651  *  XXX document implementation including references if appropriate
     640 * This number corresponds to the byte alignment requirement for the
     641 * heap handler.  This alignment requirement may be stricter than that
     642 * for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
     643 * common for the heap to follow the same alignment requirement as
     644 * @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
     645 * the heap, then this should be set to @ref CPU_ALIGNMENT.
     646 *
     647 * @note  This does not have to be a power of 2 although it should be
     648 *        a multiple of 2 greater than or equal to 2.  The requirement
     649 *        to be a multiple of 2 is because the heap uses the least
     650 *        significant field of the front and back flags to indicate
     651 *        that a block is in use or free.  So you do not want any odd
     652 *        length blocks really putting length data in that bit.
     653 *
     654 *        On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
     655 *        have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
     656 *        elements allocated from the heap meet all restrictions.
     657 *
     658 * Port Specific Information:
     659 *
     660 * XXX document implementation including references if appropriate
    652661 */
    653662#define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
    654663
    655664/**
    656  *  This number corresponds to the byte alignment requirement for memory
    657  *  buffers allocated by the partition manager.  This alignment requirement
    658  *  may be stricter than that for the data types alignment specified by
    659  *  @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
    660  *  alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
    661  *  strict enough for the partition, then this should be set to
    662  *  @ref CPU_ALIGNMENT.
    663  *
    664  *  @note  This does not have to be a power of 2.  It does have to
    665  *         be greater or equal to than @ref CPU_ALIGNMENT.
    666  *
    667  *  Port Specific Information:
    668  *
    669  *  XXX document implementation including references if appropriate
     665 * This number corresponds to the byte alignment requirement for memory
     666 * buffers allocated by the partition manager.  This alignment requirement
     667 * may be stricter than that for the data types alignment specified by
     668 * @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
     669 * alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
     670 * strict enough for the partition, then this should be set to
     671 * @ref CPU_ALIGNMENT.
     672 *
     673 * @note  This does not have to be a power of 2.  It does have to
     674 *        be greater or equal to than @ref CPU_ALIGNMENT.
     675 *
     676 * Port Specific Information:
     677 *
     678 * XXX document implementation including references if appropriate
    670679 */
    671680#define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
    672681
    673682/**
    674  *  This number corresponds to the byte alignment requirement for the
    675  *  stack.  This alignment requirement may be stricter than that for the
    676  *  data types alignment specified by @ref CPU_ALIGNMENT.  If the
    677  *  @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
    678  *  set to 0.
    679  *
    680  *  @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
    681  *
    682  *  Port Specific Information:
    683  *
    684  *  XXX document implementation including references if appropriate
     683 * This number corresponds to the byte alignment requirement for the
     684 * stack.  This alignment requirement may be stricter than that for the
     685 * data types alignment specified by @ref CPU_ALIGNMENT.  If the
     686 * @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
     687 * set to 0.
     688 *
     689 * @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
     690 *
     691 * Port Specific Information:
     692 *
     693 * XXX document implementation including references if appropriate
    685694 */
    686695#define CPU_STACK_ALIGNMENT        8
     
    691700
    692701/**
    693  *  @ingroup CPUInterrupt
    694  *  Support routine to initialize the RTEMS vector table after it is allocated.
    695  *
    696  *  Port Specific Information:
    697  *
    698  *  XXX document implementation including references if appropriate
     702 * @addtogroup CPUInterrupt
     703 *
     704 * @{
     705 */
     706
     707/**
     708 * Support routine to initialize the RTEMS vector table after it is allocated.
     709 *
     710 * Port Specific Information:
     711 *
     712 * XXX document implementation including references if appropriate
    699713 */
    700714#define _CPU_Initialize_vectors()
    701715
    702716/**
    703  *  @ingroup CPUInterrupt
    704  *  Disable all interrupts for an RTEMS critical section.  The previous
    705  *  level is returned in @a _isr_cookie.
    706  *
    707  *  @param[out] _isr_cookie will contain the previous level cookie
    708  *
    709  *  Port Specific Information:
    710  *
    711  *  XXX document implementation including references if appropriate
     717 * Disable all interrupts for an RTEMS critical section.  The previous
     718 * level is returned in @a _isr_cookie.
     719 *
     720 * @param[out] _isr_cookie will contain the previous level cookie
     721 *
     722 * Port Specific Information:
     723 *
     724 * XXX document implementation including references if appropriate
    712725 */
    713726#define _CPU_ISR_Disable( _level ) \
     
    718731
    719732/**
    720  *  @ingroup CPUInterrupt
    721  *  Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
    722  *  This indicates the end of an RTEMS critical section.  The parameter
    723  *  @a _isr_cookie is not modified.
    724  *
    725  *  @param[in] _isr_cookie contain the previous level cookie
    726  *
    727  *  Port Specific Information:
    728  *
    729  *  XXX document implementation including references if appropriate
     733 * Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
     734 * This indicates the end of an RTEMS critical section.  The parameter
     735 * @a _isr_cookie is not modified.
     736 *
     737 * @param[in] _isr_cookie contain the previous level cookie
     738 *
     739 * Port Specific Information:
     740 *
     741 * XXX document implementation including references if appropriate
    730742 */
    731743#define _CPU_ISR_Enable( _level ) { \
     
    734746
    735747/**
    736  *  @ingroup CPUInterrupt
    737  *  This temporarily restores the interrupt to @a _isr_cookie before immediately
    738  *  disabling them again.  This is used to divide long RTEMS critical
    739  *  sections into two or more parts.  The parameter @a _isr_cookie is not
    740  *  modified.
    741  *
    742  *  @param[in] _isr_cookie contain the previous level cookie
    743  *
    744  *  Port Specific Information:
    745  *
    746  *  XXX document implementation including references if appropriate
     748 * This temporarily restores the interrupt to @a _isr_cookie before immediately
     749 * disabling them again.  This is used to divide long RTEMS critical
     750 * sections into two or more parts.  The parameter @a _isr_cookie is not
     751 * modified.
     752 *
     753 * @param[in] _isr_cookie contain the previous level cookie
     754 *
     755 * Port Specific Information:
     756 *
     757 * XXX document implementation including references if appropriate
    747758 */
    748759#define _CPU_ISR_Flash( _level ) { \
     
    752763
    753764/**
    754  *  @ingroup CPUInterrupt
    755  *
    756  *  This routine and @ref _CPU_ISR_Get_level
    757  *  Map the interrupt level in task mode onto the hardware that the CPU
    758  *  actually provides.  Currently, interrupt levels which do not
    759  *  map onto the CPU in a generic fashion are undefined.  Someday,
    760  *  it would be nice if these were "mapped" by the application
    761  *  via a callout.  For example, m68k has 8 levels 0 - 7, levels
    762  *  8 - 255 would be available for bsp/application specific meaning.
    763  *  This could be used to manage a programmable interrupt controller
    764  *  via the rtems_task_mode directive.
    765  *
    766  *  Port Specific Information:
    767  *
    768  *  XXX document implementation including references if appropriate
     765 * This routine and @ref _CPU_ISR_Get_level
     766 * Map the interrupt level in task mode onto the hardware that the CPU
     767 * actually provides.  Currently, interrupt levels which do not
     768 * map onto the CPU in a generic fashion are undefined.  Someday,
     769 * it would be nice if these were "mapped" by the application
     770 * via a callout.  For example, m68k has 8 levels 0 - 7, levels
     771 * 8 - 255 would be available for bsp/application specific meaning.
     772 * This could be used to manage a programmable interrupt controller
     773 * via the rtems_task_mode directive.
     774 *
     775 * Port Specific Information:
     776 *
     777 * XXX document implementation including references if appropriate
    769778 */
    770779#define _CPU_ISR_Set_level( _new_level ) \
     
    776785
    777786/**
    778  *  @ingroup CPUInterrupt
    779  *  Return the current interrupt disable level for this task in
    780  *  the format used by the interrupt level portion of the task mode.
    781  *
    782  *  @note This routine usually must be implemented as a subroutine.
    783  *
    784  *  Port Specific Information:
    785  *
    786  *  XXX document implementation including references if appropriate
     787 * Return the current interrupt disable level for this task in
     788 * the format used by the interrupt level portion of the task mode.
     789 *
     790 * @note This routine usually must be implemented as a subroutine.
     791 *
     792 * Port Specific Information:
     793 *
     794 * XXX document implementation including references if appropriate
    787795 */
    788796uint32_t   _CPU_ISR_Get_level( void );
     
    790798/* end of ISR handler macros */
    791799
     800/** @} */
     801
    792802/* Context handler macros */
    793803
    794804/**
    795  *  @ingroup CPUContext
    796  *  Initialize the context to a state suitable for starting a
    797  *  task after a context restore operation.  Generally, this
    798  *  involves:
    799  *
    800  *     - setting a starting address
    801  *     - preparing the stack
    802  *     - preparing the stack and frame pointers
    803  *     - setting the proper interrupt level in the context
    804  *     - initializing the floating point context
    805  *
    806  *  This routine generally does not set any unnecessary register
    807  *  in the context.  The state of the "general data" registers is
    808  *  undefined at task start time.
    809  *
    810  *  @param[in] _the_context is the context structure to be initialized
    811  *  @param[in] _stack_base is the lowest physical address of this task's stack
    812  *  @param[in] _size is the size of this task's stack
    813  *  @param[in] _isr is the interrupt disable level
    814  *  @param[in] _entry_point is the thread's entry point.  This is
    815  *         always @a _Thread_Handler
    816  *  @param[in] _is_fp is TRUE if the thread is to be a floating
    817  *        point thread.  This is typically only used on CPUs where the
    818  *        FPU may be easily disabled by software such as on the SPARC
    819  *        where the PSR contains an enable FPU bit.
    820  *
    821  *  Port Specific Information:
    822  *
    823  *  See implementation in cpu.c
     805 * @ingroup CPUContext
     806 * Initialize the context to a state suitable for starting a
     807 * task after a context restore operation.  Generally, this
     808 * involves:
     809 *
     810 *    - setting a starting address
     811 *    - preparing the stack
     812 *    - preparing the stack and frame pointers
     813 *    - setting the proper interrupt level in the context
     814 *    - initializing the floating point context
     815 *
     816 * This routine generally does not set any unnecessary register
     817 * in the context.  The state of the "general data" registers is
     818 * undefined at task start time.
     819 *
     820 * @param[in] _the_context is the context structure to be initialized
     821 * @param[in] _stack_base is the lowest physical address of this task's stack
     822 * @param[in] _size is the size of this task's stack
     823 * @param[in] _isr is the interrupt disable level
     824 * @param[in] _entry_point is the thread's entry point.  This is
     825 *        always @a _Thread_Handler
     826 * @param[in] _is_fp is TRUE if the thread is to be a floating
     827 *       point thread.  This is typically only used on CPUs where the
     828 *       FPU may be easily disabled by software such as on the SPARC
     829 *       where the PSR contains an enable FPU bit.
     830 *
     831 * Port Specific Information:
     832 *
     833 * See implementation in cpu.c
    824834 */
    825835void _CPU_Context_Initialize(
     
    833843
    834844/**
    835  *  This routine is responsible for somehow restarting the currently
    836  *  executing task.  If you are lucky, then all that is necessary
    837  *  is restoring the context.  Otherwise, there will need to be
    838  *  a special assembly routine which does something special in this
    839  *  case.  For many ports, simply adding a label to the restore path
    840  *  of @ref _CPU_Context_switch will work.  On other ports, it may be
    841  *  possibly to load a few arguments and jump to the restore path. It will
    842  *  not work if restarting self conflicts with the stack frame
    843  *  assumptions of restoring a context.
    844  *
    845  *  Port Specific Information:
    846  *
    847  *  XXX document implementation including references if appropriate
     845 * This routine is responsible for somehow restarting the currently
     846 * executing task.  If you are lucky, then all that is necessary
     847 * is restoring the context.  Otherwise, there will need to be
     848 * a special assembly routine which does something special in this
     849 * case.  For many ports, simply adding a label to the restore path
     850 * of @ref _CPU_Context_switch will work.  On other ports, it may be
     851 * possibly to load a few arguments and jump to the restore path. It will
     852 * not work if restarting self conflicts with the stack frame
     853 * assumptions of restoring a context.
     854 *
     855 * Port Specific Information:
     856 *
     857 * XXX document implementation including references if appropriate
    848858 */
    849859#define _CPU_Context_Restart_self( _the_context ) \
     
    851861
    852862/**
    853  *  @ingroup CPUContext
    854  *  The purpose of this macro is to allow the initial pointer into
    855  *  a floating point context area (used to save the floating point
    856  *  context) to be at an arbitrary place in the floating point
    857  *  context area.
    858  *
    859  *  This is necessary because some FP units are designed to have
    860  *  their context saved as a stack which grows into lower addresses.
    861  *  Other FP units can be saved by simply moving registers into offsets
    862  *  from the base of the context area.  Finally some FP units provide
    863  *  a "dump context" instruction which could fill in from high to low
    864  *  or low to high based on the whim of the CPU designers.
    865  *
    866  *  @param[in] _base is the lowest physical address of the floating point
    867  *         context area
    868  *  @param[in] _offset is the offset into the floating point area
    869  *
    870  *  Port Specific Information:
    871  *
    872  *  XXX document implementation including references if appropriate
     863 * @ingroup CPUContext
     864 * The purpose of this macro is to allow the initial pointer into
     865 * a floating point context area (used to save the floating point
     866 * context) to be at an arbitrary place in the floating point
     867 * context area.
     868 *
     869 * This is necessary because some FP units are designed to have
     870 * their context saved as a stack which grows into lower addresses.
     871 * Other FP units can be saved by simply moving registers into offsets
     872 * from the base of the context area.  Finally some FP units provide
     873 * a "dump context" instruction which could fill in from high to low
     874 * or low to high based on the whim of the CPU designers.
     875 *
     876 * @param[in] _base is the lowest physical address of the floating point
     877 *        context area
     878 * @param[in] _offset is the offset into the floating point area
     879 *
     880 * Port Specific Information:
     881 *
     882 * XXX document implementation including references if appropriate
    873883 */
    874884#define _CPU_Context_Fp_start( _base, _offset ) \
     
    876886
    877887/**
    878  *  This routine initializes the FP context area passed to it to.
    879  *  There are a few standard ways in which to initialize the
    880  *  floating point context.  The code included for this macro assumes
    881  *  that this is a CPU in which a "initial" FP context was saved into
    882  *  @a _CPU_Null_fp_context and it simply copies it to the destination
    883  *  context passed to it.
    884  *
    885  *  Other floating point context save/restore models include:
    886  *    -# not doing anything, and
    887  *    -# putting a "null FP status word" in the correct place in the FP context.
    888  *
    889  *  @param[in] _destination is the floating point context area
    890  *
    891  *  Port Specific Information:
    892  *
    893  *  XXX document implementation including references if appropriate
     888 * This routine initializes the FP context area passed to it to.
     889 * There are a few standard ways in which to initialize the
     890 * floating point context.  The code included for this macro assumes
     891 * that this is a CPU in which a "initial" FP context was saved into
     892 * @a _CPU_Null_fp_context and it simply copies it to the destination
     893 * context passed to it.
     894 *
     895 * Other floating point context save/restore models include:
     896 *   -# not doing anything, and
     897 *   -# putting a "null FP status word" in the correct place in the FP context.
     898 *
     899 * @param[in] _destination is the floating point context area
     900 *
     901 * Port Specific Information:
     902 *
     903 * XXX document implementation including references if appropriate
    894904 */
    895905#define _CPU_Context_Initialize_fp( _destination ) \
     
    903913
    904914/**
    905  *  This routine copies _error into a known place -- typically a stack
    906  *  location or a register, optionally disables interrupts, and
    907  *  halts/stops the CPU.
    908  *
    909  *  Port Specific Information:
    910  *
    911  *  XXX document implementation including references if appropriate
     915 * This routine copies _error into a known place -- typically a stack
     916 * location or a register, optionally disables interrupts, and
     917 * halts/stops the CPU.
     918 *
     919 * Port Specific Information:
     920 *
     921 * XXX document implementation including references if appropriate
    912922 */
    913923#define _CPU_Fatal_halt( _error ) \
     
    926936
    927937/**
    928  *  @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
    929  *
    930  *  This set of routines are used to implement fast searches for
    931  *  the most important ready task.
    932  */
    933 
    934 /**
    935  *  @ingroup CPUBitfield
    936  *  This definition is set to TRUE if the port uses the generic bitfield
    937  *  manipulation implementation.
     938 * @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
     939 *
     940 * This set of routines are used to implement fast searches for
     941 * the most important ready task.
     942 *
     943 * @{
     944 */
     945
     946/**
     947 * This definition is set to TRUE if the port uses the generic bitfield
     948 * manipulation implementation.
    938949 */
    939950#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
    940951
    941952/**
    942  *  @ingroup CPUBitfield
    943  *  This definition is set to TRUE if the port uses the data tables provided
    944  *  by the generic bitfield manipulation implementation.
    945  *  This can occur when actually using the generic bitfield manipulation
    946  *  implementation or when implementing the same algorithm in assembly
    947  *  language for improved performance.  It is unlikely that a port will use
    948  *  the data if it has a bitfield scan instruction.
     953 * This definition is set to TRUE if the port uses the data tables provided
     954 * by the generic bitfield manipulation implementation.
     955 * This can occur when actually using the generic bitfield manipulation
     956 * implementation or when implementing the same algorithm in assembly
     957 * language for improved performance.  It is unlikely that a port will use
     958 * the data if it has a bitfield scan instruction.
    949959 */
    950960#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
    951961
    952962/**
    953  *  @ingroup CPUBitfield
    954  *  This routine sets @a _output to the bit number of the first bit
    955  *  set in @a _value.  @a _value is of CPU dependent type
    956  *  @a Priority_bit_map_Control.  This type may be either 16 or 32 bits
    957  *  wide although only the 16 least significant bits will be used.
    958  *
    959  *  There are a number of variables in using a "find first bit" type
    960  *  instruction.
    961  *
    962  *    -# What happens when run on a value of zero?
    963  *    -# Bits may be numbered from MSB to LSB or vice-versa.
    964  *    -# The numbering may be zero or one based.
    965  *    -# The "find first bit" instruction may search from MSB or LSB.
    966  *
    967  *  RTEMS guarantees that (1) will never happen so it is not a concern.
    968  *  (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
    969  *  @ref _CPU_Priority_bits_index.  These three form a set of routines
    970  *  which must logically operate together.  Bits in the _value are
    971  *  set and cleared based on masks built by @ref _CPU_Priority_Mask.
    972  *  The basic major and minor values calculated by @ref _Priority_Major
    973  *  and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
    974  *  to properly range between the values returned by the "find first bit"
    975  *  instruction.  This makes it possible for @ref _Priority_Get_highest to
    976  *  calculate the major and directly index into the minor table.
    977  *  This mapping is necessary to ensure that 0 (a high priority major/minor)
    978  *  is the first bit found.
    979  *
    980  *  This entire "find first bit" and mapping process depends heavily
    981  *  on the manner in which a priority is broken into a major and minor
    982  *  components with the major being the 4 MSB of a priority and minor
    983  *  the 4 LSB.  Thus (0 << 4) + 0 corresponds to priority 0 -- the highest
    984  *  priority.  And (15 << 4) + 14 corresponds to priority 254 -- the next
    985  *  to the lowest priority.
    986  *
    987  *  If your CPU does not have a "find first bit" instruction, then
    988  *  there are ways to make do without it.  Here are a handful of ways
    989  *  to implement this in software:
     963 * This routine sets @a _output to the bit number of the first bit
     964 * set in @a _value.  @a _value is of CPU dependent type
     965 * @a Priority_bit_map_Control.  This type may be either 16 or 32 bits
     966 * wide although only the 16 least significant bits will be used.
     967 *
     968 * There are a number of variables in using a "find first bit" type
     969 * instruction.
     970 *
     971 *   -# What happens when run on a value of zero?
     972 *   -# Bits may be numbered from MSB to LSB or vice-versa.
     973 *   -# The numbering may be zero or one based.
     974 *   -# The "find first bit" instruction may search from MSB or LSB.
     975 *
     976 * RTEMS guarantees that (1) will never happen so it is not a concern.
     977 * (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
     978 * @ref _CPU_Priority_bits_index.  These three form a set of routines
     979 * which must logically operate together.  Bits in the _value are
     980 * set and cleared based on masks built by @ref _CPU_Priority_Mask.
     981 * The basic major and minor values calculated by @ref _Priority_Major
     982 * and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
     983 * to properly range between the values returned by the "find first bit"
     984 * instruction.  This makes it possible for @ref _Priority_Get_highest to
     985 * calculate the major and directly index into the minor table.
     986 * This mapping is necessary to ensure that 0 (a high priority major/minor)
     987 * is the first bit found.
     988 *
     989 * This entire "find first bit" and mapping process depends heavily
     990 * on the manner in which a priority is broken into a major and minor
     991 * components with the major being the 4 MSB of a priority and minor
     992 * the 4 LSB.  Thus (0 << 4) + 0 corresponds to priority 0 -- the highest
     993 * priority.  And (15 << 4) + 14 corresponds to priority 254 -- the next
     994 * to the lowest priority.
     995 *
     996 * If your CPU does not have a "find first bit" instruction, then
     997 * there are ways to make do without it.  Here are a handful of ways
     998 * to implement this in software:
    990999 *
    9911000@verbatim
     
    10041013@endverbatim
    10051014
    1006  *    where bit_set_table[ 16 ] has values which indicate the first
    1007  *      bit set
    1008  *
    1009  *  @param[in] _value is the value to be scanned
    1010  *  @param[in] _output is the first bit set
    1011  *
    1012  *  Port Specific Information:
    1013  *
    1014  *  XXX document implementation including references if appropriate
     1015 *   where bit_set_table[ 16 ] has values which indicate the first
     1016 *     bit set
     1017 *
     1018 * @param[in] _value is the value to be scanned
     1019 * @param[in] _output is the first bit set
     1020 *
     1021 * Port Specific Information:
     1022 *
     1023 * XXX document implementation including references if appropriate
    10151024 */
    10161025
     
    10251034/* end of Bitfield handler macros */
    10261035
    1027 /**
    1028  *  This routine builds the mask which corresponds to the bit fields
    1029  *  as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
    1030  *  for that routine.
    1031  *
    1032  *  Port Specific Information:
    1033  *
    1034  *  XXX document implementation including references if appropriate
     1036/** @} */
     1037
     1038/**
     1039 * This routine builds the mask which corresponds to the bit fields
     1040 * as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
     1041 * for that routine.
     1042 *
     1043 * Port Specific Information:
     1044 *
     1045 * XXX document implementation including references if appropriate
    10351046 */
    10361047#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    10421053
    10431054/**
    1044  *  @ingroup CPUBitfield
    1045  *  This routine translates the bit numbers returned by
    1046  *  @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
    1047  *  a major or minor component of a priority.  See the discussion
    1048  *  for that routine.
    1049  *
    1050  *  @param[in] _priority is the major or minor number to translate
    1051  *
    1052  *  Port Specific Information:
    1053  *
    1054  *  XXX document implementation including references if appropriate
     1055 * @ingroup CPUBitfield
     1056 * This routine translates the bit numbers returned by
     1057 * @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
     1058 * a major or minor component of a priority.  See the discussion
     1059 * for that routine.
     1060 *
     1061 * @param[in] _priority is the major or minor number to translate
     1062 *
     1063 * Port Specific Information:
     1064 *
     1065 * XXX document implementation including references if appropriate
    10551066 */
    10561067#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    10661077
    10671078/**
    1068  *  @brief CPU Initialize
    1069  *  This routine performs CPU dependent initialization.
    1070  *
    1071  *  Port Specific Information:
    1072  *
    1073  *  XXX document implementation including references if appropriate
     1079 * @brief CPU initialize.
     1080 * This routine performs CPU dependent initialization.
     1081 *
     1082 * Port Specific Information:
     1083 *
     1084 * XXX document implementation including references if appropriate
    10741085 */
    10751086void _CPU_Initialize(void);
    10761087
    10771088/**
    1078  *  @ingroup CPUInterrupt
    1079  *  This routine installs a "raw" interrupt handler directly into the
    1080  *  processor's vector table.
    1081  *
    1082  *  @param[in] vector is the vector number
    1083  *  @param[in] new_handler is the raw ISR handler to install
    1084  *  @param[in] old_handler is the previously installed ISR Handler
    1085  *
    1086  *  Port Specific Information:
    1087  *
    1088  *  XXX document implementation including references if appropriate
     1089 * @ingroup CPUInterrupt
     1090 * This routine installs a "raw" interrupt handler directly into the
     1091 * processor's vector table.
     1092 *
     1093 * @param[in] vector is the vector number
     1094 * @param[in] new_handler is the raw ISR handler to install
     1095 * @param[in] old_handler is the previously installed ISR Handler
     1096 *
     1097 * Port Specific Information:
     1098 *
     1099 * XXX document implementation including references if appropriate
    10891100 */
    10901101void _CPU_ISR_install_raw_handler(
     
    10951106
    10961107/**
    1097  *  @ingroup CPUInterrupt
    1098  *  This routine installs an interrupt vector.
    1099  *
    1100  *  @param[in] vector is the vector number
    1101  *  @param[in] new_handler is the RTEMS ISR handler to install
    1102  *  @param[in] old_handler is the previously installed ISR Handler
    1103  *
    1104  *  Port Specific Information:
    1105  *
    1106  *  XXX document implementation including references if appropriate
     1108 * @ingroup CPUInterrupt
     1109 * This routine installs an interrupt vector.
     1110 *
     1111 * @param[in] vector is the vector number
     1112 * @param[in] new_handler is the RTEMS ISR handler to install
     1113 * @param[in] old_handler is the previously installed ISR Handler
     1114 *
     1115 * Port Specific Information:
     1116 *
     1117 * XXX document implementation including references if appropriate
    11071118 */
    11081119void _CPU_ISR_install_vector(
     
    11131124
    11141125/**
    1115  *  @ingroup CPUInterrupt
    1116  *  This routine installs the hardware interrupt stack pointer.
    1117  *
    1118  *  @note  It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK
    1119  *         is TRUE.
    1120  *
    1121  *  Port Specific Information:
    1122  *
    1123  *  XXX document implementation including references if appropriate
     1126 * @ingroup CPUInterrupt
     1127 * This routine installs the hardware interrupt stack pointer.
     1128 *
     1129 * @note  It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK
     1130 *        is TRUE.
     1131 *
     1132 * Port Specific Information:
     1133 *
     1134 * XXX document implementation including references if appropriate
    11241135 */
    11251136void _CPU_Install_interrupt_stack( void );
    11261137
    11271138/**
    1128  *  This routine is the CPU dependent IDLE thread body.
    1129  *
    1130  *  @note  It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY
    1131  *         is TRUE.
    1132  *
    1133  *  Port Specific Information:
    1134  *
    1135  *  XXX document implementation including references if appropriate
     1139 * This routine is the CPU dependent IDLE thread body.
     1140 *
     1141 * @note  It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY
     1142 *        is TRUE.
     1143 *
     1144 * Port Specific Information:
     1145 *
     1146 * XXX document implementation including references if appropriate
    11361147 */
    11371148void *_CPU_Thread_Idle_body( uintptr_t ignored );
    11381149
    11391150/**
    1140  *  @ingroup CPUContext
    1141  *  This routine switches from the run context to the heir context.
    1142  *
    1143  *  @param[in] run points to the context of the currently executing task
    1144  *  @param[in] heir points to the context of the heir task
    1145  *
    1146  *  Port Specific Information:
    1147  *
    1148  *  XXX document implementation including references if appropriate
     1151 * @addtogroup CPUContext
     1152 *
     1153 * @{
     1154 */
     1155
     1156/**
     1157 * This routine switches from the run context to the heir context.
     1158 *
     1159 * @param[in] run points to the context of the currently executing task
     1160 * @param[in] heir points to the context of the heir task
     1161 *
     1162 * Port Specific Information:
     1163 *
     1164 * XXX document implementation including references if appropriate
    11491165 */
    11501166void _CPU_Context_switch(
     
    11541170
    11551171/**
    1156  *  @ingroup CPUContext
    1157  *  This routine is generally used only to restart self in an
    1158  *  efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
    1159  *
    1160  *  @param[in] new_context points to the context to be restored.
    1161  *
    1162  *  @note May be unnecessary to reload some registers.
    1163  *
    1164  *  Port Specific Information:
    1165  *
    1166  *  XXX document implementation including references if appropriate
     1172 * This routine is generally used only to restart self in an
     1173 * efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
     1174 *
     1175 * @param[in] new_context points to the context to be restored.
     1176 *
     1177 * @note May be unnecessary to reload some registers.
     1178 *
     1179 * Port Specific Information:
     1180 *
     1181 * XXX document implementation including references if appropriate
    11671182 */
    11681183void _CPU_Context_restore(
     
    11711186
    11721187/**
    1173  *  @ingroup CPUContext
    1174  *  This routine saves the floating point context passed to it.
    1175  *
    1176  *  @param[in] fp_context_ptr is a pointer to a pointer to a floating
    1177  *  point context area
    1178  *
    1179  *  @return on output @a *fp_context_ptr will contain the address that
    1180  *  should be used with @ref _CPU_Context_restore_fp to restore this context.
    1181  *
    1182  *  Port Specific Information:
    1183  *
    1184  *  XXX document implementation including references if appropriate
     1188 * This routine saves the floating point context passed to it.
     1189 *
     1190 * @param[in] fp_context_ptr is a pointer to a pointer to a floating
     1191 * point context area
     1192 *
     1193 * @return on output @a *fp_context_ptr will contain the address that
     1194 * should be used with @ref _CPU_Context_restore_fp to restore this context.
     1195 *
     1196 * Port Specific Information:
     1197 *
     1198 * XXX document implementation including references if appropriate
    11851199 */
    11861200void _CPU_Context_save_fp(
     
    11891203
    11901204/**
    1191  *  @ingroup CPUContext
    1192  *  This routine restores the floating point context passed to it.
    1193  *
    1194  *  @param[in] fp_context_ptr is a pointer to a pointer to a floating
    1195  *  point context area to restore
    1196  *
    1197  *  @return on output @a *fp_context_ptr will contain the address that
    1198  *  should be used with @ref _CPU_Context_save_fp to save this context.
    1199  *
    1200  *  Port Specific Information:
    1201  *
    1202  *  XXX document implementation including references if appropriate
     1205 * This routine restores the floating point context passed to it.
     1206 *
     1207 * @param[in] fp_context_ptr is a pointer to a pointer to a floating
     1208 * point context area to restore
     1209 *
     1210 * @return on output @a *fp_context_ptr will contain the address that
     1211 * should be used with @ref _CPU_Context_save_fp to save this context.
     1212 *
     1213 * Port Specific Information:
     1214 *
     1215 * XXX document implementation including references if appropriate
    12031216 */
    12041217void _CPU_Context_restore_fp(
     
    12061219);
    12071220
     1221/** @} */
     1222
    12081223/* FIXME */
    12091224typedef CPU_Interrupt_frame CPU_Exception_frame;
     
    12121227
    12131228/**
    1214  *  @ingroup CPUEndian
    1215  *  The following routine swaps the endian format of an unsigned int.
    1216  *  It must be static because it is referenced indirectly.
    1217  *
    1218  *  This version will work on any processor, but if there is a better
    1219  *  way for your CPU PLEASE use it.  The most common way to do this is to:
    1220  *
    1221  *     swap least significant two bytes with 16-bit rotate
    1222  *     swap upper and lower 16-bits
    1223  *     swap most significant two bytes with 16-bit rotate
    1224  *
    1225  *  Some CPUs have special instructions which swap a 32-bit quantity in
    1226  *  a single instruction (e.g. i486).  It is probably best to avoid
    1227  *  an "endian swapping control bit" in the CPU.  One good reason is
    1228  *  that interrupts would probably have to be disabled to ensure that
    1229  *  an interrupt does not try to access the same "chunk" with the wrong
    1230  *  endian.  Another good reason is that on some CPUs, the endian bit
    1231  *  endianness for ALL fetches -- both code and data -- so the code
    1232  *  will be fetched incorrectly.
    1233  *
    1234  *  @param[in] value is the value to be swapped
    1235  *  @return the value after being endian swapped
    1236  *
    1237  *  Port Specific Information:
    1238  *
    1239  *  XXX document implementation including references if appropriate
     1229 * @ingroup CPUEndian
     1230 * The following routine swaps the endian format of an unsigned int.
     1231 * It must be static because it is referenced indirectly.
     1232 *
     1233 * This version will work on any processor, but if there is a better
     1234 * way for your CPU PLEASE use it.  The most common way to do this is to:
     1235 *
     1236 *    swap least significant two bytes with 16-bit rotate
     1237 *    swap upper and lower 16-bits
     1238 *    swap most significant two bytes with 16-bit rotate
     1239 *
     1240 * Some CPUs have special instructions which swap a 32-bit quantity in
     1241 * a single instruction (e.g. i486).  It is probably best to avoid
     1242 * an "endian swapping control bit" in the CPU.  One good reason is
     1243 * that interrupts would probably have to be disabled to ensure that
     1244 * an interrupt does not try to access the same "chunk" with the wrong
     1245 * endian.  Another good reason is that on some CPUs, the endian bit
     1246 * endianness for ALL fetches -- both code and data -- so the code
     1247 * will be fetched incorrectly.
     1248 *
     1249 * @param[in] value is the value to be swapped
     1250 * @return the value after being endian swapped
     1251 *
     1252 * Port Specific Information:
     1253 *
     1254 * XXX document implementation including references if appropriate
    12401255 */
    12411256static inline uint32_t CPU_swap_u32(
     
    12551270
    12561271/**
    1257  *  @ingroup CPUEndian
    1258  *  This routine swaps a 16 bir quantity.
    1259  *
    1260  *  @param[in] value is the value to be swapped
    1261  *  @return the value after being endian swapped
     1272 * @ingroup CPUEndian
     1273 * This routine swaps a 16 bir quantity.
     1274 *
     1275 * @param[in] value is the value to be swapped
     1276 * @return the value after being endian swapped
    12621277 */
    12631278#define CPU_swap_u16( value ) \
  • cpukit/score/cpu/bfin/rtems/score/cpu_asm.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/cpu_asm.h
     2 * @file
     3 *
     4 * @brief Blackfin Assembly File
     5 *
     6 * Defines a couple of Macros used in cpu_asm.S
    37 */
    48
    59/*
    6  *  Defines a couple of Macros used in cpu_asm.S
    7  *
    810 *  COPYRIGHT (c) 2006 by Atos Automacao Industrial Ltda.
    911 *             written by Alain Schaefer <alain.schaefer@easc.ch>
  • cpukit/score/cpu/bfin/rtems/score/types.h

    rf597cc1 r4f5740f  
     1/**
     2 * @file
     3 *
     4 * @brief Blackfin CPU Type Definitions
     5 *
     6 * This include file contains type definitions pertaining to the
     7 * Blackfin processor family.
     8 */
     9
    110/*
    2  *  This include file contains type definitions pertaining to the
    3  *  Blackfin processor family.
    4  *
    511 *  COPYRIGHT (c) 1989-2006.
    612 *  On-Line Applications Research Corporation (OAR).
  • cpukit/score/cpu/nios2/rtems/score/cpu.h

    rf597cc1 r4f5740f  
     1/**
     2 * @file
     3 *
     4 * @brief Altera Nios II CPU Department Source
     5 */
     6
    17/*
    28 *  Copyright (c) 2011 embedded brains GmbH
     
    254260 *
    255261 * This flash code is optimal for all Nios II configurations.  The rdctl does
    256  * not flush the pipeline and has only a late result penalty.  The wrctl on the
    257  * other hand leads to a pipeline flush.
     262 * not flush the pipeline and has only a late result penalty.  The wrctl on
     263 * the other hand leads to a pipeline flush.
    258264 */
    259265#define _CPU_ISR_Flash( _isr_cookie ) \
     
    320326
    321327/**
    322  * @brief CPU Initialize
    323  *
     328 * @brief CPU initialization.
    324329 */
    325330void _CPU_Initialize( void );
    326331
    327332/**
    328  * @brief CPU ISR Install Raw Handler
    329  *
     333 * @brief CPU ISR install raw handler.
    330334 */
    331335void _CPU_ISR_install_raw_handler(
     
    336340
    337341/**
    338  * @brief CPU ISR Install Vector.
    339  *
     342 * @brief CPU ISR install vector.
    340343 */
    341344void _CPU_ISR_install_vector(
  • cpukit/score/cpu/nios2/rtems/score/cpu_asm.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/cpu_asm.h
     2 * @file
     3 *
     4 * @brief Altera Nios II Assembly File
     5 *
     6 * Very loose template for an include file for the cpu_asm.? file
     7 * if it is implemented as a ".S" file (preprocessed by cpp) instead
     8 * of a ".s" file (preprocessed by gm4 or gasp).
    39 */
    410
    511/*
    6  *  Very loose template for an include file for the cpu_asm.? file
    7  *  if it is implemented as a ".S" file (preprocessed by cpp) instead
    8  *  of a ".s" file (preprocessed by gm4 or gasp).
    9  *
    1012 *  COPYRIGHT (c) 1989-1999.
    1113 *  On-Line Applications Research Corporation (OAR).
  • cpukit/score/cpu/nios2/rtems/score/types.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/types.h
     2 * @file
     3 *
     4 * @brief Altera Nios II CPU Type Definitions
     5 *
     6 * This include file contains type definitions pertaining to the
     7 * Altera Nios II processor family.
    38 */
    49
    510/*
    6  *  This include file contains type definitions pertaining to the
    7  *  Altera Nios II processor family.
    8  *
    911 *  COPYRIGHT (c) 1989-1999.
    1012 *  On-Line Applications Research Corporation (OAR).
  • cpukit/score/cpu/sh/rtems/asm.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/asm.h
     2 * @file
    33 *
    4  *  This include file attempts to address the problems
    5  *  caused by incompatible flavors of assemblers and
    6  *  toolsets.  It primarily addresses variations in the
    7  *  use of leading underscores on symbols and the requirement
    8  *  that register names be preceded by a %.
     4 * @brief Address the Problems Caused by Incompatible Flavor of
     5 * Assemblers and Toolsets
     6 *
     7 * This include file attempts to address the problems
     8 * caused by incompatible flavors of assemblers and
     9 * toolsets.  It primarily addresses variations in the
     10 * use of leading underscores on symbols and the requirement
     11 * that register names be preceded by a %.
     12 *
     13 * @note The spacing in the use of these macros
     14 *       is critical to them working as advertised.
    915 */
    1016
     
    1218 *  Authors: Ralf Corsepius (corsepiu@faw.uni-ulm.de) and
    1319 *           Bernd Becker (becker@faw.uni-ulm.de)
    14  *
    15  *  NOTE: The spacing in the use of these macros
    16  *        is critical to them working as advertised.
    1720 *
    1821 *  COPYRIGHT:
  • cpukit/score/cpu/sh/rtems/score/sh.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/sh.h
    3  */
    4 
    5 /*
    6  *  This include file contains information pertaining to the Hitachi SH
    7  *  processor.
    8  *
     2 * @file
     3 *
     4 * @brief Hitachi SH CPU Department Source
     5 *
     6 * This include file contains information pertaining to the Hitachi SH
     7 * processor.
     8 */
     9
     10/*
    911 *  Authors: Ralf Corsepius (corsepiu@faw.uni-ulm.de) and
    1012 *           Bernd Becker (becker@faw.uni-ulm.de)
  • cpukit/score/cpu/sh/rtems/score/sh_io.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/sh_io.h
     2 * @file
     3 *
     4 * @brief Macros to Access Memory Mapped Devices on the SH7000-Architecture
     5 *
     6 * These are some macros to access memory mapped devices
     7 * on the SH7000-architecture.
    38 */
    49
    510/*
    6  * These are some macros to access memory mapped devices
    7  * on the SH7000-architecture.
    8  *
    911 * Inspired from the linux kernel's include/asm/io.h
    1012 *
  • cpukit/score/cpu/sh/rtems/score/types.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/types.h
     2 * @file
     3 *
     4 * @brief Hitachi SH CPU Type Definitions
     5 *
     6 * This include file contains information pertaining to the Hitachi SH
     7 * processor.
    38 */
    49
    510/*
    6  *  This include file contains information pertaining to the Hitachi SH
    7  *  processor.
    8  *
    911 *  Authors: Ralf Corsepius (corsepiu@faw.uni-ulm.de) and
    1012 *           Bernd Becker (becker@faw.uni-ulm.de)
  • cpukit/score/cpu/v850/rtems/asm.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/asm.h
     2 * @file
    33 *
    4  *  This include file attempts to address the problems
    5  *  caused by incompatible flavors of assemblers and
    6  *  toolsets.  It primarily addresses variations in the
    7  *  use of leading underscores on symbols and the requirement
    8  *  that register names be preceded by a %.
     4 * @brief Address the Problems Caused by Incompatible Flavor of
     5 * Assemblers and Toolsets
     6 *
     7 * This include file attempts to address the problems
     8 * caused by incompatible flavors of assemblers and
     9 * toolsets.  It primarily addresses variations in the
     10 * use of leading underscores on symbols and the requirement
     11 * that register names be preceded by a %.
     12 *
     13 * @note The spacing in the use of these macros
     14 *       is critical to them working as advertised.
    915 */
    1016
    1117/*
    12  *  NOTE: The spacing in the use of these macros
    13  *        is critical to them working as advertised.
    14  *
    1518 *  COPYRIGHT:
    1619 *
     
    1922 *  notice.  This file is freely distributable as long as the source
    2023 *  of the file is noted.  This file is:
    21  */
    22 
    23 /*
     24 *
    2425 *  COPYRIGHT (c) 1994-2012.
    2526 *  On-Line Applications Research Corporation (OAR).
     
    4142#ifndef __USER_LABEL_PREFIX__
    4243/**
    43  *  Recent versions of GNU cpp define variables which indicate the
    44  *  need for underscores and percents.  If not using GNU cpp or
    45  *  the version does not support this, then you will obviously
    46  *  have to define these as appropriate.
     44 * Recent versions of GNU cpp define variables which indicate the
     45 * need for underscores and percents.  If not using GNU cpp or
     46 * the version does not support this, then you will obviously
     47 * have to define these as appropriate.
    4748 *
    48  *  This symbol is prefixed to all C program symbols.
     49 * This symbol is prefixed to all C program symbols.
    4950 */
    5051#define __USER_LABEL_PREFIX__ _
     
    5354#ifndef __REGISTER_PREFIX__
    5455/**
    55  *  Recent versions of GNU cpp define variables which indicate the
    56  *  need for underscores and percents.  If not using GNU cpp or
    57  *  the version does not support this, then you will obviously
    58  *  have to define these as appropriate.
     56 * Recent versions of GNU cpp define variables which indicate the
     57 * need for underscores and percents.  If not using GNU cpp or
     58 * the version does not support this, then you will obviously
     59 * have to define these as appropriate.
    5960 *
    60  *  This symbol is prefixed to all register names.
     61 * This symbol is prefixed to all register names.
    6162 */
    6263#define __REGISTER_PREFIX__
     
    9899/** This macro is used to denote the end of a data section. */
    99100#define END_DATA
    100 /** This macro is used to denote the beginning of the
    101  *  unitialized data section.
     101/**
     102 * This macro is used to denote the beginning of the
     103 * unitialized data section.
    102104 */
    103105#define BEGIN_BSS
     
    108110
    109111/**
    110  *  This macro is used to declare a public global symbol.
     112 * This macro is used to declare a public global symbol.
    111113 *
    112  *  @note This must be tailored for a particular flavor of the C compiler.
    113  *  They may need to put underscores in front of the symbols.
     114 * @note This must be tailored for a particular flavor of the C compiler.
     115 * They may need to put underscores in front of the symbols.
    114116 */
    115117#define PUBLIC(sym) .globl SYM (sym)
    116118
    117119/**
    118  *  This macro is used to prototype a public global symbol.
     120 * This macro is used to prototype a public global symbol.
    119121 *
    120  *  @note This must be tailored for a particular flavor of the C compiler.
    121  *  They may need to put underscores in front of the symbols.
     122 * @note This must be tailored for a particular flavor of the C compiler.
     123 * They may need to put underscores in front of the symbols.
    122124 */
    123125#define EXTERN(sym) .globl SYM (sym)
  • cpukit/score/cpu/v850/rtems/score/cpu.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/cpu.h
    3  */
    4 
    5 /*
    6  *  This include file contains information pertaining to the v850
    7  *  processor.
     2 * @file
     3 *
     4 * @brief V850 CPU Department Source
     5 *
     6 * This include file contains information pertaining to the v850
     7 * processor.
    88 */
    99
     
    3030
    3131/**
    32  *  Should the calls to @ref _Thread_Enable_dispatch be inlined?
    33  *
    34  *  If TRUE, then they are inlined.
    35  *  If FALSE, then a subroutine call is made.
    36  *
    37  *  This conditional is an example of the classic trade-off of size
    38  *  versus speed.  Inlining the call (TRUE) typically increases the
    39  *  size of RTEMS while speeding up the enabling of dispatching.
    40  *
    41  *  @note In general, the @ref _Thread_Dispatch_disable_level will
    42  *  only be 0 or 1 unless you are in an interrupt handler and that
    43  *  interrupt handler invokes the executive.]  When not inlined
    44  *  something calls @ref _Thread_Enable_dispatch which in turns calls
    45  *  @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
    46  *  one subroutine call is avoided entirely.
    47  *
    48  *  Port Specific Information:
    49  *
    50  *  The v850 is a RISC CPU which typically has enough memory to justify
    51  *  the inlining of this method.
     32 * Should the calls to @ref _Thread_Enable_dispatch be inlined?
     33 *
     34 * If TRUE, then they are inlined.
     35 * If FALSE, then a subroutine call is made.
     36 *
     37 * This conditional is an example of the classic trade-off of size
     38 * versus speed.  Inlining the call (TRUE) typically increases the
     39 * size of RTEMS while speeding up the enabling of dispatching.
     40 *
     41 * @note In general, the @ref _Thread_Dispatch_disable_level will
     42 * only be 0 or 1 unless you are in an interrupt handler and that
     43 * interrupt handler invokes the executive.]  When not inlined
     44 * something calls @ref _Thread_Enable_dispatch which in turns calls
     45 * @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
     46 * one subroutine call is avoided entirely.
     47 *
     48 * Port Specific Information:
     49 *
     50 * The v850 is a RISC CPU which typically has enough memory to justify
     51 * the inlining of this method.
    5252 */
    5353#define CPU_INLINE_ENABLE_DISPATCH       TRUE
    5454
    5555/**
    56  *  Should the body of the search loops in _Thread_queue_Enqueue_priority
    57  *  be unrolled one time?  In unrolled each iteration of the loop examines
    58  *  two "nodes" on the chain being searched.  Otherwise, only one node
    59  *  is examined per iteration.
    60  *
    61  *  If TRUE, then the loops are unrolled.
    62  *  If FALSE, then the loops are not unrolled.
    63  *
    64  *  The primary factor in making this decision is the cost of disabling
    65  *  and enabling interrupts (_ISR_Flash) versus the cost of rest of the
    66  *  body of the loop.  On some CPUs, the flash is more expensive than
    67  *  one iteration of the loop body.  In this case, it might be desirable
    68  *  to unroll the loop.  It is important to note that on some CPUs, this
    69  *  code is the longest interrupt disable period in RTEMS.  So it is
    70  *  necessary to strike a balance when setting this parameter.
    71  *
    72  *  Port Specific Information:
    73  *
    74  *  The v850 is a RISC CPU which typically has enough memory to justify
    75  *  the unrolling of this method.
     56 * Should the body of the search loops in _Thread_queue_Enqueue_priority
     57 * be unrolled one time?  In unrolled each iteration of the loop examines
     58 * two "nodes" on the chain being searched.  Otherwise, only one node
     59 * is examined per iteration.
     60 *
     61 * If TRUE, then the loops are unrolled.
     62 * If FALSE, then the loops are not unrolled.
     63 *
     64 * The primary factor in making this decision is the cost of disabling
     65 * and enabling interrupts (_ISR_Flash) versus the cost of rest of the
     66 * body of the loop.  On some CPUs, the flash is more expensive than
     67 * one iteration of the loop body.  In this case, it might be desirable
     68 * to unroll the loop.  It is important to note that on some CPUs, this
     69 * code is the longest interrupt disable period in RTEMS.  So it is
     70 * necessary to strike a balance when setting this parameter.
     71 *
     72 * Port Specific Information:
     73 *
     74 * The v850 is a RISC CPU which typically has enough memory to justify
     75 * the unrolling of this method.
    7676 */
    7777#define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
    7878
    7979/**
    80  *  Does RTEMS manage a dedicated interrupt stack in software?
    81  *
    82  *  If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
    83  *  If FALSE, nothing is done.
    84  *
    85  *  If the CPU supports a dedicated interrupt stack in hardware,
    86  *  then it is generally the responsibility of the BSP to allocate it
    87  *  and set it up.
    88  *
    89  *  If the CPU does not support a dedicated interrupt stack, then
    90  *  the porter has two options: (1) execute interrupts on the
    91  *  stack of the interrupted task, and (2) have RTEMS manage a dedicated
    92  *  interrupt stack.
    93  *
    94  *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    95  *
    96  *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    97  *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    98  *  possible that both are FALSE for a particular CPU.  Although it
    99  *  is unclear what that would imply about the interrupt processing
    100  *  procedure on that CPU.
    101  *
    102  *  Port Specific Information:
    103  *
    104  *  The v850 does not have support for a hardware interrupt stack.
     80 * Does RTEMS manage a dedicated interrupt stack in software?
     81 *
     82 * If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
     83 * If FALSE, nothing is done.
     84 *
     85 * If the CPU supports a dedicated interrupt stack in hardware,
     86 * then it is generally the responsibility of the BSP to allocate it
     87 * and set it up.
     88 *
     89 * If the CPU does not support a dedicated interrupt stack, then
     90 * the porter has two options: (1) execute interrupts on the
     91 * stack of the interrupted task, and (2) have RTEMS manage a dedicated
     92 * interrupt stack.
     93 *
     94 * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     95 *
     96 * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     97 * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     98 * possible that both are FALSE for a particular CPU.  Although it
     99 * is unclear what that would imply about the interrupt processing
     100 * procedure on that CPU.
     101 *
     102 * Port Specific Information:
     103 *
     104 * The v850 does not have support for a hardware interrupt stack.
    105105 */
    106106#define CPU_HAS_SOFTWARE_INTERRUPT_STACK TRUE
    107107
    108108/**
    109  *  Does the CPU follow the simple vectored interrupt model?
    110  *
    111  *  If TRUE, then RTEMS allocates the vector table it internally manages.
    112  *  If FALSE, then the BSP is assumed to allocate and manage the vector
    113  *  table
    114  *
    115  *  Port Specific Information:
    116  *
    117  *  This port uses the Progammable Interrupt Controller interrupt model.
     109 * Does the CPU follow the simple vectored interrupt model?
     110 *
     111 * If TRUE, then RTEMS allocates the vector table it internally manages.
     112 * If FALSE, then the BSP is assumed to allocate and manage the vector
     113 * table
     114 *
     115 * Port Specific Information:
     116 *
     117 * This port uses the Progammable Interrupt Controller interrupt model.
    118118 */
    119119#define CPU_SIMPLE_VECTORED_INTERRUPTS FALSE
    120120
    121121/**
    122  *  Does this CPU have hardware support for a dedicated interrupt stack?
    123  *
    124  *  If TRUE, then it must be installed during initialization.
    125  *  If FALSE, then no installation is performed.
    126  *
    127  *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    128  *
    129  *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    130  *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    131  *  possible that both are FALSE for a particular CPU.  Although it
    132  *  is unclear what that would imply about the interrupt processing
    133  *  procedure on that CPU.
    134  *
    135  *  Port Specific Information:
    136  *
    137  *  The v850 does not have support for a hardware interrupt stack.
     122 * Does this CPU have hardware support for a dedicated interrupt stack?
     123 *
     124 * If TRUE, then it must be installed during initialization.
     125 * If FALSE, then no installation is performed.
     126 *
     127 * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     128 *
     129 * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     130 * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     131 * possible that both are FALSE for a particular CPU.  Although it
     132 * is unclear what that would imply about the interrupt processing
     133 * procedure on that CPU.
     134 *
     135 * Port Specific Information:
     136 *
     137 * The v850 does not have support for a hardware interrupt stack.
    138138 */
    139139#define CPU_HAS_HARDWARE_INTERRUPT_STACK FALSE
    140140
    141141/**
    142  *  Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
    143  *
    144  *  If TRUE, then the memory is allocated during initialization.
    145  *  If FALSE, then the memory is allocated during initialization.
    146  *
    147  *  This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
    148  *
    149  *  Port Specific Information:
    150  *
    151  *  XXX document implementation including references if appropriate
     142 * Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
     143 *
     144 * If TRUE, then the memory is allocated during initialization.
     145 * If FALSE, then the memory is allocated during initialization.
     146 *
     147 * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
     148 *
     149 * Port Specific Information:
     150 *
     151 * XXX document implementation including references if appropriate
    152152 */
    153153#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
    154154
    155155/**
    156  *  @def CPU_HARDWARE_FP
    157  *
    158  *  Does the CPU have hardware floating point?
    159  *
    160  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
    161  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
    162  *
    163  *  If there is a FP coprocessor such as the i387 or mc68881, then
    164  *  the answer is TRUE.
    165  *
    166  *  The macro name "V850_HAS_FPU" should be made CPU specific.
    167  *  It indicates whether or not this CPU model has FP support.  For
    168  *  example, it would be possible to have an i386_nofp CPU model
    169  *  which set this to false to indicate that you have an i386 without
    170  *  an i387 and wish to leave floating point support out of RTEMS.
    171  */
    172 
    173 /**
    174  *  @def CPU_SOFTWARE_FP
    175  *
    176  *  Does the CPU have no hardware floating point and GCC provides a
    177  *  software floating point implementation which must be context
    178  *  switched?
    179  *
    180  *  This feature conditional is used to indicate whether or not there
    181  *  is software implemented floating point that must be context
    182  *  switched.  The determination of whether or not this applies
    183  *  is very tool specific and the state saved/restored is also
    184  *  compiler specific.
    185  *
    186  *  Port Specific Information:
    187  *
    188  *  Some v850 models do have IEEE hardware floating point support but
    189  *  they do not have any special registers to save or bit(s) which
    190  *  determine if the FPU is enabled. In short, there appears to be nothing
    191  *  related to the floating point operations which impact the RTEMS
    192  *  thread context switch. Thus from an RTEMS perspective, there is really
    193  *  no FPU to manage.
     156 * @def CPU_HARDWARE_FP
     157 *
     158 * Does the CPU have hardware floating point?
     159 *
     160 * If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
     161 * If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
     162 *
     163 * If there is a FP coprocessor such as the i387 or mc68881, then
     164 * the answer is TRUE.
     165 *
     166 * The macro name "V850_HAS_FPU" should be made CPU specific.
     167 * It indicates whether or not this CPU model has FP support.  For
     168 * example, it would be possible to have an i386_nofp CPU model
     169 * which set this to false to indicate that you have an i386 without
     170 * an i387 and wish to leave floating point support out of RTEMS.
     171 */
     172
     173/**
     174 * @def CPU_SOFTWARE_FP
     175 *
     176 * Does the CPU have no hardware floating point and GCC provides a
     177 * software floating point implementation which must be context
     178 * switched?
     179 *
     180 * This feature conditional is used to indicate whether or not there
     181 * is software implemented floating point that must be context
     182 * switched.  The determination of whether or not this applies
     183 * is very tool specific and the state saved/restored is also
     184 * compiler specific.
     185 *
     186 * Port Specific Information:
     187 *
     188 * Some v850 models do have IEEE hardware floating point support but
     189 * they do not have any special registers to save or bit(s) which
     190 * determine if the FPU is enabled. In short, there appears to be nothing
     191 * related to the floating point operations which impact the RTEMS
     192 * thread context switch. Thus from an RTEMS perspective, there is really
     193 * no FPU to manage.
    194194 */
    195195#define CPU_HARDWARE_FP     FALSE
     
    197197
    198198/**
    199  *  Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
    200  *
    201  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
    202  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
    203  *
    204  *  So far, the only CPUs in which this option has been used are the
    205  *  HP PA-RISC and PowerPC.  On the PA-RISC, The HP C compiler and
    206  *  gcc both implicitly used the floating point registers to perform
    207  *  integer multiplies.  Similarly, the PowerPC port of gcc has been
    208  *  seen to allocate floating point local variables and touch the FPU
    209  *  even when the flow through a subroutine (like vfprintf()) might
    210  *  not use floating point formats.
    211  *
    212  *  If a function which you would not think utilize the FP unit DOES,
    213  *  then one can not easily predict which tasks will use the FP hardware.
    214  *  In this case, this option should be TRUE.
    215  *
    216  *  If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
    217  *
    218  *  Port Specific Information:
    219  *
    220  *  This should be false until it has been demonstrated that gcc for the
    221  *  v850 generates FPU code when it is unexpected. But even this would
    222  *  not matter since there are no FP specific registers or bits which
    223  *  would be corrupted if an FP operation occurred in an integer only
    224  *  thread.
     199 * Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
     200 *
     201 * If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
     202 * If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
     203 *
     204 * So far, the only CPUs in which this option has been used are the
     205 * HP PA-RISC and PowerPC.  On the PA-RISC, The HP C compiler and
     206 * gcc both implicitly used the floating point registers to perform
     207 * integer multiplies.  Similarly, the PowerPC port of gcc has been
     208 * seen to allocate floating point local variables and touch the FPU
     209 * even when the flow through a subroutine (like vfprintf()) might
     210 * not use floating point formats.
     211 *
     212 * If a function which you would not think utilize the FP unit DOES,
     213 * then one can not easily predict which tasks will use the FP hardware.
     214 * In this case, this option should be TRUE.
     215 *
     216 * If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
     217 *
     218 * Port Specific Information:
     219 *
     220 * This should be false until it has been demonstrated that gcc for the
     221 * v850 generates FPU code when it is unexpected. But even this would
     222 * not matter since there are no FP specific registers or bits which
     223 * would be corrupted if an FP operation occurred in an integer only
     224 * thread.
    225225 */
    226226#define CPU_ALL_TASKS_ARE_FP     FALSE
    227227
    228228/**
    229  *  Should the IDLE task have a floating point context?
    230  *
    231  *  If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
    232  *  and it has a floating point context which is switched in and out.
    233  *  If FALSE, then the IDLE task does not have a floating point context.
    234  *
    235  *  Setting this to TRUE negatively impacts the time required to preempt
    236  *  the IDLE task from an interrupt because the floating point context
    237  *  must be saved as part of the preemption.
    238  *
    239  *  Port Specific Information:
    240  *
    241  *  The IDLE thread should not be using the FPU. Leave this off.
     229 * Should the IDLE task have a floating point context?
     230 *
     231 * If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
     232 * and it has a floating point context which is switched in and out.
     233 * If FALSE, then the IDLE task does not have a floating point context.
     234 *
     235 * Setting this to TRUE negatively impacts the time required to preempt
     236 * the IDLE task from an interrupt because the floating point context
     237 * must be saved as part of the preemption.
     238 *
     239 * Port Specific Information:
     240 *
     241 * The IDLE thread should not be using the FPU. Leave this off.
    242242 */
    243243#define CPU_IDLE_TASK_IS_FP      FALSE
    244244
    245245/**
    246  *  Should the saving of the floating point registers be deferred
    247  *  until a context switch is made to another different floating point
    248  *  task?
    249  *
    250  *  If TRUE, then the floating point context will not be stored until
    251  *  necessary.  It will remain in the floating point registers and not
    252  *  disturned until another floating point task is switched to.
    253  *
    254  *  If FALSE, then the floating point context is saved when a floating
    255  *  point task is switched out and restored when the next floating point
    256  *  task is restored.  The state of the floating point registers between
    257  *  those two operations is not specified.
    258  *
    259  *  If the floating point context does NOT have to be saved as part of
    260  *  interrupt dispatching, then it should be safe to set this to TRUE.
    261  *
    262  *  Setting this flag to TRUE results in using a different algorithm
    263  *  for deciding when to save and restore the floating point context.
    264  *  The deferred FP switch algorithm minimizes the number of times
    265  *  the FP context is saved and restored.  The FP context is not saved
    266  *  until a context switch is made to another, different FP task.
    267  *  Thus in a system with only one FP task, the FP context will never
    268  *  be saved or restored.
    269  *
    270  *  Port Specific Information:
    271  *
    272  *  See earlier comments. There is no FPU state to manage.
     246 * Should the saving of the floating point registers be deferred
     247 * until a context switch is made to another different floating point
     248 * task?
     249 *
     250 * If TRUE, then the floating point context will not be stored until
     251 * necessary.  It will remain in the floating point registers and not
     252 * disturned until another floating point task is switched to.
     253 *
     254 * If FALSE, then the floating point context is saved when a floating
     255 * point task is switched out and restored when the next floating point
     256 * task is restored.  The state of the floating point registers between
     257 * those two operations is not specified.
     258 *
     259 * If the floating point context does NOT have to be saved as part of
     260 * interrupt dispatching, then it should be safe to set this to TRUE.
     261 *
     262 * Setting this flag to TRUE results in using a different algorithm
     263 * for deciding when to save and restore the floating point context.
     264 * The deferred FP switch algorithm minimizes the number of times
     265 * the FP context is saved and restored.  The FP context is not saved
     266 * until a context switch is made to another, different FP task.
     267 * Thus in a system with only one FP task, the FP context will never
     268 * be saved or restored.
     269 *
     270 * Port Specific Information:
     271 *
     272 * See earlier comments. There is no FPU state to manage.
    273273 */
    274274#define CPU_USE_DEFERRED_FP_SWITCH       TRUE
    275275
    276276/**
    277  *  Does this port provide a CPU dependent IDLE task implementation?
    278  *
    279  *  If TRUE, then the routine @ref _CPU_Thread_Idle_body
    280  *  must be provided and is the default IDLE thread body instead of
    281  *  @ref _CPU_Thread_Idle_body.
    282  *
    283  *  If FALSE, then use the generic IDLE thread body if the BSP does
    284  *  not provide one.
    285  *
    286  *  This is intended to allow for supporting processors which have
    287  *  a low power or idle mode.  When the IDLE thread is executed, then
    288  *  the CPU can be powered down.
    289  *
    290  *  The order of precedence for selecting the IDLE thread body is:
    291  *
    292  *    -#  BSP provided
    293  *    -#  CPU dependent (if provided)
    294  *    -#  generic (if no BSP and no CPU dependent)
    295  *
    296  *  Port Specific Information:
    297  *
    298  *  There does not appear to be a reason for the v850 port itself to provide
    299  *  a special idle task.
     277 * Does this port provide a CPU dependent IDLE task implementation?
     278 *
     279 * If TRUE, then the routine @ref _CPU_Thread_Idle_body
     280 * must be provided and is the default IDLE thread body instead of
     281 * @ref _CPU_Thread_Idle_body.
     282 *
     283 * If FALSE, then use the generic IDLE thread body if the BSP does
     284 * not provide one.
     285 *
     286 * This is intended to allow for supporting processors which have
     287 * a low power or idle mode.  When the IDLE thread is executed, then
     288 * the CPU can be powered down.
     289 *
     290 * The order of precedence for selecting the IDLE thread body is:
     291 *
     292 *   -#  BSP provided
     293 *   -#  CPU dependent (if provided)
     294 *   -#  generic (if no BSP and no CPU dependent)
     295 *
     296 * Port Specific Information:
     297 *
     298 * There does not appear to be a reason for the v850 port itself to provide
     299 * a special idle task.
    300300 */
    301301#define CPU_PROVIDES_IDLE_THREAD_BODY    FALSE
    302302
    303303/**
    304  *  Does the stack grow up (toward higher addresses) or down
    305  *  (toward lower addresses)?
    306  *
    307  *  If TRUE, then the grows upward.
    308  *  If FALSE, then the grows toward smaller addresses.
    309  *
    310  *  Port Specific Information:
    311  *
    312  *  The v850 stack grows from high addresses to low addresses.
     304 * Does the stack grow up (toward higher addresses) or down
     305 * (toward lower addresses)?
     306 *
     307 * If TRUE, then the grows upward.
     308 * If FALSE, then the grows toward smaller addresses.
     309 *
     310 * Port Specific Information:
     311 *
     312 * The v850 stack grows from high addresses to low addresses.
    313313 */
    314314#define CPU_STACK_GROWS_UP               FALSE
    315315
    316316/**
    317  *  The following is the variable attribute used to force alignment
    318  *  of critical RTEMS structures.  On some processors it may make
    319  *  sense to have these aligned on tighter boundaries than
    320  *  the minimum requirements of the compiler in order to have as
    321  *  much of the critical data area as possible in a cache line.
    322  *
    323  *  The placement of this macro in the declaration of the variables
    324  *  is based on the syntactically requirements of the GNU C
    325  *  "__attribute__" extension.  For example with GNU C, use
    326  *  the following to force a structures to a 32 byte boundary.
    327  *
    328  *      __attribute__ ((aligned (32)))
    329  *
    330  *  @note Currently only the Priority Bit Map table uses this feature.
    331  *        To benefit from using this, the data must be heavily
    332  *        used so it will stay in the cache and used frequently enough
    333  *        in the executive to justify turning this on.
    334  *
    335  *  Port Specific Information:
    336  *
    337  *  Until proven otherwise, use the compiler default.
     317 * The following is the variable attribute used to force alignment
     318 * of critical RTEMS structures.  On some processors it may make
     319 * sense to have these aligned on tighter boundaries than
     320 * the minimum requirements of the compiler in order to have as
     321 * much of the critical data area as possible in a cache line.
     322 *
     323 * The placement of this macro in the declaration of the variables
     324 * is based on the syntactically requirements of the GNU C
     325 * "__attribute__" extension.  For example with GNU C, use
     326 * the following to force a structures to a 32 byte boundary.
     327 *
     328 *     __attribute__ ((aligned (32)))
     329 *
     330 * @note Currently only the Priority Bit Map table uses this feature.
     331 *       To benefit from using this, the data must be heavily
     332 *       used so it will stay in the cache and used frequently enough
     333 *       in the executive to justify turning this on.
     334 *
     335 * Port Specific Information:
     336 *
     337 * Until proven otherwise, use the compiler default.
    338338 */
    339339#define CPU_STRUCTURE_ALIGNMENT
    340340
    341341/**
    342  *  The v850 should use 64-bit timestamps and inline them.
     342 * The v850 should use 64-bit timestamps and inline them.
    343343 */
    344344#define CPU_TIMESTAMP_USE_INT64_INLINE TRUE
    345345
    346346/**
    347  *  @defgroup CPUEndian Processor Dependent Endianness Support
    348  *
    349  *  This group assists in issues related to processor endianness.
    350  */
    351 
    352 /**
    353  *  @ingroup CPUEndian
    354  *  Define what is required to specify how the network to host conversion
    355  *  routines are handled.
    356  *
    357  *  @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
    358  *  same values.
    359  *
    360  *  @see CPU_LITTLE_ENDIAN
    361  *
    362  *  Port Specific Information:
    363  *
    364  *  The v850 is little endian.
     347 * @defgroup CPUEndian Processor Dependent Endianness Support
     348 *
     349 * This group assists in issues related to processor endianness.
     350 *
     351 * @{
     352 */
     353
     354/**
     355 * Define what is required to specify how the network to host conversion
     356 * routines are handled.
     357 *
     358 * @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
     359 * same values.
     360 *
     361 * @see CPU_LITTLE_ENDIAN
     362 *
     363 * Port Specific Information:
     364 *
     365 * The v850 is little endian.
    365366 */
    366367#define CPU_BIG_ENDIAN  FALSE
    367368
    368369/**
    369  *  @ingroup CPUEndian
    370  *  Define what is required to specify how the network to host conversion
    371  *  routines are handled.
    372  *
    373  *  @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
    374  *  same values.
    375  *
    376  *  @see CPU_BIG_ENDIAN
    377  *
    378  *  Port Specific Information:
    379  *
    380  *  The v850 is little endian.
     370 * Define what is required to specify how the network to host conversion
     371 * routines are handled.
     372 *
     373 * @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
     374 * same values.
     375 *
     376 * @see CPU_BIG_ENDIAN
     377 *
     378 * Port Specific Information:
     379 *
     380 * The v850 is little endian.
    381381 */
    382382#define CPU_LITTLE_ENDIAN TRUE
    383383
    384 /**
    385  *  @ingroup CPUInterrupt
    386  *  The following defines the number of bits actually used in the
    387  *  interrupt field of the task mode.  How those bits map to the
    388  *  CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
    389  *
    390  *  Port Specific Information:
    391  *
    392  *  The v850 only has a single bit in the CPU for interrupt disable/enable.
     384/** @} */
     385
     386/**
     387 * @ingroup CPUInterrupt
     388 * The following defines the number of bits actually used in the
     389 * interrupt field of the task mode.  How those bits map to the
     390 * CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
     391 *
     392 * Port Specific Information:
     393 *
     394 * The v850 only has a single bit in the CPU for interrupt disable/enable.
    393395 */
    394396#define CPU_MODES_INTERRUPT_MASK   0x00000001
     
    397399 * @defgroup CPUContext Processor Dependent Context Management
    398400 *
    399  *  From the highest level viewpoint, there are 2 types of context to save.
    400  *
    401  *     -# Interrupt registers to save
    402  *     -# Task level registers to save
    403  *
    404  *  Since RTEMS handles integer and floating point contexts separately, this
    405  *  means we have the following 3 context items:
    406  *
    407  *     -# task level context stuff::  Context_Control
    408  *     -# floating point task stuff:: Context_Control_fp
    409  *     -# special interrupt level context :: CPU_Interrupt_frame
    410  *
    411  *  On some processors, it is cost-effective to save only the callee
    412  *  preserved registers during a task context switch.  This means
    413  *  that the ISR code needs to save those registers which do not
    414  *  persist across function calls.  It is not mandatory to make this
    415  *  distinctions between the caller/callee saves registers for the
    416  *  purpose of minimizing context saved during task switch and on interrupts.
    417  *  If the cost of saving extra registers is minimal, simplicity is the
    418  *  choice.  Save the same context on interrupt entry as for tasks in
    419  *  this case.
    420  *
    421  *  Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then
    422  *  care should be used in designing the context area.
    423  *
    424  *  On some CPUs with hardware floating point support, the Context_Control_fp
    425  *  structure will not be used or it simply consist of an array of a
    426  *  fixed number of bytes.   This is done when the floating point context
    427  *  is dumped by a "FP save context" type instruction and the format
    428  *  is not really defined by the CPU.  In this case, there is no need
    429  *  to figure out the exact format -- only the size.  Of course, although
    430  *  this is enough information for RTEMS, it is probably not enough for
    431  *  a debugger such as gdb.  But that is another problem.
    432  *
    433  *  Port Specific Information:
    434  *
    435  *  On the v850, this port saves special registers and those that are
    436  *  callee saved.
    437  */
    438 
    439 /**
    440  *  @ingroup CPUContext Management
    441  *  This defines the minimal set of integer and processor state registers
    442  *  that must be saved during a voluntary context switch from one thread
    443  *  to another.
     401 * From the highest level viewpoint, there are 2 types of context to save.
     402 *
     403 *    -# Interrupt registers to save
     404 *    -# Task level registers to save
     405 *
     406 * Since RTEMS handles integer and floating point contexts separately, this
     407 * means we have the following 3 context items:
     408 *
     409 *    -# task level context stuff::  Context_Control
     410 *    -# floating point task stuff:: Context_Control_fp
     411 *    -# special interrupt level context :: CPU_Interrupt_frame
     412 *
     413 * On some processors, it is cost-effective to save only the callee
     414 * preserved registers during a task context switch.  This means
     415 * that the ISR code needs to save those registers which do not
     416 * persist across function calls.  It is not mandatory to make this
     417 * distinctions between the caller/callee saves registers for the
     418 * purpose of minimizing context saved during task switch and on interrupts.
     419 * If the cost of saving extra registers is minimal, simplicity is the
     420 * choice.  Save the same context on interrupt entry as for tasks in
     421 * this case.
     422 *
     423 * Additionally, if gdb is to be made aware of RTEMS tasks for this CPU, then
     424 * care should be used in designing the context area.
     425 *
     426 * On some CPUs with hardware floating point support, the Context_Control_fp
     427 * structure will not be used or it simply consist of an array of a
     428 * fixed number of bytes.   This is done when the floating point context
     429 * is dumped by a "FP save context" type instruction and the format
     430 * is not really defined by the CPU.  In this case, there is no need
     431 * to figure out the exact format -- only the size.  Of course, although
     432 * this is enough information for RTEMS, it is probably not enough for
     433 * a debugger such as gdb.  But that is another problem.
     434 *
     435 * Port Specific Information:
     436 *
     437 * On the v850, this port saves special registers and those that are
     438 * callee saved.
     439 *
     440 * @{
     441 */
     442
     443/**
     444 * This defines the minimal set of integer and processor state registers
     445 * that must be saved during a voluntary context switch from one thread
     446 * to another.
    444447 */
    445448typedef struct {
     
    462465
    463466/**
    464  *  @ingroup CPUContext Management
    465  *
    466  *  This macro returns the stack pointer associated with @a _context.
    467  *
    468  *  @param[in] _context is the thread context area to access
    469  *
    470  *  @return This method returns the stack pointer.
     467 * This macro returns the stack pointer associated with @a _context.
     468 *
     469 * @param[in] _context is the thread context area to access
     470 *
     471 * @return This method returns the stack pointer.
    471472 */
    472473#define _CPU_Context_Get_SP( _context ) \
     
    474475
    475476/**
    476  *  @ingroup CPUContext Management
    477  *  This defines the complete set of floating point registers that must
    478  *  be saved during any context switch from one thread to another.
     477 * This defines the complete set of floating point registers that must
     478 * be saved during any context switch from one thread to another.
    479479 */
    480480typedef struct {
     
    484484
    485485/**
    486  *  @ingroup CPUContext Management
    487  *  This defines the set of integer and processor state registers that must
    488  *  be saved during an interrupt.  This set does not include any which are
    489  *  in @ref Context_Control.
     486 * This defines the set of integer and processor state registers that must
     487 * be saved during an interrupt.  This set does not include any which are
     488 * in @ref Context_Control.
    490489 */
    491490typedef struct {
    492491    /** This field is a hint that a port will have a number of integer
    493      *  registers that need to be saved when an interrupt occurs or
    494      *  when a context switch occurs at the end of an ISR.
     492     * registers that need to be saved when an interrupt occurs or
     493     * when a context switch occurs at the end of an ISR.
    495494     */
    496495    uint32_t   special_interrupt_register;
    497496} CPU_Interrupt_frame;
    498497
    499 /**
    500  *  @defgroup CPUInterrupt Processor Dependent Interrupt Management
    501  *
    502  *  On some CPUs, RTEMS supports a software managed interrupt stack.
    503  *  This stack is allocated by the Interrupt Manager and the switch
    504  *  is performed in @ref _ISR_Handler.  These variables contain pointers
    505  *  to the lowest and highest addresses in the chunk of memory allocated
    506  *  for the interrupt stack.  Since it is unknown whether the stack
    507  *  grows up or down (in general), this give the CPU dependent
    508  *  code the option of picking the version it wants to use.
    509  *
    510  *  @note These two variables are required if the macro
    511  *        @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
    512  *
    513  *  Port Specific Information:
    514  *
    515  *  XXX document implementation including references if appropriate
    516  */
    517 
    518 /**
    519  *  @ingroup CPUContext
    520  *  The size of the floating point context area.  On some CPUs this
    521  *  will not be a "sizeof" because the format of the floating point
    522  *  area is not defined -- only the size is.  This is usually on
    523  *  CPUs with a "floating point save context" instruction.
    524  *
    525  *  Port Specific Information:
    526  *
    527  *  The v850 does not need a floating point context but this needs to be
    528  *  defined so confdefs.h.
     498/** @} */
     499
     500/**
     501 * @defgroup CPUInterrupt Processor Dependent Interrupt Management
     502 *
     503 * On some CPUs, RTEMS supports a software managed interrupt stack.
     504 * This stack is allocated by the Interrupt Manager and the switch
     505 * is performed in @ref _ISR_Handler.  These variables contain pointers
     506 * to the lowest and highest addresses in the chunk of memory allocated
     507 * for the interrupt stack.  Since it is unknown whether the stack
     508 * grows up or down (in general), this give the CPU dependent
     509 * code the option of picking the version it wants to use.
     510 *
     511 * @note These two variables are required if the macro
     512 *       @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
     513 *
     514 * Port Specific Information:
     515 *
     516 * XXX document implementation including references if appropriate
     517 *
     518 * @{
     519 */
     520
     521/**
     522 * @ingroup CPUContext
     523 * The size of the floating point context area.  On some CPUs this
     524 * will not be a "sizeof" because the format of the floating point
     525 * area is not defined -- only the size is.  This is usually on
     526 * CPUs with a "floating point save context" instruction.
     527 *
     528 * Port Specific Information:
     529 *
     530 * The v850 does not need a floating point context but this needs to be
     531 * defined so confdefs.h.
    529532 */
    530533/* #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp ) */
     
    532535
    533536/**
    534  *  Amount of extra stack (above minimum stack size) required by
    535  *  MPCI receive server thread.  Remember that in a multiprocessor
    536  *  system this thread must exist and be able to process all directives.
    537  *
    538  *  Port Specific Information:
    539  *
    540  *  There is no reason to think the v850 needs extra MPCI receive
    541  *  server stack.
     537 * Amount of extra stack (above minimum stack size) required by
     538 * MPCI receive server thread.  Remember that in a multiprocessor
     539 * system this thread must exist and be able to process all directives.
     540 *
     541 * Port Specific Information:
     542 *
     543 * There is no reason to think the v850 needs extra MPCI receive
     544 * server stack.
    542545 */
    543546#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
     
    547550#if 0
    548551/**
    549  *  @ingroup CPUInterrupt
    550  *  This defines the number of entries in the @ref _ISR_Vector_table managed
    551  *  by RTEMS.
    552  *
    553  *  Port Specific Information:
    554  *
    555  *  XXX document implementation including references if appropriate
     552 * This defines the number of entries in the @ref _ISR_Vector_table managed
     553 * by RTEMS.
     554 *
     555 * Port Specific Information:
     556 *
     557 * XXX document implementation including references if appropriate
    556558 */
    557559#define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
     
    559561
    560562/**
    561  *  @ingroup CPUInterrupt
    562  *  This defines the highest interrupt vector number for this port.
     563 * This defines the highest interrupt vector number for this port.
    563564 */
    564565#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER  (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
    565566
    566567/**
    567  *  @ingroup CPUInterrupt
    568  *  This is defined if the port has a special way to report the ISR nesting
    569  *  level.  Most ports maintain the variable @a _ISR_Nest_level.
     568 * This is defined if the port has a special way to report the ISR nesting
     569 * level.  Most ports maintain the variable @a _ISR_Nest_level.
    570570 */
    571571#define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
    572572
    573 /**
    574  *  @ingroup CPUContext
    575  *  Should be large enough to run all RTEMS tests.  This ensures
    576  *  that a "reasonable" small application should not have any problems.
    577  *
    578  *  Port Specific Information:
    579  *
    580  *  This should be very conservative on the v850.
     573/** @} */
     574
     575/**
     576 * @ingroup CPUContext
     577 * Should be large enough to run all RTEMS tests.  This ensures
     578 * that a "reasonable" small application should not have any problems.
     579 *
     580 * Port Specific Information:
     581 *
     582 * This should be very conservative on the v850.
    581583 */
    582584#define CPU_STACK_MINIMUM_SIZE          (1024*4)
     
    585587
    586588/**
    587  *  CPU's worst alignment requirement for data types on a byte boundary.  This
    588  *  alignment does not take into account the requirements for the stack.
    589  *
    590  *  Port Specific Information:
    591  *
    592  *  There is no apparent reason why this should be larger than 8.
     589 * CPU's worst alignment requirement for data types on a byte boundary.  This
     590 * alignment does not take into account the requirements for the stack.
     591 *
     592 * Port Specific Information:
     593 *
     594 * There is no apparent reason why this should be larger than 8.
    593595 */
    594596#define CPU_ALIGNMENT              8
    595597
    596598/**
    597  *  This number corresponds to the byte alignment requirement for the
    598  *  heap handler.  This alignment requirement may be stricter than that
    599  *  for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
    600  *  common for the heap to follow the same alignment requirement as
    601  *  @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
    602  *  the heap, then this should be set to @ref CPU_ALIGNMENT.
    603  *
    604  *  @note  This does not have to be a power of 2 although it should be
    605  *         a multiple of 2 greater than or equal to 2.  The requirement
    606  *         to be a multiple of 2 is because the heap uses the least
    607  *         significant field of the front and back flags to indicate
    608  *         that a block is in use or free.  So you do not want any odd
    609  *         length blocks really putting length data in that bit.
    610  *
    611  *         On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
    612  *         have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
    613  *         elements allocated from the heap meet all restrictions.
    614  *
    615  *  Port Specific Information:
    616  *
    617  *  There is no apparent reason why this should be larger than CPU_ALIGNMENT.
     599 * This number corresponds to the byte alignment requirement for the
     600 * heap handler.  This alignment requirement may be stricter than that
     601 * for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
     602 * common for the heap to follow the same alignment requirement as
     603 * @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
     604 * the heap, then this should be set to @ref CPU_ALIGNMENT.
     605 *
     606 * @note  This does not have to be a power of 2 although it should be
     607 *        a multiple of 2 greater than or equal to 2.  The requirement
     608 *        to be a multiple of 2 is because the heap uses the least
     609 *        significant field of the front and back flags to indicate
     610 *        that a block is in use or free.  So you do not want any odd
     611 *        length blocks really putting length data in that bit.
     612 *
     613 *        On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
     614 *        have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
     615 *        elements allocated from the heap meet all restrictions.
     616 *
     617 * Port Specific Information:
     618 *
     619 * There is no apparent reason why this should be larger than CPU_ALIGNMENT.
    618620 */
    619621#define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
    620622
    621623/**
    622  *  This number corresponds to the byte alignment requirement for memory
    623  *  buffers allocated by the partition manager.  This alignment requirement
    624  *  may be stricter than that for the data types alignment specified by
    625  *  @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
    626  *  alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
    627  *  strict enough for the partition, then this should be set to
    628  *  @ref CPU_ALIGNMENT.
    629  *
    630  *  @note  This does not have to be a power of 2.  It does have to
    631  *         be greater or equal to than @ref CPU_ALIGNMENT.
    632  *
    633  *  Port Specific Information:
    634  *
    635  *  There is no apparent reason why this should be larger than CPU_ALIGNMENT.
     624 * This number corresponds to the byte alignment requirement for memory
     625 * buffers allocated by the partition manager.  This alignment requirement
     626 * may be stricter than that for the data types alignment specified by
     627 * @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
     628 * alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
     629 * strict enough for the partition, then this should be set to
     630 * @ref CPU_ALIGNMENT.
     631 *
     632 * @note  This does not have to be a power of 2.  It does have to
     633 *        be greater or equal to than @ref CPU_ALIGNMENT.
     634 *
     635 * Port Specific Information:
     636 *
     637 * There is no apparent reason why this should be larger than CPU_ALIGNMENT.
    636638 */
    637639#define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
    638640
    639641/**
    640  *  This number corresponds to the byte alignment requirement for the
    641  *  stack.  This alignment requirement may be stricter than that for the
    642  *  data types alignment specified by @ref CPU_ALIGNMENT.  If the
    643  *  @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
    644  *  set to 0.
    645  *
    646  *  @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
    647  *
    648  *  Port Specific Information:
    649  *
    650  *  The v850 has enough RAM where alignment to 16 may be desirable depending
    651  *  on the cache properties. But this remains to be demonstrated.
     642 * This number corresponds to the byte alignment requirement for the
     643 * stack.  This alignment requirement may be stricter than that for the
     644 * data types alignment specified by @ref CPU_ALIGNMENT.  If the
     645 * @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
     646 * set to 0.
     647 *
     648 * @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
     649 *
     650 * Port Specific Information:
     651 *
     652 * The v850 has enough RAM where alignment to 16 may be desirable depending
     653 * on the cache properties. But this remains to be demonstrated.
    652654 */
    653655#define CPU_STACK_ALIGNMENT        4
     
    658660
    659661/**
    660  *  @ingroup CPUInterrupt
    661  *  Disable all interrupts for an RTEMS critical section.  The previous
    662  *  level is returned in @a _isr_cookie.
    663  *
    664  *  @param[out] _isr_cookie will contain the previous level cookie
    665  *
    666  *  Port Specific Information:
    667  *
    668  *  On the v850, we need to save the PSW and use "di" to disable interrupts.
     662 * @addtogroup CPUInterrupt
     663 *
     664 * @{
     665 */
     666
     667/**
     668 * Disable all interrupts for an RTEMS critical section.  The previous
     669 * level is returned in @a _isr_cookie.
     670 *
     671 * @param[out] _isr_cookie will contain the previous level cookie
     672 *
     673 * Port Specific Information:
     674 *
     675 * On the v850, we need to save the PSW and use "di" to disable interrupts.
    669676 */
    670677#define _CPU_ISR_Disable( _isr_cookie ) \
     
    678685
    679686/**
    680  *  @ingroup CPUInterrupt
    681  *  Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
    682  *  This indicates the end of an RTEMS critical section.  The parameter
    683  *  @a _isr_cookie is not modified.
    684  *
    685  *  @param[in] _isr_cookie contain the previous level cookie
    686  *
    687  *  Port Specific Information:
    688  *
    689  *  On the v850, we simply need to restore the PSW.
     687 * Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
     688 * This indicates the end of an RTEMS critical section.  The parameter
     689 * @a _isr_cookie is not modified.
     690 *
     691 * @param[in] _isr_cookie contain the previous level cookie
     692 *
     693 * Port Specific Information:
     694 *
     695 * On the v850, we simply need to restore the PSW.
    690696 */
    691697#define _CPU_ISR_Enable( _isr_cookie )  \
     
    697703
    698704/**
    699  *  @ingroup CPUInterrupt
    700  *  This temporarily restores the interrupt to @a _isr_cookie before immediately
    701  *  disabling them again.  This is used to divide long RTEMS critical
    702  *  sections into two or more parts.  The parameter @a _isr_cookie is not
    703  *  modified.
    704  *
    705  *  @param[in] _isr_cookie contain the previous level cookie
    706  *
    707  *  Port Specific Information:
    708  *
    709  *  This saves at least one instruction over using enable/disable back to back.
     705 * This temporarily restores the interrupt to @a _isr_cookie before immediately
     706 * disabling them again.  This is used to divide long RTEMS critical
     707 * sections into two or more parts.  The parameter @a _isr_cookie is not
     708 * modified.
     709 *
     710 * @param[in] _isr_cookie contain the previous level cookie
     711 *
     712 * Port Specific Information:
     713 *
     714 * This saves at least one instruction over using enable/disable back to back.
    710715 */
    711716#define _CPU_ISR_Flash( _isr_cookie ) \
     
    717722
    718723/**
    719  *  @ingroup CPUInterrupt
    720  *
    721  *  This routine and @ref _CPU_ISR_Get_level
    722  *  Map the interrupt level in task mode onto the hardware that the CPU
    723  *  actually provides.  Currently, interrupt levels which do not
    724  *  map onto the CPU in a generic fashion are undefined.  Someday,
    725  *  it would be nice if these were "mapped" by the application
    726  *  via a callout.  For example, m68k has 8 levels 0 - 7, levels
    727  *  8 - 255 would be available for bsp/application specific meaning.
    728  *  This could be used to manage a programmable interrupt controller
    729  *  via the rtems_task_mode directive.
    730  *
    731  *  Port Specific Information:
    732  *
    733  *  On the v850, level 0 is enabled. Non-zero is disabled.
     724 * This routine and @ref _CPU_ISR_Get_level
     725 * Map the interrupt level in task mode onto the hardware that the CPU
     726 * actually provides.  Currently, interrupt levels which do not
     727 * map onto the CPU in a generic fashion are undefined.  Someday,
     728 * it would be nice if these were "mapped" by the application
     729 * via a callout.  For example, m68k has 8 levels 0 - 7, levels
     730 * 8 - 255 would be available for bsp/application specific meaning.
     731 * This could be used to manage a programmable interrupt controller
     732 * via the rtems_task_mode directive.
     733 *
     734 * Port Specific Information:
     735 *
     736 * On the v850, level 0 is enabled. Non-zero is disabled.
    734737 */
    735738#define _CPU_ISR_Set_level( new_level ) \
     
    742745
    743746/**
    744  *  @ingroup CPUInterrupt
    745  *  Return the current interrupt disable level for this task in
    746  *  the format used by the interrupt level portion of the task mode.
    747  *
    748  *  @note This routine usually must be implemented as a subroutine.
    749  *
    750  *  Port Specific Information:
    751  *
    752  *  This method is implemented in C on the v850.
     747 * Return the current interrupt disable level for this task in
     748 * the format used by the interrupt level portion of the task mode.
     749 *
     750 * @note This routine usually must be implemented as a subroutine.
     751 *
     752 * Port Specific Information:
     753 *
     754 * This method is implemented in C on the v850.
    753755 */
    754756uint32_t   _CPU_ISR_Get_level( void );
     
    756758/* end of ISR handler macros */
    757759
     760/** @} */
     761
    758762/* Context handler macros */
    759763
    760764/**
    761  *  @ingroup CPUContext
    762  *  Initialize the context to a state suitable for starting a
    763  *  task after a context restore operation.  Generally, this
    764  *  involves:
    765  *
    766  *     - setting a starting address
    767  *     - preparing the stack
    768  *     - preparing the stack and frame pointers
    769  *     - setting the proper interrupt level in the context
    770  *     - initializing the floating point context
    771  *
    772  *  This routine generally does not set any unnecessary register
    773  *  in the context.  The state of the "general data" registers is
    774  *  undefined at task start time.
    775  *
    776  *  @param[in] _the_context is the context structure to be initialized
    777  *  @param[in] _stack_base is the lowest physical address of this task's stack
    778  *  @param[in] _size is the size of this task's stack
    779  *  @param[in] _isr is the interrupt disable level
    780  *  @param[in] _entry_point is the thread's entry point.  This is
    781  *         always @a _Thread_Handler
    782  *  @param[in] _is_fp is TRUE if the thread is to be a floating
    783  *        point thread.  This is typically only used on CPUs where the
    784  *        FPU may be easily disabled by software such as on the SPARC
    785  *        where the PSR contains an enable FPU bit.
    786  *
    787  *  Port Specific Information:
    788  *
    789  *  This method is implemented in C on the v850.
     765 * @ingroup CPUContext
     766 * Initialize the context to a state suitable for starting a
     767 * task after a context restore operation.  Generally, this
     768 * involves:
     769 *
     770 *    - setting a starting address
     771 *    - preparing the stack
     772 *    - preparing the stack and frame pointers
     773 *    - setting the proper interrupt level in the context
     774 *    - initializing the floating point context
     775 *
     776 * This routine generally does not set any unnecessary register
     777 * in the context.  The state of the "general data" registers is
     778 * undefined at task start time.
     779 *
     780 * @param[in] _the_context is the context structure to be initialized
     781 * @param[in] _stack_base is the lowest physical address of this task's stack
     782 * @param[in] _size is the size of this task's stack
     783 * @param[in] _isr is the interrupt disable level
     784 * @param[in] _entry_point is the thread's entry point.  This is
     785 *        always @a _Thread_Handler
     786 * @param[in] _is_fp is TRUE if the thread is to be a floating
     787 *       point thread.  This is typically only used on CPUs where the
     788 *       FPU may be easily disabled by software such as on the SPARC
     789 *       where the PSR contains an enable FPU bit.
     790 *
     791 * Port Specific Information:
     792 *
     793 * This method is implemented in C on the v850.
    790794 */
    791795void _CPU_Context_Initialize(
     
    799803
    800804/**
    801  *  This routine is responsible for somehow restarting the currently
    802  *  executing task.  If you are lucky, then all that is necessary
    803  *  is restoring the context.  Otherwise, there will need to be
    804  *  a special assembly routine which does something special in this
    805  *  case.  For many ports, simply adding a label to the restore path
    806  *  of @ref _CPU_Context_switch will work.  On other ports, it may be
    807  *  possibly to load a few arguments and jump to the restore path. It will
    808  *  not work if restarting self conflicts with the stack frame
    809  *  assumptions of restoring a context.
    810  *
    811  *  Port Specific Information:
    812  *
    813  *  On the v850, we require a special entry point to restart a task.
     805 * This routine is responsible for somehow restarting the currently
     806 * executing task.  If you are lucky, then all that is necessary
     807 * is restoring the context.  Otherwise, there will need to be
     808 * a special assembly routine which does something special in this
     809 * case.  For many ports, simply adding a label to the restore path
     810 * of @ref _CPU_Context_switch will work.  On other ports, it may be
     811 * possibly to load a few arguments and jump to the restore path. It will
     812 * not work if restarting self conflicts with the stack frame
     813 * assumptions of restoring a context.
     814 *
     815 * Port Specific Information:
     816 *
     817 * On the v850, we require a special entry point to restart a task.
    814818 */
    815819#define _CPU_Context_Restart_self( _the_context ) \
     
    819823#if 0
    820824/**
    821  *  @ingroup CPUContext
    822  *  The purpose of this macro is to allow the initial pointer into
    823  *  a floating point context area (used to save the floating point
    824  *  context) to be at an arbitrary place in the floating point
    825  *  context area.
    826  *
    827  *  This is necessary because some FP units are designed to have
    828  *  their context saved as a stack which grows into lower addresses.
    829  *  Other FP units can be saved by simply moving registers into offsets
    830  *  from the base of the context area.  Finally some FP units provide
    831  *  a "dump context" instruction which could fill in from high to low
    832  *  or low to high based on the whim of the CPU designers.
    833  *
    834  *  @param[in] _base is the lowest physical address of the floating point
    835  *         context area
    836  *  @param[in] _offset is the offset into the floating point area
    837  *
    838  *  Port Specific Information:
    839  *
    840  *  XXX document implementation including references if appropriate
     825 * @ingroup CPUContext
     826 * The purpose of this macro is to allow the initial pointer into
     827 * a floating point context area (used to save the floating point
     828 * context) to be at an arbitrary place in the floating point
     829 * context area.
     830 *
     831 * This is necessary because some FP units are designed to have
     832 * their context saved as a stack which grows into lower addresses.
     833 * Other FP units can be saved by simply moving registers into offsets
     834 * from the base of the context area.  Finally some FP units provide
     835 * a "dump context" instruction which could fill in from high to low
     836 * or low to high based on the whim of the CPU designers.
     837 *
     838 * @param[in] _base is the lowest physical address of the floating point
     839 *        context area
     840 * @param[in] _offset is the offset into the floating point area
     841 *
     842 * Port Specific Information:
     843 *
     844 * XXX document implementation including references if appropriate
    841845 */
    842846#define _CPU_Context_Fp_start( _base, _offset ) \
     
    847851#if 0
    848852/**
    849  *  This routine initializes the FP context area passed to it to.
    850  *  There are a few standard ways in which to initialize the
    851  *  floating point context.  The code included for this macro assumes
    852  *  that this is a CPU in which a "initial" FP context was saved into
    853  *  @a _CPU_Null_fp_context and it simply copies it to the destination
    854  *  context passed to it.
    855  *
    856  *  Other floating point context save/restore models include:
    857  *    -# not doing anything, and
    858  *    -# putting a "null FP status word" in the correct place in the FP context.
    859  *
    860  *  @param[in] _destination is the floating point context area
    861  *
    862  *  Port Specific Information:
    863  *
    864  *  XXX document implementation including references if appropriate
     853 * This routine initializes the FP context area passed to it to.
     854 * There are a few standard ways in which to initialize the
     855 * floating point context.  The code included for this macro assumes
     856 * that this is a CPU in which a "initial" FP context was saved into
     857 * @a _CPU_Null_fp_context and it simply copies it to the destination
     858 * context passed to it.
     859 *
     860 * Other floating point context save/restore models include:
     861 *   -# not doing anything, and
     862 *   -# putting a "null FP status word" in the correct place in the FP context.
     863 *
     864 * @param[in] _destination is the floating point context area
     865 *
     866 * Port Specific Information:
     867 *
     868 * XXX document implementation including references if appropriate
    865869 */
    866870#define _CPU_Context_Initialize_fp( _destination ) \
     
    874878
    875879/**
    876  *  This routine copies _error into a known place -- typically a stack
    877  *  location or a register, optionally disables interrupts, and
    878  *  halts/stops the CPU.
    879  *
    880  *  Port Specific Information:
    881  *
    882  *  Move the error code into r10, disable interrupts and halt.
     880 * This routine copies _error into a known place -- typically a stack
     881 * location or a register, optionally disables interrupts, and
     882 * halts/stops the CPU.
     883 *
     884 * Port Specific Information:
     885 *
     886 * Move the error code into r10, disable interrupts and halt.
    883887 */
    884888#define _CPU_Fatal_halt( _error ) \
     
    894898
    895899/**
    896  *  @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
    897  *
    898  *  This set of routines are used to implement fast searches for
    899  *  the most important ready task.
    900  */
    901 
    902 /**
    903  *  @ingroup CPUBitfield
    904  *  This definition is set to TRUE if the port uses the generic bitfield
    905  *  manipulation implementation.
     900 * @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
     901 *
     902 * This set of routines are used to implement fast searches for
     903 * the most important ready task.
     904 *
     905 * @{
     906 */
     907
     908/**
     909 * This definition is set to TRUE if the port uses the generic bitfield
     910 * manipulation implementation.
    906911 */
    907912#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
    908913
    909914/**
    910  *  @ingroup CPUBitfield
    911  *  This definition is set to TRUE if the port uses the data tables provided
    912  *  by the generic bitfield manipulation implementation.
    913  *  This can occur when actually using the generic bitfield manipulation
    914  *  implementation or when implementing the same algorithm in assembly
    915  *  language for improved performance.  It is unlikely that a port will use
    916  *  the data if it has a bitfield scan instruction.
    917  *
    918  *  Port Specific Information:
    919  *
    920  *  There is no single v850 instruction to do a bit scan so there is
    921  *  no CPU specific implementation of bit field scanning. The empty
    922  *  stub routines are left as a place holder in case someone figures
    923  *  out how to do a v850 implementation better than the generic algorithm.
     915 * This definition is set to TRUE if the port uses the data tables provided
     916 * by the generic bitfield manipulation implementation.
     917 * This can occur when actually using the generic bitfield manipulation
     918 * implementation or when implementing the same algorithm in assembly
     919 * language for improved performance.  It is unlikely that a port will use
     920 * the data if it has a bitfield scan instruction.
     921 *
     922 * Port Specific Information:
     923 *
     924 * There is no single v850 instruction to do a bit scan so there is
     925 * no CPU specific implementation of bit field scanning. The empty
     926 * stub routines are left as a place holder in case someone figures
     927 * out how to do a v850 implementation better than the generic algorithm.
    924928 */
    925929#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
    926930
    927931/**
    928  *  @ingroup CPUBitfield
    929  *  This routine sets @a _output to the bit number of the first bit
    930  *  set in @a _value.  @a _value is of CPU dependent type
    931  *  @a Priority_bit_map_Control.  This type may be either 16 or 32 bits
    932  *  wide although only the 16 least significant bits will be used.
    933  *
    934  *  There are a number of variables in using a "find first bit" type
    935  *  instruction.
    936  *
    937  *    -# What happens when run on a value of zero?
    938  *    -# Bits may be numbered from MSB to LSB or vice-versa.
    939  *    -# The numbering may be zero or one based.
    940  *    -# The "find first bit" instruction may search from MSB or LSB.
    941  *
    942  *  RTEMS guarantees that (1) will never happen so it is not a concern.
    943  *  (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
    944  *  @ref _CPU_Priority_bits_index.  These three form a set of routines
    945  *  which must logically operate together.  Bits in the _value are
    946  *  set and cleared based on masks built by @ref _CPU_Priority_Mask.
    947  *  The basic major and minor values calculated by @ref _Priority_Major
    948  *  and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
    949  *  to properly range between the values returned by the "find first bit"
    950  *  instruction.  This makes it possible for @ref _Priority_Get_highest to
    951  *  calculate the major and directly index into the minor table.
    952  *  This mapping is necessary to ensure that 0 (a high priority major/minor)
    953  *  is the first bit found.
    954  *
    955  *  This entire "find first bit" and mapping process depends heavily
    956  *  on the manner in which a priority is broken into a major and minor
    957  *  components with the major being the 4 MSB of a priority and minor
    958  *  the 4 LSB.  Thus (0 << 4) + 0 corresponds to priority 0 -- the highest
    959  *  priority.  And (15 << 4) + 14 corresponds to priority 254 -- the next
    960  *  to the lowest priority.
    961  *
    962  *  If your CPU does not have a "find first bit" instruction, then
    963  *  there are ways to make do without it.  Here are a handful of ways
    964  *  to implement this in software:
     932 * This routine sets @a _output to the bit number of the first bit
     933 * set in @a _value.  @a _value is of CPU dependent type
     934 * @a Priority_bit_map_Control.  This type may be either 16 or 32 bits
     935 * wide although only the 16 least significant bits will be used.
     936 *
     937 * There are a number of variables in using a "find first bit" type
     938 * instruction.
     939 *
     940 *   -# What happens when run on a value of zero?
     941 *   -# Bits may be numbered from MSB to LSB or vice-versa.
     942 *   -# The numbering may be zero or one based.
     943 *   -# The "find first bit" instruction may search from MSB or LSB.
     944 *
     945 * RTEMS guarantees that (1) will never happen so it is not a concern.
     946 * (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
     947 * @ref _CPU_Priority_bits_index.  These three form a set of routines
     948 * which must logically operate together.  Bits in the _value are
     949 * set and cleared based on masks built by @ref _CPU_Priority_Mask.
     950 * The basic major and minor values calculated by @ref _Priority_Major
     951 * and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
     952 * to properly range between the values returned by the "find first bit"
     953 * instruction.  This makes it possible for @ref _Priority_Get_highest to
     954 * calculate the major and directly index into the minor table.
     955 * This mapping is necessary to ensure that 0 (a high priority major/minor)
     956 * is the first bit found.
     957 *
     958 * This entire "find first bit" and mapping process depends heavily
     959 * on the manner in which a priority is broken into a major and minor
     960 * components with the major being the 4 MSB of a priority and minor
     961 * the 4 LSB.  Thus (0 << 4) + 0 corresponds to priority 0 -- the highest
     962 * priority.  And (15 << 4) + 14 corresponds to priority 254 -- the next
     963 * to the lowest priority.
     964 *
     965 * If your CPU does not have a "find first bit" instruction, then
     966 * there are ways to make do without it.  Here are a handful of ways
     967 * to implement this in software:
    965968 *
    966969@verbatim
     
    979982@endverbatim
    980983
    981  *    where bit_set_table[ 16 ] has values which indicate the first
    982  *      bit set
    983  *
    984  *  @param[in] _value is the value to be scanned
    985  *  @param[in] _output is the first bit set
    986  *
    987  *  Port Specific Information:
    988  *
    989  *  There is no single v850 instruction to do a bit scan so there is
    990  *  no CPU specific implementation of bit field scanning.
     984 *   where bit_set_table[ 16 ] has values which indicate the first
     985 *     bit set
     986 *
     987 * @param[in] _value is the value to be scanned
     988 * @param[in] _output is the first bit set
     989 *
     990 * Port Specific Information:
     991 *
     992 * There is no single v850 instruction to do a bit scan so there is
     993 * no CPU specific implementation of bit field scanning.
    991994 */
    992995#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    10001003
    10011004/**
    1002  *  This routine builds the mask which corresponds to the bit fields
    1003  *  as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
    1004  *  for that routine.
    1005  *
    1006  *  Port Specific Information:
    1007  *
    1008  *  There is no single v850 instruction to do a bit scan so there is
    1009  *  no CPU specific implementation of bit field scanning.
     1005 * This routine builds the mask which corresponds to the bit fields
     1006 * as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
     1007 * for that routine.
     1008 *
     1009 * Port Specific Information:
     1010 *
     1011 * There is no single v850 instruction to do a bit scan so there is
     1012 * no CPU specific implementation of bit field scanning.
    10101013 */
    10111014#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    10171020
    10181021/**
    1019  *  @ingroup CPUBitfield
    1020  *  This routine translates the bit numbers returned by
    1021  *  @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
    1022  *  a major or minor component of a priority.  See the discussion
    1023  *  for that routine.
    1024  *
    1025  *  @param[in] _priority is the major or minor number to translate
    1026  *
    1027  *  Port Specific Information:
    1028  *
    1029  *  There is no single v850 instruction to do a bit scan so there is
    1030  *  no CPU specific implementation of bit field scanning.
     1022 * This routine translates the bit numbers returned by
     1023 * @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
     1024 * a major or minor component of a priority.  See the discussion
     1025 * for that routine.
     1026 *
     1027 * @param[in] _priority is the major or minor number to translate
     1028 *
     1029 * Port Specific Information:
     1030 *
     1031 * There is no single v850 instruction to do a bit scan so there is
     1032 * no CPU specific implementation of bit field scanning.
    10311033 */
    10321034#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    10391041/* end of Priority handler macros */
    10401042
     1043/** @} */
     1044
    10411045/* functions */
    10421046
    10431047/**
    1044  *  @brief CPU Initialize
    1045  *  This routine performs CPU dependent initialization.
    1046  *
    1047  *  Port Specific Information:
    1048  *
    1049  *  This is implemented in C.
    1050  *
    1051  *  v850 CPU Dependent Source
     1048 * @brief CPU initialize.
     1049 * This routine performs CPU dependent initialization.
     1050 *
     1051 * Port Specific Information:
     1052 *
     1053 * This is implemented in C.
     1054 *
     1055 * v850 CPU Dependent Source
    10521056 */
    10531057void _CPU_Initialize(void);
    10541058
    10551059/**
    1056  *  @ingroup CPUContext
    1057  *  This routine switches from the run context to the heir context.
    1058  *
    1059  *  @param[in] run points to the context of the currently executing task
    1060  *  @param[in] heir points to the context of the heir task
    1061  *
    1062  *  Port Specific Information:
    1063  *
    1064  *  This is implemented in assembly on the v850.
     1060 * @addtogroup CPUContext
     1061 *
     1062 * @{
     1063 */
     1064
     1065/**
     1066 * This routine switches from the run context to the heir context.
     1067 *
     1068 * @param[in] run points to the context of the currently executing task
     1069 * @param[in] heir points to the context of the heir task
     1070 *
     1071 * Port Specific Information:
     1072 *
     1073 * This is implemented in assembly on the v850.
    10651074 */
    10661075void _CPU_Context_switch(
     
    10701079
    10711080/**
    1072  *  @ingroup CPUContext
    1073  *  This routine is generally used only to restart self in an
    1074  *  efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
    1075  *
    1076  *  @param[in] new_context points to the context to be restored.
    1077  *
    1078  *  @note May be unnecessary to reload some registers.
    1079  *
    1080  *  Port Specific Information:
    1081  *
    1082  *  This is implemented in assembly on the v850.
     1081 * This routine is generally used only to restart self in an
     1082 * efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
     1083 *
     1084 * @param[in] new_context points to the context to be restored.
     1085 *
     1086 * @note May be unnecessary to reload some registers.
     1087 *
     1088 * Port Specific Information:
     1089 *
     1090 * This is implemented in assembly on the v850.
    10831091 */
    10841092void _CPU_Context_restore(
     
    10891097#if 0
    10901098/**
    1091  *  @ingroup CPUContext
    1092  *  This routine saves the floating point context passed to it.
    1093  *
    1094  *  @param[in] fp_context_ptr is a pointer to a pointer to a floating
    1095  *  point context area
    1096  *
    1097  *  @return on output @a *fp_context_ptr will contain the address that
    1098  *  should be used with @ref _CPU_Context_restore_fp to restore this context.
    1099  *
    1100  *  Port Specific Information:
    1101  *
    1102  *  XXX document implementation including references if appropriate
     1099 * This routine saves the floating point context passed to it.
     1100 *
     1101 * @param[in] fp_context_ptr is a pointer to a pointer to a floating
     1102 * point context area
     1103 *
     1104 * @return on output @a *fp_context_ptr will contain the address that
     1105 * should be used with @ref _CPU_Context_restore_fp to restore this context.
     1106 *
     1107 * Port Specific Information:
     1108 *
     1109 * XXX document implementation including references if appropriate
    11031110 */
    11041111void _CPU_Context_save_fp(
     
    11101117#if 0
    11111118/**
    1112  *  @ingroup CPUContext
    1113  *  This routine restores the floating point context passed to it.
    1114  *
    1115  *  @param[in] fp_context_ptr is a pointer to a pointer to a floating
    1116  *  point context area to restore
    1117  *
    1118  *  @return on output @a *fp_context_ptr will contain the address that
    1119  *  should be used with @ref _CPU_Context_save_fp to save this context.
    1120  *
    1121  *  Port Specific Information:
    1122  *
    1123  *  XXX document implementation including references if appropriate
     1119 * This routine restores the floating point context passed to it.
     1120 *
     1121 * @param[in] fp_context_ptr is a pointer to a pointer to a floating
     1122 * point context area to restore
     1123 *
     1124 * @return on output @a *fp_context_ptr will contain the address that
     1125 * should be used with @ref _CPU_Context_save_fp to save this context.
     1126 *
     1127 * Port Specific Information:
     1128 *
     1129 * XXX document implementation including references if appropriate
    11241130 */
    11251131void _CPU_Context_restore_fp(
     
    11281134#endif
    11291135
     1136/** @} */
     1137
    11301138/* FIXME */
    11311139typedef CPU_Interrupt_frame CPU_Exception_frame;
     
    11341142
    11351143/**
    1136  *  @ingroup CPUEndian
    1137  *  The following routine swaps the endian format of an unsigned int.
    1138  *  It must be static because it is referenced indirectly.
    1139  *
    1140  *  This version will work on any processor, but if there is a better
    1141  *  way for your CPU PLEASE use it.  The most common way to do this is to:
    1142  *
    1143  *     swap least significant two bytes with 16-bit rotate
    1144  *     swap upper and lower 16-bits
    1145  *     swap most significant two bytes with 16-bit rotate
    1146  *
    1147  *  Some CPUs have special instructions which swap a 32-bit quantity in
    1148  *  a single instruction (e.g. i486).  It is probably best to avoid
    1149  *  an "endian swapping control bit" in the CPU.  One good reason is
    1150  *  that interrupts would probably have to be disabled to ensure that
    1151  *  an interrupt does not try to access the same "chunk" with the wrong
    1152  *  endian.  Another good reason is that on some CPUs, the endian bit
    1153  *  endianness for ALL fetches -- both code and data -- so the code
    1154  *  will be fetched incorrectly.
    1155  *
    1156  *  @param[in] value is the value to be swapped
    1157  *  @return the value after being endian swapped
    1158  *
    1159  *  Port Specific Information:
    1160  *
    1161  *  The v850 has a single instruction to swap endianness on a 32 bit quantity.
     1144 * @ingroup CPUEndian
     1145 * The following routine swaps the endian format of an unsigned int.
     1146 * It must be static because it is referenced indirectly.
     1147 *
     1148 * This version will work on any processor, but if there is a better
     1149 * way for your CPU PLEASE use it.  The most common way to do this is to:
     1150 *
     1151 *    swap least significant two bytes with 16-bit rotate
     1152 *    swap upper and lower 16-bits
     1153 *    swap most significant two bytes with 16-bit rotate
     1154 *
     1155 * Some CPUs have special instructions which swap a 32-bit quantity in
     1156 * a single instruction (e.g. i486).  It is probably best to avoid
     1157 * an "endian swapping control bit" in the CPU.  One good reason is
     1158 * that interrupts would probably have to be disabled to ensure that
     1159 * an interrupt does not try to access the same "chunk" with the wrong
     1160 * endian.  Another good reason is that on some CPUs, the endian bit
     1161 * endianness for ALL fetches -- both code and data -- so the code
     1162 * will be fetched incorrectly.
     1163 *
     1164 * @param[in] value is the value to be swapped
     1165 * @return the value after being endian swapped
     1166 *
     1167 * Port Specific Information:
     1168 *
     1169 * The v850 has a single instruction to swap endianness on a 32 bit quantity.
    11621170 */
    11631171static inline uint32_t CPU_swap_u32(
     
    11861194
    11871195/**
    1188  *  @ingroup CPUEndian
    1189  *  This routine swaps a 16 bir quantity.
    1190  *
    1191  *  @param[in] value is the value to be swapped
    1192  *  @return the value after being endian swapped
    1193  *
    1194  *  Port Specific Information:
    1195  *
    1196  *  The v850 has a single instruction to swap endianness on a 16 bit quantity.
     1196 * @ingroup CPUEndian
     1197 * This routine swaps a 16 bir quantity.
     1198 *
     1199 * @param[in] value is the value to be swapped
     1200 * @return the value after being endian swapped
     1201 *
     1202 * Port Specific Information:
     1203 *
     1204 * The v850 has a single instruction to swap endianness on a 16 bit quantity.
    11971205 */
    11981206static inline uint16_t CPU_swap_u16( uint16_t value )
  • cpukit/score/cpu/v850/rtems/score/types.h

    rf597cc1 r4f5740f  
    11/**
    2  * @file rtems/score/types.h
     2 * @file
     3 *
     4 * @brief V850 CPU Type Definitions
     5 *
     6 * This include file contains type definitions pertaining to the
     7 * v850 processor family.
    38 */
    49
    510/*
    6  *  This include file contains type definitions pertaining to the
    7  *  v850 processor family.
    8  *
    911 *  COPYRIGHT (c) 1989-2011.
    1012 *  On-Line Applications Research Corporation (OAR).
  • cpukit/score/cpu/v850/rtems/score/v850.h

    rf597cc1 r4f5740f  
    1 /*
    2  *  This file sets up basic CPU dependency settings based on
    3  *  compiler settings.  For example, it can determine if
    4  *  floating point is available.  This particular implementation
    5  *  is specified to the Renesas v850 port.
     1/**
     2 * @file
     3 *
     4 * @brief V850 Set up Basic CPU Dependency Settings Based on Compiler Settings
     5 *
     6 * This file sets up basic CPU dependency settings based on
     7 * compiler settings.  For example, it can determine if
     8 * floating point is available.  This particular implementation
     9 * is specified to the Renesas v850 port.
    610 */
    711
Note: See TracChangeset for help on using the changeset viewer.