[[!tag standards]]

# SPRs <a name="sprs"></a>

Note Power ISA v3.1 p12:

     The designated SPR sandbox consists of non-privileged SPRs
     704-719 and privileged SPRs 720-735.

There are eight SPRs, available in any privilege level:

* SVSTATE (containing copies of MVL, VL and SUBVL as well as context information)
* SVSRR0 which is used for exceptions and traps to store SVSTATE.
* SVLR, a mirror of LR, used by Vectorised Branch
* SVSHAPE0-3 for REMAP purposes, re-shaping Vector loops
* SVREMAP for applying specific shapes to specific registers

If SVSTATE is all zeros then SV is disabled and the contents of the
other SPRs SVSHAPE/SVREMAP are ignored.

For Privilege Levels (trap handling) there are the following SPRs,
where x may be u, s or h for User, Supervisor or Hypervisor
Modes respectively:

* (x)eSTATE (useful for saving and restoring during context switch,
  and for providing fast transitions)

The u/s SPRs are treated and handled exactly like their (x)epc
equivalents.  On entry to or exit from a privilege level, the contents
of its (x)eSTATE are swapped with SVSTATE.

# SVSTATE

This is a standard SPR that (REMAP aside) contains sufficient information for a
full context save/restore (see SVSRR0).  It contains (and permits setting of):

* MVL (the Maximum Vector Length) - declares (statically) how
  much of a regfile is to be reserved for Vector elements
* VL - Vector Length
* dststep - the destination element offset of the current parallel
  instruction being executed
* srcstep - for twin-predication, the source element offset as well.
* ssubstep - the source subvector element offset of the current
  parallel instruction being executed
* dsubstep - the destination subvector element offset of the current
  parallel instruction being executed
* vfirst - Vertical First mode.  srcstep, dststep and substep
    **do not advance** unless explicitly requested to do so with
    pseudo-op svstep (a mode of setvl)
* RMpst - REMAP persistence.  REMAP will apply only to the following
  instruction unless this bit is set, in which case REMAP "persists".
  Reset (cleared) on use of the `setvl` instruction if used to
  alter VL or MVL.
* Pack - if set then srcstep/substep VL/SUBVL loop-ordering is inverted.
* UnPack - if set then dststep/substep VL/SUBVL loop-ordering is inverted.
* hphint - Horizontal Parallelism Hint. Indicates that
  no Hazards exist between these elements. In Vertical First Mode
   hardware **MUST** perform this many elements in parallel
   per instruction. Set to zero to indicate "no hint".
* SVme - REMAP enable bits, indicating which register is to be
 REMAPed.  RA, RB, RC, RT or EA.
* mi0-mi4 - when the corresponding SVme bit is enabled, mi0-mi4
  indicate the SVSHAPE (0-3) that the corresponding register (RA etc)
  should use.

**MAXVECTORLENGTH (MVL)** <a name="mvl" />

MAXVECTORLENGTH is the same concept as MVL in RVV, except that it
is variable length and may be dynamically set.  MVL is
however limited to the regfile bitwidth, 64.

**Vector Length (VL)** <a name="vl" />

VSETVL is slightly different from RVV.  Similar to RVV, VL is set to be within
the range 0 <= VL <= MVL (where MVL in turn is limited to 1 <= MVL <= XLEN)

    VL = rd = MIN(vlen, MVL)

where 1 <= MVL <= XLEN

**SUBVL - Sub Vector Length**

This is a "group by quantity" that effectively asks each iteration
of the hardware loop to load SUBVL elements of width elwidth at a
time. Effectively, SUBVL is like a SIMD multiplier: instead of just 1
operation issued, SUBVL operations are issued.

The main effect of SUBVL is that predication bits are applied per
**group**, rather than by individual element.  Legal values are 1 to 4.
Illegal values raise an exception.

**Horizontal Parallelism**

A problem exists for hardware where it may not be able to detect
that a programmer (or compiler) knows of opportunities for parallelism
and lack of overlap between loops.

For hphint, the number chosen must be consistently
executed **every time**. Hardware is not permitted to execute five
computations for one instruction then three on the next.
hphint is a hint from the compiler to hardware that exactly this
many elements may be safely executed in parallel, without hazards
(including Memory accesses).
Interestingly, when hphint is set equal to VL, it is in effect
as if Vertical First mode were not set, because the hardware is
given the option to run through all elements in an instruction.
This is exactly what Horizontal-First is: a for-loop from 0 to VL-1
except that the hardware may *choose* the number of elements.

*Note to programmers: changing VL during the middle of such modes
should be done only with due care and respect for the fact that SVSTATE
has exactly the same peer-level status as a Program Counter.*

**SVSTATE SPR**

The format of the SVSTATE SPR is as follows:

| Field | Name     | Description           |
| ----- | -------- | --------------------- |
| 0:6   | maxvl    | Max Vector Length     |
| 7:13  |    vl    | Vector Length         |
| 14:20 | srcstep  | for srcstep = 0..VL-1 |
| 21:27 | dststep  | for dststep = 0..VL-1 |
| 28:29 | dsubstep | for substep = 0..SUBVL-1  |
| 30:31 | ssubstep | for substep = 0..SUBVL-1  |
| 32:33 | mi0      | REMAP RA SVSHAPE0-3    |
| 34:35 | mi1      | REMAP RB SVSHAPE0-3    |
| 36:37 | mi2      | REMAP RC SVSHAPE0-3    |
| 38:39 | mo0      | REMAP RT SVSHAPE0-3    |
| 40:41 | mo1      | REMAP EA SVSHAPE0-3    |
| 42:46 | SVme     | REMAP enable (RA-RT)  |
| 47:52 | rsvd     | reserved              |
| 53    | pack     | PACK (srcstrp reorder)  |
| 54    | unpack   | UNPACK (dststep order)  |
| 55:61 | hphint   | Horizontal Hint       |
| 62    | RMpst    | REMAP persistence     |
| 63    | vfirst   | Vertical First mode   |

Notes:

* The entries are truncated to be within range.  Attempts to set VL to
  greater than MAXVL will truncate VL.
* Setting srcstep, dststep to 64 or greater, or VL or MVL to greater
  than 64 is reserved and will cause an illegal instruction trap.

# SVSRR0

In scalar v3.0B traps, exceptions and interrupts, two SRRs are saved/restored:

* SRR0 to store the PC (CIA/NIA)
* SRR1 to store a copy of the MSR

Given that SVSTATE is effectively a Sub-PC it is critically important to add saving/restoring of SVSTATE as a full peer equal in status to PC, in every way.  At any time PC is saved or restored, so is SVSTATE in **exactly** the same way for **exactly** the same reasons.  Thus, at an exception point,
hardware **must** save/restore SVSTATE in SVSRR0 at exactly the same
time that SRR0 is saved/restored in PC and SRR1 in MSR.

The SPR name given for the purposes of saving/restoring
SVSTATE is SVSRR0.

# SVLR

SV Link Register, exactly analogous to LR (Link Register) may
be used for temporary storage of SVSTATE, and, in particular,
Vectorised Branch-Conditional instructions may interchange
SVLR and SVSTATE whenever LR and NIA are.

Note that there is no equivalent Link variant of SVREMAP or
SVSHAPE0-3 (it would be too costly), so SVLR has limited applicability:
REMAP SPRs must be saved and restored explicitly.