Changeset 7497f5e in rtems-docs


Ignore:
Timestamp:
Oct 28, 2016, 8:57:11 PM (3 years ago)
Author:
Joel Sherrill <joel@…>
Branches:
4.11, master
Children:
9dd79f2
Parents:
790fcab
Message:

porting: Review and tidy up multiple formatting issues.

Location:
porting
Files:
11 edited

Legend:

Unmodified
Added
Removed
  • porting/code_tuning.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Code Tuning Parameters
     
    913Should the calls to _Thread_Enable_dispatch be inlined?
    1014
    11 If TRUE, then they are inlined.
     15- If ``TRUE``, then they are inlined.
    1216
    13 If FALSE, then a subroutine call is made.
     17- If ``FALSE``, then a subroutine call is made.
    1418
    1519Basically this is an example of the classic trade-off of size versus
     
    2226which in turns calls _Thread_Dispatch.  If the enable dispatch is inlined,
    2327then one subroutine call is avoided entirely.]
     28
    2429.. code-block:: c
    2530
     
    3439per iteration.
    3540
    36 If TRUE, then the loops are unrolled.
    37 
    38 If FALSE, then the loops are not unrolled.
     41- If ``TRUE``, then the loops are unrolled.
     42 
     43- If ``FALSE``, then the loops are not unrolled.
    3944
    4045The primary factor in making this decision is the cost of disabling and
     
    4550interrupt disable period in RTEMS.  So it is necessary to strike a balance
    4651when setting this parameter.
     52
    4753.. code-block:: c
    4854
     
    7076CPU_STRUCTURE_ALIGNMENT to force a structures to a 32 byte boundary.
    7177
    72 #define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
     78.. code-block:: c
     79
     80    #define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
    7381
    7482To benefit from using this, the data must be heavily used so it will stay
     
    8088ports which require no special alignment for optimized access to data
    8189structures:
     90
    8291.. code-block:: c
    8392
     
    98107is a basic C data type for this port which much be aligned to an 8 byte
    99108boundary.
     109
    100110.. code-block:: c
    101111
     
    117127when the required alignment for elements from the heap is the same as the
    118128basic CPU alignment requirements.
     129
    119130.. code-block:: c
    120131
     
    147158NOTE:  This does not have to be a power of 2.  It does have to be greater
    148159or equal to than CPU_ALIGNMENT.
    149 
    150 .. COMMENT: COPYRIGHT (c) 1988-2002.
    151 
    152 .. COMMENT: On-Line Applications Research Corporation (OAR).
    153 
    154 .. COMMENT: All rights reserved.
    155 
  • porting/cpu_init.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37CPU Initialization
     
    1721
    1822The _CPU_Initialize routine performs processor dependent initialization.
     23
    1924.. code-block:: c
    2025
    2126    void _CPU_Initialize(
    22     void            (*thread_dispatch)  /* may be ignored */
     27      void            (*thread_dispatch)  /* may be ignored */
    2328    )
    2429
     
    3338If you encounter this problem save the entry point in a CPU dependent
    3439variable as shown below:
     40
    3541.. code-block:: c
    3642
     
    4551to ensure that the state of the floating point unit is in a coherent,
    4652initialized state.
    47 
    48 .. COMMENT: COPYRIGHT (c) 1988-2002.
    49 
    50 .. COMMENT: On-Line Applications Research Corporation (OAR).
    51 
    52 .. COMMENT: All rights reserved.
    53 
  • porting/cpu_model_variations.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37CPU Model Variations
    48####################
    5 
    6 XXX enhance using portability presentation from CS595 class.  See
    7 general/portability.ppt.
    89
    910Since the text in the next section was written, RTEMS view of
     
    141142XXX deal with this as it applies to score/cpu.  Section name may
    142143be bad.
    143 
    144 .. COMMENT: COPYRIGHT (c) 1988-2002.
    145 
    146 .. COMMENT: On-Line Applications Research Corporation (OAR).
    147 
    148 .. COMMENT: All rights reserved.
    149 
  • porting/development_tools.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Development Tools
     
    1923The best advice that can be offered is to look at the existing RTEMS
    2024targets in the tool source and use that as a guideline.
    21 
    22 .. COMMENT: COPYRIGHT (c) 1988-2002.
    23 
    24 .. COMMENT: On-Line Applications Research Corporation (OAR).
    25 
    26 .. COMMENT: All rights reserved.
    27 
  • porting/idle_thread.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37IDLE Thread
     
    812
    913The setting of the macro CPU_IDLE_TASK_IS_FP is based on the answer to the
    10 question:  Should the IDLE task have a floating point context?  If the
    11 answer to this question is TRUE, then the IDLE task has a floating point
    12 context associated.  This is equivalent to creating a task in the Classic
    13 API (using rtems_task_create) as a RTEMS_FLOATING_POINT task.  If
     14question:  Should the IDLE task have a floating point context?
     15
     16If the answer to this question is TRUE, then the IDLE task has a floating
     17point context associated.  This is equivalent to creating a task in the
     18Classic API (using rtems_task_create) as a RTEMS_FLOATING_POINT task. If
    1419CPU_IDLE_TASK_IS_FP is set to TRUE, then a floating point context switch
    1520occurs when the IDLE task is switched in and out.  This adds to the
     
    2328
    2429The following illustrates how to set this macro:
     30
    2531.. code-block:: c
    2632
     
    5056The order of precedence for selecting the IDLE thread body is:
    5157
    52 # BSP provided
     58#. BSP provided
    5359
    54 # CPU dependent (if provided)
     60#. CPU dependent (if provided)
    5561
    56 # generic (if no BSP and no CPU dependent)
     62#. generic (if no BSP and no CPU dependent)
    5763
    5864The following illustrates setting the CPU_PROVIDES_IDLE_THREAD_BODY macro:
     65
    5966.. code-block:: c
    6067
     
    7279CPU_PROVIDES_IDLE_THREAD_BODY macro should be defined to TRUE.  This
    7380routine is prototyped as follows:
     81
    7482.. code-block:: c
    7583
     
    8189independent algorithm is used.  This algorithm consists of a "branch to
    8290self" which is implemented in a routine as follows.
     91
    8392.. code-block:: c
    8493
     
    92101in an infinite loop as the CPU will have to reexecute this instruction
    93102each time the IDLE thread is dispatched.
     103
    94104.. code-block:: c
    95105
     
    103113DMA if the CPU were put in IDLE mode.  This might also be a problem with
    104114other on-chip peripherals.  So use this hook with caution.
    105 
    106 .. COMMENT: COPYRIGHT (c) 1988-2002.
    107 
    108 .. COMMENT: On-Line Applications Research Corporation (OAR).
    109 
    110 .. COMMENT: All rights reserved.
    111 
  • porting/interrupts.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Interrupts
     
    2933family like the Intel i386 where the CPU itself only recognizes two
    3034interrupt levels - enabled and disabled.
     35
    3136.. code-block:: c
    3237
     
    3742
    3843The _CPU_ISR_Get_level function returns the current interrupt level.
     44
    3945.. code-block:: c
    4046
     
    5561
    5662The following is a dummy implementation of the _CPU_ISR_Set_level routine:
    57 .. code-block:: c
    58 
    59     #define _CPU_ISR_Set_level( new_level ) \\
    60     { \\
     63
     64.. code-block:: c
     65
     66    #define _CPU_ISR_Set_level( new_level ) \
     67    { \
    6168    }
    6269
    6370The following is the implementation from the Motorola M68K:
     71
    6472.. code-block:: c
    6573
     
    8593_CPU_ISR_Get_level and _CPU_ISR_Set_level routines. The following is a
    8694dummy implementation that simply sets the previous level to 0.
    87 .. code-block:: c
    88 
    89     #define _CPU_ISR_Disable( _isr_cookie ) \\
     95
     96.. code-block:: c
     97
     98    #define _CPU_ISR_Disable( _isr_cookie ) \
    9099    { \
    91100      (_isr_cookie) = 0;   /* do something to prevent warnings */ \
     
    93102
    94103The following is the implementation from the Motorola M68K port:
     104
    95105.. code-block:: c
    96106
     
    106116to.  The following illustrates a dummy implementation of the
    107117_CPU_ISR_Enable routine:
    108 .. code-block:: c
    109 
    110     #define _CPU_ISR_Enable( _isr_cookie )  \\
    111     { \\
     118
     119.. code-block:: c
     120
     121    #define _CPU_ISR_Enable( _isr_cookie )  \
     122    { \
    112123    }
    113124
    114125The following is the implementation from the Motorola M68K port:
     126
    115127.. code-block:: c
    116128
     
    127139
    128140The following is a dummy implementation of the _CPU_ISR_Flash routine:
    129 .. code-block:: c
    130 
    131     #define _CPU_ISR_Flash( _isr_cookie ) \\
    132     { \\
     141
     142.. code-block:: c
     143
     144    #define _CPU_ISR_Flash( _isr_cookie ) \
     145    { \
    133146    }
    134147
    135148The following is the implementation from the Motorola M68K port:
     149
    136150.. code-block:: c
    137151
     
    180194
    181195NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
     196
    182197.. code-block:: c
    183198
     
    185200
    186201If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in ``_ISR_Handler`` on the outermost interrupt.  The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack.  Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive.  Whether the stack  grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
     202
    187203.. code-block:: c
    188204
     
    201217
    202218NOTE:  It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STAC is TRUE.
     219
    203220.. code-block:: c
    204221
     
    212229
    213230The _CPU_ISR_install_raw_handler XXX
     231
    214232.. code-block:: c
    215233
     
    236254indicates the highest vector number which can be looked up in the table
    237255and mapped into a user provided handler.
     256
    238257.. code-block:: c
    239258
    240259    #define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
    241     #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \\
     260    #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \
    242261      (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
    243262
     
    252271old_handler - former ISR for this vector number
    253272new_handler - replacement ISR for this vector number
     273
    254274.. code-block:: c
    255275
     
    267287then we need to install the appropriate RTEMS interrupt handler for this
    268288vector number.
     289
    269290.. code-block:: c
    270291
     
    273294We put the actual user ISR address in _ISR_vector_table.  This will be
    274295used by the ``_ISR_Handler`` so the user gets control.
     296
    275297.. code-block:: c
    276298
     
    291313define the ``CPU_Interrupt_frame`` structure so that application code can
    292314examine the saved state.
     315
    293316.. code-block:: c
    294317
     
    302325
    303326The ``_ISR_Handler`` routine provides the RTEMS interrupt management.
     327
    304328.. code-block:: c
    305329
     
    334358which somehow place the vector number in a known place (which is safe if
    335359another interrupt nests this one) and branches to ``_ISR_Handler``.
     360
    336361.. code-block:: c
    337362
     
    373398Does the RTEMS invoke the user's ISR with the vector number and a pointer
    374399to the saved interrupt frame (1) or just the vector number (0)?
     400
    375401.. code-block:: c
    376402
     
    391417invoke that routine at the end of the interrupt sequence (if a dispatch is
    392418necessary).
     419
    393420.. code-block:: c
    394421
    395422    void (*_CPU_Thread_dispatch_pointer)();
    396423
    397 .. COMMENT: COPYRIGHT (c) 1988-2002.
    398 
    399 .. COMMENT: On-Line Applications Research Corporation (OAR).
    400 
    401 .. COMMENT: All rights reserved.
    402 
  • porting/miscellanous.rst

    r790fcab r7497f5e  
    1111a register, optionally disables interrupts, and halts/stops the CPU.  It
    1212is prototyped as follows and is often implemented as a macro:
     13
    1314.. code-block:: c
    1415
    1516    void _CPU_Fatal_halt(
    16     unsigned32 _error
     17      unsigned32 _error
    1718    );
    1819
     
    2425the CPU port.  These two functions are only used for this test and have no
    2526other purpose.
     27
    2628.. code-block:: c
    2729
     
    6870-------------------------------
    6971
    70 The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are
    71 set to specify the endian
    72 format used by this microprocessor.  These macros should not be set to the
    73 same value.  The following example illustrates how these macros should be
    74 set on a processor family that is big endian.
     72The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are set to specify
     73the endian format used by this microprocessor.  These macros should not
     74be set to the same value.  The following example illustrates how these
     75macros should be set on a processor family that is big endian.
     76
    7577.. code-block:: c
    7678
     
    8385system the MPCI Receive Server Thread must be able to process all
    8486directives.
     87
    8588.. code-block:: c
    8689
     
    109112work on any CPU.  It operates by breaking the unsigned thirty-two bit
    110113integer into four byte-wide quantities and reassemblying them.
     114
    111115.. code-block:: c
    112116
    113117    static inline unsigned int CPU_swap_u32(
    114     unsigned int value
     118      unsigned int value
    115119    )
    116120    {
    117     unsigned32 byte1, byte2, byte3, byte4, swapped;
    118     byte4 = (value >> 24) & 0xff;
    119     byte3 = (value >> 16) & 0xff;
    120     byte2 = (value >> 8)  & 0xff;
    121     byte1 =  value        & 0xff;
    122     swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
    123     return( swapped );
     121      unsigned32 byte1, byte2, byte3, byte4, swapped;
     122      byte4 = (value >> 24) & 0xff;
     123      byte3 = (value >> 16) & 0xff;
     124      byte2 = (value >> 8)  & 0xff;
     125      byte1 =  value        & 0xff;
     126      swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
     127      return( swapped );
    124128    }
    125129
     
    134138greatly improve the ``CPU_swap_u32`` routine.  The most common
    135139way to do this is to:
     140
    136141.. code-block:: c
    137142
     
    151156routine.  Just as with the ``CPU_swap_u32`` routine, the porter
    152157should provide a better implementation if possible.
     158
    153159.. code-block:: c
    154160
    155161    #define CPU_swap_u16( value ) \\
    156     (((value&0xff) << 8) | ((value >> 8)&0xff))
     162      (((value&0xff) << 8) | ((value >> 8)&0xff))
    157163
  • porting/preface.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37=======
     
    2933CPU family but since only a limited amount of assembly is required to port
    3034RTEMS.
    31 
    32 .. COMMENT: COPYRIGHT (c) 1988-2002.
    33 
    34 .. COMMENT: On-Line Applications Research Corporation (OAR).
    35 
    36 .. COMMENT: All rights reserved.
    37 
  • porting/priority_bitmap.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Priority Bitmap Manipulation
     
    2428routines is used to maintain and search the bit map array.
    2529
    26 When manipulating the bitmap array, RTEMS internally divides the
    27 8 bits of the task priority into "major" and "minor" components.
    28 The most significant 4 bits are the major component, while the least
    29 significant are the minor component.  The major component of a priority
    30 value is used to determine which 16-bit wide entry in the``_Priority_Bit_map`` array is associated with this priority.
    31 Each element in the ``_Priority_Bit_map`` array has a bit
    32 in the ``_Priority_Major_bit_map`` associated with it.
    33 That bit is cleared when all of the bits in a particular``_Priority_Bit_map`` array entry are zero.
     30When manipulating the bitmap array, RTEMS internally divides the 8 bits
     31of the task priority into "major" and "minor" components.  The most
     32significant 4 bits are the major component, while the least significant
     33are the minor component.  The major component of a priority value is
     34used to determine which 16-bit wide entry in the``_Priority_Bit_map``
     35array is associated with this priority.  Each element in the
     36``_Priority_Bit_map`` array has a bit in the ``_Priority_Major_bit_map``
     37associated with it.  That bit is cleared when all of the bits in a
     38particular``_Priority_Bit_map`` array entry are zero.
    3439
    3540The minor component of a priority is used to determine
     
    5560The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
    5661the first bit set in ``_value``.  ``_value`` is of CPU dependent type``Priority_bit_map_Control``.  A stub version of this routine is as follows:
     62
    5763.. code-block:: c
    5864
     
    6571instruction.
    6672
    67 # What happens when run on a value of zero?
     73#. What happens when run on a value of zero?
    6874
    69 # Bits may be numbered from MSB to LSB or vice-versa.
     75#. Bits may be numbered from MSB to LSB or vice-versa.
    7076
    71 # The numbering may be zero or one based.
     77#. The numbering may be zero or one based.
    7278
    73 # The "find first bit" instruction may search from MSB or LSB.
     79#. The "find first bit" instruction may search from MSB or LSB.
    7480
    7581RTEMS guarantees that (1) will never happen so it is not a concern.
     
    99105- a "binary search using if's"
    100106
    101 - the following algorithm based upon a 16 entry lookup table.  In this pseudo-code, bit_set_table[16] has values which indicate the first bit set:
     107- the following algorithm based upon a 16 entry lookup table.  In this
     108  pseudo-code, bit_set_table[16] has values which indicate the first
     109  bit set:
    102110
    103111  .. code-block:: c
     
    107115      _number = 8;
    108116      if _value > 0x0000f
    109       _value >=8
    110       _number += 4
    111       _number += bit_set_table[ _value ]
     117        _value >=8
     118        _number += 4
     119        _number += bit_set_table[ _value ]
    112120
    113121The following illustrates how the CPU_USE_GENERIC_BITFIELD_CODE macro may
     
    117125performance port.  This is perfectly acceptable during development and
    118126testing phases.
     127
    119128.. code-block:: c
    120129
     
    127136available on all models in the CPU family.  In this case, one might find
    128137something like this stub example did:
     138
    129139.. code-block:: c
    130140
    131141    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    132     #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
    133     { \
    134       (_output) = 0;   /* do something to prevent warnings */ \
    135     }
     142      #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
     143      { \
     144        (_output) = 0;   /* do something to prevent warnings */ \
     145      }
    136146    #endif
    137147
     
    145155The following is a typical implementation when the
    146156_CPU_Bitfield_Find_first_bit searches for the most significant bit set:
     157
    147158.. code-block:: c
    148159
    149160    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    150     #define _CPU_Priority_Mask( _bit_number ) \\
    151     ( 1 << (_bit_number) )
     161      #define _CPU_Priority_Mask( _bit_number ) \
     162        ( 1 << (_bit_number) )
    152163    #endif
    153164
     
    170181into a normalized form that is easier to process and use
    171182as an index.
     183
    172184.. code-block:: c
    173185
    174186    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
    175     #define _CPU_Priority_bits_index( _priority ) \\
    176     (_priority)
     187      #define _CPU_Priority_bits_index( _priority ) \
     188        (_priority)
    177189    #endif
    178 
    179 .. COMMENT: COPYRIGHT (c) 1988-2002.
    180 
    181 .. COMMENT: On-Line Applications Research Corporation (OAR).
    182 
    183 .. COMMENT: All rights reserved.
    184 
  • porting/source_code_org.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Source Code Organization
     
    1721
    1822XXX list the files and directories here
    19 
    20 .. COMMENT: COPYRIGHT (c) 1988-2002.
    21 
    22 .. COMMENT: On-Line Applications Research Corporation (OAR).
    23 
    24 .. COMMENT: All rights reserved.
    25 
  • porting/task_context.rst

    r790fcab r7497f5e  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Task Context Management
     
    2428
    2529The following illustrates how the CPU_STACK_GROWS_UP macro is set:
     30
    2631.. code-block:: c
    2732
     
    4651The following illustrates setting the minimum stack size to 4 kilobytes
    4752per task.
     53
    4854.. code-block:: c
    4955
     
    6167The following illustrates how the CPU_STACK_ALIGNMENT macro should be set
    6268when there are no special requirements:
     69
    6370.. code-block:: c
    6471
     
    8996Additionally, if the GNU debugger gdb is to be made aware of RTEMS tasks
    9097for this CPU, then care should be used in designing the context area.
     98
    9199.. code-block:: c
    92100
    93101    typedef struct {
    94     unsigned32 special_interrupt_register;
     102      unsigned32 special_interrupt_register;
    95103    } CPU_Interrupt_frame;
    96104
     
    119127of elements results in the simplest, most efficient implementation of XXX.
    120128A typical implementation starts with a definition such as the following:
     129
    121130.. code-block:: c
    122131
    123132    typedef struct {
    124     unsigned32 some_integer_register;
    125     unsigned32 another_integer_register;
    126     unsigned32 some_system_register;
     133      unsigned32 some_integer_register;
     134      unsigned32 another_integer_register;
     135      unsigned32 some_system_register;
    127136    } Context_Control;
    128137
     
    147156context.  The state of the "general data" registers is undefined at task
    148157start time. The _CPU_Context_initialize routine is prototyped as follows:
     158
    149159.. code-block:: c
    150160
     
    166176
    167177The ``_stack_base`` parameter is the base address of the memory area
    168 allocated for use as the task stack.  It is critical to understand that``_stack_base`` may not be the starting stack pointer for this task.
     178allocated for use as the task stack.  It is critical to understand that
     179``_stack_base`` may not be the starting stack pointer for this task.
    169180On CPU families where the stack grows from high addresses to lower ones,
    170181(i.e. ``CPU_STACK_GROWS_UP`` is FALSE) the starting stack point
    171 will be near the end of the stack memory area or close to``_stack_base`` + ``_size``.  Even on CPU families where the stack
    172 grows from low to higher addresses, there may be some required
    173 outermost stack frame that must be put at the address ``_stack_base``.
     182will be near the end of the stack memory area or close to ``_stack_base``
     183+ ``_size``.  Even on CPU families where the stack grows from low to
     184higher addresses, there may be some required outermost stack frame that
     185must be put at the address ``_stack_base``.
    174186
    175187The ``_size`` parameter is the requested size in bytes of the stack for
     
    184196The _CPU_Context_switch performs a normal non-FP context switch from the
    185197context of the current executing thread to the context of the heir thread.
     198
    186199.. code-block:: c
    187200
    188201    void _CPU_Context_switch(
    189     Context_Control  *run,
    190     Context_Control  *heir
     202      Context_Control  *run,
     203      Context_Control  *heir
    191204    );
    192205
    193 This routine begins by saving the current state of the
    194 CPU (i.e. the context) in the context area at ``run``.
    195 Then the routine should load the CPU context pointed to
    196 by ``heir``.  Loading the new context will cause a
    197 branch to its task code, so the task that invoked``_CPU_Context_switch`` will not run for a while.
    198 When, eventually, a context switch is made to load
    199 context from ``*run`` again, this task will resume
    200 and ``_CPU_Context_switch`` will return to its caller.
    201 
    202 Care should be exercise when writing this routine.  All
    203 registers assumed to be preserved across subroutine calls
    204 must be preserved.  These registers may be saved in
    205 the task's context area or on its stack.  However, the
    206 stack pointer and address to resume executing the task
    207 at must be included in the context (normally the subroutine
    208 return address to the caller of ``_Thread_Dispatch``.
    209 The decision of where to store the task's context is based
    210 on numerous factors including the capabilities of
    211 the CPU architecture itself and simplicity as well
    212 as external considerations such as debuggers wishing
    213 to examine a task's context.  In this case, it is
    214 often simpler to save all data in the context area.
    215 
    216 Also there may be special considerations
    217 when loading the stack pointers or interrupt level of the
    218 incoming task.  Independent of CPU specific considerations,
    219 if some context is saved on the task stack, then the porter
    220 must ensure that the stack pointer is adjusted *BEFORE*
    221 to make room for this context information before the
    222 information is written.  Otherwise, an interrupt could
    223 occur writing over the context data.  The following is
    224 an example of an *INCORRECT* sequence:
     206This routine begins by saving the current state of the CPU (i.e. the
     207context) in the context area at ``run``.  Then the routine should load the
     208CPU context pointed to by ``heir``.  Loading the new context will cause a
     209branch to its task code, so the task that invoked ``_CPU_Context_switch``
     210will not run for a while.  When, eventually, a context switch is
     211made to load context from ``*run`` again, this task will resume and
     212``_CPU_Context_switch`` will return to its caller.
     213
     214Care should be exercise when writing this routine.  All registers
     215assumed to be preserved across subroutine calls must be preserved.
     216These registers may be saved in the task's context area or on its stack.
     217However, the stack pointer and address to resume executing the task at
     218must be included in the context (normally the subroutine return address to
     219the caller of ``_Thread_Dispatch``.  The decision of where to store the
     220task's context is based on numerous factors including the capabilities
     221of the CPU architecture itself and simplicity as well as external
     222considerations such as debuggers wishing to examine a task's context.
     223In this case, it is often simpler to save all data in the context area.
     224
     225Also there may be special considerations when loading the stack pointers
     226or interrupt level of the incoming task.  Independent of CPU specific
     227considerations, if some context is saved on the task stack, then the
     228porter must ensure that the stack pointer is adjusted *BEFORE* to make
     229room for this context information before the information is written.
     230Otherwise, an interrupt could occur writing over the context data.
     231The following is an example of an *INCORRECT* sequence:
     232
    225233.. code-block:: c
    226234
     
    237245ports, it can simply be a label in _CPU_Context_switch. It may be
    238246unnecessary to reload some registers.
     247
    239248.. code-block:: c
    240249
     
    256265The following is an implementation of _CPU_Context_Restart_self that can
    257266be used when no special handling is required for this case.
     267
    258268.. code-block:: c
    259269
     
    283293The following example illustrates how the CPU_HARDWARE_FP (XXX macro name
    284294is varying) macro is set based on the CPU family dependent macro.
     295
    285296.. code-block:: c
    286297
     
    334345the PowerPC.  On this CPU family, this macro is set to TRUE if the CPU
    335346model has hardware floating point.
     347
    336348.. code-block:: c
    337349
    338350    #if (CPU_HARDWARE_FP == TRUE)
    339     #define CPU_ALL_TASKS_ARE_FP     TRUE
     351      #define CPU_ALL_TASKS_ARE_FP     TRUE
    340352    #else
    341     #define CPU_ALL_TASKS_ARE_FP     FALSE
     353      #define CPU_ALL_TASKS_ARE_FP     FALSE
    342354    #endif
    343355
     
    383395a processor family such as the M68K or i386 which can use deferred
    384396floating point context switches.
     397
    385398.. code-block:: c
    386399
     
    405418information for RTEMS, it is probably not enough for a debugger such as
    406419gdb.  But that is another problem.
     420
    407421.. code-block:: c
    408422
    409423    typedef struct {
    410     double      some_float_register;
     424      double      some_float_register;
    411425    } Context_Control_fp;
    412426
     
    424438operation and define the Context_Control_fp structure to be an area of
    425439bytes of the required size in this case.
     440
    426441.. code-block:: c
    427442
     
    437452use this implementation since the floating point context is saved as a
    438453sequence of store operations.
     454
    439455.. code-block:: c
    440456
     
    467483point context passed to it.  The following example implementation shows
    468484how to accomplish this:
     485
    469486.. code-block:: c
    470487
    471488    #define _CPU_Context_Initialize_fp( _destination ) \
    472489    { \
    473       *((Context_Control_fp *) *((void **) _destination)) = \\
    474         _CPU_Null_fp_context; \\
     490      *((Context_Control_fp *) *((void **) _destination)) = \
     491        _CPU_Null_fp_context; \
    475492    }
    476493
    477494The _CPU_Null_fp_context is optional.  A port need only include this variable when it uses the above mechanism to initialize a floating point context.  This is typically done on CPUs where it is difficult to generate an "uninitialized" FP context.  If the port requires this variable, then it is declared as follows:
     495
    478496.. code-block:: c
    479497
     
    484502
    485503The _CPU_Context_save_fp_context routine is responsible for saving the FP
    486 context at *fp_context_ptr.  If the point to load the FP context from is
     504context at ``*fp_context_ptr``.  If the point to load the FP context from is
    487505changed then the pointer is modified by this routine.
    488506
    489507Sometimes a macro implementation of this is in cpu.h which dereferences
    490 the ** and a similarly named routine in this file is passed something like
    491 a (Context_Control_fp *).  The general rule on making this decision is to
     508the ``**`` and a similarly named routine in this file is passed something like
     509a ``(Context_Control_fp *)``.  The general rule on making this decision is to
    492510avoid writing assembly language.
     511
    493512.. code-block:: c
    494513
     
    501520
    502521The _CPU_Context_restore_fp_context is responsible for restoring the FP
    503 context at *fp_context_ptr.  If the point to load the FP context from is
     522context at ``*fp_context_ptr``.  If the point to load the FP context from is
    504523changed then the pointer is modified by this routine.
    505524
    506525Sometimes a macro implementation of this is in cpu.h which dereferences
    507 the ** and a similarly named routine in this file is passed something like
    508 a (Context_Control_fp *).  The general rule on making this decision is to
     526the ``**`` and a similarly named routine in this file is passed something like
     527a ``(Context_Control_fp *)``.  The general rule on making this decision is to
    509528avoid writing assembly language.
     529
    510530.. code-block:: c
    511531
    512532    void _CPU_Context_restore_fp(
    513     void **fp_context_ptr
     533      void **fp_context_ptr
    514534    );
    515 
    516 .. COMMENT: COPYRIGHT (c) 1988-2002.
    517 
    518 .. COMMENT: On-Line Applications Research Corporation (OAR).
    519 
    520 .. COMMENT: All rights reserved.
    521 
Note: See TracChangeset for help on using the changeset viewer.