Changeset baff4da in rtems for cpukit/score/cpu/no_cpu


Ignore:
Timestamp:
Nov 1, 2004, 1:22:41 PM (16 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
e6f664f
Parents:
7ce11b2
Message:

2004-11-01 Joel Sherrill <joel@…>

  • score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/copyrt.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremsg.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/mppkt.inl, score/inline/rtems/score/objectmp.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/states.inl, score/inline/rtems/score/sysstate.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/threadmp.inl, score/inline/rtems/score/tod.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/watchdog.inl, score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working modifications which are not complete and may have broken code. Committing so work and testing can proceed.
  • score/Doxyfile, score/mainpage.h: New files.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/score/cpu/no_cpu/rtems/score/cpu.h

    r7ce11b2 rbaff4da  
    1 /*  cpu.h
     1/** @file  cpu.h
    22 *
    33 *  This include file contains information pertaining to the XXX
    44 *  processor.
    55 *
    6  *  COPYRIGHT (c) 1989-1999.
     6 *  @note This file is part of a porting template that is intended
     7 *  to be used as the starting point when porting RTEMS to a new
     8 *  CPU family.  The following needs to be done when using this as
     9 *  the starting point for a new port:
     10 *
     11 *  + Anywhere there is an XXX, it should be replaced
     12 *    with information about the CPU family being ported to.
     13 * 
     14 *  + At the end of each comment section, there is a heading which
     15 *    says "Port Specific Information:".  When porting to RTEMS,
     16 *    add CPU family specific information in this section
     17 */
     18
     19/*  COPYRIGHT (c) 1989-2004.
    720 *  On-Line Applications Research Corporation (OAR).
    821 *
     
    2841/* conditional compilation parameters */
    2942
    30 /*
    31  *  Should the calls to _Thread_Enable_dispatch be inlined?
     43/**
     44 *  Should the calls to @ref _Thread_Enable_dispatch be inlined?
    3245 *
    3346 *  If TRUE, then they are inlined.
    3447 *  If FALSE, then a subroutine call is made.
    3548 *
    36  *  Basically this is an example of the classic trade-off of size
     49 *  This conditional is an example of the classic trade-off of size
    3750 *  versus speed.  Inlining the call (TRUE) typically increases the
    3851 *  size of RTEMS while speeding up the enabling of dispatching.
    39  *  [NOTE: In general, the _Thread_Dispatch_disable_level will
     52 *
     53 *  @note In general, the @ref _Thread_Dispatch_disable_level will
    4054 *  only be 0 or 1 unless you are in an interrupt handler and that
    4155 *  interrupt handler invokes the executive.]  When not inlined
    42  *  something calls _Thread_Enable_dispatch which in turns calls
    43  *  _Thread_Dispatch.  If the enable dispatch is inlined, then
    44  *  one subroutine call is avoided entirely.]
    45  *
    46  *  NO_CPU Specific Information:
    47  *
    48  *  XXX document implementation including references if appropriate
    49  */
    50 
     56 *  something calls @ref _Thread_Enable_dispatch which in turns calls
     57 *  @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
     58 *  one subroutine call is avoided entirely.
     59 *
     60 *  Port Specific Information:
     61 *
     62 *  XXX document implementation including references if appropriate
     63 */
    5164#define CPU_INLINE_ENABLE_DISPATCH       FALSE
    5265
    53 /*
     66/**
    5467 *  Should the body of the search loops in _Thread_queue_Enqueue_priority
    5568 *  be unrolled one time?  In unrolled each iteration of the loop examines
     
    6881 *  necessary to strike a balance when setting this parameter.
    6982 *
    70  *  NO_CPU Specific Information:
    71  *
    72  *  XXX document implementation including references if appropriate
    73  */
    74 
     83 *  Port Specific Information:
     84 *
     85 *  XXX document implementation including references if appropriate
     86 */
    7587#define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
    7688
    77 /*
     89/**
    7890 *  Does RTEMS manage a dedicated interrupt stack in software?
    7991 *
    80  *  If TRUE, then a stack is allocated in _ISR_Handler_initialization.
     92 *  If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
    8193 *  If FALSE, nothing is done.
    8294 *
     
    90102 *  interrupt stack.
    91103 *
    92  *  If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    93  *
    94  *  Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    95  *  CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     104 *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     105 *
     106 *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     107 *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    96108 *  possible that both are FALSE for a particular CPU.  Although it
    97109 *  is unclear what that would imply about the interrupt processing
    98110 *  procedure on that CPU.
    99111 *
    100  *  NO_CPU Specific Information:
    101  *
    102  *  XXX document implementation including references if appropriate
    103  */
    104 
     112 *  Port Specific Information:
     113 *
     114 *  XXX document implementation including references if appropriate
     115 */
    105116#define CPU_HAS_SOFTWARE_INTERRUPT_STACK FALSE
    106117
    107 /*
     118/**
    108119 *  Does this CPU have hardware support for a dedicated interrupt stack?
    109120 *
     
    111122 *  If FALSE, then no installation is performed.
    112123 *
    113  *  If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
    114  *
    115  *  Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
    116  *  CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
     124 *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
     125 *
     126 *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
     127 *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
    117128 *  possible that both are FALSE for a particular CPU.  Although it
    118129 *  is unclear what that would imply about the interrupt processing
    119130 *  procedure on that CPU.
    120131 *
    121  *  NO_CPU Specific Information:
    122  *
    123  *  XXX document implementation including references if appropriate
    124  */
    125 
     132 *  Port Specific Information:
     133 *
     134 *  XXX document implementation including references if appropriate
     135 */
    126136#define CPU_HAS_HARDWARE_INTERRUPT_STACK TRUE
    127137
    128 /*
     138/**
    129139 *  Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
    130140 *
     
    132142 *  If FALSE, then the memory is allocated during initialization.
    133143 *
    134  *  This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
    135  *  or CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
    136  *
    137  *  NO_CPU Specific Information:
    138  *
    139  *  XXX document implementation including references if appropriate
    140  */
    141 
     144 *  This should be TRUE is @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
     145 *  or @ref CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
     146 *
     147 *  Port Specific Information:
     148 *
     149 *  XXX document implementation including references if appropriate
     150 */
    142151#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
    143152
    144 /*
     153/**
    145154 *  Does the RTEMS invoke the user's ISR with the vector number and
    146155 *  a pointer to the saved interrupt frame (1) or just the vector
    147156 *  number (0)?
    148157 *
    149  *  NO_CPU Specific Information:
    150  *
    151  *  XXX document implementation including references if appropriate
    152  */
    153 
     158 *  Port Specific Information:
     159 *
     160 *  XXX document implementation including references if appropriate
     161 */
    154162#define CPU_ISR_PASSES_FRAME_POINTER 0
    155163
    156 /*
     164/**
     165 *  @def CPU_HARDWARE_FP
     166 *
    157167 *  Does the CPU have hardware floating point?
    158168 *
    159  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
    160  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
     169 *  If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is supported.
     170 *  If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is ignored.
    161171 *
    162172 *  If there is a FP coprocessor such as the i387 or mc68881, then
     
    168178 *  which set this to false to indicate that you have an i386 without
    169179 *  an i387 and wish to leave floating point support out of RTEMS.
    170  *
    171  *  The CPU_SOFTWARE_FP is used to indicate whether or not there
     180 */
     181
     182/**
     183 *  @def CPU_SOFTWARE_FP
     184 *
     185 *  Does the CPU have no hardware floating point and GCC provides a
     186 *  software floating point implementation which must be context
     187 *  switched?
     188 *
     189 *  This feature conditional is used to indicate whether or not there
    172190 *  is software implemented floating point that must be context
    173191 *  switched.  The determination of whether or not this applies
     
    175193 *  compiler specific.
    176194 *
    177  *  NO_CPU Specific Information:
    178  *
    179  *  XXX document implementation including references if appropriate
    180  */
    181 
     195 *  Port Specific Information:
     196 *
     197 *  XXX document implementation including references if appropriate
     198 */
    182199#if ( NO_CPU_HAS_FPU == 1 )
    183200#define CPU_HARDWARE_FP     TRUE
     
    187204#define CPU_SOFTWARE_FP     FALSE
    188205
    189 /*
     206/**
    190207 *  Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
    191208 *
    192  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
    193  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
     209 *  If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is assumed.
     210 *  If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is followed.
    194211 *
    195212 *  So far, the only CPUs in which this option has been used are the
     
    205222 *  In this case, this option should be TRUE.
    206223 *
    207  *  If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
    208  *
    209  *  NO_CPU Specific Information:
    210  *
    211  *  XXX document implementation including references if appropriate
    212  */
    213 
     224 *  If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
     225 *
     226 *  Port Specific Information:
     227 *
     228 *  XXX document implementation including references if appropriate
     229 */
    214230#define CPU_ALL_TASKS_ARE_FP     TRUE
    215231
    216 /*
     232/**
    217233 *  Should the IDLE task have a floating point context?
    218234 *
    219  *  If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
     235 *  If TRUE, then the IDLE task is created as a @ref RTEMS_FLOATING_POINT task
    220236 *  and it has a floating point context which is switched in and out.
    221237 *  If FALSE, then the IDLE task does not have a floating point context.
     
    225241 *  must be saved as part of the preemption.
    226242 *
    227  *  NO_CPU Specific Information:
    228  *
    229  *  XXX document implementation including references if appropriate
    230  */
    231 
     243 *  Port Specific Information:
     244 *
     245 *  XXX document implementation including references if appropriate
     246 */
    232247#define CPU_IDLE_TASK_IS_FP      FALSE
    233248
    234 /*
     249/**
    235250 *  Should the saving of the floating point registers be deferred
    236251 *  until a context switch is made to another different floating point
     
    257272 *  be saved or restored.
    258273 *
    259  *  NO_CPU Specific Information:
    260  *
    261  *  XXX document implementation including references if appropriate
    262  */
    263 
     274 *  Port Specific Information:
     275 *
     276 *  XXX document implementation including references if appropriate
     277 */
    264278#define CPU_USE_DEFERRED_FP_SWITCH       TRUE
    265279
    266 /*
     280/**
    267281 *  Does this port provide a CPU dependent IDLE task implementation?
    268282 *
    269  *  If TRUE, then the routine _CPU_Thread_Idle_body
     283 *  If TRUE, then the routine @ref _CPU_Thread_Idle_body
    270284 *  must be provided and is the default IDLE thread body instead of
    271  *  _CPU_Thread_Idle_body.
     285 *  @ref _CPU_Thread_Idle_body.
    272286 *
    273287 *  If FALSE, then use the generic IDLE thread body if the BSP does
     
    280294 *  The order of precedence for selecting the IDLE thread body is:
    281295 *
    282  *    1.  BSP provided
    283  *    2.  CPU dependent (if provided)
    284  *    3.  generic (if no BSP and no CPU dependent)
    285  *
    286  *  NO_CPU Specific Information:
    287  *
    288  *  XXX document implementation including references if appropriate
    289  */
    290 
     296 *    -#  BSP provided
     297 *    -#  CPU dependent (if provided)
     298 *    -#  generic (if no BSP and no CPU dependent)
     299 *
     300 *  Port Specific Information:
     301 *
     302 *  XXX document implementation including references if appropriate
     303 */
    291304#define CPU_PROVIDES_IDLE_THREAD_BODY    TRUE
    292305
    293 /*
     306/**
    294307 *  Does the stack grow up (toward higher addresses) or down
    295308 *  (toward lower addresses)?
     
    298311 *  If FALSE, then the grows toward smaller addresses.
    299312 *
    300  *  NO_CPU Specific Information:
    301  *
    302  *  XXX document implementation including references if appropriate
    303  */
    304 
     313 *  Port Specific Information:
     314 *
     315 *  XXX document implementation including references if appropriate
     316 */
    305317#define CPU_STACK_GROWS_UP               TRUE
    306318
    307 /*
     319/**
    308320 *  The following is the variable attribute used to force alignment
    309321 *  of critical RTEMS structures.  On some processors it may make
     
    319331 *      __attribute__ ((aligned (32)))
    320332 *
    321  *  NOTE:  Currently only the Priority Bit Map table uses this feature.
    322  *         To benefit from using this, the data must be heavily
    323  *         used so it will stay in the cache and used frequently enough
    324  *         in the executive to justify turning this on.
    325  *
    326  *  NO_CPU Specific Information:
    327  *
    328  *  XXX document implementation including references if appropriate
    329  */
    330 
     333 *  @note Currently only the Priority Bit Map table uses this feature.
     334 *        To benefit from using this, the data must be heavily
     335 *        used so it will stay in the cache and used frequently enough
     336 *        in the executive to justify turning this on.
     337 *
     338 *  Port Specific Information:
     339 *
     340 *  XXX document implementation including references if appropriate
     341 */
    331342#define CPU_STRUCTURE_ALIGNMENT
    332343
    333 /*
     344/**
     345 *  @defgroup CPUEndian Processor Dependent Endianness Support
     346 *
     347 *  This group assists in issues related to processor endianness.
     348 */
     349
     350/**
     351 *  @ingroup CPUEndian
    334352 *  Define what is required to specify how the network to host conversion
    335353 *  routines are handled.
    336354 *
    337  *  NO_CPU Specific Information:
    338  *
    339  *  XXX document implementation including references if appropriate
    340  */
    341 
    342 #define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES     FALSE
     355 *  @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
     356 *  same values.
     357 *
     358 *  @see CPU_LITTLE_ENDIAN
     359 *
     360 *  Port Specific Information:
     361 *
     362 *  XXX document implementation including references if appropriate
     363 */
    343364#define CPU_BIG_ENDIAN                           TRUE
     365
     366/**
     367 *  @ingroup CPUEndian
     368 *  Define what is required to specify how the network to host conversion
     369 *  routines are handled.
     370 *
     371 *  @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
     372 *  same values.
     373 *
     374 *  @see CPU_BIG_ENDIAN
     375 *
     376 *  Port Specific Information:
     377 *
     378 *  XXX document implementation including references if appropriate
     379 */
    344380#define CPU_LITTLE_ENDIAN                        FALSE
    345381
    346 /*
     382/**
     383 *  @ingroup CPUInterrupt
    347384 *  The following defines the number of bits actually used in the
    348385 *  interrupt field of the task mode.  How those bits map to the
    349  *  CPU interrupt levels is defined by the routine _CPU_ISR_Set_level().
    350  *
    351  *  NO_CPU Specific Information:
    352  *
    353  *  XXX document implementation including references if appropriate
    354  */
    355 
     386 *  CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
     387 *
     388 *  Port Specific Information:
     389 *
     390 *  XXX document implementation including references if appropriate
     391 */
    356392#define CPU_MODES_INTERRUPT_MASK   0x00000001
    357393
     
    359395 *  Processor defined structures required for cpukit/score.
    360396 *
    361  *  NO_CPU Specific Information:
     397 *  Port Specific Information:
    362398 *
    363399 *  XXX document implementation including references if appropriate
     
    366402/* may need to put some structures here.  */
    367403
    368 /*
    369  * Contexts
    370  *
    371  *  Generally there are 2 types of context to save.
    372  *     1. Interrupt registers to save
    373  *     2. Task level registers to save
    374  *
    375  *  This means we have the following 3 context items:
    376  *     1. task level context stuff::  Context_Control
    377  *     2. floating point task stuff:: Context_Control_fp
    378  *     3. special interrupt level context :: Context_Control_interrupt
     404/**
     405 * @defgroup CPUContext Processor Dependent Context Management
     406 *
     407 *  From the highest level viewpoint, there are 2 types of context to save.
     408 *
     409 *     -# Interrupt registers to save
     410 *     -# Task level registers to save
     411 *
     412 *  Since RTEMS handles integer and floating point contexts separately, this
     413 *  means we have the following 3 context items:
     414 *
     415 *     -# task level context stuff::  Context_Control
     416 *     -# floating point task stuff:: Context_Control_fp
     417 *     -# special interrupt level context :: CPU_Interrupt_frame
    379418 *
    380419 *  On some processors, it is cost-effective to save only the callee
     
    400439 *  a debugger such as gdb.  But that is another problem.
    401440 *
    402  *  NO_CPU Specific Information:
    403  *
    404  *  XXX document implementation including references if appropriate
    405  */
    406 
     441 *  Port Specific Information:
     442 *
     443 *  XXX document implementation including references if appropriate
     444 */
     445
     446/**
     447 *  @ingroup CPUContext Management
     448 *  This defines the minimal set of integer and processor state registers
     449 *  that must be saved during a voluntary context switch from one thread
     450 *  to another.
     451 */
    407452typedef struct {
     453    /** This field is a hint that a port will have a number of integer
     454     *  registers that need to be saved at a context switch.
     455     */
    408456    uint32_t   some_integer_register;
     457    /** This field is a hint that a port will have a number of system
     458     *  registers that need to be saved at a context switch.
     459     */
    409460    uint32_t   some_system_register;
    410461} Context_Control;
    411462
     463/**
     464 *  @ingroup CPUContext Management
     465 *  This defines the complete set of floating point registers that must
     466 *  be saved during any context switch from one thread to another.
     467 */
    412468typedef struct {
    413469    double      some_float_register;
    414470} Context_Control_fp;
    415471
     472/**
     473 *  @ingroup CPUContext Management
     474 *  This defines the set of integer and processor state registers that must
     475 *  be saved during an interrupt.  This set does not include any which are
     476 *  in @ref Context_Control.
     477 */
    416478typedef struct {
     479    /** This field is a hint that a port will have a number of integer
     480     *  registers that need to be saved when an interrupt occurs or
     481     *  when a context switch occurs at the end of an ISR.
     482     */
    417483    uint32_t   special_interrupt_register;
    418484} CPU_Interrupt_frame;
    419485
    420486
    421 /*
     487/**
    422488 *  The following table contains the information required to configure
    423489 *  the XXX processor specific parameters.
    424490 *
    425  *  NO_CPU Specific Information:
     491 *  Port Specific Information:
    426492 *
    427493 *  XXX document implementation including references if appropriate
     
    429495
    430496typedef struct {
     497  /** This element points to the BSP's pretasking hook. */
    431498  void       (*pretasking_hook)( void );
     499  /** This element points to the BSP's predriver hook. */
    432500  void       (*predriver_hook)( void );
     501  /** This element points to the BSP's postdriver hook. */
    433502  void       (*postdriver_hook)( void );
     503  /** This element points to the BSP's optional idle task which may override
     504   *  the default one provided with RTEMS.
     505   */
    434506  void       (*idle_task)( void );
     507  /** If this element is TRUE, then RTEMS will zero the Executive Workspace.
     508   *  When this element is FALSE, it is assumed that the BSP or invoking
     509   *  environment has ensured that memory was cleared before RTEMS was
     510   *  invoked.
     511   */
    435512  boolean      do_zero_of_workspace;
     513  /** This field specifies the size of the IDLE task's stack.  If less than or
     514   *  equal to the minimum stack size, then the IDLE task will have the minimum
     515   *  stack size.
     516   */
    436517  uint32_t     idle_task_stack_size;
     518  /** This field specifies the size of the interrupt stack.  If less than or
     519   *  equal to the minimum stack size, then the interrupt stack will be of
     520   *  minimum stack size.
     521   */
    437522  uint32_t     interrupt_stack_size;
     523  /** The MPCI Receive server is assumed to have a stack of at least
     524   *  minimum stack size.  This field specifies the amount of extra
     525   *  stack this task will be given in bytes.
     526   */
    438527  uint32_t     extra_mpci_receive_server_stack;
     528  /** The BSP may want to provide it's own stack allocation routines.
     529   *  In this case, the BSP will provide this stack allocation hook.
     530   */
    439531  void *     (*stack_allocate_hook)( uint32_t   );
    440   void       (*stack_free_hook)( void* );
     532  /** The BSP may want to provide it's own stack free routines.
     533   *  In this case, the BSP will provide this stack free hook.
     534   */
     535  void       (*stack_free_hook)( void *);
    441536  /* end of fields required on all CPUs */
    442 
    443537}   rtems_cpu_table;
    444538
     
    447541 *  the file rtems/system.h.
    448542 *
    449  *  NO_CPU Specific Information:
     543 *  Port Specific Information:
    450544 *
    451545 *  XXX document implementation including references if appropriate
     
    455549 *  Macros to access NO_CPU specific additions to the CPU Table
    456550 *
    457  *  NO_CPU Specific Information:
     551 *  Port Specific Information:
    458552 *
    459553 *  XXX document implementation including references if appropriate
     
    462556/* There are no CPU specific additions to the CPU Table for this port. */
    463557
    464 /*
     558/**
    465559 *  This variable is optional.  It is used on CPUs on which it is difficult
    466560 *  to generate an "uninitialized" FP context.  It is filled in by
    467  *  _CPU_Initialize and copied into the task's FP context area during
    468  *  _CPU_Context_Initialize.
    469  *
    470  *  NO_CPU Specific Information:
    471  *
    472  *  XXX document implementation including references if appropriate
    473  */
    474 
     561 *  @ref _CPU_Initialize and copied into the task's FP context area during
     562 *  @ref _CPU_Context_Initialize.
     563 *
     564 *  Port Specific Information:
     565 *
     566 *  XXX document implementation including references if appropriate
     567 */
    475568SCORE_EXTERN Context_Control_fp  _CPU_Null_fp_context;
    476569
    477 /*
     570/**
     571 *  @defgroup CPUInterrupt Processor Dependent Interrupt Management
     572 *
    478573 *  On some CPUs, RTEMS supports a software managed interrupt stack.
    479574 *  This stack is allocated by the Interrupt Manager and the switch
    480  *  is performed in _ISR_Handler.  These variables contain pointers
     575 *  is performed in @ref _ISR_Handler.  These variables contain pointers
    481576 *  to the lowest and highest addresses in the chunk of memory allocated
    482577 *  for the interrupt stack.  Since it is unknown whether the stack
     
    484579 *  code the option of picking the version it wants to use.
    485580 *
    486  *  NOTE: These two variables are required if the macro
    487  *        CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
    488  *
    489  *  NO_CPU Specific Information:
    490  *
    491  *  XXX document implementation including references if appropriate
    492  */
    493 
     581 *  @note These two variables are required if the macro
     582 *        @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
     583 *
     584 *  Port Specific Information:
     585 *
     586 *  XXX document implementation including references if appropriate
     587 */
     588
     589/**
     590 *  @ingroup CPUInterrupt
     591 *  This variable points to the lowest physical address of the interrupt
     592 *  stack.
     593 */
    494594SCORE_EXTERN void               *_CPU_Interrupt_stack_low;
     595
     596/**
     597 *  @ingroup CPUInterrupt
     598 *  This variable points to the lowest physical address of the interrupt
     599 *  stack.
     600 */
    495601SCORE_EXTERN void               *_CPU_Interrupt_stack_high;
    496602
    497 /*
     603/**
     604 *  @ingroup CPUInterrupt
    498605 *  With some compilation systems, it is difficult if not impossible to
    499606 *  call a high-level language routine from assembly language.  This
    500607 *  is especially true of commercial Ada compilers and name mangling
    501608 *  C++ ones.  This variable can be optionally defined by the CPU porter
    502  *  and contains the address of the routine _Thread_Dispatch.  This
     609 *  and contains the address of the routine @ref _Thread_Dispatch.  This
    503610 *  can make it easier to invoke that routine at the end of the interrupt
    504611 *  sequence (if a dispatch is necessary).
    505612 *
    506  *  NO_CPU Specific Information:
    507  *
    508  *  XXX document implementation including references if appropriate
    509  */
    510 
     613 *  Port Specific Information:
     614 *
     615 *  XXX document implementation including references if appropriate
     616 */
    511617SCORE_EXTERN void           (*_CPU_Thread_dispatch_pointer)();
    512618
     
    514620 *  Nothing prevents the porter from declaring more CPU specific variables.
    515621 *
    516  *  NO_CPU Specific Information:
     622 *  Port Specific Information:
    517623 *
    518624 *  XXX document implementation including references if appropriate
     
    521627/* XXX: if needed, put more variables here */
    522628
    523 /*
     629/**
     630 *  @ingroup CPUContext
    524631 *  The size of the floating point context area.  On some CPUs this
    525632 *  will not be a "sizeof" because the format of the floating point
     
    527634 *  CPUs with a "floating point save context" instruction.
    528635 *
    529  *  NO_CPU Specific Information:
    530  *
    531  *  XXX document implementation including references if appropriate
    532  */
    533 
     636 *  Port Specific Information:
     637 *
     638 *  XXX document implementation including references if appropriate
     639 */
    534640#define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
    535641
    536 /*
     642/**
    537643 *  Amount of extra stack (above minimum stack size) required by
    538644 *  MPCI receive server thread.  Remember that in a multiprocessor
    539645 *  system this thread must exist and be able to process all directives.
    540646 *
    541  *  NO_CPU Specific Information:
    542  *
    543  *  XXX document implementation including references if appropriate
    544  */
    545 
     647 *  Port Specific Information:
     648 *
     649 *  XXX document implementation including references if appropriate
     650 */
    546651#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
    547652
    548 /*
    549  *  This defines the number of entries in the ISR_Vector_table managed
     653/**
     654 *  @ingroup CPUInterrupt
     655 *  This defines the number of entries in the @ref _ISR_Vector_table managed
    550656 *  by RTEMS.
    551657 *
    552  *  NO_CPU Specific Information:
    553  *
    554  *  XXX document implementation including references if appropriate
    555  */
    556 
     658 *  Port Specific Information:
     659 *
     660 *  XXX document implementation including references if appropriate
     661 */
    557662#define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
     663
     664/**
     665 *  @ingroup CPUInterrupt
     666 *  This defines the highest interrupt vector number for this port.
     667 */
    558668#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER  (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
    559669
    560 /*
     670/**
     671 *  @ingroup CPUInterrupt
    561672 *  This is defined if the port has a special way to report the ISR nesting
    562  *  level.  Most ports maintain the variable _ISR_Nest_level.
    563  */
    564 
     673 *  level.  Most ports maintain the variable @a _ISR_Nest_level.
     674 */
    565675#define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
    566676
    567 /*
    568  *  Should be large enough to run all RTEMS tests.  This insures
     677/**
     678 *  @ingroup CPUContext
     679 *  Should be large enough to run all RTEMS tests.  This ensures
    569680 *  that a "reasonable" small application should not have any problems.
    570681 *
    571  *  NO_CPU Specific Information:
    572  *
    573  *  XXX document implementation including references if appropriate
    574  */
    575 
     682 *  Port Specific Information:
     683 *
     684 *  XXX document implementation including references if appropriate
     685 */
    576686#define CPU_STACK_MINIMUM_SIZE          (1024*4)
    577687
    578 /*
     688/**
    579689 *  CPU's worst alignment requirement for data types on a byte boundary.  This
    580690 *  alignment does not take into account the requirements for the stack.
    581691 *
    582  *  NO_CPU Specific Information:
    583  *
    584  *  XXX document implementation including references if appropriate
    585  */
    586 
     692 *  Port Specific Information:
     693 *
     694 *  XXX document implementation including references if appropriate
     695 */
    587696#define CPU_ALIGNMENT              8
    588697
    589 /*
     698/**
    590699 *  This number corresponds to the byte alignment requirement for the
    591700 *  heap handler.  This alignment requirement may be stricter than that
    592  *  for the data types alignment specified by CPU_ALIGNMENT.  It is
     701 *  for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
    593702 *  common for the heap to follow the same alignment requirement as
    594  *  CPU_ALIGNMENT.  If the CPU_ALIGNMENT is strict enough for the heap,
    595  *  then this should be set to CPU_ALIGNMENT.
    596  *
    597  *  NOTE:  This does not have to be a power of 2 although it should be
     703 *  @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
     704 *  the heap, then this should be set to @ref CPU_ALIGNMENT.
     705 *
     706 *  @note  This does not have to be a power of 2 although it should be
    598707 *         a multiple of 2 greater than or equal to 2.  The requirement
    599708 *         to be a multiple of 2 is because the heap uses the least
     
    602711 *         length blocks really putting length data in that bit.
    603712 *
    604  *         On byte oriented architectures, CPU_HEAP_ALIGNMENT normally will
    605  *         have to be greater or equal to than CPU_ALIGNMENT to ensure that
     713 *         On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
     714 *         have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
    606715 *         elements allocated from the heap meet all restrictions.
    607716 *
    608  *  NO_CPU Specific Information:
    609  *
    610  *  XXX document implementation including references if appropriate
    611  */
    612 
     717 *  Port Specific Information:
     718 *
     719 *  XXX document implementation including references if appropriate
     720 */
    613721#define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
    614722
    615 /*
     723/**
    616724 *  This number corresponds to the byte alignment requirement for memory
    617725 *  buffers allocated by the partition manager.  This alignment requirement
    618726 *  may be stricter than that for the data types alignment specified by
    619  *  CPU_ALIGNMENT.  It is common for the partition to follow the same
    620  *  alignment requirement as CPU_ALIGNMENT.  If the CPU_ALIGNMENT is strict
    621  *  enough for the partition, then this should be set to CPU_ALIGNMENT.
    622  *
    623  *  NOTE:  This does not have to be a power of 2.  It does have to
    624  *         be greater or equal to than CPU_ALIGNMENT.
    625  *
    626  *  NO_CPU Specific Information:
    627  *
    628  *  XXX document implementation including references if appropriate
    629  */
    630 
     727 *  @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
     728 *  alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
     729 *  strict enough for the partition, then this should be set to
     730 *  @ref CPU_ALIGNMENT.
     731 *
     732 *  @note  This does not have to be a power of 2.  It does have to
     733 *         be greater or equal to than @ref CPU_ALIGNMENT.
     734 *
     735 *  Port Specific Information:
     736 *
     737 *  XXX document implementation including references if appropriate
     738 */
    631739#define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
    632740
    633 /*
     741/**
    634742 *  This number corresponds to the byte alignment requirement for the
    635743 *  stack.  This alignment requirement may be stricter than that for the
    636  *  data types alignment specified by CPU_ALIGNMENT.  If the CPU_ALIGNMENT
    637  *  is strict enough for the stack, then this should be set to 0.
    638  *
    639  *  NOTE:  This must be a power of 2 either 0 or greater than CPU_ALIGNMENT.
    640  *
    641  *  NO_CPU Specific Information:
    642  *
    643  *  XXX document implementation including references if appropriate
    644  */
    645 
     744 *  data types alignment specified by @ref CPU_ALIGNMENT.  If the
     745 *  @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
     746 *  set to 0.
     747 *
     748 *  @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
     749 *
     750 *  Port Specific Information:
     751 *
     752 *  XXX document implementation including references if appropriate
     753 */
    646754#define CPU_STACK_ALIGNMENT        0
    647755
     
    650758 */
    651759
    652 /*
     760/**
     761 *  @ingroup CPUInterrupt
    653762 *  Support routine to initialize the RTEMS vector table after it is allocated.
    654763 *
    655  *  NO_CPU Specific Information:
    656  *
    657  *  XXX document implementation including references if appropriate
    658  */
    659 
     764 *  Port Specific Information:
     765 *
     766 *  XXX document implementation including references if appropriate
     767 */
    660768#define _CPU_Initialize_vectors()
    661769
    662 /*
     770/**
     771 *  @ingroup CPUInterrupt
    663772 *  Disable all interrupts for an RTEMS critical section.  The previous
    664  *  level is returned in _level.
    665  *
    666  *  NO_CPU Specific Information:
    667  *
    668  *  XXX document implementation including references if appropriate
    669  */
    670 
     773 *  level is returned in @a _isr_cookie.
     774 *
     775 *  @param _isr_cookie (out) will contain the previous level cookie
     776 *
     777 *  Port Specific Information:
     778 *
     779 *  XXX document implementation including references if appropriate
     780 */
    671781#define _CPU_ISR_Disable( _isr_cookie ) \
    672782  { \
     
    674784  }
    675785
    676 /*
     786/**
     787 *  @ingroup CPUInterrupt
    677788 *  Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
    678789 *  This indicates the end of an RTEMS critical section.  The parameter
    679  *  _level is not modified.
    680  *
    681  *  NO_CPU Specific Information:
    682  *
    683  *  XXX document implementation including references if appropriate
    684  */
    685 
     790 *  @a _isr_cookie is not modified.
     791 *
     792 *  @param _isr_cookie (in) contain the previous level cookie
     793 *
     794 *  Port Specific Information:
     795 *
     796 *  XXX document implementation including references if appropriate
     797 */
    686798#define _CPU_ISR_Enable( _isr_cookie )  \
    687799  { \
    688800  }
    689801
    690 /*
    691  *  This temporarily restores the interrupt to _level before immediately
     802/**
     803 *  @ingroup CPUInterrupt
     804 *  This temporarily restores the interrupt to @a _isr_cookie before immediately
    692805 *  disabling them again.  This is used to divide long RTEMS critical
    693  *  sections into two or more parts.  The parameter _level is not
    694  * modified.
    695  *
    696  *  NO_CPU Specific Information:
    697  *
    698  *  XXX document implementation including references if appropriate
    699  */
    700 
     806 *  sections into two or more parts.  The parameter @a _isr_cookie is not
     807 *  modified.
     808 *
     809 *  @param _isr_cookie (in) contain the previous level cookie
     810 *
     811 *  Port Specific Information:
     812 *
     813 *  XXX document implementation including references if appropriate
     814 */
    701815#define _CPU_ISR_Flash( _isr_cookie ) \
    702816  { \
    703817  }
    704818
    705 /*
    706  *  Map interrupt level in task mode onto the hardware that the CPU
     819/**
     820 *  @ingroup CPUInterrupt
     821 *
     822 *  This routine and @ref _CPU_ISR_Get_level
     823 *  Map the interrupt level in task mode onto the hardware that the CPU
    707824 *  actually provides.  Currently, interrupt levels which do not
    708825 *  map onto the CPU in a generic fashion are undefined.  Someday,
     
    713830 *  via the rtems_task_mode directive.
    714831 *
    715  *  The get routine usually must be implemented as a subroutine.
    716  *
    717  *  NO_CPU Specific Information:
    718  *
    719  *  XXX document implementation including references if appropriate
    720  */
    721 
     832 *  Port Specific Information:
     833 *
     834 *  XXX document implementation including references if appropriate
     835 */
    722836#define _CPU_ISR_Set_level( new_level ) \
    723837  { \
    724838  }
    725839
     840/**
     841 *  @ingroup CPUInterrupt
     842 *  Return the current interrupt disable level for this task in
     843 *  the format used by the interrupt level portion of the task mode.
     844 *
     845 *  @note This routine usually must be implemented as a subroutine.
     846 *
     847 *  Port Specific Information:
     848 *
     849 *  XXX document implementation including references if appropriate
     850 */
    726851uint32_t   _CPU_ISR_Get_level( void );
    727852
     
    730855/* Context handler macros */
    731856
    732 /*
     857/**
     858 *  @ingroup CPUContext
    733859 *  Initialize the context to a state suitable for starting a
    734860 *  task after a context restore operation.  Generally, this
     
    745871 *  undefined at task start time.
    746872 *
    747  *  NOTE: This is_fp parameter is TRUE if the thread is to be a floating
     873 *  @param _the_context (in) is the context structure to be initialized
     874 *  @param _stack_base (in) is the lowest physical address of this task's stack
     875 *  @param _size (in) is the size of this task's stack
     876 *  @param _isr (in) is the interrupt disable level
     877 *  @param _entry_point (in) is the thread's entry point.  This is
     878 *         always @a _Thread_Handler
     879 *  @param _is_fp (in) is TRUE if the thread is to be a floating
    748880 *        point thread.  This is typically only used on CPUs where the
    749881 *        FPU may be easily disabled by software such as on the SPARC
    750882 *        where the PSR contains an enable FPU bit.
    751883 *
    752  *  NO_CPU Specific Information:
    753  *
    754  *  XXX document implementation including references if appropriate
    755  */
    756 
     884 *  Port Specific Information:
     885 *
     886 *  XXX document implementation including references if appropriate
     887 */
    757888#define _CPU_Context_Initialize( _the_context, _stack_base, _size, \
    758889                                 _isr, _entry_point, _is_fp ) \
     
    765896 *  is restoring the context.  Otherwise, there will need to be
    766897 *  a special assembly routine which does something special in this
    767  *  case.  Context_Restore should work most of the time.  It will
     898 *  case.  @ref _CPU_Context_Restore should work most of the time.  It will
    768899 *  not work if restarting self conflicts with the stack frame
    769900 *  assumptions of restoring a context.
    770901 *
    771  *  NO_CPU Specific Information:
    772  *
    773  *  XXX document implementation including references if appropriate
    774  */
    775 
     902 *  Port Specific Information:
     903 *
     904 *  XXX document implementation including references if appropriate
     905 */
    776906#define _CPU_Context_Restart_self( _the_context ) \
    777907   _CPU_Context_restore( (_the_context) );
    778908
    779 /*
     909/**
     910 *  @ingroup CPUContext
    780911 *  The purpose of this macro is to allow the initial pointer into
    781912 *  a floating point context area (used to save the floating point
     
    790921 *  or low to high based on the whim of the CPU designers.
    791922 *
    792  *  NO_CPU Specific Information:
    793  *
    794  *  XXX document implementation including references if appropriate
    795  */
    796 
     923 *  @param _base (in) is the lowest physical address of the floating point
     924 *         context area
     925 *  @param _offset (in) is the offset into the floating point area
     926 *
     927 *  Port Specific Information:
     928 *
     929 *  XXX document implementation including references if appropriate
     930 */
    797931#define _CPU_Context_Fp_start( _base, _offset ) \
    798932   ( (void *) _Addresses_Add_offset( (_base), (_offset) ) )
    799933
    800 /*
     934/**
    801935 *  This routine initializes the FP context area passed to it to.
    802936 *  There are a few standard ways in which to initialize the
    803937 *  floating point context.  The code included for this macro assumes
    804938 *  that this is a CPU in which a "initial" FP context was saved into
    805  *  _CPU_Null_fp_context and it simply copies it to the destination
     939 *  @a _CPU_Null_fp_context and it simply copies it to the destination
    806940 *  context passed to it.
    807941 *
    808  *  Other models include (1) not doing anything, and (2) putting
    809  *  a "null FP status word" in the correct place in the FP context.
    810  *
    811  *  NO_CPU Specific Information:
    812  *
    813  *  XXX document implementation including references if appropriate
    814  */
    815 
     942 *  Other floating point context save/restore models include:
     943 *    -# not doing anything, and
     944 *    -# putting a "null FP status word" in the correct place in the FP context.
     945 *
     946 *  @param _destination (in) is the floating point context area
     947 *
     948 *  Port Specific Information:
     949 *
     950 *  XXX document implementation including references if appropriate
     951 */
    816952#define _CPU_Context_Initialize_fp( _destination ) \
    817953  { \
     
    823959/* Fatal Error manager macros */
    824960
    825 /*
     961/**
    826962 *  This routine copies _error into a known place -- typically a stack
    827963 *  location or a register, optionally disables interrupts, and
    828964 *  halts/stops the CPU.
    829965 *
    830  *  NO_CPU Specific Information:
    831  *
    832  *  XXX document implementation including references if appropriate
    833  */
    834 
     966 *  Port Specific Information:
     967 *
     968 *  XXX document implementation including references if appropriate
     969 */
    835970#define _CPU_Fatal_halt( _error ) \
    836971  { \
     
    841976/* Bitfield handler macros */
    842977
    843 /*
    844  *  This routine sets _output to the bit number of the first bit
    845  *  set in _value.  _value is of CPU dependent type Priority_Bit_map_control.
    846  *  This type may be either 16 or 32 bits wide although only the 16
    847  *  least significant bits will be used.
     978/**
     979 *  @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
     980 *
     981 *  This set of routines are used to implement fast searches for
     982 *  the most important ready task.
     983 */
     984
     985/**
     986 *  @ingroup CPUBitfield
     987 *  This definition is set to TRUE if the port uses the generic bitfield
     988 *  manipulation implementation.
     989 */
     990#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
     991
     992/**
     993 *  @ingroup CPUBitfield
     994 *  This definition is set to TRUE if the port uses the data tables provided
     995 *  by the generic bitfield manipulation implementation.
     996 *  This can occur when actually using the generic bitfield manipulation
     997 *  implementation or when implementing the same algorithm in assembly
     998 *  language for improved performance.  It is unlikely that a port will use
     999 *  the data if it has a bitfield scan instruction.
     1000 */
     1001#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
     1002
     1003/**
     1004 *  @ingroup CPUBitfield
     1005 *  This routine sets @a _output to the bit number of the first bit
     1006 *  set in @a _value.  @a _value is of CPU dependent type
     1007 *  @a Priority_Bit_map_control.  This type may be either 16 or 32 bits
     1008 *  wide although only the 16 least significant bits will be used.
    8481009 *
    8491010 *  There are a number of variables in using a "find first bit" type
    8501011 *  instruction.
    8511012 *
    852  *    (1) What happens when run on a value of zero?
    853  *    (2) Bits may be numbered from MSB to LSB or vice-versa.
    854  *    (3) The numbering may be zero or one based.
    855  *    (4) The "find first bit" instruction may search from MSB or LSB.
     1013 *    -# What happens when run on a value of zero?
     1014 *    -# Bits may be numbered from MSB to LSB or vice-versa.
     1015 *    -# The numbering may be zero or one based.
     1016 *    -# The "find first bit" instruction may search from MSB or LSB.
    8561017 *
    8571018 *  RTEMS guarantees that (1) will never happen so it is not a concern.
    858  *  (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
    859  *  _CPU_Priority_bits_index().  These three form a set of routines
     1019 *  (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
     1020 *  @ref _CPU_Priority_bits_index.  These three form a set of routines
    8601021 *  which must logically operate together.  Bits in the _value are
    861  *  set and cleared based on masks built by _CPU_Priority_mask().
    862  *  The basic major and minor values calculated by _Priority_Major()
    863  *  and _Priority_Minor() are "massaged" by _CPU_Priority_bits_index()
     1022 *  set and cleared based on masks built by @ref _CPU_Priority_Mask.
     1023 *  The basic major and minor values calculated by @ref _Priority_Major
     1024 *  and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
    8641025 *  to properly range between the values returned by the "find first bit"
    865  *  instruction.  This makes it possible for _Priority_Get_highest() to
     1026 *  instruction.  This makes it possible for @ref _Priority_Get_highest to
    8661027 *  calculate the major and directly index into the minor table.
    8671028 *  This mapping is necessary to ensure that 0 (a high priority major/minor)
     
    8791040 *  to implement this in software:
    8801041 *
    881  *    - a series of 16 bit test instructions
    882  *    - a "binary search using if's"
    883  *    - _number = 0
    884  *      if _value > 0x00ff
    885  *        _value >>=8
    886  *        _number = 8;
    887  *
    888  *      if _value > 0x0000f
    889  *        _value >=8
    890  *        _number += 4
    891  *
    892  *      _number += bit_set_table[ _value ]
    893  *
     1042@verbatim
     1043      - a series of 16 bit test instructions
     1044      - a "binary search using if's"
     1045      - _number = 0
     1046        if _value > 0x00ff
     1047          _value >>=8
     1048          _number = 8;
     1049 
     1050        if _value > 0x0000f
     1051          _value >=8
     1052          _number += 4
     1053 
     1054        _number += bit_set_table[ _value ]
     1055@endverbatim
     1056 
    8941057 *    where bit_set_table[ 16 ] has values which indicate the first
    8951058 *      bit set
    8961059 *
    897  *  NO_CPU Specific Information:
    898  *
    899  *  XXX document implementation including references if appropriate
    900  */
    901 
    902 #define CPU_USE_GENERIC_BITFIELD_CODE TRUE
    903 #define CPU_USE_GENERIC_BITFIELD_DATA TRUE
     1060 *  @param _value (in) is the value to be scanned
     1061 *  @param _output (in) is the first bit set
     1062 *
     1063 *  Port Specific Information:
     1064 *
     1065 *  XXX document implementation including references if appropriate
     1066 */
    9041067
    9051068#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    906 
    9071069#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
    9081070  { \
    9091071    (_output) = 0;   /* do something to prevent warnings */ \
    9101072  }
    911 
    9121073#endif
    9131074
    9141075/* end of Bitfield handler macros */
    9151076
    916 /*
     1077/**
    9171078 *  This routine builds the mask which corresponds to the bit fields
    918  *  as searched by _CPU_Bitfield_Find_first_bit().  See the discussion
     1079 *  as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
    9191080 *  for that routine.
    9201081 *
    921  *  NO_CPU Specific Information:
    922  *
    923  *  XXX document implementation including references if appropriate
    924  */
    925 
     1082 *  Port Specific Information:
     1083 *
     1084 *  XXX document implementation including references if appropriate
     1085 */
    9261086#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    9271087
     
    9311091#endif
    9321092
    933 /*
     1093/**
     1094 *  @ingroup CPUBitfield
    9341095 *  This routine translates the bit numbers returned by
    935  *  _CPU_Bitfield_Find_first_bit() into something suitable for use as
     1096 *  @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
    9361097 *  a major or minor component of a priority.  See the discussion
    9371098 *  for that routine.
    9381099 *
    939  *  NO_CPU Specific Information:
    940  *
    941  *  XXX document implementation including references if appropriate
    942  */
    943 
     1100 *  @param _priority (in) is the major or minor number to translate
     1101 *
     1102 *  Port Specific Information:
     1103 *
     1104 *  XXX document implementation including references if appropriate
     1105 */
    9441106#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    9451107
     
    9531115/* functions */
    9541116
    955 /*
    956  *  _CPU_Initialize
    957  *
     1117/**
    9581118 *  This routine performs CPU dependent initialization.
    9591119 *
    960  *  NO_CPU Specific Information:
    961  *
    962  *  XXX document implementation including references if appropriate
    963  */
    964 
     1120 *  @param cpu_table (in) is the CPU Dependent Configuration Table
     1121 *  @param thread_dispatch (in) is the address of @ref _Thread_Dispatch
     1122 *
     1123 *  Port Specific Information:
     1124 *
     1125 *  XXX document implementation including references if appropriate
     1126 */
    9651127void _CPU_Initialize(
    9661128  rtems_cpu_table  *cpu_table,
     
    9681130);
    9691131
    970 /*
    971  *  _CPU_ISR_install_raw_handler
    972  *
     1132/**
     1133 *  @ingroup CPUInterrupt
    9731134 *  This routine installs a "raw" interrupt handler directly into the
    9741135 *  processor's vector table.
    9751136 *
    976  *  NO_CPU Specific Information:
    977  *
    978  *  XXX document implementation including references if appropriate
    979  */
    980  
     1137 *  @param vector (in) is the vector number
     1138 *  @param new_handler (in) is the raw ISR handler to install
     1139 *  @param old_handler (in) is the previously installed ISR Handler
     1140 *
     1141 *  Port Specific Information:
     1142 *
     1143 *  XXX document implementation including references if appropriate
     1144 */
    9811145void _CPU_ISR_install_raw_handler(
    9821146  uint32_t    vector,
     
    9851149);
    9861150
    987 /*
    988  *  _CPU_ISR_install_vector
    989  *
     1151/**
     1152 *  @ingroup CPUInterrupt
    9901153 *  This routine installs an interrupt vector.
    9911154 *
    992  *  NO_CPU Specific Information:
    993  *
    994  *  XXX document implementation including references if appropriate
    995  */
    996 
     1155 *  @param vector (in) is the vector number
     1156 *  @param new_handler (in) is the RTEMS ISR handler to install
     1157 *  @param old_handler (in) is the previously installed ISR Handler
     1158 *
     1159 *  Port Specific Information:
     1160 *
     1161 *  XXX document implementation including references if appropriate
     1162 */
    9971163void _CPU_ISR_install_vector(
    9981164  uint32_t    vector,
     
    10011167);
    10021168
    1003 /*
    1004  *  _CPU_Install_interrupt_stack
    1005  *
     1169/**
     1170 *  @ingroup CPUInterrupt
    10061171 *  This routine installs the hardware interrupt stack pointer.
    10071172 *
    1008  *  NOTE:  It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STACK
     1173 *  @note  It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK
    10091174 *         is TRUE.
    10101175 *
    1011  *  NO_CPU Specific Information:
    1012  *
    1013  *  XXX document implementation including references if appropriate
    1014  */
    1015 
     1176 *  Port Specific Information:
     1177 *
     1178 *  XXX document implementation including references if appropriate
     1179 */
    10161180void _CPU_Install_interrupt_stack( void );
    10171181
    1018 /*
    1019  *  _CPU_Thread_Idle_body
    1020  *
     1182/**
    10211183 *  This routine is the CPU dependent IDLE thread body.
    10221184 *
    1023  *  NOTE:  It need only be provided if CPU_PROVIDES_IDLE_THREAD_BODY
     1185 *  @note  It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY
    10241186 *         is TRUE.
    10251187 *
    1026  *  NO_CPU Specific Information:
    1027  *
    1028  *  XXX document implementation including references if appropriate
    1029  */
    1030 
     1188 *  Port Specific Information:
     1189 *
     1190 *  XXX document implementation including references if appropriate
     1191 */
    10311192void _CPU_Thread_Idle_body( void );
    10321193
    1033 /*
    1034  *  _CPU_Context_switch
    1035  *
     1194/**
     1195 *  @ingroup CPUContext
    10361196 *  This routine switches from the run context to the heir context.
    10371197 *
    1038  *  NO_CPU Specific Information:
    1039  *
    1040  *  XXX document implementation including references if appropriate
    1041  */
    1042 
     1198 *  @param run (in) points to the context of the currently executing task
     1199 *  @param heir (in) points to the context of the heir task
     1200 *
     1201 *  Port Specific Information:
     1202 *
     1203 *  XXX document implementation including references if appropriate
     1204 */
    10431205void _CPU_Context_switch(
    10441206  Context_Control  *run,
     
    10461208);
    10471209
    1048 /*
    1049  *  _CPU_Context_restore
    1050  *
     1210/**
     1211 *  @ingroup CPUContext
    10511212 *  This routine is generally used only to restart self in an
    1052  *  efficient manner.  It may simply be a label in _CPU_Context_switch.
    1053  *
    1054  *  NOTE: May be unnecessary to reload some registers.
    1055  *
    1056  *  NO_CPU Specific Information:
    1057  *
    1058  *  XXX document implementation including references if appropriate
    1059  */
    1060 
     1213 *  efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
     1214 *
     1215 *  @param new_context (in) points to the context to be restored.
     1216 *
     1217 *  @note May be unnecessary to reload some registers.
     1218 *
     1219 *  Port Specific Information:
     1220 *
     1221 *  XXX document implementation including references if appropriate
     1222 */
    10611223void _CPU_Context_restore(
    10621224  Context_Control *new_context
    10631225);
    10641226
    1065 /*
    1066  *  _CPU_Context_save_fp
    1067  *
     1227/**
     1228 *  @ingroup CPUContext
    10681229 *  This routine saves the floating point context passed to it.
    10691230 *
    1070  *  NO_CPU Specific Information:
    1071  *
    1072  *  XXX document implementation including references if appropriate
    1073  */
    1074 
     1231 *  @param fp_context_ptr (in) is a pointer to a pointer to a floating
     1232 *  point context area
     1233 *
     1234 *  @return on output @a *fp_context_ptr will contain the address that
     1235 *  should be used with @ref _CPU_Context_restore_fp to restore this context.
     1236 *
     1237 *  Port Specific Information:
     1238 *
     1239 *  XXX document implementation including references if appropriate
     1240 */
    10751241void _CPU_Context_save_fp(
    10761242  void **fp_context_ptr
    10771243);
    10781244
    1079 /*
    1080  *  _CPU_Context_restore_fp
    1081  *
     1245/**
     1246 *  @ingroup CPUContext
    10821247 *  This routine restores the floating point context passed to it.
    10831248 *
    1084  *  NO_CPU Specific Information:
    1085  *
    1086  *  XXX document implementation including references if appropriate
    1087  */
    1088 
     1249 *  @param fp_context_ptr (in) is a pointer to a pointer to a floating
     1250 *  point context area to restore
     1251 *
     1252 *  @return on output @a *fp_context_ptr will contain the address that
     1253 *  should be used with @ref _CPU_Context_save_fp to save this context.
     1254 *
     1255 *  Port Specific Information:
     1256 *
     1257 *  XXX document implementation including references if appropriate
     1258 */
    10891259void _CPU_Context_restore_fp(
    10901260  void **fp_context_ptr
    10911261);
    10921262
    1093 /*  The following routine swaps the endian format of an unsigned int.
     1263/**
     1264 *  @ingroup CPUEndian
     1265 *  The following routine swaps the endian format of an unsigned int.
    10941266 *  It must be static because it is referenced indirectly.
    10951267 *
     
    11101282 *  will be fetched incorrectly.
    11111283 *
    1112  *  NO_CPU Specific Information:
    1113  *
    1114  *  XXX document implementation including references if appropriate
    1115  */
    1116  
     1284 *  @param value (in) is the value to be swapped
     1285 *  @return the value after being endian swapped
     1286 *
     1287 *  Port Specific Information:
     1288 *
     1289 *  XXX document implementation including references if appropriate
     1290 */
    11171291static inline unsigned int CPU_swap_u32(
    11181292  unsigned int value
     
    11301304}
    11311305
     1306/**
     1307 *  @ingroup CPUEndian
     1308 *  This routine swaps a 16 bir quantity.
     1309 *
     1310 *  @param value (in) is the value to be swapped
     1311 *  @return the value after being endian swapped
     1312 */
    11321313#define CPU_swap_u16( value ) \
    11331314  (((value&0xff) << 8) | ((value >> 8)&0xff))
Note: See TracChangeset for help on using the changeset viewer.