Sound_InstallVoice

The PRM documentation implies that an existing Voice Generator can be replaced:

On entry
R0 = pointer to Voice Generator
R1 = voice slot (0 to install in next free slot, else 1 – 32)

On exit
R0 = pointer to name of previous voice, or null terminated error string if R1 = 0
R1 = voice number allocated, or 0 if unable to install

For Use, it says:

This software interrupt is used by Voice Modules or Libraries to add a Voice Generator
to the table of available voices. If an error occurs, this SWI does not set V in the usual
manner. Instead R1 is zero on exit, and R0 points directly to a null-terminated error
string.

So I’d expect the following SWI to work:
SYS “Sound_InstallVoice”, VG%, 1

However, what happens is the new Voice Generator is not installed and it returns:
R0=“WaveSynth-Beep”
R1=0

This doesn’t match what the documentation says, as you’re expecting R0 to point to a null terminated string is there’s an error. Its consistent from RO3.1 right up to 5.21 so I’m guessing it’s the documentation that needs to detail what happens if you try to replace an existing Voice Generator. For the time being, I’ve updated the Wiki documentation to state explicitly what currently happens.

I tested with the following code:

SYS "OS_Module",6,,,&40 TO ,,Z%
P%=Z%:[LDR PC,[R13],#4:LDR PC,[R13],#4:LDR PC,[R13],#4:LDR PC,[R13],#4:LDR PC,[R13],#4:LDR PC,[R13],#4:LDR PC,[R13],#4:DCD 32:DCB "TestVoice":DCB 0:]
SYS "Sound_InstallVoice",Z%,1 TO A%,B%
PRINT "R0=";
REPEAT:PRINT ;CHR$(?A%);:A%+=1:UNTIL ?A%=0
PRINT ;" R1=";B%
*Voices

If you then remove WaveSynth-Beep via:
SYS “Sound_RemoveVoice”,,1

And then install the new one:
SYS “Sound_InstallVoice”,Z%,1 TO A%,B%
PRINT “R0=”;~A%," R1=";B%

It returns:
R0=Z%
R1=1

So it looks like R0 is preserved if the SWI succeeds, which again isn’t covered in the documentation.

So I’d expect the following SWI to work:
SYS “Sound_InstallVoice”, VG%, 1

However, what happens is the new Voice Generator is not installed and it returns:
R0=“WaveSynth-Beep”
R1=0

“You’re holding it wrong.”

Abort on Brain Fetch at &øflåøflåøflåøflå! Read what you quoted – R0 = pointer to name of previous voice, or null terminated error string if R1 = 0.

To be honest, I think it is pretty dumb not to set R0 to point to an error if an error occurred, however – your example is NOT specifying R1=0, and since the PRM makes a point of this, I would imagine the behaviour is in fact correct, even if it makes no sense whatsoever. point to an error block when the documentation states that it should.

Additionally, this is a grey area but…

If you then remove WaveSynth-Beep via:
SYS “Sound_RemoveVoice”,,1

And then install the new one:
SYS “Sound_InstallVoice”,Z%,1 TO A%,B%
PRINT “R0=”;~A%," R1=";B%

It returns:
R0=Z%
R1=1

R0 on exit (if not an error) is supposed to be the name of the previous voice. In your case, you removed the previous voice, so it probably ought to return an empty string (not a null!).

Update: looks like the documentation is utterly wrong and this SWI cannot change an allocated voice (must be done manually – Remove old then Install new), and as such there is no possible way it can return the previous anything. It actually appears to return information on the current voice (see below).
Furthermore, there appear to be instances when the SWI raises an error in the usual manner – in direct contradiction to the documentation that states (with a big bold not!) that the SWI does not (!) set the V flag, yet in some cases, it can.

I’m presuming if R1 = 0 to mean R0 will be a null terminated string if on exit R1 = 0

Neither the documentation or actual results make a lot of sense to me.

Why for example would you return the previous voice name, if it’s been removed?

Yeah – this does look like a contradiction.

The SWI “Sound_InstallVoice” appears to be capable – in the documentation – if replacing a specified voice with a new one (else why would R0 be the name of the previous voice on exit?), however the code does this:

installvoice2
        LDR     r14, [r11, r1, LSL #2]  ; check if any existing voice here
        CMP     r14, #0
        LDRNE   r0, [r14, #SoundVoiceTitle]     ; voice title offset
        ADDNE   r0, r14, r0                     ; make address
        BNE     %FT80                           ; fail if already allocated

…which to my eyes is pretty much a “something here so bomb out”. Furthermore, instead of returning a pointer to an error string, it just returns a pointer to the existing voice name.

I’m presuming if R1 = 0 to mean R0 will be a null terminated string if on exit R1 = 0

<sheepish grin> – yeah, that would make sense. ;-)

Why for example would you return the previous voice name, if it’s been removed?

Exactly what I pointed out above. I rather imagine the documentation writers had plans and aspirations that were stuck to a post-it note that fell down the back of a radiator and never made it to being actual code.

Eyeballing the code is complicated thanks to overloading the SWI with special values (R0 = 0-3 instead of a pointer).

So…

R0 = 0 = See what is present at a given slot
         R1 = slot number
  Exit = R0 = Pointer to voice name, or zero if no voice.
         R1 = Preserved
  Returns an error (with V set - try asking for voice #123) if voice slot is out of range.

[code path → handled in installvoice1]

(nb. code paths given for those brave bored clever enough to want to look through the code themselves)

I rather imagine the documentation writers had plans and aspirations that were stuck to a post-it note that fell down the back of a radiator and never made it to being actual code.

LOL

Just tested RO2 and it’s the same behaviour as above, so one can only presume the documentation needs amending. I don’t have an Arthur machine to test, but it’s probably the same.

R0 = 1 = Install a voice with a localised name
         R1 = slot number (0 for first free slot)
         R2 = pointer to voice generator code
         R3 = local language name, or zero if none
  Exit = R0 = Preserved; if voice here it is a pointer to existing voice name
         R1 = Voice slot allocated, zero for fail
         R2 = Preserved
         R3 = Preserved

Looks like this can return an error with V set – see line 924. What would this be? Null pointer?

R0 is “preserved” in a manner of speaking. ;-)

[code path if R1 = 0 → installvoice1 → %50 → %40 → CheckAttachments → install_change (if local name) → done
code path if R1 != 0 → installvoice1 → installvoice2 → CheckAttachments → install_change (if local name) → done]

R0 = 2 = See what's present at a given slot, with localised name
         R1 = slot number
  Exit = R0 = Preserved
         R1 = Preserved
         R2 = Voice generator name
         R3 = Given localised name (or same as R2 if no localised name)
  Returns an error (with V set - try asking for voice #123) if voice slot is out of range.

[code path → same as R0=0 with some added fluff]

R0 = 3 = Change localised name of an existing generator
         R1 = slot number
         R2 = must be zero (for MOVS at line 923)
         R3 = pointer to new localised name
  Exit = Everything preserved

R2 must be zero, else could return a V-set error (same code as for R0=1, line 924).

[code path → installvoice1 → install_change]

And finally…

R0 = pointer to voice generator to install
         R1 = slot number (zero for first available)
  Exit = R0 and R1 preserved.

The preserving Z flag in CheckAttachments is so we know if R0 on entry was 1 or not (result of TEQ at line 864); as this shares code with R0=1 functionality.

[code path if R1 = 0 → installvoice1 → %50 → %40 → CheckAttachments → done
code path if R1 != 0 → installvoice1 → installvoice2 → CheckAttachments → done]

Phew. I’m off to brew a nice cuppa. Good luck distilling that into an easy-to-read page of documentation!

Thanks Rick, I’ll endeavour to update the documentation based on your findings.

Open message to those more familiar with the RISC OS sound system…

The installvoice2 code does a bail-out if a voice slot currently has a voice present. As a consequence, it sets R1 to zero (fail) and R0 to point to the name of the existing voice generator. This contravenes the published API¹².

Would there be any serious harm if instead the fail action was to stack the important registers, then call Sound_RemoveVoice automatically?
It appears as if all that Sound_RemoveVoice requires is the voice slot number, and we have this available. From there it can fall through to adding a new voice. It looks like the only important modification we would have is somewhere to stash the pointer to the name of the previous voice (returned by Sound_RemoveVoice, supposed to be returned by Sound_InstallVoice). Then the SWI can operate as per the documentation.

Off the top of my head, this doesn’t look like a complicated job.
I am asking this in case some other bit of software (SharedSound? One of the built in voices?) depends upon the current (broken) behaviour.

¹ Documentation does not state, but implies that voices can be installed into slots with existing voices; hence the “previous name” return result.

² The documentation says that if R1=0, then R0 points to a null-terminated error string. [note: it’s a string, not an error block] The name of a voice generator isn’t exactly a good error message, is it? Why did your sound handler fail to install? “WaveSynth-Beep”. Wait, are you Kafka? “Wibble.”

Done, with the exception that R0 on exit returns the address of the CURRENT voice handler, not the name of the previous. This is because I had no spare registers without messing with the entire Install function and its entry/exit points. I wanted this to be as simple as possible.

It worked here with light testing (using Jon’s test code above).

For those who want to try this and see if it blows up…

The file is …castle.RiscOS.Sources.HWSupport.Sound.Sound1.s.Sound1.

Change this (Zap line #842):

installvoice2
        LDR     r14, [r11, r1, LSL #2]  ; check if any existing voice here
        CMP     r14, #0
        LDRNE   r0, [r14, #SoundVoiceTitle]   ; voice title offset
        ADDNE   r0, r14, r0                   ; make address
        BNE     %FT80                         ; fail if already allocated

to this:

installvoice2
        LDR     r14, [r11, r1, LSL #2]  ; check if any existing voice here
        CMP     r14, #0
        ; LDRNE   r0, [r14, #SoundVoiceTitle]   ; voice title offset
        ; ADDNE   r0, r14, r0                   ; make address
        BNE     %FT123                          ; fail if already allocated [was -> %FT80]

Go down a screenful (around Zap line 932) and you should see this:

80
        MOV     r1, #0
        EXIT

Immediately below that, insert this (just above “NullVoice”):

123 ; voice-already-allocated comes here so we can unallocate it (Rick 2014/09/18)
        STMFD   r13!, {r0-r3, r11}              ; I think these are all that's important to us
        BL      RemoveVoice                     ; R1 = voice slot, so just call code
        ; on return, we have R1 = 0 or VS for failure, with possibly some sort of error in R0
        ; otherwise R0 points to the name of the previous handler
        MOV     r10, r0                         ; R10 not yet used, so preserve returned name
        MOV     r14, r1                         ; R14 not yet used, so perserve return status
        LDMFD   r13!, {r0-r3, r11}              ; Unstack everything
        MOVVS   r0, r10                         ; An error? Copy across error pointer...
        EXIT    VS                              ; ...then get out of here
        CMP     r14, #0                         ; Was there an unflagged error?
        MOVEQ   r0, r10                         ; Copy across message...
        EXIT    EQ                              ; ...then get out of here
        ; pointer to "previous" voice is in R10, but we don't do that bit yet
        B       %BT40                           ; Voice slot now clear, so proceed to add new

This should sanely deal with the exit conditions, but this has not been tested (it’s stuff like OS_Module RMAFree failing).

To build a version to play with, the easy-but-long way is to build a new ROM.

The harder-but-simpler way is to build a softload. To go this, back up to the “Sound1” directory and copy MkROM as MkSA. Open MkSA and where it says amu_machine rom change this to amu_machine standalone and save this.
Now load up the !Builder app but don’t run it. That sets up all the paths and stuff (if you have configured it correctly) so all you need to do now is double-click the MkSA file.

After a bit of activity, your module will be in …Sound1.rm.ARM11ZF as “Sound1SA”.

Double-click it.

You will have no sounds and no voices. So open a TaskWindow and type:

*RMReInit WaveSynth
*RMReInit StringLib
*RMReInit Percussion

Then you can play. :-) If you copy Jon’s program from the top of the page, you can tweak the name “TestVoice”, “TestVoice1”, “TestVoice2”, etc and you’ll see you can drop one on top of an existing and it’ll replace it. Note that Jon’s code specifies slot #1 so you’ll wipe out WaveSynth. It might be an idea to tweak it to initially use a different channel?

Now, the really interesting thing is that if you use Jon’s code and knock out WaveSynth and then ReInit WaveSynth, it will nuke whatever was there and reinstate itself as voice #1. ;-)

Oh – and a quick note before anybody says anything.

If you are using the test program, this is expected and correct:

*Voices
         Voice      Name
           1    Internal error: abort on data transfer at &FC02xxxx
*

The reason for this is simple. Jon’s test program assembles into a bit of BASIC memory and then links that into the sound handler. The addresses, name, pointers, etc are only valid for as long as that program is active. This leading to a quirky situation where if you run the test program in a taskwindow, using *Voices in the same taskwindow will work, but a different taskwindow will abort.

Just thought I’d mention this before anybody stumbles upon it…

[hint: quick fix: *RMReInit WaveSynth ;-) ]

I’ve modified the example code to use the RMA, so you don’t get an Abort after exiting BASIC.

If this quirk has been around since RO2 and quite possibly Arthur, should we be changing the behaviour now? Admittedly it’s an unlikely scenario that code would rely on a voice failing to be replaced. It’s also unlikely that many people will be using the 8bit sound system these days, SharedSound has pretty much replaced it.

My only reason for raising this was to clarify the documentation, which I’ve been adding to the Wiki as I’ve been coding the 26bit sound layer in ADFFS. The documentation in the PRM doesn’t provide concise enough information around implementing Channel Handlers, certainly not to the level of detail I required. As with MiscOp and DiscOp, I had to study the source code to find out what actually happens, not what’s supposed to happen!

(Rick) The harder-but-simpler way is to build a softload. To go this, back up to the “Sound1” directory and copy MkROM as MkSA. Open MkSA and where it says amu_machine rom change this to amu_machine standalone and save this.
Now load up the !Builder app but don’t run it.

At this point click Builder on the iconbar and select a “Build Directory” and “Environment” – causing builder to set up the appropriate paths (as below). Now close the builder window follow the rest below.

That sets up all the paths and stuff (if you have configured it correctly) so all you need to do now is double-click the MkSA file.

All works nicely.