rtems-docs/cpu_supplement/sparc64.rst

SPARC-64 Specific Information
#############################

This document discusses the SPARC Version 9 (aka SPARC-64, SPARC64 or SPARC V9)
architecture dependencies in this port of RTEMS.

The SPARC V9 architecture leaves a lot of undefined implemenation dependencies
which are defined by the processor models. Consult the specific CPU model
section in this document for additional documents covering the implementation
dependent architectural features.

**sun4u Specific Information**

sun4u is the subset of the SPARC V9 implementations comprising the UltraSPARC I
through UltraSPARC IV processors.

The following documents were used in developing the SPARC-64 sun4u port:

- UltraSPARC  User’s Manual
  (http://www.sun.com/microelectronics/manuals/ultrasparc/802-7220-02.pdf)

- UltraSPARC IIIi Processor (datasheets.chipdb.org/Sun/UltraSparc-IIIi.pdf)

**sun4v Specific Information**

sun4v is the subset of the SPARC V9 implementations comprising the
UltraSPARC T1 or T2 processors.

The following documents were used in developing the SPARC-64 sun4v port:

- UltraSPARC Architecture 2005 Specification
  (http://opensparc-t1.sunsource.net/specs/UA2005-current-draft-P-EXT.pdf)

- UltraSPARC T1 supplement to UltraSPARC Architecture 2005 Specification
  (http://opensparc-t1.sunsource.net/specs/UST1-UASuppl-current-draft-P-EXT.pdf)

The defining feature that separates the sun4v architecture from its
predecessor is the existence of a super-privileged hypervisor that
is responsible for providing virtualized execution environments.  The impact
of the hypervisor on the real-time guarantees available with sun4v has not
yet been determined.

CPU Model Dependent Features
============================

CPU Model Feature Flags
-----------------------

This section presents the set of features which vary across
SPARC-64 implementations and
are of importance to RTEMS. The set of CPU model feature macros
are defined in the file
cpukit/score/cpu/sparc64/sparc64.h based upon the particular
CPU model defined on the compilation command line.

CPU Model Name
~~~~~~~~~~~~~~

The macro CPU MODEL NAME is a string which designates
the name of this CPU model.
For example, for the UltraSPARC T1 SPARC V9 model,
this macro is set to the string "sun4v".

Floating Point Unit
~~~~~~~~~~~~~~~~~~~

The macro SPARC_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise.

Number of Register Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~

The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to
indicate the number of register window sets implemented by this
CPU model.  The SPARC architecture allows for a maximum of
thirty-two register window sets although most implementations
only include eight.

CPU Model Implementation Notes
------------------------------

This section describes the implemenation dependencies of the
CPU Models sun4u and sun4v of the SPARC V9 architecture.

sun4u Notes
~~~~~~~~~~~

XXX

sun4v Notes
-----------

XXX

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Calling Conventions
===================

Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler’s calling convention.   These rules address the
following issues:

- register preservation and usage

- parameter passing

- call and return mechanism

A compiler’s calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level.  Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions.  As a result, calling conventions
are both processor and compiler dependent.

The following document also provides some conventions on the
global register usage in SPARC V9:
http://developers.sun.com/solaris/articles/sparcv9abi.html

Programming Model
-----------------

This section discusses the programming model for the
SPARC architecture.

Non-Floating Point Registers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The SPARC architecture defines thirty-two
non-floating point registers directly visible to the programmer.
These are divided into four sets:

- input registers

- local registers

- output registers

- global registers

Each register is referred to by either two or three
names in the SPARC reference manuals.  First, the registers are
referred to as r0 through r31 or with the alternate notation
r[0] through r[31].  Second, each register is a member of one of
the four sets listed above.  Finally, some registers have an
architecturally defined role in the programming model which
provides an alternate name.  The following table describes the
mapping between the 32 registers and the register sets:

.. code:: c

    +-----------------+----------------+------------------+
    | Register Number | Register Names |   Description    |
    +-----------------+----------------+------------------+
    |     0 - 7       |    g0 - g7     | Global Registers |
    +-----------------+----------------+------------------+
    |     8 - 15      |    o0 - o7     | Output Registers |
    +-----------------+----------------+------------------+
    |    16 - 23      |    l0 - l7     | Local Registers  |
    +-----------------+----------------+------------------+
    |    24 - 31      |    i0 - i7     | Input Registers  |
    +-----------------+----------------+------------------+

As mentioned above, some of the registers serve
defined roles in the programming model.  The following table
describes the role of each of these registers:

.. code:: c

    +---------------+----------------+----------------------+
    | Register Name | Alternate Name |      Description     |
    +---------------+----------------+----------------------+
    |     g0        |      na        |    reads return 0    |
    |               |                |  writes are ignored  |
    +---------------+----------------+----------------------+
    |     o6        |      sp        |     stack pointer    |
    +---------------+----------------+----------------------+
    |     i6        |      fp        |     frame pointer    |
    +---------------+----------------+----------------------+
    |     i7        |      na        |    return address    |
    +---------------+----------------+----------------------+

Floating Point Registers
~~~~~~~~~~~~~~~~~~~~~~~~

The SPARC V9 architecture includes sixty-four,
thirty-two bit registers.  These registers may be viewed as
follows:

- 32 32-bit single precision floating point or integer registers
  (f0, f1,  ... f31)

- 32 64-bit double precision floating point registers (f0, f2,
  f4, ... f62)

- 16 128-bit extended precision floating point registers (f0, f4,
  f8, ... f60)

The floating point state register (fsr) specifies
the behavior of the floating point unit for rounding, contains
its condition codes, version specification, and trap information.

Special Registers
~~~~~~~~~~~~~~~~~

The SPARC architecture includes a number of special registers:

*``Ancillary State Registers (ASRs)``*
    The ancillary state registers (ASRs) are optional state registers that
    may be privileged or nonprivileged. ASRs 16-31 are implementation-
    dependent. The SPARC V9 ASRs include: y, ccr, asi, tick, pc, fprs.
    The sun4u ASRs include: pcr, pic, dcr, gsr, softint set, softint clr,
    softint, and tick cmpr. The sun4v ASRs include: pcr, pic, gsr, soft-
    int set, softint clr, softint, tick cmpr, stick, and stick cmpr.

*``Processor State Register (pstate)``*
    The privileged pstate register contains control fields for the proces-
    sor’s current state. Its flag fields include the interrupt enable, privi-
    leged mode, and enable FPU.

*``Processor Interrupt Level (pil)``*
    The PIL specifies the interrupt level above which interrupts will be
    accepted.

*``Trap Registers``*
    The trap handling mechanism of the SPARC V9 includes a number of
    registers, including: trap program counter (tpc), trap next pc (tnpc),
    trap state (tstate), trap type (tt), trap base address (tba), and trap
    level (tl).

*``Alternate Globals``*
    The AG bit of the pstate register provides access to an alternate set
    of global registers. On sun4v, the AG bit is replaced by the global
    level (gl) register, providing access to at least two and at most eight
    alternate sets of globals.

*``Register Window registers``*
    A number of registers assist in register window management.
    These include the current window pointer (cwp), savable windows
    (cansave), restorable windows (canrestore), clean windows (clean-
    win), other windows (otherwin), and window state (wstate).

Register Windows
----------------

The SPARC architecture includes the concept of
register windows.  An overly simplistic way to think of these
windows is to imagine them as being an infinite supply of
"fresh" register sets available for each subroutine to use.  In
reality, they are much more complicated.

The save instruction is used to obtain a new register window.
This instruction increments the current window pointer, thus
providing a new set of registers for use. This register set
includes eight fresh local registers for use exclusively by
this subroutine. When done with a register set, the restore
instruction decrements the current window pointer and the
previous register set is once again available.

The two primary issues complicating the use of register windows
are that (1) the set of register windows is finite, and (2) some
registers are shared between adjacent registers windows.

Because the set of register windows is finite, it is
possible to execute enough save instructions without
corresponding restore’s to consume all of the register windows.
This is easily accomplished in a high level language because
each subroutine typically performs a save instruction upon
entry.  Thus having a subroutine call depth greater than the
number of register windows will result in a window overflow
condition.  The window overflow condition generates a trap which
must be handled in software.  The window overflow trap handler
is responsible for saving the contents of the oldest register
window on the program stack.

Similarly, the subroutines will eventually complete
and begin to perform restore’s.  If the restore results in the
need for a register window which has previously been written to
memory as part of an overflow, then a window underflow condition
results.  Just like the window overflow, the window underflow
condition must be handled in software by a trap handler.  The
window underflow trap handler is responsible for reloading the
contents of the register window requested by the restore
instruction from the program stack.

The cansave, canrestore, otherwin, and cwp are used in conjunction
to manage the finite set of register windows and detect the window
overflow and underflow conditions. The first three of these
registers must satisfy the invariant cansave + canrestore + otherwin =
nwindow - 2, where nwindow is the number of register windows.
The cwp contains the index of the register window currently in use.
RTEMS does not use the cleanwin and otherwin registers.

The save instruction increments the cwp modulo the number of
register windows, and if cansave is 0 then it also generates a
window overflow. Similarly, the restore instruction decrements the
cwp modulo the number of register windows, and if canrestore is 0 then it
also generates a window underflow.

Unlike with the SPARC model, the SPARC-64 port does not assume that
a register window is available for a trap. The window overflow
and underflow conditions are not detected without hardware generating
the trap. (These conditions can be detected by reading the register window
registers and doing some simple arithmetic.)

The window overflow and window underflow trap
handlers are a critical part of the run-time environment for a
SPARC application.  The SPARC architectural specification allows
for the number of register windows to be any power of two less
than or equal to 32.  The most common choice for SPARC
implementations appears to be 8 register windows.  This results
in the cwp ranging in value from 0 to 7 on most implementations.

The second complicating factor is the sharing of
registers between adjacent register windows.  While each
register window has its own set of local registers, the input
and output registers are shared between adjacent windows.  The
output registers for register window N are the same as the input
registers for register window ((N + 1) modulo RW) where RW is
the number of register windows.  An alternative way to think of
this is to remember how parameters are passed to a subroutine on
the SPARC.  The caller loads values into what are its output
registers.  Then after the callee executes a save instruction,
those parameters are available in its input registers.  This is
a very efficient way to pass parameters as no data is actually
moved by the save or restore instructions.

Call and Return Mechanism
-------------------------

The SPARC architecture supports a simple yet
effective call and return mechanism.  A subroutine is invoked
via the call (call) instruction.  This instruction places the
return address in the caller’s output register 7 (o7).  After
the callee executes a save instruction, this value is available
in input register 7 (i7) until the corresponding restore
instruction is executed.

The callee returns to the caller via a jmp to the
return address.  There is a delay slot following this
instruction which is commonly used to execute a restore
instruction – if a register window was allocated by this
subroutine.

It is important to note that the SPARC subroutine
call and return mechanism does not automatically save and
restore any registers.  This is accomplished via the save and
restore instructions which manage the set of registers windows.
This allows for the compiler to generate leaf-optimized functions
that utilize the caller’s output registers without using save and restore.

Calling Mechanism
-----------------

All RTEMS directives are invoked using the regular
SPARC calling convention via the call instruction.

Register Usage
--------------

As discussed above, the call instruction does not
automatically save any registers.  The save and restore
instructions are used to allocate and deallocate register
windows.  When a register window is allocated, the new set of
local registers are available for the exclusive use of the
subroutine which allocated this register set.

Parameter Passing
-----------------

RTEMS assumes that arguments are placed in the
caller’s output registers with the first argument in output
register 0 (o0), the second argument in output register 1 (o1),
and so forth.  Until the callee executes a save instruction, the
parameters are still visible in the output registers.  After the
callee executes a save instruction, the parameters are visible
in the corresponding input registers.  The following pseudo-code
illustrates the typical sequence used to call a RTEMS directive
with three (3) arguments:
.. code:: c

    load third argument into o2
    load second argument into o1
    load first argument into o0
    invoke directive

User-Provided Routines
----------------------

All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Memory Model
============

A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems.  RTEMS supports a flat memory
model which ranges contiguously over the processor’s allowable
address space.  RTEMS does not support segmentation or virtual
memory of any kind.  The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.

Flat Memory Model
-----------------

The SPARC-64 architecture supports a flat 64-bit address space with
addresses ranging from 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF.
Each address is represented by a 64-bit value (and an 8-bit address
space identifider or ASI) and is byte addressable. The address
may be used to reference a single byte, half-word (2-bytes),
word (4 bytes), doubleword (8 bytes), or quad-word (16 bytes).
Memory accesses within this address space are performed
in big endian fashion by the SPARC. Memory accesses which are not
properly aligned generate a "memory address not aligned" trap
(type number 0x34). The following table lists the alignment
requirements for a variety of data accesses:

.. code:: c

    +--------------+-----------------------+
    |   Data Type  | Alignment Requirement |
    +--------------+-----------------------+
    |     byte     |          1            |
    |   half-word  |          2            |
    |     word     |          4            |
    |  doubleword  |          8            |
    |   quadword   |          16           |
    +--------------+-----------------------+

RTEMS currently does not support any SPARC Memory Management
Units, therefore, virtual memory or segmentation systems
involving the SPARC are not supported.

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Interrupt Processing
====================

RTEMS and associated documentation uses the terms
interrupt and vector.  In the SPARC architecture, these terms
correspond to traps and trap type, respectively.  The terms will
be used interchangeably in this manual. Note that in the SPARC manuals,
interrupts are a subset of the traps that are delivered to software
interrupt handlers.

Synchronous Versus Asynchronous Traps
-------------------------------------

The SPARC architecture includes two classes of traps:
synchronous (precise) and asynchronous (deferred).
Asynchronous traps occur when an
external event interrupts the processor.  These traps are not
associated with any instruction executed by the processor and
logically occur between instructions.  The instruction currently
in the execute stage of the processor is allowed to complete
although subsequent instructions are annulled.  The return
address reported by the processor for asynchronous traps is the
pair of instructions following the current instruction.

Synchronous traps are caused by the actions of an
instruction.  The trap stimulus in this case either occurs
internally to the processor or is from an external signal that
was provoked by the instruction.  These traps are taken
immediately and the instruction that caused the trap is aborted
before any state changes occur in the processor itself.   The
return address reported by the processor for synchronous traps
is the instruction which caused the trap and the following
instruction.

Vectoring of Interrupt Handler
------------------------------

Upon receipt of an interrupt the SPARC automatically
performs the following actions:

- The trap level is set. This provides access to a fresh set of
  privileged trap-state registers used to save the current state,
  in effect, pushing a frame on the trap stack.
  TL <- TL + 1

- Existing state is preserved
  - TSTATE[TL].CCR <- CCR
  - TSTATE[TL].ASI <- ASI
  - TSTATE[TL].PSTATE <- PSTATE
  - TSTATE[TL].CWP <- CWP
  - TPC[TL] <- PC
  - TNPC[TL] <- nPC

- The trap type is preserved. TT[TL] <- the trap type

- The PSTATE register is updated to a predefined state
  - PSTATE.MM is unchanged
  - PSTATE.RED <- 0
  - PSTATE.PEF <- 1 if FPU is present, 0 otherwise
  - PSTATE.AM <- 0 (address masking is turned off)
  - PSTATE.PRIV <- 1 (the processor enters privileged mode)
  - PSTATE.IE <- 0 (interrupts are disabled)
  - PSTATE.AG <- 1 (global regs are replaced with alternate globals)
  - PSTATE.CLE <- PSTATE.TLE (set endian mode for traps)

- For a register-window trap only, CWP is set to point to the register
  window that must be accessed by the trap-handler software, that is:

  - If TT[TL] = 0x24 (a clean window trap), then CWP <- CWP + 1.
  - If (0x80 <= TT[TL] <= 0xBF) (window spill trap), then CWP <- CWP +
    CANSAVE + 2.
  - If (0xC0 <= TT[TL] <= 0xFF) (window fill trap), then CWP <- CWP1.
  - For non-register-window traps, CWP is not changed.

- Control is transferred into the trap table:

  - PC <- TBA<63:15> (TL>0) TT[TL] 0 0000
  - nPC <- TBA<63:15> (TL>0) TT[TL] 0 0100
  - where (TL>0) is 0 if TL = 0, and 1 if TL > 0.

In order to safely invoke a subroutine during trap handling, traps must be
enabled to allow for the possibility of register window overflow and
underflow traps.

If the interrupt handler was installed as an RTEMS
interrupt handler, then upon receipt of the interrupt, the
processor passes control to the RTEMS interrupt handler which
performs the following actions:

- saves the state of the interrupted task on it’s stack,

- switches the processor to trap level 0,

- if this is the outermost (i.e. non-nested) interrupt,
  then the RTEMS interrupt handler switches from the current stack
  to the interrupt stack,

- enables traps,

- invokes the vectors to a user interrupt service routine (ISR).

Asynchronous interrupts are ignored while traps are
disabled.  Synchronous traps which occur while traps are
disabled may result in the CPU being forced into an error mode.

A nested interrupt is processed similarly with the
exception that the current stack need not be switched to the
interrupt stack.

Traps and Register Windows
--------------------------

XXX

Interrupt Levels
----------------

Sixteen levels (0-15) of interrupt priorities are
supported by the SPARC architecture with level fifteen (15)
being the highest priority.  Level zero (0) indicates that
interrupts are fully enabled.  Interrupt requests for interrupts
with priorities less than or equal to the current interrupt mask
level are ignored.

Although RTEMS supports 256 interrupt levels, the
SPARC only supports sixteen.  RTEMS interrupt levels 0 through
15 directly correspond to SPARC processor interrupt levels.  All
other RTEMS interrupt levels are undefined and their behavior is
unpredictable.

Disabling of Interrupts by RTEMS
--------------------------------

XXX

Interrupt Stack
---------------

The SPARC architecture does not provide for a
dedicated interrupt stack.  Thus by default, trap handlers would
execute on the stack of the RTEMS task which they interrupted.
This artificially inflates the stack requirements for each task
since EVERY task stack would have to include enough space to
account for the worst case interrupt stack requirements in
addition to it’s own worst case usage.  RTEMS addresses this
problem on the SPARC by providing a dedicated interrupt stack
managed by software.

During system initialization, RTEMS allocates the
interrupt stack from the Workspace Area.  The amount of memory
allocated for the interrupt stack is determined by the
interrupt_stack_size field in the CPU Configuration Table.  As
part of processing a non-nested interrupt, RTEMS will switch to
the interrupt stack before invoking the installed handler.

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Default Fatal Error Processing
==============================

Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked.  The
fatal error manager will invoke the user-supplied fatal error
handlers.  If no user-supplied handlers are configured,  the
RTEMS provided default fatal error handler is invoked.  If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked.  This chapter
describes the precise operations of the default fatal error
handler.

Default Fatal Error Handler Operations
--------------------------------------

The default fatal error handler which is invoked by
the fatal_error_occurred directive when there is no user handler
configured or the user handler returns control to RTEMS.  The
default fatal error handler disables processor interrupts to
level 15, places the error code in g1, and goes into an infinite
loop to simulate a halt processor instruction.

Symmetric Multiprocessing
=========================

SMP is not supported.

Thread-Local Storage
====================

Thread-local storage is supported.

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Board Support Packages
======================

An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of SPARC specific BSP issues.
For more information on developing a BSP, refer to the chapter
titled Board Support Packages in the RTEMS
Applications User’s Guide.

HelenOS and Open Firmware
-------------------------

The provided BSPs make use of some bootstrap and low-level hardware code
of the HelenOS operating system. These files can be found in the shared/helenos
directory of the sparc64 bsp directory.  Consult the sources for more
detailed information.

The shared BSP code also uses the Open Firmware interface to re-use firmware
code, primarily for console support and default trap handlers.