Introduction and Overview
In order to allow the SoundScheduler to function within a 32bit executable 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.
Technical Details
Sound_QSchedule
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.
Using the new interface
Clients wishing to use the new API should first attempt to use SWI 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.
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 SWI Sound_QSchedule32 interface, rather than the Sound_QSchedule interface.
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 SWI 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.
SWI Calls
| R0 | = | Time (as for SWI Sound_QSchedule) | ||||||||||
| R1 | = | Schedule type:
| ||||||||||
| R2 | = | Data for SWI/function call | ||||||||||
| R3 | = | Data for SWI/function call |
| R0 | = | 0 for success, negative if there is an error |
| R1 | = | &FC000003 if this API is present on this version of the SoundScheduler module |
This SWI is similar to SWI Sound_QSchedule 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.
Clients wishing to use the new API should first attempt to use this SWI 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.
FIXME: With bits 0-1 of R1 clear, the SWI either calls Sound_ControlPacked or treats R1 as a function to call; the condition which selects between them is not documented.