Changeset baff4da in rtems


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, 5, 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.
Location:
cpukit
Files:
2 added
53 edited

Legend:

Unmodified
Added
Removed
  • cpukit/ChangeLog

    r7ce11b2 rbaff4da  
     12004-11-01      Joel Sherrill <joel@oarcorp.com>
     2
     3        * score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h,
     4        score/include/rtems/seterr.h, score/include/rtems/system.h,
     5        score/include/rtems/score/address.h,
     6        score/include/rtems/score/apiext.h,
     7        score/include/rtems/score/apimutex.h,
     8        score/include/rtems/score/bitfield.h,
     9        score/include/rtems/score/chain.h,
     10        score/include/rtems/score/context.h,
     11        score/include/rtems/score/copyrt.h,
     12        score/include/rtems/score/coremsg.h,
     13        score/include/rtems/score/coremutex.h,
     14        score/include/rtems/score/coresem.h,
     15        score/include/rtems/score/heap.h, score/include/rtems/score/interr.h,
     16        score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h,
     17        score/include/rtems/score/mppkt.h,
     18        score/include/rtems/score/objectmp.h,
     19        score/include/rtems/score/priority.h,
     20        score/include/rtems/score/stack.h,
     21        score/include/rtems/score/states.h,
     22        score/include/rtems/score/sysstate.h,
     23        score/include/rtems/score/thread.h,
     24        score/include/rtems/score/threadmp.h,
     25        score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h,
     26        score/include/rtems/score/tqdata.h,
     27        score/include/rtems/score/userext.h,
     28        score/include/rtems/score/watchdog.h,
     29        score/include/rtems/score/wkspace.h,
     30        score/inline/rtems/score/address.inl,
     31        score/inline/rtems/score/chain.inl,
     32        score/inline/rtems/score/coremsg.inl,
     33        score/inline/rtems/score/coremutex.inl,
     34        score/inline/rtems/score/coresem.inl,
     35        score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl,
     36        score/inline/rtems/score/mppkt.inl,
     37        score/inline/rtems/score/objectmp.inl,
     38        score/inline/rtems/score/priority.inl,
     39        score/inline/rtems/score/stack.inl,
     40        score/inline/rtems/score/states.inl,
     41        score/inline/rtems/score/sysstate.inl,
     42        score/inline/rtems/score/thread.inl,
     43        score/inline/rtems/score/threadmp.inl,
     44        score/inline/rtems/score/tod.inl,
     45        score/inline/rtems/score/tqdata.inl,
     46        score/inline/rtems/score/userext.inl,
     47        score/inline/rtems/score/watchdog.inl,
     48        score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working
     49        modifications which are not complete and may have broken code.
     50        Committing so work and testing can proceed.
     51        * score/Doxyfile, score/mainpage.h: New files.
     52
    1532004-11-01      Joel Sherrill <joel@oarcorp.com>
    254
  • 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))
  • cpukit/score/include/rtems/debug.h

    r7ce11b2 rbaff4da  
    1 /*  debug.h
     1/**
     2 *  @file debug.h
    23 *
    34 *  This include file contains the information pertaining to the debug
    45 *  support within RTEMS.  It is currently cast in the form of a
    56 *  Manager since it is externally accessible.
    6  *
    7  *
    8  *  COPYRIGHT (c) 1989-1999.
     7 */
     8
     9/*
     10 *  COPYRIGHT (c) 1989-2004.
    911 *  On-Line Applications Research Corporation (OAR).
    1012 *
  • cpukit/score/include/rtems/score/address.h

    r7ce11b2 rbaff4da  
    1 /*  address.h
     1/**
     2 *  @file address.h
    23 *
    34 *  This include file contains the information required to manipulate
    45 *  physical addresses.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1720#define __RTEMS_ADDRESSES_h
    1821
     22/**
     23 *  @defgroup ScoreAddress Address Handler
     24 *
     25 *  This group contains functionality which abstracts address manipulation
     26 *  in a portable manner.
     27 */
     28/**@{*/
     29
    1930#ifdef __cplusplus
    2031extern "C" {
     
    2738#endif
    2839
     40/**@}*/
     41
    2942#endif
    3043/* end of include file */
  • cpukit/score/include/rtems/score/apiext.h

    r7ce11b2 rbaff4da  
    1 /*  apiext.h
     1/**
     2 *  @file apiext.h
    23 *
    34 *  This is the API Extensions Handler.
    4  *
    5  *  COPYRIGHT (c) 1989-1999.
     5 */
     6
     7/*
     8 *  COPYRIGHT (c) 1989-2004.
    69 *  On-Line Applications Research Corporation (OAR).
    710 *
     
    1316 */
    1417
    15 
    1618#ifndef __API_EXTENSIONS_h
    1719#define __API_EXTENSIONS_h
     20
     21/**
     22 *  @defgroup ScoreAPIExtension API Extension Handler
     23 *
     24 *  This group contains functionality which provides mechanisms for the
     25 *  SuperCore to perform API specific actions without there being
     26 *  "up-references" from the SuperCore to APIs.  If these references
     27 *  were allowed in the implementation, the cohesion would be too high
     28 *  and adding an API would be more difficult.  The SuperCore is supposed
     29 *  to be largely independent of any API.
     30 */
     31/**@{*/
    1832
    1933#include <rtems/score/chain.h>
    2034#include <rtems/score/thread.h>
    2135
    22 /*
    23  *  The control structure which defines the points at which an API
    24  *  can add an extension to the system initialization thread.
     36/**
     37 *  This type defines the prototype of the Predriver Hook.
    2538 */
     39typedef void (*API_extensions_Predriver_hook)(void);
    2640
    27 typedef void (*API_extensions_Predriver_hook)(void);
     41/**
     42 *  This type defines the prototype of the Postdriver Hook.
     43 */
    2844typedef void (*API_extensions_Postdriver_hook)(void);
     45
     46/**
     47 *  This type defines the prototype of the Postswitch Hook.
     48 */
    2949typedef void (*API_extensions_Postswitch_hook)(
    3050                 Thread_Control *
    3151             );
    3252
    33 
     53/**
     54 *  The control structure which defines the points at which an API
     55 *  can add an extension to the system initialization thread.
     56 */
    3457typedef struct {
     58  /** This field allows this structure to be used with the Chain Handler. */
    3559  Chain_Node                      Node;
     60  /**
     61   * This field is the callout invoked during RTEMS initialization after
     62   * RTEMS data structures are initialized before device driver initialization
     63   * has occurred.
     64   *
     65   * @note If this field is NULL, no extension is invoked.
     66   */
    3667  API_extensions_Predriver_hook   predriver_hook;
     68  /**
     69   * This field is the callout invoked during RTEMS initialization after
     70   * RTEMS data structures and device driver initialization has occurred
     71   * but before multitasking is initiated.
     72   *
     73   * @note If this field is NULL, no extension is invoked.
     74   */
    3775  API_extensions_Postdriver_hook  postdriver_hook;
     76  /**
     77   * This field is the callout invoked during each context switch
     78   * in the context of the heir thread.
     79   *
     80   * @note If this field is NULL, no extension is invoked.
     81   */
    3882  API_extensions_Postswitch_hook  postswitch_hook;
    3983}  API_extensions_Control;
    4084
    41 /*
     85/**
    4286 *  This is the list of API extensions to the system initialization.
    4387 */
    44 
    4588SCORE_EXTERN Chain_Control _API_extensions_List;
    4689
    47 /*
    48  *  _API_extensions_Initialization
    49  *
    50  *  DESCRIPTION:
    51  *
     90/**
    5291 *  This routine initializes the API extension handler.
    53  *
    5492 */
    55 
    5693void _API_extensions_Initialization( void );
    5794
    58 /*
    59  *  _API_extensions_Add
     95/**
     96 *  This routine adds an extension to the active set of API extensions.
    6097 *
    61  *  DESCRIPTION:
    62  *
    63  *  XXX
     98 *  @param the_extension (in) is the extension set to add.
    6499 */
    65 
    66100void _API_extensions_Add(
    67101  API_extensions_Control *the_extension
    68102);
    69103
    70 /*
    71  *  _API_extensions_Run_predriver
    72  *
    73  *  DESCRIPTION:
    74  *
    75  *  XXX
     104/**
     105 *  This routine executes all of the predriver callouts.
    76106 */
    77 
    78107void _API_extensions_Run_predriver( void );
    79108
    80 /*
    81  *  _API_extensions_Run_postdriver
    82  *
    83  *  DESCRIPTION:
    84  *
    85  *  XXX
     109/**
     110 *  This routine executes all of the postdriver callouts.
    86111 */
    87 
    88112void _API_extensions_Run_postdriver( void );
    89113
    90 /*
    91  *  _API_extensions_Run_postswitch
    92  *
    93  *  DESCRIPTION:
    94  *
    95  *  XXX
     114/**
     115 *  This routine executes all of the post context switch callouts.
    96116 */
     117 */
     118void _API_extensions_Run_postswitch( void );
    97119
    98 void _API_extensions_Run_postswitch( void );
     120/**@}*/
    99121
    100122#endif
  • cpukit/score/include/rtems/score/apimutex.h

    r7ce11b2 rbaff4da  
    1 /*  apimutex.h
     1/**
     2 *  @file apimutex.h
    23 *
    34 *  This include file contains all the constants and structures associated
    45 *  with the API Mutex Handler.  This handler is used by API level
    56 *  routines to manage mutual exclusion.
    6  *
    7  *  COPYRIGHT (c) 1989-2002.
     7 */
     8
     9/*
     10 *  COPYRIGHT (c) 1989-2004.
    811 *  On-Line Applications Research Corporation (OAR).
    912 *
     
    1821#define __API_MUTEX_h
    1922
     23/**
     24 *  @defgroup ScoreAPIMutex API Mutex Handler
     25 *
     26 *  This group contains functionality which provides mutexes to be used
     27 *  in the implementation of API functionality.
     28 */
     29/**@{*/
     30
    2031#ifdef __cplusplus
    2132extern "C" {
     
    2637#include <rtems/score/object.h>
    2738
    28 /*
    29  *  The following defines the control block used to manage each mutex.
     39/**
     40 *  The following defines the control block used to manage each API mutex.
     41 *  An API Mutex is an aggregration of an Object and a SuperCore Mutex.
    3042 */
    31 
    3243typedef struct {
     44  /** This field allows each API Mutex to be a full-fledged RTEMS object.
    3345  Objects_Control       Object;
     46  /** This field contains the SuperCore mutex information. */
    3447  CORE_mutex_Control    Mutex;
    3548}   API_Mutex_Control;
    3649
    37 /*
    38  *  The following defines the information control block used to manage
     50/**
     51 *  The following variable is the information control block used to manage
    3952 *  this class of objects.
    4053 */
    41 
    4254SCORE_EXTERN Objects_Information  _API_Mutex_Information;
    4355
    44 /*
    45  *  _API_Mutex_Initialization
     56/**
     57 *  This routine performs the initialization necessary for this handler.
    4658 *
    47  *  DESCRIPTION:
    48  *
    49  *  This routine performs the initialization necessary for this handler.
     59 *  @param _maximum_mutexes (in) is the maximum number of API mutexes
     60 *         that may exist at any time
    5061 */
    51 
    5262#if defined(RTEMS_MULTIPROCESSING)
    5363#define _API_Mutex_Initialization( _maximum_mutexes ) \
     
    7686#endif
    7787
    78 /*
    79  *  _API_Mutex_Allocate
     88/**
     89 *  This routine allocates an API mutex from the inactive set.
    8090 *
    81  *  DESCRIPTION:
    82  *
    83  *  This routine allocates an api mutex from the inactive set.
     91 *  @param _the_mutex (out) will contain the allocated mutex.
    8492 */
    85 
    8693#define _API_Mutex_Allocate( _the_mutex ) \
    8794  do { \
     
    95102  } while (0)
    96103
    97 /*
    98  *  _API_Mutex_Lock
     104/**
     105 *  This routine acquires the specified API mutex.
    99106 *
    100  *  DESCRIPTION:
    101  *
    102  *  This routine acquires the specified api mutex.
     107 *  @param _the_mutex (in) is the mutex to acquire.
    103108 */
    104 
    105109#define _API_Mutex_Lock( _the_mutex ) \
    106110  do { \
     
    111115  } while (0)
    112116
    113 /*
    114  *  _API_Mutex_Unlock
     117/**
     118 *  This routine releases the specified API mutex.
    115119 *
    116  *  DESCRIPTION:
    117  *
    118  *  This routine releases the specified api mutex.
     120 *  @param _the_mutex (in) is the mutex to release.
    119121 */
    120122
     
    127129  } while (0);
    128130
    129 /*XXX when the APIs all use this for allocation and deallocation
    130  *XXX protection, then they should be renamed and probably moved
     131/**
     132 *  This variable points to the API Mutex instance that is used
     133 *  to protect all memory allocation and deallocation in RTEMS.
     134 *
     135 *  @note When the APIs all use this for allocation and deallocation
     136 *  protection, then this possibly should be renamed and moved to a
     137 *  higher level in the hierarchy.
    131138 */
    132 
    133139SCORE_EXTERN API_Mutex_Control  *_RTEMS_Allocator_Mutex;
    134140
     141/**
     142 *  This macro locks the RTEMS Allocation Mutex.
     143 *
     144 *  @see _RTEMS_Allocator_Mutex
     145 */
    135146#define _RTEMS_Lock_allocator() \
    136147  _API_Mutex_Lock( _RTEMS_Allocator_Mutex )
    137148
     149/**
     150 *  This macro unlocks the RTEMS Allocation Mutex.
     151 *
     152 *  @see _RTEMS_Allocator_Mutex
     153 */
    138154#define _RTEMS_Unlock_allocator() \
    139155  _API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
     
    151167#endif
    152168
     169/*!@}*/
     170
    153171#endif
    154172/*  end of include file */
  • cpukit/score/include/rtems/score/bitfield.h

    r7ce11b2 rbaff4da  
    1 /*  bitfield.h
     1/**
     2 *  @file bitfield.h
    23 *
    34 *  This include file contains all bit field manipulation routines.
    4  *
    5  *  COPYRIGHT (c) 1989-1999.
     5 */
     6
     7/*
     8 *  COPYRIGHT (c) 1989-2004.
    69 *  On-Line Applications Research Corporation (OAR).
    710 *
     
    1619#define __RTEMS_BITFIELD_h
    1720
     21/**
     22 *  @defgroup ScoreBitfield Bitfield Handler
     23 *
     24 *  This group contains functionality that is used to manipulate the
     25 *  priority bitfields used to lookup which priority has the highest
     26 *  priority ready to execute thread.
     27 */
     28/**@{*/
     29
    1830#ifdef __cplusplus
    1931extern "C" {
    2032#endif
    2133
    22 /*
    23  *  _Bitfield_Find_first_bit
    24  *
    25  *  DESCRIPTION:
    26  *
    27  *  This routine returns the bit_number of the first bit set
    28  *  in the specified value.  The correspondence between bit_number
    29  *  and actual bit position is processor dependent.  The search for
    30  *  the first bit set may run from most to least significant bit
    31  *  or vice-versa.
    32  *
    33  *  NOTE:
    34  *
    35  *  This routine is used when the executing thread is removed
    36  *  from the ready state and, as a result, its performance has a
    37  *  significant impact on the performance of the executive as a whole.
    38  */
    39 
    4034#if ( CPU_USE_GENERIC_BITFIELD_DATA == TRUE )
    4135
     36/**
     37 *  This table is used by the generic bitfield routines to perform
     38 *  a highly optimized bit scan without the use of special CPU
     39 *  instructions.
     40 */
    4241#ifndef SCORE_INIT
    4342extern const unsigned char __log2table[256];
     
    6564#endif
    6665
     66/**
     67 *  This routine returns the @a _bit_number of the first bit set
     68 *  in the specified value.  The correspondence between @a _bit_number
     69 *  and actual bit position is processor dependent.  The search for
     70 *  the first bit set may run from most to least significant bit
     71 *  or vice-versa.
     72 *
     73 *  @param _value (in) is the value to bit scan.
     74 *  @param _bit_number (in) is the position of the first bit set.
     75 *
     76 *  @note This routine is used when the executing thread is removed
     77 *  from the ready state and, as a result, its performance has a
     78 *  significant impact on the performance of the executive as a whole.
     79 *
     80 *  @note This routine must be a macro because if a CPU specific version
     81 *  is used it will most likely use inline assembly.
     82 */
    6783#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
    68 
    6984#define _Bitfield_Find_first_bit( _value, _bit_number ) \
    7085        _CPU_Bitfield_Find_first_bit( _value, _bit_number )
    71 
    7286#else
    73 
    74 /*
    75  *  The following must be a macro because if a CPU specific version
    76  *  is used it will most likely use inline assembly.
    77  */
    78 
    7987#define _Bitfield_Find_first_bit( _value, _bit_number ) \
    8088  { \
     
    8795      (_bit_number) = __p[ __value >> 8 ]; \
    8896  }
    89 
    9097#endif
    9198
     
    94101#endif
    95102
     103/**@}*/
     104
    96105#endif
    97106/* end of include file */
  • cpukit/score/include/rtems/score/chain.h

    r7ce11b2 rbaff4da  
    1 /*  chain.h
     1/**
     2 *  @file chain.h
    23 *
    34 *  This include file contains all the constants and structures associated
    4  *  with the Doubly Linked Chain Handler.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     5 *  with the Doubly-Linked Chain Handler.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1720#define __RTEMS_CHAIN_h
    1821
     22/**
     23 *  @defgroup ScoreChain Chain Handler
     24 *
     25 *  The Chain Handler contains XXX
     26 */
     27/**@{*/
     28
    1929#ifdef __cplusplus
    2030extern "C" {
     
    2333#include <rtems/score/address.h>
    2434
    25 /*
     35/**
     36 *  @typedef Chain_Node
     37 *
     38 *  This type definition promotes the name for the Chain Node used by
     39 *  all RTEMS code.  It is a separate type definition because a forward
     40 *  reference is required to define it.
     41 */
     42typedef struct Chain_Node_struct Chain_Node;
     43
     44/**
     45 *  @struct Chain_Node_struct
     46 *
    2647 *  This is used to manage each element (node) which is placed
    2748 *  on a chain.
    2849 *
    29  *  NOTE: Typically, a more complicated structure will use the
    30  *         chain package.  The more complicated structure will
    31  *         include a chain node as the first element in its
    32  *         control structure.  It will then call the chain package
    33  *         with a pointer to that node element.  The node pointer
    34  *         and the higher level structure start at the same address
    35  *         so the user can cast the pointers back and forth.
     50 *  @note Typically, a more complicated structure will use the
     51 *        chain package.  The more complicated structure will
     52 *        include a chain node as the first element in its
     53 *        control structure.  It will then call the chain package
     54 *        with a pointer to that node element.  The node pointer
     55 *        and the higher level structure start at the same address
     56 *        so the user can cast the pointers back and forth.
    3657 *
    3758 */
    38 
    39 typedef struct Chain_Node_struct Chain_Node;
    40 
    4159struct Chain_Node_struct {
     60  /** This points to the node after to this one on this chain. */
    4261  Chain_Node *next;
     62  /** This points to the node immediate prior to this one on this chain. */
    4363  Chain_Node *previous;
    4464};
    4565
    46 /*
    47  *  This is used to manage a chain.  A chain consists of a doubly
    48  *  linked list of zero or more nodes.
     66/**
     67 *  @struct Chain_Control
    4968 *
    50  *  NOTE:  This implementation does not require special checks for
    51  *         manipulating the first and last elements on the chain.
    52  *         To accomplish this the chain control structure is
    53  *         treated as two overlapping chain nodes.  The permanent
    54  *         head of the chain overlays a node structure on the
    55  *         first and permanent_null fields.  The permanent tail
    56  *         of the chain overlays a node structure on the
    57  *         permanent_null and last elements of the structure.
     69 * This is used to manage a chain.  A chain consists of a doubly
     70 * linked list of zero or more nodes.
     71 *
     72 * @note This implementation does not require special checks for
     73 *   manipulating the first and last elements on the chain.
     74 *   To accomplish this the @a Chain_Control structure is
     75 *   treated as two overlapping @ref Chain_Node structures.
     76 *   The permanent head of the chain overlays a node structure on the
     77 *   @a first and @a permanent_null fields.  The permanent tail
     78 *   of the chain overlays a node structure on the
     79 *   @a permanent_null and @a last elements of the structure.
    5880 *
    5981 */
    60 
    6182typedef struct {
     83  /** This points to the first node on this chain. */
    6284  Chain_Node *first;
     85  /** This field is always 0. */
    6386  Chain_Node *permanent_null;
     87  /** This points to the last node on this chain. */
    6488  Chain_Node *last;
    6589} Chain_Control;
    6690
    67 /*
    68  *  _Chain_Initialize
     91/**
     92 *  @brief Initialize a Chain Header
    6993 *
    70  *  DESCRIPTION:
     94 *  This routine initializes @a the_chain structure to manage the
     95 *  contiguous array of @a number_nodes nodes which starts at
     96 *  @a starting_address.  Each node is of @a node_size bytes.
    7197 *
    72  *  This routine initializes the_chain structure to manage the
    73  *  contiguous array of number_nodes nodes which starts at
    74  *  starting_address.  Each node is of node_size bytes.
    75  *
     98 *  @param the_chain (in) specifies the chain to initialize
     99 *  @param starting_address (in) is the starting address of the array
     100 *         of elements
     101 *  @param number_nodes (in) is the numebr of nodes that will be in the chain
     102 *  @param node_size (in) is the size of each node
    76103 */
    77 
    78104void _Chain_Initialize(
    79105  Chain_Control *the_chain,
    80106  void          *starting_address,
    81   uint32_t       number_nodes,
    82   uint32_t       node_size
     107  unsigned32     number_nodes,
     108  unsigned32     node_size
    83109);
    84110
    85 /*
    86  *  _Chain_Get_first_unprotected
     111#ifndef RTEMS_INLINES
     112/**
     113 *  @brief Get the first node (do not disable interrupts)
     114 *
     115 *  This method attempts to obtain the first node from \a the_chain.
     116 *
     117 *  @param the_chain (in) points to the chain to operate upon
     118 *  @return If successful, a chain node is returned.  Otherwise, NULL
     119 *  is returned.
    87120 */
    88 
    89 #ifndef RTEMS_INLINES
    90121Chain_Node *_Chain_Get_first_unprotected(
    91122  Chain_Control *the_chain
     
    93124#endif
    94125
    95 /*
    96  *  _Chain_Extract
     126/**
     127 *  @brief Extract the specified node from a chain
    97128 *
    98  *  DESCRIPTION:
    99  *
    100  *  This routine extracts the_node from the chain on which it resides.
     129 *  This routine extracts \a the_node from the chain on which it resides.
    101130 *  It disables interrupts to insure the atomicity of the
    102131 *  extract operation.
    103132 *
     133 *  @arg the_node specifies the node to extract
    104134 */
    105 
    106135void _Chain_Extract(
    107136  Chain_Node *the_node
    108137);
    109138
    110 /*
    111  *  _Chain_Get
     139/**
     140 *  @brief Obtain the first node on a chain
    112141 *
    113  *  DESCRIPTION:
     142 *  This function removes the first node from \a the_chain and returns
     143 *  a pointer to that node.  If \a the_chain is empty, then NULL is returned.
    114144 *
    115  *  This function removes the first node from the_chain and returns
    116  *  a pointer to that node.  If the_chain is empty, then NULL is returned.
    117  *  It disables interrupts to insure the atomicity of the
     145 *  @note It disables interrupts to insure the atomicity of the
    118146 *  get operation.
    119  *
    120147 */
    121 
    122148Chain_Node *_Chain_Get(
    123149  Chain_Control *the_chain
    124150);
    125151
    126 /*
    127  *  _Chain_Insert
     152/**
     153 *  @brief Insert a node on a chain
    128154 *
    129  *  DESCRIPTION:
     155 *  This routine inserts \a the_node on a chain immediately following
     156 *  \a after_node. 
    130157 *
    131  *  This routine inserts the_node on a chain immediately following
    132  *  after_node.  It disables interrupts to insure the atomicity
     158 *  @note It disables interrupts to insure the atomicity
    133159 *  of the extract operation.
    134  *
    135160 */
    136 
    137161void _Chain_Insert(
    138162  Chain_Node *after_node,
     
    140164);
    141165
    142 /*
    143  *  _Chain_Append
     166/**
     167 *  @brief Append a node on the end of a chain
    144168 *
    145  *  DESCRIPTION:
     169 *  This routine appends \a the_node onto the end of \a the_chain.
    146170 *
    147  *  This routine appends the_node onto the end of the_chain.
    148  *  It disables interrupts to insure the atomicity of the
     171 *  @note It disables interrupts to insure the atomicity of the
    149172 *  append operation.
    150  *
    151173 */
    152 
    153174void _Chain_Append(
    154175  Chain_Control *the_chain,
     
    164185#endif
    165186
     187/**@}*/
     188
    166189#endif
    167190/* end of include file */
  • cpukit/score/include/rtems/score/context.h

    r7ce11b2 rbaff4da  
    1 /*  context.h
     1/**
     2 *  @file context.h
    23 *
    3  *  This include file contains all information about a context.
    4  *
    5  *  COPYRIGHT (c) 1989-1999.
     4 *  This include file contains all information about each thread's context.
     5 */
     6
     7/*
     8 *  COPYRIGHT (c) 1989-2004.
    69 *  On-Line Applications Research Corporation (OAR).
    710 *
     
    1619#define __RTEMS_CONTEXT_h
    1720
     21/**
     22 *  @defgroup ScoreContext Context Handler
     23 *
     24 *  This group contains functionality which abstracts thread context
     25 *  management in a portable manner.
     26 */
     27/**@{*/
     28
    1829#ifdef __cplusplus
    1930extern "C" {
     
    2233#include <rtems/score/cpu.h>
    2334
    24 /*
    25  *  The following constant defines the number of bytes required
     35/**
     36 *  @ingroup ScoreContext
     37 *  This constant defines the number of bytes required
    2638 *  to store a full floating point context.
    2739 */
    28 
    2940#define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE
    3041
    31 /*
    32  *  The following variable is set to TRUE when a reschedule operation
     42/**
     43 *  @ingroup ScoreContext
     44 *  This variable is set to TRUE when a reschedule operation
    3345 *  has determined that the processor should be taken away from the
    3446 *  currently executing thread and given to the heir thread.
     
    3749SCORE_EXTERN volatile boolean _Context_Switch_necessary;
    3850
    39 /*
    40  *  _Context_Initialize
    41  *
    42  *  DESCRIPTION:
    43  *
    44  *  This routine initializes THE_CONTEXT such that the stack
     51/**
     52 *  @ingroup ScoreContext
     53 *  This routine initializes @a _the_context such that the stack
    4554 *  pointer, interrupt level, and entry point are correct for the
    4655 *  thread's initial state.
     56 *
     57 *  @param _the_context (in) will be initialized
     58 *  @param _stack (in) is the lowest physical address of the thread's
     59 *         context
     60 *  @param _size (in) is the size in octets of the thread's context
     61 *  @param _isr (in) is the ISR enable level for this thread
     62 *  @param _entry (in) is this thread's entry point
     63 *  @param _is_fp (in) is set to TRUE if this thread has floating point
     64 *         enabled
    4765 */
    48 
    4966#define \
    5067   _Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \
    5168   _CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp )
    5269
    53 /*
    54  *  _Context_Switch
     70/**
     71 *  @ingroup ScoreContext
     72 *  This routine saves the current context into the @a _executing
     73 *  context record and restores the context specified by @a _heir.
    5574 *
    56  *  DESCRIPTION:
    57  *
    58  *  This routine saves the current context into the EXECUTING
    59  *  context record and restores the context specified by HEIR.
     75 *  @param _executing (in) is the currently executing thread's context
     76 *  @param _heir (in) is the context of the thread to be switched to
    6077 */
    61 
    6278#define _Context_Switch( _executing, _heir ) \
    6379   _CPU_Context_switch( _executing, _heir )
    6480
    65 /*
    66  *  _Context_Restart_self
    67  *
    68  *  DESCRIPTION:
    69  *
     81/**
     82 *  @ingroup ScoreContext
    7083 *  This routine restarts the calling thread by restoring its initial
    7184 *  stack pointer and returning to the thread's entry point.
     85 *
     86 *  @param _the_context (in) is the context of the thread to restart
    7287 */
    73 
    7488#define _Context_Restart_self( _the_context ) \
    7589   _CPU_Context_Restart_self( _the_context )
    7690
    77 /*
    78  *  _Context_Fp_start
    79  *
    80  *  DESCRIPTION:
    81  *
     91/**
     92 *  @ingroup ScoreContext
    8293 *  This function returns the starting address of the floating
    8394 *  point context save area.  It is assumed that the are reserved
    8495 *  for the floating point save area is large enough.
     96 *
     97 *  @param _base (in) is lowest physical address of the floating point
     98 *         context save area.
     99 *  @param _offset (in) is XXX
     100 *
     101 *  @return the initial FP context pointer
    85102 */
    86 
    87103#define _Context_Fp_start( _base, _offset ) \
    88104   _CPU_Context_Fp_start( (_base), (_offset) )
    89105
    90 /*
    91  *  _Context_Initialize_fp
    92  *
    93  *  DESCRIPTION:
    94  *
     106/**
     107 *  @ingroup ScoreContext
    95108 *  This routine initializes the floating point context save
    96109 *  area to contain an initial known state.
     110 *
     111 *  @param _fp_area (in) is the base address of the floating point
     112 *         context save area to initialize.
    97113 */
    98 
    99114#define _Context_Initialize_fp( _fp_area ) \
    100115   _CPU_Context_Initialize_fp( _fp_area )
    101116
    102 /*
    103  *  _Context_Restore_fp
     117/**
     118 *  @ingroup ScoreContext
     119 *  This routine restores the floating point context contained
     120 *  in the @a _fp area.  It is assumed that the current
     121 *  floating point context has been saved by a previous invocation
     122 *  of @a _Context_Save_fp.
    104123 *
    105  *  DESCRIPTION:
    106  *
    107  *  This routine restores the floating point context contained
    108  *  in the FP_CONTEXT area.  It is assumed that the current
    109  *  floating point context has been saved by a previous invocation
    110  *  of SAVE_FP.
     124 *  @param _fp (in) points to the floating point context area to restore.
    111125 */
    112 
    113126#define _Context_Restore_fp( _fp ) \
    114127   _CPU_Context_restore_fp( _fp )
    115128
    116 /*
    117  *  _Context_Save_fp
     129/**
     130 *  @ingroup ScoreContext
     131 *  This routine saves the current floating point context
     132 *  in the @a _fp area.
    118133 *
    119  *  DESCRIPTION:
    120  *
    121  *  This routine saves the current floating point context
    122  *  in the FP_CONTEXT area.
     134 *  @param _fp (in) points to the floating point context area to restore.
    123135 */
    124 
    125136#define _Context_Save_fp( _fp ) \
    126137   _CPU_Context_save_fp( _fp )
     
    130141#endif
    131142
     143/**@}*/
     144
    132145#endif
    133146/* end of include file */
  • cpukit/score/include/rtems/score/copyrt.h

    r7ce11b2 rbaff4da  
    1 /*  copyrt.h
     1/**
     2 *  @file copyrt.h
    23 *
    34 *  This include file contains the copyright notice for RTEMS
    45 *  which is included in every binary copy of the executive.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    2124#endif
    2225
     26/**
     27 *  This is the copyright string for RTEMS.
     28 */
    2329#ifdef SCORE_INIT
    24 
    2530const char _Copyright_Notice[] =
    26 "COPYRIGHT (c) 1989-1999.\n\
     31"COPYRIGHT (c) 1989-2004.\n\
    2732On-Line Applications Research Corporation (OAR).\n";
    28 
    2933#else
    30 
    3134extern const char _Copyright_Notice[];
    32 
    3335#endif
    3436
  • cpukit/score/include/rtems/score/coremsg.h

    r7ce11b2 rbaff4da  
    1 /*  coremsg.h
     1/**
     2 *  @file coremsg.h
    23 *
    34 *  This include file contains all the constants and structures associated
    45 *  with the Message queue Handler.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1619#ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
    1720#define __RTEMS_CORE_MESSAGE_QUEUE_h
     21
     22/**
     23 *  @defgroup ScoreMessageQueue Message Queue Handler
     24 *
     25 *  This group contains functionality which provides the foundation
     26 *  Message Queue services used in all of the APIs supported by RTEMS.
     27 */
     28/**@{*/
    1829
    1930#ifdef __cplusplus
     
    2738#include <rtems/score/watchdog.h>
    2839
    29 /*
     40/**
    3041 *  The following type defines the callout which the API provides
    3142 *  to support global/multiprocessor operations on message_queues.
    3243 */
    33 
    3444typedef void ( *CORE_message_queue_API_mp_support_callout )(
    3545                 Thread_Control *,
     
    3747             );
    3848
    39 /*
     49/**
    4050 *  The following defines the data types needed to manipulate
    4151 *  the contents of message buffers.
    4252 *
    43  *  NOTE:  The buffer field is normally longer than a single uint32_t  .
     53 *  @note  The buffer field is normally longer than a single uint32_t
    4454 *         but since messages are variable length we just make a ptr to 1.
    4555 */
    46 
    4756typedef struct {
    48     uint32_t    size;
    49     uint32_t    buffer[1];
     57  /** This field is the size of this message. */
     58  uint32_t    size;
     59  /** This field contains the actual message. */
     60  uint32_t    buffer[1];
    5061} CORE_message_queue_Buffer;
    5162
    52 /*
     63/**
    5364 *  The following records define the organization of a message
    5465 *  buffer.
    5566 */
    56 
    5767typedef struct {
     68  /** This element allows this structure to be placed on chains. */
    5869  Chain_Node                 Node;
     70  /** This field is the priority of this message. */
    5971  int                        priority;
     72  /** This field points to the contents of the message. */
    6073  CORE_message_queue_Buffer  Contents;
    6174}   CORE_message_queue_Buffer_control;
    6275
    63 /*
    64  *  Blocking disciplines for a message_queue.
    65  */
    66 
     76/**
     77 *  Blocking disciplines for a message queue.
     78 */
    6779typedef enum {
     80  /** This value indicates that pending messages are in FIFO order. */
    6881  CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
     82  /** This value indicates that pending messages are in priority order. */
    6983  CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
    7084}   CORE_message_queue_Disciplines;
    7185
    72 /*
     86/**
     87 *  This is the priority constant used when appending messages onto
     88 *  a message queue.
     89 */
     90#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
     91
     92/**
     93 *  This is the priority constant used when prepending messages onto
     94 *  a message queue.
     95 */
     96#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
     97
     98/**
    7399 *  The following enumerated type details the modes in which a message
    74100 *  may be submitted to a message queue.  The message may be posted
    75101 *  in a send or urgent fashion.
    76102 *
    77  *  NOTE:  All other values are message priorities.  Numerically smaller
     103 *  @note  All other values are message priorities.  Numerically smaller
    78104 *         priorities indicate higher priority messages.
    79  *
    80  */
    81 
    82 #define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
    83 #define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
    84 
     105 */
    85106typedef int CORE_message_queue_Submit_types;
    86107
    87 /*
     108/**
    88109 *  Core Message queue handler return statuses.
    89110 */
    90 
    91111typedef enum {
     112  /** This value indicates the operation completed sucessfully. */
    92113  CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
     114  /** This value indicates that the message was too large for this queue. */
    93115  CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
     116  /** This value indicates that there are too many messages pending. */
    94117  CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
     118  /** This value indicates that a receive was unsuccessful. */
    95119  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
     120  /** This value indicates that a blocking send was unsuccessful. */
    96121  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
     122  /** This value indicates that the message queue being blocked upon
     123   *  was deleted while the thread was waiting.
     124   */
    97125  CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
     126  /** This value indicates that the thread had to timeout while waiting
     127   *  to receive a message because one did not become available.
     128   */
    98129  CORE_MESSAGE_QUEUE_STATUS_TIMEOUT,
     130  /** This value indicates that a blocking receive was unsuccessful. */
    99131  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
    100132}   CORE_message_queue_Status;
    101133
    102 /*
     134/**
    103135 *  The following defines the control block used to manage the
    104136 *  attributes of each message queue.
    105137 */
    106 
    107138typedef struct {
     139  /** This field specifies the order in which blocking tasks will be ordered. */
    108140  CORE_message_queue_Disciplines  discipline;
    109141}   CORE_message_queue_Attributes;
    110142
    111 /*
     143/**
    112144 *  The following defines the type for a Notification handler.  A notification
    113145 *  handler is invoked when the message queue makes a 0->1 transition on
    114146 *  pending messages.
    115147 */
    116 
    117148typedef void (*CORE_message_queue_Notify_Handler)( void * );
    118149
    119 /*
     150/**
    120151 *  The following defines the control block used to manage each
    121152 *  counting message_queue.
    122153 */
    123 
    124154typedef struct {
     155  /** This field is the Waiting Queue used to manage the set of tasks
     156   *  which are blocked waiting to receive a message from this queue.
     157   */
    125158  Thread_queue_Control               Wait_queue;
     159  /** This element is the set of attributes which define this instance's
     160   *  behavior.
     161   */
    126162  CORE_message_queue_Attributes      Attributes;
     163  /** This element is maximum number of messages which may be pending
     164   *  at any given time.
     165   */
    127166  uint32_t                           maximum_pending_messages;
     167  /** This element is the number of messages which are currently pending.
     168   */
    128169  uint32_t                           number_of_pending_messages;
     170  /** This is the size in bytes of the largest message which may be
     171   *  sent via this queue.
     172   */
    129173  uint32_t                           maximum_message_size;
     174  /** This chain is the set of pending messages.  It may be ordered by
     175   *  message priority or in FIFO order.
     176   */
    130177  Chain_Control                      Pending_messages;
     178  /** This is the address of the memory allocated for message buffers.
     179   *  It is allocated are part of message queue initialization and freed
     180   *  as part of destroying it.
     181   */
    131182  CORE_message_queue_Buffer         *message_buffers;
     183  /** This is the routine invoked when the message queue transitions
     184   *  from zero (0) messages pending to one (1) message pending.
     185   */
    132186  CORE_message_queue_Notify_Handler  notify_handler;
     187  /** This field is the argument passed to the @ref notify_argument. */
    133188  void                              *notify_argument;
     189  /** This chain is the set of inactive messages.  A message is inactive
     190   *  when it does not contain a pending message.
     191   */
    134192  Chain_Control                      Inactive_messages;
    135193}   CORE_message_queue_Control;
    136194
    137 /*
    138  *  _CORE_message_queue_Initialize
    139  *
    140  *  DESCRIPTION:
    141  *
     195/**
    142196 *  This routine initializes the message_queue based on the parameters passed.
    143  */
    144 
     197 *
     198 *  @param the_message_queue (in) points to the message queue to initialize
     199 *  @param the_message_queue_attributes (in) points to the attributes that
     200 *         will be used with this message queue instance
     201 *  @param maximum_pending_messages (in) is the maximum number of messages
     202 *         that will be allowed to pend at any given time
     203 *  @param maximum_message_size (in) is the size of largest message that
     204 *         may be sent to this message queue instance
     205 *
     206 *  @return TRUE if the message queue can be initialized.  In general,
     207 *         FALSE will only be returned if memory for the pending
     208 *         messages cannot be allocated.
     209 */
    145210boolean _CORE_message_queue_Initialize(
    146211  CORE_message_queue_Control    *the_message_queue,
     
    150215);
    151216
    152 /*
    153  *  _CORE_message_queue_Close
    154  *
    155  *  DESCRIPTION:
    156  *
     217/**
    157218 *  This function closes a message by returning all allocated space and
    158219 *  flushing the message_queue's task wait queue.
    159  */
    160 
     220 *
     221 *  @param the_message_queue (in) points to the message queue to close
     222 *  @param remote_extract_callout (in) is the routine to call for each thread
     223 *         that is extracted from the set of waiting threads
     224 *  @param status (in) is the status that each waiting thread will return
     225 *         from it's blocking service
     226 */
    161227void _CORE_message_queue_Close(
    162228  CORE_message_queue_Control *the_message_queue,
     
    165231);
    166232
    167 /*
    168  *  _CORE_message_queue_Flush
    169  *
    170  *  DESCRIPTION:
    171  *
     233/**
    172234 *  This function flushes the message_queue's pending message queue.  The
    173235 *  number of messages flushed from the queue is returned.
    174236 *
    175  */
    176 
     237 *  @param the_message_queue (in) points to the message queue to flush
     238 *  @return the number of message pending messages flushed
     239 */
    177240uint32_t   _CORE_message_queue_Flush(
    178241  CORE_message_queue_Control *the_message_queue
    179242);
    180243
    181 /*
    182  *  _CORE_message_queue_Flush_support
    183  *
    184  *  DESCRIPTION:
    185  *
     244/**
    186245 *  This routine flushes all outstanding messages and returns
    187246 *  them to the inactive message chain.
    188  */
    189 
     247 *
     248 *  @param the_message_queue (in) points to the message queue to flush
     249 *  @return the number of message pending messages flushed
     250 */
    190251uint32_t   _CORE_message_queue_Flush_support(
    191252  CORE_message_queue_Control *the_message_queue
    192253);
    193254
    194 /*
    195  *  _CORE_message_queue_Flush_waiting_threads
    196  *
    197  *  DESCRIPTION:
    198  *
     255/**
    199256 *  This function flushes the threads which are blocked on this
    200257 *  message_queue's pending message queue.  They are unblocked whether
    201258 *  blocked sending or receiving.
    202  */
    203 
     259 *
     260 *  @param the_message_queue (in) points to the message queue to flush
     261 */
    204262void _CORE_message_queue_Flush_waiting_threads(
    205263  CORE_message_queue_Control *the_message_queue
    206264);
    207265
    208 /*
    209  *  _CORE_message_queue_Broadcast
    210  *
    211  *  DESCRIPTION:
    212  *
     266/**
    213267 *  This function sends a message for every thread waiting on the queue and
    214268 *  returns the number of threads made ready by the message.
    215269 *
    216  */
    217 
     270 *  @param the_message_queue (in) points to the message queue
     271 *  @param buffer (in) is the starting address of the message to broadcast
     272 *  @param size (in) is the size of the message being broadcast
     273 *  @param id (in) is the RTEMS object Id associated with this message queue.
     274 *         It is used when unblocking a remote thread.
     275 *  @param api_message_queue_mp_support (in) is the routine to invoke if
     276 *         a thread that is unblocked is actually a remote thread.
     277 *  @param count (out) points to the variable that will contain the
     278 *         number of tasks that are sent this message
     279 *  @return @a *count will contain the number of messages sent
     280 *  @return indication of the successful completion or reason for failure
     281 */
    218282CORE_message_queue_Status _CORE_message_queue_Broadcast(
    219283  CORE_message_queue_Control                *the_message_queue,
     
    225289);
    226290
    227 /*
    228  *  _CORE_message_queue_Submit
    229  *
    230  *  DESCRIPTION:
    231  *
     291/**
    232292 *  This routine implements the send and urgent message functions. It
    233293 *  processes a message that is to be submitted to the designated
     
    237297 *  at the front of the queue.
    238298 *
    239  */
    240 
     299 *  @param the_message_queue (in) points to the message queue
     300 *  @param buffer (in) is the starting address of the message to send
     301 *  @param size (in) is the size of the message being send
     302 *  @param id (in) is the RTEMS object Id associated with this message queue.
     303 *         It is used when unblocking a remote thread.
     304 *  @param api_message_queue_mp_support (in) is the routine to invoke if
     305 *         a thread that is unblocked is actually a remote thread.
     306 *  @param submit_type (in) determines whether the message is prepended,
     307 *         appended, or enqueued in priority order.
     308 *  @param wait (in) indicates whether the calling thread is willing to block
     309 *         if the message queue is full.
     310 *  @param timeout (in) is the maximum number of clock ticks that the calling
     311 *         thread is willing to block if the message queue is full.
     312 *  @return indication of the successful completion or reason for failure
     313 */
    241314CORE_message_queue_Status _CORE_message_queue_Submit(
    242315  CORE_message_queue_Control                *the_message_queue,
     
    250323);
    251324
    252 /*
    253  *  _CORE_message_queue_Seize
    254  *
    255  *  DESCRIPTION:
    256  *
     325/**
    257326 *  This kernel routine dequeues a message, copies the message buffer to
    258327 *  a given destination buffer, and frees the message buffer to the
     
    260329 *  otherwise an error will be given to the thread if no messages are available.
    261330 *
    262  *  NOTE: Returns message priority via return are in TCB.
    263  */
    264 
     331 *  @param the_message_queue (in) points to the message queue
     332 *  @param id (in) is the RTEMS object Id associated with this message queue.
     333 *         It is used when unblocking a remote thread.
     334 *  @param buffer (in) is the starting address of the message buffer to
     335 *         to be filled in with a message
     336 *  @param size (in) is the size of the @a buffer and indicates the maximum
     337 *         size message that the caller can receive.
     338 *  @param wait (in) indicates whether the calling thread is willing to block
     339 *         if the message queue is empty.
     340 *  @param timeout (in) is the maximum number of clock ticks that the calling
     341 *         thread is willing to block if the message queue is empty.
     342 *
     343 *  @return indication of the successful completion or reason for failure
     344 *  @note Returns message priority via return are in TCB.
     345 */
    265346void _CORE_message_queue_Seize(
    266347  CORE_message_queue_Control      *the_message_queue,
     
    272353);
    273354
    274 /*
    275  *  _CORE_message_queue_Insert_message
    276  *
    277  *  DESCRIPTION:
    278  *
     355/**
    279356 *  This kernel routine inserts the specified message into the
    280357 *  message queue.  It is assumed that the message has been filled
    281358 *  in before this routine is called.
    282  */
    283 
     359 *
     360 *  @param the_message_queue (in) points to the message queue
     361 *  @param the_message (in) is the message to enqueue
     362 *  @param submit_type (in) determines whether the message is prepended,
     363 *         appended, or enqueued in priority order.
     364 */
    284365void _CORE_message_queue_Insert_message(
    285366  CORE_message_queue_Control        *the_message_queue,
     
    296377#endif
    297378
     379/**@}*/
     380
    298381#endif
    299382/*  end of include file */
  • cpukit/score/include/rtems/score/coremutex.h

    r7ce11b2 rbaff4da  
    1 /*  mutex.h
     1/**
     2 *  @file coremutex.h
    23 *
    34 *  This include file contains all the constants and structures associated
     
    56 *  Dijkstra binary semaphore used to provide synchronization and mutual
    67 *  exclusion capabilities.
    7  *
    8  *  COPYRIGHT (c) 1989-1999.
     8 */
     9
     10/*
     11 *  COPYRIGHT (c) 1989-2004.
    912 *  On-Line Applications Research Corporation (OAR).
    1013 *
     
    1821#ifndef __RTEMS_CORE_MUTEX_h
    1922#define __RTEMS_CORE_MUTEX_h
     23
     24/**
     25 *  @defgroup ScoreMutex Mutex Handler
     26 *
     27 *  This group contains functionality which provides the foundation
     28 *  Mutex services used in all of the APIs supported by RTEMS.
     29 */
     30/**@{*/
    2031
    2132#ifdef __cplusplus
     
    3041#include <rtems/score/sysstate.h>
    3142
    32 /*
     43/**
    3344 *  The following type defines the callout which the API provides
    3445 *  to support global/multiprocessor operations on mutexes.
    3546 */
    36 
    3747typedef void ( *CORE_mutex_API_mp_support_callout )(
    3848                 Thread_Control *,
     
    4050             );
    4151
    42 /*
     52/**
    4353 *  Blocking disciplines for a mutex.
    4454 */
    45 
    4655typedef enum {
     56  /** This specifies that threads will wait for the mutex in FIFO order. */
    4757  CORE_MUTEX_DISCIPLINES_FIFO,
     58  /** This specifies that threads will wait for the mutex in priority order.  */
    4859  CORE_MUTEX_DISCIPLINES_PRIORITY,
     60  /** This specifies that threads will wait for the mutex in priority order.
     61   *  Additionally, the Priority Inheritance Protocol will be in effect.
     62   */
    4963  CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
     64  /** This specifies that threads will wait for the mutex in priority order.
     65   *  Additionally, the Priority Ceiling Protocol will be in effect.
     66   */
    5067  CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
    5168}   CORE_mutex_Disciplines;
    5269
    53 /*
     70/**
    5471 *  Mutex handler return statuses.
    5572 */
    56 
    5773typedef enum {
     74  /** This status indicates that the operation completed successfully. */
    5875  CORE_MUTEX_STATUS_SUCCESSFUL,
     76  /** This status indicates that the calling task did not want to block
     77   *  and the operation was unable to complete immediately because the
     78   *  resource was unavailable.
     79   */
    5980  CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
     81  /** This status indicates that an attempt was made to relock a mutex
     82   *  for which nesting is not configured.
     83   */
    6084  CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
     85  /** This status indicates that an attempt was made to release a mutex
     86   *  by a thread other than the thread which locked it.
     87   */
    6188  CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
     89  /** This status indicates that the thread was blocked waiting for an
     90   *  operation to complete and the mutex was deleted.
     91   */
    6292  CORE_MUTEX_WAS_DELETED,
     93  /** This status indicates that the calling task was willing to block
     94   *  but the operation was unable to complete within the time allotted
     95   *  because the resource never became available.
     96   */
    6397  CORE_MUTEX_TIMEOUT,
     98  /** This status indicates that a thread of logically greater importance
     99   *  than the ceiling priority attempted to lock this mutex.
     100   */
    64101  CORE_MUTEX_STATUS_CEILING_VIOLATED
    65102}   CORE_mutex_Status;
    66103
    67 /*
     104/**
    68105 *  Mutex lock nesting behavior
    69106 *
    70  *  CORE_MUTEX_NESTING_ACQUIRES:
     107 *  + CORE_MUTEX_NESTING_ACQUIRES:
    71108 *    This sequence has no blocking or errors:
    72  *         lock(m)
    73  *         lock(m)
    74  *         unlock(m)
    75  *         unlock(m)
    76  *
    77  *  CORE_MUTEX_NESTING_IS_ERROR
     109 *
     110 *         + lock(m)
     111 *         + lock(m)
     112 *         + unlock(m)
     113 *         + unlock(m)
     114 *
     115 *  + CORE_MUTEX_NESTING_IS_ERROR
    78116 *    This sequence returns an error at the indicated point:
    79  *        lock(m)
    80  *        lock(m)   - already locked error
    81  *        unlock(m)
    82  *
    83  *  CORE_MUTEX_NESTING_BLOCKS
     117 *
     118 *        + lock(m)
     119 *        + lock(m)   - already locked error
     120 *        + unlock(m)
     121 *
     122 *  + CORE_MUTEX_NESTING_BLOCKS
    84123 *    This sequence performs as indicated:
    85  *        lock(m)
    86  *        lock(m)   - deadlocks or timeouts
    87  *        unlock(m) - releases
    88  */
    89 
     124 *        + lock(m)
     125 *        + lock(m)   - deadlocks or timeouts
     126 *        + unlock(m) - releases
     127 */
    90128typedef enum {
    91129  CORE_MUTEX_NESTING_ACQUIRES,
     
    94132}  CORE_mutex_Nesting_behaviors;
    95133
    96 /*
    97  *  Locked and unlocked values
    98  */
    99 
     134/**
     135 *  This is the value of a mutex when it is unlocked.
     136 */
    100137#define CORE_MUTEX_UNLOCKED 1
     138
     139/**
     140 *  This is the value of a mutex when it is locked.
     141 */
    101142#define CORE_MUTEX_LOCKED   0
    102143
    103 /*
     144/**
    104145 *  The following defines the control block used to manage the
    105146 *  attributes of each mutex.
    106147 */
    107 
    108148typedef struct {
     149  /** This field determines what the behavior of this mutex instance will
     150   *  be when attempting to acquire the mutex when it is already locked.
     151   */
    109152  CORE_mutex_Nesting_behaviors lock_nesting_behavior;
     153  /** When this field is TRUE, then only the thread that locked the mutex
     154   *  is allowed to unlock it.
     155   */
    110156  boolean                      only_owner_release;
     157  /** This field indicates whether threads waiting on the mutex block in
     158   *  FIFO or priority order.
     159   */
    111160  CORE_mutex_Disciplines       discipline;
     161  /** This field contains the ceiling priority to be used if that protocol
     162   *  is selected.
     163   */
    112164  Priority_Control             priority_ceiling;
    113165}   CORE_mutex_Attributes;
    114166
    115 /*
     167/**
    116168 *  The following defines the control block used to manage each mutex.
    117169 */
    118 
    119170typedef struct {
     171  /** This field is the Waiting Queue used to manage the set of tasks
     172   *  which are blocked waiting to lock the mutex.
     173   */
    120174  Thread_queue_Control    Wait_queue;
     175  /** This element is the set of attributes which define this instance's
     176   *  behavior.
     177   */
    121178  CORE_mutex_Attributes   Attributes;
     179  /** This element contains the current state of the mutex.
     180   */
    122181  uint32_t                lock;
     182  /** This element contains the number of times the mutex has been acquired
     183   *  nested.  This must be zero (0) before the mutex is actually unlocked.
     184   */
    123185  uint32_t                nest_count;
     186  /** This is the number of waiting threads. */
    124187  uint32_t                blocked_count;
     188  /** This element points to the thread which is currently holding this mutex.
     189   *  The holder is the last thread to successfully lock the mutex and which
     190   *  has not unlocked it.  If the thread is not locked, there is no holder.
     191   */
    125192  Thread_Control         *holder;
     193  /** This element contains the object Id of the holding thread.  */
    126194  Objects_Id              holder_id;
    127195}   CORE_mutex_Control;
    128196
    129 /*
    130  *  _CORE_mutex_Initialize
    131  *
    132  *  DESCRIPTION:
     197/**
    133198 *
    134199 *  This routine initializes the mutex based on the parameters passed.
    135  */
    136 
     200 *
     201 *  @param the_mutex (in) is the mutex to initalize
     202 *  @param the_mutex_attributes (in) is the attributes associated with this
     203 *         mutex instance
     204 *  @param initial_lock (in) is the initial value of the mutex
     205 */
    137206void _CORE_mutex_Initialize(
    138207  CORE_mutex_Control           *the_mutex,
     
    141210);
    142211
    143 /*
    144  *  _CORE_mutex_Seize
    145  *
    146  *  DESCRIPTION:
    147  *
     212#ifndef __RTEMS_APPLICATION__
     213/**
    148214 *  This routine attempts to receive a unit from the_mutex.
    149215 *  If a unit is available or if the wait flag is FALSE, then the routine
     
    151217 *  available.
    152218 *
    153  *  NOTE:  For performance reasons, this routine is implemented as
     219 *  @param the_mutex (in) is the mutex to attempt to lock
     220 *  @param level_p (in) is the interrupt level holder
     221 *
     222 *  @note  For performance reasons, this routine is implemented as
    154223 *         a macro that uses two support routines.
    155224 */
    156 
    157 
    158 #ifndef __RTEMS_APPLICATION__
    159225RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
    160226  CORE_mutex_Control  *the_mutex,
     
    162228);
    163229
     230/**
     231 *  This routine performs the blocking portion of a mutex obtain.
     232 *  It is an actual subroutine and is not implemented as something
     233 *  that may be inlined.
     234 *
     235 *  @param the_mutex (in) is the mutex to attempt to lock
     236 *  @param timeout (in) is the maximum number of ticks to block
     237 */
    164238void _CORE_mutex_Seize_interrupt_blocking(
    165239  CORE_mutex_Control  *the_mutex,
     
    167241);
    168242
     243/**
     244 *  This routine attempts to obtain the mutex.  If the mutex is available,
     245 *  then it will return immediately.  Otherwise, it will invoke the
     246 *  support routine @a _Core_mutex_Seize_interrupt_blocking.
     247 *
     248 *  @param _the_mutex (in) is the mutex to attempt to lock
     249 *  @param _id (in) is the Id of the owning API level Semaphore object
     250 *  @param _wait (in) is TRUE if the thread is willing to wait
     251 *  @param _timeout (in) is the maximum number of ticks to block
     252 *  @param _level (in) is a temporary variable used to contain the ISR
     253 *         disable level cookie
     254 */
    169255#define _CORE_mutex_Seize( \
    170256  _the_mutex, _id, _wait, _timeout, _level ) \
    171257  do { \
    172         if ( _Thread_Dispatch_disable_level \
    173                 && (_wait) \
    174                 && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
    175            ) { \
    176                 _Internal_error_Occurred( \
    177                                                         INTERNAL_ERROR_CORE, \
    178                                                         FALSE, \
    179                                                         18 /* called from wrong environment */); \
    180         } \
     258    if ( _Thread_Dispatch_disable_level \
     259        && (_wait) \
     260        && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
     261       ) { \
     262        _Internal_error_Occurred( \
     263           INTERNAL_ERROR_CORE, \
     264           FALSE, \
     265           18 /* called from wrong environment */); \
     266    } \
    181267    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
    182268      if ( !_wait ) { \
     
    195281  } while (0)
    196282
    197 /*
    198  *  _CORE_mutex_Surrender
    199  *
    200  *  DESCRIPTION:
    201  *
     283/**
    202284 *  This routine frees a unit to the mutex.  If a task was blocked waiting for
    203285 *  a unit from this mutex, then that task will be readied and the unit
    204286 *  given to that task.  Otherwise, the unit will be returned to the mutex.
    205  */
    206 
     287 *
     288 *  @param the_mutex (in) is the mutex to surrender
     289 *  @param id (in) is the id of the RTEMS Object associated with this mutex
     290 *  @param api_mutex_mp_support (in) is the routine that will be called when
     291 *         unblocking a remote mutex
     292 *
     293 *  @return an indication of whether the routine succeeded or failed
     294 */
    207295CORE_mutex_Status _CORE_mutex_Surrender(
    208296  CORE_mutex_Control                *the_mutex,
     
    211299);
    212300
    213 /*
    214  *  _CORE_mutex_Flush
    215  *
    216  *  DESCRIPTION:
    217  *
     301/**
    218302 *  This routine assists in the deletion of a mutex by flushing the associated
    219303 *  wait queue.
    220  */
    221 
     304 *
     305 *  @param the_mutex (in) is the mutex to flush
     306 *  @param remote_extract_callout (in) is the routine to invoke when a remote
     307 *         thread is extracted
     308 *  @param status (in) is the status value which each unblocked thread will
     309 *         return to its caller.
     310 */
    222311void _CORE_mutex_Flush(
    223312  CORE_mutex_Control         *the_mutex,
     
    233322#endif
    234323
     324/**@}*/
     325
    235326#endif
    236327/*  end of include file */
  • cpukit/score/include/rtems/score/coresem.h

    r7ce11b2 rbaff4da  
    1 /*  core_sem.h
     1/**
     2 *  @file coresem.h
    23 *
    34 *  This include file contains all the constants and structures associated
     
    56 *  standard Dijkstra binary semaphore used to provide synchronization
    67 *  and mutual exclusion capabilities.
    7  *
    8  *  COPYRIGHT (c) 1989-1999.
     8 */
     9
     10/*
     11 *  COPYRIGHT (c) 1989-2004.
    912 *  On-Line Applications Research Corporation (OAR).
    1013 *
     
    1922#define __RTEMS_CORE_COUNTING_SEMAPHORE_h
    2023
     24/**
     25 *  @defgroup ScoreSemaphore Semaphore Handler
     26 *
     27 *  This group contains functionality which provides the foundation
     28 *  Semaphore services used in all of the APIs supported by RTEMS.
     29 */
     30/**@{*/
     31
    2132#ifdef __cplusplus
    2233extern "C" {
     
    2839#include <rtems/score/watchdog.h>
    2940
    30 /*
     41/**
    3142 *  The following type defines the callout which the API provides
    3243 *  to support global/multiprocessor operations on semaphores.
    3344 */
    34 
    3545typedef void ( *CORE_semaphore_API_mp_support_callout )(
    3646                 Thread_Control *,
     
    3848             );
    3949
    40 /*
     50/**
    4151 *  Blocking disciplines for a semaphore.
    4252 */
    43 
    4453typedef enum {
     54  /** This specifies that threads will wait for the semaphore in FIFO order. */
    4555  CORE_SEMAPHORE_DISCIPLINES_FIFO,
     56  /** This specifies that threads will wait for the semaphore in
     57   *  priority order.
     58   */
    4659  CORE_SEMAPHORE_DISCIPLINES_PRIORITY
    4760}   CORE_semaphore_Disciplines;
    4861
    49 /*
     62/**
    5063 *  Core Semaphore handler return statuses.
    5164 */
    52 
    5365typedef enum {
     66  /** This status indicates that the operation completed successfully. */
    5467  CORE_SEMAPHORE_STATUS_SUCCESSFUL,
     68  /** This status indicates that the calling task did not want to block
     69   *  and the operation was unable to complete immediately because the
     70   *  resource was unavailable.
     71   */
    5572  CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT,
     73  /** This status indicates that the thread was blocked waiting for an
     74   *  operation to complete and the semaphore was deleted.
     75   */
    5676  CORE_SEMAPHORE_WAS_DELETED,
     77  /** This status indicates that the calling task was willing to block
     78   *  but the operation was unable to complete within the time allotted
     79   *  because the resource never became available.
     80   */
    5781  CORE_SEMAPHORE_TIMEOUT,
     82  /** This status indicates that an attempt was made to unlock the semaphore
     83   *  and this would have made its count greater than that allowed.
    5884  CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED
    5985}   CORE_semaphore_Status;
    6086
    61 /*
     87/**
    6288 *  The following defines the control block used to manage the
    6389 *  attributes of each semaphore.
    6490 */
    65 
    6691typedef struct {
     92  /** This element indicates the maximum count this semaphore may have. */
    6793  uint32_t                    maximum_count;
     94  /** This field indicates whether threads waiting on the semaphore block in
     95   *  FIFO or priority order.
     96   */
    6897  CORE_semaphore_Disciplines  discipline;
    6998}   CORE_semaphore_Attributes;
    7099
    71 /*
     100/**
    72101 *  The following defines the control block used to manage each
    73102 *  counting semaphore.
    74103 */
    75 
    76104typedef struct {
     105  /** This field is the Waiting Queue used to manage the set of tasks
     106   *  which are blocked waiting to obtain the semaphore.
     107   */
    77108  Thread_queue_Control        Wait_queue;
     109  /** This element is the set of attributes which define this instance's
     110   *  behavior.
     111   */
    78112  CORE_semaphore_Attributes   Attributes;
     113  /** This element contains the current count of this semaphore. */
    79114  uint32_t                    count;
    80115}   CORE_semaphore_Control;
    81116
    82 /*
    83  *  _CORE_semaphore_Initialize
     117/**
     118 *  This routine initializes the semaphore based on the parameters passed.
    84119 *
    85  *  DESCRIPTION:
    86  *
    87  *  This routine initializes the semaphore based on the parameters passed.
     120 *  @param the_semaphore (in) is the semaphore to initialize
     121 *  @param the_semaphore_attributes (in) define the behavior of this instance
     122 *  @param initial_value (in) is the initial count of the semaphore
    88123 */
    89 
    90124void _CORE_semaphore_Initialize(
    91125  CORE_semaphore_Control       *the_semaphore,
     
    94128);
    95129
    96 /*
    97  *  _CORE_semaphore_Seize
    98  *
    99  *  DESCRIPTION:
    100  *
     130/**
    101131 *  This routine attempts to receive a unit from the_semaphore.
    102132 *  If a unit is available or if the wait flag is FALSE, then the routine
    103133 *  returns.  Otherwise, the calling task is blocked until a unit becomes
    104134 *  available.
     135 *
     136 *  @param the_semaphore (in) is the semaphore to seize
     137 *  @param id (in) is the Id of the API level Semaphore object associated
     138 *         with this instance of a SuperCore Semaphore
     139 *  @param wait (in) is TRUE if the calling thread is willing to wait
     140 *  @param timeout (in) is the number of ticks the calling thread is willing
     141 *         to wait if @a wait is TRUE.
    105142 */
    106 
    107143void _CORE_semaphore_Seize(
    108144  CORE_semaphore_Control  *the_semaphore,
     
    112148);
    113149
    114 /*
    115  *  _CORE_semaphore_Surrender
    116  *
    117  *  DESCRIPTION:
    118  *
     150/**
    119151 *  This routine frees a unit to the semaphore.  If a task was blocked waiting
    120152 *  for a unit from this semaphore, then that task will be readied and the unit
    121153 *  given to that task.  Otherwise, the unit will be returned to the semaphore.
     154 *
     155 *  @param the_semaphore (in) is the semaphore to surrender
     156 *  @param id (in) is the Id of the API level Semaphore object associated
     157 *         with this instance of a SuperCore Semaphore
     158 *  @param api_semaphore_mp_support (in) is the routine to invoke if the
     159 *         thread unblocked is remote
     160 *
     161 *  @return an indication of whether the routine succeeded or failed
    122162 */
    123 
    124163CORE_semaphore_Status _CORE_semaphore_Surrender(
    125164  CORE_semaphore_Control                *the_semaphore,
     
    128167);
    129168
    130 /*
    131  *  _CORE_semaphore_Flush
    132  *
    133  *  DESCRIPTION:
    134  *
     169/**
    135170 *  This routine assists in the deletion of a semaphore by flushing the
    136171 *  associated wait queue.
     172 *
     173 *  @param the_semaphore (in) is the semaphore to flush
     174 *  @param remote_extract_callout (in) is the routine to invoke if the
     175 *         thread unblocked is remote
     176 *  @param status (in) is the status to be returned to the unblocked thread
    137177 */
    138 
    139178void _CORE_semaphore_Flush(
    140179  CORE_semaphore_Control         *the_semaphore,
     
    151190#endif
    152191
     192/**@}*/
     193
    153194#endif
    154195/*  end of include file */
  • cpukit/score/include/rtems/score/heap.h

    r7ce11b2 rbaff4da  
    1 /*  heap.h
     1/**
     2 *  @file heap.h
    23 *
    34 *  This include file contains the information pertaining to the Heap
     
    89 *  and unallocated blocks is contained in the heap space.  A heap header
    910 *  contains control information for the heap.
    10  *
    11  *  COPYRIGHT (c) 1989-1999.
     11 */
     12
     13/*
     14 *  COPYRIGHT (c) 1989-2004.
    1215 *  On-Line Applications Research Corporation (OAR).
    1316 *
     
    2225#define __RTEMS_HEAP_h
    2326
     27/**
     28 *  @defgroup ScoreHeap Heap Handler
     29 *
     30 *  This group contains functionality which provides the foundation
     31 *  Heap services used in all of the APIs supported by RTEMS.
     32 */
     33/**@{*/
     34
    2435#ifdef __cplusplus
    2536extern "C" {
    2637#endif
    2738
    28 /*
     39/**
    2940 *  Status codes for heap_extend
    3041 */
    31 
    3242typedef enum {
    3343  HEAP_EXTEND_SUCCESSFUL,
     
    3646}  Heap_Extend_status;
    3747
    38 /*
     48/**
    3949 *  Status codes for _Heap_Get_information
    4050 */
    41 
    4251typedef enum {
    4352    HEAP_GET_INFORMATION_SUCCESSFUL = 0,
     
    4655}  Heap_Get_information_status;
    4756
    48 /*
     57/**
    4958 *  Information block returned by _Heap_Get_information
    5059 */
    51 
    5260typedef struct {
     61  /** This field is the number of free blocks in this heap. */
    5362  uint32_t     free_blocks;
     63  /** This field is the amount of free memory in this heap. */
    5464  uint32_t     free_size;
     65  /** This field is the number of used blocks in this heap. */
    5566  uint32_t     used_blocks;
     67  /** This field is the amount of used memory in this heap. */
    5668  uint32_t     used_size;
    5769} Heap_Information_block;
    5870
    59 /*
    60  *  Constants used in the size/used field of each heap block to
    61  *  indicate when a block is free or in use.
    62  */
    63 
    64 #define HEAP_BLOCK_USED    1           /* indicates block is in use */
    65 #define HEAP_BLOCK_FREE    0           /* indicates block is free */
    66 
    67 /*
     71/**
     72 *  This constant is used in the size/used field of each heap block to
     73 *  indicate when a block is in use.
     74 */
     75#define HEAP_BLOCK_USED    1
     76
     77/**
     78 *  This constant is used in the size/used field of each heap block to
     79 *  indicate when a block is free.
     80 */
     81#define HEAP_BLOCK_FREE    0
     82
     83/**
    6884 *  The size/used field value for the dummy front and back flags.
    6985 */
    70 
    7186#define HEAP_DUMMY_FLAG    (0 + HEAP_BLOCK_USED)
    7287
     
    7590 *  heap data structures which impact the management of a heap.
    7691 *
    77  * NOTE:   Because free block overhead is greater than used block
     92 *  NOTE:  Because free block overhead is greater than used block
    7893 *         overhead AND a portion of the allocated space is from
    7994 *         the extra free block overhead, the absolute lower bound
     
    8297 */
    8398
    84 #define HEAP_OVERHEAD \
    85   (sizeof( uint32_t   ) * 2)         /* size dummy first and last blocks */
    86 #define HEAP_BLOCK_USED_OVERHEAD \
    87   (sizeof( void * ) * 2)             /* num bytes overhead in used block */
    88 #define HEAP_MINIMUM_SIZE \
    89   (HEAP_OVERHEAD + sizeof (Heap_Block))
    90                                      /* min number of bytes the user may */
    91                                      /*   specify for the heap size      */
    92 
    93 /*
     99/** size dummy first and last blocks */
     100#define HEAP_OVERHEAD (sizeof( uint32_t   ) * 2)
     101
     102/** number of bytes of overhead in used block */
     103#define HEAP_BLOCK_USED_OVERHEAD (sizeof( void * ) * 2)
     104
     105/** Minimum number of bytes the user may specify for the heap size */
     106#define HEAP_MINIMUM_SIZE (HEAP_OVERHEAD + sizeof (Heap_Block))
     107
     108/**
     109 *  Forward reference
     110 *
     111 *  @ref Heap_Block
     112 */
     113typedef struct Heap_Block_struct Heap_Block;
     114
     115/**
    94116 *  The following defines the data structure used to manage
    95117 *  individual blocks in a heap.   When the block is allocated, the
     
    98120 *  the address of the next field.
    99121 *
    100  *  NOTE:  The next and previous pointers are only valid when the
     122 *  @note  The next and previous pointers are only valid when the
    101123 *         block is free.  Caution must be exercised to insure that
    102124 *         allocated blocks are large enough to contain them and
     
    104126 *         block is actually allocated.
    105127 */
    106 
    107 typedef struct Heap_Block_struct Heap_Block;
    108 
    109128struct Heap_Block_struct {
    110   uint32_t    back_flag;   /* size and status of prev block */
    111   uint32_t    front_flag;  /* size and status of block */
    112   Heap_Block *next;        /* pointer to next block */
    113   Heap_Block *previous;    /* pointer to previous block */
     129  /** size and status of prev block */
     130  uint32_t    back_flag;
     131  /** size and status of block */
     132  uint32_t    front_flag;
     133  /** pointer to next block */
     134  Heap_Block *next;
     135  /** pointer to previous block */
     136  Heap_Block *previous;
    114137};
    115138
    116 /*
     139/**
    117140 *  The following defines the control block used to manage each heap.
    118141 *
    119  *  NOTE:
    120  *
    121  *  This structure is layed out such that it can be used a a dummy
     142 *  @note This structure is layed out such that it can be used a a dummy
    122143 *  first and last block on the free block chain.  The extra padding
    123144 *  insures the dummy last block is the correct size.
     
    127148 *  Handler.
    128149 */
    129 
    130150typedef struct {
    131   Heap_Block *start;       /* first valid block address in heap */
    132   Heap_Block *final;       /* last valid block address in heap */
    133 
    134   Heap_Block *first;       /* pointer to first block in heap */
    135   Heap_Block *permanent_null;  /* always NULL pointer */
    136   Heap_Block *last;        /* pointer to last block in heap */
    137   uint32_t    page_size;   /* allocation unit */
     151  /** first valid block address in heap */
     152  Heap_Block *start;
     153  /** last valid block address in heap */
     154  Heap_Block *final;
     155
     156  /** pointer to first block in heap */
     157  Heap_Block *first;
     158  /** always NULL pointer */
     159  Heap_Block *permanent_null;
     160  /** pointer to last block in heap */
     161  Heap_Block *last;
     162  /** allocation unit */
     163  uint32_t    page_size;
     164  /** reserved field */
    138165  uint32_t    reserved;
    139166}   Heap_Control;
    140167
    141 /*
    142  *  _Heap_Initialize
    143  *
    144  *  DESCRIPTION:
    145  *
    146  *  This routine initializes the_heap record to manage the
    147  *  contiguous heap of size bytes which starts at starting_address.
     168/**
     169 *  This routine initializes @a the_heap record to manage the
     170 *  contiguous heap of @a size bytes which starts at @a starting_address.
    148171 *  Blocks of memory are allocated from the heap in multiples of
    149  *  page_size byte units.
    150  */
    151 
     172 *  @a page_size byte units.
     173 *
     174 *  @param the_heap (in) is the heap to operate upon
     175 *  @param starting_address (in) is the starting address of the memory for
     176 *         the heap
     177 *  @param size (in) is the size in bytes of the memory area for the heap
     178 *  @param page_size (in) is the size in bytes of the allocation unit
     179 *  @return XXX
     180 */
    152181uint32_t   _Heap_Initialize(
    153182  Heap_Control *the_heap,
     
    157186);
    158187
    159 /*
    160  *  _Heap_Extend
    161  *
    162  *  DESCRIPTION:
    163  *
    164  *  This routine grows the_heap memory area using the size bytes which
    165  *  begin at starting_address.
    166  */
    167 
     188/**
     189 *  This routine grows @a the_heap memory area using the size bytes which
     190 *  begin at @a starting_address.
     191 *
     192 *  @param the_heap (in) is the heap to operate upon
     193 *  @param starting_address (in) is the starting address of the memory
     194 *         to add to the heap
     195 *  @param size (in) is the size in bytes of the memory area to add
     196 *  @param amount_extended (in) points to a user area to return the
     197 *  @return a status indicating success or the reason for failure
     198 *  @return *size filled in with the amount of memory added to the heap
     199 */
    168200Heap_Extend_status _Heap_Extend(
    169201  Heap_Control *the_heap,
     
    173205);
    174206
    175 /*
    176  *  _Heap_Allocate
    177  *
    178  *  DESCRIPTION:
    179  *
    180  *  DESCRIPTION:
    181  *
     207/**
    182208 *  This function attempts to allocate a block of size bytes from
    183  *  the_heap.  If insufficient memory is free in the_heap to allocate
     209 *  @a the_heap.  If insufficient memory is free in @a the_heap to allocate
    184210 *  a  block of the requested size, then NULL is returned.
    185  */
    186 
     211 *
     212 *  @param the_heap (in) is the heap to operate upon
     213 *  @param size (in) is the amount of memory to allocate in bytes
     214 *  @return NULL if unsuccessful and a pointer to the block if successful
     215 */
    187216void *_Heap_Allocate(
    188217  Heap_Control *the_heap,
     
    190219);
    191220
    192 /*
    193  *  _Heap_Size_of_user_area
    194  *
    195  *  DESCRIPTION:
    196  *
     221/**
    197222 *  This kernel routine sets size to the size of the given heap block.
    198  *  It returns TRUE if the starting_address is in the heap, and FALSE
     223 *  It returns TRUE if the @a starting_address is in @a the_heap, and FALSE
    199224 *  otherwise.
    200  */
    201 
     225 *
     226 *  @param the_heap (in) is the heap to operate upon
     227 *  @param starting_address (in) is the starting address of the user block
     228 *         to obtain the size of
     229 *  @param size (in) points to a user area to return the size in
     230 *  @return TRUE if successfully able to determine the size, FALSE otherwise
     231 *  @return *size filled in with the size of the user area for this block
     232 */
    202233boolean _Heap_Size_of_user_area(
    203234  Heap_Control        *the_heap,
     
    206237);
    207238
    208 /*
    209  *  _Heap_Free
    210  *
    211  *  DESCRIPTION:
    212  *
     239/**
    213240 *  This routine returns the block of memory which begins
    214  *  at starting_address to the_heap.  Any coalescing which is
     241 *  at @a starting_address to @a the_heap.  Any coalescing which is
    215242 *  possible with the freeing of this routine is performed.
    216  */
    217 
     243 *
     244 *  @param the_heap (in) is the heap to operate upon
     245 *  @param starting_address (in) is the starting address of the user block
     246 *         to free
     247 *  @return TRUE if successfully freed, FALSE otherwise
     248 */
    218249boolean _Heap_Free(
    219250  Heap_Control *the_heap,
     
    221252);
    222253
    223 /*
    224  *  _Heap_Walk
    225  *
    226  *  DESCRIPTION:
    227  *
     254/**
    228255 *  This routine walks the heap to verify its integrity.
    229  */
    230 
     256 * 
     257 *  @param the_heap (in) is the heap to operate upon
     258 *  @param source (in) XXX
     259 *  @param do_dump (in) is set to TRUE if errors should be printed
     260 */
    231261void _Heap_Walk(
    232262  Heap_Control *the_heap,
     
    235265);
    236266
    237 /*PAGE
    238  *
    239  *  _Heap_Get_information
    240  *
     267/**
    241268 *  This kernel routine walks the heap and tots up the free and allocated
    242269 *  sizes.  Derived from _Heap_Walk.
    243270 *
    244  *  Input parameters:
    245  *    the_heap  - pointer to heap header
    246  *    the_info  - pointer to information block
    247  *
    248  *  Output parameters:
    249  *    *the_info - status information
    250  *    return 0=success, otherwise heap is corrupt.
    251  */
    252 
    253 
     271 *  @param the_heap (in) pointer to heap header
     272 *  @param the_info (in) pointer to a status information area
     273 *  @return *the_info is filled with status information
     274 *  @return 0=success, otherwise heap is corrupt.
     275 */
    254276Heap_Get_information_status _Heap_Get_information(
    255277  Heap_Control            *the_heap,
     
    266288#endif
    267289
     290/**@}*/
     291
    268292#endif
    269293/* end of include file */
  • cpukit/score/include/rtems/score/interr.h

    r7ce11b2 rbaff4da  
    1 /*  interr.h
     1/**
     2 *  @file interr.h
    23 *
    34 *  This include file contains constants and prototypes related
    45 *  to the Internal Error Handler.
    5  *
    6  *
    7  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    810 *  On-Line Applications Research Corporation (OAR).
    911 *
     
    1820#define __RTEMS_INTERNAL_ERROR_h
    1921
     22/**
     23 *  @defgroup ScoreIntErr Internal Error Handler
     24 *
     25 *  This group contains functionality which provides the foundation
     26 *  Semaphore services used in all of the APIs supported by RTEMS.
     27 */
     28/**@{*/
     29
    2030#ifdef __cplusplus
    2131extern "C" {
    2232#endif
    2333
    24 /*
     34/**
    2535 *  This type lists the possible sources from which an error
    2636 *  can be reported.
    2737 */
    28 
    2938typedef enum {
    3039  INTERNAL_ERROR_CORE,
     
    3746 *  A list of errors which are generated internally by the executive core.
    3847 */
    39 
    4048typedef enum {
    4149  INTERNAL_ERROR_NO_CONFIGURATION_TABLE,
     
    6169 *  This type holds the fatal error information.
    6270 */
    63 
    6471typedef struct {
    6572  Internal_errors_Source  the_source;
     
    7178 *  When a fatal error occurs, the error information is stored here.
    7279 */
    73 
    7480SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened;
    7581
    76 /*
    77  *  _Internal_error_Occurred
    78  *
    79  *  DESCRIPTION:
     82/** @brief  Internal error Occurred
    8083 *
    8184 *  This routine is invoked when the application or the executive itself
    8285 *  determines that a fatal error has occurred.
    8386 */
    84 
    8587void volatile _Internal_error_Occurred(
    8688  Internal_errors_Source  the_source,
     
    9395#endif
    9496
     97/**@}*/
     98
    9599#endif
    96100/* end of include file */
  • cpukit/score/include/rtems/score/isr.h

    r7ce11b2 rbaff4da  
    1 /*  isr.h
     1/**
     2 *  @file isr.h
    23 *
    34 *  This include file contains all the constants and structures associated
     
    56 *  supports interrupt critical sections, vectoring of user interrupt
    67 *  handlers, nesting of interrupts, and manipulating interrupt levels.
    7  *
    8  *  COPYRIGHT (c) 1989-1999.
     8 */
     9
     10/*
     11 *  COPYRIGHT (c) 1989-2004.
    912 *  On-Line Applications Research Corporation (OAR).
    1013 *
     
    1922#define __ISR_h
    2023
     24/**
     25 *  @defgroup ScoreISR ISR Handler
     26 *
     27 *  This group contains functionality which provides the foundation
     28 *  ISR services used in all of the APIs supported by RTEMS.
     29 */
     30/**@{*/
     31
    2132#ifdef __cplusplus
    2233extern "C" {
    2334#endif
    2435
    25 /*
     36/**
    2637 *  The following type defines the control block used to manage
    2738 *  the interrupt level portion of the status register.
    2839 */
    29 
    3040typedef uint32_t   ISR_Level;
    3141
    32 /*
     42/**
    3343 *  The following type defines the type used to manage the vectors.
    3444 */
    35 
    3645typedef uint32_t   ISR_Vector_number;
    3746
    38 /*
     47/**
    3948 *  Return type for ISR Handler
    4049 */
    41 
    4250typedef void ISR_Handler;
    4351
    44 /*
     52/**
    4553 *  Pointer to an ISR Handler
    4654 */
    47 
    4855#if (CPU_ISR_PASSES_FRAME_POINTER == 1)
    4956typedef ISR_Handler ( *ISR_Handler_entry )(
     
    5663             );
    5764#endif
    58 /*
     65
     66/**
    5967 *  This constant promotes out the number of vectors truly supported by
    6068 *  the current CPU being used.  This is usually the number of distinct vectors
    6169 *  the cpu can vector.
    6270 */
    63 
    6471#define ISR_NUMBER_OF_VECTORS                CPU_INTERRUPT_NUMBER_OF_VECTORS
    6572
    66 /*
     73/**
    6774 *  This constant promotes out the highest valid interrupt vector number.
    6875 */
    69 
    7076#define ISR_INTERRUPT_MAXIMUM_VECTOR_NUMBER  CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER
    7177
    72 /*
     78/**
    7379 *  The following is TRUE if signals have been sent to the currently
    7480 *  executing thread by an ISR handler.
    7581 */
    76 
    7782SCORE_EXTERN boolean    _ISR_Signals_to_thread_executing;
    7883
    79 /*
     84/**
    8085 *  The following contains the interrupt service routine nest level.
    8186 *  When this variable is zero, a thread is executing.
    8287 */
    83 
    8488SCORE_EXTERN volatile uint32_t   _ISR_Nest_level;
    8589
    86 /*
     90/**
    8791 *  The following declares the Vector Table.  Application
    8892 *  interrupt service routines are vectored by the ISR Handler via this table.
    8993 */
    90 
    9194SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table;
    9295
    93 /*
    94  *  _ISR_Handler_initialization
    95  *
    96  *  DESCRIPTION:
    97  *
     96/**
    9897 *  This routine performs the initialization necessary for this handler.
    9998 */
    100 
    10199void _ISR_Handler_initialization ( void );
    102100
    103 /*
    104  *  _ISR_Disable
    105  *
    106  *  DESCRIPTION:
    107  *
     101/**
    108102 *  This routine disables all interrupts so that a critical section
    109103 *  of code can be executing without being interrupted.  Upon return,
    110104 *  the argument _level will contain the previous interrupt mask level.
    111105 */
    112 
    113106#define _ISR_Disable( _level ) \
    114107        _CPU_ISR_Disable( _level )
    115108
    116 /*
    117  *  _ISR_Enable
    118  *
    119  *  DESCRIPTION:
    120  *
     109/**
    121110 *  This routine enables interrupts to the previous interrupt mask
    122111 *  LEVEL.  It is used at the end of a critical section of code to
    123112 *  enable interrupts so they can be processed again.
    124113 */
    125 
    126114#define _ISR_Enable( _level ) \
    127115        _CPU_ISR_Enable( _level )
    128116
    129 /*
    130  *  _ISR_Flash
    131  *
    132  *  DESCRIPTION:
    133  *
     117/**
    134118 *  This routine temporarily enables interrupts to the previous
    135119 *  interrupt mask level and then disables all interrupts so that
     
    143127 *  properly protects itself.
    144128 */
    145 
    146129#define _ISR_Flash( _level ) \
    147130        _CPU_ISR_Flash( _level )
    148131
    149 /*
    150  *  _ISR_Install_vector
    151  *
    152  *  DESCRIPTION:
    153  *
     132/**
    154133 *  This routine installs new_handler as the interrupt service routine
    155134 *  for the specified vector.  The previous interrupt service routine is
    156135 *  returned as old_handler.
    157136 */
    158 
    159137#define _ISR_Install_vector( _vector, _new_handler, _old_handler ) \
    160138  _CPU_ISR_install_vector( _vector, _new_handler, _old_handler )
    161139
    162 /*
    163  *  _ISR_Get_level
    164  *
    165  *  DESCRIPTION:
    166  *
     140/**
    167141 *  This routine returns the current interrupt level.
    168142 */
    169 
    170143#define _ISR_Get_level() \
    171144        _CPU_ISR_Get_level()
    172145
    173 /*
    174  *  _ISR_Set_level
    175  *
    176  *  DESCRIPTION:
    177  *
     146/**
    178147 *  This routine sets the current interrupt level to that specified
    179148 *  by new_level.  The new interrupt level is effective when the
    180149 *  routine exits.
    181150 */
    182 
    183151#define _ISR_Set_level( _new_level ) \
    184152        _CPU_ISR_Set_level( _new_level )
    185153
    186 /*
    187  *  _ISR_Handler
    188  *
    189  *  DESCRIPTION:
    190  *
     154/**
    191155 *  This routine is the interrupt dispatcher.  ALL interrupts
    192156 *  are vectored to this routine so that minimal context can be saved
     
    198162 *  performed when the outermost interrupt service routine exits.
    199163 *
    200  *  NOTE:  Implemented in assembly language.
    201  */
    202 
     164 *  @note  Implemented in assembly language.
     165 */
    203166void _ISR_Handler( void );
    204167
    205 /*
    206  *  _ISR_Dispatch
    207  *
    208  *  DESCRIPTION:
    209  *
     168/**
    210169 *  This routine provides a wrapper so that the routine
    211  *  _Thread_Dispatch can be invoked when a reschedule is necessary
     170 *  @ref _Thread_Dispatch can be invoked when a reschedule is necessary
    212171 *  at the end of the outermost interrupt service routine.  This
    213172 *  wrapper is necessary to establish the processor context needed
     
    216175 *  of registers which are not preserved across routine invocations.
    217176 *
    218  *  NOTE:  Implemented in assembly language.
    219  */
    220 
     177 *  @note  Implemented in assembly language.
     178 */
    221179void _ISR_Dispatch( void );
    222180
    223 /*PAGE
    224  *
    225  *  _ISR_Is_in_progress
    226  *
    227  *  DESCRIPTION:
    228  *
     181/**
    229182 *  This function returns TRUE if the processor is currently servicing
    230183 *  and interrupt and FALSE otherwise.   A return value of TRUE indicates
    231184 *  that the caller is an interrupt service routine, NOT a thread.  The
    232185 */
    233 
    234186#if (CPU_PROVIDES_ISR_IS_IN_PROGRESS == TRUE)
    235187boolean _ISR_Is_in_progress( void );
     
    245197#endif
    246198
     199/**@}*/
     200
    247201#endif
    248202/* end of include file */
  • cpukit/score/include/rtems/score/mpci.h

    r7ce11b2 rbaff4da  
    1 /*  mpci.h
     1/**
     2 *  @file mpci.h
    23 *
    34 *  This include file contains all the constants and structures associated
    45 *  with the MPCI layer.  It provides mechanisms to utilize packets.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1619#ifndef __MPCI_h
    1720#define __MPCI_h
     21
     22/**
     23 *  @defgroup ScoreMPCI MPCI Handler
     24 *
     25 *  This group contains functionality which XXX
     26 */
     27/**@{*/
    1828
    1929#ifdef __cplusplus
     
    3343 *  the system threads.
    3444 */
    35 
    3645#define MPCI_RECEIVE_SERVER_STACK_SIZE \
    3746  ( STACK_MINIMUM_SIZE + \
     
    4352 *  The following defines the node number used when a broadcast is desired.
    4453 */
    45 
    4654#define MPCI_ALL_NODES 0
    4755
     
    5260 *   should take to complete.
    5361 */
    54 
    5562#define MPCI_DEFAULT_TIMEOUT    0xFFFFFFFF
    5663
     
    6471 */
    6572
     73/**
     74 *  This type is returned by all user provided MPCI routines.
     75 */
    6676typedef void MPCI_Entry;
    6777
     78/**
     79 *  This type is XXX
     80 */
    6881typedef MPCI_Entry ( *MPCI_initialization_entry )( void );
    6982
     83/**
     84 *  This type is XXX
     85 */
    7086typedef MPCI_Entry ( *MPCI_get_packet_entry )(
    7187                 MP_packet_Prefix **
    7288             );
    7389
     90/**
     91 *  This type is XXX
     92 */
    7493typedef MPCI_Entry ( *MPCI_return_packet_entry )(
    7594                 MP_packet_Prefix *
    7695             );
    7796
     97/**
     98 *  This type is XXX
     99 */
    78100typedef MPCI_Entry ( *MPCI_send_entry )(
    79101                 uint32_t  ,
     
    81103             );
    82104
     105/**
     106 *  This type is XXX
     107 */
    83108typedef MPCI_Entry ( *MPCI_receive_entry )(
    84109                 MP_packet_Prefix **
    85110             );
    86111
     112/**
     113 *  This type is XXX
     114 */
    87115typedef struct {
    88   uint32_t                   default_timeout;        /* in ticks */
     116  /** timeout for MPCI operations in ticks */
     117  uint32_t                   default_timeout;
     118  /** XXX */
    89119  uint32_t                   maximum_packet_size;
     120  /** XXX */
    90121  MPCI_initialization_entry  initialization;
     122  /** XXX */
    91123  MPCI_get_packet_entry      get_packet;
     124  /** XXX */
    92125  MPCI_return_packet_entry   return_packet;
     126  /** XXX */
    93127  MPCI_send_entry            send_packet;
     128  /** XXX */
    94129  MPCI_receive_entry         receive_packet;
    95130} MPCI_Control;
    96131
    97 /*
     132/**
    98133 *  The following defines the type for packet processing routines
    99134 *  invoked by the MPCI Receive server.
    100135 */
    101 
    102136typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * );
    103137
    104 /*
     138/**
    105139 *  The following enumerated type defines the list of
    106140 *  internal MP operations.
    107141 */
    108 
    109142typedef enum {
    110143  MPCI_PACKETS_SYSTEM_VERIFY  =  0
    111144}   MPCI_Internal_Remote_operations;
    112145
    113 /*
     146/**
    114147 *  The following data structure defines the packet used to perform
    115148 *  remote event operations.
    116149 */
    117 
    118150typedef struct {
     151  /** XXX */
    119152  MP_packet_Prefix                 Prefix;
     153  /** XXX */
    120154  MPCI_Internal_Remote_operations  operation;
     155  /** XXX */
    121156  uint32_t                         maximum_nodes;
     157  /** XXX */
    122158  uint32_t                         maximum_global_objects;
    123159}    MPCI_Internal_packet;
    124160
    125 /*
     161/**
    126162 *  This is the core semaphore which the MPCI Receive Server blocks on.
    127163 */
    128 
    129164SCORE_EXTERN CORE_semaphore_Control _MPCI_Semaphore;
    130 /*
     165
     166/**
    131167 *  The following thread queue is used to maintain a list of tasks
    132168 *  which currently have outstanding remote requests.
    133169 */
    134 
    135170SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads;
    136171
    137 /*
     172/**
    138173 *  The following define the internal pointers to the user's
    139174 *  configuration information.
    140175 */
    141 
    142176SCORE_EXTERN MPCI_Control *_MPCI_table;
    143177
    144 /*
     178/**
    145179 *  The following points to the MPCI Receive Server.
    146180 */
    147 
    148181SCORE_EXTERN Thread_Control *_MPCI_Receive_server_tcb;
    149182
    150 /*
     183/**
    151184 *  The following table contains the process packet routines provided
    152185 *  by each object that supports MP operations.
    153186 */
    154 
    155187SCORE_EXTERN MPCI_Packet_processor
    156188               _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1];
    157189
    158 /*
    159  *  _MPCI_Handler_initialization
    160  *
    161  *  DESCRIPTION:
    162  *
     190/**
    163191 *  This routine performs the initialization necessary for this handler.
    164192 */
    165 
    166193void _MPCI_Handler_initialization(
    167194  MPCI_Control            *users_mpci_table,
     
    169196);
    170197
    171 /*
    172  *  _MPCI_Create_server
    173  *
    174  *  DESCRIPTION:
    175  *
     198/**
    176199 *  This routine creates the packet receive server used in MP systems.
    177200 */
    178 
    179201void _MPCI_Create_server( void );
    180202
    181 /*
    182  *  _MPCI_Initialization
    183  *
    184  *  DESCRIPTION:
    185  *
     203/**
    186204 *  This routine initializes the MPCI driver by
    187205 *  invoking the user provided MPCI initialization callout.
    188206 */
    189 
    190207void _MPCI_Initialization ( void );
    191208
    192 /*
    193  *  _MPCI_Register_packet_processor
    194  *
    195  *  DESCRIPTION:
    196  *
     209/**
    197210 *  This routine registers the MPCI packet processor for the
    198211 *  designated object class.
    199212 */
    200 
    201213void _MPCI_Register_packet_processor(
    202214  MP_packet_Classes      the_class,
     
    205217);
    206218
    207 /*
    208  *  _MPCI_Get_packet
    209  *
    210  *  DESCRIPTION:
    211  *
     219/**
    212220 *  This function obtains a packet by invoking the user provided
    213221 *  MPCI get packet callout.
    214222 */
    215 
    216223MP_packet_Prefix *_MPCI_Get_packet ( void );
    217224
    218 /*
    219  *  _MPCI_Return_packet
    220  *
    221  *  DESCRIPTION:
    222  *
     225/**
    223226 *  This routine returns a packet by invoking the user provided
    224227 *  MPCI return packet callout.
    225228 */
    226 
    227229void _MPCI_Return_packet (
    228230  MP_packet_Prefix *the_packet
    229231);
    230232
    231 /*
    232  *  _MPCI_Send_process_packet
    233  *
    234  *  DESCRIPTION:
    235  *
     233/**
    236234 *  This routine sends a process packet by invoking the user provided
    237235 *  MPCI send callout.
    238236 */
    239 
    240237void _MPCI_Send_process_packet (
    241238  uint32_t          destination,
     
    243240);
    244241
    245 /*
    246  *  _MPCI_Send_request_packet
    247  *
    248  *  DESCRIPTION:
    249  *
     242/**
    250243 *  This routine sends a request packet by invoking the user provided
    251244 *  MPCI send callout.
    252245 */
    253 
    254246uint32_t   _MPCI_Send_request_packet (
    255247  uint32_t           destination,
     
    258250);
    259251
    260 /*
    261  *  _MPCI_Send_response_packet
    262  *
    263  *  DESCRIPTION:
    264  *
     252/**
    265253 *  This routine sends a response packet by invoking the user provided
    266254 *  MPCI send callout.
    267255 */
    268 
    269256void _MPCI_Send_response_packet (
    270257  uint32_t          destination,
     
    272259);
    273260
    274 /*
    275  *  _MPCI_Receive_packet
    276  *
    277  *  DESCRIPTION:
    278  *
     261/**
    279262 *  This routine receives a packet by invoking the user provided
    280263 *  MPCI receive callout.
    281264 */
    282 
    283265MP_packet_Prefix  *_MPCI_Receive_packet ( void );
    284266
    285 /*
    286  *  _MPCI_Process_response
    287  *
    288  *  DESCRIPTION:
    289  *
     267/**
    290268 *  This routine obtains a packet by invoking the user provided
    291269 *  MPCI get packet callout.
    292270 */
    293 
    294271Thread_Control *_MPCI_Process_response (
    295272  MP_packet_Prefix *the_packet
    296273);
    297274
    298 /*PAGE
    299  *
    300  *  _MPCI_Receive_server
    301  *
    302  */
    303 
     275/**
     276 *  This is the server thread which receives and processes all MCPI packets.
     277 */
    304278Thread _MPCI_Receive_server(
    305279  uint32_t   ignored
    306280);
    307281
    308 /*PAGE
    309  *
    310  *  _MPCI_Announce
    311  *
    312  *  DESCRIPTION:
    313  *
    314  *  XXX
    315  */
    316 
     282/**
     283 *  This routine informs RTEMS of the availability of an MPCI packet.
     284 */
    317285void _MPCI_Announce ( void );
    318286
    319 /*
    320  *  _MPCI_Internal_packets_Send_process_packet
    321  *
    322  *  DESCRIPTION:
    323  *
     287/**
    324288 *  This routine performs a remote procedure call so that a
    325289 *  process operation can be performed on another node.
    326290 */
    327 
    328291void _MPCI_Internal_packets_Send_process_packet (
    329292   MPCI_Internal_Remote_operations operation
     
    333296 *  _MPCI_Internal_packets_Send_request_packet
    334297 *
    335  *  DESCRIPTION:
    336  *
    337298 *  This routine performs a remote procedure call so that a
    338299 *  directive operation can be initiated on another node.
     
    345306 *  _MPCI_Internal_packets_Send_response_packet
    346307 *
    347  *  DESCRIPTION:
    348  *
    349308 *  This routine performs a remote procedure call so that a
    350309 *  directive can be performed on another node.
     
    354313 */
    355314
    356 /*
    357  *
    358  *  _MPCI_Internal_packets_Process_packet
    359  *
    360  *  DESCRIPTION:
    361  *
     315/**
    362316 *  This routine performs the actions specific to this package for
    363317 *  the request from another node.
    364318 */
    365 
    366319void _MPCI_Internal_packets_Process_packet (
    367320  MP_packet_Prefix *the_packet_prefix
     
    370323/*
    371324 *  _MPCI_Internal_packets_Send_object_was_deleted
    372  *
    373  *  DESCRIPTION:
    374325 *
    375326 *  This routine is invoked indirectly by the thread queue
     
    384335 *  _MPCI_Internal_packets_Send_extract_proxy
    385336 *
    386  *  DESCRIPTION:
    387  *
    388337 *  This routine is invoked when a task is deleted and it
    389338 *  has a proxy which must be removed from a thread queue and
     
    394343 */
    395344
    396 /*
    397  *  _MPCI_Internal_packets_Get_packet
    398  *
    399  *  DESCRIPTION:
    400  *
     345/**
    401346 *  This routine is used to obtain a internal threads mp packet.
    402347 */
    403 
    404  MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
     348MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
    405349
    406350#ifdef __cplusplus
     
    408352#endif
    409353
     354/**@}*/
     355
    410356#endif
    411357/* end of include file */
  • cpukit/score/include/rtems/score/mppkt.h

    r7ce11b2 rbaff4da  
    1 /*  mppkt.h
     1/**
     2 *  @file mppkt.h
    23 *
    34 *  This package is the specification for the Packet Handler.
     
    67 *  Packets are the fundamental basis for messages passed between
    78 *  nodes in an MP system.
    8  *
    9  *
    10  *  COPYRIGHT (c) 1989-1999.
     9 */
     10
     11/*
     12 *  COPYRIGHT (c) 1989-2004.
    1113 *  On-Line Applications Research Corporation (OAR).
    1214 *
     
    2123#define __MP_PACKET_h
    2224
     25/**
     26 *  @defgroup ScoreMPPacket MP Packet Handler
     27 *
     28 *  This group contains functionality which XXX
     29 */
     30/**@{*/
     31
    2332#ifdef __cplusplus
    2433extern "C" {
     
    2938#include <rtems/score/watchdog.h>
    3039
    31 /*
     40/**
    3241 *  The following enumerated type defines the packet classes.
    3342 *
    34  *  NOTE:  In general, each class corresponds to a manager
     43 *  @note  In general, each class corresponds to a manager
    3544 *         which supports global operations.  Each manager
    3645 *         defines the set of supported operations.
    3746 */
    38 
    3947typedef enum {
    4048  MP_PACKET_MPCI_INTERNAL    = 0,
     
    4856}   MP_packet_Classes;
    4957
     58/**
     59 *  XXX
     60 */
    5061#define MP_PACKET_CLASSES_FIRST  MP_PACKET_MPCI_INTERNAL
     62
     63/**
     64 *  XXX
     65 */
    5166#define MP_PACKET_CLASSES_LAST   MP_PACKET_SIGNAL
    5267
    53 /*
     68/**
    5469 *  The following record contains the prefix for every packet
    5570 *  passed between nodes in an MP system.
    5671 *
    57  *  NOTE: This structure is padded to ensure that anything following it
     72 *  @note This structure is padded to ensure that anything following it
    5873 *        is on a 16 byte boundary.  This is the most stringent structure
    5974 *        alignment rule encountered yet.
    6075 */
    61 
    6276typedef struct {
     77  /** XXX */
    6378  MP_packet_Classes       the_class;
     79  /** XXX */
    6480  Objects_Id              id;
     81  /** XXX */
    6582  Objects_Id              source_tid;
     83  /** XXX */
    6684  Priority_Control        source_priority;
     85  /** XXX */
    6786  uint32_t                return_code;
     87  /** XXX */
    6888  uint32_t                length;
     89  /** XXX */
    6990  uint32_t                to_convert;
     91  /** XXX */
    7092  Watchdog_Interval       timeout;
    7193}   MP_packet_Prefix;
    7294
    73 /*
     95/**
    7496 *  An MPCI must support packets of at least this size.
    7597 */
    76 
    7798#define MP_PACKET_MINIMUM_PACKET_SIZE  64
    7899
    79 /*
     100/**
    80101 *  The following constant defines the number of uint32_t  's
    81102 *  in a packet which must be converted to native format in a
     
    84105 *  may a user message buffer which is not automatically endian swapped.
    85106 */
    86 
    87107#define MP_PACKET_MINIMUN_HETERO_CONVERSION  \
    88108  ( sizeof( MP_packet_Prefix ) / sizeof( uint32_t   ) )
     
    96116#endif
    97117
     118/**@}*/
     119
    98120#endif
    99121/* end of include file */
  • cpukit/score/include/rtems/score/objectmp.h

    r7ce11b2 rbaff4da  
    1 /*  objectmp.h
     1/**
     2 *  @file objectmp.h
    23 *
    34 *  This include file contains all the constants and structures associated
    45 *  with the manipulation of Global RTEMS Objects.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1720#define __RTEMS_OBJECTS_MP_h
    1821
     22/**
     23 *  @defgroup ScoreObjectMP Object Handler Multiprocessing Support
     24 *
     25 *  This group contains functionality which XXX
     26 */
     27/**@{*/
     28
    1929#ifdef __cplusplus
    2030extern "C" {
     
    2535 *  objects resident on other nodes.
    2636 */
    27 
    2837typedef struct {
    2938  Objects_Control Object;
     
    3241}   Objects_MP_Control;
    3342
    34 /*
    35  *  _Objects_MP_Handler_initialization
    36  *
    37  *  DESCRIPTION:
     43/** @brief  Objects MP Handler initialization
    3844 *
    3945 *  This routine intializes the inactive global object chain
    4046 *  based on the maximum number of global objects configured.
    4147 */
    42 
    4348void _Objects_MP_Handler_initialization (
    4449  uint32_t   node,
     
    4752);
    4853
    49 /*PAGE
    50  *
    51  *  _Objects_MP_Open
    52  *
    53  *  DESCRIPTION:
     54/** @brief Objects MP Open
    5455 *
    5556 *  This routine place the specified global object in the
     
    6465);
    6566
    66 /*
    67  *  _Objects_MP_Allocate_and_open
    68  *
    69  *  DESCRIPTION:
     67/** @brief  Objects MP Allocate and open
    7068 *
    7169 *  This routine allocates a global object control block
     
    7472 *  error processing actions taken.
    7573 */
    76 
    7774boolean _Objects_MP_Allocate_and_open (
    7875  Objects_Information *information,
     
    8279);
    8380
    84 /*
    85  *  _Objects_MP_Close
    86  *
    87  *  DESCRIPTION:
     81/** @brief  Objects MP Close
    8882 *
    8983 *  This routine removes a global object from the specified
    9084 *  information table and deallocates the global object control block.
    9185 */
    92 
    9386void _Objects_MP_Close (
    9487  Objects_Information *information,
     
    9689);
    9790
    98 /*
    99  *  _Objects_MP_Global_name_search
    100  *
    101  *  DESCRIPTION:
     91/** @brief  Objects MP Global name search
    10292 *
    10393 *  This routine looks for the object with the_name in the global
     
    10595 *  object with that name if one is found.
    10696 */
    107 
    10897Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
    10998  Objects_Information *information,
     
    113102);
    114103
    115 /*
    116  *  _Objects_MP_Is_remote
    117  *
    118  *  DESCRIPTION:
     104/** @brief  Objects MP Is remote
    119105 *
    120106 *  This function searches the Global Object Table managed
     
    124110 *  is undefined.
    125111 */
    126 
    127112void _Objects_MP_Is_remote (
    128113  Objects_Information  *information,
     
    136121 *  inactive global object control blocks.
    137122 */
    138 
    139123SCORE_EXTERN uint32_t       _Objects_MP_Maximum_global_objects;
    140124SCORE_EXTERN Chain_Control  _Objects_MP_Inactive_global_objects;
     
    148132#endif
    149133
     134/**@}*/
     135
    150136#endif
    151137/* end of include file */
  • cpukit/score/include/rtems/score/priority.h

    r7ce11b2 rbaff4da  
    1 /*  priority.h
     1/**
     2 *  @file priority.h
    23 *
    34 *  This include file contains all thread priority manipulation routines.
    45 *  This Handler provides mechanisms which can be used to
    56 *  initialize and manipulate thread priorities.
    6  *
    7  *  COPYRIGHT (c) 1989-1999.
     7 */
     8
     9/*
     10 *  COPYRIGHT (c) 1989-2004.
    811 *  On-Line Applications Research Corporation (OAR).
    912 *
     
    1821#define __PRIORITY_h
    1922
     23/**
     24 *  @defgroup ScorePriority Priority Handler
     25 *
     26 *  This group contains functionality which XXX
     27 */
     28/**@{*/
     29
    2030#ifdef __cplusplus
    2131extern "C" {
     
    2636 *  thread priorities.
    2737 *
    28  *  NOTE: Priority 0 is reserved for internal threads only.
     38 *  @note Priority 0 is reserved for internal threads only.
    2939 */
    3040
     
    7080 *  Priority Bitfield Manipulation Routines
    7181 *
    72  *  NOTE:
     82 *  @note
    7383 *
    7484 *  These may simply be pass throughs to CPU dependent routines.
     
    93103#endif
    94104
     105/**@}*/
     106
    95107#endif
    96108/* end of include file */
  • cpukit/score/include/rtems/score/stack.h

    r7ce11b2 rbaff4da  
    1 /*  stack.h
     1/**
     2 *  @file stack.h
    23 *
    34 *  This include file contains all information about the thread
    45 *  Stack Handler.  This Handler provides mechanisms which can be used to
    56 *  initialize and utilize stacks.
    6  *
    7  *  COPYRIGHT (c) 1989-1999.
     7 */
     8
     9/*
     10 *  COPYRIGHT (c) 1989-2004.
    811 *  On-Line Applications Research Corporation (OAR).
    912 *
     
    1720#ifndef __STACK_h
    1821#define __STACK_h
     22
     23/**
     24 *  @defgroup ScoreStack Stack Handler
     25 *
     26 *  This group contains functionality which XXX
     27 */
     28/**@{*/
    1929
    2030#ifdef __cplusplus
     
    4656#endif
    4757
     58/**@}*/
     59
    4860#endif
    4961/* end of include file */
  • cpukit/score/include/rtems/score/states.h

    r7ce11b2 rbaff4da  
    1 /*  states.h
     1/**
     2 *  @file states.h
    23 *
    34 *  This include file contains thread execution state information.
    4  *
    5  *  COPYRIGHT (c) 1989-1999.
     5 */
     6
     7/*
     8 *  COPYRIGHT (c) 1989-2004.
    69 *  On-Line Applications Research Corporation (OAR).
    710 *
     
    1518#ifndef __RTEMS_STATES_h
    1619#define __RTEMS_STATES_h
     20
     21/**
     22 *  @defgroup ScoreStates Thread States Handler
     23 *
     24 *  This group contains functionality which XXX
     25 */
     26/**@{*/
    1727
    1828#ifdef __cplusplus
     
    8090#endif
    8191
     92/**@}*/
     93
    8294#endif
    8395/* end of include file */
  • cpukit/score/include/rtems/score/sysstate.h

    r7ce11b2 rbaff4da  
    1 /*  sysstates.h
     1/**
     2 *  @file sysstate.h
    23 *
    34 *  This include file contains information regarding the system state.
    4  *
    5  *  COPYRIGHT (c) 1989-1999.
     5 */
     6
     7/*
     8 *  COPYRIGHT (c) 1989-2004.
    69 *  On-Line Applications Research Corporation (OAR).
    710 *
     
    1518#ifndef __RTEMS_SYSTEM_STATE_h
    1619#define __RTEMS_SYSTEM_STATE_h
     20
     21/**
     22 *  @defgroup ScoreSysState System State Handler
     23 *
     24 *  This group contains functionality which XXX
     25 */
     26/**@{*/
    1727
    1828#ifdef __cplusplus
     
    6373#endif
    6474
     75/**@}*/
     76
    6577#endif
    6678/* end of include file */
  • cpukit/score/include/rtems/score/thread.h

    r7ce11b2 rbaff4da  
    1 /*  thread.h
     1/**
     2 *  @file thread.h
    23 *
    34 *  This include file contains all constants and structures associated
    45 *  with the thread control block.
    5  *
    6  *  COPYRIGHT (c) 1989-1999.
     6 */
     7
     8/*
     9 *  COPYRIGHT (c) 1989-2004.
    710 *  On-Line Applications Research Corporation (OAR).
    811 *
     
    1619#ifndef __THREAD_h
    1720#define __THREAD_h
     21
     22/**
     23 *  @defgroup ScoreThread Thread Handler
     24 *
     25 *  This group contains functionality which XXX
     26 */
     27/**@{*/
    1828
    1929#ifdef __cplusplus
     
    3444#include <rtems/score/watchdog.h>
    3545
    36 /*
     46/**
    3747 *  The following defines the "return type" of a thread.
    3848 *
    39  *  NOTE:  This cannot always be right.  Some APIs have void
     49 *  @note  This cannot always be right.  Some APIs have void
    4050 *         tasks/threads, others return pointers, others may
    4151 *         return a numeric value.  Hopefully a pointer is
    4252 *         always at least as big as an uint32_t  . :)
    4353 */
    44 
    4554typedef void *Thread;
    4655
    47 /*
     56/**
    4857 *  The following defines the ways in which the entry point for a
    4958 *  thread can be invoked.  Basically, it can be passed any
    5059 *  combination/permutation of a pointer and an uint32_t   value.
    5160 *
    52  *  NOTE: For now, we are ignoring the return type.
    53  */
    54 
     61 *  @note For now, we are ignoring the return type.
     62 */
    5563typedef enum {
    5664  THREAD_START_NUMERIC,
     
    6068} Thread_Start_types;
    6169
     70/**
     71 */
    6272typedef Thread ( *Thread_Entry )();   /* basic type */
    6373
    6474typedef Thread ( *Thread_Entry_numeric )( uint32_t   );
     75
     76/**
     77 */
    6578typedef Thread ( *Thread_Entry_pointer )( void * );
     79
     80/**
     81 */
    6682typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t   );
     83
     84/**
     85 */
    6786typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t  , void * );
    6887
    69 /*
     88/**
    7089 *  The following lists the algorithms used to manage the thread cpu budget.
    7190 *
     
    7493 *  Callout:           Execute routine when budget is consumed.
    7594 */
    76 
    7795typedef enum {
    7896  THREAD_CPU_BUDGET_ALGORITHM_NONE,
     
    82100}  Thread_CPU_budget_algorithms;
    83101
     102/**
     103 */
    84104typedef struct Thread_Control_struct Thread_Control;
    85105
     106/**
     107 */
    86108typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
    87109
    88 /*
    89  *  Per task variable structure
    90  */
    91 
     110/** @brief Per Task Variable Manager Structure Forward Reference
     111 *
     112 *  Forward reference to the per task variable structure.
     113 */
    92114struct rtems_task_variable_tt;
    93115
     116/** @brief Per Task Variable Manager Structure
     117 *
     118 *  This is the internal structure used to manager per Task Variables.
     119 */
    94120struct rtems_task_variable_tt {
     121  /** This field points to the next per task variable for this task. */
    95122  struct rtems_task_variable_tt  *next;
     123  /** This field points to the physical memory location of this per
     124   *  task variable.
     125   */
    96126  void                          **ptr;
     127  /** This field is to the global value for this per task variable. */
    97128  void                           *gval;
     129  /** This field is to this thread's value for this per task variable. */
    98130  void                           *tval;
     131  /** This field points to the destructor for this per task variable. */
    99132  void                          (*dtor)(void *);
    100133};
    101134
     135/**
     136 */
    102137typedef struct rtems_task_variable_tt   rtems_task_variable_t;
    103138
    104 /*
     139/**
    105140 *  The following structure contains the information which defines
    106141 *  the starting state of a thread.
    107142 */
    108 
    109143typedef struct {
    110144  Thread_Entry         entry_point;      /* starting thread address         */
     
    126160}   Thread_Start_information;
    127161
    128 /*
     162/**
    129163 *  The following structure contains the information necessary to manage
    130164 *  a thread which it is  waiting for a resource.
    131165 */
    132 
    133166#define THREAD_STATUS_PROXY_BLOCKING 0x1111111
    134167
     168/** @brief Thread Blocking Management Information
     169 *
     170 *  This contains the information required to manage a thread while it is
     171 *  blocked and to return information to it.
     172 */
    135173typedef struct {
    136   Objects_Id            id;              /* waiting on this object       */
    137   uint32_t              count;           /* "generic" fields to be used */
    138   void                 *return_argument; /*   when blocking */
     174  /** This field is the Id of the object this thread is waiting upon. */
     175  Objects_Id            id;
     176  /** This field is used to return an integer while when blocked. */
     177  uint32_t              count;
     178  /** This field is the first pointer to a user return argument. */
     179  void                 *return_argument;
     180  /** This field is the second pointer to a user return argument. */
    139181  void                 *return_argument_1;
     182  /** This field contains any options in effect on this blocking operation. */
    140183  uint32_t              option;
    141 
    142   /*
    143    *  NOTE: The following assumes that all API return codes can be
    144    *        treated as an uint32_t  .
     184  /** This field will contain the return status from a blocking operation.
     185   *
     186   *  @note The following assumes that all API return codes can be
     187   *        treated as an uint32_t.
    145188   */
    146   uint32_t              return_code;     /* status for thread awakened   */
    147 
    148   Chain_Control         Block2n;         /* 2 - n priority blocked chain */
    149   Thread_queue_Control *queue;           /* pointer to thread queue      */
     189  uint32_t              return_code;
     190
     191  /** This field is the chain header for the second through Nth tasks
     192   *  of the same priority blocked waiting on the same object.
     193   */
     194  Chain_Control         Block2n;
     195  /** This field points to the thread queue on which this thread is blocked. */
     196  Thread_queue_Control *queue;
    150197}   Thread_Wait_information;
    151198
    152 /*
     199/**
    153200 *  The following defines the control block used to manage
    154201 *  each thread proxy.
    155202 *
    156  *  NOTE: It is critical that proxies and threads have identical
     203 *  @note It is critical that proxies and threads have identical
    157204 *        memory images for the shared part.
    158205 */
    159 
    160206typedef struct {
    161207  Objects_Control          Object;
     
    173219}   Thread_Proxy_control;
    174220
    175 
    176 /*
     221/**
    177222 *  The following record defines the control block used
    178223 *  to manage each thread.
    179224 *
    180  *  NOTE: It is critical that proxies and threads have identical
     225 *  @note It is critical that proxies and threads have identical
    181226 *        memory images for the shared part.
    182227 */
    183 
    184228typedef enum {
    185229  THREAD_API_RTEMS,
     
    188232}  Thread_APIs;
    189233
     234/**
     235 */
    190236#define THREAD_API_FIRST THREAD_API_RTEMS
     237
     238/**
     239 */
    191240#define THREAD_API_LAST  THREAD_API_ITRON
    192241
     242/**
     243 */
    193244struct Thread_Control_struct {
    194245  Objects_Control                       Object;
     
    227278};
    228279
    229 /*
     280/**
    230281 *  Self for the GNU Ada Run-Time
    231282 */
    232 
    233283SCORE_EXTERN void *rtems_ada_self;
    234284
    235 /*
     285/**
    236286 *  The following defines the information control block used to
    237287 *  manage this class of objects.
    238288 */
    239 
    240289SCORE_EXTERN Objects_Information _Thread_Internal_information;
    241290
    242 /*
     291/**
    243292 *  The following define the thread control pointers used to access
    244293 *  and manipulate the idle thread.
    245294 */
    246 
    247295SCORE_EXTERN Thread_Control *_Thread_Idle;
    248296
    249 /*
     297/**
    250298 *  The following context area contains the context of the "thread"
    251299 *  which invoked the start multitasking routine.  This context is
     
    254302 *  which initiated the system.
    255303 */
    256 
    257304SCORE_EXTERN Context_Control _Thread_BSP_context;
    258305
    259 /*
     306/***
    260307 *  The following declares the dispatch critical section nesting
    261308 *  counter which is used to prevent context switches at inopportune
    262309 *  moments.
    263310 */
    264 
    265311SCORE_EXTERN volatile uint32_t   _Thread_Dispatch_disable_level;
    266312
    267 /*
     313/**
    268314 *  If this is non-zero, then the post-task switch extension
    269315 *  is run regardless of the state of the per thread flag.
    270316 */
    271 
    272317SCORE_EXTERN uint32_t   _Thread_Do_post_task_switch_extension;
    273318
    274 /*
     319/**
    275320 *  The following holds how many user extensions are in the system.  This
    276321 *  is used to determine how many user extension data areas to allocate
    277322 *  per thread.
    278323 */
    279 
    280324SCORE_EXTERN uint32_t   _Thread_Maximum_extensions;
    281325
    282 /*
     326/**
    283327 *  The following is used to manage the length of a timeslice quantum.
    284328 */
    285 
    286329SCORE_EXTERN uint32_t   _Thread_Ticks_per_timeslice;
    287330
    288 /*
     331/**
    289332 *  The following points to the array of FIFOs used to manage the
    290333 *  set of ready threads.
    291334 */
    292 
    293335SCORE_EXTERN Chain_Control *_Thread_Ready_chain;
    294336
    295 /*
     337/**
    296338 *  The following points to the thread which is currently executing.
    297339 *  This thread is implicitly manipulated by numerous directives.
    298340 */
    299 
    300341SCORE_EXTERN Thread_Control *_Thread_Executing;
    301342
    302 /*
     343/**
    303344 *  The following points to the highest priority ready thread
    304345 *  in the system.  Unless the current thread is not preemptibl,
     
    306347 *  dispatch occurs.
    307348 */
    308 
    309349SCORE_EXTERN Thread_Control *_Thread_Heir;
    310350