# Shared Sound Software Functional Specification

CONFIDENTIAL

Document ref: | 2107,746
Project: | NC100 1.15
Revision: | $Revision$
Date: | $Date$
Author(s): | Mark Taunton
Change: | ECO 3997
Classification: | Acorn Restricted

## Contents

1.0 | Overview
2.0 | Outstanding issues
3.0 | Technical background
4.0 | User interface
5.0 | Programmer interface
6.0 | Data interchange
7.0 | Data formats
8.0 | External dependencies
9.0 | Acceptance test
10.0 | Non compliances
11.0 | Development test strategy
12.0 | Product organisation
13.0 | Future enhancements
14.0 | Glossary
15.0 | References
16.0 | History

## 1.0 Overview

The purpose of the SharedSound module is to allow multiple, distinct, simultaneous software sound generation activities (e.g. a sound codec under Replay, the software MIDI synthesiser, and a directly generated sound effect) to all output their individual sounds in a consistent way, to a single sound output device. Each source can have its own volume level and sample rate, with the SharedSound module maintaining this information on its behalf. In cooperation with code in the respective client (source) applications to implement the low-level operations, the SharedSound module supports the conversion and mixing of the individual streams of data in the appropriate way, to produce a final composite output stream to be delivered to the hardware. The composite stream can also be processed by further functions, also registered by clients of the module, to achieve any overall effects which may be desired.

## 2.0 Outstanding issues

There are no outstanding issues.

## 3.0 Technical background

### Principles

SharedSound allows multiple sound handlers to output through one sound output route. SharedSound can potentially provide a number of useful functions such as mixing, sample rate interpolationand volume scaling. The initial versions of Shared Sound will simply store the values requested and insist that the handlers provide these functions. It may be advantageous for a handler to do its own mixing, volume scaling and frequency conversion if it is already carrying out such functions as in the case of the MIDI Synthesiser. Some mixing is required by SharedSound, however, to mix the 8 bit source and any immediate sound handlers with the call back handler buffer data.

In any case values are passed to the Handler fill routine which indicate the current state of play, in particular the current sample rate, along with associated values, as well as the current volume setting. The volume for a handler is calculated from the current system volume and the volume requested for the handler as well as scaling depending on the number of currently active handlers. This is passed as a Left and Right (Stereo) volume as two 16 bit words packed into a 32 bit word. A mixer could be provided that reads that name and current volume of each handler and allows the user to set the volume of each handler.

SharedSound will typically sit on top of the current Sound_LinearHandler. The register values provided by the LinearHandler fill call are used as the basis for the parameters passed by SharedSound to the SharedSound handlers. In other words the fill buffer size, initial buffer status and current sample frequency are all derived from the LinearHandler. It is perfectly feasible for the InstallDriver SWI to be implemented so that SharedSound could sit on other sound output hardware devices, although this may not be the best way of providing a fully integrated sound system.

Initially, Shared Sound will not offer the sample rate required by a client handler but will use the rate currently set in the hardware. If there is only one handler present or active (all other handlers paused) then it could (in principle) change the system rate to suit the requests of the single handler; however the current version does not do this.

As the possession of the Sound_LinearHandler (as with other handlers) is not in the control of SharedSound it is quite possible that SharedSound may lose control of the handler. To cope with this, SharedSound will check that it is in charge of the handler whenever it is called via its SWIs, and re-install if it has lost control. A specific SWI is provided which will check that SharedSound is still attached and this can be called by the handler if required.

The call back mechanism is designed to relieve pressure on interrupts by calling handlers in a state where interrupts can be enabled; to provide 'look ahead' so that data is available when the system is busy, to allow the soundDMA activity to overrun without crashing the computer and to provide overrun information to handlers so that they can take action to reduce CPU usage.

### Implementation

The current version of SharedSound provides three levels of handler activity. The first is an immediate handler. This is called when SharedSound is called by the SoundDMA and is therefore required to act with interrupts disabled and return as quickly as possible. Such handlers are likely to be simple 'fill buffer' handlers that do not require to process any data or a timing device that is using the Sound interrupt as a timer.

The second type of handler is a call back handler. This is called on a call back and can therefore operate with interrupts enabled and take more time to execute.

The third handler type is a process handler. This is called in the same way as a call back handler but is called at the end of the call back process to allow it to add effects or process the current buffer in some way. The call back buffer is set to 8 times the current SoundDMA buffer size and the handlers are called repeatedly to attempt to keep the call back buffer full. In other words, if there is sufficient CPU time then the call back buffer will have 8 buffers ready for adding to the SoundDMA buffer when called under interrupts.

When a handler is installed with SharedSound it can specify which sample rate it requires. SharedSound does not attempt to change the system rate but it does calculate the fractional stepping value required by the handler to achieve the rate required. If the system rate is changed by another application then SharedSound re-calculates the values for each handler and passes on both the new sample rate and the new fractional step to the handler on the next buffer fill. Similarly, each handler's volume can be changed by an external application and the current volume is passed on to each handler.

SharedSound is currently used by the the Sound16 codecs/drivers for Replay, the sound effects system and the MIDI Synthesiser. All sound sources can be active at once.

## 4.0 User interface

SharedSound has no direct user interface.

## 5.0 Programmer interface

### SWI interface

Shared Sound SWI definitions

SWI Name | SWI-num | r0 | r1 | r2 | r3 | Status
SharedSound_InstallHandler | 0xB440 | Handler | Parameter | Flags | Name | OK
SharedSound_RemoveHandler | 0xB441 | Handler-num | -- | -- | -- | OK
SharedSound_HandlerInfo | 0xB442 | Handler-num | -- | -- | -- | OK
SharedSound_HandlerVolume | 0xB443 | Handler-num | Volume | -- | -- | OK
SharedSound_HandlerSampleType | 0xB444 | -- | -- | -- | -- | x
SharedSound_HandlerPause | 0xB445 | -- | -- | -- | -- | x
SharedSound_SampleRate | 0xB446 | Handler-num | Rate | -- | -- | OK
SharedSound_InstallDriver | 0xB447 | -- | -- | -- | -- | x
SharedSound_RemoveDriver | 0xB448 | -- | -- | -- | -- | x
SharedSound_DriverInfo | 0xB449 | -- | -- | -- | -- | x
SharedSound_DriverVolume | 0xB44A | -- | -- | -- | -- | x
SharedSound_DriverMixer | 0xB44B | -- | -- | -- | -- | x
SharedSound_CheckDriver | 0xB44C | None | -- | -- | -- | OK
SharedSound_ControlWord | 0xB44D | None | -- | -- | -- | OK
SharedSound_HandlerType | 0xB44E | Handler-num | Type | -- | -- | OK

OK = implemented, x = not implemented

### SharedSound_InstallHandler

This SWI is used to install multiple Sound Handlers into the system.

On entry

            R0 =    handler address
            R1 =    parameter to pass
            R2 =    flags
            R3 =    name of handler
            If successful V flag is clear and R0 holds a handler number
            If unsuccessful V flag is set and R0 points to a SWI error block.

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

Flags

Only one flag is used in this version:

            Bit 0           if set then use type in R4 otherwise set type to default.

Type

The handler types are defined as follows:

            0       Immediate handler
            1       Call back handler
            2       Process handler

Use

Each handler is called with when the current driver is called if the handler is an immediate handler or on call back if the handler is either a call back or process handler. The handlers in each type are called in the order in which they were installed. Process handlers are called after call back handlers.

Each handler is passed a buffer to fill with the registers set as follows:

On entry

            R0 =  parameter
            R1 =  base address of buffer to fill
            R2 =  end of buffer
            R3 =  flags:
                    bit    0   Mix. If set then data must be mixed otherwise overwrite.
                    bit    1   Quality. If set then use highest quality e.g. oversampling.
                    bits 3-7   0       No overrun
                               1--30   Number of times buffer has been overrun
                               31      Buffer has been overrun by more than 30 times
                    bit 29     Reversed Stereo: reverse stereo channels (L<->R) if set.
                    bit 30     Set if to use volume in R7, otherwise use max volume
                    bit 31     Mute if set.
            R4 =  sample frequency
            R5 =  sample period
            R6 =  fractional step as specified by SharedSound_SampleRate
            R7 =  LR volume

R4, R5 and R6 are updated at the start of a buffer fill to represent the current sample frequency etc. Only bit 0 of the above flags is implemented by SharedSound. The other flags are currently used by the Sound16 drivers.

On exit

            R3 contains flags as above, modified according to the action of the handler

### SharedSound_RemoveHandler

This SWI is used to remove a specific handler.

On entry

            R0 =    handler number

On exit

            If successful V flag is clear and R0 holds a handler number
            If unsuccessful V flag is set and R0 points to a SWI error block.

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_HandlerInfo

This SWI is used to provide information on a specific handler.

On entry

            R0 =    handler number

On exit

            If successful V flag is clear and
            R0 = number of next available handler or 0 for none
            R1 = Flags
            R2 = name
            R3 = Sample frequency
            R4 = Sample type
            R5 = Volume

            If unsuccessful V flag is set and R0 points to a SWI error block.

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_HandlerVolume

This is to set the volume level for a particular handler. Shared sound can use this information to provide internal mixing or pass it on to the handler at each buffer fill.

On entry

            R0 =    Handler number
            R1 =    volume (bits 0-15 left channel, 16-31 right channel)

On exit

            If successful V flag is clear and
            R0  is preserved
            R1 = current volume
            If unsuccessful V flag is set and R0 points to a SWI error block.

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_HandlerSampleType

Not implemented in this version.

This is to set the sample type for the data for a particular handler. Shared sound can provide a buffer to the handler that is to be filled in this particular type. It will return the buffer fill type that it will be using. By default this will be Stereo, 16 bit Signed as in Sound Linear Handler.

### SharedSound_HandlerPause

Not implemented in this version.

This is to turn a particular handler on or off without having to de-install it.

### SharedSound_SampleRate

This SWI is used to set the sample rate used by a particular handler. Information is returned to indicate whether Shared Sound can provide this rate and if not what is the nearest rate it can provide. Along with this is a fractional step value to suggest how the handler can achieve it's required rate. Sample frequency is always supplied in 1/1024 Hz.

On entry

            R0 = >0  handler number
                 =  0 to set the rate for the current output driver
            R1 = sample frequency required

On exit

            R1 = current sample frequency
            R2 = current sample period
            R3 = fractional step required to achieve this rate in 8.24 fixed point

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_InstallDriver

Not implemented in this version. This is to allow other output devices to be installed.

### SharedSound_RemoveDriver

Not implemented in this version.

This is to allow other output devices to be installed.

### SharedSound_DriverInfo

Not implemented in this version.

This provides information for a particular driver.

### SharedSound_DriverVolume

Not implemented in this version.

This sets the volume for a driver.

### SharedSound_DriverMixer

Not implemented in this version.

This sets or reads the mixer values for a driver, where relevant.

### SharedSound_CheckDriver

This is used to force SharedSound to make sure that current driver is still active. It is needed for situations where another application has taken control of the Sound Linear handler and note returned control to SharedSound.

On entry:

            none

On exit:

            none

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_ControlWord

This is used by the Replay Sound16 codecs as part of the multi-tasking Replay implementation. It provides a control word to both Replay and the Sound16 code allowing for a "1 audible handler of many" support.

On entry:

            none

On exit:

            R0 =    Pointer to  control word

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

### SharedSound_HandlerType

This is used to change the type of a handler from for example, an immediate handler to a call back handler.

On entry:

            R0 =    handler number
            R1 =    handler type (see Install handler for type number)

On exit:

            none

Interrupts

            Interrupts status is undefined
            Fast interrupt are enabled

Processor mode

            Processor is in SVC mode

Re-entrancy

            SWI is not reentrant

## 6.0 Data interchange

N/A.

## 7.0 Data formats

All data processed by the SharedSound module is in 16-bits/sample linear format. For stereo data, two samples are packed into one word, with the default arrangement being that the left channel sample is in the high order half-word (bits <31:16>) and the right channel sample is in the low order half-word (bits <15:0>). In some circumstances this can be reversed (i.e. left in lower half, right in upper half), as indicated by flags in the relevant API function interface.

## 8.0 External dependencies

N/A.

## 9.0 Acceptance test

The acceptance test must check that multiple simultaneous sound sources can correctly function together.

## 10.0 Non compliances

Aside from those functions which are explicitly marked in the above table as being "not implemented", there are no non-compliances.

## 11.0 Development test strategy

Development testing is performed by interactive use of the facilities of the module to verify correct functioning of the function of SharedSound to support multiple simultaneous sound sources. By using an EMBED tag, a particular piece of audio content (e.g. Wave, MIDI) can be set up as a background sound which should continue to play (without play controls available) either to its end or until the browser leaves the page. Any other audio object on the page should also be playable (with codec controls available) while the background sound is active.

## 12.0 Product organisation

SharedSound is implemented as a standard NC OS relocatable module.

## 13.0 Future enhancements

Possible future enhancements include use of Call-Back-After-Interrupt (CBAI) to improve timing precision, and filling out of the implementation to include all functions listed in the API but which are not currently implemented.

## 14.0 Glossary

API | Application Programmer Interface.
NC | Network Computer.
MIDI | Musical Instrument Digital Interface.
OS | Operating System.
SWI | Software Interrupt.
UI | User Interface.

## 15.0 References

ESP Web Site
SoundDMA Software Functional Specification (2107,749)

## 16.0 History

    $Log$
    Revision 6.1  1997/08/11 19:41:33  srose
    SECTION: header
    CHANGE:  ECO 3997 allocated
    REASON:  Sign off

    Revision 5.1  1997/08/11 16:49:08  srose

    SECTION: 15.0 References
    CHANGE:  Corrected URL link to the sound dma specification
    REASON:  Broken link
    IMPACTS: None.

    Revision 4.1  1997/08/11 16:45:59  srose

    SECTION: header
    CHANGE:  renamed project from NC100 to NC100 1.15
    REASON:  to avoid confusion between NC100 1.15 and NC100 1.16
    IMPACTS: none

    Revision 3.1  1997/05/06 10:40:42  srose
    AMR number allocated; internal sign off agreed.

    Revision 2.8  1997/04/24 16:47:06  srose
    HTML updates following weblint checks; automated history section; added
    classification and confidential info to header section; had to redo some
    updates from previous minutes because the last edited version wasn't the
    one which got reviewed - I need to check this specification against all
    previously agreed updates and restore what got deleted as necessary.

This document is issued under license and must not be copied, reproduced or disclosed in part or whole outside the terms of the license. | For NC Inc. by Acorn Network Computing, UK. © Acorn Computers Ltd 1997