SoundDriver
Functional Specification

( SD1001/FS )

Issue 8
30 Jul 2002

Authors

Andy Pierson
David Lenthall

ESP Music

© ESP Music

Contents

Introduction

The SoundDriver module is designed to provide a general purpose sampling manager. It is independent of the hardware used to provide the data and can handle any number of streams of data. High level resources are provided to sample data into memory or onto disc.

SWI Interface

SoundDriver_Install - &4DBC0

This is used by a hardware or software device that wishes to register itself as a sampling device. Once installed it can be selected by application software when recording data.

The driver number allocated is numbered from 1 onwards.

A Service call is issued by SoundDriver on start up which allows for drivers to install automatically. At present PowerWAVE (DMI cards) and SharedSound respond to this Service call so if these modules are present then there should be at least two drivers ready for use.

The current list of installed drivers can be found by using the SoundDriver_Info SWI.

On entry
R0 = Call table address
R1 = R12 parameter
R2 = Flags
R3 = Name
On exit
R0 = Driver number
R1 = Address to call data with
R2 = R12 parameter
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

The call table entries are as follows :

0driverEntry_Start
4driverEntry_Stop
8driverEntry_Pause
12driverEntry_Volume
16driverEntry_Device
20driverEntry_SampleRate
24driverEntry_SampleType
28driverEntry_Gain

Zero in an entry indicates that this option is not available.

Call details for these entries are given later in this document.

SoundDriver_Remove - &4DBC1

Remove an installed record driver.

On entry
R0 = Driver
On exit
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_Info - &4DBC2

This enables an application to find out which sample drivers are currently installed.

On entry
R1 = Driver number
On exit
R0 = Call table address (or = -1, indicating no more drivers)
R1 = R12 parameter
R2 = Flags
R3 = Name (or = 0, if no driver installed)
R4 is corrupted (set to 0)
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

Driver numbers are allocated when they are installed, starting from 1. If drivers are removed, then gaps can appear in the sequence of driver numbers.

Thus to enumerate all installed drivers, call this SWI in a loop starting from driver number 1, incrementing until R0 returns -1. Any driver number that returns non-zero in R3 (ie there is a name) is a valid (installed) driver. If R3 returns 0, but R0 is not -1, then this is a gap.

SoundDriver_Control - &4DBC3

This provides applications with the ability to stop, start and pause playback. It also allows for the current data counter to be polled to indicate the progress of recording.

Playback can only be started once a Record process has been setup.

On entry
R0 = Function code : 0 = Read, 1 = Write
R1 = Driver number
R2 = Play status : 0 = Stop, 1 = Start, 2 = Pause
R4 = Call back address (not implemented)
R5 = Call back flags (not implemented)
BitFunction
0Call back when status changes
1Call back every buffer fill
On exit
R0 = Function code (preserved)
R1 is corrupted (set to 0)
R2 = Play status

If function code is 0 :
R3 = Counter
R4 = 0
R5 = 0

If function code is 1 :
R3, R4, R5 are preserved

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_Volume - &4DBC4

Read or set the record volume for a driver. Volumes are 8-bit values (ie 0 - 255) per channel.

On entry
R0 = Function code : 0 = Read, 1 = Write
R1 = Driver

If function code is 1 :
R2 = Left volume (or -1 for no change)
R3 = Right volume (or -1 for no change)

On exit
R0, R1 are preserved
R2 = Left volume
R3 = Right volume
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Notes

The SharedSound driver does not respond to record volume changes. Both channels remain at the maximum setting (255) at all times.

For the PowerWAVE driver, setting the record volume to zero does not equate to silence, as this SWI sets it's trim level. Note also that this driver does not use the full 8-bit resolution, there being only 16 discrete levels. The actual settings applied are returned in R3 and R4.

SoundDriver_Source - &4DBC5

Set or read the source device selected for a driver. Sources are specified 0 to n-1, where n is the number of sources available for a driver.

On entry
R0 = Function code : 0 = Read, 1 = Write, 2 = Info
R1 = Driver

If function code is 1 :
R2 = Left source
R3 = Right source

If function code is 2 :
R2 = Left source number to read name of, or -1 to get the number of available sources
R3 = Right source number to read name of, or -1 to get the number of available sources

On exit
R0, R1 are preserved

If function code is 0 or 1 :
R2 = Left source
R3 = Right source

If function code is 2 :
R2 = Left device name, or number of left sources
R3 = Right device name, or number of right sources

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

Call with R0 = 2, and R2 and R3 = -1 to determine the number of sources (n) available for a driver.

Call with R0 = 2, and R2 and R3 = 0 to n-1 to determine the name of each source device.

SoundDriver_SampleRate - &4DBC6

Set or read the sample rate selected for a driver.

On entry
R0 = Function code : 0 = Read, 1 = Write, 2 = Test
Test = Give nearest available rate without changing it.
R1 = Driver

If function code is 1 or 2 :
R2 = Sample rate

On exit
R0, R1 are preserved
R2 = Nearest available sample rate
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_SampleType - &4DBC7

Set or read the sample type selected for a driver.

On entry
R0 = Function code : 0 = Read, 1 = Write, 2 = Info
R1 = Driver

If function code is 1 :
R2 = Sample channels
R3 = Sample data type (from list given by Info call)

If function code is 2 :
R2 = -1 to read number of types, 0 to n-1 to get name of types

On exit
R0, R1 are preserved

If function code is 0 or 1 :
R2 = Channels (1,2 ....)
R3 = Sample data type (0,1,....)

If function code is 2 :
R2 = Number of channels available
R3 = Number of data types, or name of type

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_Gain - &4DBC8

Set or read the extra gain option, if available, for a source device for a driver.

On entry
R0 = Function code : 0 = Read, 1 = Write, 2 = Info
R1 = Driver
R2 = Source device (0,1,...)

If function code is 1 :
R3 = Left gain state (0 or 1)
R4 = Right gain state (0 or 1)

On exit
R0, R1, R2 are preserved

If function code is 0 or 1 :
R3 = Left gain state (0 or 1)
R4 = Right gain state (0 or 1)

If function code is 2 :
R3, R4 > 0 if gain is available for the device specified in R2

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Notes

The source device numbers passed into R2 are the same as used with the SoundDriver_Source SWI. That SWI should be used to determine the number of source devices available for a driver.

SoundDriver_Record - &4DBC9

Set up a record process. This call is required prior to a Control start call. It allows for the setting up of the record code but does not start a record process.

On entry
R0 = Function code : 0 = Read, 1 = Write
R1 = Driver

If function code is 1 :
R2 = Process type :

0 = None
1 = Internal buffer
2 = External buffer
3 = File

If function code is 1, and process type = 1 (Internal) :
R3 = Max memory (0 = use all available)
R4 = Initial size to use (0 = use default)

If function code is 1, and process type = 2 (External) :
R3 = Data pointer
R4 = Data length

If function code is 1, and process type = 3 (File) :
R3 = File name

On exit
R0, R1 are preserved
R2 = Process type

If process type = 0 (None) :
R3, R4 are corrupted

If process type = 1 (Internal) or 2 (External) :
R3 = Data pointer
R4 = Data length

If process type = 3 (File) :
R3 = File name

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_Monitor - &4DBCA

This SWI allows for the record sample data to be monitored and passed onto other parts of the sound system. The Sprite buffer data is a circular buffer that contains 1 seconds worth of data with the latest data at the right hand end. This can be used by a sprite draw routine to display the activity of a record channel.

SharedSound data is passed onto SharedSound as a call back handler so that SharedSound process handlers such as Reverb can be used to modify the data.

On entry
R0 = Function code : 0 = Read, 1 = Write
R1 = Driver
R2 = Monitor device :
0 = SharedSound
1 = Sprite sample data (not implemented)
2 = PCSound
3 = Word bar

If function code is 1 :
R3 = Monitor state : 0 = Off, 1 = On

On exit
R0, R1, R2 are preserved
R3 = Monitor state (0 or 1)

If Monitor device = 1 :
R4 = Pointer to Sprite sample data (not implemented)

If Monitor device = 3 :
R4 = Pointer to 32-bit word (instantaneous stereo 16-bit value, left channel in the lower 16 bits)

If Monitor device = 0 or 2 :
R4 is corrupted (set to 0)

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

SoundDriver_Internal - &4DBCB

This SWI provides information on the internal sample data currently being processed, enables an application to save it to a file, or free up the memory when no longer required.

On entry
R0 = Function code : 0 = Read, 1 = Write, 2 = Free
R1 = Driver

If function code is 1 :
R2 = File name (null terminated)

On exit
R0, R1 are preserved
R2 = Memory address of data (or = 0, if no sample data)
R3 = Sample length, including a 44-byte WAV header (or invalid/corrupted, if no sample data)
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Notes

Attempting to save a sample (R0 = 1) when there is no sample data, returns without saving a file, and without generating an error.