Intel IXP400 User Manual

209.92 Kb
Loading...

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

+ 39 hidden pages