Intel IXP400 User Manual

Intel® IXP400 Digital Signal

Processing (DSP) Software

Version 2.5

API Reference Manual

December 2004

Document Number: 273811-007a

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY RELATING TO SALE AND/OR USE OF INTEL PRODUCTS, INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT, OR OTHER INTELLECTUAL PROPERTY RIGHT.

Intel Corporation may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights that relate to the presented subject matter. The furnishing of documents and other materials and information does not provide any license, express or implied, by estoppel or otherwise, to any such patents, trademarks, copyrights, or other intellectual property rights.

Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. Intel may make changes to specifications and product descriptions at any time, without notice.

Designers must not rely on the absence or characteristics of any features or instructions marked “reserved” or “undefined.” Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.

Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.

Copies of documents which have an ordering number and are referenced in this document, or other Intel literature may be obtained by calling 1-800-548-4725 or by visiting Intel's website at http://www.intel.com.

BunnyPeople, Celeron, Chips, Dialogic, EtherExpress, ETOX, FlashFile, i386, i486, i960, iCOMP, InstantIP, Intel, Intel Centrino, Intel Centrino logo, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Xeon, Intel XScale, IPLink, Itanium, MCS, MMX, MMX logo, Optimizer logo, OverDrive, Paragon, PDCharm, Pentium, Pentium II Xeon, Pentium III Xeon, Performance at Your Command, Sound Mark, The Computer Inside, The Journey Inside, VTune, and Xircom are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Copyright © Intel Corporation, 2004

*Other names and brands may be claimed as the property of others.

2	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Contents

1.0	Introduction ............................................................................................................		7
	1.1	General............................................................................................................	7
	1.2	Scope ..............................................................................................................	7
	1.3	Audience .........................................................................................................	7
	1.4	Acronyms ........................................................................................................	7
2.0	Architectural Overview ......................................................................................		9
3.0	Media Processing Resource Components ..............................................		10
	3.1	Network Endpoint Resource Component ......................................................	10
	3.2	Decoder Resource Component.....................................................................	11
	3.3	Encoder Resource Component .....................................................................	13
	3.4	Tone Generation Resource Component .......................................................	15
	3.5	Tone Detection Resource Component ..........................................................	16
	3.6	Audio Player Resource Component ..............................................................	17
	3.7	Audio Mixer Resource Component ...............................................................	17
	3.8	T.38 Fax Resource Component ....................................................................	18
	3.9	Message Agent Resource Component .........................................................	19
4.0	Message Format and Delivery Mechanism..............................................		20
	4.1	Message Functions .......................................................................................	20
	4.2	Message Header Format...............................................................................	21
	4.3	Message Type List ........................................................................................	22
5.0	Common Control Message.............................................................................		23
	5.1	Reset Message .............................................................................................	23
	5.2	Start Message ...............................................................................................	23
	5.3	Stop Message ...............................................................................................	24
	5.4	Ping Message................................................................................................	24
	5.5	Set-Parameter Message ...............................................................................	24
	5.6	Set-Multiple-Parameter Message..................................................................	25
	5.7	Get-Parameter Message ...............................................................................	26
	5.8	Get-Parameter Acknowledge Message.........................................................	26
	5.9	Get-All-Parameters Message ........................................................................	26
	5.10	Get-All-Parameters Acknowledge Message..................................................	27
	5.11	General-Acknowledge Message ...................................................................	27
	5.12	Error Message...............................................................................................	28
	5.13	Event Message..............................................................................................	28
6.0	Resource-Specific Control Messages .......................................................		29
	6.1	CODEC Start Message .................................................................................	29
	6.2	CODEC Stop-Acknowledgement Message...................................................	29
	6.3	Tone Generator Play Message .....................................................................	30
	6.4	Tone Generator Play-FSK Message .............................................................	30
	6.5	Tone Generator Play-Completed Message...................................................	31
	6.6	Tone Detector Receive-Digit Message..........................................................	31
	6.7	Tone Detector Receive-Completed Message ...............................................	32

API Reference Manual

3

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

	6.8	Tone Detector Receive-FSK Message...........................................................	32
	6.9	Tone Detector FSK-Receive-Completed Message ........................................	33
	6.10	Player-Start Message.....................................................................................	33
	6.11	Player Play-Completed Message...................................................................	34
	6.12	Get-Jitter-Buffer-Statistics Message ..............................................................	35
	6.13	Complete Message of Getting Jitter Buffer Statistics.....................................	35
7.0	Packet Data Interface.........................................................................................		36
	7.1	Packet Formats ..............................................................................................	36
	7.2	Packet Delivery Mechanism...........................................................................	37
8.0	Configuration and Initialization.....................................................................		38
	8.1	System Configuration.....................................................................................	38
	8.2	Adding Tones to Tone Generator...................................................................	40
	8.3	Adding Tones to Tone Detector .....................................................................	41
	8.4	Getting DSP Resource Configuration and Routing Information .....................	42
9.0	Complementary Functions..............................................................................		44
	9.1	Direct Parameter Access ...............................................................................	44
	9.2	Flash Hook Detection.....................................................................................	44
	9.3	Cache Prompt Registration ............................................................................	45
	9.4	Get Version Number ......................................................................................	46
10.0	Constant Data.......................................................................................................		47
	10.1	Error Codes....................................................................................................	47
	10.2	Event Codes...................................................................................................	48
	10.3	Tone IDs.........................................................................................................	48
	10.4	Other Constants .............................................................................................	51

Figures

1	Architecture of Intel® IXP400 DSP Software v2.5	............................................9
2	Resource Component Identifiers....................................................................	10

Tables

None.

4	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Revision History

	Date	Revision	Description
	December 2004	008	Updated product branding.
	September 2004	007	Further updates for the release of Intel® IXP400 DSP Software
			v2.5. Change bars indicate areas of change.
	June 2004	006	Updates for the release of Intel® IXP400 DSP Software v2.5.
	January 2004	005	Updates for the release of Intel® IXP400 DSP Software
			Version 2.4.
	September 2003	004	Clarified input for XStatus_t xMsgReceive message
			function.
	September 2003	003	Updates for the release of Intel® IXP400 DSP Software
			Version 2.3
	March 2003	002	Added minor updates to represent features of Intel® IXP400
			DSP Software Version 1.1.
	January 2003	001	First release of this document.

API Reference Manual

5

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

This page intentionally left blank.

6	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Introduction

1.0Introduction

The Intel® IXP400 DSP Software v2.5 is a software module that provides the basic voice processing functionalities for VoIP residential gateway applications. It can be viewed as a completed media processing layer with control and data interfaces as its API.

This document defines the API specifications.

1.1General

The Intel® IXP400 DSP Software is a software module for media processing, targeted for next generation IADs such as Consumer Premise Equipment (CPE), specifically, to perform audio encoding/ decoding, echo cancellation, tone processing and jitter control, etc., as required in any IP media gateway or real-time media streaming functionalities.

This document is intended to describe the control and data interfaces in order for a third party developer to incorporate the module into a media gateway or server system. It provides sufficient details of the interfaces so that the user can fully configure and control the operations and services.

It additionally describes the data interface and format as well as message and data delivery mechanisms.

1.2Scope

The interface of DSP software is a set of functions, macros, and message and packet formats that determines how the applications access the media processing resource components.

1.3Audience

This document is intended for the following audiences:

•Firmware engineers who are responsible for the development of DSP Resources

•Third party software engineers who are building a gateway or server application

•System architects and engineers

•Project development managers

1.4Acronyms

AGC	Automatic Gain Control for voice data towards IP network
ALC	Automatic Level Control
CPE	Consumer Premise Equipment
EC	Echo Cancellation
FSK	Frequency Shift Keying
IP	Internet Protocol
ISR	Interrupt Service Routine

API Reference Manual

7

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Introduction

NLP	Non-linear Processing (for EC)
SP	Signal Processing
VAD	Voice Activity Detection

8	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Architectural Overview

2.0Architectural Overview

Intel® IXP400 DSP Software is implemented as an independent module having its own tasks and runtime environment. The software architecture is of a two-layer hierarchy – a control layer that provides the control interface and control logic, and a data processing layer where the media data streams are processed by appropriate algorithms. Figure 1 shows the architecture of the module.

In this architecture, a group of media resource (MPR) components forms a channel for full duplex media processing. They are the addressable entities that can be controlled individually by the applications.

Figure 1. Architecture of Intel® IXP400 DSP Software v2.5

				Intel® IXP400 DSP Software Client
							User-Defined
		Control			Replies and		Control
		Messages			Events		Messages
							and Replies
			Intel® IXP400 DSP				User-Defined
			Software Control Interface				Control Interface
			Common Control Logic and				Message
			Generic Control Engine				Agent
	Network	Decoder	Encoder		Tone	Tone	Audio	Audio	T.38
	Endpoint				Generator	Detector	Player	Mixer
									Control Layer
								Data Processing Layer
	SLIC	PCM			Data-Processing		Packet		IP
		Data			Algorithms and
	Interface						Interface		Stack
		Interface		PCM	Components
						Encoded
				Data		Packets
		Sync
				Real-Time Execution Environment

Revision 002

API Reference Manual

9

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Media Processing Resource Components

3.0Media Processing Resource Components

As shown in Figure 1, the addressable control entities of Intel® IXP400 DSP Software are media processing resource (MPR) components similar to those defined in many Intel Dialogic compute telephony system architecture. There are nine resource components, working together to provide all the media processing needed by a gateway or server channel. Each resource component has a unique identifier as shown below. In the following, we will refer to each of these nine media processing entities as either a resource or a resource component.

Figure 2. Resource Component Identifiers

typedef enum{
XMPR_ANY=0,	/* any resource, not currently supported */
XMPR_NET,	/* Network Endpoint resource */
XMPR_DEC,	/* Decoder resource */
XMPR_ENC,	/* Encoder resource */
XMPR_TNGEN,	/* Tone generator resource */
XMPR_TNDET,	/* Tone detector resource */
XMPR_PLY,	/* Audio player resource */
XMPR_MIX,	/* Audio mixer resource */
XMPR_T38,	/* T38 IP fax resource */
XMPR_MA	/* Message Agent resource */
} XMPResource_t;

Each resource contains a particular set of algorithms to perform a specific set of media-processing functions. For example, the Network Endpoint resource consists of echo cancellation, high pass filter and PCM A-law or µ-lawconversion algorithms to perform TDM front-end processing. Each resource, therefore, has a unique set of parameters associated with the particular set of algorithms it contains.

Communications of control information to these resource components are through messages defined in this document. Some messages are common to all the resources while others are unique only to a particular resource.

The following sections describe each resource in terms of their identifiers, media processing functions, parameters, and control messages. The resource parameters can be read or modified by the messages or direct function calls. Some of the parameters can only be set though the messages because they can only be updated by the internal control task.

3.1Network Endpoint Resource Component

Resource Type: XMPR_NET

Media Processing Functions

•A-law or µ-law compression and decompression

•High pass Filter

•Echo Cancellation (EC)

•Supplementary functions (timer and flash hook detection)

Resource-Specific Control Messages: None

10	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Media Processing Resource Components

Parameters

	Identifier	Description, Values	Attr.	Direct
				Write
	XPARMID_RES_STATE	Current state (0: idle, 1: active)	R	N
	XPARMID_NET_LP_STREAM	The L-Port stream ID. Default: the stream assigned to the IP termination’s T-	R/W	N
		Port of the same channel if exist, otherwise –1.
		PCM data format on HSS TDM bus. XPARM_NET_ALAW or
	XPARMID_NET_LAW	XPARM_NET_MULAW.	R/W	N
		Default: XPARM_NET_MULAW
	XPARMID_NET_ECENABLE	EC enabling flag, XPARM_ON or XPARM_OFF.	R/W	Y
		Default: XPARM_ON
		EC tail length (2, 4, 6, 8, ... in 1 ms unit, Max 64 in narrowband mode and 32
	XPARMID_NET_ECTAIL	in wideband mode).	R/W	N
		Default: 6. The resource must be reset after setting the parameter.
		EC NLP and suppress flag, XPARM_OFF, XPARM_EC_NLP_ON or
	XPARMID_NET_ECNLP	XPARM_EC_NLP_SUP_ON.	R/W	N
		Default: XPARM_OFF
	XPARMID_NET_ECFREEZE	EC freezing flag, XPARM_ON (freeze) or XPARM_OFF (adaptive).	R/W	N
		Typically, freeze is used only in debug situations. Default: XPARM_OFF
	XPARMID_NET_DELAYCOMP	EC delay compensation (0 ~ 240 in 0.125-ms units).	R/W	Y
		Default: 20 (or 2.5 ms delay compensation)
	XPARMID_NET_FLASH_HK	The window of flash hook detection (in 10-ms units)	R/W	Y
		Default: 100
		Timer counter (in 10 ms unit). This timer can be used for timing that is
	XPARMID_NET_TIMER	synchronized to the TDM clock.	R/W	Y
		Default: 0
	XPARMID_NET_GAIN_RX	Input gain of HSS interface (+15 ~ –40 in 1-dB units)	R/W	N
		Default: 0
	XPARMID_NET_GAIN_TX	Output gain of HSS interface (+15 ~ –40 in 1-dB units)	R/W	N
		Default: 0
		TDM short bypass flag, XPARM_ON or XPARM_OFF. The low latency
	XPARMID_NET_HSS_BYPASS	connection made within NPE between the corresponding time slots if	R/W	N
		enabled. Do not enable it in wideband mode.
		Default: XPARM_OFF

Events

•XEVT_NET_HOOK_STATE — Hook state change detected.

•XEVT_NET_TIMER — Timer expired.

3.2Decoder Resource Component

Resource Type: XMPR_DEC

API Reference Manual

11

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Media Processing Resource Components

Media Processing Functions

•Decoding

•Automatic level control and/or volume control

•Comfort noise generation

•Jitter compensation

Resource-Specific Control Messages

•XMSG_CODER_START (inbound)

•XMSG_CODER_STOP_ACK (outbound)

Parameters

	Identifier	Description and Values	Attr.	Direct
				Write
	XPARMID_RES_STATE	Current state (0: idle, 1: active)	R	N
	XPARMID_DEC_VOL	Decoder volume adjustment; +15 ~ -40 in 1-dB units.	R/W	N
		Default: 0 (Set to -99 to mute)
	XPARMID_DEC_ALC	ALC enable flag. XPARM_ON or XPARM_OFF.	R/W	N
		Default: XPARM_ON
	XPARMID_DEC_CNG	CNG enable flag. XPARM_ON or XPARM_OFF. Default:	R/W	Y
		XPARM_OFF
		Coder type. Currently supported types are
		XCODER_TYPE_G711MU_10MS,
		XCODER_TYPE_G711A_10MS, XCODER_TYPE_G729A
		or XCODE_TYPE_G723, XCODER_TYPE_G722,
	XPARMID_DEC_CTYPE	XCODER_TYPE_G726_40, XCODER_TYPE_G726_32,	R/W	N
		XCODER_TYPE_G726_24, XCODER_TYPE_G726_16,
		and XCODER_TYPE_G729.
		Default: XCODER_TYPE_G711MU_10MS
		Report bad and lost packet, caused by the jitter buffer unable to
	XPARMID_DEC_EVT_PKT	provide packets to the decoder. XPARM_ON or XPARM_OFF.	R/W	Y
		Default: XPARM_OFF
		Report RTP payload type change. XPARM_ON or
	XPARMID_DEC_EVT_PKTCHNG	XPARM_OFF.	R/W	Y
		Default: XPARM_ON.
		Auto-Switch mask bits. This specifies which coder types are
	XPARMID_DEC_AUTOSW	allowed to be auto-switched based on input RTP payload type.	R/W	Y
		Default: XPARM_DEC_AUTOSW_ALL
	XPARMID_DEC_JB_MAXDLY	Jitter buffer maximum delay (0 ~ 500 in 1-ms units).	R/W	N
		Default: 200.
	XPARMID_DEC_JB_PLR	Jitter buffer packet loss rate in 0.1% units.	R/W	N
		Default: 1

12	API Reference Manual

Intel® IXP400 Digital Signal Processing (DSP) Software Version 2.5

Media Processing Resource Components

	Identifier	Description and Values	Attr.	Direct
				Write
		RTP payload type for G.726 40-Kbps coder. The payload type is
	XPARMID_DEC_G726_40_RTP_PLD	negotiated and set by the call stack. The range of values is 96 to	R/W	Y
		127.
		Default: 96
		RTP payload type for G.726 32-Kkbps coder, The payload type is
	XPARMID_DEC_G726_32_RTP_PLD	negotiated and set by the call stack. The range of values is 96 to	R/W	Y
		127.
		Default: 97
		RTP payload type for G.726 24-Kbps coder, The payload type is
	XPARMID_DEC_G726_24_RTP_PLD	negotiated and set by the call stack. The range of values is 96 to	R/W	Y
		127.
		Default: 98
		RTP payload type for G.726 16kbps coder, The payload type is
	XPARMID_DEC_G726_16_RTP_PLD	negotiated and set by the call stack. The range of values is 96 to	R/W	Y
		127.
		Default: 99
		G.726 packing format. Set to XPARM_G726_PACK_LSB for RFC
	XPARMID_DEC_G726_PACK	3551 format, or XPARM_G726_PACK_MSB for I.366.2 Annex E	R/W	N
		format.
		Default: XPARM_G726_PACK_LSB

Events

•XEVT_LOST_PACKET – Bad or lost packet.

•XEVT_DEC_PACKET_CHNG – RTP payload type changed.

3.3Encoder Resource Component

Resource Type: XMPR_ENC

Media Processing Functions

•Encoding

•Automatic Gain Control

•Voice Activity Detection

Resource-Specific Control Messages

•XMSG_CODER_START (inbound)

•XMSG_CODER_STOP_ACK (outbound)

API Reference Manual

13