(Do not delete) SWS-0141 Template Revision Error! Bookmark not defined.





Mercury Standard Audio Decoder Interface Specification













Sign Off Authorization


Luke Kiernan_______________	__________________________________	Date:	__________
Firmware Group Leader	Signature

Joe Barcelo_________________	__________________________________	Date:	__________
Author/Mercury DSP Engineer	Signature






	Date:	October 3, 2002
	Revision	D-3.10
	Filename: 	DEC_DEFS.DOC
	Author: 	Joe Barcelo, Catherine Cai
	Document #: 	SWS-0141


INTEL CONFIDENTIAL

TABLE OF CONTENTS
1.	Overview	4
1.1	Revision History	4
1.2	Purpose	5
1.3	Scope	5
1.4	References	5
2.	Theory of Operation	6
2.1	Function of Decoder	6
2.2	Control of Decoder	6
2.3	Adding New Decoders	7
2.4	Start-up and Initialization - a brief summary	8
2.5	'Steady State' operation	8
3.	Environmental Requirements	9
3.1	Processor	9
3.2	Messaging	9
3.3	Kernel and Player Version	9
3.4	Internal Memory	9
3.5	MMA - linear, RJ	9
4.	Messaging Protocol	10
4.1	Kernel Messages	10
4.2	Standard Component Messages	10
4.3	Dialogic Decoder-specific Messages to Instances	10
4.3.1	Messages from Player to Decoder Instance	10
4.3.2	Messages from Decoder Instance to Player	10
4.3.2.1.1	Completion Messages	11
4.3.2.1.2	Event Messages	11
4.4	Use of messages to control a decoder instance	11
5.	Component Overview	13
6.	Message Set	14
6.1	MsgStart	15
6.2	MsgStartCmplt	17
6.3	MsgStop	18
6.4	MsgStopCmplt	19
6.5	MsgPause	20
6.6	MsgPauseCmplt	21
6.7	MsgResume	22
6.8	MsgResumeCmplt	23
6.9	MsgStatusEvt	24
6.10	MsgLoadDictionary	25
6.11	MsgLoadDictionaryCmplt	26
6.12	MsgActivateDictionary	27
6.13	MsgActivateDictionaryCmplt	28
6.14	MsgUnloadDictionary	29
6.15	MsgUnloadDictionaryCmplt	30
6.16	MsgDeactivateDictionary	31
6.17	MsgDeactivateDictionaryCmplt	32
6.18	MsgStartx	33
7.	Error Codes	35
8.	Parameters	36
8.1	Component Level Parameters	36
8.2	Instance Level Parameters	38
8.2.1	Parameters related to Enable/Disable AGC	38
8.2.2	Parameters related to playback level	38
8.2.3	Parameters related to playback speed	38
8.2.4	Parameters related to status events	39
8.2.5	Parameters related to synchronized play/record (transcoding)	39
9.	Attributes	40
10.	Event Types	41
11.	Miscellaneous Equates	42
1. 	Overview
This document describes the message set used by the Mercury Audio Decoder Component ("decoder"). This is the Mercury Component that resides on the signal processor (SP) which decodes audio data. It is used primarily to implement the "Play" function. The messages described are those which the decoder may receive from the Player Component or transmit to the Player Component. It is not planned for this Component to be accessed directly by the Host Software. 
In addition to the written description of each message there is a Mercury Message Definition Language (MMDL) representation of each of the messages embedded in the description. This allows a C header file of equates and definitions to be generated for each of the messages from this document using the MMDL Translation Utility. This header file is then used to format messages by any component that wishes to send or receive messages to and from this Component.  
Messages are sent using the Mercury Messaging scheme. 
1.1 Revision History

REVISION HISTORY
Rev.
Date of Change
Description of Change
Rev Originator
0.1
11/21/94
Initial Release
Joe Barcelo
1.0
7/10/95
modified to include status event - review version
Joe Barcelo
A
7/11/95
Revision A Release
Joe Barcelo
A-1.0
8/15/95
cleanup for MMDL
Joe Barcelo
B
7/2/96
Add the bytesplayed and timeplayed in MsgStopCmplt
Catherine Cai
C
7/23/96
Changed the MsgStart to fit new qCStreamOpen (MDK.A106)
Catherine Cai
D
11/13/96
Changed message set range to 0x0300-0x03FF.
Catherine Cai
D-1.0
1/2/97
Changed InputStream to InputStreamID in MsgStart.
Arthur Elwell
D-2.0
3/6/97
Removed EOF, added EOS and changed values of EOT and. MsgStop in MsgStopCmplt message.
Arthur Elwell
D-3.0
4/15/97
Modified the AGC parameters and corrected the vol parm. default
Catherine Cai
D-3.1
7/1/97
Changed Std_ComponentType attribute value from "ADec=0x03" to "Std_ComponentType=0x03". Removed reference to "coders.h".
Arthur Elwell
D-3.2
8/4/97
Added BrokenPipe stop reason.
Arthur Elwell
D-3.3
10/7/97
Changed event base value to 0x350; Changed ADec_MsgStart  to integer class messaging; Added MsgStatusEvt message
Arthur Elwell
D-3.4
8/4/98
Updated dictionary section
Ray Bailey
D-3.5
2/26/99
Updated status event document
Ray Bailey
D-3.6
8/9/00
Added ParmBitNibbleRev parameter
Catherine Cai
D-3.7
10/9/00
Delete ParmBitNibbleRev parameter
Catherine Cai
D-3.8
3/1/2001
Added synchronized play/record parameter, ParmSyncRecord
Arthur Elwell
D-3.9
07/11/01
Clean up the file and updated the table of contents
Bing Leng
D-3.10
10/03/02
Added Msgstartx.  Msgstartx is the Msgstart plus parameter value which is sent at runtime. ( Volume, Speed and Sync Reocrd )
Himanshu

1.2 Purpose
The purpose of this document is to describe the message interface between the Dialogic Standard Player, resident on the Mercury platform's control processor (CP), and the Standard Audio Decoder Component which resides on a signal processor.
This document will be used by the developers of the Mercury Standard Audio Decoder Component as well as by technology partners adding new audio decoders and using the standard interface provided.
1.3 Scope
This document defines all of the messages that the Standard Audio Decoder Components may send and receive. It also defines all of the parameters that apply to these Components.
1.4 References
SWS-0047				Mercury Resource Firmware SAS by Luke Kiernan
SWS-0048				Mercury Kernel Architecture Specification by Steve Magnell
SWS-0049				Mercury Kernel API  by Steve Magnell
SWS-0138				Mercury MDL Specification by Steve Magnell
SWS-0139				Mercury Player Component Interface Specification by Luke Kiernan
SWS-0143				Standard Interface Specification for Mercury Components by Luke Kiernan
2. Theory of Operation
2.1 Function of Decoder
A decoder would typically be used to play an audio file.  The audio file might be stored on the host system's disk or other mass storage device.  It would be coded so as to consume less storage space.  The coding might be some form of PCM, ADPCM or other.  This coded data would have to be 'decoded' (decompressed) prior to transmission.  The component that performs this function and resides on the Signal Processor is referred to as a decoder.  The component that resides on the Control Processor is referred to as a Player.
In addition to converting coded data from the format used for storage to a linear format needed for transmission1 the decoder may also provide such features as volume control, playback speed control, AGC and others.
2.2 Control of Decoder
A mechanism must be provided to inform the decoder where to get its input data, where to put its output data and what processing to perform on the data.  Messages sent to the decoder provide this mechanism.  They specify when the decoder instance starts and stops 'playing', what gain should be applied to the decoded data (volume), what average volume level should be sought (AGC), and at what speed the data should be played2.
These messages will originate in the Player Component residing on the Control Processor.  The Player component will, in turn, receive some control information from the host.  The Host will not, at this stage of development, communicate directly with the decoder component resident on the DSP.


Fig. 1	The Player Component may control several types of decoders
2.3 Adding New Decoders
For the Mercury architecture to be open, a mechanism must be provided to allow technology partners to provide support for other voice compression techniques; i.e., to add new decoders.  
There are two distinct ways that new coders may be added.  The first, shown in diagram below, uses the Dialogic Player interface.  Using this approach only the component resident on the DSP, the decoder, need be added.  The CP component is already provided.  It is necessary, then, to use the message set described in this specification.

Fig. 2	Addition of a new Decoder component using the Dialogic Player Interface
The second approach, shown below, involves the creation of a new player resource.  This additional effort yields the benefit that the resource writer is free to define his/her own message set interface.

Fig. 3	Addition of a new Decoder component using a proprietary player interface
2.4 
Start-up and Initialization - a brief summary
Download: A decoder starts life as a component of a module,  a part of a component of a module (if several types of decoders are implemented by one component), or, possibly, collection of modules (some of which may be 'passive', i.e., libraries).  This code, referred hereafter simply as the 'module', must be placed into the DSP's local memory such that its entry point is known.  This process is called downloading.
Component Initialization: A decoder module that is implemented as a component on a signal processor will have a task associated with it.  This task must be 'started', allowing for some component-level initialization.  The component will also register itself with the resource manager giving it a list of the components attributes and will, in response, receive its component address.  
Instance creation: The decoder is now ready to receive messages.  It will probably receive one or more set parameter messages.  These may specify the number of instances to create, modify default volume settings, etc.  Eventually a Std_MsgInit message is sent to the component.  It then creates as many instances as are specified by the Std_ParmInstNum parameter, allocating any memory needed for control structures and initializing these structures.  

Fig. 4	Message flow during decoder initialization.
For a more detailed description of this phase of operation refer Mercury Kernel Architecture Specification.
2.5 'Steady State' operation
Once the decoder instance has been created and initialized it is ready to receive messages including 'start playing'.  The remainder of this document is concerned with the control of the decoder during this steady state phase.
3. Environmental Requirements
3.1 Processor
The decoder will execute on the signal processor.  It will have available all kernel services provided for the SP kernel.  These are described in document SWS-0049, Mercury Kernel API .
3.2 Messaging
The decoder receives and transmits standard Mercury messages. The Player will be the only Component to send messages to the decoder.  That is, all messages from the host or other components containing control information for the decoder (e.g., parameters) must be addressed to the primary component, the Player.

3.3 Kernel and Player Version

3.4 Internal Memory
3.5 MMA - linear, RJ



4. Messaging Protocol
4.1 Kernel Messages
All messages described in the Mercury Kernel API are supported by this standard component.
4.2 Standard Component Messages
All messages defined in Standard Interface Specification for Mercury Components are supported by this component.
4.3 Dialogic Decoder-specific Messages to Instances
All decoder instances need to be given the following information:
* 	host input stream identifier
* 	PCM output stream identifier
* 	when to start conversion
* 	when to stop conversion
* 	when to pause
* 	when to continue
*  	what values to give to parameters (e.g., volume, speed)
The decoder also needs to provide information to the CP player component including:
* 	parameter values
* 	indication of completion of certain activities (events such as play complete)
* 	certain status information such as how many bytes have been read from host input stream.
Some of this control can be implemented using standard messages, e.g., set parameters or enable events.  Others require messages that are specific to this component.  These component-specific messages are described below.
4.3.1 Messages from Player to Decoder Instance

message
MsgStart
MsgStop
MsgPause
MsgResume

4.3.2 Messages from Decoder Instance to Player

4.3.2.1.1 Completion Messages

message
MsgStartCmplt
MsgStopCmplt 
MsgPauseCmplt
MsgResumeCmplt

4.3.2.1.2 Event Messages
Standard Event messages are used to indicate status updates.

4.4 Use of messages to control a decoder instance
Once the decoder instance has been initialized and registered (described above) it is ready to accept messages.  The first message the Dialogic Standard Decoder will accept is an Allocate Instance (InstAlloc).  The decoder instance will, in response, allocate any data buffers that it needs and return an Allocate Instance Complete message indicating whether it was successful.  
The existence of the Decoder Instance is now known to the Resource Manager.  It is now possible to get messages from other components.  For the Dialogic Standard Decoder the next message expected is a Std_MsgSetParm, to instruct the instance to set its parameters to specified values, or an Std_MsgDetectEvent message, to specify which events the Player is interested in knowing about (occurrence of these events will result in the appropriate event messages being sent to the Player instance that enabled the event). However, it is possible for a MsgStart to follow the InstAlloc message (if the default value of the parameters is acceptable) or a Free instance (deallocate instance) might be received if, for example, a call is terminated prior to start of play.
To aid in the understanding of the role of the remaining messages a state transition diagram is shown below.  The decoder may be in any of  four basic states: not allocated, allocated but stopped ('Idle'), started ('Playing') or paused (not playing, but maintaining data buffers).
The legality of a message is, in part, dependent upon the state of the decoder when it is received.  For example, receipt of a MsgStart message while in the Paused state is considered to be an error and results in an error message being sent to the Player instance that issued the erroneous message.  Only messages considered legal by the Dialogic Standard Decoder as shown below.  

Fig. 5 - Decoder states visible to Player and some messages that result in transitions.
For the most part the decoder is driven from one state to another by the receipt of command messages.  For example, if the decoder is in the IDLE state and receives a legal MsgStart command, it will make a transition into the PLAYING state.
Not all messages result in state transitions.  Specifically commands to 'set' or 'get' parameters or to enable or disable events do not result in changes of state. 
Nor are all state transitions due to the receipt of a message.  A decoder in the PLAYING state may encounter an end-of-data or end-of-file in the input data stream.  This will result in a transition from the PLAYING state to the IDLE state.
A decoder instance may receive a standard Exit message while in any state.  The response must be to deallocate all resources and enter the Not Allocated state.
5. Component Overview
<high level overview
Bstream -> Cstream
using Internal Memory><Each individual Mercury Component will have a description of how its message set implements the features of the product in that Component's Interface Specification or Architecture Specification. >

6. Message Set
The following messages are defined using the Mercury Message Definition Language (MMDL) with accompanying textual descriptions.  The output header file from this message description will be DEC_DEFS.H  

Message directional modifiers (i.e., in and out) are given with respect to the Decoder Component.

.file	"dec_defs.h"
.author	"Joe Barcelo, Catherine Cai"
.version	"Revision D-3.9"
<< 
MMDL comment: This file describes the list of  Standard Dialogic Decoder Messages.
>>

The Mercury Kernel definitions must not be used as definitions for any Component level information.

.sysdefs	"mercdefs.ext"
<< 
Standard Message Definitions
>>
.predefs "stddefs.ext"

For now we define the range for Decoder messages, error codes and parameters here. In future this may be automatically generated by the MMDL based on the Component Type.


.min	.message	0x0300
.max	.message	0x03FF
.min	.parameter	0x0300
.max	.parameter	0x03FF
.min	.error		0x0300
.max	.error		0x03FF

.component ADec=0x03
{
.uses
{
<< uses the standard messages >>
}
.defines
{
<< decoder-specific messages defined in following sections >>
6.1 
MsgStart

		
.message .in MsgStart
	{	
	.uint24 DecoderType 
	.uint24 OutputStreamID
	.uint24 Law {Mulaw,Alaw}
	.uint24 InputStreamID
	.uint24 offset
	}
	
 Description
	Target
This message may be sent to a decoder instance that is in the IDLE state.
	Interpretation
This message is interpreted to mean open input and output stream, advance read pointer offset milliseconds into the host input stream, discarding any data read while doing so, and begin converting data from that point into appropriate form for output stream.
The DecoderType specifies which decoder will be used for the addressed instance when multiple decoders are  supported by a decoder component.
The Law specifies whether a-law or (-law data is to be converted to linear data and transferred to the frontend by MMA.
Parameters provide additional information needed to determine the mapping from input to output (e.g., volume control and speed control)
	Return message
Returns MsgStartCmplt if play is successfully started.  Returns Std_MsgError message if any error condition prevents the execution of the MsgStart command.
	Error conditions
	decoder instance already started
	decoder instance paused
	unable to open specified input stream
	unable to open specified output stream
	unable to allocate memory
* offset beyond EOT or EOS
* unable to index into file
	Cautions
None.
6.2 MsgStartCmplt

		
.message .out MsgStartCmplt

	
 Description
	Target
This message may be sent to the source of the MsgStart command.
	Interpretation
This message is interpreted to mean that the MsgStart message was received by the source address and was successfully executed.  The decoding of the input stream has begun.
This message is not sent until the decoder instance has successfully advanced into the input stream offset milliseconds.
	Return message
None.
	Error conditions
None.
	Cautions
None.
6.3 MsgStop

		
.message .in MsgStop

	
 Description
	Target
This message may be sent to a Decoder instance that is in the PLAY or PAUSED state.
	Interpretation
This message is interpreted to mean 
1.	write silence into output stream,
2.	close output stream
3..	deallocate any resources allocated upon receipt of MsgStart
4.	close input stream 
5.	upon receipt of kernel message indication successful completion of close of stream, make state transition into IDLE state,
6.  and send MsgStopCmplt message to source of MsgStart.  Host can now write EOS to data stream.
	Return message
Returns MsgStopCmplt is play is successfully stopped.  Returns Std_MsgError message if any error condition prevents the execution of the MsgStop command.
	Error conditions
	decoder instance already stopped
	unable to return control of specified input stream
	unable to deallocate resources
	Cautions
None.
6.4 MsgStopCmplt

		
.message .out MsgStopCmplt
{
.uint24 Reason {EOT=2, EOS=0x80, MsgStop=4, ErrorStop=3, BrokenPipe=5}
.uint24 BytesPlayed
.uint24 TimePlayed
}

	
 Description
	Target
This message is sent to the source of the MsgStop message.
	Interpretation
This message is interpreted to mean 
1.	either the MsgStop message was received or an EOT or EOS was encountered in the input stream,
2.	silence has been written to the output stream,
3.	the input  stream was returned to player and output stream was closed,
4.	any resources allocated upon receipt of MsgStart were deallocated.
The reason that the instance stopped decoding input stream, the number of bytes played and the time played in milliseconds are included in the message body.
	Return message
None.
	Error conditions
None.
	Cautions
None.
6.5 MsgPause

		
.message .in MsgPause
	
 Description
	Target
This message may be sent to an decoder instance that is in the PLAYING state.
	Interpretation
The MsgPause message causes the decoder to stop the input stream, and to cause silence to be written to the output stream. 
	Return message
A PauseCmplt message is sent to the source of the Pause message once the decoder has entered the PAUSED state.
	Error conditions
	instance not in PLAYING state
	Cautions
None.
6.6 MsgPauseCmplt
		
.message .out MsgPauseCmplt

	
 Description
	Target
This message is sent to the source of the MsgPause message.
	Interpretation
This message may be interpreted to mean that the MsgPause message was received and successfully executed.  Silence is being 'played' to the output stream, no input data is being consumed.  The decoder is in the PAUSED state.
	Return message
None.
	Error conditions
None.
	Cautions
None. 
6.7 MsgResume

		
.message .in MsgResume
	
 Description
	Target
This message may be sent to an decoder instance that is in the PAUSED state.
	Interpretation
The MsgResume message causes the decoder to exit the PAUSED state and enter the PLAYING state.  It continues to consume data from the input stream from the current input pointer position and again places decoded data in the output stream.  The decoder must have been previously paused to be resumed.
	Return message
A MsgResumeCmplt message is sent to the source of the MsgResume message.
	Error conditions
	instance not paused
	Cautions
None.
6.8 MsgResumeCmplt

		
.message .out MsgResumeCmplt
	
 Description
	Target
This message is sent to the source of the MsgResume message.
	Interpretation
This message is interpreted to mean that the decoder has received and executed the MsgResume message.  The decoder has reentered the PLAYING state.
	Return message
None
	Error conditions
None  
	Cautions
None

6.9 MsgStatusEvt

		
.message .out MsgStatusEvt
{
.uint24 BytesPlayed
}

	
 Description
	Target
This message may be sent to the source of the MsgStart command.
	Interpretation
This message is generated each time another ParmBytesRead bytes of data have been read from the host input stream. The number of bytes read is reported in this message.
	Return message
None.
	Error conditions
None.
	Cautions
		   None.

6.10 MsgLoadDictionary

		
.message .in MsgLoadDictionary
{
.uint24	StreamId
.uint24 DictionaryId
.uint24	languageAttribute
.uint24	textAttribute	
}

	
 Description
	Target
This message may be sent to a decoder instance to initiate a dictionary load.
	Interpretation
This message is generated by the Player component to load a user dictionary.  The message fields describe the format of the dictionary.
	Return message
MsgLoadDictionaryCmplt.
	Error conditions
None.
	Cautions
None.
6.11 MsgLoadDictionaryCmplt

		
.message .out MsgLoadDictionaryCmplt
{
.uint24	StreamId
.uint24 DictionaryId
.uint24	languageAttribute
.uint24	textAttribute	
}

	
 Description
	Target
This message may be sent to a player instance to acknowledge completion of a dictionary load.
	Interpretation
This message is generated by the Decoder component to acknowledge load of a user dictionary.  The message fields describe the format of the dictionary.
	Return message
None.
	Error conditions
None.
	Cautions
None.

6.12 MsgActivateDictionary

		
.message .in MsgActivateDictionary
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a decoder instance to activate a dictionary.
	Interpretation
This message is generated by the Player component to activate a user dictionary.  The message field describes the identifier for the dictionary.
	Return message
MsgActivateDictionaryCmplt.
	Error conditions
None.
	Cautions
None.

6.13 MsgActivateDictionaryCmplt

		
.message .out MsgActivateDictionaryCmplt
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a player instance to acknowledge dictionary activation.
	Interpretation
This message is generated by the decoder component to acknowledge activation of a user dictionary.  The message fields describe the dictionary id.
	Return message
None.
	Error conditions
None.
	Cautions
None.

6.14 MsgUnloadDictionary

		
.message .in MsgUnloadDictionary
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a decoder instance to initiate a dictionary unload.
	Interpretation
This message is generated by the Player component to load a user dictionary.  The message fields describe the format of the dictionary.
	Return message
MsgLoadDictionaryCmplt.
	Error conditions
None.
	Cautions
None.
6.15 MsgUnloadDictionaryCmplt

		
.message .out MsgUnloadDictionaryCmplt
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a player instance to acknowledge completion of a dictionary unload.
	Interpretation
This message is generated by the Decoder component to acknowledge unload of a user dictionary.  The message fields describe the id of the dictionary.
	Return message
None.
	Error conditions
None.
	Cautions
None.

6.16 MsgDeactivateDictionary

		
.message .in MsgDeactivateDictionary
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a decoder instance to deactivate a dictionary.
	Interpretation
This message is generated by the Player component to deactivate a user dictionary.  The message field describes the identifier for the dictionary.
	Return message
MsgDeactivateDictionaryCmplt.
	Error conditions
None.
	Cautions
None.

6.17 MsgDeactivateDictionaryCmplt

		
.message .out MsgDeactivateDictionaryCmplt
{
.uint24 DictionaryId
}

	
 Description
	Target
This message may be sent to a player instance to acknowledge dictionary deactivation.
	Interpretation
This message is generated by the decoder component to acknowledge deactivation of a user dictionary.  The message fields describe the dictionary id.
	Return message
None.
	Error conditions
None.
	Cautions
None.



6.18 MsgStartx

		
.message .in MsgStartx
	{	
	.uint24 DecoderType 
	.uint24 OutputStreamID
	.uint24 Law {Mulaw,Alaw}
	.uint24 InputStreamID
	.uint24 offset
	.uint32  Volume
 	.uint32   Speed
	.uint32   SyncRecord
         
	}
	
 Description
	Target
This message may be sent to a decoder instance that is in the IDLE state.
	Interpretation
This message is interpreted to mean open input and output stream, advance read pointer offset milliseconds into the host input stream, discarding any data read while doing so, and begin converting data from that point into appropriate form for output stream.
The DecoderType specifies which decoder will be used for the addressed instance when multiple decoders are  supported by a decoder component.
The Law specifies whether a-law or (-law data is to be converted to linear data and transferred to the frontend by MMA.
The offset specifies where to start decoding.
The Volume specifies the value of the parameter ADec_ParmVolume.
The Speed  specifies the value of the parameter ADec_ParmSpeed.
The SyncRecord  specifies the value of the parameter ADec_ParmSyncRecord.
	Return message
Returns MsgStartCmplt if play is successfully started.  Returns Std_MsgError message if any error condition prevents the execution of the MsgStartx command.
	Error conditions
	decoder instance already started
	decoder instance paused
	unable to open specified input stream
	unable to open specified output stream
	unable to allocate memory
* offset beyond EOT or EOS
* unable to index into file
	Cautions
None.
7. Error Codes 
The following is a list of error codes specific to the Decoder that are returned in the Error code field of the Std_MsgError message.
<< 
Standard Component Error Code Definitions
>>
		
.error	ErrInStmOpn		<< an error while opening the host input stream >>
.error	ErrOStmOpn		<< an error while opening the PCM output stream >>
.error	ErrInStmURun		<< input stream data underrun >>
.error	ErrOStmURun		<< output PCM stream data underrun >>
.error	ErrOStmOvflw		<< decoder generating data faster than it can be consumed>>
.error	ErrBadStmData		<< some illegal input value >>
.error	ErrGMAlloc		<< unable to allocate global memory buffer >>
.error	ErrLMAlloc		<< unable to allocate local memory buffer >>
.error	ErrBadOffset		<< offset specified exceeds stream length>>
.error ErrInPlayState		<< inappropriate message: decoder in playing state >>
.error ErrInPauseState		<< inappropriate message: decoder in paused state >>
.error ErrInIdleState		<< inappropriate message: decoder in idle state >>
.error ErrInternalError		<< debug 'assert' >>

	

8. Parameters
The following is a list of parameters used with the Decoder component.
8.1 Component Level Parameters
General Parameters
.parameter .uint24 ParmHstOBufSiz 	<< default = 500 >>
<< The ParmHstOBufSiz parameter specifies how many milliseconds worth of samples to buffer in the >> << output stream.  Buffering this data permits the Pause and Stop message to specify, via a >>
<< Backspace parameter, that the last 'Backspace' samples should be discarded.  This is useful >>
<< for removing tones used to terminate record sessions.  ParmHstOBufSiz specifies the >>
<< maximum amount of data that can be truncated >>

Parameters related to Automatic Gain Control
.parameter .uint24 ParmAGC00		<< AGC on/off in component level >>
.parameter .uint24 ParmAGC01		<< Attack_Constant >>
.parameter .uint24 ParmAGC02		<< Noise_Floor_Decay >>
.parameter .uint24 ParmAGC03		<< Lower_AGC_Threshold >>
.parameter .uint24 ParmAGC04	 	<< Hangover_Time >>
.parameter .uint24 ParmAGC05		<< Very_Slow_Decay >>
.parameter .uint24 ParmAGC06		<< Upper_AGC_Threshold >>
.parameter .uint24 ParmAGC07		<< Gain_Taper >>
.parameter .uint24 ParmAGC08		<< K_Constant >>
.parameter .uint24 ParmAGC09		<< RFU >>
.parameter .uint24 ParmAGC10		<< RFU >>
.parameter .uint24 ParmAGC11		<< RFU >>
.parameter .uint24 ParmAGC12		<< RFU >>
.parameter .uint24 ParmAGC13		<< RFU >>
.parameter .uint24 ParmAGC14		<< RFU >>
.parameter .uint24 ParmAGC15		<< RFU >>
.parameter .uint24 ParmAGC16		<< RFU >>
.parameter .uint24 ParmAGC17		<< RFU  >>
.parameter .uint24 ParmAGC18		<< RFU  >>
.parameter .uint24 ParmAGC19		<< RFU  >>


The parameter  AGC00 will allow the application to enable or disable AGC prior to initialization.  There is an instance parameter of AGC on/off , see 8.2 description, which allows the application to tune on/off AGC for a specified instance during  run time.  If the application does not disable AGC on a component-wide basis prior to initialization, the Encoder will pick the default value, thus enabling AGC.

There are eight AGC parameters can be changed by the application.  All the parameters should be linear integer  values.  The fractional value should be converted to integer by multiplying by 2 23 in the application, and the conversion from dB to our internal linear representation is computed as: y(linear) = (2/() * 10 -x (db)/20 .  The following table shows the default value in decimal and hexadecimal:

Parameter Name
original value
converted to integer * 2 23    
 in Hex
AGC attack constant
0.3
2516582
0.266666
Noise floor decay
 0.0005
4194
1062
Lower agc threshold
0.00083923 (-57.6dB)
7039
1b7F
hangover time
0x1f4

1F4
very slow decay
0.99999
8388524
7FFFAC
upper agc threshold
0.01185 (-34.6dB)
99405
1844D
gain taper
0.05
419430
66666>>5=3333
K constant
0.2108 (-9.6dB)
1768318
1AFB7E>>D7DB

8.2 
Instance Level Parameters

8.2.1 Parameters related to Enable/Disable AGC

.parameter .uint24 ParmAGCOn		<< default = 1 >>

8.2.2 Parameters related to playback level
Playback amplitude depends upon a number of factors.  These include 
* record level, 
* amplitude adjustment by decoder, 
* and any gain or loss between the SC-backplane and the network.  
The decoder has control over only the second of these.  
There are four parameters that determine the gain or attenuation applied by the decoder instance:
1. ParmRecLvl - the level at which the stream arriving from the host was recorded. unit = dBm
2. ParmNrmLvl - the 'normal' level at which the output PCM stream would be played. unit = dBm
3. ParmVolume - the adjustment applied to ParmNrmLvl.  This parameter provides the mechanism for implementing 'volume control'.  unit = dB
4. ParmMaxVol - the largest value ParmVolume is allowed to take. unit = dB
The gain (or attenuation) applied by the decoder is computed as
	gain = DesiredLevel - ParmRecLvl 
where
	DesiredLevel = ParmNrmLvl + MIN(ParmVolume, ParmMaxVol).

The gain applied is therefore
gain = ParmNrmLvl + MIN(ParmVolume, ParmMaxVol) - ParmRecLvl

A detailed explanation may be found in the document Mercury Transmission Level Plan.

.parameter .uint24 ParmRecLvl		<< default = 0 >>
.parameter .uint24 ParmNrmLvl		<< default = -28 >>
.parameter .uint24 ParmVolume		<< default = 0 >>
.parameter .uint24 ParmMaxVol		<< default = +40 >>

8.2.3 Parameters related to playback speed
This parameter controls the speed at which the input stream is read.  Positive values specify a 'speed up'.  Negative values a 'slow down'.  The parameter is specified as a percentage of change from normal speed.  Normal speed is considered to be 100%.  Hence a parameter value of 20 is interpreted to mean a playback at 120% (100 + 20) of normal speed.  Similarly, a ParmSpeed of -40 is interpreted as "playback at 60% of normal speed", i.e., 100 + (-40).

.parameter .uint24 ParmSpeed		<< default = 0 >>
8.2.4 Parameters related to status events
If the status event is enabled the decoder will report, via the standard status event message, each time an EOD has been read by the decoder.  Status event reporting is controlled by the ParmEvtStatusReporting parameter.

.parameter .uint32 ParmEvtStatusReporting {On, Off}

Caution #1: The need to send this message adds load to the system.  If status updates are required they should be requested no more frequently than needed.  For example, if it is desired to update some field on a screen every second, and if we assume a 32kb/s ADPCM file is being played, it would be prudent to set ParmBytesRead to 4032.

Caution #2: If enabled the status event message is sent each time ParmBytesRead bytes have been read from the host input stream.  Thus the frequency of issuance of status event messages is dependent upon playback speed.

Caution #3: If the first data block of consecutive data blocks, separated by EOD, is less than 288 bytes, the decoder will report 577 bytes read from the host input stream. 

.parameter .uint24 ParmBytesRead	<< default = 4032, minimum = 1000 >>

Hint: By setting ParmBytesRead to a value larger than the number of bytes in the input stream the result would be a single status event message sent when play stopped.
8.2.5 Parameters related to synchronized play/record (transcoding)
This parameter indicates whether a synchronized play/record, or transcoding, is to occur. The corresponding parameters in the decoder and encoder must be set to the matching parameter value. If there is a mismatch in values, play or record failures will result.

.parameter .uint24 ParmSyncRecord {NOSYNC, SYNC}
9. Attributes
In addition to the standard attribute types Std_ComponentType, Std_ComponentID and Std_VendorID which must be initialized by this component the following are attribute types specific to the decoder:
Attribute name
Description
.external .attribute Std_ComponentType 
{ Std_ComponentType = 0x03}

<<
Decoder Component Type definition.
>>
.attribute DecoderType 
<<
coders defined in coders.h 
>>
.attribute Feature {VolCntrl=1, SpdCntrl=2, IndxPlay=3, AGC=4}
<<
Decoder features
>>
.external .attribute Std_ComponentId {DIALOGIC = 1}
<<
Dialogic Id.
>>


10. Event Types
The following is the only event type for the Mercury Decoder Component that may be enabled or disabled. It is supported by the decoder component and its instances.  When enabled, this event is sent to the Component specified in the ReturnAddress field of the Std_MsgDetectEvent message. It is sent using the Std_MsgEventDetected message.

<< 
Audio Decoder Event Type Definitions. 
>>
.message! out	Event
{
	.compdesc	ReturnAddress
	.uint32	Type	{EvtStatus=0x350}
	.uint32	Label
}

Event name
Description
.message! .out EvtStatus
{
    .uint32 Label
    .uint32 BytesRead
}
<<
EvtStatus is generated each time another ParmBytesRead bytes of data have been read from the host input stream. 

EvtStatus is also generated when a MsgStop is received.  

The number of bytes read is reported in this message. 
>>

11. Miscellaneous Equates
<<
End of all Mercury Decoder Component Definitions
>>
}
}
1 The actual data sent out onto the sc-bus is -law or A-law compressed PCM not linear. The linear-to-law compression is performed by hardware outside of the DSP.
2 The data is always transmitted at 8,000 samples per second.  Speed control may be achieved by decimating (to achieve speed-up) the input data stream or interpolating the input data (to achieve a slowdown).  The rate at which data is consumed from the input stream thus varies.
Mercury Standard Audio Decoder Interface SpecificationSWS-0141
Revision D - October 22, 2002


INTEL CONFIDENTIAL
42 of 42

