View source for S-DSP registers


The S-DSP registers are accessed via the [[S-SMP#$F2-F3_DSP|<tt>DSPADDR</tt> and <tt>DSPDATA</tt>]] S-SMP registers.

{| class="wikitable"
|+ S-DSP global register summary
|-
! colspan=2 | Name
! Address
! Bits
! Type
! Notes
|-
{{:APU register table/DSP global}}
|-
! colspan=6 | <small>([[APU register table/DSP global|table source]])</small>
|}


There are 8 voices, numbered 0 to 7. Each voice X has 10 registers in the range $X0-$X9. 

{| class="wikitable"
|+ S-DSP voice register summary
|-
! colspan=2 | Name
! Address
! Bits
! Type
! Notes
|-
{{:APU register table/DSP voice}}
|-
! colspan=6 | <small>([[APU register table/DSP voice|table source]])</small>
|}


Register types:
* '''RW''' - Readable and Writable
* '''R''' - Readable (technically writable, but not intended to be written to)


== Reading and writing S-DSP registers ==

The S-DSP registers are accessed via the [[S-SMP#$F2-F3_DSP|<tt>DSPADDR</tt> and <tt>DSPDATA</tt>]] S-SMP registers.

Writing to the S-SMP <tt>$F2</tt> <tt>DSPADDR</tt> register will set the selected S-DSP register address.  The S-SMP <tt>$F3</tt> <tt>DSPDATA</tt> register is then used to read or write the selected S-DSP register.


CAUTIONS:
* Writing to <tt>DSPADDR</tt> with the high bit set will disable <tt>DSPDATA</tt> writes.
* Reading <tt>DSPDATA</tt> will return the value stored in the S-DSP's 128 byte register memory.  Some <tt>DSPDATA</tt> reads might not match the internal S-DSP state until the S-DSP register has been written to.
* S-DSP registers are polled by the S-DSP at different points within the 32-cycle sample loop.
** Most S-DSP register writes do not take effect immediately.
** Some S-DSP registers are polled every second sample.
** Overriding a S-DSP register write too early can skip the previous S-DSP register write (with audible glitches with the <tt>KON</tt>, <tt>KOFF</tt> registers).
** The echo buffer registers are polled at unexpected times and should be treated with care.


<pre>
    ; Select the KON ($4c) S-DSP register
    mov  a,       #$4c
    mov  DSPADDR, a

    ; Write 1 to the KON S-DSP register
    mov  a,       #$01
    mov  DSPDATA, a
</pre>


The SPC-700 direct page move instructions can be used to simplify S-DSP register writes.

<pre>
    ; Write zpTmp to the MVOLL ($0c) and MVOLR ($1c) S-DSP registers

    mov  DSPADDR, #$0c              ; Select MVOLL register
    mov  DSPDATA, zpTmp             ; Write zpTmp to MVOLL

    mov  DSPADDR, #$1c              ; Select MVOLR register
    mov  DSPDATA, zpTmp             ; Write zpTmp to MVOLR
</pre>


The <tt>movw dp,ya</tt> 16 bit write instruction can be used to write to <tt>DSPADDR</tt> and <tt>DSPDATA</tt> in a single SPC-700 instruction.
<tt>movw DSPADDR,ya</tt> will write '''A''' to <tt>DSPADDR</tt> and '''Y''' to <tt>DSPDATA</tt>.
This instruction is useful when setting multiple S-DSP registers to the same value.

<pre>
    mov  y,       #$7f

    ; Write Y to the MVOLL ($0c) and MVOLR ($1c) S-DSP registers

    mov  a,       #$0c
    movw DSPADDR, ya                ; DSPADDR = a, DSPDATA = y

    mov  a,       #$1c
    movw DSPADDR, ya                ; DSPADDR = a, DSPDATA = y
</pre>


Another advantage of <tt>movw DSPADDR,ya</tt> is that you can do arithmetic on <tt>A</tt> to select the next <tt>DSPADDR</tt> to write to.  For example, incrementing <tt>A</tt> by 1 to select the next voice S-DSP register or adding $10 to <tt>A</tt> to select the next global S-DSP register.

<pre>
    mov  y,       #100

    ; Write Y to the VxVOLL ($x0) and VxVOLR ($x1) S-DSP registers

    mov  a,       #(voice << 4)     ; a = $x0

    movw DSPADDR, ya                ; DSPADDR = a, DSPDATA = y
    inc  a                          ; a = $x1
    movw DSPADDR, ya                ; DSPADDR = a, DSPDATA = y
</pre>


The <tt>DSPADDR</tt> register is readable and writable.  The direct-page read-modify-write SPC-700 instructions can be applied to the <tt>DSPADDR</tt> register to advance the selected S-DSP register without modifying the <tt>A</tt>, <tt>X</tt> or <tt>Y</tt> registers.

<pre>
    ; Copy 8 bytes from `zpPtr` to the FIR S-DSP registers

    mov  y,       #0

    ; Select C0 ($0f) S-DSP register
    mov  DSPADDR, #$0f

    Loop:
        ; Write zpPtr[y] to the S-DSP
        mov  a,       [zpPtr]+y
        mov  DSPDATA, a
        inc  y

        ; Add $10 to DSPADDR and loop if DSPADDR <= $7f (C7 S-DSP register)
        clrc
        adc  DSPADDR, #$10
        bpl  Loop
</pre>


Finally, the <tt>DSPDATA</tt> register is readable and writeable.  Allowing modifications of S-DSP registers without shadow variables.

<pre>
    ; Enable noise on selected voices
    ; IN: A = bitmask of voices to enable

    ; Select NON ($3d) S-DSP register
    mov  DSPADDR, #$3d

    ; DSPDATA = DSPDATA | a
    or   a,       DSPDATA
    mov  DSPDATA, a
</pre>

<pre>
    ; Adds 8 bit `Y` to voice `A`'s VxPITCH registers
    ; IN: A = voice to change
    ; IN: Y = amount to add to VxPITCH
    ; REQUIRES: A < 8

    ; Select VxPITCHL register
    ; DSPADDR = ((A & 7) << 4) | 2
    and  a,       #$07
    xcn  a                          ; swap high and low nibbles of A
    or   a,       #$02
    mov  DSPADDR, a

    ; A = Y
    mov  a,       y

    ; Add A to DSPDATA (VxPITCHL)
    clrc
    adc  a,       DSPDATA
    mov  DSPDATA, a

    bcc  SkipHighByte
        ; Select VxPITCHH by setting bit 0 of DSPADDR. (VxPITCHH = VxPITCHL | 1)
        set1 DSPADDR.0

        ; Increment VxPITCHH register
        inc  DSPDATA
SkipHighByte:
</pre>

== Global registers ==

{{Anchor|MVOL|MVOLL|MVOLH}}
=== MVOLL, MVOLR - Main volume ($0C, $1C) ===

 7  bit  0
 ---- ----
 VVVV VVVV
 |||| ||||
 ++++-++++- left/right channel volume (signed)


{{Anchor|EVOL|EVOLL|EVOLR}}
=== EVOLL, EVOLR - Echo volume ($2C, $3C) ===

 7  bit  0
 ---- ----
 VVVV VVVV
 |||| ||||
 ++++-++++- left/right channel volume (signed)


{{Anchor|KON}}
=== KON - Key on ($4C) ===

 7  bit  0
 ---- ----
 7654 3210
 |||| ||||
 |||| |||+- key-on voice 0
 |||| ||+-- key-on voice 1
 |||| |+--- key-on voice 2
 |||| +---- key-on voice 3
 |||+------ key-on voice 4
 ||+------- key-on voice 5
 |+-------- key-on voice 6
 +--------- key-on voice 7

Writing a 1 to a <tt>KON</tt> voice bit will:
* Set the voice's envelope to 0
* Change the voice's ADSR state to Attack
* Reset the voice's BRR decoder to the start of the sample (as determined by <tt>[[#DIR|DIR]]</tt> and <tt>[[#VxSCRN|VxSCRN]]</tt>)

<tt>KON</tt> is polled every second sample.


ERRATA:<ref>Anomie's S-DSP Doc: KON and KOFF registers</ref>
* Clearing <tt>KON</tt> too early can cause the voice to not key-on.
* If a voice's <tt>KON</tt> and <tt>KOFF</tt> bits are both set; the key-on will be followed by a key-off, silencing the channel.


{{Anchor|KOFF|KOF}}
=== KOFF - Key off ($5C) ===

 7  bit  0
 ---- ----
 7654 3210
 |||| ||||
 |||| |||+- key-off voice 0
 |||| ||+-- key-off voice 1
 |||| |+--- key-off voice 2
 |||| +---- key-off voice 3
 |||+------ key-off voice 4
 ||+------- key-off voice 5
 |+-------- key-off voice 6
 +--------- key-off voice 7

Setting a voice bit in <tt>KON</tt> will:
* Change the voice's envelope state to Release

<tt>KOFF</tt> is polled every second sample.


ERRATA:<ref>Anomie's S-DSP Doc: KON and KOFF registers</ref>
* Clearing <tt>KOFF</tt> too early can cause the voice to not key-off.
* Clearing the <tt>KOFF</tt> bits after writing to <tt>KON</tt> might key-on, key-off or silence the channel.
* If a voice's <tt>KON</tt> and <tt>KOFF</tt> bits are both set; the key-on will be followed by a key-off, silencing the channel.


{{Anchor|FLG}}
=== FLG - Flags register ($6C) ===

 7  bit  0
 ---- ----
 RMEN NNNN
 |||| ||||
 |||+-++++- Noise frequency
 ||+------- Disable echo write
 |+-------- Mute all
 +--------- Soft reset


{{Anchor|ENDX}}
=== ENDX - End of sample flags ($7C, read-only) ===

 7  bit  0
 ---- ----
 7654 3210
 |||| ||||
 |||| |||+- Voice 0 BRR block has end-flag set
 |||| ||+-- Voice 1 BRR block has end-flag set
 |||| |+--- Voice 2 BRR block has end-flag set
 |||| +---- Voice 3 BRR block has end-flag set
 |||+------ Voice 4 BRR block has end-flag set
 ||+------- Voice 5 BRR block has end-flag set
 |+-------- Voice 6 BRR block has end-flag set
 +--------- Voice 7 BRR block has end-flag set

The voice bits are set when the current BRR block has the end-flag set (not at the end of the BRR sample).

If the voice is recently keyed-on, the <tt>ENDX</tt> bits will be clear (even if the BRR sample is a single BRR block).<ref>ares source code, <tt>ares::SuperFamicom::Dsp::voice5()</tt>, by Near and ares team</ref>

<tt>ENDX</tt> is technically writable and not intended to be written to.  The S-DSP updates this register 8 times per sample.


{{Anchor|EFB}}
=== EFB - Echo feedback ($0D) ===

 7  bit  0
 ---- ----
 VVVV VVVV
 |||| ||||
 ++++-++++- echo feedback (signed)


{{Anchor|PMON}}
=== PMON - Pitch modulation enable ($2D) ===

 7  bit  0
 ---- ----
 7654 321-
 |||| |||
 |||| ||+-- Enable pitch modulation on voice 1
 |||| |+--- Enable pitch modulation on voice 2
 |||| +---- Enable pitch modulation on voice 3
 |||+------ Enable pitch modulation on voice 4
 ||+------- Enable pitch modulation on voice 5
 |+-------- Enable pitch modulation on voice 6
 +--------- Enable pitch modulation on voice 7


{{Anchor|NON}}
=== NON - Noise enable ($3D) ===

 7  bit  0
 ---- ----
 7654 3210
 |||| ||||
 |||| |||+- Replace voice 0 with noise generator
 |||| ||+-- Replace voice 1 with noise generator
 |||| |+--- Replace voice 2 with noise generator
 |||| +---- Replace voice 3 with noise generator
 |||+------ Replace voice 4 with noise generator
 ||+------- Replace voice 5 with noise generator
 |+-------- Replace voice 6 with noise generator
 +--------- Replace voice 7 with noise generator


{{Anchor|EON}}
=== EON - Echo enable ($3D) ===

 7  bit  0
 ---- ----
 7654 3210
 |||| ||||
 |||| |||+- Enable echo on voice 0
 |||| ||+-- Enable echo on voice 1
 |||| |+--- Enable echo on voice 2
 |||| +---- Enable echo on voice 3
 |||+------ Enable echo on voice 4
 ||+------- Enable echo on voice 5
 |+-------- Enable echo on voice 6
 +--------- Enable echo on voice 7


{{Anchor|DIR}}
=== DIR - Sample directory page ($5D) ===

 7  bit  0
 ---- ----
 DDDD DDDD
 |||| ||||
 ++++-++++- Page pointer to the sample source directory


{{Anchor|ESA}}
=== ESA - Echo start address ($6D) ===

 7  bit  0
 ---- ----
 EEEE EEEE
 |||| ||||
 ++++-++++- Page pointer to start of the echo buffer


ERRATA:
* Care must be taken when writing to the <tt>EDL</tt> and <tt>ESA</tt> echo buffer registers.
* The <tt>ESA</tt> (echo buffer address) register is accessed once per sample and <tt>ESA</tt> writes can be delayed by a single sample.<ref>Anomie's S-DSP Doc: ESA register</ref>
* The echo buffer wraps around the 16-bit Audio-RAM address boundary, clobbering zeropage.
* The echo buffer will write a minimum 4 bytes to the start of <tt>ESA</tt>, unless echo writes are disabled in <tt>[[#FLG|FLG]]</tt>.
* See <tt>[[#EDL|EDL]]</tt> errata for more details.


{{Anchor|EDL}}
=== EDL - Echo delay ($7D) ===

 7  bit  0
 ---- ----
 ---- DDDD
      ||||
      ++++- Echo delay time (delay = DDDD * 512 samples)

<tt>EDL</tt> controls the size (<tt>DDDD</tt> * 2048 bytes) and length (<tt>DDDD</tt> * 512 samples or 16ms @ 32000Hz) of the echo buffer.


ERRATA:
* Care must be taken when writing to the <tt>EDL</tt> and <tt>ESA</tt> echo buffer registers.
* Setting echo delay (<tt>[[#EDL|EDL]]</tt>, register $7D) to 0 continuously overwrites 4 bytes of ARAM at the start of the echo buffer page (selected by <tt>ESA</tt>, $6D). In particular, <tt>ESA</tt> = $00 and <tt>EDL</tt> = $00 overwrites zero page locations $0000-$0003. If not using echo, remember to set the echo write protect bit of <tt>[[#FLG|FLG]]</tt> ($6C bit 5) to 1.
* <tt>EDL</tt> (echo delay / echo buffer size) register writes take effect when the S-DSP reaches the end of the echo buffer.<ref>Anomie's S-DSP Doc: EDL register</ref>
** Writing to <tt>EDL</tt> can take up to 7680 samples (240ms @ 32000Hz) to take effect.
* The <tt>ESA</tt> (echo buffer address) register is accessed once per sample and <tt>ESA</tt> writes can be delayed by a single sample.<ref>Anomie's S-DSP Doc: ESA register</ref>
* The echo buffer wraps around the 16-bit Audio-RAM address boundary, clobbering zeropage.
* To prevent the echo buffer from clobbering memory when initialing the echo buffer, echo buffer writes should be disabled (<tt>FLG</tt> bit 5 set) before writing to <tt>ESA</tt> and <tt>EDL</tt>.  There should be a minimum 7680 sample (240ms @ 32000Hz) delay before echo buffer writes are enabled (<tt>FLG</tt> bit 5 clear).


{{Anchor|FIR}}
=== C0, C1, C2, C3, C4, C5, C6, C7 - Echo FIR filter coefficients ($xF) ===

 7  bit  0
 ---- ----
 VVVV VVVV
 |||| ||||
 ++++-++++- FIR filter tap (signed)


ERRATA:
* The FIR filter uses a clipped-sum for the first 7 tap calculations and a clamped-sum for only the last tap. <ref>[https://sneslab.net/wiki/FIR_Filter#S-DSP_Implementation SnesLab Wiki - FIR Filter - S-DSP Implementation]</ref>
* This can cause audio clicks if the FIR filter gain exceeds 0dB.
* To prevent FIR clicks ensure the absolute sum of the FIR taps (S-DSP registers <tt>C0</tt>-<tt>C7</tt>) is &lt;= 128.


== Voice registers ==


{{Anchor|VxVOL|VxVOLL|VxVOLR}}
=== VxVOLL, VxVOLR - Voice volume ($x0, $x1) ===

 7  bit  0
 ---- ----
 VVVV VVVV
 |||| ||||
 ++++-++++- left/right channel volume (signed)


{{Anchor|VxPITCH|VxPITCHL|VxPITCHR}}
=== VxPITCHL, VxPITCHH - Voice pitch ($x2, $x3) ===

 15  bit  8   7  bit  0
  ---- ----   ---- ----
  ..PP pppp   pppp pppp
    || ||||   |||| ||||
    ++-++++---++++-++++- Voice pitch (2.12 fixed point)


{{Anchor|VxSRCN}}
=== VxSRCN - Voice sample source ($x4) ===

 7  bit  0
 ---- ----
 SSSS SSSS
 |||| ||||
 ++++-++++- DIR sample source table entry


{{Anchor|VxADSR|VxADSR1|VxADSR2}}
=== VxADSR1, VxADSR2 - ADSR enable and settings ($x5, $x6) ===

  VxADSR1
 7  bit  0
 ---- ----
 EDDD AAAA
 |||| ||||
 |||| ++++- Attack rate (A)
 |+++------ Decay rate (D)
 +--------- ADSR enable

  VxADSR2
 7  bit  0
 ---- ----
 LLLR RRRR
 |||| ||||
 |||+-++++- Sustain rate (SR)
 +++------- Sustain level (SL)

* If the ''ADSR enable'' bit is clear, the envelope is controlled by the <tt>[[#VxGAIN|VxGAIN]]</tt> register.
* If the ''ADSR enable'' bit is set, the envelope will be changed depending on the ADSR state
** '''Attack''':
*** If <tt>AAAA == 15</tt>, Linear increase +1024 at a rate of 31
*** If <tt>AAAA < 15</tt>, Linear increase +32 at a rate of <tt>AAAA1</tt> (equivalent to <tt>VxGAIN == 110_AAAA1</tt>)
** '''Decay''': Exponential decrease at a rate of <tt>1DDD0</tt> (equivalent to <tt>VxGAIN == 101_1DDD0</tt>)
*** ''Sustain level'' controls 
** '''Sustain''': Exponential decrease at a rate of <tt>RRRRR</tt> (equivalent to <tt>VxGAIN == 101_RRRRR</tt>)
** '''Release''': Linear decrease at a fixed rate of -8 every sample.

[[File:Adsr_envelope.svg]]


ERRATA:
* There is a race-condition when changing the ADSR/GAIN envelope mode (bit 7 of <tt>ADSR1</tt>) in the middle of a note.  If the S-DSP registers are written in the order <tt>ADSR1</tt> followed by <tt>ADSR2</tt>/<tt>GAIN</tt>, the S-DSP might read the old <tt>ADSR2</tt>/<tt>GAIN</tt> value before the <tt>ADSR2</tt>/<tt>GAIN</tt> write, potentially glitching the rest of the envelope (especially if the previous <tt>GAIN</tt> was a fixed envelope).<ref>[https://undisbeliever.net/blog/20231231-terrific-audio-driver.html#i-found-a-race-condition Terrific Audio Driver - I found a race condition]</ref>
** Workaround: Write to the <tt>ADSR2</tt>/<tt>GAIN</tt> register before the <tt>ADSR1</tt> register.
** Workaround: Only change the ADSR/GAIN envelope mode bit when the channel is in the release state.


See: [[DSP envelopes]]


{{Anchor|VxGAIN}}
=== VxGAIN - GAIN envelope settings ($x7) ===

 7  bit  0
 ---- ----
 0VVV VVVV
  ||| ||||
  +++ ++++- Fixed envelope
 
 7  bit  0
 ---- ----
 1MMr rrrr
  ||| ||||
  ||+ ++++- GAIN rate
  ++------- GAIN mode

GAIN envelope is used if the <tt>[[#VxADSR1|VxADSR1]]</tt> ''ADSR enable'' bit is clear.

{| class="wikitable"
|+ GAIN modes
! Mode bits || Name || envelope change per rate
|-
| <tt>0??</tt> || Fixed || envelope = <tt>VVVVVVV << 4</tt> every sample
|-
| <tt>100</tt> || Linear decrease || -32
|-
| <tt>101</tt> || Exponential decrease || -1 - ((envelope - 1) >> 8)
|-
| <tt>110</tt> || Linear increase || +32
|-
| <tt>111</tt> || Bent increase || if envelope < $600 (75%) { +32 } else { +8 }
|-
|}

If the voice is in the release state, the envelope is linear decrease at a fixed rate of -8 every sample.


See: [[DSP envelopes]]


{{Anchor|VxENVX}}
=== VxENVX - Voice envelope value ($x8, read-only) ===

 7  bit  0
 ---- ----
 0EEE EEEE
  ||| ||||
  +++-++++- Upper 7 bits of envelope

<tt>VxENVX</tt> is technically writable and not intended to be written to.  The S-DSP updates this register once per sample.


{{Anchor|VxOUTX}}
=== VxOUTX - Voice sample value ($x9, read-only) ===

 7  bit  0
 ---- ----
 OOOO OOOO
 |||| ||||
 ++++-++++- Upper 8 bits of current sample (signed)

<tt>VxOUTX</tt> contains the upper 8 bits of the current sample after the envelope has been applied to the Gaussian Interpolation (or noise) output and before the <tt>VxVOL</tt> channel volume multiplication.

<tt>VxOUTX</tt> is technically writable and not intended to be written to.  The S-DSP updates this register once per sample.

== References ==
* Anomie's S-DSP Doc
* ares source code, <tt>[https://github.com/ares-emulator/ares/tree/master/ares/sfc/dsp ares/sfc/dsp]</tt> directory, by Near and ares team