Audio

SoundScheduler changes for 32bit

Overview

In order to allow sound scheduler to function within a 32bit excutable space, a rationalisation has been necessary for the interfaces. The normal, PRM documented functioning of the interfaces remains unchanged. The undocumented interfaces, however have required a minor restructuring to allow the full address space to be used as intended.

This SWI may take R1 as a pointer to a function to be executed at the scheduled time. This is not documented, and the address must not have the mask &xFxxxxxx due to the documented SWI interface. As this interface was previously undocumented, and cannot be used with the full address space, it is recommended that clients continue to not use it.

SWI Sound_QSchedule32

This SWI is similar to the Sound_QSchedule SWI except that it provides a documented mechanism to schedule a call to a client-supplied function that may be anywhere within the entire address range of the system.

On entry:

   R0 = Time (as Sound_QSchedule)
   R1 = Schedule type:
        If bit 0-1 = 0: call Sound_ControlPacked otherwise R1 is a function to call
           bits 2-31: reserved
        If bit 0-1 = 1:  
           bit 2-7 control the operation to perform:
                       0: call SWI given in bits 8-31
                       1-63: reserved for future expansion
           bits 8-31: reserved
        If bit 0-1 = 2:  
           Reserved, do not use
        If bit 0-1 = 3:  
           Reserved, do not use
   R2 = data for SWI/function call
   R3 = data for SWI/function call

On exit:

   R0 = 0 for success, 
        -ve if there is an error
   R1 = &FC000003 if this API is present on this version of the SoundScheduler module

Use

Clients wishing to use the new API should first attempt to use Sound_QSchedule32 with the correct parameters. If R1 returns &FC000003 then the operation was successful. If R1 returns any other value, the Scheduler module is not capable of the operation and the client must fall back to the old style Sound_QSchedule operation.

SWI Sound_QRemove

This SWI is not documented in the PRMs and the following description assumes that clients understand the API in use.

The parameters returned are in internal format which has changed to reflect the Sound_QSchedule32 interface, rather than the Sound_QSchedule interface.

SWI Sound_QInterface

This SWI is not documented in the PRMs and the following description assumes that clients understand the API in use.

The parameters returned are those for the old style interface. The new style interface has been provided without modification to the API for Sound_QInterface. The instruction pointed to by R1 will be a branch if the new interface is available. This can be identified by (R1 AND &FF000000) = &EA000000. If this condition is met, then the address R1+4 may be called with parameters as for the Sound_QSchedule32 API.

Compatibility with earlier software

As mentioned earlier, the interfaces for Sound_QRemove, Sound_QInterface and the function pointer interface in Sound_QSchedule are not documented and clients using them should be aware of the consequences of doing so. Where possible the API for such undocumented use has been retained such that code should require no modification.

New clients may use the old style interface where they are not interested in the function pointer API. The updated QSchedule32 API is merely more flexible for clients wishing to use the, now documented, function pointer API.

Note that undefined SoundScheduler SWIs have never returned errors with V set. They merely return with parameters preserved.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015