Changeset f233256 in rtems-docs


Ignore:
Timestamp:
Oct 6, 2016, 10:13:16 PM (3 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
be428d1
Parents:
e6fe68d
Message:

Clean up the CPU Supplement.

Location:
cpu_supplement
Files:
19 edited

Legend:

Unmodified
Added
Removed
  • cpu_supplement/altera_nios_ii.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 2014 Hesham ALMatary <heshamelmatary@gmail.com>
     4.. COMMENT: All rights reserved.
    25
    36Altera Nios II Specific Information
     
    1316
    1417Thread-local storage is not implemented.
    15 
    16 .. COMMENT: COPYRIGHT (c) 2014 Hesham ALMatary <heshamelmatary@gmail.com>
    17 
    18 .. COMMENT: All rights reserved.
    19 
  • cpu_supplement/arm.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2009.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37ARM Specific Information
    48########################
    59
    6 This chapter discusses the`ARM architecture <http://en.wikipedia.org/wiki/ARM_architecture>`_
    7 dependencies in this port of RTEMS.  The ARMv4T (and compatible), ARMv7-A,
    8 ARMv7-R and ARMv7-M architecture versions are supported by RTEMS.  Processors
    9 with a MMU use a static configuration which is set up during system start.  SMP
    10 is supported.
     10This chapter discusses the *ARM architecture*
     11(http://en.wikipedia.org/wiki/ARM_architecture) dependencies in this port of
     12RTEMS.  The ARMv4T (and compatible), ARMv7-A, ARMv7-R and ARMv7-M architecture
     13versions are supported by RTEMS.  Processors with a MMU use a static
     14configuration which is set up during system start.  SMP is supported.
    1115
    1216**Architecture Documents**
    1317
    14 For information on the ARM architecture refer to the`ARM Infocenter <http://infocenter.arm.com>`_.
     18For information on the ARM architecture refer to the *ARM Infocenter*
     19(http://infocenter.arm.com/).
    1520
    1621CPU Model Dependent Features
    1722============================
    1823
    19 This section presents the set of features which vary
    20 across ARM implementations and are of importance to RTEMS.  The set of CPU
    21 model feature macros are defined in the file:file:`cpukit/score/cpu/arm/rtems/score/arm.h` based upon the particular CPU
    22 model flags specified on the compilation command line.
     24This section presents the set of features which vary across ARM implementations
     25and are of importance to RTEMS.  The set of CPU model feature macros are
     26defined in the file :file:`cpukit/score/cpu/arm/rtems/score/arm.h` based upon
     27the particular CPU model flags specified on the compilation command line.
    2328
    2429CPU Model Name
    2530--------------
    2631
    27 The macro ``CPU_MODEL_NAME`` is a string which designates
    28 the architectural level of this CPU model.  See in:file:`cpukit/score/cpu/arm/rtems/score/arm.h` for the values.
     32The macro ``CPU_MODEL_NAME`` is a string which designates the architectural
     33level of this CPU model.  See in :file:`cpukit/score/cpu/arm/rtems/score/arm.h`
     34for the values.
    2935
    3036Count Leading Zeroes Instruction
     
    5258The following multilibs are available:
    5359
    54 # ``.``: ARMv4T, ARM instruction set
     60#. ``.``: ARMv4T, ARM instruction set
    5561
    56 # ``thumb``: ARMv4T, Thumb-1 instruction set
     62#. ``thumb``: ARMv4T, Thumb-1 instruction set
    5763
    58 # ``thumb/armv6-m``: ARMv6M, subset of Thumb-2 instruction set
     64#. ``thumb/armv6-m``: ARMv6M, subset of Thumb-2 instruction set
    5965
    60 # ``thumb/armv7-a``: ARMv7-A, Thumb-2 instruction set
     66#. ``thumb/armv7-a``: ARMv7-A, Thumb-2 instruction set
    6167
    62 # ``thumb/armv7-a/neon/hard``: ARMv7-A, Thumb-2 instruction set with
    63   hard-float ABI Neon and VFP-D32 support
     68#. ``thumb/armv7-a/neon/hard``: ARMv7-A, Thumb-2 instruction set with
     69   hard-float ABI Neon and VFP-D32 support
    6470
    65 # ``thumb/armv7-r``: ARMv7-R, Thumb-2 instruction set
     71#. ``thumb/armv7-r``: ARMv7-R, Thumb-2 instruction set
    6672
    67 # ``thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Thumb-2 instruction set
    68   with hard-float ABI VFP-D16 support
     73#. ``thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Thumb-2 instruction set with
     74  hard-float ABI VFP-D16 support
    6975
    70 # ``thumb/armv7-m``: ARMv7-M, Thumb-2 instruction set with hardware
    71   integer division (SDIV/UDIV)
     76#. ``thumb/armv7-m``: ARMv7-M, Thumb-2 instruction set with hardware
     77   integer division (SDIV/UDIV)
    7278
    73 # ``thumb/armv7-m/fpv4-sp-d16``: ARMv7-M, Thumb-2 instruction set with
    74   hardware integer division (SDIV/UDIV) and hard-float ABI FPv4-SP support
     79#. ``thumb/armv7-m/fpv4-sp-d16``: ARMv7-M, Thumb-2 instruction set with
     80   hardware integer division (SDIV/UDIV) and hard-float ABI FPv4-SP support
    7581
    76 # ``eb/thumb/armv7-r``: ARMv7-R, Big-endian Thumb-2 instruction set
     82#. ``eb/thumb/armv7-r``: ARMv7-R, Big-endian Thumb-2 instruction set
    7783
    78 # ``eb/thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Big-endian Thumb-2
    79   instruction set with hard-float ABI VFP-D16 support
     84#. ``eb/thumb/armv7-r/vfpv3-d16/hard``: ARMv7-R, Big-endian Thumb-2 instruction
     85  set with hard-float ABI VFP-D16 support
    8086
    8187Multilib 1. and 2. support the standard ARM7TDMI and ARM926EJ-S targets.
     
    94100big-endian variants are available.
    95101
    96 Use for example the following GCC options
    97 .. code:: c
     102Use for example the following GCC options:
     103
     104.. code-block:: shell
    98105
    99106    -mthumb -march=armv7-a -mfpu=neon -mfloat-abi=hard -mtune=cortex-a9
     
    101108to build an application or BSP for the ARMv7-A architecture and tune the code
    102109for a Cortex-A9 processor.  It is important to select the options used for the
    103 multilibs. For example
    104 .. code:: c
     110multilibs. For example:
     111
     112.. code-block:: shell
    105113
    106114    -mthumb -mcpu=cortex-a9
     
    111119===================
    112120
    113 Please refer to the`Procedure Call Standard for the ARM Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf>`_.
     121Please refer to the *Procedure Call Standard for the ARM Architecture*
     122(http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf).
    114123
    115124Memory Model
     
    144153
    145154The ARMv7-M architecture has a completely different exception model.  Here
    146 interrupts are disabled with a write of 0x80 to the ``basepri_max``
    147 register.  This means that all exceptions and interrupts with a priority value
    148 of greater than or equal to 0x80 are disabled.  Thus exceptions and interrupts
    149 with a priority value of less than 0x80 are non-maskable with respect to the
    150 operating system and therefore must not use operating system services.  Several
    151 support libraries of chip vendors implicitly shift the priority value somehow
    152 before the value is written to the NVIC IPR register.  This can easily lead to
     155interrupts are disabled with a write of 0x80 to the ``basepri_max`` register.
     156This means that all exceptions and interrupts with a priority value of greater
     157than or equal to 0x80 are disabled.  Thus exceptions and interrupts with a
     158priority value of less than 0x80 are non-maskable with respect to the operating
     159system and therefore must not use operating system services.  Several support
     160libraries of chip vendors implicitly shift the priority value somehow before
     161the value is written to the NVIC IPR register.  This can easily lead to
    153162confusion.
    154163
     
    169178==============================
    170179
    171 The default fatal error handler for this architecture performs the
    172 following actions:
     180The default fatal error handler for this architecture performs the following
     181actions:
    173182
    174183- disables operating system supported interrupts (IRQ),
     
    188197
    189198Thread-local storage is supported.
    190 
    191 .. COMMENT: COPYRIGHT (c) 1988-2009.
    192 
    193 .. COMMENT: On-Line Applications Research Corporation (OAR).
    194 
    195 .. COMMENT: All rights reserved.
    196 
  • cpu_supplement/atmel_avr.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2006.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Atmel AVR Specific Information
    48##############################
    59
    6 This chapter discusses the AVR architecture dependencies in this
    7 port of RTEMS.
     10This chapter discusses the AVR architecture dependencies in this port of RTEMS.
    811
    912**Architecture Documents**
    1013
    11 For information on the AVR architecture, refer to the following
    12 documents available from Atmel.
     14For information on the AVR architecture, refer to the following documents
     15available from Atmel.
    1316
    1417TBD
     
    1922============================
    2023
    21 CPUs of the AVR 53X only differ in the peripherals and thus in the
    22 device drivers. This port does not yet support the 56X dual core variants.
     24CPUs of the AVR 53X only differ in the peripherals and thus in the device
     25drivers. This port does not yet support the 56X dual core variants.
    2326
    2427Count Leading Zeroes Instruction
    2528--------------------------------
    2629
    27 The AVR CPU has the XXX instruction which could be used to speed
    28 up the find first bit operation.  The use of this instruction should
    29 significantly speed up the scheduling associated with a thread blocking.
     30The AVR CPU has the XXX instruction which could be used to speed up the find
     31first bit operation.  The use of this instruction should significantly speed up
     32the scheduling associated with a thread blocking.
    3033
    3134Calling Conventions
     
    3538--------------------
    3639
    37 The AVR architecture supports a simple call and return mechanism.
    38 A subroutine is invoked via the call (``call``) instruction.
    39 This instruction saves the return address in the ``RETS`` register
    40 and transfers the execution to the given address.
     40The AVR architecture supports a simple call and return mechanism.  A subroutine
     41is invoked via the call (``call``) instruction.  This instruction saves the
     42return address in the ``RETS`` register and transfers the execution to the
     43given address.
    4144
    42 It is the called funcions responsability to use the link instruction
    43 to reserve space on the stack for the local variables.  Returning from
    44 a subroutine is done by using the RTS (``RTS``) instruction which
    45 loads the PC with the adress stored in RETS.
     45It is the called funcions responsability to use the link instruction to reserve
     46space on the stack for the local variables.  Returning from a subroutine is
     47done by using the RTS (``RTS``) instruction which loads the PC with the adress
     48stored in RETS.
    4649
    47 It is is important to note that the ``call`` instruction does not
    48 automatically save or restore any registers.  It is the responsibility
    49 of the high-level language compiler to define the register preservation
    50 and usage convention.
     50It is is important to note that the ``call`` instruction does not automatically
     51save or restore any registers.  It is the responsibility of the high-level
     52language compiler to define the register preservation and usage convention.
    5153
    5254Register Usage
    5355--------------
    5456
    55 A called function may clobber all registers, except RETS, R4-R7, P3-P5,
    56 FP and SP.  It may also modify the first 12 bytes in the caller's stack
    57 frame which is used as an argument area for the first three arguments
    58 (which are passed in R0...R3 but may be placed on the stack by the
    59 called function).
     57A called function may clobber all registers, except RETS, R4-R7, P3-P5, FP and
     58SP.  It may also modify the first 12 bytes in the caller's stack frame which is
     59used as an argument area for the first three arguments (which are passed in
     60R0...R3 but may be placed on the stack by the called function).
    6061
    6162Parameter Passing
    6263-----------------
    6364
    64 RTEMS assumes that the AVR GCC calling convention is followed.
    65 The first three parameters are stored in registers R0, R1, and R2.
    66 All other parameters are put pushed on the stack.  The result is returned
    67 through register R0.
     65RTEMS assumes that the AVR GCC calling convention is followed.  The first three
     66parameters are stored in registers R0, R1, and R2.  All other parameters are
     67put pushed on the stack.  The result is returned through register R0.
    6868
    6969Memory Model
    7070============
    7171
    72 The AVR family architecutre support a single unified 4 GB byte
    73 address space using 32-bit addresses. It maps all resources like internal
    74 and external memory and IO registers into separate sections of this
    75 common address space.
     72The AVR family architecutre support a single unified 4 GB byte address space
     73using 32-bit addresses. It maps all resources like internal and external memory
     74and IO registers into separate sections of this common address space.
    7675
    77 The AVR architcture supports some form of memory
    78 protection via its Memory Management Unit. Since the
    79 AVR port runs in supervisior mode this memory
     76The AVR architcture supports some form of memory protection via its Memory
     77Management Unit. Since the AVR port runs in supervisior mode this memory
    8078protection mechanisms are not used.
    8179
     
    8381====================
    8482
    85 Discussed in this chapter are the AVR's interrupt response and
    86 control mechanisms as they pertain to RTEMS.
     83Discussed in this chapter are the AVR's interrupt response and control
     84mechanisms as they pertain to RTEMS.
    8785
    8886Vectoring of an Interrupt Handler
     
    9492--------------------------------
    9593
    96 During interrupt disable critical sections, RTEMS disables interrupts to
    97 level N (N) before the execution of this section and restores them
    98 to the previous level upon completion of the section. RTEMS uses the
    99 instructions CLI and STI to enable and disable Interrupts. Emulation,
    100 Reset, NMI and Exception Interrupts are never disabled.
     94During interrupt disable critical sections, RTEMS disables interrupts to level
     95N (N) before the execution of this section and restores them to the previous
     96level upon completion of the section. RTEMS uses the instructions CLI and STI
     97to enable and disable Interrupts. Emulation, Reset, NMI and Exception
     98Interrupts are never disabled.
    10199
    102100Interrupt Stack
    103101---------------
    104102
    105 The AVR Architecture works with two different kind of stacks,
    106 User and Supervisor Stack. Since RTEMS and its Application run
    107 in supervisor mode, all interrupts will use the interrupted
    108 tasks stack for execution.
     103The AVR Architecture works with two different kind of stacks, User and
     104Supervisor Stack. Since RTEMS and its Application run in supervisor mode, all
     105interrupts will use the interrupted tasks stack for execution.
    109106
    110107Default Fatal Error Processing
     
    138135
    139136TBD
    140 
    141 .. COMMENT: COPYRIGHT (c) 1988-2006.
    142 
    143 .. COMMENT: On-Line Applications Research Corporation (OAR).
    144 
    145 .. COMMENT: All rights reserved.
    146 
  • cpu_supplement/blackfin.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: Copyright (c) 2015 University of York.
     4.. COMMENT: Hesham ALMatary <hmka501@york.ac.uk>
    25
    36Blackfin Specific Information
    47#############################
    58
    6 This chapter discusses the Blackfin architecture dependencies in this
    7 port of RTEMS.
     9This chapter discusses the Blackfin architecture dependencies in this port of
     10RTEMS.
    811
    912**Architecture Documents**
    1013
    11 For information on the Blackfin architecture, refer to the following
    12 documents available from Analog Devices.
     14For information on the Blackfin architecture, refer to the following documents
     15available from Analog Devices.
    1316
    1417TBD
    1518
    16 - *"ADSP-BF533 Blackfin Processor Hardware Reference."*:file:`http://www.analog.com/UploadedFiles/Associated_Docs/892485982bf533_hwr.pdf`
     19- *"ADSP-BF533 Blackfin Processor Hardware Reference."* http://www.analog.com/UploadedFiles/Associated_Docs/892485982bf533_hwr.pdf
    1720
    1821CPU Model Dependent Features
    1922============================
    2023
    21 CPUs of the Blackfin 53X only differ in the peripherals and thus in the
    22 device drivers. This port does not yet support the 56X dual core variants.
     24CPUs of the Blackfin 53X only differ in the peripherals and thus in the device
     25drivers. This port does not yet support the 56X dual core variants.
    2326
    2427Count Leading Zeroes Instruction
    2528--------------------------------
    2629
    27 The Blackfin CPU has the BITTST instruction which could be used to speed
    28 up the find first bit operation.  The use of this instruction should
    29 significantly speed up the scheduling associated with a thread blocking.
     30The Blackfin CPU has the BITTST instruction which could be used to speed up the
     31find first bit operation.  The use of this instruction should significantly
     32speed up the scheduling associated with a thread blocking.
    3033
    3134Calling Conventions
     
    3336
    3437This section is heavily based on content taken from the Blackfin uCLinux
    35 documentation wiki which is edited by Analog Devices and Arcturus
    36 Networks.  :file:`http://docs.blackfin.uclinux.org/`
     38documentation wiki which is edited by Analog Devices and Arcturus Networks.
     39http://docs.blackfin.uclinux.org/
    3740
    3841Processor Background
    3942--------------------
    4043
    41 The Blackfin architecture supports a simple call and return mechanism.
    42 A subroutine is invoked via the call (``call``) instruction.
    43 This instruction saves the return address in the ``RETS`` register
    44 and transfers the execution to the given address.
     44The Blackfin architecture supports a simple call and return mechanism.  A
     45subroutine is invoked via the call (``call``) instruction.  This instruction
     46saves the return address in the ``RETS`` register and transfers the execution
     47to the given address.
    4548
    46 It is the called funcions responsability to use the link instruction
    47 to reserve space on the stack for the local variables.  Returning from
    48 a subroutine is done by using the RTS (``RTS``) instruction which
    49 loads the PC with the adress stored in RETS.
     49It is the called funcions responsability to use the link instruction to reserve
     50space on the stack for the local variables.  Returning from a subroutine is
     51done by using the RTS (``RTS``) instruction which loads the PC with the adress
     52stored in RETS.
    5053
    51 It is is important to note that the ``call`` instruction does not
    52 automatically save or restore any registers.  It is the responsibility
    53 of the high-level language compiler to define the register preservation
    54 and usage convention.
     54It is is important to note that the ``call`` instruction does not automatically
     55save or restore any registers.  It is the responsibility of the high-level
     56language compiler to define the register preservation and usage convention.
    5557
    5658Register Usage
    5759--------------
    5860
    59 A called function may clobber all registers, except RETS, R4-R7, P3-P5,
    60 FP and SP.  It may also modify the first 12 bytes in the caller's stack
    61 frame which is used as an argument area for the first three arguments
    62 (which are passed in R0...R3 but may be placed on the stack by the
    63 called function).
     61A called function may clobber all registers, except RETS, R4-R7, P3-P5, FP and
     62SP.  It may also modify the first 12 bytes in the caller's stack frame which is
     63used as an argument area for the first three arguments (which are passed in
     64R0...R3 but may be placed on the stack by the called function).
    6465
    6566Parameter Passing
    6667-----------------
    6768
    68 RTEMS assumes that the Blackfin GCC calling convention is followed.
    69 The first three parameters are stored in registers R0, R1, and R2.
    70 All other parameters are put pushed on the stack.  The result is returned
    71 through register R0.
     69RTEMS assumes that the Blackfin GCC calling convention is followed.  The first
     70three parameters are stored in registers R0, R1, and R2.  All other parameters
     71are put pushed on the stack.  The result is returned through register R0.
    7272
    7373Memory Model
    7474============
    7575
    76 The Blackfin family architecutre support a single unified 4 GB byte
    77 address space using 32-bit addresses. It maps all resources like internal
    78 and external memory and IO registers into separate sections of this
    79 common address space.
     76The Blackfin family architecutre support a single unified 4 GB byte address
     77space using 32-bit addresses. It maps all resources like internal and external
     78memory and IO registers into separate sections of this common address space.
    8079
    81 The Blackfin architcture supports some form of memory
    82 protection via its Memory Management Unit. Since the
    83 Blackfin port runs in supervisior mode this memory
     80The Blackfin architcture supports some form of memory protection via its Memory
     81Management Unit. Since the Blackfin port runs in supervisior mode this memory
    8482protection mechanisms are not used.
    8583
     
    8785====================
    8886
    89 Discussed in this chapter are the Blackfin's interrupt response and
    90 control mechanisms as they pertain to RTEMS. The Blackfin architecture
    91 support 16 kinds of interrupts broken down into Core and general-purpose
    92 interrupts.
     87Discussed in this chapter are the Blackfin's interrupt response and control
     88mechanisms as they pertain to RTEMS. The Blackfin architecture support 16 kinds
     89of interrupts broken down into Core and general-purpose interrupts.
    9390
    9491Vectoring of an Interrupt Handler
    9592---------------------------------
    9693
    97 RTEMS maps levels 0 -15 directly to Blackfins event vectors EVT0 -
    98 EVT15. Since EVT0 - EVT6 are core events and it is suggested to use
    99 EVT15 and EVT15 for Software interrupts, 7 Interrupts (EVT7-EVT13)
    100 are left for periferical use.
     94RTEMS maps levels 0 -15 directly to Blackfins event vectors EVT0 - EVT15. Since
     95EVT0 - EVT6 are core events and it is suggested to use EVT15 and EVT15 for
     96Software interrupts, 7 Interrupts (EVT7-EVT13) are left for periferical use.
    10197
    102 When installing an RTEMS interrupt handler RTEMS installs a generic
    103 Interrupt Handler which saves some context and enables nested interrupt
    104 servicing and then vectors to the users interrupt handler.
     98When installing an RTEMS interrupt handler RTEMS installs a generic Interrupt
     99Handler which saves some context and enables nested interrupt servicing and
     100then vectors to the users interrupt handler.
    105101
    106102Disabling of Interrupts by RTEMS
    107103--------------------------------
    108104
    109 During interrupt disable critical sections, RTEMS disables interrupts to
    110 level four (4) before the execution of this section and restores them
    111 to the previous level upon completion of the section. RTEMS uses the
    112 instructions CLI and STI to enable and disable Interrupts. Emulation,
    113 Reset, NMI and Exception Interrupts are never disabled.
     105During interrupt disable critical sections, RTEMS disables interrupts to level
     106four (4) before the execution of this section and restores them to the previous
     107level upon completion of the section. RTEMS uses the instructions CLI and STI
     108to enable and disable Interrupts. Emulation, Reset, NMI and Exception
     109Interrupts are never disabled.
    114110
    115111Interrupt Stack
    116112---------------
    117113
    118 The Blackfin Architecture works with two different kind of stacks,
    119 User and Supervisor Stack. Since RTEMS and its Application run
    120 in supervisor mode, all interrupts will use the interrupted
    121 tasks stack for execution.
     114The Blackfin Architecture works with two different kind of stacks, User and
     115Supervisor Stack. Since RTEMS and its Application run in supervisor mode, all
     116interrupts will use the interrupted tasks stack for execution.
    122117
    123118Default Fatal Error Processing
     
    151146
    152147TBD
    153 
    154 .. COMMENT: Copyright (c) 2015 University of York.
    155 
    156 .. COMMENT: Hesham ALMatary <hmka501@york.ac.uk>
    157 
  • cpu_supplement/ephiphany.rst

    re6fe68d rf233256  
    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
    37Epiphany Specific Information
    48#############################
    59
    6 This chapter discusses the`Epiphany Architecture <http://adapteva.com/docs/epiphany_sdk_ref.pdf>`_
    7 dependencies in this port of RTEMS. Epiphany is a chip that can come with 16 and
    8 64 cores, each of which can run RTEMS separately or they can work together to
    9 run a SMP RTEMS application.
     10This chapter discusses the`Epiphany Architecture
     11http://adapteva.com/docs/epiphany_sdk_ref.pdf dependencies in this port of
     12RTEMS. Epiphany is a chip that can come with 16 and 64 cores, each of which can
     13run RTEMS separately or they can work together to run a SMP RTEMS application.
    1014
    1115**Architecture Documents**
    1216
    13 For information on the Epiphany architecture refer to the`Epiphany Architecture Reference <http://adapteva.com/docs/epiphany_arch_ref.pdf>`_.
     17For information on the Epiphany architecture refer to the *Epiphany
     18Architecture Reference* http://adapteva.com/docs/epiphany_arch_ref.pdf.
    1419
    1520Calling Conventions
    1621===================
    1722
    18 Please refer to the`Epiphany SDK <http://adapteva.com/docs/epiphany_sdk_ref.pdf>`_
    19 Appendix A: Application Binary Interface
     23Please refer to the *Epiphany SDK*
     24http://adapteva.com/docs/epiphany_sdk_ref.pdf Appendix A: Application Binary
     25Interface
    2026
    2127Floating Point Unit
     
    2733============
    2834
    29 A flat 32-bit memory model is supported, no caches. Each core has its own 32 KiB
    30 strictly ordered local memory along with an access to a shared 32 MiB external
    31 DRAM.
     35A flat 32-bit memory model is supported, no caches. Each core has its own 32
     36KiB strictly ordered local memory along with an access to a shared 32 MiB
     37external DRAM.
    3238
    3339Interrupt Processing
     
    6470---------------
    6571
    66 The Epiphany RTEMS port uses a dedicated software interrupt stack.
    67 The stack for interrupts is allocated during interrupt driver initialization.
    68 When an  interrupt is entered, the _ISR_Handler routine is responsible for
    69 switching from the interrupted task stack to RTEMS software interrupt stack.
     72The Epiphany RTEMS port uses a dedicated software interrupt stack.  The stack
     73for interrupts is allocated during interrupt driver initialization.  When an
     74interrupt is entered, the _ISR_Handler routine is responsible for switching
     75from the interrupted task stack to RTEMS software interrupt stack.
    7076
    7177Default Fatal Error Processing
    7278==============================
    7379
    74 The default fatal error handler for this architecture performs the
    75 following actions:
     80The default fatal error handler for this architecture performs the following
     81actions:
    7682
    7783- disables operating system supported interrupts (IRQ),
     
    8591
    8692SMP is not supported.
    87 
    88 .. COMMENT: COPYRIGHT (c) 1988-2002.
    89 
    90 .. COMMENT: On-Line Applications Research Corporation (OAR).
    91 
    92 .. COMMENT: All rights reserved.
    93 
  • cpu_supplement/index.rst

    re6fe68d rf233256  
    55=================================
    66
    7 COPYRIGHT (c) 1988 - 2015.
     7 | COPYRIGHT (c) 1988 - 2015.
     8 | On-Line Applications Research Corporation (OAR).
    89
    9 On-Line Applications Research Corporation (OAR).
     10The authors have used their best efforts in preparing this material.  These
     11efforts include the development, research, and testing of the theories and
     12programs to determine their effectiveness.  No warranty of any kind, expressed
     13or implied, with regard to the software or the material contained in this
     14document is provided.  No liability arising out of the application or use of
     15any product described in this document is assumed.  The authors reserve the
     16right to revise this material and to make changes from time to time in the
     17content hereof without obligation to notify anyone of such revision or changes.
    1018
    11 The authors have used their best efforts in preparing
    12 this material.  These efforts include the development, research,
    13 and testing of the theories and programs to determine their
    14 effectiveness.  No warranty of any kind, expressed or implied,
    15 with regard to the software or the material contained in this
    16 document is provided.  No liability arising out of the
    17 application or use of any product described in this document is
    18 assumed.  The authors reserve the right to revise this material
    19 and to make changes from time to time in the content hereof
    20 without obligation to notify anyone of such revision or changes.
     19The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
     20RTEMS, its related support components, or its documentation should be directed
     21to the Community Project hosted at http://www.rtems.org/.
    2122
    22 The RTEMS Project is hosted at http://www.rtems.org.  Any
    23 inquiries concerning RTEMS, its related support components, or its
    24 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
     23.. topic:: RTEMS Online Resources
    2524
    26 Any inquiries for commercial services including training, support, custom
    27 development, application development assistance should be directed tohttp://www.rtems.com.
    28 
    29 
    30 Table of Contents
    31 -----------------
    32 
    33 .. toctree::
    34 
    35         preface
    36 
     25  ================  =============================
     26  Home              https://www.rtems.org/
     27  Developers        https://devel.rtems.org/
     28  Documentation     https://docs.rtems.org/
     29  Bug Reporting     https://devel.rtems.org/query
     30  Mailing Lists     https://lists.rtems.org/
     31  Git Repositories  https://git.rtems.org/
     32  ================  =============================
    3733
    3834.. toctree::
     
    4036        :numbered:
    4137
     38        preface
    4239        port
    4340        arm
     
    5956        command
    6057
    61 
    6258*       :ref:`genindex`
    6359*       :ref:`search`
    64 
  • cpu_supplement/intel_amd_x86.rst

    re6fe68d rf233256  
    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.
     6.. COMMENT: Jukka Pietarinen <jukka.pietarinen@mrf.fi>, 2008,
     7.. COMMENT: Micro-Research Finland Oy
    28
    39Intel/AMD x86 Specific Information
    410##################################
    511
    6 This chapter discusses the Intel x86 architecture dependencies
    7 in this port of RTEMS.  This family has multiple implementations
    8 from multiple vendors and suffers more from having evolved rather
    9 than being designed for growth.
    10 
    11 For information on the i386 processor, refer to the
    12 following documents:
     12This chapter discusses the Intel x86 architecture dependencies in this port of
     13RTEMS.  This family has multiple implementations from multiple vendors and
     14suffers more from having evolved rather than being designed for growth.
     15
     16For information on the i386 processor, refer to the following documents:
    1317
    1418- *386 Programmer's Reference Manual, Intel, Order No.  230985-002*.
     
    2428============================
    2529
    26 This section presents the set of features which vary
    27 across i386 implementations and are of importance to RTEMS.
    28 The set of CPU model feature macros are defined in the file``cpukit/score/cpu/i386/i386.h`` based upon the particular CPU
    29 model specified on the compilation command line.
     30This section presents the set of features which vary across i386
     31implementations and are of importance to RTEMS.  The set of CPU model feature
     32macros are defined in the :file:`cpukit/score/cpu/i386/i386.h` based upon the
     33particular CPU model specified on the compilation command line.
    3034
    3135bswap Instruction
    3236-----------------
    3337
    34 The macro ``I386_HAS_BSWAP`` is set to 1 to indicate that
    35 this CPU model has the ``bswap`` instruction which
    36 endian swaps a thirty-two bit quantity.  This instruction
    37 appears to be present in all CPU models
    38 i486's and above.
     38The macro ``I386_HAS_BSWAP`` is set to 1 to indicate that this CPU model has
     39the ``bswap`` instruction which endian swaps a thirty-two bit quantity.  This
     40instruction appears to be present in all CPU models i486's and above.
    3941
    4042Calling Conventions
     
    4446--------------------
    4547
    46 The i386 architecture supports a simple yet effective
    47 call and return mechanism.  A subroutine is invoked via the call
    48 (``call``) instruction.  This instruction pushes the return address
    49 on the stack.  The return from subroutine (``ret``) instruction pops
    50 the return address off the current stack and transfers control
    51 to that instruction.  It is is important to note that the i386
    52 call and return mechanism does not automatically save or restore
    53 any registers.  It is the responsibility of the high-level
    54 language compiler to define the register preservation and usage
    55 convention.
     48The i386 architecture supports a simple yet effective call and return
     49mechanism.  A subroutine is invoked via the call (``call``) instruction.  This
     50instruction pushes the return address on the stack.  The return from subroutine
     51(``ret``) instruction pops the return address off the current stack and
     52transfers control to that instruction.  It is is important to note that the
     53i386 call and return mechanism does not automatically save or restore any
     54registers.  It is the responsibility of the high-level language compiler to
     55define the register preservation and usage convention.
    5656
    5757Calling Mechanism
    5858-----------------
    5959
    60 All RTEMS directives are invoked using a call instruction and return to
    61 the user application via the ret instruction.
     60All RTEMS directives are invoked using a call instruction and return to the
     61user application via the ret instruction.
    6262
    6363Register Usage
    6464--------------
    6565
    66 As discussed above, the call instruction does not automatically save
    67 any registers.  RTEMS uses the registers EAX, ECX, and EDX as scratch
    68 registers.  These registers are not preserved by RTEMS directives
    69 therefore, the contents of these registers should not be assumed upon
    70 return from any RTEMS directive.
     66As discussed above, the call instruction does not automatically save any
     67registers.  RTEMS uses the registers EAX, ECX, and EDX as scratch registers.
     68These registers are not preserved by RTEMS directives therefore, the contents
     69of these registers should not be assumed upon return from any RTEMS directive.
    7170
    7271Parameter Passing
    7372-----------------
    7473
    75 RTEMS assumes that arguments are placed on the
    76 current stack before the directive is invoked via the call
    77 instruction.  The first argument is assumed to be closest to the
    78 return address on the stack.  This means that the first argument
    79 of the C calling sequence is pushed last.  The following
    80 pseudo-code illustrates the typical sequence used to call a
    81 RTEMS directive with three (3) arguments:
    82 .. code:: c
     74RTEMS assumes that arguments are placed on the current stack before the
     75directive is invoked via the call instruction.  The first argument is assumed
     76to be closest to the return address on the stack.  This means that the first
     77argument of the C calling sequence is pushed last.  The following pseudo-code
     78illustrates the typical sequence used to call a RTEMS directive with three (3)
     79arguments:
     80
     81.. code-block:: c
    8382
    8483    push third argument
     
    8887    remove arguments from the stack
    8988
    90 The arguments to RTEMS are typically pushed onto the
    91 stack using a push instruction.  These arguments must be removed
    92 from the stack after control is returned to the caller.  This
    93 removal is typically accomplished by adding the size of the
    94 argument list in bytes to the stack pointer.
     89The arguments to RTEMS are typically pushed onto the stack using a push
     90instruction.  These arguments must be removed from the stack after control is
     91returned to the caller.  This removal is typically accomplished by adding the
     92size of the argument list in bytes to the stack pointer.
    9593
    9694Memory Model
     
    10098-----------------
    10199
    102 RTEMS supports the i386 protected mode, flat memory
    103 model with paging disabled.  In this mode, the i386
    104 automatically converts every address from a logical to a
    105 physical address each time it is used.  The i386 uses
    106 information provided in the segment registers and the Global
    107 Descriptor Table to convert these addresses.  RTEMS assumes the
    108 existence of the following segments:
    109 
    110 - a single code segment at protection level (0) which
    111   contains all application and executive code.
    112 
    113 - a single data segment at protection level zero (0) which
    114   contains all application and executive data.
    115 
    116 The i386 segment registers and associated selectors
    117 must be initialized when the initialize_executive directive is
    118 invoked.  RTEMS treats the segment registers as system registers
    119 and does not modify or context switch them.
    120 
    121 This i386 memory model supports a flat 32-bit address
    122 space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
    123 gigabytes).  Each address is represented by a 32-bit value and
    124 is byte addressable.  The address may be used to reference a
    125 single byte, half-word (2-bytes), or word (4 bytes).
     100RTEMS supports the i386 protected mode, flat memory model with paging disabled.
     101In this mode, the i386 automatically converts every address from a logical to a
     102physical address each time it is used.  The i386 uses information provided in
     103the segment registers and the Global Descriptor Table to convert these
     104addresses.  RTEMS assumes the existence of the following segments:
     105
     106- a single code segment at protection level (0) which contains all application
     107  and executive code.
     108
     109- a single data segment at protection level zero (0) which contains all
     110  application and executive data.
     111
     112The i386 segment registers and associated selectors must be initialized when
     113the initialize_executive directive is invoked.  RTEMS treats the segment
     114registers as system registers and does not modify or context switch them.
     115
     116This i386 memory model supports a flat 32-bit address space with addresses
     117ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is
     118represented by a 32-bit value and is byte addressable.  The address may be used
     119to reference a single byte, half-word (2-bytes), or word (4 bytes).
    126120
    127121Interrupt Processing
    128122====================
    129123
    130 Although RTEMS hides many of the processor
    131 dependent details of interrupt processing, it is important to
    132 understand how the RTEMS interrupt manager is mapped onto the
    133 processor's unique architecture. Discussed in this chapter are
    134 the the processor's response and control mechanisms as they
    135 pertain to RTEMS.
     124Although RTEMS hides many of the processor dependent details of interrupt
     125processing, it is important to understand how the RTEMS interrupt manager is
     126mapped onto the processor's unique architecture. Discussed in this chapter are
     127the the processor's response and control mechanisms as they pertain to RTEMS.
    136128
    137129Vectoring of Interrupt Handler
    138130------------------------------
    139131
    140 Although the i386 supports multiple privilege levels,
    141 RTEMS and all user software executes at privilege level 0.  This
    142 decision was made by the RTEMS designers to enhance
    143 compatibility with processors which do not provide sophisticated
    144 protection facilities like those of the i386.  This decision
    145 greatly simplifies the discussion of i386 processing, as one
    146 need only consider interrupts without privilege transitions.
    147 
    148 Upon receipt of an interrupt  the i386 automatically
    149 performs the following actions:
     132Although the i386 supports multiple privilege levels, RTEMS and all user
     133software executes at privilege level 0.  This decision was made by the RTEMS
     134designers to enhance compatibility with processors which do not provide
     135sophisticated protection facilities like those of the i386.  This decision
     136greatly simplifies the discussion of i386 processing, as one need only consider
     137interrupts without privilege transitions.
     138
     139Upon receipt of an interrupt the i386 automatically performs the following
     140actions:
    150141
    151142- pushes the EFLAGS register
     
    155146- vectors to the interrupt service routine (ISR).
    156147
    157 A nested interrupt is processed similarly by the
    158 i386.
     148A nested interrupt is processed similarly by the i386.
    159149
    160150Interrupt Stack Frame
    161151---------------------
    162152
    163 The structure of the Interrupt Stack Frame for the
    164 i386 which is placed on the interrupt stack by the processor in
    165 response to an interrupt is as follows:
     153The structure of the Interrupt Stack Frame for the i386 which is placed on the
     154interrupt stack by the processor in response to an interrupt is as follows:
    166155
    167156+----------------------+-------+
     
    177166----------------
    178167
    179 Although RTEMS supports 256 interrupt levels, the
    180 i386 only supports two - enabled and disabled.  Interrupts are
    181 enabled when the interrupt-enable flag (IF) in the extended
    182 flags (EFLAGS) is set.  Conversely, interrupt processing is
    183 inhibited when the IF is cleared.  During a non-maskable
    184 interrupt, all other interrupts, including other non-maskable
    185 ones, are inhibited.
     168Although RTEMS supports 256 interrupt levels, the i386 only supports two -
     169enabled and disabled.  Interrupts are enabled when the interrupt-enable flag
     170(IF) in the extended flags (EFLAGS) is set.  Conversely, interrupt processing
     171is inhibited when the IF is cleared.  During a non-maskable interrupt, all
     172other interrupts, including other non-maskable ones, are inhibited.
    186173
    187174RTEMS interrupt levels 0 and 1 such that level zero
    188 (0) indicates that interrupts are fully enabled and level one
    189 that interrupts are disabled.  All other RTEMS interrupt levels
    190 are undefined and their behavior is unpredictable.
     175(0) indicates that interrupts are fully enabled and level one that interrupts
     176are disabled.  All other RTEMS interrupt levels are undefined and their
     177behavior is unpredictable.
    191178
    192179Interrupt Stack
    193180---------------
    194181
    195 The i386 family does not support a dedicated hardware
    196 interrupt stack.  On this processor, RTEMS allocates and manages
    197 a dedicated interrupt stack.  As part of vectoring a non-nested
    198 interrupt service routine, RTEMS switches from the stack of the
    199 interrupted task to a dedicated interrupt stack.  When a
    200 non-nested interrupt returns, RTEMS switches back to the stack
    201 of the interrupted stack.  The current stack pointer is not
    202 altered by RTEMS on nested interrupt.
     182The i386 family does not support a dedicated hardware interrupt stack.  On this
     183processor, RTEMS allocates and manages a dedicated interrupt stack.  As part of
     184vectoring a non-nested interrupt service routine, RTEMS switches from the stack
     185of the interrupted task to a dedicated interrupt stack.  When a non-nested
     186interrupt returns, RTEMS switches back to the stack of the interrupted stack.
     187The current stack pointer is not altered by RTEMS on nested interrupt.
    203188
    204189Default Fatal Error Processing
     
    206191
    207192The default fatal error handler for this architecture disables processor
    208 interrupts, places the error code in EAX, and executes a HLT instruction
    209 to halt the processor.
     193interrupts, places the error code in EAX, and executes a HLT instruction to
     194halt the processor.
    210195
    211196Symmetric Multiprocessing
     
    225210------------
    226211
    227 An RTEMS based application is initiated when the i386 processor is reset.
    228 When the i386 is reset,
    229 
    230 - The EAX register is set to indicate the results of the processor's
    231   power-up self test.  If the self-test was not executed, the contents of
    232   this register are undefined.  Otherwise, a non-zero value indicates the
    233   processor is faulty and a zero value indicates a successful self-test.
    234 
    235 - The DX register holds a component identifier and revision level.  DH
    236   contains 3 to indicate an i386 component and DL contains a unique revision
    237   level indicator.
    238 
    239 - Control register zero (CR0) is set such that the processor is in real
    240   mode with paging disabled.  Other portions of CR0 are used to indicate the
     212An RTEMS based application is initiated when the i386 processor is reset.  When
     213the i386 is reset,
     214
     215- The EAX register is set to indicate the results of the processor's power-up
     216  self test.  If the self-test was not executed, the contents of this register
     217  are undefined.  Otherwise, a non-zero value indicates the processor is faulty
     218  and a zero value indicates a successful self-test.
     219
     220- The DX register holds a component identifier and revision level.  DH contains
     221  3 to indicate an i386 component and DL contains a unique revision level
     222  indicator.
     223
     224- Control register zero (CR0) is set such that the processor is in real mode
     225  with paging disabled.  Other portions of CR0 are used to indicate the
    241226  presence of a numeric coprocessor.
    242227
    243 - All bits in the extended flags register (EFLAG) which are not
    244   permanently set are cleared.  This inhibits all maskable interrupts.
    245 
    246 - The Interrupt Descriptor Register (IDTR) is set to point at address
    247   zero.
     228- All bits in the extended flags register (EFLAG) which are not permanently set
     229  are cleared.  This inhibits all maskable interrupts.
     230
     231- The Interrupt Descriptor Register (IDTR) is set to point at address zero.
    248232
    249233- All segment registers are set to zero.
    250234
    251 - The instruction pointer is set to 0x0000FFF0.  The first instruction
    252   executed after a reset is actually at 0xFFFFFFF0 because the i386 asserts
    253   the upper twelve address until the first intersegment (FAR) JMP or CALL
    254   instruction.  When a JMP or CALL is executed, the upper twelve address
    255   lines are lowered and the processor begins executing in the first megabyte
    256   of memory.
     235- The instruction pointer is set to 0x0000FFF0.  The first instruction executed
     236  after a reset is actually at 0xFFFFFFF0 because the i386 asserts the upper
     237  twelve address until the first intersegment (FAR) JMP or CALL instruction.
     238  When a JMP or CALL is executed, the upper twelve address lines are lowered
     239  and the processor begins executing in the first megabyte of memory.
    257240
    258241Typically, an intersegment JMP to the application's initialization code is
     
    262245------------------------
    263246
    264 This initialization code is responsible for initializing all data
    265 structures required by the i386 in protected mode and for actually entering
    266 protected mode.  The i386 must be placed in protected mode and the segment
    267 registers and associated selectors must be initialized before the
    268 initialize_executive directive is invoked.
    269 
    270 The initialization code is responsible for initializing the Global
    271 Descriptor Table such that the i386 is in the thirty-two bit flat memory
    272 model with paging disabled.  In this mode, the i386 automatically converts
    273 every address from a logical to a physical address each time it is used.
    274 For more information on the memory model used by RTEMS, please refer to the
    275 Memory Model chapter in this document.
    276 
    277 Since the processor is in real mode upon reset, the processor must be
    278 switched to protected mode before RTEMS can execute.  Before switching to
    279 protected mode, at least one descriptor table and two descriptors must be
    280 created.  Descriptors are needed for a code segment and a data segment. (
    281 This will give you the flat memory model.)  The stack can be placed in a
    282 normal read/write data segment, so no descriptor for the stack is needed.
    283 Before the GDT can be used, the base address and limit must be loaded into
    284 the GDTR register using an LGDT instruction.
    285 
    286 If the hardware allows an NMI to be generated, you need to create the IDT
    287 and a gate for the NMI interrupt handler.  Before the IDT can be used, the
    288 base address and limit for the idt must be loaded into the IDTR register
    289 using an LIDT instruction.
    290 
    291 Protected mode is entered by setting thye PE bit in the CR0 register.
    292 Either a LMSW or MOV CR0 instruction may be used to set this bit. Because
    293 the processor overlaps the interpretation of several instructions, it is
    294 necessary to discard the instructions from the read-ahead cache. A JMP
    295 instruction immediately after the LMSW changes the flow and empties the
    296 processor if intructions which have been pre-fetched and/or decoded.  At
    297 this point, the processor is in protected mode and begins to perform
    298 protected mode application initialization.
    299 
    300 If the application requires that the IDTR be some value besides zero, then
    301 it should set it to the required value at this point.  All tasks share the
    302 same i386 IDTR value.  Because interrupts are enabled automatically by
    303 RTEMS as part of the initialize_executive directive, the IDTR MUST be set
    304 properly before this directive is invoked to insure correct interrupt
    305 vectoring.  If processor caching is to be utilized, then it should be
    306 enabled during the reset application initialization code.  The reset code
    307 which is executed before the call to initialize_executive has the following
    308 requirements:
    309 
    310 For more information regarding the i386 data structures and their
    311 contents, refer to Intel's 386 Programmer's Reference Manual.
    312 
    313 .. COMMENT: COPYRIGHT (c) 1988-2002.
    314 
    315 .. COMMENT: On-Line Applications Research Corporation (OAR).
    316 
    317 .. COMMENT: All rights reserved.
    318 
    319 .. COMMENT: Jukka Pietarinen <jukka.pietarinen@mrf.fi>, 2008,
    320 
    321 .. COMMENT: Micro-Research Finland Oy
    322 
     247This initialization code is responsible for initializing all data structures
     248required by the i386 in protected mode and for actually entering protected
     249mode.  The i386 must be placed in protected mode and the segment registers and
     250associated selectors must be initialized before the initialize_executive
     251directive is invoked.
     252
     253The initialization code is responsible for initializing the Global Descriptor
     254Table such that the i386 is in the thirty-two bit flat memory model with paging
     255disabled.  In this mode, the i386 automatically converts every address from a
     256logical to a physical address each time it is used.  For more information on
     257the memory model used by RTEMS, please refer to the Memory Model chapter in
     258this document.
     259
     260Since the processor is in real mode upon reset, the processor must be switched
     261to protected mode before RTEMS can execute.  Before switching to protected
     262mode, at least one descriptor table and two descriptors must be created.
     263Descriptors are needed for a code segment and a data segment. ( This will give
     264you the flat memory model.)  The stack can be placed in a normal read/write
     265data segment, so no descriptor for the stack is needed.  Before the GDT can be
     266used, the base address and limit must be loaded into the GDTR register using an
     267LGDT instruction.
     268
     269If the hardware allows an NMI to be generated, you need to create the IDT and a
     270gate for the NMI interrupt handler.  Before the IDT can be used, the base
     271address and limit for the idt must be loaded into the IDTR register using an
     272LIDT instruction.
     273
     274Protected mode is entered by setting thye PE bit in the CR0 register.  Either a
     275LMSW or MOV CR0 instruction may be used to set this bit. Because the processor
     276overlaps the interpretation of several instructions, it is necessary to discard
     277the instructions from the read-ahead cache. A JMP instruction immediately after
     278the LMSW changes the flow and empties the processor if intructions which have
     279been pre-fetched and/or decoded.  At this point, the processor is in protected
     280mode and begins to perform protected mode application initialization.
     281
     282If the application requires that the IDTR be some value besides zero, then it
     283should set it to the required value at this point.  All tasks share the same
     284i386 IDTR value.  Because interrupts are enabled automatically by RTEMS as part
     285of the initialize_executive directive, the IDTR MUST be set properly before
     286this directive is invoked to insure correct interrupt vectoring.  If processor
     287caching is to be utilized, then it should be enabled during the reset
     288application initialization code.  The reset code which is executed before the
     289call to initialize_executive has the following requirements:
     290
     291For more information regarding the i386 data structures and their contents,
     292refer to Intel's 386 Programmer's Reference Manual.
  • cpu_supplement/lattice_micro32.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    24
    35Lattice Mico32 Specific Information
    46###################################
    57
    6 This chaper discusses the Lattice Mico32 architecture dependencies in
    7 this port of RTEMS. The Lattice Mico32 is a 32-bit Harvard, RISC
    8 architecture "soft" microprocessor, available for free with an open IP
    9 core licensing agreement. Although mainly targeted for Lattice FPGA
    10 devices the microprocessor can be implemented on other vendors' FPGAs,
    11 too.
     8This chaper discusses the Lattice Mico32 architecture dependencies in this port
     9of RTEMS. The Lattice Mico32 is a 32-bit Harvard, RISC architecture "soft"
     10microprocessor, available for free with an open IP core licensing
     11agreement. Although mainly targeted for Lattice FPGA devices the microprocessor
     12can be implemented on other vendors' FPGAs, too.
    1213
    1314**Architecture Documents**
    1415
    15 For information on the Lattice Mico32 architecture, refer to the
    16 following documents available from Lattice Semiconductor:file:`http://www.latticesemi.com/`.
    17 
    18 - *"LatticeMico32 Processor Reference Manual"*:file:`http://www.latticesemi.com/dynamic/view_document.cfm?document_id=20890`
     16For information on the Lattice Mico32 architecture, refer to the following
     17documents available from Lattice Semiconductor http://www.latticesemi.com/.
     18
     19- *"LatticeMico32 Processor Reference Manual"*
     20  http://www.latticesemi.com/dynamic/view_document.cfm?document_id=20890
    1921
    2022CPU Model Dependent Features
    2123============================
    2224
    23 The Lattice Mico32 architecture allows for different configurations of
    24 the processor. This port is based on the assumption that the following options are implemented:
     25The Lattice Mico32 architecture allows for different configurations of the
     26processor. This port is based on the assumption that the following options are
     27implemented:
    2528
    2629- hardware multiplier
     
    4144=====================
    4245
    43 This section gives a brief introduction to the register architecture
    44 of the Lattice Mico32 processor.
    45 
    46 The Lattice Mico32 is a RISC archictecture processor with a
    47 32-register file of 32-bit registers.
     46This section gives a brief introduction to the register architecture of the
     47Lattice Mico32 processor.
     48
     49The Lattice Mico32 is a RISC archictecture processor with a 32-register file of
     5032-bit registers.
    4851
    4952Register Name
     
    8386breakpoint address
    8487
    85 Note that on processor startup all register values are undefined
    86 including r0, thus r0 has to be initialized to zero.
     88Note that on processor startup all register values are undefined including r0,
     89thus r0 has to be initialized to zero.
    8790
    8891Calling Conventions
     
    9295-----------------
    9396
    94 A call instruction places the return address to register r29 and a
    95 return from subroutine (ret) is actually a branch to r29/ra.
     97A call instruction places the return address to register r29 and a return from
     98subroutine (ret) is actually a branch to r29/ra.
    9699
    97100Register Usage
    98101--------------
    99102
    100 A subroutine may freely use registers r1 to r10 which are *not*
    101 preserved across subroutine invocations.
     103A subroutine may freely use registers r1 to r10 which are *not* preserved
     104across subroutine invocations.
    102105
    103106Parameter Passing
    104107-----------------
    105108
    106 When calling a C function the first eight arguments are stored in
    107 registers r1 to r8. Registers r1 and r2 hold the return value.
     109When calling a C function the first eight arguments are stored in registers r1
     110to r8. Registers r1 and r2 hold the return value.
    108111
    109112Memory Model
    110113============
    111114
    112 The Lattice Mico32 processor supports a flat memory model with a 4
    113 Gbyte address space with 32-bit addresses.
     115The Lattice Mico32 processor supports a flat memory model with a 4 Gbyte
     116address space with 32-bit addresses.
    114117
    115118The following data types are supported:
    116119
    117 Type
    118 
    119 Bits
    120 
    121 C Compiler Type
    122 
    123 unsigned byte
    124 
    125 8
    126 
    127 unsigned char
    128 
    129 signed byte
    130 
    131 8
    132 
    133 char
    134 
    135 unsigned half-word
    136 
    137 16
    138 
    139 unsigned short
    140 
    141 signed half-word
    142 
    143 16
    144 
    145 short
    146 
    147 unsigned word
    148 
    149 32
    150 
    151 unsigned int / unsigned long
    152 
    153 signed word
    154 
    155 32
    156 
    157 int / long
    158 
    159 Data accesses need to be aligned, with unaligned accesses result are
    160 undefined.
     120================== ==== ======================
     121Type               Bits C Compiler Type
     122================== ==== ======================
     123unsigned byte      8    unsigned char
     124signed byte        8    char
     125unsigned half-word 16   unsigned short
     126signed half-word   16   short
     127unsigned word      32   unsigned int / unsigned long
     128signed word        32   int / long
     129================== ==== ======================
     130
     131Data accesses need to be aligned, with unaligned accesses result are undefined.
    161132
    162133Interrupt Processing
    163134====================
    164135
    165 The Lattice Mico32 has 32 interrupt lines which are however served by
    166 only one exception vector. When an interrupt occurs following happens:
     136The Lattice Mico32 has 32 interrupt lines which are however served by only one
     137exception vector. When an interrupt occurs following happens:
    167138
    168139- address of next instruction placed in r30/ea
    169140
    170 - IE field of IE CSR saved to EIE field and IE field cleared preventing further exceptions from occuring.
     141- IE field of IE CSR saved to EIE field and IE field cleared preventing further
     142  exceptions from occuring.
    171143
    172144- branch to interrupt exception address EBA CSR + 0xC0
    173145
    174 The interrupt exception handler determines from the state of the
    175 interrupt pending registers (IP CSR) and interrupt enable register (IE
    176 CSR) which interrupt to serve and jumps to the interrupt routine
    177 pointed to by the corresponding interrupt vector.
    178 
    179 For now there is no dedicated interrupt stack so every task in
    180 the system MUST have enough stack space to accommodate the worst
    181 case stack usage of that particular task and the interrupt
    182 service routines COMBINED.
     146The interrupt exception handler determines from the state of the interrupt
     147pending registers (IP CSR) and interrupt enable register (IE CSR) which
     148interrupt to serve and jumps to the interrupt routine pointed to by the
     149corresponding interrupt vector.
     150
     151For now there is no dedicated interrupt stack so every task in the system MUST
     152have enough stack space to accommodate the worst case stack usage of that
     153particular task and the interrupt service routines COMBINED.
    183154
    184155Nested interrupts are not supported.
     
    188159
    189160Upon detection of a fatal error by either the application or RTEMS during
    190 initialization the ``rtems_fatal_error_occurred`` directive supplied
    191 by the Fatal Error Manager is invoked.  The Fatal Error Manager will
    192 invoke the user-supplied fatal error handlers.  If no user-supplied
    193 handlers are configured or all of them return without taking action to
    194 shutdown the processor or reset, a default fatal error handler is invoked.
     161initialization the ``rtems_fatal_error_occurred`` directive supplied by the
     162Fatal Error Manager is invoked.  The Fatal Error Manager will invoke the
     163user-supplied fatal error handlers.  If no user-supplied handlers are
     164configured or all of them return without taking action to shutdown the
     165processor or reset, a default fatal error handler is invoked.
    195166
    196167Most of the action performed as part of processing the fatal error are
    197 described in detail in the Fatal Error Manager chapter in the User's
    198 Guide.  However, the if no user provided extension or BSP specific fatal
    199 error handler takes action, the final default action is to invoke a
    200 CPU architecture specific function.  Typically this function disables
    201 interrupts and halts the processor.
     168described in detail in the Fatal Error Manager chapter in the User's Guide.
     169However, the if no user provided extension or BSP specific fatal error handler
     170takes action, the final default action is to invoke a CPU architecture specific
     171function.  Typically this function disables interrupts and halts the processor.
    202172
    203173In each of the architecture specific chapters, this describes the precise
     
    217187======================
    218188
    219 An RTEMS Board Support Package (BSP) must be designed to support a
    220 particular processor model and target board combination.
    221 
    222 In each of the architecture specific chapters, this section will present
    223 a discussion of architecture specific BSP issues.   For more information
    224 on developing a BSP, refer to BSP and Device Driver Development Guide
    225 and the chapter titled Board Support Packages in the RTEMS
    226 Applications User's Guide.
     189An RTEMS Board Support Package (BSP) must be designed to support a particular
     190processor model and target board combination.
     191
     192In each of the architecture specific chapters, this section will present a
     193discussion of architecture specific BSP issues.  For more information on
     194developing a BSP, refer to BSP and Device Driver Development Guide and the
     195chapter titled Board Support Packages in the RTEMS Applications User's Guide.
    227196
    228197System Reset
    229198------------
    230199
    231 An RTEMS based application is initiated or re-initiated when the processor
    232 is reset.
    233 
    234 .. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    235 
     200An RTEMS based application is initiated or re-initiated when the processor is
     201reset.
  • cpu_supplement/m68xxx_and_coldfire.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    24
    35M68xxx and Coldfire Specific Information
    46########################################
    57
    6 This chapter discusses the Freescale (formerly Motorola) MC68xxx
    7 and Coldfire architectural dependencies.  The MC68xxx family has a
    8 wide variety of CPU models within it based upon different CPU core
    9 implementations.  Ignoring the Coldfire parts, the part numbers for
    10 these models are generally divided into MC680xx and MC683xx.  The MC680xx
    11 models are more general purpose processors with no integrated peripherals.
    12 The MC683xx models, on the other hand, are more specialized and have a
    13 variety of peripherals on chip including sophisticated timers and serial
    14 communications controllers.
     8This chapter discusses the Freescale (formerly Motorola) MC68xxx and Coldfire
     9architectural dependencies.  The MC68xxx family has a wide variety of CPU
     10models within it based upon different CPU core implementations.  Ignoring the
     11Coldfire parts, the part numbers for these models are generally divided into
     12MC680xx and MC683xx.  The MC680xx models are more general purpose processors
     13with no integrated peripherals.  The MC683xx models, on the other hand, are
     14more specialized and have a variety of peripherals on chip including
     15sophisticated timers and serial communications controllers.
    1516
    1617**Architecture Documents**
    1718
    18 For information on the MC68xxx and Coldfire architecture, refer to the following documents available from Freescale website (:file:`http//www.freescale.com/`):
     19For information on the MC68xxx and Coldfire architecture, refer to the
     20following documents available from Freescale website
     21(http//www.freescale.com/):
    1922
    2023- *M68000 Family Reference, Motorola, FR68K/D*.
     
    2831============================
    2932
    30 This section presents the set of features which vary
    31 across m68k/Coldfire implementations that are of importance to RTEMS.
    32 The set of CPU model feature macros are defined in the file``cpukit/score/cpu/m68k/m68k.h`` based upon the particular CPU
    33 model selected on the compilation command line.
     33This section presents the set of features which vary across m68k/Coldfire
     34implementations that are of importance to RTEMS.  The set of CPU model feature
     35macros are defined in the file :file:`cpukit/score/cpu/m68k/m68k.h` based upon
     36the particular CPU model selected on the compilation command line.
    3437
    3538BFFFO Instruction
    3639-----------------
    3740
    38 The macro ``M68K_HAS_BFFFO`` is set to 1 to indicate that
    39 this CPU model has the bfffo instruction.
     41The macro ``M68K_HAS_BFFFO`` is set to 1 to indicate that this CPU model has
     42the bfffo instruction.
    4043
    4144Vector Base Register
    4245--------------------
    4346
    44 The macro ``M68K_HAS_VBR`` is set to 1 to indicate that
    45 this CPU model has a vector base register (vbr).
     47The macro ``M68K_HAS_VBR`` is set to 1 to indicate that this CPU model has a
     48vector base register (vbr).
    4649
    4750Separate Stacks
    4851---------------
    4952
    50 The macro ``M68K_HAS_SEPARATE_STACKS`` is set to 1 to
    51 indicate that this CPU model has separate interrupt, user, and
    52 supervisor mode stacks.
     53The macro ``M68K_HAS_SEPARATE_STACKS`` is set to 1 to indicate that this CPU
     54model has separate interrupt, user, and supervisor mode stacks.
    5355
    5456Pre-Indexing Address Mode
    5557-------------------------
    5658
    57 The macro ``M68K_HAS_PREINDEXING`` is set to 1 to indicate that
    58 this CPU model has the pre-indexing address mode.
     59The macro ``M68K_HAS_PREINDEXING`` is set to 1 to indicate that this CPU model
     60has the pre-indexing address mode.
    5961
    6062Extend Byte to Long Instruction
    6163-------------------------------
    6264
    63 The macro ``M68K_HAS_EXTB_L`` is set to 1 to indicate that this CPU model
    64 has the extb.l instruction.  This instruction is supposed to be available
    65 in all models based on the cpu32 core as well as mc68020 and up models.
     65The macro ``M68K_HAS_EXTB_L`` is set to 1 to indicate that this CPU model has
     66the extb.l instruction.  This instruction is supposed to be available in all
     67models based on the cpu32 core as well as mc68020 and up models.
    6668
    6769Calling Conventions
    6870===================
    6971
    70 The MC68xxx architecture supports a simple yet effective call and
    71 return mechanism.  A subroutine is invoked via the branch to subroutine
    72 (``bsr``) or the jump to subroutine (``jsr``) instructions.
    73 These instructions push the return address on the current stack.
    74 The return from subroutine (``rts``) instruction pops the return
    75 address off the current stack and transfers control to that instruction.
    76 It is is important to note that the MC68xxx call and return mechanism does
    77 not automatically save or restore any registers.  It is the responsibility
    78 of the high-level language compiler to define the register preservation
    79 and usage convention.
     72The MC68xxx architecture supports a simple yet effective call and return
     73mechanism.  A subroutine is invoked via the branch to subroutine (``bsr``) or
     74the jump to subroutine (``jsr``) instructions.  These instructions push the
     75return address on the current stack.  The return from subroutine (``rts``)
     76instruction pops the return address off the current stack and transfers control
     77to that instruction.  It is is important to note that the MC68xxx call and
     78return mechanism does not automatically save or restore any registers.  It is
     79the responsibility of the high-level language compiler to define the register
     80preservation and usage convention.
    8081
    8182Calling Mechanism
    8283-----------------
    8384
    84 All RTEMS directives are invoked using either a ``bsr`` or ``jsr``
    85 instruction and return to the user application via the rts instruction.
     85All RTEMS directives are invoked using either a ``bsr`` or ``jsr`` instruction
     86and return to the user application via the rts instruction.
    8687
    8788Register Usage
    8889--------------
    8990
    90 As discussed above, the ``bsr`` and ``jsr`` instructions do not
    91 automatically save any registers.  RTEMS uses the registers D0, D1,
    92 A0, and A1 as scratch registers.  These registers are not preserved by
    93 RTEMS directives therefore, the contents of these registers should not
    94 be assumed upon return from any RTEMS directive.
     91As discussed above, the ``bsr`` and ``jsr`` instructions do not automatically
     92save any registers.  RTEMS uses the registers D0, D1, A0, and A1 as scratch
     93registers.  These registers are not preserved by RTEMS directives therefore,
     94the contents of these registers should not be assumed upon return from any
     95RTEMS directive.
    9596
    9697Parameter Passing
    9798-----------------
    9899
    99 RTEMS assumes that arguments are placed on the current stack before
    100 the directive is invoked via the bsr or jsr instruction.  The first
    101 argument is assumed to be closest to the return address on the stack.
    102 This means that the first argument of the C calling sequence is pushed
    103 last.  The following pseudo-code illustrates the typical sequence used
    104 to call a RTEMS directive with three (3) arguments:
    105 .. code:: c
     100RTEMS assumes that arguments are placed on the current stack before the
     101directive is invoked via the bsr or jsr instruction.  The first argument is
     102assumed to be closest to the return address on the stack.  This means that the
     103first argument of the C calling sequence is pushed last.  The following
     104pseudo-code illustrates the typical sequence used to call a RTEMS directive
     105with three (3) arguments:
     106
     107.. code-block:: c
    106108
    107109    push third argument
     
    112114
    113115The arguments to RTEMS are typically pushed onto the stack using a move
    114 instruction with a pre-decremented stack pointer as the destination.
    115 These arguments must be removed from the stack after control is returned
    116 to the caller.  This removal is typically accomplished by adding the
    117 size of the argument list in bytes to the current stack pointer.
     116instruction with a pre-decremented stack pointer as the destination.  These
     117arguments must be removed from the stack after control is returned to the
     118caller.  This removal is typically accomplished by adding the size of the
     119argument list in bytes to the current stack pointer.
    118120
    119121Memory Model
    120122============
    121123
    122 The MC68xxx family supports a flat 32-bit address
    123 space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
    124 gigabytes).  Each address is represented by a 32-bit value and
    125 is byte addressable.  The address may be used to reference a
    126 single byte, word (2-bytes), or long word (4 bytes).  Memory
    127 accesses within this address space are performed in big endian
    128 fashion by the processors in this family.
    129 
    130 Some of the MC68xxx family members such as the
    131 MC68020, MC68030, and MC68040 support virtual memory and
    132 segmentation.  The MC68020 requires external hardware support
    133 such as the MC68851 Paged Memory Management Unit coprocessor
    134 which is typically used to perform address translations for
    135 these systems.  RTEMS does not support virtual memory or
    136 segmentation on any of the MC68xxx family members.
     124The MC68xxx family supports a flat 32-bit address space with addresses ranging
     125from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is represented by a
     12632-bit value and is byte addressable.  The address may be used to reference a
     127single byte, word (2-bytes), or long word (4 bytes).  Memory accesses within
     128this address space are performed in big endian fashion by the processors in
     129this family.
     130
     131Some of the MC68xxx family members such as the MC68020, MC68030, and MC68040
     132support virtual memory and segmentation.  The MC68020 requires external
     133hardware support such as the MC68851 Paged Memory Management Unit coprocessor
     134which is typically used to perform address translations for these systems.
     135RTEMS does not support virtual memory or segmentation on any of the MC68xxx
     136family members.
    137137
    138138Interrupt Processing
    139139====================
    140140
    141 Discussed in this section are the MC68xxx's interrupt response and
    142 control mechanisms as they pertain to RTEMS.
     141Discussed in this section are the MC68xxx's interrupt response and control
     142mechanisms as they pertain to RTEMS.
    143143
    144144Vectoring of an Interrupt Handler
    145145---------------------------------
    146146
    147 Depending on whether or not the particular CPU supports a separate
    148 interrupt stack, the MC68xxx family has two different interrupt handling
    149 models.
     147Depending on whether or not the particular CPU supports a separate interrupt
     148stack, the MC68xxx family has two different interrupt handling models.
    150149
    151150Models Without Separate Interrupt Stacks
     
    153152
    154153Upon receipt of an interrupt the MC68xxx family members without separate
    155 interrupt stacks automatically perform the following actions:
    156 
    157 - To Be Written
     154interrupt stacks automatically use software to switch stacks.
    158155
    159156Models With Separate Interrupt Stacks
    160157~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    161158
    162 Upon receipt of an interrupt the MC68xxx family members with separate
    163 interrupt stacks automatically perform the following actions:
     159Upon receipt of an interrupt the MC68xxx family members with separate interrupt
     160stacks automatically perform the following actions:
    164161
    165162- saves the current status register (SR),
    166163
    167 - clears the master/interrupt (M) bit of the SR to
    168   indicate the switch from master state to interrupt state,
     164- clears the master/interrupt (M) bit of the SR to indicate the switch from
     165  master state to interrupt state,
    169166
    170167- sets the privilege mode to supervisor,
     
    172169- suppresses tracing,
    173170
    174 - sets the interrupt mask level equal to the level of the
    175   interrupt being serviced,
    176 
    177 - pushes an interrupt stack frame (ISF), which includes
    178   the program counter (PC), the status register (SR), and the
    179   format/exception vector offset (FVO) word, onto the supervisor
    180   and interrupt stacks,
    181 
    182 - switches the current stack to the interrupt stack and
    183   vectors to an interrupt service routine (ISR).  If the ISR was
    184   installed with the interrupt_catch directive, then the RTEMS
    185   interrupt handler will begin execution.  The RTEMS interrupt
    186   handler saves all registers which are not preserved according to
     171- sets the interrupt mask level equal to the level of the interrupt being
     172  serviced,
     173
     174- pushes an interrupt stack frame (ISF), which includes the program counter
     175  (PC), the status register (SR), and the format/exception vector offset (FVO)
     176  word, onto the supervisor and interrupt stacks,
     177
     178- switches the current stack to the interrupt stack and vectors to an interrupt
     179  service routine (ISR).  If the ISR was installed with the interrupt_catch
     180  directive, then the RTEMS interrupt handler will begin execution.  The RTEMS
     181  interrupt handler saves all registers which are not preserved according to
    187182  the calling conventions and invokes the application's ISR.
    188183
    189 A nested interrupt is processed similarly by these
    190 CPU models with the exception that only a single ISF is placed
    191 on the interrupt stack and the current stack need not be
    192 switched.
    193 
    194 The FVO word in the Interrupt Stack Frame is examined
    195 by RTEMS to determine when an outer most interrupt is being
    196 exited. Since the FVO is used by RTEMS for this purpose, the
    197 user application code MUST NOT modify this field.
    198 
    199 The following shows the Interrupt Stack Frame for
    200 MC68xxx CPU models with separate interrupt stacks:
     184A nested interrupt is processed similarly by these CPU models with the
     185exception that only a single ISF is placed on the interrupt stack and the
     186current stack need not be switched.
     187
     188The FVO word in the Interrupt Stack Frame is examined by RTEMS to determine
     189when an outer most interrupt is being exited. Since the FVO is used by RTEMS
     190for this purpose, the user application code MUST NOT modify this field.
     191
     192The following shows the Interrupt Stack Frame for MC68xxx CPU models with
     193separate interrupt stacks:
    201194
    202195+----------------------+-----+
     
    214207-----------------------------------
    215208
    216 This is from a post by Zoltan Kocsi <zoltan@bendor.com.au> and is
    217 a nice trick in certain situations.  In his words:
    218 
    219 I think somebody on this list asked about the interupt vector handling
    220 w/o VBR and RAM at 0.  The usual trick is to initialise the vector table
    221 (except the first 2 two entries, of course) to point to the same location
    222 BUT you also add the vector number times 0x1000000 to them. That is,
    223 bits 31-24 contain the vector number and 23-0 the address of the common
    224 handler.  Since the PC is 32 bit wide but the actual address bus is only
    225 24, the top byte will be in the PC but will be ignored when jumping onto
    226 your routine.
    227 
    228 Then your common interrupt routine gets this info by loading the PC
    229 into some register and based on that info, you can jump to a vector in
    230 a vector table pointed by a virtual VBR:
    231 .. code:: c
     209This is from a post by Zoltan Kocsi <zoltan@bendor.com.au> and is a nice trick
     210in certain situations.  In his words:
     211
     212I think somebody on this list asked about the interupt vector handling w/o VBR
     213and RAM at 0.  The usual trick is to initialise the vector table (except the
     214first 2 two entries, of course) to point to the same location BUT you also add
     215the vector number times 0x1000000 to them. That is, bits 31-24 contain the
     216vector number and 23-0 the address of the common handler.  Since the PC is 32
     217bit wide but the actual address bus is only 24, the top byte will be in the PC
     218but will be ignored when jumping onto your routine.
     219
     220Then your common interrupt routine gets this info by loading the PC into some
     221register and based on that info, you can jump to a vector in a vector table
     222pointed by a virtual VBR:
     223
     224.. code-block:: c
    232225
    233226    //
     
    248241    // directly from the HW vector table at 0.
    249242    //
    250     .comm    VBR,4,2        // This defines the 'virtual' VBR
    251     // From C: extern void \*VBR;
     243        .comm    VBR,4,2        // This defines the 'virtual' VBR
     244    // From C: extern void *VBR;
    252245    myhandler:                  // At entry, PC contains the full vector
    253     move.l  %d0,-(%sp)      // Save d0
    254     move.l  %a0,-(%sp)      // Save a0
    255     lea     0(%pc),%a0      // Get the value of the PC
    256     move.l  %a0,%d0         // Copy it to a data reg, d0 is VV??????
    257     swap    %d0             // Now d0 is ????VV??
    258     and.w   #0xff00,%d0     // Now d0 is ????VV00 (1)
    259     lsr.w   #6,%d0          // Now d0.w contains the VBR table offset
    260     move.l  VBR,%a0         // Get the address from VBR to a0
    261     move.l  (%a0,%d0.w),%a0 // Fetch the vector
    262     move.l  4(%sp),%d0      // Restore d0
    263     move.l  %a0,4(%sp)      // Place target address to the stack
    264     move.l  (%sp)+,%a0      // Restore a0, target address is on TOS
    265     ret                     // This will jump to the handler and
     246        move.l  %d0,-(%sp)      // Save d0
     247        move.l  %a0,-(%sp)      // Save a0
     248        lea     0(%pc),%a0      // Get the value of the PC
     249        move.l  %a0,%d0         // Copy it to a data reg, d0 is VV??????
     250        swap    %d0             // Now d0 is ????VV??
     251        and.w   #0xff00,%d0     // Now d0 is ????VV00 (1)
     252        lsr.w   #6,%d0          // Now d0.w contains the VBR table offset
     253        move.l  VBR,%a0         // Get the address from VBR to a0
     254        move.l  (%a0,%d0.w),%a0 // Fetch the vector
     255        move.l  4(%sp),%d0      // Restore d0
     256        move.l  %a0,4(%sp)      // Place target address to the stack
     257        move.l  (%sp)+,%a0      // Restore a0, target address is on TOS
     258        ret                     // This will jump to the handler and
    266259    // restore the stack
    267     (1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
     260
     261(1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
    268262    after the vector table then that insn is not needed.
    269263
    270 There are probably shorter ways to do this, but it I believe is enough
    271 to illustrate the trick. Optimisation is left as an exercise to the
    272 reader :-)
     264There are probably shorter ways to do this, but it I believe is enough to
     265illustrate the trick. Optimisation is left as an exercise to the reader :-)
    273266
    274267Interrupt Levels
    275268----------------
    276269
    277 Eight levels (0-7) of interrupt priorities are
    278 supported by MC68xxx family members with level seven (7) being
    279 the highest priority.  Level zero (0) indicates that interrupts
    280 are fully enabled.  Interrupt requests for interrupts with
    281 priorities less than or equal to the current interrupt mask
    282 level are ignored.
    283 
    284 Although RTEMS supports 256 interrupt levels, the
    285 MC68xxx family only supports eight.  RTEMS interrupt levels 0
    286 through 7 directly correspond to MC68xxx interrupt levels.  All
    287 other RTEMS interrupt levels are undefined and their behavior is
    288 unpredictable.
     270Eight levels (0-7) of interrupt priorities are supported by MC68xxx family
     271members with level seven (7) being the highest priority.  Level zero (0)
     272indicates that interrupts are fully enabled.  Interrupt requests for interrupts
     273with priorities less than or equal to the current interrupt mask level are
     274ignored.
     275
     276Although RTEMS supports 256 interrupt levels, the MC68xxx family only supports
     277eight.  RTEMS interrupt levels 0 through 7 directly correspond to MC68xxx
     278interrupt levels.  All other RTEMS interrupt levels are undefined and their
     279behavior is unpredictable.
    289280
    290281Default Fatal Error Processing
     
    292283
    293284The default fatal error handler for this architecture disables processor
    294 interrupts to level 7, places the error code in D0, and executes a``stop`` instruction to simulate a halt processor instruction.
     285interrupts to level 7, places the error code in D0, and executes a ``stop``
     286instruction to simulate a halt processor instruction.
    295287
    296288Symmetric Multiprocessing
     
    311303
    312304An RTEMS based application is initiated or re-initiated when the MC68020
    313 processor is reset.  When the MC68020 is reset, the processor performs
    314 the following actions:
    315 
    316 - The tracing bits of the status register are cleared to
    317   disable tracing.
    318 
    319 - The supervisor interrupt state is entered by setting the
    320   supervisor (S) bit and clearing the master/interrupt (M) bit of
    321   the status register.
    322 
    323 - The interrupt mask of the status register is set to
    324   level 7 to effectively disable all maskable interrupts.
     305processor is reset.  When the MC68020 is reset, the processor performs the
     306following actions:
     307
     308- The tracing bits of the status register are cleared to disable tracing.
     309
     310- The supervisor interrupt state is entered by setting the supervisor (S) bit
     311  and clearing the master/interrupt (M) bit of the status register.
     312
     313- The interrupt mask of the status register is set to level 7 to effectively
     314  disable all maskable interrupts.
    325315
    326316- The vector base register (VBR) is set to zero.
    327317
    328 - The cache control register (CACR) is set to zero to
    329   disable and freeze the processor cache.
    330 
    331 - The interrupt stack pointer (ISP) is set to the value
    332   stored at vector 0 (bytes 0-3) of the exception vector table
    333   (EVT).
    334 
    335 - The program counter (PC) is set to the value stored at
    336   vector 1 (bytes 4-7) of the EVT.
    337 
    338 - The processor begins execution at the address stored in
    339   the PC.
     318- The cache control register (CACR) is set to zero to disable and freeze the
     319  processor cache.
     320
     321- The interrupt stack pointer (ISP) is set to the value stored at vector 0
     322  (bytes 0-3) of the exception vector table (EVT).
     323
     324- The program counter (PC) is set to the value stored at vector 1 (bytes 4-7)
     325  of the EVT.
     326
     327- The processor begins execution at the address stored in the PC.
    340328
    341329Processor Initialization
    342330------------------------
    343331
    344 The address of the application's initialization code should be stored in
    345 the first vector of the EVT which will allow the immediate vectoring to
    346 the application code.  If the application requires that the VBR be some
    347 value besides zero, then it should be set to the required value at this
    348 point.  All tasks share the same MC68020's VBR value.  Because interrupts
    349 are enabled automatically by RTEMS as part of the context switch to the
    350 first task, the VBR MUST be set by either RTEMS of the BSP before this
    351 occurs ensure correct interrupt vectoring.  If processor caching is
    352 to be utilized, then it should be enabled during the reset application
    353 initialization code.
    354 
    355 In addition to the requirements described in the
    356 Board Support Packages chapter of the Applications User's
    357 Manual for the reset code which is executed before the call to
    358 initialize executive, the MC68020 version has the following
     332The address of the application's initialization code should be stored in the
     333first vector of the EVT which will allow the immediate vectoring to the
     334application code.  If the application requires that the VBR be some value
     335besides zero, then it should be set to the required value at this point.  All
     336tasks share the same MC68020's VBR value.  Because interrupts are enabled
     337automatically by RTEMS as part of the context switch to the first task, the VBR
     338MUST be set by either RTEMS of the BSP before this occurs ensure correct
     339interrupt vectoring.  If processor caching is to be utilized, then it should be
     340enabled during the reset application initialization code.
     341
     342In addition to the requirements described in the Board Support Packages chapter
     343of the Applications User's Manual for the reset code which is executed before
     344the call to initialize executive, the MC68020 version has the following
    359345specific requirements:
    360346
    361 - Must leave the S bit of the status register set so that
    362   the MC68020 remains in the supervisor state.
    363 
    364 - Must set the M bit of the status register to remove the
    365   MC68020 from the interrupt state.
    366 
    367 - Must set the master stack pointer (MSP) such that a
    368   minimum stack size of MINIMUM_STACK_SIZE bytes is provided for
    369   the initialize executive directive.
     347- Must leave the S bit of the status register set so that the MC68020 remains
     348  in the supervisor state.
     349
     350- Must set the M bit of the status register to remove the MC68020 from the
     351  interrupt state.
     352
     353- Must set the master stack pointer (MSP) such that a minimum stack size of
     354  MINIMUM_STACK_SIZE bytes is provided for the initialize executive directive.
    370355
    371356- Must initialize the MC68020's vector table.
    372 
    373 .. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    374 
  • cpu_supplement/mips.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    24
    35MIPS Specific Information
    46#########################
    57
    6 This chapter discusses the MIPS architecture dependencies
    7 in this port of RTEMS.  The MIPS family has a wide variety
    8 of implementations by a wide range of vendors.  Consequently,
    9 there are many, many CPU models within it.
     8This chapter discusses the MIPS architecture dependencies in this port of
     9RTEMS.  The MIPS family has a wide variety of implementations by a wide range
     10of vendors.  Consequently, there are many, many CPU models within it.
    1011
    1112**Architecture Documents**
     
    1314IDT docs are online at http://www.idt.com/products/risc/Welcome.html
    1415
    15 For information on the XXX architecture, refer to the following documents
    16 available from VENDOR (:file:`http//www.XXX.com/`):
    17 
    18 - *XXX Family Reference, VENDOR, PART NUMBER*.
    19 
    2016CPU Model Dependent Features
    2117============================
    2218
    23 This section presents the set of features which vary
    24 across MIPS implementations and are of importance to RTEMS.
    25 The set of CPU model feature macros are defined in the file``cpukit/score/cpu/mips/mips.h`` based upon the particular CPU
    26 model specified on the compilation command line.
     19This section presents the set of features which vary across MIPS
     20implementations and are of importance to RTEMS.  The set of CPU model feature
     21macros are defined in the file ``cpukit/score/cpu/mips/mips.h`` based upon the
     22particular CPU model specified on the compilation command line.
    2723
    2824Another Optional Feature
     
    6056-----------------
    6157
    62 The MIPS family supports a flat 32-bit address
    63 space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
    64 gigabytes).  Each address is represented by a 32-bit value and
    65 is byte addressable.  The address may be used to reference a
    66 single byte, word (2-bytes), or long word (4 bytes).  Memory
    67 accesses within this address space are performed in big endian
    68 fashion by the processors in this family.
     58The MIPS family supports a flat 32-bit address space with addresses ranging
     59from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is represented by a
     6032-bit value and is byte addressable.  The address may be used to reference a
     61single byte, word (2-bytes), or long word (4 bytes).  Memory accesses within
     62this address space are performed in big endian fashion by the processors in
     63this family.
    6964
    7065Some of the MIPS family members such as the support virtual memory and
    71 segmentation.  RTEMS does not support virtual memory or
    72 segmentation on any of these family members.
     66segmentation.  RTEMS does not support virtual memory or segmentation on any of
     67these family members.
    7368
    7469Interrupt Processing
    7570====================
    7671
    77 Although RTEMS hides many of the processor dependent
    78 details of interrupt processing, it is important to understand
    79 how the RTEMS interrupt manager is mapped onto the processor's
    80 unique architecture. Discussed in this chapter are the MIPS's
    81 interrupt response and control mechanisms as they pertain to
    82 RTEMS.
     72Although RTEMS hides many of the processor dependent details of interrupt
     73processing, it is important to understand how the RTEMS interrupt manager is
     74mapped onto the processor's unique architecture. Discussed in this chapter are
     75the MIPS's interrupt response and control mechanisms as they pertain to RTEMS.
    8376
    8477Vectoring of an Interrupt Handler
    8578---------------------------------
    8679
    87 Upon receipt of an interrupt the XXX family
    88 members with separate interrupt stacks automatically perform the
    89 following actions:
     80Upon receipt of an interrupt the XXX family members with separate interrupt
     81stacks automatically perform the following actions:
    9082
    9183- TBD
    9284
    93 A nested interrupt is processed similarly by these
    94 CPU models with the exception that only a single ISF is placed
    95 on the interrupt stack and the current stack need not be
    96 switched.
     85A nested interrupt is processed similarly by these CPU models with the
     86exception that only a single ISF is placed on the interrupt stack and the
     87current stack need not be switched.
    9788
    9889Interrupt Levels
     
    10495==============================
    10596
    106 The default fatal error handler for this target architecture disables
    107 processor interrupts, places the error code in *XXX*, and executes a``XXX`` instruction to simulate a halt processor instruction.
     97The default fatal error handler for this target architecture disables processor
     98interrupts, places the error code in *XXX*, and executes a``XXX`` instruction
     99to simulate a halt processor instruction.
    108100
    109101Symmetric Multiprocessing
     
    123115------------
    124116
    125 An RTEMS based application is initiated or
    126 re-initiated when the processor is reset.  When the
    127 processor is reset, it performs the following actions:
     117An RTEMS based application is initiated or re-initiated when the processor is
     118reset.  When the processor is reset, it performs the following actions:
    128119
    129120- TBD
     
    133124
    134125TBD
    135 
    136 .. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
    137 
  • cpu_supplement/openrisc_1000.rst

    re6fe68d rf233256  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1989-2007.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37OpenRISC 1000 Specific Information
    48##################################
    59
    6 This chapter discusses the`OpenRISC 1000 architecture <http://opencores.org/or1k/Main_Page>`_
    7 dependencies in this port of RTEMS. There are many implementations
    8 for OpenRISC like or1200 and mor1kx. Currently RTEMS supports basic
    9 features that all implementations should have.
     10This chapter discusses the`OpenRISC 1000 architecture
     11http://opencores.org/or1k/Main_Page dependencies in this port of RTEMS. There
     12are many implementations for OpenRISC like or1200 and mor1kx. Currently RTEMS
     13supports basic features that all implementations should have.
    1014
    1115**Architecture Documents**
    1216
    13 For information on the OpenRISC 1000 architecture refer to the`OpenRISC 1000 architecture manual <http://openrisc.github.io/or1k.html>`_.
     17For information on the OpenRISC 1000 architecture refer to the`OpenRISC 1000
     18architecture manual http://openrisc.github.io/or1k.html.
    1419
    1520Calling Conventions
    1621===================
    1722
    18 Please refer to the`Function Calling Sequence <http://openrisc.github.io/or1k.html#__RefHeading__504887_595890882>`_.
     23Please refer to the`Function Calling Sequence
     24http://openrisc.github.io/or1k.html#__RefHeading__504887_595890882.
    1925
    2026Floating Point Unit
     
    6975---------------
    7076
    71 The OpenRISC RTEMS port uses a dedicated software interrupt stack.
    72 The stack for interrupts is allocated during interrupt driver initialization.
    73 When an  interrupt is entered, the _ISR_Handler routine is responsible for
    74 switching from the interrupted task stack to RTEMS software interrupt stack.
     77The OpenRISC RTEMS port uses a dedicated software interrupt stack.  The stack
     78for interrupts is allocated during interrupt driver initialization.  When an
     79interrupt is entered, the _ISR_Handler routine is responsible for switching
     80from the interrupted task stack to RTEMS software interrupt stack.
    7581
    7682Default Fatal Error Processing
    7783==============================
    7884
    79 The default fatal error handler for this architecture performs the
    80 following actions:
     85The default fatal error handler for this architecture performs the following
     86actions:
    8187
    8288- disables operating system supported interrupts (IRQ),
     
    9096
    9197SMP is not supported.
    92 
    93 .. COMMENT: COPYRIGHT (c) 1989-2007.
    94 
    95 .. COMMENT: On-Line Applications Research Corporation (OAR).
    96 
    97 .. COMMENT: All rights reserved.
    98 
  • cpu_supplement/port.rst

    re6fe68d rf233256  
    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
    37Port Specific Information
    48#########################
    59
    6 This chaper provides a general description of the type of
    7 architecture specific information which is in each of
    8 the architecture specific chapters that follow.  The outline
    9 of this chapter is identical to that of the architecture
    10 specific chapters.
    11 
    12 In each of the architecture specific chapters, this
    13 introductory section will provide an overview of the
    14 architecture
     10This chaper provides a general description of the type of architecture specific
     11information which is in each of the architecture specific chapters that follow.
     12The outline of this chapter is identical to that of the architecture specific
     13chapters.
     14
     15In each of the architecture specific chapters, this introductory section will
     16provide an overview of the architecture:
    1517
    1618**Architecture Documents**
    1719
    18 In each of the architecture specific chapters, this
    19 section will provide pointers on where to obtain
    20 documentation.
     20In each of the architecture specific chapters, this section will provide
     21pointers on where to obtain documentation.
    2122
    2223CPU Model Dependent Features
    2324============================
    2425
    25 Microprocessors are generally classified into families with a variety of
    26 CPU models or implementations within that family.  Within a processor
    27 family, there is a high level of binary compatibility.  This family
    28 may be based on either an architectural specification or on maintaining
    29 compatibility with a popular processor.  Recent microprocessor families
    30 such as the SPARC or PowerPC are based on an architectural specification
    31 which is independent or any particular CPU model or implementation.
    32 Older families such as the Motorola 68000 and the Intel x86 evolved as the
    33 manufacturer strived to produce higher performance processor models which
    34 maintained binary compatibility with older models.
    35 
    36 RTEMS takes advantage of the similarity of the various models within a
    37 CPU family.  Although the models do vary in significant ways, the high
    38 level of compatibility makes it possible to share the bulk of the CPU
    39 dependent executive code across the entire family.  Each processor family
    40 supported by RTEMS has a list of features which vary between CPU models
    41 within a family.  For example, the most common model dependent feature
    42 regardless of CPU family is the presence or absence of a floating point
    43 unit or coprocessor.  When defining the list of features present on a
    44 particular CPU model, one simply notes that floating point hardware
    45 is or is not present and defines a single constant appropriately.
    46 Conditional compilation is utilized to include the appropriate source
    47 code for this CPU model's feature set.  It is important to note that
    48 this means that RTEMS is thus compiled using the appropriate feature set
    49 and compilation flags optimal for this CPU model used.  The alternative
    50 would be to generate a binary which would execute on all family members
    51 using only the features which were always present.
    52 
    53 The set of CPU model feature macros are defined in the file``cpukit/score/cpu/CPU/rtems/score/cpu.h`` based upon the GNU tools
    54 multilib variant that is appropriate for the particular CPU model defined
    55 on the compilation command line.
    56 
    57 In each of the architecture specific chapters, this section presents
    58 the set of features which vary across various implementations of the
    59 architecture that may be of importance to RTEMS application developers.
    60 
    61 The subsections will vary amongst the target architecture chapters as
    62 the specific features may vary.  However, each port will include a few
    63 common features such as the CPU Model Name and presence of a hardware
    64 Floating Point Unit.  The common features are described here.
     26Microprocessors are generally classified into families with a variety of CPU
     27models or implementations within that family.  Within a processor family, there
     28is a high level of binary compatibility.  This family may be based on either an
     29architectural specification or on maintaining compatibility with a popular
     30processor.  Recent microprocessor families such as the SPARC or PowerPC are
     31based on an architectural specification which is independent or any particular
     32CPU model or implementation.  Older families such as the Motorola 68000 and the
     33Intel x86 evolved as the manufacturer strived to produce higher performance
     34processor models which maintained binary compatibility with older models.
     35
     36RTEMS takes advantage of the similarity of the various models within a CPU
     37family.  Although the models do vary in significant ways, the high level of
     38compatibility makes it possible to share the bulk of the CPU dependent
     39executive code across the entire family.  Each processor family supported by
     40RTEMS has a list of features which vary between CPU models within a family.
     41For example, the most common model dependent feature regardless of CPU family
     42is the presence or absence of a floating point unit or coprocessor.  When
     43defining the list of features present on a particular CPU model, one simply
     44notes that floating point hardware is or is not present and defines a single
     45constant appropriately.  Conditional compilation is utilized to include the
     46appropriate source code for this CPU model's feature set.  It is important to
     47note that this means that RTEMS is thus compiled using the appropriate feature
     48set and compilation flags optimal for this CPU model used.  The alternative
     49would be to generate a binary which would execute on all family members using
     50only the features which were always present.
     51
     52The set of CPU model feature macros are defined in the
     53:file:`cpukit/score/cpu/CPU/rtems/score/cpu.h` based upon the GNU tools
     54multilib variant that is appropriate for the particular CPU model defined on
     55the compilation command line.
     56
     57In each of the architecture specific chapters, this section presents the set of
     58features which vary across various implementations of the architecture that may
     59be of importance to RTEMS application developers.
     60
     61The subsections will vary amongst the target architecture chapters as the
     62specific features may vary.  However, each port will include a few common
     63features such as the CPU Model Name and presence of a hardware Floating Point
     64Unit.  The common features are described here.
    6565
    6666CPU Model Name
    6767--------------
    6868
    69 The macro ``CPU_MODEL_NAME`` is a string which designates
    70 the name of this CPU model.  For example, for the MC68020
    71 processor model from the m68k architecture, this macro
    72 is set to the string "mc68020".
     69The macro ``CPU_MODEL_NAME`` is a string which designates the name of this CPU
     70model.  For example, for the MC68020 processor model from the m68k
     71architecture, this macro is set to the string "mc68020".
    7372
    7473Floating Point Unit
    7574-------------------
    7675
    77 In most architectures, the presence of a floating point unit is an option.
    78 It does not matter whether the hardware floating point support is
    79 incorporated on-chip or is an external coprocessor as long as it
    80 appears an FPU per the ISA.  However, if a hardware FPU is not present,
    81 it is possible that the floating point emulation library for this
    82 CPU is not reentrant and thus context switched by RTEMS.
     76In most architectures, the presence of a floating point unit is an option.  It
     77does not matter whether the hardware floating point support is incorporated
     78on-chip or is an external coprocessor as long as it appears an FPU per the ISA.
     79However, if a hardware FPU is not present, it is possible that the floating
     80point emulation library for this CPU is not reentrant and thus context switched
     81by RTEMS.
    8382
    8483RTEMS provides two feature macros to indicate the FPU configuration:
     
    8887
    8988- CPU_SOFTWARE_FP
    90   is set to TRUE to indicate that a hardware FPU is not present and that
    91   the FP software emulation will be context switched.
     89  is set to TRUE to indicate that a hardware FPU is not present and that the FP
     90  software emulation will be context switched.
    9291
    9392Multilibs
    9493=========
    9594
    96 Newlib and GCC provide several target libraries like the :file:`libc.a`,:file:`libm.a` and :file:`libgcc.a`.  These libraries are artifacts of the GCC
     95Newlib and GCC provide several target libraries like the :file:`libc.a`,
     96:file:`libm.a` and :file:`libgcc.a`.  These libraries are artifacts of the GCC
    9797build process.  Newlib is built together with GCC.  To provide optimal support
    9898for various chip derivatives and instruction set revisions multiple variants of
     
    111111Invoking the GCC with the ``-print-multi-lib`` option lists the available
    112112multilibs.  Each line of the output describes one multilib variant.  The
    113 default variant is denoted by ``.`` which is selected when no or
    114 contradicting GCC machine options are selected.  The multilib selection for a
    115 target is specified by target makefile fragments (see file :file:`t-rtems` in
    116 the GCC sources and section`The Target Makefile Fragment <https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment>`_
    117 in the `GCC Internals Manual <https://gcc.gnu.org/onlinedocs/gccint/>`_.
     113default variant is denoted by ``.`` which is selected when no or contradicting
     114GCC machine options are selected.  The multilib selection for a target is
     115specified by target makefile fragments (see file :file:`t-rtems` in the GCC
     116sources and section *The Target Makefile Fragment*
     117(https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment)
     118in the *GCC Internals Manual* (https://gcc.gnu.org/onlinedocs/gccint/).
    118119
    119120Calling Conventions
    120121===================
    121122
    122 Each high-level language compiler generates subroutine entry and exit
    123 code based upon a set of rules known as the compiler's calling convention.
    124 These rules address the following issues:
     123Each high-level language compiler generates subroutine entry and exit code
     124based upon a set of rules known as the compiler's calling convention.  These
     125rules address the following issues:
    125126
    126127- register preservation and usage
     
    130131- call and return mechanism
    131132
    132 A compiler's calling convention is of importance when
    133 interfacing to subroutines written in another language either
    134 assembly or high-level.  Even when the high-level language and
    135 target processor are the same, different compilers may use
    136 different calling conventions.  As a result, calling conventions
    137 are both processor and compiler dependent.
     133A compiler's calling convention is of importance when interfacing to
     134subroutines written in another language either assembly or high-level.  Even
     135when the high-level language and target processor are the same, different
     136compilers may use different calling conventions.  As a result, calling
     137conventions are both processor and compiler dependent.
    138138
    139139Calling Mechanism
    140140-----------------
    141141
    142 In each of the architecture specific chapters, this subsection will
    143 describe the instruction(s) used to perform a *normal* subroutine
    144 invocation.  All RTEMS directives are invoked as *normal* C language
    145 functions so it is important to the user application to understand the
    146 call and return mechanism.
     142In each of the architecture specific chapters, this subsection will describe
     143the instruction(s) used to perform a *normal* subroutine invocation.  All RTEMS
     144directives are invoked as *normal* C language functions so it is important to
     145the user application to understand the call and return mechanism.
    147146
    148147Register Usage
    149148--------------
    150149
    151 In each of the architecture specific chapters, this subsection will
    152 detail the set of registers which are *NOT* preserved across subroutine
    153 invocations.  The registers which are not preserved are assumed to be
    154 available for use as scratch registers.  Therefore, the contents of these
    155 registers should not be assumed upon return from any RTEMS directive.
     150In each of the architecture specific chapters, this subsection will detail the
     151set of registers which are *NOT* preserved across subroutine invocations.  The
     152registers which are not preserved are assumed to be available for use as
     153scratch registers.  Therefore, the contents of these registers should not be
     154assumed upon return from any RTEMS directive.
    156155
    157156In some architectures, there may be a set of registers made available
    158 automatically as a side-effect of the subroutine invocation
    159 mechanism.
     157automatically as a side-effect of the subroutine invocation mechanism.
    160158
    161159Parameter Passing
    162160-----------------
    163161
    164 In each of the architecture specific chapters, this subsection will
    165 describe the mechanism by which the parameters or arguments are passed
    166 by the caller to a subroutine.  In some architectures, all parameters
    167 are passed on the stack while in others some are passed in registers.
     162In each of the architecture specific chapters, this subsection will describe
     163the mechanism by which the parameters or arguments are passed by the caller to
     164a subroutine.  In some architectures, all parameters are passed on the stack
     165while in others some are passed in registers.
    168166
    169167User-Provided Routines
    170168----------------------
    171169
    172 All user-provided routines invoked by RTEMS, such as
    173 user extensions, device drivers, and MPCI routines, must also
    174 adhere to these calling conventions.
     170All user-provided routines invoked by RTEMS, such as user extensions, device
     171drivers, and MPCI routines, must also adhere to these calling conventions.
    175172
    176173Memory Model
    177174============
    178175
    179 A processor may support any combination of memory
    180 models ranging from pure physical addressing to complex demand
    181 paged virtual memory systems.  RTEMS supports a flat memory
    182 model which ranges contiguously over the processor's allowable
    183 address space.  RTEMS does not support segmentation or virtual
    184 memory of any kind.  The appropriate memory model for RTEMS
    185 provided by the targeted processor and related characteristics
    186 of that model are described in this chapter.
     176A processor may support any combination of memory models ranging from pure
     177physical addressing to complex demand paged virtual memory systems.  RTEMS
     178supports a flat memory model which ranges contiguously over the processor's
     179allowable address space.  RTEMS does not support segmentation or virtual memory
     180of any kind.  The appropriate memory model for RTEMS provided by the targeted
     181processor and related characteristics of that model are described in this
     182chapter.
    187183
    188184Flat Memory Model
     
    190186
    191187Most RTEMS target processors can be initialized to support a flat address
    192 space.  Although the size of addresses varies between architectures, on
    193 most RTEMS targets, an address is 32-bits wide which defines addresses
    194 ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is
    195 represented by a 32-bit value and is byte addressable.  The address may be
    196 used to reference a single byte, word (2-bytes), or long word (4 bytes).
    197 Memory accesses within this address space may be performed in little or
    198 big endian fashion.
    199 
    200 On smaller CPU architectures supported by RTEMS, the address space
    201 may only be 20 or 24 bits wide.
    202 
    203 If the CPU model has support for virtual memory or segmentation, it is
    204 the responsibility of the Board Support Package (BSP) to initialize the
    205 MMU hardware to perform address translations which correspond to flat
    206 memory model.
    207 
    208 In each of the architecture specific chapters, this subsection will
    209 describe any architecture characteristics that differ from this general
    210 description.
     188space.  Although the size of addresses varies between architectures, on most
     189RTEMS targets, an address is 32-bits wide which defines addresses ranging from
     1900x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is represented by a
     19132-bit value and is byte addressable.  The address may be used to reference a
     192single byte, word (2-bytes), or long word (4 bytes).  Memory accesses within
     193this address space may be performed in little or big endian fashion.
     194
     195On smaller CPU architectures supported by RTEMS, the address space may only be
     19620 or 24 bits wide.
     197
     198If the CPU model has support for virtual memory or segmentation, it is the
     199responsibility of the Board Support Package (BSP) to initialize the MMU
     200hardware to perform address translations which correspond to flat memory model.
     201
     202In each of the architecture specific chapters, this subsection will describe
     203any architecture characteristics that differ from this general description.
    211204
    212205Interrupt Processing
    213206====================
    214207
    215 Different types of processors respond to the occurrence of an interrupt
    216 in its own unique fashion. In addition, each processor type provides
    217 a control mechanism to allow for the proper handling of an interrupt.
    218 The processor dependent response to the interrupt modifies the current
    219 execution state and results in a change in the execution stream.  Most
    220 processors require that an interrupt handler utilize some special control
    221 mechanisms to return to the normal processing stream.  Although RTEMS
    222 hides many of the processor dependent details of interrupt processing,
    223 it is important to understand how the RTEMS interrupt manager is mapped
    224 onto the processor's unique architecture.
    225 
    226 RTEMS supports a dedicated interrupt stack for all architectures.
    227 On architectures with hardware support for a dedicated interrupt stack,
    228 it will be initialized such that when an interrupt occurs, the processor
    229 automatically switches to this dedicated stack.  On architectures without
    230 hardware support for a dedicated interrupt stack which is separate from
    231 those of the tasks, RTEMS will support switching to a dedicated stack
    232 for interrupt processing.
    233 
    234 Without a dedicated interrupt stack, every task in
    235 the system MUST have enough stack space to accommodate the worst
    236 case stack usage of that particular task and the interrupt
    237 service routines COMBINED.  By supporting a dedicated interrupt
    238 stack, RTEMS significantly lowers the stack requirements for
    239 each task.
    240 
    241 A nested interrupt is processed similarly with the exception that since
    242 the CPU is already executing on the interrupt stack, there is no need
    243 to switch to the interrupt stack.
    244 
    245 In some configurations, RTEMS allocates the interrupt stack from the
    246 Workspace Area.  The amount of memory allocated for the interrupt stack
    247 is user configured and based upon the ``confdefs.h`` parameter``CONFIGURE_INTERRUPT_STACK_SIZE``.  This parameter is described
    248 in detail in the Configuring a System chapter of the User's Guide.
    249 On configurations in which RTEMS allocates the interrupt stack, during
    250 the initialization process, RTEMS will also install its interrupt stack.
    251 In other configurations, the interrupt stack is allocated and installed
    252 by the Board Support Package (BSP).
    253 
    254 In each of the architecture specific chapters, this section discesses
    255 the interrupt response and control mechanisms of the architecture as
    256 they pertain to RTEMS.
     208Different types of processors respond to the occurrence of an interrupt in its
     209own unique fashion. In addition, each processor type provides a control
     210mechanism to allow for the proper handling of an interrupt.  The processor
     211dependent response to the interrupt modifies the current execution state and
     212results in a change in the execution stream.  Most processors require that an
     213interrupt handler utilize some special control mechanisms to return to the
     214normal processing stream.  Although RTEMS hides many of the processor dependent
     215details of interrupt processing, it is important to understand how the RTEMS
     216interrupt manager is mapped onto the processor's unique architecture.
     217
     218RTEMS supports a dedicated interrupt stack for all architectures.  On
     219architectures with hardware support for a dedicated interrupt stack, it will be
     220initialized such that when an interrupt occurs, the processor automatically
     221switches to this dedicated stack.  On architectures without hardware support
     222for a dedicated interrupt stack which is separate from those of the tasks,
     223RTEMS will support switching to a dedicated stack for interrupt processing.
     224
     225Without a dedicated interrupt stack, every task in the system MUST have enough
     226stack space to accommodate the worst case stack usage of that particular task
     227and the interrupt service routines COMBINED.  By supporting a dedicated
     228interrupt stack, RTEMS significantly lowers the stack requirements for each
     229task.
     230
     231A nested interrupt is processed similarly with the exception that since the CPU
     232is already executing on the interrupt stack, there is no need to switch to the
     233interrupt stack.
     234
     235In some configurations, RTEMS allocates the interrupt stack from the Workspace
     236Area.  The amount of memory allocated for the interrupt stack is user
     237configured and based upon the ``confdefs.h`` parameter
     238``CONFIGURE_INTERRUPT_STACK_SIZE``.  This parameter is described in detail in
     239the Configuring a System chapter of the User's Guide.  On configurations in
     240which RTEMS allocates the interrupt stack, during the initialization process,
     241RTEMS will also install its interrupt stack.  In other configurations, the
     242interrupt stack is allocated and installed by the Board Support Package (BSP).
     243
     244In each of the architecture specific chapters, this section discesses the
     245interrupt response and control mechanisms of the architecture as they pertain
     246to RTEMS.
    257247
    258248Vectoring of an Interrupt Handler
    259249---------------------------------
    260250
    261 In each of the architecture specific chapters, this subsection will
    262 describe the architecture specific details of the interrupt vectoring
    263 process.  In particular, it should include a description of the
    264 Interrupt Stack Frame (ISF).
     251In each of the architecture specific chapters, this subsection will describe
     252the architecture specific details of the interrupt vectoring process.  In
     253particular, it should include a description of the Interrupt Stack Frame (ISF).
    265254
    266255Interrupt Levels
    267256----------------
    268257
    269 In each of the architecture specific chapters, this subsection will
    270 describe how the interrupt levels available on this particular architecture
    271 are mapped onto the 255 reserved in the task mode.  The interrupt level
    272 value of zero (0) should always mean that interrupts are enabled.
    273 
    274 Any use of an  interrupt level that is is not undefined on a particular
     258In each of the architecture specific chapters, this subsection will describe
     259how the interrupt levels available on this particular architecture are mapped
     260onto the 255 reserved in the task mode.  The interrupt level value of zero (0)
     261should always mean that interrupts are enabled.
     262
     263Any use of an interrupt level that is is not undefined on a particular
    275264architecture may result in behavior that is unpredictable.
    276265
     
    278267--------------------------------
    279268
    280 During the execution of directive calls, critical sections of code may
    281 be executed.  When these sections are encountered, RTEMS disables all
    282 external interrupts before the execution of this section and restores
    283 them to the previous level upon completion of the section.  RTEMS has
    284 been optimized to ensure that interrupts are disabled for the shortest
    285 number of instructions possible.  Since the precise number of instructions
    286 and their execution time varies based upon target CPU family, CPU model,
    287 board memory speed, compiler version, and optimization level, it is
    288 not practical to provide the precise number for all possible RTEMS
    289 configurations.
    290 
    291 Historically, the measurements were made by hand analyzing and counting
    292 the execution time of instruction sequences during interrupt disable
    293 critical sections.  For reference purposes, on a 16 Mhz Motorola
    294 MC68020, the maximum interrupt disable period was typically approximately
    295 ten (10) to thirteen (13) microseconds.  This architecture was memory bound
    296 and had a slow bit scan instruction.  In contrast, during the same
    297 period a 14 Mhz SPARC would have a worst case disable time of approximately
    298 two (2) to three (3) microseconds because it had a single cycle bit scan
    299 instruction and used fewer cycles for memory accesses.
    300 
    301 If you are interested in knowing the worst case execution time for
    302 a particular version of RTEMS, please contact OAR Corporation and
    303 we will be happy to product the results as a consulting service.
    304 
    305 Non-maskable interrupts (NMI) cannot be disabled, and
    306 ISRs which execute at this level MUST NEVER issue RTEMS system
    307 calls.  If a directive is invoked, unpredictable results may
    308 occur due to the inability of RTEMS to protect its critical
    309 sections.  However, ISRs that make no system calls may safely
    310 execute as non-maskable interrupts.
     269During the execution of directive calls, critical sections of code may be
     270executed.  When these sections are encountered, RTEMS disables all external
     271interrupts before the execution of this section and restores them to the
     272previous level upon completion of the section.  RTEMS has been optimized to
     273ensure that interrupts are disabled for the shortest number of instructions
     274possible.  Since the precise number of instructions and their execution time
     275varies based upon target CPU family, CPU model, board memory speed, compiler
     276version, and optimization level, it is not practical to provide the precise
     277number for all possible RTEMS configurations.
     278
     279Historically, the measurements were made by hand analyzing and counting the
     280execution time of instruction sequences during interrupt disable critical
     281sections.  For reference purposes, on a 16 Mhz Motorola MC68020, the maximum
     282interrupt disable period was typically approximately ten (10) to thirteen (13)
     283microseconds.  This architecture was memory bound and had a slow bit scan
     284instruction.  In contrast, during the same period a 14 Mhz SPARC would have a
     285worst case disable time of approximately two (2) to three (3) microseconds
     286because it had a single cycle bit scan instruction and used fewer cycles for
     287memory accesses.
     288
     289If you are interested in knowing the worst case execution time for a particular
     290version of RTEMS, please contact OAR Corporation and we will be happy to
     291product the results as a consulting service.
     292
     293Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
     294this level MUST NEVER issue RTEMS system calls.  If a directive is invoked,
     295unpredictable results may occur due to the inability of RTEMS to protect its
     296critical sections.  However, ISRs that make no system calls may safely execute
     297as non-maskable interrupts.
    311298
    312299Default Fatal Error Processing
     
    314301
    315302Upon detection of a fatal error by either the application or RTEMS during
    316 initialization the ``rtems_fatal_error_occurred`` directive supplied
    317 by the Fatal Error Manager is invoked.  The Fatal Error Manager will
    318 invoke the user-supplied fatal error handlers.  If no user-supplied
    319 handlers are configured or all of them return without taking action to
    320 shutdown the processor or reset, a default fatal error handler is invoked.
     303initialization the ``rtems_fatal_error_occurred`` directive supplied by the
     304Fatal Error Manager is invoked.  The Fatal Error Manager will invoke the
     305user-supplied fatal error handlers.  If no user-supplied handlers are
     306configured or all of them return without taking action to shutdown the
     307processor or reset, a default fatal error handler is invoked.
    321308
    322309Most of the action performed as part of processing the fatal error are
    323 described in detail in the Fatal Error Manager chapter in the User's
    324 Guide.  However, the if no user provided extension or BSP specific fatal
    325 error handler takes action, the final default action is to invoke a
    326 CPU architecture specific function.  Typically this function disables
    327 interrupts and halts the processor.
     310described in detail in the Fatal Error Manager chapter in the User's Guide.
     311However, the if no user provided extension or BSP specific fatal error handler
     312takes action, the final default action is to invoke a CPU architecture specific
     313function.  Typically this function disables interrupts and halts the processor.
    328314
    329315In each of the architecture specific chapters, this describes the precise
     
    341327In order to support thread-local storage (TLS) the CPU port must implement the
    342328facilities mandated by the application binary interface (ABI) of the CPU
    343 architecture.  The CPU port must initialize the TLS area in the``_CPU_Context_Initialize()`` function.  There are support functions available
     329architecture.  The CPU port must initialize the TLS area in the
     330``_CPU_Context_Initialize()`` function.  There are support functions available
    344331via ``#include <rtems/score/tls.h>`` which implement Variants I and II
    345332according to Ulrich Drepper, *ELF Handling For Thread-Local Storage*.
    346333
    347334``_TLS_TCB_at_area_begin_initialize()``
    348     Uses Variant I, TLS offsets emitted by linker takes the TCB into account.  For
    349     a reference implementation see :file:`cpukit/score/cpu/arm/cpu.c`.
     335    Uses Variant I, TLS offsets emitted by linker takes the TCB into account.
     336    For a reference implementation see :file:`cpukit/score/cpu/arm/cpu.c`.
    350337
    351338``_TLS_TCB_before_TLS_block_initialize()``
    352339    Uses Variant I, TLS offsets emitted by linker neglects the TCB.  For a
    353     reference implementation see:file:`c/src/lib/libcpu/powerpc/new-exceptions/cpu.c`.
     340    reference implementation see
     341    :file:`c/src/lib/libcpu/powerpc/new-exceptions/cpu.c`.
    354342
    355343``_TLS_TCB_after_TLS_block_initialize()``
    356     Uses Variant II.  For a reference implementation see:file:`cpukit/score/cpu/sparc/cpu.c`.
     344    Uses Variant II.  For a reference implementation see
     345    :file:`cpukit/score/cpu/sparc/cpu.c`.
    357346
    358347The board support package (BSP) must provide the following sections and symbols
    359348in its linker command file:
    360 .. code:: c
     349
     350.. code-block:: c
    361351
    362352    .tdata : {
    363     _TLS_Data_begin = .;
    364     \*(.tdata .tdata.* .gnu.linkonce.td.*)
    365     _TLS_Data_end = .;
     353      _TLS_Data_begin = .;
     354      *(.tdata .tdata.* .gnu.linkonce.td.*)
     355      _TLS_Data_end = .;
    366356    }
    367357    .tbss : {
    368     _TLS_BSS_begin = .;
    369     \*(.tbss .tbss.* .gnu.linkonce.tb.*) \*(.tcommon)
    370     _TLS_BSS_end = .;
     358      _TLS_BSS_begin = .;
     359      *(.tbss .tbss.* .gnu.linkonce.tb.*) *(.tcommon)
     360      _TLS_BSS_end = .;
    371361    }
    372362    _TLS_Data_size = _TLS_Data_end - _TLS_Data_begin;
     
    384374or system bus clock.  On some architectures the actual implementation is board
    385375support package dependent.  The CPU counter is used for profiling of low-level
    386 functions.  It is also used to implement two busy wait functions``rtems_counter_delay_ticks()`` and ``rtems_counter_delay_nanoseconds()``
    387 which may be used in device drivers.  It may be also used as an entropy source
    388 for random number generators.
    389 
    390 The CPU counter interface uses a CPU port specific unsigned integer type``CPU_Counter_ticks`` to represent CPU counter values.  The CPU port must
     376functions.  It is also used to implement two busy wait functions
     377``rtems_counter_delay_ticks()`` and ``rtems_counter_delay_nanoseconds()`` which
     378may be used in device drivers.  It may be also used as an entropy source for
     379random number generators.
     380
     381The CPU counter interface uses a CPU port specific unsigned integer type
     382``CPU_Counter_ticks`` to represent CPU counter values.  The CPU port must
    391383provide the following two functions
    392384
     
    401393The RTEMS profiling needs support by the CPU port for the interrupt entry and
    402394exit times.  In case profiling is enabled via the RTEMS build configuration
    403 option ``--enable-profiling`` (in this case the pre-processor symbol``RTEMS_PROFILING`` is defined) the CPU port may provide data for the
    404 interrupt entry and exit times of the outer-most interrupt.  The CPU port can
    405 feed interrupt entry and exit times with the``_Profiling_Outer_most_interrupt_entry_and_exit()`` function
    406 (``#include <rtems/score/profiling.h>``).  For an example please have a look
    407 at ``cpukit/score/cpu/arm/arm_exc_interrupt.S``.
     395option ``--enable-profiling`` (in this case the pre-processor symbol
     396``RTEMS_PROFILING`` is defined) the CPU port may provide data for the interrupt
     397entry and exit times of the outer-most interrupt.  The CPU port can feed
     398interrupt entry and exit times with the
     399``_Profiling_Outer_most_interrupt_entry_and_exit()`` function (``#include
     400<rtems/score/profiling.h>``).  For an example please have a look at
     401:file:`cpukit/score/cpu/arm/arm_exc_interrupt.S`.
    408402
    409403Board Support Packages
    410404======================
    411405
    412 An RTEMS Board Support Package (BSP) must be designed to support a
    413 particular processor model and target board combination.
    414 
    415 In each of the architecture specific chapters, this section will present
    416 a discussion of architecture specific BSP issues.   For more information
    417 on developing a BSP, refer to BSP and Device Driver Development Guide
    418 and the chapter titled Board Support Packages in the RTEMS
    419 Applications User's Guide.
     406An RTEMS Board Support Package (BSP) must be designed to support a particular
     407processor model and target board combination.
     408
     409In each of the architecture specific chapters, this section will present a
     410discussion of architecture specific BSP issues.  For more information on
     411developing a BSP, refer to BSP and Device Driver Development Guide and the
     412chapter titled Board Support Packages in the RTEMS Applications User's Guide.
    420413
    421414System Reset
    422415------------
    423416
    424 An RTEMS based application is initiated or re-initiated when the processor
    425 is reset or transfer is passed to it from a boot monitor or ROM monitor.
    426 
    427 In each of the architecture specific chapters, this subsection describes
    428 the actions that the BSP must tak assuming the application gets control
    429 when the microprocessor is reset.
    430 
    431 .. COMMENT: COPYRIGHT (c) 1988-2002.
    432 
    433 .. COMMENT: On-Line Applications Research Corporation (OAR).
    434 
    435 .. COMMENT: All rights reserved.
    436 
     417An RTEMS based application is initiated or re-initiated when the processor is
     418reset or transfer is passed to it from a boot monitor or ROM monitor.
     419
     420In each of the architecture specific chapters, this subsection describes the
     421actions that the BSP must tak assuming the application gets control when the
     422microprocessor is reset.
  • cpu_supplement/powerpc.rst

    re6fe68d rf233256  
    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
    37PowerPC Specific Information
    48############################
    59
    6 This chapter discusses the PowerPC architecture dependencies
    7 in this port of RTEMS.  The PowerPC family has a wide variety
    8 of implementations by a range of vendors.  Consequently,
    9 there are many, many CPU models within it.
    10 
    11 It is highly recommended that the PowerPC RTEMS
    12 application developer obtain and become familiar with the
    13 documentation for the processor being used as well as the
    14 specification for the revision of the PowerPC architecture which
     10This chapter discusses the PowerPC architecture dependencies in this port of
     11RTEMS.  The PowerPC family has a wide variety of implementations by a range of
     12vendors.  Consequently, there are many, many CPU models within it.
     13
     14It is highly recommended that the PowerPC RTEMS application developer obtain
     15and become familiar with the documentation for the processor being used as well
     16as the specification for the revision of the PowerPC architecture which
    1517corresponds to that processor.
    1618
    1719**PowerPC Architecture Documents**
    1820
    19 For information on the PowerPC architecture, refer to
    20 the following documents available from Motorola and IBM:
     21For information on the PowerPC architecture, refer to the following documents
     22available from Motorola and IBM:
    2123
    2224- *PowerPC Microprocessor Family: The Programming Environment*
     
    4345  (Motorola Document MPC821UM/AD).
    4446
    45 - *PowerQUICC MPC860 User's Manual* (Motorola Document MPC860UM/AD).
    46 
    47 Motorola maintains an on-line electronic library for the PowerPC
    48 at the following URL:
     47- *PowerQUICC MPC860 User's Manual*
     48  (Motorola Document MPC860UM/AD).
     49
     50Motorola maintains an on-line electronic library for the PowerPC at the
     51following URL:
    4952
    5053-  http://www.mot.com/powerpc/library/library.html
    5154
    52 This site has a a wealth of information and examples.  Many of the
    53 manuals are available from that site in electronic format.
     55This site has a a wealth of information and examples.  Many of the manuals are
     56available from that site in electronic format.
    5457
    5558**PowerPC Processor Simulator Information**
    5659
    57 PSIM is a program which emulates the Instruction Set Architecture
    58 of the PowerPC microprocessor family.  It is reely available in source
    59 code form under the terms of the GNU General Public License (version
    60 2 or later).  PSIM can be integrated with the GNU Debugger (gdb) to
    61 execute and debug PowerPC executables on non-PowerPC hosts.  PSIM
    62 supports the addition of user provided device models which can be
    63 used to allow one to develop and debug embedded applications using
    64 the simulator.
    65 
    66 The latest version of PSIM is included in GDB and enabled on pre-built
    67 binaries provided by the RTEMS Project.
     60PSIM is a program which emulates the Instruction Set Architecture of the
     61PowerPC microprocessor family.  It is reely available in source code form under
     62the terms of the GNU General Public License (version 2 or later).  PSIM can be
     63integrated with the GNU Debugger (gdb) to execute and debug PowerPC executables
     64on non-PowerPC hosts.  PSIM supports the addition of user provided device
     65models which can be used to allow one to develop and debug embedded
     66applications using the simulator.
     67
     68The latest version of PSIM is included in GDB and enabled on pre-built binaries
     69provided by the RTEMS Project.
    6870
    6971CPU Model Dependent Features
    7072============================
    7173
    72 This section presents the set of features which vary
    73 across PowerPC implementations and are of importance to RTEMS.
    74 The set of CPU model feature macros are defined in the file``cpukit/score/cpu/powerpc/powerpc.h`` based upon the particular CPU
    75 model specified on the compilation command line.
     74This section presents the set of features which vary across PowerPC
     75implementations and are of importance to RTEMS.  The set of CPU model feature
     76macros are defined in the file ``cpukit/score/cpu/powerpc/powerpc.h`` based
     77upon the particular CPU model specified on the compilation command line.
    7678
    7779Alignment
     
    7981
    8082The macro PPC_ALIGNMENT is set to the PowerPC model's worst case alignment
    81 requirement for data types on a byte boundary.  This value is used
    82 to derive the alignment restrictions for memory allocated from
    83 regions and partitions.
     83requirement for data types on a byte boundary.  This value is used to derive
     84the alignment restrictions for memory allocated from regions and partitions.
    8485
    8586Cache Alignment
    8687---------------
    8788
    88 The macro PPC_CACHE_ALIGNMENT is set to the line size of the cache.  It is
    89 used to align the entry point of critical routines so that as much code
    90 as possible can be retrieved with the initial read into cache.  This
    91 is done for the interrupt handler as well as the context switch routines.
     89The macro PPC_CACHE_ALIGNMENT is set to the line size of the cache.  It is used
     90to align the entry point of critical routines so that as much code as possible
     91can be retrieved with the initial read into cache.  This is done for the
     92interrupt handler as well as the context switch routines.
    9293
    9394In addition, the "shortcut" data structure used by the PowerPC implementation
     
    9899------------------
    99100
    100 The macro PPC_INTERRUPT_MAX is set to the number of exception sources
    101 supported by this PowerPC model.
     101The macro PPC_INTERRUPT_MAX is set to the number of exception sources supported
     102by this PowerPC model.
    102103
    103104Has Double Precision Floating Point
    104105-----------------------------------
    105106
    106 The macro PPC_HAS_DOUBLE is set to 1 to indicate that the PowerPC model
    107 has support for double precision floating point numbers.  This is
    108 important because the floating point registers need only be four bytes
    109 wide (not eight) if double precision is not supported.
     107The macro PPC_HAS_DOUBLE is set to 1 to indicate that the PowerPC model has
     108support for double precision floating point numbers.  This is important because
     109the floating point registers need only be four bytes wide (not eight) if double
     110precision is not supported.
    110111
    111112Critical Interrupts
    112113-------------------
    113114
    114 The macro PPC_HAS_RFCI is set to 1 to indicate that the PowerPC model
    115 has the Critical Interrupt capability as defined by the IBM 403 models.
     115The macro PPC_HAS_RFCI is set to 1 to indicate that the PowerPC model has the
     116Critical Interrupt capability as defined by the IBM 403 models.
    116117
    117118Use Multiword Load/Store Instructions
     
    119120
    120121The macro PPC_USE_MULTIPLE is set to 1 to indicate that multiword load and
    121 store instructions should be used to perform context switch operations.
    122 The relative efficiency of multiword load and store instructions versus
    123 an equivalent set of single word load and store instructions varies based
    124 upon the PowerPC model.
     122store instructions should be used to perform context switch operations.  The
     123relative efficiency of multiword load and store instructions versus an
     124equivalent set of single word load and store instructions varies based upon the
     125PowerPC model.
    125126
    126127Instruction Cache Size
     
    137138-----------
    138139
    139 The macro PPC_DEBUG_MODEL is set to indicate the debug support features
    140 present in this CPU model.  The following debug support feature sets
    141 are currently supported:
     140The macro PPC_DEBUG_MODEL is set to indicate the debug support features present
     141in this CPU model.  The following debug support feature sets are currently
     142supported:
    142143
    143144*``PPC_DEBUG_MODEL_STANDARD``*
    144     indicates that the single-step trace enable (SE) and branch trace
    145     enable (BE) bits in the MSR are supported by this CPU model.
     145    indicates that the single-step trace enable (SE) and branch trace enable
     146    (BE) bits in the MSR are supported by this CPU model.
    146147
    147148*``PPC_DEBUG_MODEL_SINGLE_STEP_ONLY``*
    148     indicates that only the single-step trace enable (SE) bit in the MSR
    149     is supported by this CPU model.
     149    indicates that only the single-step trace enable (SE) bit in the MSR is
     150    supported by this CPU model.
    150151
    151152*``PPC_DEBUG_MODEL_IBM4xx``*
    152153    indicates that the debug exception enable (DE) bit in the MSR is supported
    153     by this CPU model.  At this time, this particular debug feature set
    154     has only been seen in the IBM 4xx series.
     154    by this CPU model.  At this time, this particular debug feature set has
     155    only been seen in the IBM 4xx series.
    155156
    156157Low Power Model
    157158~~~~~~~~~~~~~~~
    158159
    159 The macro PPC_LOW_POWER_MODE is set to indicate the low power model
    160 supported by this CPU model.  The following low power modes are currently
    161 supported.
     160The macro PPC_LOW_POWER_MODE is set to indicate the low power model supported
     161by this CPU model.  The following low power modes are currently supported.
    162162
    163163*``PPC_LOW_POWER_MODE_NONE``*
     
    165165
    166166*``PPC_LOW_POWER_MODE_STANDARD``*
    167     indicates that this CPU model follows the low power model defined for
    168     the PPC603e.
     167    indicates that this CPU model follows the low power model defined for the
     168    PPC603e.
    169169
    170170Multilibs
     
    216216===================
    217217
    218 RTEMS supports the Embedded Application Binary Interface (EABI)
    219 calling convention.  Documentation for EABI is available by sending
    220 a message with a subject line of "EABI" to eabi@goth.sis.mot.com.
     218RTEMS supports the Embedded Application Binary Interface (EABI) calling
     219convention.  Documentation for EABI is available by sending a message with a
     220subject line of "EABI" to eabi@goth.sis.mot.com.
    221221
    222222Programming Model
    223223-----------------
    224224
    225 This section discusses the programming model for the
    226 PowerPC architecture.
     225This section discusses the programming model for the PowerPC architecture.
    227226
    228227Non-Floating Point Registers
     
    236235These registers are referred to as ``gpr0`` to ``gpr31``.
    237236
    238 Some of the registers serve defined roles in the EABI programming model.
    239 The following table describes the role of each of these registers:
    240 .. code:: c
    241 
    242     +---------------+----------------+------------------------------+
    243     | Register Name | Alternate Name |         Description          |
    244     +---------------+----------------+------------------------------+
    245     |      r1       |      sp        |         stack pointer        |
    246     +---------------+----------------+------------------------------+
    247     |               |                |  global pointer to the Small |
    248     |      r2       |      na        |     Constant Area (SDA2)     |
    249     +---------------+----------------+------------------------------+
    250     |    r3 - r12   |      na        | parameter and result passing |
    251     +---------------+----------------+------------------------------+
    252     |               |                |  global pointer to the Small |
    253     |      r13      |      na        |         Data Area (SDA)      |
    254     +---------------+----------------+------------------------------+
     237Some of the registers serve defined roles in the EABI programming model.  The
     238following table describes the role of each of these registers:
     239
     240+---------------+----------------+------------------------------+
     241| Register Name | Alternate Name |         Description          |
     242+---------------+----------------+------------------------------+
     243|      r1       |      sp        |         stack pointer        |
     244+---------------+----------------+------------------------------+
     245|               |                |  global pointer to the Small |
     246|      r2       |      na        |     Constant Area (SDA2)     |
     247+---------------+----------------+------------------------------+
     248|    r3 - r12   |      na        | parameter and result passing |
     249+---------------+----------------+------------------------------+
     250|               |                |  global pointer to the Small |
     251|      r13      |      na        |         Data Area (SDA)      |
     252+---------------+----------------+------------------------------+
    255253
    256254Floating Point Registers
    257255~~~~~~~~~~~~~~~~~~~~~~~~
    258256
    259 The PowerPC architecture includes thirty-two, sixty-four bit
    260 floating point registers.  All PowerPC floating point instructions
    261 interpret these registers as 32 double precision floating point registers,
    262 regardless of whether the processor has 64-bit or 32-bit implementation.
    263 
    264 The floating point status and control register (fpscr) records exceptions
    265 and the type of result generated by floating-point operations.
    266 Additionally, it controls the rounding mode of operations and allows the
    267 reporting of floating exceptions to be enabled or disabled.
     257The PowerPC architecture includes thirty-two, sixty-four bit floating point
     258registers.  All PowerPC floating point instructions interpret these registers
     259as 32 double precision floating point registers, regardless of whether the
     260processor has 64-bit or 32-bit implementation.
     261
     262The floating point status and control register (fpscr) records exceptions and
     263the type of result generated by floating-point operations.  Additionally, it
     264controls the rounding mode of operations and allows the reporting of floating
     265exceptions to be enabled or disabled.
    268266
    269267Special Registers
    270268~~~~~~~~~~~~~~~~~
    271269
    272 The PowerPC architecture includes a number of special registers
    273 which are critical to the programming model:
     270The PowerPC architecture includes a number of special registers which are
     271critical to the programming model:
    274272
    275273*Machine State Register*
    276274    The MSR contains the processor mode, power management mode, endian mode,
    277275    exception information, privilege level, floating point available and
    278     floating point excepiton mode, address translation information and
    279     the exception prefix.
     276    floating point excepiton mode, address translation information and the
     277    exception prefix.
    280278
    281279*Link Register*
    282280    The LR contains the return address after a function call.  This register
    283     must be saved before a subsequent subroutine call can be made.  The
    284     use of this register is discussed further in the *Call and Return
    285     Mechanism* section below.
     281    must be saved before a subsequent subroutine call can be made.  The use of
     282    this register is discussed further in the *Call and Return Mechanism*
     283    section below.
    286284
    287285*Count Register*
    288     The CTR contains the iteration variable for some loops.  It may also be used
    289     for indirect function calls and jumps.
     286    The CTR contains the iteration variable for some loops.  It may also be
     287    used for indirect function calls and jumps.
    290288
    291289Call and Return Mechanism
    292290-------------------------
    293291
    294 The PowerPC architecture supports a simple yet effective call
    295 and return mechanism.  A subroutine is invoked
    296 via the "branch and link" (``bl``) and
    297 "brank and link absolute" (``bla``)
    298 instructions.  This instructions place the return address
    299 in the Link Register (LR).  The callee returns to the caller by
    300 executing a "branch unconditional to the link register" (``blr``)
    301 instruction.  Thus the callee returns to the caller via a jump
    302 to the return address which is stored in the LR.
    303 
    304 The previous contents of the LR are not automatically saved
    305 by either the ``bl`` or ``bla``.  It is the responsibility
    306 of the callee to save the contents of the LR before invoking
    307 another subroutine.  If the callee invokes another subroutine,
    308 it must restore the LR before executing the ``blr`` instruction
    309 to return to the caller.
    310 
    311 It is important to note that the PowerPC subroutine
    312 call and return mechanism does not automatically save and
    313 restore any registers.
    314 
    315 The LR may be accessed as special purpose register 8 (``SPR8``) using the
    316 "move from special register" (``mfspr``) and
    317 "move to special register" (``mtspr``) instructions.
     292The PowerPC architecture supports a simple yet effective call and return
     293mechanism.  A subroutine is invoked via the "branch and link" (``bl``) and
     294"brank and link absolute" (``bla``) instructions.  This instructions place the
     295return address in the Link Register (LR).  The callee returns to the caller by
     296executing a "branch unconditional to the link register" (``blr``) instruction.
     297Thus the callee returns to the caller via a jump to the return address which is
     298stored in the LR.
     299
     300The previous contents of the LR are not automatically saved by either the
     301``bl`` or ``bla``.  It is the responsibility of the callee to save the contents
     302of the LR before invoking another subroutine.  If the callee invokes another
     303subroutine, it must restore the LR before executing the ``blr`` instruction to
     304return to the caller.
     305
     306It is important to note that the PowerPC subroutine call and return mechanism
     307does not automatically save and restore any registers.
     308
     309The LR may be accessed as special purpose register 8 (``SPR8``) using the "move
     310from special register" (``mfspr``) and "move to special register" (``mtspr``)
     311instructions.
    318312
    319313Calling Mechanism
    320314-----------------
    321315
    322 All RTEMS directives are invoked using the regular
    323 PowerPC EABI calling convention via the ``bl`` or``bla`` instructions.
     316All RTEMS directives are invoked using the regular PowerPC EABI calling
     317convention via the ``bl`` or``bla`` instructions.
    324318
    325319Register Usage
    326320--------------
    327321
    328 As discussed above, the call instruction does not
    329 automatically save any registers.  It is the responsibility
    330 of the callee to save and restore any registers which must be preserved
    331 across subroutine calls.  The callee is responsible for saving
    332 callee-preserved registers to the program stack and restoring them
    333 before returning to the caller.
     322As discussed above, the call instruction does not automatically save any
     323registers.  It is the responsibility of the callee to save and restore any
     324registers which must be preserved across subroutine calls.  The callee is
     325responsible for saving callee-preserved registers to the program stack and
     326restoring them before returning to the caller.
    334327
    335328Parameter Passing
    336329-----------------
    337330
    338 RTEMS assumes that arguments are placed in the
    339 general purpose registers with the first argument in
    340 register 3 (``r3``), the second argument in general purpose
    341 register 4 (``r4``), and so forth until the seventh
    342 argument is in general purpose register 10 (``r10``).
    343 If there are more than seven arguments, then subsequent arguments
    344 are placed on the program stack.  The following pseudo-code
    345 illustrates the typical sequence used to call a RTEMS directive
     331RTEMS assumes that arguments are placed in the general purpose registers with
     332the first argument in register 3 (``r3``), the second argument in general
     333purpose register 4 (``r4``), and so forth until the seventh argument is in
     334general purpose register 10 (``r10``).  If there are more than seven arguments,
     335then subsequent arguments are placed on the program stack.  The following
     336pseudo-code illustrates the typical sequence used to call a RTEMS directive
    346337with three (3) arguments:
    347 .. code:: c
     338
     339.. code-block:: c
    348340
    349341    load third argument into r5
     
    358350-----------------
    359351
    360 The PowerPC architecture supports a variety of memory models.
    361 RTEMS supports the PowerPC using a flat memory model with
    362 paging disabled.  In this mode, the PowerPC automatically
    363 converts every address from a logical to a physical address
    364 each time it is used.  The PowerPC uses information provided
    365 in the Block Address Translation (BAT) to convert these addresses.
    366 
    367 Implementations of the PowerPC architecture may be thirty-two or sixty-four bit.
    368 The PowerPC architecture supports a flat thirty-two or sixty-four bit address
    369 space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
    370 gigabytes) in thirty-two bit implementations or to 0xFFFFFFFFFFFFFFFF
    371 in sixty-four bit implementations.  Each address is represented
    372 by either a thirty-two bit or sixty-four bit value and is byte addressable.
    373 The address may be used to reference a single byte, half-word
    374 (2-bytes), word (4 bytes), or in sixty-four bit implementations a
    375 doubleword (8 bytes).  Memory accesses within the address space are
    376 performed in big or little endian fashion by the PowerPC based
    377 upon the current setting of the Little-endian mode enable bit (LE)
    378 in the Machine State Register (MSR).  While the processor is in
    379 big endian mode, memory accesses which are not properly aligned
    380 generate an "alignment exception" (vector offset 0x00600).  In
    381 little endian mode, the PowerPC architecture does not require
    382 the processor to generate alignment exceptions.
    383 
    384 The following table lists the alignment requirements for a variety
    385 of data accesses:
    386 
    387 .. code:: c
    388 
    389     +--------------+-----------------------+
    390     |   Data Type  | Alignment Requirement |
    391     +--------------+-----------------------+
    392     |     byte     |          1            |
    393     |   half-word  |          2            |
    394     |     word     |          4            |
    395     |  doubleword  |          8            |
    396     +--------------+-----------------------+
    397 
    398 Doubleword load and store operations are only available in
    399 PowerPC CPU models which are sixty-four bit implementations.
    400 
    401 RTEMS does not directly support any PowerPC Memory Management
    402 Units, therefore, virtual memory or segmentation systems
    403 involving the PowerPC  are not supported.
    404 
    405 .. COMMENT: COPYRIGHT (c) 1989-2007.
    406 
    407 .. COMMENT: On-Line Applications Research Corporation (OAR).
    408 
    409 .. COMMENT: All rights reserved.
     352The PowerPC architecture supports a variety of memory models.  RTEMS supports
     353the PowerPC using a flat memory model with paging disabled.  In this mode, the
     354PowerPC automatically converts every address from a logical to a physical
     355address each time it is used.  The PowerPC uses information provided in the
     356Block Address Translation (BAT) to convert these addresses.
     357
     358Implementations of the PowerPC architecture may be thirty-two or sixty-four
     359bit.  The PowerPC architecture supports a flat thirty-two or sixty-four bit
     360address space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
     361gigabytes) in thirty-two bit implementations or to 0xFFFFFFFFFFFFFFFF in
     362sixty-four bit implementations.  Each address is represented by either a
     363thirty-two bit or sixty-four bit value and is byte addressable.  The address
     364may be used to reference a single byte, half-word (2-bytes), word (4 bytes), or
     365in sixty-four bit implementations a doubleword (8 bytes).  Memory accesses
     366within the address space are performed in big or little endian fashion by the
     367PowerPC based upon the current setting of the Little-endian mode enable bit
     368(LE) in the Machine State Register (MSR).  While the processor is in big endian
     369mode, memory accesses which are not properly aligned generate an "alignment
     370exception" (vector offset 0x00600).  In little endian mode, the PowerPC
     371architecture does not require the processor to generate alignment exceptions.
     372
     373The following table lists the alignment requirements for a variety of data
     374accesses:
     375
     376+--------------+-----------------------+
     377|   Data Type  | Alignment Requirement |
     378+--------------+-----------------------+
     379|     byte     |          1            |
     380|   half-word  |          2            |
     381|     word     |          4            |
     382|  doubleword  |          8            |
     383+--------------+-----------------------+
     384
     385Doubleword load and store operations are only available in PowerPC CPU models
     386which are sixty-four bit implementations.
     387
     388RTEMS does not directly support any PowerPC Memory Management Units, therefore,
     389virtual memory or segmentation systems involving the PowerPC are not supported.
    410390
    411391Interrupt Processing
    412392====================
    413393
    414 Although RTEMS hides many of the processor dependent
    415 details of interrupt processing, it is important to understand
    416 how the RTEMS interrupt manager is mapped onto the processor's
    417 unique architecture. Discussed in this chapter are the PowerPC's
    418 interrupt response and control mechanisms as they pertain to
     394Although RTEMS hides many of the processor dependent details of interrupt
     395processing, it is important to understand how the RTEMS interrupt manager is
     396mapped onto the processor's unique architecture. Discussed in this chapter are
     397the PowerPC's interrupt response and control mechanisms as they pertain to
    419398RTEMS.
    420399
    421 RTEMS and associated documentation uses the terms interrupt and vector.
    422 In the PowerPC architecture, these terms correspond to exception and
    423 exception handler, respectively.  The terms will be used interchangeably
    424 in this manual.
     400RTEMS and associated documentation uses the terms interrupt and vector.  In the
     401PowerPC architecture, these terms correspond to exception and exception
     402handler, respectively.  The terms will be used interchangeably in this manual.
    425403
    426404Synchronous Versus Asynchronous Exceptions
    427405------------------------------------------
    428406
    429 In the PowerPC architecture exceptions can be either precise or
    430 imprecise and either synchronous or asynchronous.  Asynchronous
    431 exceptions occur when an external event interrupts the processor.
    432 Synchronous exceptions are caused by the actions of an
    433 instruction. During an exception SRR0 is used to calculate where
    434 instruction processing should resume.  All instructions prior to
    435 the resume instruction will have completed execution.  SRR1 is used to
    436 store the machine status.
    437 
    438 There are two asynchronous nonmaskable, highest-priority exceptions
    439 system reset and machine check.  There are two asynchrononous maskable
    440 low-priority exceptions external interrupt and decrementer.  Nonmaskable
    441 execptions are never delayed, therefore if two nonmaskable, asynchronous
    442 exceptions occur in immediate succession, the state information saved by
    443 the first exception may be overwritten when the subsequent exception occurs.
    444 
    445 The PowerPC arcitecure defines one imprecise exception, the imprecise
    446 floating point enabled exception.  All other synchronous exceptions are
    447 precise.  The synchronization occuring during asynchronous precise
    448 exceptions conforms to the requirements for context synchronization.
     407In the PowerPC architecture exceptions can be either precise or imprecise and
     408either synchronous or asynchronous.  Asynchronous exceptions occur when an
     409external event interrupts the processor.  Synchronous exceptions are caused by
     410the actions of an instruction. During an exception SRR0 is used to calculate
     411where instruction processing should resume.  All instructions prior to the
     412resume instruction will have completed execution.  SRR1 is used to store the
     413machine status.
     414
     415There are two asynchronous nonmaskable, highest-priority exceptions system
     416reset and machine check.  There are two asynchrononous maskable low-priority
     417exceptions external interrupt and decrementer.  Nonmaskable execptions are
     418never delayed, therefore if two nonmaskable, asynchronous exceptions occur in
     419immediate succession, the state information saved by the first exception may be
     420overwritten when the subsequent exception occurs.
     421
     422The PowerPC arcitecure defines one imprecise exception, the imprecise floating
     423point enabled exception.  All other synchronous exceptions are precise.  The
     424synchronization occuring during asynchronous precise exceptions conforms to the
     425requirements for context synchronization.
    449426
    450427Vectoring of Interrupt Handler
     
    456433- an instruction address is loaded into SRR0
    457434
    458 - bits 33-36 and 42-47 of SRR1 are loaded with information
    459   specific to the exception.
    460 
    461 - bits 0-32, 37-41, and 48-63 of SRR1 are loaded with corresponding
    462   bits from the MSR.
     435- bits 33-36 and 42-47 of SRR1 are loaded with information specific to the
     436  exception.
     437
     438- bits 0-32, 37-41, and 48-63 of SRR1 are loaded with corresponding bits from
     439  the MSR.
    463440
    464441- the MSR is set based upon the exception type.
    465442
    466 - instruction fetch and execution resumes, using the new MSR value, at a location specific to the execption type.
    467 
    468 If the interrupt handler was installed as an RTEMS
    469 interrupt handler, then upon receipt of the interrupt, the
    470 processor passes control to the RTEMS interrupt handler which
    471 performs the following actions:
     443- instruction fetch and execution resumes, using the new MSR value, at a
     444  location specific to the execption type.
     445
     446If the interrupt handler was installed as an RTEMS interrupt handler, then upon
     447receipt of the interrupt, the processor passes control to the RTEMS interrupt
     448handler which performs the following actions:
    472449
    473450- saves the state of the interrupted task on it's stack,
    474451
    475 - saves all registers which are not normally preserved
    476   by the calling sequence so the user's interrupt service
    477   routine can be written in a high-level language.
    478 
    479 - if this is the outermost (i.e. non-nested) interrupt,
    480   then the RTEMS interrupt handler switches from the current stack
    481   to the interrupt stack,
     452- saves all registers which are not normally preserved by the calling sequence
     453  so the user's interrupt service routine can be written in a high-level
     454  language.
     455
     456- if this is the outermost (i.e. non-nested) interrupt, then the RTEMS
     457  interrupt handler switches from the current stack to the interrupt stack,
    482458
    483459- enables exceptions,
     
    485461- invokes the vectors to a user interrupt service routine (ISR).
    486462
    487 Asynchronous interrupts are ignored while exceptions are
    488 disabled.  Synchronous interrupts which occur while are
    489 disabled result in the CPU being forced into an error mode.
    490 
    491 A nested interrupt is processed similarly with the
    492 exception that the current stack need not be switched to the
    493 interrupt stack.
     463Asynchronous interrupts are ignored while exceptions are disabled.  Synchronous
     464interrupts which occur while are disabled result in the CPU being forced into
     465an error mode.
     466
     467A nested interrupt is processed similarly with the exception that the current
     468stack need not be switched to the interrupt stack.
    494469
    495470Interrupt Levels
    496471----------------
    497472
    498 The PowerPC architecture supports only a single external
    499 asynchronous interrupt source.  This interrupt source
    500 may be enabled and disabled via the External Interrupt Enable (EE)
    501 bit in the Machine State Register (MSR).  Thus only two level (enabled
    502 and disabled) of external device interrupt priorities are
     473The PowerPC architecture supports only a single external asynchronous interrupt
     474source.  This interrupt source may be enabled and disabled via the External
     475Interrupt Enable (EE) bit in the Machine State Register (MSR).  Thus only two
     476level (enabled and disabled) of external device interrupt priorities are
    503477directly supported by the PowerPC architecture.
    504478
    505 Some PowerPC implementations include a Critical Interrupt capability
    506 which is often used to receive interrupts from high priority external
    507 devices.
    508 
    509 The RTEMS interrupt level mapping scheme for the PowerPC is not
    510 a numeric level as on most RTEMS ports.  It is a bit mapping in
    511 which the least three significiant bits of the interrupt level
    512 are mapped directly to the enabling of specific interrupt
    513 sources as follows:
     479Some PowerPC implementations include a Critical Interrupt capability which is
     480often used to receive interrupts from high priority external devices.
     481
     482The RTEMS interrupt level mapping scheme for the PowerPC is not a numeric level
     483as on most RTEMS ports.  It is a bit mapping in which the least three
     484significiant bits of the interrupt level are mapped directly to the enabling of
     485specific interrupt sources as follows:
    514486
    515487*Critical Interrupt*
    516     Setting bit 0 (the least significant bit) of the interrupt level
    517     enables the Critical Interrupt source, if it is available on this
    518     CPU model.
     488    Setting bit 0 (the least significant bit) of the interrupt level enables
     489    the Critical Interrupt source, if it is available on this CPU model.
    519490
    520491*Machine Check*
     
    529500==============================
    530501
    531 The default fatal error handler for this architecture performs the
    532 following actions:
     502The default fatal error handler for this architecture performs the following
     503actions:
    533504
    534505- places the error code in r3, and
     
    559530------------
    560531
    561 An RTEMS based application is initiated or
    562 re-initiated when the PowerPC processor is reset.  The PowerPC
    563 architecture defines a Reset Exception, but leaves the
    564 details of the CPU state as implementation specific.  Please
    565 refer to the User's Manual for the CPU model in question.
    566 
    567 In general, at power-up the PowerPC begin execution at address
    568 0xFFF00100 in supervisor mode with all exceptions disabled.  For
    569 soft resets, the CPU will vector to either 0xFFF00100 or 0x00000100
    570 depending upon the setting of the Exception Prefix bit in the MSR.
    571 If during a soft reset, a Machine Check Exception occurs, then the
    572 CPU may execute a hard reset.
     532An RTEMS based application is initiated or re-initiated when the PowerPC
     533processor is reset.  The PowerPC architecture defines a Reset Exception, but
     534leaves the details of the CPU state as implementation specific.  Please refer
     535to the User's Manual for the CPU model in question.
     536
     537In general, at power-up the PowerPC begin execution at address 0xFFF00100 in
     538supervisor mode with all exceptions disabled.  For soft resets, the CPU will
     539vector to either 0xFFF00100 or 0x00000100 depending upon the setting of the
     540Exception Prefix bit in the MSR.  If during a soft reset, a Machine Check
     541Exception occurs, then the CPU may execute a hard reset.
    573542
    574543Processor Initialization
    575544------------------------
    576545
    577 If this PowerPC implementation supports on-chip caching
    578 and this is to be utilized, then it should be enabled during the
    579 reset application initialization code.  On-chip caching has been
    580 observed to prevent some emulators from working properly, so it
    581 may be necessary to run with caching disabled to use these emulators.
    582 
    583 In addition to the requirements described in the*Board Support Packages* chapter of the RTEMS C
    584 Applications User's Manual for the reset code
    585 which is executed before the call to ``rtems_initialize_executive``,
    586 the PowrePC version has the following specific requirements:
    587 
    588 - Must leave the PR bit of the Machine State Register (MSR) set
    589   to 0 so the PowerPC remains in the supervisor state.
    590 
    591 - Must set stack pointer (sp or r1) such that a minimum stack
    592   size of MINIMUM_STACK_SIZE bytes is provided for the RTEMS initialization
    593   sequence.
    594 
    595 - Must disable all external interrupts (i.e. clear the EI (EE)
    596   bit of the machine state register).
    597 
    598 - Must enable traps so window overflow and underflow
    599   conditions can be properly handled.
    600 
    601 - Must initialize the PowerPC's initial Exception Table with default
    602   handlers.
    603 
    604 .. COMMENT: COPYRIGHT (c) 1988-2002.
    605 
    606 .. COMMENT: On-Line Applications Research Corporation (OAR).
    607 
    608 .. COMMENT: All rights reserved.
    609 
     546If this PowerPC implementation supports on-chip caching and this is to be
     547utilized, then it should be enabled during the reset application initialization
     548code.  On-chip caching has been observed to prevent some emulators from working
     549properly, so it may be necessary to run with caching disabled to use these
     550emulators.
     551
     552In addition to the requirements described in the*Board Support Packages*
     553chapter of the RTEMS C Applications User's Manual for the reset code which is
     554executed before the call to ``rtems_initialize_executive``, the PowrePC version
     555has the following specific requirements:
     556
     557- Must leave the PR bit of the Machine State Register (MSR) set to 0 so the
     558  PowerPC remains in the supervisor state.
     559
     560- Must set stack pointer (sp or r1) such that a minimum stack size of
     561  MINIMUM_STACK_SIZE bytes is provided for the RTEMS initialization sequence.
     562
     563- Must disable all external interrupts (i.e. clear the EI (EE) bit of the
     564  machine state register).
     565
     566- Must enable traps so window overflow and underflow conditions can be properly
     567  handled.
     568
     569- Must initialize the PowerPC's initial Exception Table with default handlers.
  • cpu_supplement/preface.rst

    re6fe68d rf233256  
    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=======
     
    59=======
    610
     11The Real Time Executive for Multiprocessor Systems (RTEMS) is designed to be
     12portable across multiple processor architectures.  However, the nature of
     13real-time systems makes it essential that the application designer understand
     14certain processor dependent implementation details.  These processor
     15dependencies include calling convention, board support package issues,
     16interrupt processing, exact RTEMS memory requirements, performance data, header
     17files, and the assembly language interface to the executive.
    718
    8 The Real Time Executive for Multiprocessor Systems
    9 (RTEMS) is designed to be portable across multiple processor
    10 architectures.  However, the nature of real-time systems makes
    11 it essential that the application designer understand certain
    12 processor dependent implementation details.  These processor
    13 dependencies include calling convention, board support package
    14 issues, interrupt processing, exact RTEMS memory requirements,
    15 performance data, header files, and the assembly language
    16 interface to the executive.
     19Each architecture represents a CPU family and usually there are a wide variety
     20of CPU models within it.  These models share a common Instruction Set
     21Architecture (ISA) which often varies based upon some well-defined rules.
     22There are often multiple implementations of the ISA and these may be from one
     23or multiple vendors.
    1724
    18 Each architecture represents a CPU family and usually there are
    19 a wide variety of CPU models within it.  These models share a
    20 common Instruction Set Architecture (ISA) which often varies
    21 based upon some well-defined rules.  There are often
    22 multiple implementations of the ISA and these may be from
    23 one or multiple vendors.
     25On top of variations in the ISA, there may also be variations which occur when
     26a CPU core implementation is combined with a set of peripherals to form a
     27system on chip.  For example, there are many ARM CPU models from numerous
     28semiconductor vendors and a wide variety of peripherals.  But at the ISA level,
     29they share a common compatibility.
    2430
    25 On top of variations in the ISA, there may also be variations
    26 which occur when a CPU core implementation is combined with
    27 a set of peripherals to form a system on chip.  For example,
    28 there are many ARM CPU models from numerous semiconductor
    29 vendors and a wide variety of peripherals.  But at the
    30 ISA level, they share a common compatibility.
     31RTEMS depends upon this core similarity across the CPU models and leverages
     32that to minimize the source code that is specific to any particular CPU core
     33implementation or CPU model.
    3134
    32 RTEMS depends upon this core similarity across the CPU models
    33 and leverages that to minimize the source code that is specific
    34 to any particular CPU core implementation or CPU model.
     35This manual is separate and distinct from the RTEMS Porting Guide.  That manual
     36is a guide on porting RTEMS to a new architecture.  This manual is focused on
     37the more mundane CPU architecture specific issues that may impact application
     38development.  For example, if you need to write a subroutine in assembly
     39language, it is critical to understand the calling conventions for the target
     40architecture.
    3541
    36 This manual is separate and distinct from the RTEMS Porting
    37 Guide.  That manual is a guide on porting RTEMS to a new
    38 architecture.  This manual is focused on the more mundane
    39 CPU architecture specific issues that may impact
    40 application development.  For example, if you need to write
    41 a subroutine in assembly language, it is critical to understand
    42 the calling conventions for the target architecture.
    43 
    44 The first chapter in this manual describes these issues
    45 in general terms.  In a sense, it is posing the questions
    46 one should be aware may need to be answered and understood
    47 when porting an RTEMS application to a new architecture.
    48 Each subsequent chapter gives the answers to those questions
    49 for a particular CPU architecture.
    50 
    51 .. COMMENT: COPYRIGHT (c) 1988-2002.
    52 
    53 .. COMMENT: On-Line Applications Research Corporation (OAR).
    54 
    55 .. COMMENT: All rights reserved.
    56 
     42The first chapter in this manual describes these issues in general terms.  In a
     43sense, it is posing the questions one should be aware may need to be answered
     44and understood when porting an RTEMS application to a new architecture.  Each
     45subsequent chapter gives the answers to those questions for a particular CPU
     46architecture.
  • cpu_supplement/renesas_m32c.rst

    re6fe68d rf233256  
    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
    37Renesas M32C Specific Information
     
    1317
    1418Thread-local storage is not implemented.
    15 
    16 .. COMMENT: COPYRIGHT (c) 1988-2002.
    17 
    18 .. COMMENT: On-Line Applications Research Corporation (OAR).
    19 
    20 .. COMMENT: All rights reserved.
    21 
  • cpu_supplement/sparc.rst

    re6fe68d rf233256  
    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
    37SPARC Specific Information
    48##########################
    59
    6 The Real Time Executive for Multiprocessor Systems
    7 (RTEMS) is designed to be portable across multiple processor
    8 architectures.  However, the nature of real-time systems makes
    9 it essential that the application designer understand certain
    10 processor dependent implementation details.  These processor
    11 dependencies include calling convention, board support package
    12 issues, interrupt processing, exact RTEMS memory requirements,
    13 performance data, header files, and the assembly language
    14 interface to the executive.
    15 
    16 This document discusses the SPARC architecture dependencies in this
    17 port of RTEMS.  This architectural port is for SPARC Version 7 and
     10The Real Time Executive for Multiprocessor Systems (RTEMS) is designed to be
     11portable across multiple processor architectures.  However, the nature of
     12real-time systems makes it essential that the application designer understand
     13certain processor dependent implementation details.  These processor
     14dependencies include calling convention, board support package issues,
     15interrupt processing, exact RTEMS memory requirements, performance data, header
     16files, and the assembly language interface to the executive.
     17
     18This document discusses the SPARC architecture dependencies in this port of
     19RTEMS.  This architectural port is for SPARC Version 7 and
    18208. Implementations for SPARC V9 are in the sparc64 target.
    1921
    20 It is highly recommended that the SPARC RTEMS
    21 application developer obtain and become familiar with the
    22 documentation for the processor being used as well as the
    23 specification for the revision of the SPARC architecture which
    24 corresponds to that processor.
     22It is highly recommended that the SPARC RTEMS application developer obtain and
     23become familiar with the documentation for the processor being used as well as
     24the specification for the revision of the SPARC architecture which corresponds
     25to that processor.
    2526
    2627**SPARC Architecture Documents**
    2728
    28 For information on the SPARC architecture, refer to
    29 the following documents available from SPARC International, Inc.
    30 (http://www.sparc.com):
     29For information on the SPARC architecture, refer to the following documents
     30available from SPARC International, Inc.  (http://www.sparc.com):
    3131
    3232- SPARC Standard Version 7.
     
    3636**ERC32 Specific Information**
    3737
    38 The European Space Agency's ERC32 is a three chip
    39 computing core implementing a SPARC V7 processor and associated
    40 support circuitry for embedded space applications. The integer
    41 and floating-point units (90C601E & 90C602E) are based on the
    42 Cypress 7C601 and 7C602, with additional error-detection and
    43 recovery functions. The memory controller (MEC) implements
    44 system support functions such as address decoding, memory
    45 interface, DMA interface, UARTs, timers, interrupt control,
    46 write-protection, memory reconfiguration and error-detection.
    47 The core is designed to work at 25MHz, but using space qualified
    48 memories limits the system frequency to around 15 MHz, resulting
    49 in a performance of 10 MIPS and 2 MFLOPS.
    50 
    51 Information on the ERC32 and a number of development
    52 support tools, such as the SPARC Instruction Simulator (SIS),
    53 are freely available on the Internet.  The following documents
    54 and SIS are available via anonymous ftp or pointing your web
    55 browser at ftp://ftp.estec.esa.nl/pub/ws/wsd/erc32.
     38The European Space Agency's ERC32 is a three chip computing core implementing a
     39SPARC V7 processor and associated support circuitry for embedded space
     40applications. The integer and floating-point units (90C601E & 90C602E) are
     41based on the Cypress 7C601 and 7C602, with additional error-detection and
     42recovery functions. The memory controller (MEC) implements system support
     43functions such as address decoding, memory interface, DMA interface, UARTs,
     44timers, interrupt control, write-protection, memory reconfiguration and
     45error-detection.  The core is designed to work at 25MHz, but using space
     46qualified memories limits the system frequency to around 15 MHz, resulting in a
     47performance of 10 MIPS and 2 MFLOPS.
     48
     49Information on the ERC32 and a number of development support tools, such as the
     50SPARC Instruction Simulator (SIS), are freely available on the Internet.  The
     51following documents and SIS are available via anonymous ftp or pointing your
     52web browser at ftp://ftp.estec.esa.nl/pub/ws/wsd/erc32.
    5653
    5754- ERC32 System Design Document
     
    5956- MEC Device Specification
    6057
    61 Additionally, the SPARC RISC User's Guide from Matra
    62 MHS documents the functionality of the integer and floating
    63 point units including the instruction set information.  To
    64 obtain this document as well as ERC32 components and VHDL models
    65 contact:
    66 .. code:: c
     58Additionally, the SPARC RISC User's Guide from Matra MHS documents the
     59functionality of the integer and floating point units including the instruction
     60set information.  To obtain this document as well as ERC32 components and VHDL
     61models contact:
    6762
    6863    Matra MHS SA
     
    7570Amar Guennon (amar.guennon@matramhs.fr) is familiar with the ERC32.
    7671
    77 .. COMMENT: COPYRIGHT (c) 1988-2002.
    78 
    79 .. COMMENT: On-Line Applications Research Corporation (OAR).
    80 
    81 .. COMMENT: All rights reserved.
    82 
    8372CPU Model Dependent Features
    8473============================
    8574
    86 Microprocessors are generally classified into
    87 families with a variety of CPU models or implementations within
    88 that family.  Within a processor family, there is a high level
    89 of binary compatibility.  This family may be based on either an
    90 architectural specification or on maintaining compatibility with
    91 a popular processor.  Recent microprocessor families such as the
    92 SPARC or PowerPC are based on an architectural specification
    93 which is independent or any particular CPU model or
    94 implementation.  Older families such as the M68xxx and the iX86
    95 evolved as the manufacturer strived to produce higher
    96 performance processor models which maintained binary
    97 compatibility with older models.
    98 
    99 RTEMS takes advantage of the similarity of the
    100 various models within a CPU family.  Although the models do vary
    101 in significant ways, the high level of compatibility makes it
    102 possible to share the bulk of the CPU dependent executive code
    103 across the entire family.
     75Microprocessors are generally classified into families with a variety of CPU
     76models or implementations within that family.  Within a processor family, there
     77is a high level of binary compatibility.  This family may be based on either an
     78architectural specification or on maintaining compatibility with a popular
     79processor.  Recent microprocessor families such as the SPARC or PowerPC are
     80based on an architectural specification which is independent or any particular
     81CPU model or implementation.  Older families such as the M68xxx and the iX86
     82evolved as the manufacturer strived to produce higher performance processor
     83models which maintained binary compatibility with older models.
     84
     85RTEMS takes advantage of the similarity of the various models within a CPU
     86family.  Although the models do vary in significant ways, the high level of
     87compatibility makes it possible to share the bulk of the CPU dependent
     88executive code across the entire family.
    10489
    10590CPU Model Feature Flags
    10691-----------------------
    10792
    108 Each processor family supported by RTEMS has a
    109 list of features which vary between CPU models
    110 within a family.  For example, the most common model dependent
    111 feature regardless of CPU family is the presence or absence of a
    112 floating point unit or coprocessor.  When defining the list of
    113 features present on a particular CPU model, one simply notes
    114 that floating point hardware is or is not present and defines a
    115 single constant appropriately.  Conditional compilation is
    116 utilized to include the appropriate source code for this CPU
    117 model's feature set.  It is important to note that this means
    118 that RTEMS is thus compiled using the appropriate feature set
    119 and compilation flags optimal for this CPU model used.  The
    120 alternative would be to generate a binary which would execute on
    121 all family members using only the features which were always
     93Each processor family supported by RTEMS has a list of features which vary
     94between CPU models within a family.  For example, the most common model
     95dependent feature regardless of CPU family is the presence or absence of a
     96floating point unit or coprocessor.  When defining the list of features present
     97on a particular CPU model, one simply notes that floating point hardware is or
     98is not present and defines a single constant appropriately.  Conditional
     99compilation is utilized to include the appropriate source code for this CPU
     100model's feature set.  It is important to note that this means that RTEMS is
     101thus compiled using the appropriate feature set and compilation flags optimal
     102for this CPU model used.  The alternative would be to generate a binary which
     103would execute on all family members using only the features which were always
    122104present.
    123105
    124 This section presents the set of features which vary
    125 across SPARC implementations and are of importance to RTEMS.
    126 The set of CPU model feature macros are defined in the file
    127 cpukit/score/cpu/sparc/sparc.h based upon the particular CPU
    128 model defined on the compilation command line.
     106This section presents the set of features which vary across SPARC
     107implementations and are of importance to RTEMS.  The set of CPU model feature
     108macros are defined in the file cpukit/score/cpu/sparc/sparc.h based upon the
     109particular CPU model defined on the compilation command line.
    129110
    130111CPU Model Name
    131112~~~~~~~~~~~~~~
    132113
    133 The macro CPU_MODEL_NAME is a string which designates
    134 the name of this CPU model.  For example, for the European Space
    135 Agency's ERC32 SPARC model, this macro is set to the string
    136 "erc32".
     114The macro CPU_MODEL_NAME is a string which designates the name of this CPU
     115model.  For example, for the European Space Agency's ERC32 SPARC model, this
     116macro is set to the string "erc32".
    137117
    138118Floating Point Unit
    139119~~~~~~~~~~~~~~~~~~~
    140120
    141 The macro SPARC_HAS_FPU is set to 1 to indicate that
    142 this CPU model has a hardware floating point unit and 0
    143 otherwise.
     121The macro SPARC_HAS_FPU is set to 1 to indicate that this CPU model has a
     122hardware floating point unit and 0 otherwise.
    144123
    145124Bitscan Instruction
    146125~~~~~~~~~~~~~~~~~~~
    147126
    148 The macro SPARC_HAS_BITSCAN is set to 1 to indicate
    149 that this CPU model has the bitscan instruction.  For example,
    150 this instruction is supported by the Fujitsu SPARClite family.
     127The macro SPARC_HAS_BITSCAN is set to 1 to indicate that this CPU model has the
     128bitscan instruction.  For example, this instruction is supported by the Fujitsu
     129SPARClite family.
    151130
    152131Number of Register Windows
    153132~~~~~~~~~~~~~~~~~~~~~~~~~~
    154133
    155 The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to
    156 indicate the number of register window sets implemented by this
    157 CPU model.  The SPARC architecture allows a for a maximum of
    158 thirty-two register window sets although most implementations
    159 only include eight.
     134The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to indicate the number of
     135register window sets implemented by this CPU model.  The SPARC architecture
     136allows a for a maximum of thirty-two register window sets although most
     137implementations only include eight.
    160138
    161139Low Power Mode
    162140~~~~~~~~~~~~~~
    163141
    164 The macro SPARC_HAS_LOW_POWER_MODE is set to one to
    165 indicate that this CPU model has a low power mode.  If low power
    166 is enabled, then there must be CPU model specific implementation
    167 of the IDLE task in cpukit/score/cpu/sparc/cpu.c.  The low
    168 power mode IDLE task should be of the form:
    169 .. code:: c
     142The macro SPARC_HAS_LOW_POWER_MODE is set to one to indicate that this CPU
     143model has a low power mode.  If low power is enabled, then there must be CPU
     144model specific implementation of the IDLE task in cpukit/score/cpu/sparc/cpu.c.
     145The low power mode IDLE task should be of the form:
     146
     147.. code-block:: c
    170148
    171149    while ( TRUE ) {
    172     enter low power mode
     150        enter low power mode
    173151    }
    174152
     
    203181provided in erc32.h which promote the view that the two timers are completely
    204182independent.  By exclusively using these routines to access the Timer Control
    205 Register, the application can view the system as having a General Purpose
    206 Timer Control Register and a Real Time Clock Timer Control Register
    207 rather than the single shared value.
     183Register, the application can view the system as having a General Purpose Timer
     184Control Register and a Real Time Clock Timer Control Register rather than the
     185single shared value.
    208186
    209187The RTEMS Idle thread take advantage of the low power mode provided by the
     
    211189initialization time.
    212190
    213 .. COMMENT: COPYRIGHT (c) 1988-2002.
    214 
    215 .. COMMENT: On-Line Applications Research Corporation (OAR).
    216 
    217 .. COMMENT: All rights reserved.
    218 
    219191Calling Conventions
    220192===================
     
    222194Each high-level language compiler generates subroutine entry and exit code
    223195based upon a set of rules known as the application binary interface (ABI)
    224 calling convention.   These rules address the following issues:
     196calling convention.  These rules address the following issues:
    225197
    226198- register preservation and usage
     
    241213-----------------
    242214
    243 This section discusses the programming model for the
    244 SPARC architecture.
     215This section discusses the programming model for the SPARC architecture.
    245216
    246217Non-Floating Point Registers
    247218~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    248219
    249 The SPARC architecture defines thirty-two
    250 non-floating point registers directly visible to the programmer.
    251 These are divided into four sets:
     220The SPARC architecture defines thirty-two non-floating point registers directly
     221visible to the programmer.  These are divided into four sets:
    252222
    253223- input registers
     
    259229- global registers
    260230
    261 Each register is referred to by either two or three
    262 names in the SPARC reference manuals.  First, the registers are
    263 referred to as r0 through r31 or with the alternate notation
    264 r[0] through r[31].  Second, each register is a member of one of
    265 the four sets listed above.  Finally, some registers have an
    266 architecturally defined role in the programming model which
    267 provides an alternate name.  The following table describes the
    268 mapping between the 32 registers and the register sets:
    269 
    270 .. code:: c
    271 
    272     +-----------------+----------------+------------------+
    273     | Register Number | Register Names |   Description    |
    274     +-----------------+----------------+------------------+
    275     |     0 - 7       |    g0 - g7     | Global Registers |
    276     +-----------------+----------------+------------------+
    277     |     8 - 15      |    o0 - o7     | Output Registers |
    278     +-----------------+----------------+------------------+
    279     |    16 - 23      |    l0 - l7     | Local Registers  |
    280     +-----------------+----------------+------------------+
    281     |    24 - 31      |    i0 - i7     | Input Registers  |
    282     +-----------------+----------------+------------------+
    283 
    284 As mentioned above, some of the registers serve
    285 defined roles in the programming model.  The following table
    286 describes the role of each of these registers:
    287 
    288 .. code:: c
    289 
    290     +---------------+----------------+----------------------+
    291     | Register Name | Alternate Name |      Description     |
    292     +---------------+----------------+----------------------+
    293     |     g0        |      na        |    reads return 0    |
    294     |               |                |  writes are ignored  |
    295     +---------------+----------------+----------------------+
    296     |     o6        |      sp        |     stack pointer    |
    297     +---------------+----------------+----------------------+
    298     |     i6        |      fp        |     frame pointer    |
    299     +---------------+----------------+----------------------+
    300     |     i7        |      na        |    return address    |
    301     +---------------+----------------+----------------------+
     231Each register is referred to by either two or three names in the SPARC
     232reference manuals.  First, the registers are referred to as r0 through r31 or
     233with the alternate notation r[0] through r[31].  Second, each register is a
     234member of one of the four sets listed above.  Finally, some registers have an
     235architecturally defined role in the programming model which provides an
     236alternate name.  The following table describes the mapping between the 32
     237registers and the register sets:
     238
     239+-----------------+----------------+------------------+
     240| Register Number | Register Names |   Description    |
     241+-----------------+----------------+------------------+
     242|     0 - 7       |    g0 - g7     | Global Registers |
     243+-----------------+----------------+------------------+
     244|     8 - 15      |    o0 - o7     | Output Registers |
     245+-----------------+----------------+------------------+
     246|    16 - 23      |    l0 - l7     | Local Registers  |
     247+-----------------+----------------+------------------+
     248|    24 - 31      |    i0 - i7     | Input Registers  |
     249+-----------------+----------------+------------------+
     250
     251As mentioned above, some of the registers serve defined roles in the
     252programming model.  The following table describes the role of each of these
     253registers:
     254
     255+---------------+----------------+----------------------+
     256| Register Name | Alternate Name |      Description     |
     257+---------------+----------------+----------------------+
     258|     g0        |      na        |    reads return 0    |
     259|               |                |  writes are ignored  |
     260+---------------+----------------+----------------------+
     261|     o6        |      sp        |     stack pointer    |
     262+---------------+----------------+----------------------+
     263|     i6        |      fp        |     frame pointer    |
     264+---------------+----------------+----------------------+
     265|     i7        |      na        |    return address    |
     266+---------------+----------------+----------------------+
    302267
    303268The registers g2 through g4 are reserved for applications.  GCC uses them as
     
    316281~~~~~~~~~~~~~~~~~~~~~~~~
    317282
    318 The SPARC V7 architecture includes thirty-two,
    319 thirty-two bit registers.  These registers may be viewed as
    320 follows:
    321 
    322 - 32 single precision floating point or integer registers
    323   (f0, f1,  ... f31)
    324 
    325 - 16 double precision floating point registers (f0, f2,
    326   f4, ... f30)
    327 
    328 - 8 extended precision floating point registers (f0, f4,
    329   f8, ... f28)
    330 
    331 The floating point status register (FSR) specifies
    332 the behavior of the floating point unit for rounding, contains
    333 its condition codes, version specification, and trap information.
     283The SPARC V7 architecture includes thirty-two, thirty-two bit registers.  These
     284registers may be viewed as follows:
     285
     286- 32 single precision floating point or integer registers (f0, f1, ... f31)
     287
     288- 16 double precision floating point registers (f0, f2, f4, ... f30)
     289
     290- 8 extended precision floating point registers (f0, f4, f8, ... f28)
     291
     292The floating point status register (FSR) specifies the behavior of the floating
     293point unit for rounding, contains its condition codes, version specification,
     294and trap information.
    334295
    335296According to the ABI all floating point registers and the floating point status
    336 register (FSR) are volatile.  Thus the floating point context of a thread is the
    337 empty set.  The rounding direction is a system global state and must not be
     297register (FSR) are volatile.  Thus the floating point context of a thread is
     298the empty set.  The rounding direction is a system global state and must not be
    338299modified by threads.
    339300
    340 A queue of the floating point instructions which have
    341 started execution but not yet completed is maintained.  This
    342 queue is needed to support the multiple cycle nature of floating
    343 point operations and to aid floating point exception trap
    344 handlers.  Once a floating point exception has been encountered,
    345 the queue is frozen until it is emptied by the trap handler.
    346 The floating point queue is loaded by launching instructions.
    347 It is emptied normally when the floating point completes all
    348 outstanding instructions and by floating point exception
    349 handlers with the store double floating point queue (stdfq)
    350 instruction.
     301A queue of the floating point instructions which have started execution but not
     302yet completed is maintained.  This queue is needed to support the multiple
     303cycle nature of floating point operations and to aid floating point exception
     304trap handlers.  Once a floating point exception has been encountered, the queue
     305is frozen until it is emptied by the trap handler.  The floating point queue is
     306loaded by launching instructions.  It is emptied normally when the floating
     307point completes all outstanding instructions and by floating point exception
     308handlers with the store double floating point queue (stdfq) instruction.
    351309
    352310Special Registers
    353311~~~~~~~~~~~~~~~~~
    354312
    355 The SPARC architecture includes two special registers
    356 which are critical to the programming model: the Processor State
    357 Register (psr) and the Window Invalid Mask (wim).  The psr
    358 contains the condition codes, processor interrupt level, trap
    359 enable bit, supervisor mode and previous supervisor mode bits,
    360 version information, floating point unit and coprocessor enable
    361 bits, and the current window pointer (cwp).  The cwp field of
    362 the psr and wim register are used to manage the register windows
    363 in the SPARC architecture.  The register windows are discussed
    364 in more detail below.
     313The SPARC architecture includes two special registers which are critical to the
     314programming model: the Processor State Register (psr) and the Window Invalid
     315Mask (wim).  The psr contains the condition codes, processor interrupt level,
     316trap enable bit, supervisor mode and previous supervisor mode bits, version
     317information, floating point unit and coprocessor enable bits, and the current
     318window pointer (cwp).  The cwp field of the psr and wim register are used to
     319manage the register windows in the SPARC architecture.  The register windows
     320are discussed in more detail below.
    365321
    366322Register Windows
    367323----------------
    368324
    369 The SPARC architecture includes the concept of
    370 register windows.  An overly simplistic way to think of these
    371 windows is to imagine them as being an infinite supply of
    372 "fresh" register sets available for each subroutine to use.  In
    373 reality, they are much more complicated.
    374 
    375 The save instruction is used to obtain a new register
    376 window.  This instruction decrements the current window pointer,
    377 thus providing a new set of registers for use.  This register
    378 set includes eight fresh local registers for use exclusively by
    379 this subroutine.  When done with a register set, the restore
    380 instruction increments the current window pointer and the
    381 previous register set is once again available.
    382 
    383 The two primary issues complicating the use of
    384 register windows are that (1) the set of register windows is
    385 finite, and (2) some registers are shared between adjacent
    386 registers windows.
    387 
    388 Because the set of register windows is finite, it is
    389 possible to execute enough save instructions without
    390 corresponding restore's to consume all of the register windows.
    391 This is easily accomplished in a high level language because
    392 each subroutine typically performs a save instruction upon
    393 entry.  Thus having a subroutine call depth greater than the
    394 number of register windows will result in a window overflow
    395 condition.  The window overflow condition generates a trap which
    396 must be handled in software.  The window overflow trap handler
    397 is responsible for saving the contents of the oldest register
    398 window on the program stack.
    399 
    400 Similarly, the subroutines will eventually complete
    401 and begin to perform restore's.  If the restore results in the
    402 need for a register window which has previously been written to
    403 memory as part of an overflow, then a window underflow condition
    404 results.  Just like the window overflow, the window underflow
    405 condition must be handled in software by a trap handler.  The
    406 window underflow trap handler is responsible for reloading the
    407 contents of the register window requested by the restore
    408 instruction from the program stack.
    409 
    410 The Window Invalid Mask (wim) and the Current Window
    411 Pointer (cwp) field in the psr are used in conjunction to manage
    412 the finite set of register windows and detect the window
    413 overflow and underflow conditions.  The cwp contains the index
    414 of the register window currently in use.  The save instruction
    415 decrements the cwp modulo the number of register windows.
    416 Similarly, the restore instruction increments the cwp modulo the
    417 number of register windows.  Each bit in the  wim represents
    418 represents whether a register window contains valid information.
    419 The value of 0 indicates the register window is valid and 1
    420 indicates it is invalid.  When a save instruction causes the cwp
    421 to point to a register window which is marked as invalid, a
    422 window overflow condition results.  Conversely, the restore
    423 instruction may result in a window underflow condition.
    424 
    425 Other than the assumption that a register window is
    426 always available for trap (i.e. interrupt) handlers, the SPARC
    427 architecture places no limits on the number of register windows
    428 simultaneously marked as invalid (i.e. number of bits set in the
    429 wim).  However, RTEMS assumes that only one register window is
    430 marked invalid at a time (i.e. only one bit set in the wim).
    431 This makes the maximum possible number of register windows
    432 available to the user while still meeting the requirement that
    433 window overflow and underflow conditions can be detected.
    434 
    435 The window overflow and window underflow trap
    436 handlers are a critical part of the run-time environment for a
    437 SPARC application.  The SPARC architectural specification allows
    438 for the number of register windows to be any power of two less
    439 than or equal to 32.  The most common choice for SPARC
    440 implementations appears to be 8 register windows.  This results
    441 in the cwp ranging in value from 0 to 7 on most implementations.
    442 
    443 The second complicating factor is the sharing of
    444 registers between adjacent register windows.  While each
    445 register window has its own set of local registers, the input
    446 and output registers are shared between adjacent windows.  The
    447 output registers for register window N are the same as the input
    448 registers for register window ((N - 1) modulo RW) where RW is
    449 the number of register windows.  An alternative way to think of
    450 this is to remember how parameters are passed to a subroutine on
    451 the SPARC.  The caller loads values into what are its output
    452 registers.  Then after the callee executes a save instruction,
    453 those parameters are available in its input registers.  This is
    454 a very efficient way to pass parameters as no data is actually
    455 moved by the save or restore instructions.
     325The SPARC architecture includes the concept of register windows.  An overly
     326simplistic way to think of these windows is to imagine them as being an
     327infinite supply of "fresh" register sets available for each subroutine to use.
     328In reality, they are much more complicated.
     329
     330The save instruction is used to obtain a new register window.  This instruction
     331decrements the current window pointer, thus providing a new set of registers
     332for use.  This register set includes eight fresh local registers for use
     333exclusively by this subroutine.  When done with a register set, the restore
     334instruction increments the current window pointer and the previous register set
     335is once again available.
     336
     337The two primary issues complicating the use of register windows are that (1)
     338the set of register windows is finite, and (2) some registers are shared
     339between adjacent registers windows.
     340
     341Because the set of register windows is finite, it is possible to execute enough
     342save instructions without corresponding restore's to consume all of the
     343register windows.  This is easily accomplished in a high level language because
     344each subroutine typically performs a save instruction upon entry.  Thus having
     345a subroutine call depth greater than the number of register windows will result
     346in a window overflow condition.  The window overflow condition generates a trap
     347which must be handled in software.  The window overflow trap handler is
     348responsible for saving the contents of the oldest register window on the
     349program stack.
     350
     351Similarly, the subroutines will eventually complete and begin to perform
     352restore's.  If the restore results in the need for a register window which has
     353previously been written to memory as part of an overflow, then a window
     354underflow condition results.  Just like the window overflow, the window
     355underflow condition must be handled in software by a trap handler.  The window
     356underflow trap handler is responsible for reloading the contents of the
     357register window requested by the restore instruction from the program stack.
     358
     359The Window Invalid Mask (wim) and the Current Window Pointer (cwp) field in the
     360psr are used in conjunction to manage the finite set of register windows and
     361detect the window overflow and underflow conditions.  The cwp contains the
     362index of the register window currently in use.  The save instruction decrements
     363the cwp modulo the number of register windows.  Similarly, the restore
     364instruction increments the cwp modulo the number of register windows.  Each bit
     365in the wim represents represents whether a register window contains valid
     366information.  The value of 0 indicates the register window is valid and 1
     367indicates it is invalid.  When a save instruction causes the cwp to point to a
     368register window which is marked as invalid, a window overflow condition
     369results.  Conversely, the restore instruction may result in a window underflow
     370condition.
     371
     372Other than the assumption that a register window is always available for trap
     373(i.e. interrupt) handlers, the SPARC architecture places no limits on the
     374number of register windows simultaneously marked as invalid (i.e. number of
     375bits set in the wim).  However, RTEMS assumes that only one register window is
     376marked invalid at a time (i.e. only one bit set in the wim).  This makes the
     377maximum possible number of register windows available to the user while still
     378meeting the requirement that window overflow and underflow conditions can be
     379detected.
     380
     381The window overflow and window underflow trap handlers are a critical part of
     382the run-time environment for a SPARC application.  The SPARC architectural
     383specification allows for the number of register windows to be any power of two
     384less than or equal to 32.  The most common choice for SPARC implementations
     385appears to be 8 register windows.  This results in the cwp ranging in value
     386from 0 to 7 on most implementations.
     387
     388The second complicating factor is the sharing of registers between adjacent
     389register windows.  While each register window has its own set of local
     390registers, the input and output registers are shared between adjacent windows.
     391The output registers for register window N are the same as the input registers
     392for register window ((N - 1) modulo RW) where RW is the number of register
     393windows.  An alternative way to think of this is to remember how parameters are
     394passed to a subroutine on the SPARC.  The caller loads values into what are its
     395output registers.  Then after the callee executes a save instruction, those
     396parameters are available in its input registers.  This is a very efficient way
     397to pass parameters as no data is actually moved by the save or restore
     398instructions.
    456399
    457400Call and Return Mechanism
    458401-------------------------
    459402
    460 The SPARC architecture supports a simple yet
    461 effective call and return mechanism.  A subroutine is invoked
    462 via the call (call) instruction.  This instruction places the
    463 return address in the caller's output register 7 (o7).  After
    464 the callee executes a save instruction, this value is available
    465 in input register 7 (i7) until the corresponding restore
    466 instruction is executed.
    467 
    468 The callee returns to the caller via a jmp to the
    469 return address.  There is a delay slot following this
    470 instruction which is commonly used to execute a restore
    471 instruction - if a register window was allocated by this
    472 subroutine.
    473 
    474 It is important to note that the SPARC subroutine
    475 call and return mechanism does not automatically save and
    476 restore any registers.  This is accomplished via the save and
    477 restore instructions which manage the set of registers windows.
     403The SPARC architecture supports a simple yet effective call and return
     404mechanism.  A subroutine is invoked via the call (call) instruction.  This
     405instruction places the return address in the caller's output register 7 (o7).
     406After the callee executes a save instruction, this value is available in input
     407register 7 (i7) until the corresponding restore instruction is executed.
     408
     409The callee returns to the caller via a jmp to the return address.  There is a
     410delay slot following this instruction which is commonly used to execute a
     411restore instruction - if a register window was allocated by this subroutine.
     412
     413It is important to note that the SPARC subroutine call and return mechanism
     414does not automatically save and restore any registers.  This is accomplished
     415via the save and restore instructions which manage the set of registers
     416windows.
    478417
    479418In case a floating-point unit is supported, then floating-point return values
     
    486425-----------------
    487426
    488 All RTEMS directives are invoked using the regular
    489 SPARC calling convention via the call instruction.
     427All RTEMS directives are invoked using the regular SPARC calling convention via
     428the call instruction.
    490429
    491430Register Usage
    492431--------------
    493432
    494 As discussed above, the call instruction does not
    495 automatically save any registers.  The save and restore
    496 instructions are used to allocate and deallocate register
    497 windows.  When a register window is allocated, the new set of
    498 local registers are available for the exclusive use of the
    499 subroutine which allocated this register set.
     433As discussed above, the call instruction does not automatically save any
     434registers.  The save and restore instructions are used to allocate and
     435deallocate register windows.  When a register window is allocated, the new set
     436of local registers are available for the exclusive use of the subroutine which
     437allocated this register set.
    500438
    501439Parameter Passing
    502440-----------------
    503441
    504 RTEMS assumes that arguments are placed in the
    505 caller's output registers with the first argument in output
    506 register 0 (o0), the second argument in output register 1 (o1),
    507 and so forth.  Until the callee executes a save instruction, the
    508 parameters are still visible in the output registers.  After the
    509 callee executes a save instruction, the parameters are visible
    510 in the corresponding input registers.  The following pseudo-code
    511 illustrates the typical sequence used to call a RTEMS directive
    512 with three (3) arguments:
    513 .. code:: c
     442RTEMS assumes that arguments are placed in the caller's output registers with
     443the first argument in output register 0 (o0), the second argument in output
     444register 1 (o1), and so forth.  Until the callee executes a save instruction,
     445the parameters are still visible in the output registers.  After the callee
     446executes a save instruction, the parameters are visible in the corresponding
     447input registers.  The following pseudo-code illustrates the typical sequence
     448used to call a RTEMS directive with three (3) arguments:
     449
     450.. code-block:: c
    514451
    515452    load third argument into o2
     
    521458----------------------
    522459
    523 All user-provided routines invoked by RTEMS, such as
    524 user extensions, device drivers, and MPCI routines, must also
    525 adhere to these calling conventions.
    526 
    527 .. COMMENT: COPYRIGHT (c) 1988-2002.
    528 
    529 .. COMMENT: On-Line Applications Research Corporation (OAR).
    530 
    531 .. COMMENT: All rights reserved.
     460All user-provided routines invoked by RTEMS, such as user extensions, device
     461drivers, and MPCI routines, must also adhere to these calling conventions.
    532462
    533463Memory Model
    534464============
    535465
    536 A processor may support any combination of memory
    537 models ranging from pure physical addressing to complex demand
    538 paged virtual memory systems.  RTEMS supports a flat memory
    539 model which ranges contiguously over the processor's allowable
    540 address space.  RTEMS does not support segmentation or virtual
    541 memory of any kind.  The appropriate memory model for RTEMS
    542 provided by the targeted processor and related characteristics
    543 of that model are described in this chapter.
     466A processor may support any combination of memory models ranging from pure
     467physical addressing to complex demand paged virtual memory systems.  RTEMS
     468supports a flat memory model which ranges contiguously over the processor's
     469allowable address space.  RTEMS does not support segmentation or virtual memory
     470of any kind.  The appropriate memory model for RTEMS provided by the targeted
     471processor and related characteristics of that model are described in this
     472chapter.
    544473
    545474Flat Memory Model
    546475-----------------
    547476
    548 The SPARC architecture supports a flat 32-bit address
    549 space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
    550 gigabytes).  Each address is represented by a 32-bit value and
    551 is byte addressable.  The address may be used to reference a
    552 single byte, half-word (2-bytes), word (4 bytes), or doubleword
    553 (8 bytes).  Memory accesses within this address space are
    554 performed in big endian fashion by the SPARC.  Memory accesses
    555 which are not properly aligned generate a "memory address not
    556 aligned" trap (type number 7).  The following table lists the
    557 alignment requirements for a variety of data accesses:
    558 
    559 .. code:: c
     477The SPARC architecture supports a flat 32-bit address space with addresses
     478ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is
     479represented by a 32-bit value and is byte addressable.  The address may be used
     480to reference a single byte, half-word (2-bytes), word (4 bytes), or doubleword
     481(8 bytes).  Memory accesses within this address space are performed in big
     482endian fashion by the SPARC.  Memory accesses which are not properly aligned
     483generate a "memory address not aligned" trap (type number 7).  The following
     484table lists the alignment requirements for a variety of data accesses:
    560485
    561486    +--------------+-----------------------+
     
    568493    +--------------+-----------------------+
    569494
    570 Doubleword load and store operations must use a pair
    571 of registers as their source or destination.  This pair of
    572 registers must be an adjacent pair of registers with the first
    573 of the pair being even numbered.  For example, a valid
    574 destination for a doubleword load might be input registers 0 and
    575 1 (i0 and i1).  The pair i1 and i2 would be invalid.  \[NOTE:
    576 Some assemblers for the SPARC do not generate an error if an odd
    577 numbered register is specified as the beginning register of the
    578 pair.  In this case, the assembler assumes that what the
    579 programmer meant was to use the even-odd pair which ends at the
    580 specified register.  This may or may not have been a correct
    581 assumption.]
    582 
    583 RTEMS does not support any SPARC Memory Management
    584 Units, therefore, virtual memory or segmentation systems
    585 involving the SPARC are not supported.
    586 
    587 .. COMMENT: COPYRIGHT (c) 1988-2002.
    588 
    589 .. COMMENT: On-Line Applications Research Corporation (OAR).
    590 
    591 .. COMMENT: All rights reserved.
     495Doubleword load and store operations must use a pair of registers as their
     496source or destination.  This pair of registers must be an adjacent pair of
     497registers with the first of the pair being even numbered.  For example, a valid
     498destination for a doubleword load might be input registers 0 and 1 (i0 and i1).
     499The pair i1 and i2 would be invalid.  \[NOTE: Some assemblers for the SPARC do
     500not generate an error if an odd numbered register is specified as the beginning
     501register of the pair.  In this case, the assembler assumes that what the
     502programmer meant was to use the even-odd pair which ends at the specified
     503register.  This may or may not have been a correct assumption.]
     504
     505RTEMS does not support any SPARC Memory Management Units, therefore, virtual
     506memory or segmentation systems involving the SPARC are not supported.
    592507
    593508Interrupt Processing
    594509====================
    595510
    596 Different types of processors respond to the
    597 occurrence of an interrupt in its own unique fashion. In
    598 addition, each processor type provides a control mechanism to
    599 allow for the proper handling of an interrupt.  The processor
    600 dependent response to the interrupt modifies the current
    601 execution state and results in a change in the execution stream.
    602 Most processors require that an interrupt handler utilize some
    603 special control mechanisms to return to the normal processing
    604 stream.  Although RTEMS hides many of the processor dependent
    605 details of interrupt processing, it is important to understand
    606 how the RTEMS interrupt manager is mapped onto the processor's
    607 unique architecture. Discussed in this chapter are the SPARC's
    608 interrupt response and control mechanisms as they pertain to
    609 RTEMS.
    610 
    611 RTEMS and associated documentation uses the terms
    612 interrupt and vector.  In the SPARC architecture, these terms
    613 correspond to traps and trap type, respectively.  The terms will
    614 be used interchangeably in this manual.
     511Different types of processors respond to the occurrence of an interrupt in its
     512own unique fashion. In addition, each processor type provides a control
     513mechanism to allow for the proper handling of an interrupt.  The processor
     514dependent response to the interrupt modifies the current execution state and
     515results in a change in the execution stream.  Most processors require that an
     516interrupt handler utilize some special control mechanisms to return to the
     517normal processing stream.  Although RTEMS hides many of the processor dependent
     518details of interrupt processing, it is important to understand how the RTEMS
     519interrupt manager is mapped onto the processor's unique architecture. Discussed
     520in this chapter are the SPARC's interrupt response and control mechanisms as
     521they pertain to RTEMS.
     522
     523RTEMS and associated documentation uses the terms interrupt and vector.  In the
     524SPARC architecture, these terms correspond to traps and trap type,
     525respectively.  The terms will be used interchangeably in this manual.
    615526
    616527Synchronous Versus Asynchronous Traps
    617528-------------------------------------
    618529
    619 The SPARC architecture includes two classes of traps:
    620 synchronous and asynchronous.  Asynchronous traps occur when an
    621 external event interrupts the processor.  These traps are not
    622 associated with any instruction executed by the processor and
    623 logically occur between instructions.  The instruction currently
    624 in the execute stage of the processor is allowed to complete
    625 although subsequent instructions are annulled.  The return
    626 address reported by the processor for asynchronous traps is the
    627 pair of instructions following the current instruction.
    628 
    629 Synchronous traps are caused by the actions of an
    630 instruction.  The trap stimulus in this case either occurs
    631 internally to the processor or is from an external signal that
    632 was provoked by the instruction.  These traps are taken
    633 immediately and the instruction that caused the trap is aborted
    634 before any state changes occur in the processor itself.   The
    635 return address reported by the processor for synchronous traps
    636 is the instruction which caused the trap and the following
    637 instruction.
     530The SPARC architecture includes two classes of traps: synchronous and
     531asynchronous.  Asynchronous traps occur when an external event interrupts the
     532processor.  These traps are not associated with any instruction executed by the
     533processor and logically occur between instructions.  The instruction currently
     534in the execute stage of the processor is allowed to complete although
     535subsequent instructions are annulled.  The return address reported by the
     536processor for asynchronous traps is the pair of instructions following the
     537current instruction.
     538
     539Synchronous traps are caused by the actions of an instruction.  The trap
     540stimulus in this case either occurs internally to the processor or is from an
     541external signal that was provoked by the instruction.  These traps are taken
     542immediately and the instruction that caused the trap is aborted before any
     543state changes occur in the processor itself.  The return address reported by
     544the processor for synchronous traps is the instruction which caused the trap
     545and the following instruction.
    638546
    639547Vectoring of Interrupt Handler
    640548------------------------------
    641549
    642 Upon receipt of an interrupt the SPARC automatically
    643 performs the following actions:
     550Upon receipt of an interrupt the SPARC automatically performs the following
     551actions:
    644552
    645553- disables traps (sets the ET bit of the psr to 0),
    646554
    647 - the S bit of the psr is copied into the Previous
    648   Supervisor Mode (PS) bit of the psr,
    649 
    650 - the cwp is decremented by one (modulo the number of
    651   register windows) to activate a trap window,
    652 
    653 - the PC and nPC are loaded into local register 1 and 2
    654   (l0 and l1),
    655 
    656 - the trap type (tt) field of the Trap Base Register (TBR)
    657   is set to the appropriate value, and
    658 
    659 - if the trap is not a reset, then the PC is written with
    660   the contents of the TBR and the nPC is written with TBR + 4.  If
    661   the trap is a reset, then the PC is set to zero and the nPC is
    662   set to 4.
    663 
    664 Trap processing on the SPARC has two features which
    665 are noticeably different than interrupt processing on other
    666 architectures.  First, the value of psr register in effect
    667 immediately before the trap occurred is not explicitly saved.
    668 Instead only reversible alterations are made to it.  Second, the
    669 Processor Interrupt Level (pil) is not set to correspond to that
    670 of the interrupt being processed.  When a trap occurs, ALL
    671 subsequent traps are disabled.  In order to safely invoke a
    672 subroutine during trap handling, traps must be enabled to allow
    673 for the possibility of register window overflow and underflow
    674 traps.
    675 
    676 If the interrupt handler was installed as an RTEMS
    677 interrupt handler, then upon receipt of the interrupt, the
    678 processor passes control to the RTEMS interrupt handler which
    679 performs the following actions:
     555- the S bit of the psr is copied into the Previous Supervisor Mode (PS) bit of
     556  the psr,
     557
     558- the cwp is decremented by one (modulo the number of register windows) to
     559  activate a trap window,
     560
     561- the PC and nPC are loaded into local register 1 and 2 (l0 and l1),
     562
     563- the trap type (tt) field of the Trap Base Register (TBR) is set to the
     564  appropriate value, and
     565
     566- if the trap is not a reset, then the PC is written with the contents of the
     567  TBR and the nPC is written with TBR + 4.  If the trap is a reset, then the PC
     568  is set to zero and the nPC is set to 4.
     569
     570Trap processing on the SPARC has two features which are noticeably different
     571than interrupt processing on other architectures.  First, the value of psr
     572register in effect immediately before the trap occurred is not explicitly
     573saved.  Instead only reversible alterations are made to it.  Second, the
     574Processor Interrupt Level (pil) is not set to correspond to that of the
     575interrupt being processed.  When a trap occurs, ALL subsequent traps are
     576disabled.  In order to safely invoke a subroutine during trap handling, traps
     577must be enabled to allow for the possibility of register window overflow and
     578underflow traps.
     579
     580If the interrupt handler was installed as an RTEMS interrupt handler, then upon
     581receipt of the interrupt, the processor passes control to the RTEMS interrupt
     582handler which performs the following actions:
    680583
    681584- saves the state of the interrupted task on it's stack,
    682585
    683 - insures that a register window is available for
    684   subsequent traps,
    685 
    686 - if this is the outermost (i.e. non-nested) interrupt,
    687   then the RTEMS interrupt handler switches from the current stack
    688   to the interrupt stack,
     586- insures that a register window is available for subsequent traps,
     587
     588- if this is the outermost (i.e. non-nested) interrupt, then the RTEMS
     589  interrupt handler switches from the current stack to the interrupt stack,
    689590
    690591- enables traps,
     
    692593- invokes the vectors to a user interrupt service routine (ISR).
    693594
    694 Asynchronous interrupts are ignored while traps are
    695 disabled.  Synchronous traps which occur while traps are
    696 disabled result in the CPU being forced into an error mode.
    697 
    698 A nested interrupt is processed similarly with the
    699 exception that the current stack need not be switched to the
    700 interrupt stack.
     595Asynchronous interrupts are ignored while traps are disabled.  Synchronous
     596traps which occur while traps are disabled result in the CPU being forced into
     597an error mode.
     598
     599A nested interrupt is processed similarly with the exception that the current
     600stack need not be switched to the interrupt stack.
    701601
    702602Traps and Register Windows
    703603--------------------------
    704604
    705 One of the register windows must be reserved at all
    706 times for trap processing.  This is critical to the proper
    707 operation of the trap mechanism in the SPARC architecture.  It
    708 is the responsibility of the trap handler to insure that there
    709 is a register window available for a subsequent trap before
    710 re-enabling traps.  It is likely that any high level language
    711 routines invoked by the trap handler (such as a user-provided
    712 RTEMS interrupt handler) will allocate a new register window.
    713 The save operation could result in a window overflow trap.  This
    714 trap cannot be correctly processed unless (1) traps are enabled
    715 and (2) a register window is reserved for traps.  Thus, the
    716 RTEMS interrupt handler insures that a register window is
    717 available for subsequent traps before enabling traps and
    718 invoking the user's interrupt handler.
     605One of the register windows must be reserved at all times for trap processing.
     606This is critical to the proper operation of the trap mechanism in the SPARC
     607architecture.  It is the responsibility of the trap handler to insure that
     608there is a register window available for a subsequent trap before re-enabling
     609traps.  It is likely that any high level language routines invoked by the trap
     610handler (such as a user-provided RTEMS interrupt handler) will allocate a new
     611register window.  The save operation could result in a window overflow trap.
     612This trap cannot be correctly processed unless (1) traps are enabled and (2) a
     613register window is reserved for traps.  Thus, the RTEMS interrupt handler
     614insures that a register window is available for subsequent traps before
     615enabling traps and invoking the user's interrupt handler.
    719616
    720617Interrupt Levels
    721618----------------
    722619
    723 Sixteen levels (0-15) of interrupt priorities are
    724 supported by the SPARC architecture with level fifteen (15)
    725 being the highest priority.  Level zero (0) indicates that
    726 interrupts are fully enabled.  Interrupt requests for interrupts
    727 with priorities less than or equal to the current interrupt mask
    728 level are ignored. Level fifteen (15) is a non-maskable interrupt
    729 (NMI), which makes it unsuitable for standard usage since it can
    730 affect the real-time behaviour by interrupting critical sections
    731 and spinlocks. Disabling traps stops also the NMI interrupt from
    732 happening. It can however be used for power-down or other
    733 critical events.
    734 
    735 Although RTEMS supports 256 interrupt levels, the
    736 SPARC only supports sixteen.  RTEMS interrupt levels 0 through
    737 15 directly correspond to SPARC processor interrupt levels.  All
    738 other RTEMS interrupt levels are undefined and their behavior is
    739 unpredictable.
    740 
    741 Many LEON SPARC v7/v8 systems features an extended interrupt controller
    742 which adds an extra step of interrupt decoding to allow handling of
    743 interrupt 16-31. When such an extended interrupt is generated the CPU
    744 traps into a specific interrupt trap level 1-14 and software reads out from
    745 the interrupt controller which extended interrupt source actually caused the
    746 interrupt.
     620Sixteen levels (0-15) of interrupt priorities are supported by the SPARC
     621architecture with level fifteen (15) being the highest priority.  Level
     622zero (0) indicates that interrupts are fully enabled.  Interrupt requests for
     623interrupts with priorities less than or equal to the current interrupt mask
     624level are ignored. Level fifteen (15) is a non-maskable interrupt (NMI), which
     625makes it unsuitable for standard usage since it can affect the real-time
     626behaviour by interrupting critical sections and spinlocks. Disabling traps
     627stops also the NMI interrupt from happening. It can however be used for
     628power-down or other critical events.
     629
     630Although RTEMS supports 256 interrupt levels, the SPARC only supports sixteen.
     631RTEMS interrupt levels 0 through 15 directly correspond to SPARC processor
     632interrupt levels.  All other RTEMS interrupt levels are undefined and their
     633behavior is unpredictable.
     634
     635Many LEON SPARC v7/v8 systems features an extended interrupt controller which
     636adds an extra step of interrupt decoding to allow handling of interrupt
     63716-31. When such an extended interrupt is generated the CPU traps into a
     638specific interrupt trap level 1-14 and software reads out from the interrupt
     639controller which extended interrupt source actually caused the interrupt.
    747640
    748641Disabling of Interrupts by RTEMS
    749642--------------------------------
    750643
    751 During the execution of directive calls, critical
    752 sections of code may be executed.  When these sections are
    753 encountered, RTEMS disables interrupts to level fifteen (15)
    754 before the execution of the section and restores them to the
    755 previous level upon completion of the section.  RTEMS has been
    756 optimized to ensure that interrupts are disabled for less than
    757 RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ
    758 Mhz ERC32 with zero wait states.
    759 These numbers will vary based the number of wait states and
    760 processor speed present on the target board.
    761 \[NOTE:  The maximum period with interrupts disabled is hand calculated.  This
    762 calculation was last performed for Release
     644During the execution of directive calls, critical sections of code may be
     645executed.  When these sections are encountered, RTEMS disables interrupts to
     646level fifteen (15) before the execution of the section and restores them to the
     647previous level upon completion of the section.  RTEMS has been optimized to
     648ensure that interrupts are disabled for less than RTEMS_MAXIMUM_DISABLE_PERIOD
     649microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz ERC32 with zero wait
     650states.  These numbers will vary based the number of wait states and processor
     651speed present on the target board.  [NOTE: The maximum period with interrupts
     652disabled is hand calculated.  This calculation was last performed for Release
    763653RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
    764654
    765 [NOTE: It is thought that the length of time at which
    766 the processor interrupt level is elevated to fifteen by RTEMS is
    767 not anywhere near as long as the length of time ALL traps are
    768 disabled as part of the "flush all register windows" operation.]
    769 
    770 Non-maskable interrupts (NMI) cannot be disabled, and
    771 ISRs which execute at this level MUST NEVER issue RTEMS system
    772 calls.  If a directive is invoked, unpredictable results may
    773 occur due to the inability of RTEMS to protect its critical
    774 sections.  However, ISRs that make no system calls may safely
    775 execute as non-maskable interrupts.
    776 
    777 Interrupts are disabled or enabled by performing a system call
    778 to the Operating System reserved software traps 9
    779 (SPARC_SWTRAP_IRQDIS) or 10 (SPARC_SWTRAP_IRQDIS). The trap is
    780 generated by the software trap (Ticc) instruction or indirectly
    781 by calling sparc_disable_interrupts() or sparc_enable_interrupts()
    782 functions. Disabling interrupts return the previous interrupt level
    783 (on trap entry) in register G1 and sets PSR.PIL to 15 to disable
    784 all maskable interrupts. The interrupt level can be restored by
    785 trapping into the enable interrupt handler with G1 containing the
    786 new interrupt level.
     655[NOTE: It is thought that the length of time at which the processor interrupt
     656level is elevated to fifteen by RTEMS is not anywhere near as long as the
     657length of time ALL traps are disabled as part of the "flush all register
     658windows" operation.]
     659
     660Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
     661this level MUST NEVER issue RTEMS system calls.  If a directive is invoked,
     662unpredictable results may occur due to the inability of RTEMS to protect its
     663critical sections.  However, ISRs that make no system calls may safely execute
     664as non-maskable interrupts.
     665
     666Interrupts are disabled or enabled by performing a system call to the Operating
     667System reserved software traps 9 (SPARC_SWTRAP_IRQDIS) or 10
     668(SPARC_SWTRAP_IRQDIS). The trap is generated by the software trap (Ticc)
     669instruction or indirectly by calling sparc_disable_interrupts() or
     670sparc_enable_interrupts() functions. Disabling interrupts return the previous
     671interrupt level (on trap entry) in register G1 and sets PSR.PIL to 15 to
     672disable all maskable interrupts. The interrupt level can be restored by
     673trapping into the enable interrupt handler with G1 containing the new interrupt
     674level.
    787675
    788676Interrupt Stack
    789677---------------
    790678
    791 The SPARC architecture does not provide for a
    792 dedicated interrupt stack.  Thus by default, trap handlers would
    793 execute on the stack of the RTEMS task which they interrupted.
    794 This artificially inflates the stack requirements for each task
    795 since EVERY task stack would have to include enough space to
    796 account for the worst case interrupt stack requirements in
    797 addition to it's own worst case usage.  RTEMS addresses this
    798 problem on the SPARC by providing a dedicated interrupt stack
    799 managed by software.
    800 
    801 During system initialization, RTEMS allocates the
    802 interrupt stack from the Workspace Area.  The amount of memory
    803 allocated for the interrupt stack is determined by the
    804 interrupt_stack_size field in the CPU Configuration Table.  As
    805 part of processing a non-nested interrupt, RTEMS will switch to
    806 the interrupt stack before invoking the installed handler.
    807 
    808 .. COMMENT: COPYRIGHT (c) 1988-2002.
    809 
    810 .. COMMENT: On-Line Applications Research Corporation (OAR).
    811 
    812 .. COMMENT: All rights reserved.
     679The SPARC architecture does not provide for a dedicated interrupt stack.  Thus
     680by default, trap handlers would execute on the stack of the RTEMS task which
     681they interrupted.  This artificially inflates the stack requirements for each
     682task since EVERY task stack would have to include enough space to account for
     683the worst case interrupt stack requirements in addition to it's own worst case
     684usage.  RTEMS addresses this problem on the SPARC by providing a dedicated
     685interrupt stack managed by software.
     686
     687During system initialization, RTEMS allocates the interrupt stack from the
     688Workspace Area.  The amount of memory allocated for the interrupt stack is
     689determined by the interrupt_stack_size field in the CPU Configuration Table.
     690As part of processing a non-nested interrupt, RTEMS will switch to the
     691interrupt stack before invoking the installed handler.
    813692
    814693Default Fatal Error Processing
    815694==============================
    816695
    817 Upon detection of a fatal error by either the
    818 application or RTEMS the fatal error manager is invoked.  The
    819 fatal error manager will invoke the user-supplied fatal error
    820 handlers.  If no user-supplied handlers are configured,  the
    821 RTEMS provided default fatal error handler is invoked.  If the
    822 user-supplied fatal error handlers return to the executive the
    823 default fatal error handler is then invoked.  This chapter
    824 describes the precise operations of the default fatal error
    825 handler.
     696Upon detection of a fatal error by either the application or RTEMS the fatal
     697error manager is invoked.  The fatal error manager will invoke the
     698user-supplied fatal error handlers.  If no user-supplied handlers are
     699configured, the RTEMS provided default fatal error handler is invoked.  If the
     700user-supplied fatal error handlers return to the executive the default fatal
     701error handler is then invoked.  This chapter describes the precise operations
     702of the default fatal error handler.
    826703
    827704Default Fatal Error Handler Operations
    828705--------------------------------------
    829706
    830 The default fatal error handler which is invoked by
    831 the fatal_error_occurred directive when there is no user handler
    832 configured or the user handler returns control to RTEMS.
    833 
    834 If the BSP has been configured with ``BSP_POWER_DOWN_AT_FATAL_HALT``
    835 set to true, the default handler will disable interrupts
    836 and enter power down mode. If power down mode is not available,
    837 it goes into an infinite loop to simulate a halt processor instruction.
    838 
    839 If ``BSP_POWER_DOWN_AT_FATAL_HALT`` is set to false, the default
    840 handler will place the value ``1`` in register ``g1``, the
    841 error source in register ``g2``, and the error code in register``g3``. It will then generate a system error which will
    842 hand over control to the debugger, simulator, etc.
     707The default fatal error handler which is invoked by the fatal_error_occurred
     708directive when there is no user handler configured or the user handler returns
     709control to RTEMS.
     710
     711If the BSP has been configured with ``BSP_POWER_DOWN_AT_FATAL_HALT`` set to
     712true, the default handler will disable interrupts and enter power down mode. If
     713power down mode is not available, it goes into an infinite loop to simulate a
     714halt processor instruction.
     715
     716If ``BSP_POWER_DOWN_AT_FATAL_HALT`` is set to false, the default handler will
     717place the value ``1`` in register ``g1``, the error source in register ``g2``,
     718and the error code in register``g3``. It will then generate a system error
     719which will hand over control to the debugger, simulator, etc.
    843720
    844721Symmetric Multiprocessing
     
    853730Thread-local storage is supported.
    854731
    855 .. COMMENT: COPYRIGHT (c) 1988-2002.
    856 
    857 .. COMMENT: On-Line Applications Research Corporation (OAR).
    858 
    859 .. COMMENT: All rights reserved.
    860 
    861732Board Support Packages
    862733======================
    863734
    864 An RTEMS Board Support Package (BSP) must be designed
    865 to support a particular processor and target board combination.
    866 This chapter presents a discussion of SPARC specific BSP issues.
    867 For more information on developing a BSP, refer to the chapter
    868 titled Board Support Packages in the RTEMS
    869 Applications User's Guide.
     735An RTEMS Board Support Package (BSP) must be designed to support a particular
     736processor and target board combination.  This chapter presents a discussion of
     737SPARC specific BSP issues.  For more information on developing a BSP, refer to
     738the chapter titled Board Support Packages in the RTEMS Applications User's
     739Guide.
    870740
    871741System Reset
    872742------------
    873743
    874 An RTEMS based application is initiated or
    875 re-initiated when the SPARC processor is reset.  When the SPARC
    876 is reset, the processor performs the following actions:
    877 
    878 - the enable trap (ET) of the psr is set to 0 to disable
    879   traps,
    880 
    881 - the supervisor bit (S) of the psr is set to 1 to enter
    882   supervisor mode, and
     744An RTEMS based application is initiated or re-initiated when the SPARC
     745processor is reset.  When the SPARC is reset, the processor performs the
     746following actions:
     747
     748- the enable trap (ET) of the psr is set to 0 to disable traps,
     749
     750- the supervisor bit (S) of the psr is set to 1 to enter supervisor mode, and
    883751
    884752- the PC is set 0 and the nPC is set to 4.
    885753
    886 The processor then begins to execute the code at
    887 location 0.  It is important to note that all fields in the psr
    888 are not explicitly set by the above steps and all other
    889 registers retain their value from the previous execution mode.
    890 This is true even of the Trap Base Register (TBR) whose contents
    891 reflect the last trap which occurred before the reset.
     754The processor then begins to execute the code at location 0.  It is important
     755to note that all fields in the psr are not explicitly set by the above steps
     756and all other registers retain their value from the previous execution mode.
     757This is true even of the Trap Base Register (TBR) whose contents reflect the
     758last trap which occurred before the reset.
    892759
    893760Processor Initialization
    894761------------------------
    895762
    896 It is the responsibility of the application's
    897 initialization code to initialize the TBR and install trap
    898 handlers for at least the register window overflow and register
    899 window underflow conditions.  Traps should be enabled before
    900 invoking any subroutines to allow for register window
    901 management.  However, interrupts should be disabled by setting
    902 the Processor Interrupt Level (pil) field of the psr to 15.
    903 RTEMS installs it's own Trap Table as part of initialization
    904 which is initialized with the contents of the Trap Table in
    905 place when the ``rtems_initialize_executive`` directive was invoked.
    906 Upon completion of executive initialization, interrupts are
    907 enabled.
    908 
    909 If this SPARC implementation supports on-chip caching
    910 and this is to be utilized, then it should be enabled during the
    911 reset application initialization code.
    912 
    913 In addition to the requirements described in the
    914 Board Support Packages chapter of the C
    915 Applications Users Manual for the reset code
    916 which is executed before the call to``rtems_initialize_executive``, the SPARC version has the following
     763It is the responsibility of the application's initialization code to initialize
     764the TBR and install trap handlers for at least the register window overflow and
     765register window underflow conditions.  Traps should be enabled before invoking
     766any subroutines to allow for register window management.  However, interrupts
     767should be disabled by setting the Processor Interrupt Level (pil) field of the
     768psr to 15.  RTEMS installs it's own Trap Table as part of initialization which
     769is initialized with the contents of the Trap Table in place when the
     770``rtems_initialize_executive`` directive was invoked.  Upon completion of
     771executive initialization, interrupts are enabled.
     772
     773If this SPARC implementation supports on-chip caching and this is to be
     774utilized, then it should be enabled during the reset application initialization
     775code.
     776
     777In addition to the requirements described in the Board Support Packages chapter
     778of the C Applications Users Manual for the reset code which is executed before
     779the call to``rtems_initialize_executive``, the SPARC version has the following
    917780specific requirements:
    918781
    919 - Must leave the S bit of the status register set so that
    920   the SPARC remains in the supervisor state.
    921 
    922 - Must set stack pointer (sp) such that a minimum stack
    923   size of MINIMUM_STACK_SIZE bytes is provided for the``rtems_initialize_executive`` directive.
    924 
    925 - Must disable all external interrupts (i.e. set the pil
    926   to 15).
    927 
    928 - Must enable traps so window overflow and underflow
    929   conditions can be properly handled.
    930 
    931 - Must initialize the SPARC's initial trap table with at
    932   least trap handlers for register window overflow and register
    933   window underflow.
    934 
    935 .. COMMENT: COPYRIGHT (c) 1988-2002.
    936 
    937 .. COMMENT: On-Line Applications Research Corporation (OAR).
    938 
    939 .. COMMENT: All rights reserved.
    940 
     782- Must leave the S bit of the status register set so that the SPARC remains in
     783  the supervisor state.
     784
     785- Must set stack pointer (sp) such that a minimum stack size of
     786  MINIMUM_STACK_SIZE bytes is provided for the``rtems_initialize_executive``
     787  directive.
     788
     789- Must disable all external interrupts (i.e. set the pil to 15).
     790
     791- Must enable traps so window overflow and underflow conditions can be properly
     792  handled.
     793
     794- Must initialize the SPARC's initial trap table with at least trap handlers
     795  for register window overflow and register window underflow.
  • cpu_supplement/sparc64.rst

    re6fe68d rf233256  
    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
    37SPARC-64 Specific Information
     
    2226  (http://www.sun.com/microelectronics/manuals/ultrasparc/802-7220-02.pdf)
    2327
    24 - UltraSPARC IIIi Processor (datasheets.chipdb.org/Sun/UltraSparc-IIIi.pdf)
     28- UltraSPARC IIIi Processor (http://datasheets.chipdb.org/Sun/UltraSparc-IIIi.pdf)
    2529
    2630**sun4v Specific Information**
    2731
    28 sun4v is the subset of the SPARC V9 implementations comprising the
    29 UltraSPARC T1 or T2 processors.
     32sun4v is the subset of the SPARC V9 implementations comprising the UltraSPARC
     33T1 or T2 processors.
    3034
    3135The following documents were used in developing the SPARC-64 sun4v port:
     
    3741  (http://opensparc-t1.sunsource.net/specs/UST1-UASuppl-current-draft-P-EXT.pdf)
    3842
    39 The defining feature that separates the sun4v architecture from its
    40 predecessor is the existence of a super-privileged hypervisor that
    41 is responsible for providing virtualized execution environments.  The impact
    42 of the hypervisor on the real-time guarantees available with sun4v has not
    43 yet been determined.
     43The defining feature that separates the sun4v architecture from its predecessor
     44is the existence of a super-privileged hypervisor that is responsible for
     45providing virtualized execution environments.  The impact of the hypervisor on
     46the real-time guarantees available with sun4v has not yet been determined.
    4447
    4548CPU Model Dependent Features
     
    4952-----------------------
    5053
    51 This section presents the set of features which vary across
    52 SPARC-64 implementations and
    53 are of importance to RTEMS. The set of CPU model feature macros
    54 are defined in the file
    55 cpukit/score/cpu/sparc64/sparc64.h based upon the particular
    56 CPU model defined on the compilation command line.
     54This section presents the set of features which vary across SPARC-64
     55implementations and are of importance to RTEMS. The set of CPU model feature
     56macros are defined in the file cpukit/score/cpu/sparc64/sparc64.h based upon
     57the particular CPU model defined on the compilation command line.
    5758
    5859CPU Model Name
    5960~~~~~~~~~~~~~~
    6061
    61 The macro CPU MODEL NAME is a string which designates
    62 the name of this CPU model.
    63 For example, for the UltraSPARC T1 SPARC V9 model,
    64 this macro is set to the string "sun4v".
     62The macro CPU MODEL NAME is a string which designates the name of this CPU
     63model.  For example, for the UltraSPARC T1 SPARC V9 model, this macro is set to
     64the string "sun4v".
    6565
    6666Floating Point Unit
    6767~~~~~~~~~~~~~~~~~~~
    6868
    69 The macro SPARC_HAS_FPU is set to 1 to indicate that
    70 this CPU model has a hardware floating point unit and 0
    71 otherwise.
     69The macro SPARC_HAS_FPU is set to 1 to indicate that this CPU model has a
     70hardware floating point unit and 0 otherwise.
    7271
    7372Number of Register Windows
    7473~~~~~~~~~~~~~~~~~~~~~~~~~~
    7574
    76 The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to
    77 indicate the number of register window sets implemented by this
    78 CPU model.  The SPARC architecture allows for a maximum of
    79 thirty-two register window sets although most implementations
    80 only include eight.
     75The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to indicate the number of
     76register window sets implemented by this CPU model.  The SPARC architecture
     77allows for a maximum of thirty-two register window sets although most
     78implementations only include eight.
    8179
    8280CPU Model Implementation Notes
    8381------------------------------
    8482
    85 This section describes the implemenation dependencies of the
    86 CPU Models sun4u and sun4v of the SPARC V9 architecture.
     83This section describes the implemenation dependencies of the CPU Models sun4u
     84and sun4v of the SPARC V9 architecture.
    8785
    8886sun4u Notes
     
    9694XXX
    9795
    98 .. COMMENT: COPYRIGHT (c) 1988-2002.
    99 
    100 .. COMMENT: On-Line Applications Research Corporation (OAR).
    101 
    102 .. COMMENT: All rights reserved.
    103 
    10496Calling Conventions
    10597===================
    10698
    107 Each high-level language compiler generates
    108 subroutine entry and exit code based upon a set of rules known
    109 as the compiler's calling convention.   These rules address the
    110 following issues:
     99Each high-level language compiler generates subroutine entry and exit code
     100based upon a set of rules known as the compiler's calling convention.  These
     101rules address the following issues:
    111102
    112103- register preservation and usage
     
    123114are both processor and compiler dependent.
    124115
    125 The following document also provides some conventions on the
    126 global register usage in SPARC V9:
    127 http://developers.sun.com/solaris/articles/sparcv9abi.html
     116The following document also provides some conventions on the global register
     117usage in SPARC V9: http://developers.sun.com/solaris/articles/sparcv9abi.html
    128118
    129119Programming Model
    130120-----------------
    131121
    132 This section discusses the programming model for the
    133 SPARC architecture.
     122This section discusses the programming model for the SPARC architecture.
    134123
    135124Non-Floating Point Registers
    136125~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    137126
    138 The SPARC architecture defines thirty-two
    139 non-floating point registers directly visible to the programmer.
    140 These are divided into four sets:
     127The SPARC architecture defines thirty-two non-floating point registers directly
     128visible to the programmer.  These are divided into four sets:
    141129
    142130- input registers
     
    148136- global registers
    149137
    150 Each register is referred to by either two or three
    151 names in the SPARC reference manuals.  First, the registers are
    152 referred to as r0 through r31 or with the alternate notation
    153 r[0] through r[31].  Second, each register is a member of one of
    154 the four sets listed above.  Finally, some registers have an
    155 architecturally defined role in the programming model which
    156 provides an alternate name.  The following table describes the
    157 mapping between the 32 registers and the register sets:
    158 
    159 .. code:: c
     138Each register is referred to by either two or three names in the SPARC
     139reference manuals.  First, the registers are referred to as r0 through r31 or
     140with the alternate notation r[0] through r[31].  Second, each register is a
     141member of one of the four sets listed above.  Finally, some registers have an
     142architecturally defined role in the programming model which provides an
     143alternate name.  The following table describes the mapping between the 32
     144registers and the register sets:
    160145
    161146    +-----------------+----------------+------------------+
     
    171156    +-----------------+----------------+------------------+
    172157
    173 As mentioned above, some of the registers serve
    174 defined roles in the programming model.  The following table
    175 describes the role of each of these registers:
    176 
    177 .. code:: c
     158As mentioned above, some of the registers serve defined roles in the
     159programming model.  The following table describes the role of each of these
     160registers:
    178161
    179162    +---------------+----------------+----------------------+
     
    193176~~~~~~~~~~~~~~~~~~~~~~~~
    194177
    195 The SPARC V9 architecture includes sixty-four,
    196 thirty-two bit registers.  These registers may be viewed as
    197 follows:
    198 
    199 - 32 32-bit single precision floating point or integer registers
    200   (f0, f1,  ... f31)
    201 
    202 - 32 64-bit double precision floating point registers (f0, f2,
    203   f4, ... f62)
    204 
    205 - 16 128-bit extended precision floating point registers (f0, f4,
    206   f8, ... f60)
    207 
    208 The floating point state register (fsr) specifies
    209 the behavior of the floating point unit for rounding, contains
    210 its condition codes, version specification, and trap information.
     178The SPARC V9 architecture includes sixty-four, thirty-two bit registers.  These
     179registers may be viewed as follows:
     180
     181- 32 32-bit single precision floating point or integer registers (f0, f1,
     182  ... f31)
     183
     184- 32 64-bit double precision floating point registers (f0, f2, f4, ... f62)
     185
     186- 16 128-bit extended precision floating point registers (f0, f4, f8, ... f60)
     187
     188The floating point state register (fsr) specifies the behavior of the floating
     189point unit for rounding, contains its condition codes, version specification,
     190and trap information.
    211191
    212192Special Registers
     
    216196
    217197*``Ancillary State Registers (ASRs)``*
    218     The ancillary state registers (ASRs) are optional state registers that
    219     may be privileged or nonprivileged. ASRs 16-31 are implementation-
    220     dependent. The SPARC V9 ASRs include: y, ccr, asi, tick, pc, fprs.
    221     The sun4u ASRs include: pcr, pic, dcr, gsr, softint set, softint clr,
    222     softint, and tick cmpr. The sun4v ASRs include: pcr, pic, gsr, soft-
    223     int set, softint clr, softint, tick cmpr, stick, and stick cmpr.
     198    The ancillary state registers (ASRs) are optional state registers that may
     199    be privileged or nonprivileged. ASRs 16-31 are implementation-
     200    dependent. The SPARC V9 ASRs include: y, ccr, asi, tick, pc, fprs.  The
     201    sun4u ASRs include: pcr, pic, dcr, gsr, softint set, softint clr, softint,
     202    and tick cmpr. The sun4v ASRs include: pcr, pic, gsr, soft- int set,
     203    softint clr, softint, tick cmpr, stick, and stick cmpr.
    224204
    225205*``Processor State Register (pstate)``*
     
    233213
    234214*``Trap Registers``*
    235     The trap handling mechanism of the SPARC V9 includes a number of
    236     registers, including: trap program counter (tpc), trap next pc (tnpc),
    237     trap state (tstate), trap type (tt), trap base address (tba), and trap
    238     level (tl).
     215    The trap handling mechanism of the SPARC V9 includes a number of registers,
     216    including: trap program counter (tpc), trap next pc (tnpc), trap state
     217    (tstate), trap type (tt), trap base address (tba), and trap level (tl).
    239218
    240219*``Alternate Globals``*
    241     The AG bit of the pstate register provides access to an alternate set
    242     of global registers. On sun4v, the AG bit is replaced by the global
    243     level (gl) register, providing access to at least two and at most eight
    244     alternate sets of globals.
     220    The AG bit of the pstate register provides access to an alternate set of
     221    global registers. On sun4v, the AG bit is replaced by the global level (gl)
     222    register, providing access to at least two and at most eight alternate sets
     223    of globals.
    245224
    246225*``Register Window registers``*
    247     A number of registers assist in register window management.
    248     These include the current window pointer (cwp), savable windows
    249     (cansave), restorable windows (canrestore), clean windows (clean-
    250     win), other windows (otherwin), and window state (wstate).
     226    A number of registers assist in register window management.  These include
     227    the current window pointer (cwp), savable windows (cansave), restorable
     228    windows (canrestore), clean windows (clean- win), other windows (otherwin),
     229    and window state (wstate).
    251230
    252231Register Windows
    253232----------------
    254233
    255 The SPARC architecture includes the concept of
    256 register windows.  An overly simplistic way to think of these
    257 windows is to imagine them as being an infinite supply of
    258 "fresh" register sets available for each subroutine to use.  In
    259 reality, they are much more complicated.
    260 
    261 The save instruction is used to obtain a new register window.
    262 This instruction increments the current window pointer, thus
    263 providing a new set of registers for use. This register set
    264 includes eight fresh local registers for use exclusively by
    265 this subroutine. When done with a register set, the restore
    266 instruction decrements the current window pointer and the
    267 previous register set is once again available.
    268 
    269 The two primary issues complicating the use of register windows
    270 are that (1) the set of register windows is finite, and (2) some
    271 registers are shared between adjacent registers windows.
    272 
    273 Because the set of register windows is finite, it is
    274 possible to execute enough save instructions without
    275 corresponding restore's to consume all of the register windows.
    276 This is easily accomplished in a high level language because
    277 each subroutine typically performs a save instruction upon
    278 entry.  Thus having a subroutine call depth greater than the
    279 number of register windows will result in a window overflow
    280 condition.  The window overflow condition generates a trap which
    281 must be handled in software.  The window overflow trap handler
    282 is responsible for saving the contents of the oldest register
    283 window on the program stack.
    284 
    285 Similarly, the subroutines will eventually complete
    286 and begin to perform restore's.  If the restore results in the
    287 need for a register window which has previously been written to
    288 memory as part of an overflow, then a window underflow condition
    289 results.  Just like the window overflow, the window underflow
    290 condition must be handled in software by a trap handler.  The
    291 window underflow trap handler is responsible for reloading the
    292 contents of the register window requested by the restore
    293 instruction from the program stack.
    294 
    295 The cansave, canrestore, otherwin, and cwp are used in conjunction
    296 to manage the finite set of register windows and detect the window
    297 overflow and underflow conditions. The first three of these
    298 registers must satisfy the invariant cansave + canrestore + otherwin =
    299 nwindow - 2, where nwindow is the number of register windows.
    300 The cwp contains the index of the register window currently in use.
    301 RTEMS does not use the cleanwin and otherwin registers.
    302 
    303 The save instruction increments the cwp modulo the number of
    304 register windows, and if cansave is 0 then it also generates a
    305 window overflow. Similarly, the restore instruction decrements the
    306 cwp modulo the number of register windows, and if canrestore is 0 then it
    307 also generates a window underflow.
    308 
    309 Unlike with the SPARC model, the SPARC-64 port does not assume that
    310 a register window is available for a trap. The window overflow
    311 and underflow conditions are not detected without hardware generating
    312 the trap. (These conditions can be detected by reading the register window
    313 registers and doing some simple arithmetic.)
    314 
    315 The window overflow and window underflow trap
    316 handlers are a critical part of the run-time environment for a
    317 SPARC application.  The SPARC architectural specification allows
    318 for the number of register windows to be any power of two less
    319 than or equal to 32.  The most common choice for SPARC
    320 implementations appears to be 8 register windows.  This results
    321 in the cwp ranging in value from 0 to 7 on most implementations.
    322 
    323 The second complicating factor is the sharing of
    324 registers between adjacent register windows.  While each
    325 register window has its own set of local registers, the input
    326 and output registers are shared between adjacent windows.  The
    327 output registers for register window N are the same as the input
    328 registers for register window ((N + 1) modulo RW) where RW is
    329 the number of register windows.  An alternative way to think of
    330 this is to remember how parameters are passed to a subroutine on
    331 the SPARC.  The caller loads values into what are its output
    332 registers.  Then after the callee executes a save instruction,
    333 those parameters are available in its input registers.  This is
    334 a very efficient way to pass parameters as no data is actually
    335 moved by the save or restore instructions.
     234The SPARC architecture includes the concept of register windows.  An overly
     235simplistic way to think of these windows is to imagine them as being an
     236infinite supply of "fresh" register sets available for each subroutine to use.
     237In reality, they are much more complicated.
     238
     239The save instruction is used to obtain a new register window.  This instruction
     240increments the current window pointer, thus providing a new set of registers
     241for use. This register set includes eight fresh local registers for use
     242exclusively by this subroutine. When done with a register set, the restore
     243instruction decrements the current window pointer and the previous register set
     244is once again available.
     245
     246The two primary issues complicating the use of register windows are that (1)
     247the set of register windows is finite, and (2) some registers are shared
     248between adjacent registers windows.
     249
     250Because the set of register windows is finite, it is possible to execute enough
     251save instructions without corresponding restore's to consume all of the
     252register windows.  This is easily accomplished in a high level language because
     253each subroutine typically performs a save instruction upon entry.  Thus having
     254a subroutine call depth greater than the number of register windows will result
     255in a window overflow condition.  The window overflow condition generates a trap
     256which must be handled in software.  The window overflow trap handler is
     257responsible for saving the contents of the oldest register window on the
     258program stack.
     259
     260Similarly, the subroutines will eventually complete and begin to perform
     261restore's.  If the restore results in the need for a register window which has
     262previously been written to memory as part of an overflow, then a window
     263underflow condition results.  Just like the window overflow, the window
     264underflow condition must be handled in software by a trap handler.  The window
     265underflow trap handler is responsible for reloading the contents of the
     266register window requested by the restore instruction from the program stack.
     267
     268The cansave, canrestore, otherwin, and cwp are used in conjunction to manage
     269the finite set of register windows and detect the window overflow and underflow
     270conditions. The first three of these registers must satisfy the invariant
     271cansave + canrestore + otherwin = nwindow - 2, where nwindow is the number of
     272register windows.  The cwp contains the index of the register window currently
     273in use.  RTEMS does not use the cleanwin and otherwin registers.
     274
     275The save instruction increments the cwp modulo the number of register windows,
     276and if cansave is 0 then it also generates a window overflow. Similarly, the
     277restore instruction decrements the cwp modulo the number of register windows,
     278and if canrestore is 0 then it also generates a window underflow.
     279
     280Unlike with the SPARC model, the SPARC-64 port does not assume that a register
     281window is available for a trap. The window overflow and underflow conditions
     282are not detected without hardware generating the trap. (These conditions can be
     283detected by reading the register window registers and doing some simple
     284arithmetic.)
     285
     286The window overflow and window underflow trap handlers are a critical part of
     287the run-time environment for a SPARC application.  The SPARC architectural
     288specification allows for the number of register windows to be any power of two
     289less than or equal to 32.  The most common choice for SPARC implementations
     290appears to be 8 register windows.  This results in the cwp ranging in value
     291from 0 to 7 on most implementations.
     292
     293The second complicating factor is the sharing of registers between adjacent
     294register windows.  While each register window has its own set of local
     295registers, the input and output registers are shared between adjacent windows.
     296The output registers for register window N are the same as the input registers
     297for register window ((N + 1) modulo RW) where RW is the number of register
     298windows.  An alternative way to think of this is to remember how parameters are
     299passed to a subroutine on the SPARC.  The caller loads values into what are its
     300output registers.  Then after the callee executes a save instruction, those
     301parameters are available in its input registers.  This is a very efficient way
     302to pass parameters as no data is actually moved by the save or restore
     303instructions.
    336304
    337305Call and Return Mechanism
    338306-------------------------
    339307
    340 The SPARC architecture supports a simple yet
    341 effective call and return mechanism.  A subroutine is invoked
    342 via the call (call) instruction.  This instruction places the
    343 return address in the caller's output register 7 (o7).  After
    344 the callee executes a save instruction, this value is available
    345 in input register 7 (i7) until the corresponding restore
    346 instruction is executed.
    347 
    348 The callee returns to the caller via a jmp to the
    349 return address.  There is a delay slot following this
    350 instruction which is commonly used to execute a restore
    351 instruction - if a register window was allocated by this
    352 subroutine.
    353 
    354 It is important to note that the SPARC subroutine
    355 call and return mechanism does not automatically save and
    356 restore any registers.  This is accomplished via the save and
    357 restore instructions which manage the set of registers windows.
    358 This allows for the compiler to generate leaf-optimized functions
     308The SPARC architecture supports a simple yet effective call and return
     309mechanism.  A subroutine is invoked via the call (call) instruction.  This
     310instruction places the return address in the caller's output register 7 (o7).
     311After the callee executes a save instruction, this value is available in input
     312register 7 (i7) until the corresponding restore instruction is executed.
     313
     314The callee returns to the caller via a jmp to the return address.  There is a
     315delay slot following this instruction which is commonly used to execute a
     316restore instruction - if a register window was allocated by this subroutine.
     317
     318It is important to note that the SPARC subroutine call and return mechanism
     319does not automatically save and restore any registers.  This is accomplished
     320via the save and restore instructions which manage the set of registers
     321windows.  This allows for the compiler to generate leaf-optimized functions
    359322that utilize the caller's output registers without using save and restore.
    360323
     
    362325-----------------
    363326
    364 All RTEMS directives are invoked using the regular
    365 SPARC calling convention via the call instruction.
     327All RTEMS directives are invoked using the regular SPARC calling convention via
     328the call instruction.
    366329
    367330Register Usage
    368331--------------
    369332
    370 As discussed above, the call instruction does not
    371 automatically save any registers.  The save and restore
    372 instructions are used to allocate and deallocate register
    373 windows.  When a register window is allocated, the new set of
    374 local registers are available for the exclusive use of the
    375 subroutine which allocated this register set.
     333As discussed above, the call instruction does not automatically save any
     334registers.  The save and restore instructions are used to allocate and
     335deallocate register windows.  When a register window is allocated, the new set
     336of local registers are available for the exclusive use of the subroutine which
     337allocated this register set.
    376338
    377339Parameter Passing
    378340-----------------
    379341
    380 RTEMS assumes that arguments are placed in the
    381 caller's output registers with the first argument in output
    382 register 0 (o0), the second argument in output register 1 (o1),
    383 and so forth.  Until the callee executes a save instruction, the
    384 parameters are still visible in the output registers.  After the
    385 callee executes a save instruction, the parameters are visible
    386 in the corresponding input registers.  The following pseudo-code
    387 illustrates the typical sequence used to call a RTEMS directive
    388 with three (3) arguments:
    389 .. code:: c
     342RTEMS assumes that arguments are placed in the caller's output registers with
     343the first argument in output register 0 (o0), the second argument in output
     344register 1 (o1), and so forth.  Until the callee executes a save instruction,
     345the parameters are still visible in the output registers.  After the callee
     346executes a save instruction, the parameters are visible in the corresponding
     347input registers.  The following pseudo-code illustrates the typical sequence
     348used to call a RTEMS directive with three (3) arguments:
     349
     350.. code-block:: c
    390351
    391352    load third argument into o2
     
    397358----------------------
    398359
    399 All user-provided routines invoked by RTEMS, such as
    400 user extensions, device drivers, and MPCI routines, must also
    401 adhere to these calling conventions.
    402 
    403 .. COMMENT: COPYRIGHT (c) 1988-2002.
    404 
    405 .. COMMENT: On-Line Applications Research Corporation (OAR).
    406 
    407 .. COMMENT: All rights reserved.
     360All user-provided routines invoked by RTEMS, such as user extensions, device
     361drivers, and MPCI routines, must also adhere to these calling conventions.
    408362
    409363Memory Model
    410364============
    411365
    412 A processor may support any combination of memory
    413 models ranging from pure physical addressing to complex demand
    414 paged virtual memory systems.  RTEMS supports a flat memory
    415 model which ranges contiguously over the processor's allowable
    416 address space.  RTEMS does not support segmentation or virtual
    417 memory of any kind.  The appropriate memory model for RTEMS
    418 provided by the targeted processor and related characteristics
    419 of that model are described in this chapter.
     366A processor may support any combination of memory models ranging from pure
     367physical addressing to complex demand paged virtual memory systems.  RTEMS
     368supports a flat memory model which ranges contiguously over the processor's
     369allowable address space.  RTEMS does not support segmentation or virtual memory
     370of any kind.  The appropriate memory model for RTEMS provided by the targeted
     371processor and related characteristics of that model are described in this
     372chapter.
    420373
    421374Flat Memory Model
    422375-----------------
    423376
    424 The SPARC-64 architecture supports a flat 64-bit address space with
    425 addresses ranging from 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF.
    426 Each address is represented by a 64-bit value (and an 8-bit address
    427 space identifider or ASI) and is byte addressable. The address
    428 may be used to reference a single byte, half-word (2-bytes),
    429 word (4 bytes), doubleword (8 bytes), or quad-word (16 bytes).
    430 Memory accesses within this address space are performed
    431 in big endian fashion by the SPARC. Memory accesses which are not
    432 properly aligned generate a "memory address not aligned" trap
    433 (type number 0x34). The following table lists the alignment
    434 requirements for a variety of data accesses:
    435 
    436 .. code:: c
     377The SPARC-64 architecture supports a flat 64-bit address space with addresses
     378ranging from 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF.  Each address is
     379represented by a 64-bit value (and an 8-bit address space identifider or ASI)
     380and is byte addressable. The address may be used to reference a single byte,
     381half-word (2-bytes), word (4 bytes), doubleword (8 bytes), or quad-word (16
     382bytes).  Memory accesses within this address space are performed in big endian
     383fashion by the SPARC. Memory accesses which are not properly aligned generate a
     384"memory address not aligned" trap (type number 0x34). The following table lists
     385the alignment requirements for a variety of data accesses:
     386
     387.. table::
    437388
    438389    +--------------+-----------------------+
     
    446397    +--------------+-----------------------+
    447398
    448 RTEMS currently does not support any SPARC Memory Management
    449 Units, therefore, virtual memory or segmentation systems
    450 involving the SPARC are not supported.
    451 
    452 .. COMMENT: COPYRIGHT (c) 1988-2002.
    453 
    454 .. COMMENT: On-Line Applications Research Corporation (OAR).
    455 
    456 .. COMMENT: All rights reserved.
     399RTEMS currently does not support any SPARC Memory Management Units, therefore,
     400virtual memory or segmentation systems involving the SPARC are not supported.
    457401
    458402Interrupt Processing
    459403====================
    460404
    461 RTEMS and associated documentation uses the terms
    462 interrupt and vector.  In the SPARC architecture, these terms
    463 correspond to traps and trap type, respectively.  The terms will
    464 be used interchangeably in this manual. Note that in the SPARC manuals,
    465 interrupts are a subset of the traps that are delivered to software
    466 interrupt handlers.
     405RTEMS and associated documentation uses the terms interrupt and vector.  In the
     406SPARC architecture, these terms correspond to traps and trap type,
     407respectively.  The terms will be used interchangeably in this manual. Note that
     408in the SPARC manuals, interrupts are a subset of the traps that are delivered
     409to software interrupt handlers.
    467410
    468411Synchronous Versus Asynchronous Traps
    469412-------------------------------------
    470413
    471 The SPARC architecture includes two classes of traps:
    472 synchronous (precise) and asynchronous (deferred).
    473 Asynchronous traps occur when an
    474 external event interrupts the processor.  These traps are not
    475 associated with any instruction executed by the processor and
    476 logically occur between instructions.  The instruction currently
    477 in the execute stage of the processor is allowed to complete
    478 although subsequent instructions are annulled.  The return
    479 address reported by the processor for asynchronous traps is the
    480 pair of instructions following the current instruction.
    481 
    482 Synchronous traps are caused by the actions of an
    483 instruction.  The trap stimulus in this case either occurs
    484 internally to the processor or is from an external signal that
    485 was provoked by the instruction.  These traps are taken
    486 immediately and the instruction that caused the trap is aborted
    487 before any state changes occur in the processor itself.   The
    488 return address reported by the processor for synchronous traps
    489 is the instruction which caused the trap and the following
    490 instruction.
     414The SPARC architecture includes two classes of traps: synchronous (precise) and
     415asynchronous (deferred).  Asynchronous traps occur when an external event
     416interrupts the processor.  These traps are not associated with any instruction
     417executed by the processor and logically occur between instructions.  The
     418instruction currently in the execute stage of the processor is allowed to
     419complete although subsequent instructions are annulled.  The return address
     420reported by the processor for asynchronous traps is the pair of instructions
     421following the current instruction.
     422
     423Synchronous traps are caused by the actions of an instruction.  The trap
     424stimulus in this case either occurs internally to the processor or is from an
     425external signal that was provoked by the instruction.  These traps are taken
     426immediately and the instruction that caused the trap is aborted before any
     427state changes occur in the processor itself.  The return address reported by
     428the processor for synchronous traps is the instruction which caused the trap
     429and the following instruction.
    491430
    492431Vectoring of Interrupt Handler
    493432------------------------------
    494433
    495 Upon receipt of an interrupt the SPARC automatically
    496 performs the following actions:
    497 
    498 - The trap level is set. This provides access to a fresh set of
    499   privileged trap-state registers used to save the current state,
    500   in effect, pushing a frame on the trap stack.
    501   TL <- TL + 1
     434Upon receipt of an interrupt the SPARC automatically performs the following
     435actions:
     436
     437- The trap level is set. This provides access to a fresh set of privileged
     438  trap-state registers used to save the current state, in effect, pushing a
     439  frame on the trap stack.  TL <- TL + 1
    502440
    503441- Existing state is preserved
     
    537475
    538476In order to safely invoke a subroutine during trap handling, traps must be
    539 enabled to allow for the possibility of register window overflow and
    540 underflow traps.
    541 
    542 If the interrupt handler was installed as an RTEMS
    543 interrupt handler, then upon receipt of the interrupt, the
    544 processor passes control to the RTEMS interrupt handler which
    545 performs the following actions:
     477enabled to allow for the possibility of register window overflow and underflow
     478traps.
     479
     480If the interrupt handler was installed as an RTEMS interrupt handler, then upon
     481receipt of the interrupt, the processor passes control to the RTEMS interrupt
     482handler which performs the following actions:
    546483
    547484- saves the state of the interrupted task on it's stack,
     
    549486- switches the processor to trap level 0,
    550487
    551 - if this is the outermost (i.e. non-nested) interrupt,
    552   then the RTEMS interrupt handler switches from the current stack
    553   to the interrupt stack,
     488- if this is the outermost (i.e. non-nested) interrupt, then the RTEMS
     489  interrupt handler switches from the current stack to the interrupt stack,
    554490
    555491- enables traps,
     
    557493- invokes the vectors to a user interrupt service routine (ISR).
    558494
    559 Asynchronous interrupts are ignored while traps are
    560 disabled.  Synchronous traps which occur while traps are
    561 disabled may result in the CPU being forced into an error mode.
    562 
    563 A nested interrupt is processed similarly with the
    564 exception that the current stack need not be switched to the
    565 interrupt stack.
     495Asynchronous interrupts are ignored while traps are disabled.  Synchronous
     496traps which occur while traps are disabled may result in the CPU being forced
     497into an error mode.
     498
     499A nested interrupt is processed similarly with the exception that the current
     500stack need not be switched to the interrupt stack.
    566501
    567502Traps and Register Windows
     
    573508----------------
    574509
    575 Sixteen levels (0-15) of interrupt priorities are
    576 supported by the SPARC architecture with level fifteen (15)
    577 being the highest priority.  Level zero (0) indicates that
    578 interrupts are fully enabled.  Interrupt requests for interrupts
    579 with priorities less than or equal to the current interrupt mask
     510Sixteen levels (0-15) of interrupt priorities are supported by the SPARC
     511architecture with level fifteen (15) being the highest priority.  Level
     512zero (0) indicates that interrupts are fully enabled.  Interrupt requests for
     513interrupts with priorities less than or equal to the current interrupt mask
    580514level are ignored.
    581515
    582 Although RTEMS supports 256 interrupt levels, the
    583 SPARC only supports sixteen.  RTEMS interrupt levels 0 through
    584 15 directly correspond to SPARC processor interrupt levels.  All
    585 other RTEMS interrupt levels are undefined and their behavior is
    586 unpredictable.
     516Although RTEMS supports 256 interrupt levels, the SPARC only supports sixteen.
     517RTEMS interrupt levels 0 through 15 directly correspond to SPARC processor
     518interrupt levels.  All other RTEMS interrupt levels are undefined and their
     519behavior is unpredictable.
    587520
    588521Disabling of Interrupts by RTEMS
     
    594527---------------
    595528
    596 The SPARC architecture does not provide for a
    597 dedicated interrupt stack.  Thus by default, trap handlers would
    598 execute on the stack of the RTEMS task which they interrupted.
    599 This artificially inflates the stack requirements for each task
    600 since EVERY task stack would have to include enough space to
    601 account for the worst case interrupt stack requirements in
    602 addition to it's own worst case usage.  RTEMS addresses this
    603 problem on the SPARC by providing a dedicated interrupt stack
    604 managed by software.
    605 
    606 During system initialization, RTEMS allocates the
    607 interrupt stack from the Workspace Area.  The amount of memory
    608 allocated for the interrupt stack is determined by the
    609 interrupt_stack_size field in the CPU Configuration Table.  As
    610 part of processing a non-nested interrupt, RTEMS will switch to
    611 the interrupt stack before invoking the installed handler.
    612 
    613 .. COMMENT: COPYRIGHT (c) 1988-2002.
    614 
    615 .. COMMENT: On-Line Applications Research Corporation (OAR).
    616 
    617 .. COMMENT: All rights reserved.
     529The SPARC architecture does not provide for a dedicated interrupt stack.  Thus
     530by default, trap handlers would execute on the stack of the RTEMS task which
     531they interrupted.  This artificially inflates the stack requirements for each
     532task since EVERY task stack would have to include enough space to account for
     533the worst case interrupt stack requirements in addition to it's own worst case
     534usage.  RTEMS addresses this problem on the SPARC by providing a dedicated
     535interrupt stack managed by software.
     536
     537During system initialization, RTEMS allocates the interrupt stack from the
     538Workspace Area.  The amount of memory allocated for the interrupt stack is
     539determined by the interrupt_stack_size field in the CPU Configuration Table.
     540As part of processing a non-nested interrupt, RTEMS will switch to the
     541interrupt stack before invoking the installed handler.
    618542
    619543Default Fatal Error Processing
    620544==============================
    621545
    622 Upon detection of a fatal error by either the
    623 application or RTEMS the fatal error manager is invoked.  The
    624 fatal error manager will invoke the user-supplied fatal error
    625 handlers.  If no user-supplied handlers are configured,  the