Intel Accelerated Dsp Software ® User Guide

Transcript

Intel® Accelerated DSP Software Package Version 1.1 User Guide November 2009 Document Number: 323037-001 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. 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. UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR. 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. The information here is subject to change without notice. Do not finalize a design with this information. The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. 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 order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-5484725, or by visiting Intel’s Web Site. Any software source code reprinted in this document is furnished under a software license and may only be used or copied in accordance with the terms of that license. Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. See http://www.intel.com/products/processor_number for details. BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Core Inside, i960, Intel, the Intel logo, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, the Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, InTru, the InTru logo, InTru soundmark, Itanium, Itanium Inside, MCS, MMX, Pentium, Pentium Inside, skoool, the skoool logo, Sound Mark, The Journey Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries. *Other names and brands may be claimed as the property of others. Copyright © 2009, Intel Corporation. All rights reserved. Intel® Accelerated DSP Software Package Version 1.1 User Guide 2 November 2009 Document Number: 323037-001 Contents Contents 1.0 Introduction ..............................................................................................................7 1.1 Acronyms........................................................................................................... 7 1.2 Related Documents ............................................................................................. 7 2.0 Intel® Accelerated DSP Software Package Version 1.1 Setup Procedure .................... 8 3.0 IP PBX Reference Application .................................................................................. 11 3.1 Overview ......................................................................................................... 11 3.1.1 Technology Used .................................................................................... 11 3.2 Dependencies ................................................................................................... 12 3.3 Functional Description........................................................................................ 12 3.3.1 Application Features ............................................................................... 12 3.3.1.1 Codec Support.......................................................................... 12 3.3.1.2 Three Way Call Hosting.............................................................. 12 3.3.1.3 Jitter Buffer Support.................................................................. 12 3.3.2 Hardware Interface................................................................................. 12 3.3.3 RTP Interface......................................................................................... 12 3.4 Application Menu ............................................................................................... 13 3.4.1 SETUP A CALL........................................................................................ 13 3.4.1.1 Enter the call ID: ...................................................................... 13 3.4.1.2 Enter the endpoint ID:............................................................... 13 3.4.1.3 Enter the IP Address of the remote party: .................................... 13 3.4.1.4 Enter the codec to use: ............................................................. 13 3.4.1.5 Enter the number of frames per packet: ...................................... 13 3.4.1.6 Add another endpoint (1=YES 0=NO):......................................... 14 3.4.2 SETUP MAX IP CALLS .............................................................................. 14 3.4.2.1 Enter the IP Address of the remote party: .................................... 14 3.4.2.2 Enter the codec to use: ............................................................. 14 3.4.2.3 Enter the number of frames per packet: ...................................... 14 3.4.3 TEARDOWN CALL ................................................................................... 15 3.4.3.1 Enter the call number to teardown: ............................................. 15 3.4.4 TEARDOWN ALL CALLS ........................................................................... 15 3.4.5 SET PARAMETER .................................................................................... 15 3.4.5.1 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels:.................................. 15 3.4.5.2 Enter the pipeline Direction(Inbound=0, Outbound=1): ................. 15 3.4.5.3 Enter the component ID(position in pipeline): ............................... 15 3.4.5.4 Enter the parameter number: ..................................................... 15 3.4.5.5 Enter the parameter value: ........................................................ 15 3.4.5.6 Set Parameter Example ............................................................. 16 3.4.6 PRINT COMPONENT PARAMETERS............................................................. 16 3.4.6.1 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels:.................................. 16 3.4.6.2 Enter the pipeline Direction(Inbound=0, Outbound=1): ................. 16 3.4.6.3 Enter the component ID(position in pipeline): ............................... 16 3.4.6.4 Get Parameters Example............................................................ 16 3.4.7 EXIT ..................................................................................................... 17 3.5 Usage Scenarios................................................................................................ 17 3.5.1 Basic PBX Call........................................................................................ 17 3.5.1.1 Basic PBX Call Example.............................................................. 17 3.5.2 Three-Way Call ...................................................................................... 18 4.0 IP/Media Phone Reference Application.................................................................... 19 4.1 Overview ......................................................................................................... 19 4.1.1 Technology Used .................................................................................... 19 November 2009 Document Number: 323037-001 Intel® Accelerated DSP Software Package Version 1.1 User Guide 3 Contents 4.2 4.3 4.4 4.5 Dependencies....................................................................................................20 Functional Description ........................................................................................20 4.3.1 Application Features................................................................................20 4.3.1.1 Codec Support ..........................................................................20 4.3.1.2 Acoustic Echo Cancellation..........................................................20 4.3.1.3 Three-Way Calling .....................................................................20 4.3.1.4 Jitter Buffer Support ..................................................................20 4.3.1.5 Caller ID ..................................................................................20 4.3.1.6 Sidetone ..................................................................................21 4.3.2 Hardware Interface .................................................................................21 4.3.2.1 ALSA Buffer Underrun ................................................................21 4.3.3 RTP Interface .........................................................................................21 Application Menu ...............................................................................................21 4.4.1 OFF HOOK .............................................................................................21 4.4.1.1 Enter the ALSA hardware ID in the form "plughw:x,x":...................22 4.4.2 ON HOOK ..............................................................................................22 4.4.3 MAKE A CALL .........................................................................................22 4.4.3.1 Enter the local line number to use: ..............................................22 4.4.3.2 Enter the remote line number to use: ..........................................22 4.4.3.3 Enter the IP address of the remote party:.....................................22 4.4.3.4 Enter the codec to use: ..............................................................22 4.4.3.5 Enter the number of frames per packet: .......................................23 4.4.4 SWITCH LINE .........................................................................................23 4.4.5 3 WAY CALL ...........................................................................................23 4.4.6 REVERT TO 2 WAY CALL ..........................................................................23 4.4.7 SEND DTMF STRING................................................................................23 4.4.7.1 Enter the line direction: 1 play to PCM side - 0 play to IP side - .......23 4.4.7.2 Enter the number of tones to be played - .....................................23 4.4.7.3 Enter the tone id -.....................................................................23 4.4.8 SET PARAMETER.....................................................................................23 4.4.8.1 Enter the pipeline Type(PCM=0, IP=1): ........................................23 4.4.8.2 Enter the numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: ....................................................23 4.4.8.3 Enter the pipeline Direction(Inbound=0, Outbound=1): ..................24 4.4.8.4 Enter the component ID(position in pipeline): ...............................24 4.4.8.5 Enter the parameter number: .....................................................24 4.4.8.6 Enter the parameter value:.........................................................24 4.4.8.7 Set Parameter Example..............................................................24 4.4.9 PRINT COMPONENT PARAMETERS .............................................................24 4.4.9.1 Enter the pipeline Type(PCM=0, IP=1): ........................................24 4.4.9.2 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: ..................................24 4.4.9.3 Enter the pipeline Direction(Inbound=0, Outbound=1): ..................25 4.4.9.4 Enter the component ID(position in pipeline): ...............................25 4.4.9.5 Get Parameters Example ............................................................25 4.4.10 EXIT .....................................................................................................25 Usage Scenarios ................................................................................................25 4.5.1 Basic Endpoint-to-Endpoint Call ................................................................25 4.5.1.1 Basic Endpoint-to-Endpoint Call Example ......................................26 4.5.2 Three-Way Call.......................................................................................26 4.5.2.1 Three-Way Call Example ............................................................27 Figures 1 2 3 IP PBX Reference Application Block Diagram ................................................................11 Component IDs for PCM and IP Pipeline Components.....................................................15 Basic PBX Call Setup .................................................................................................17 Intel® Accelerated DSP Software Package Version 1.1 User Guide 4 November 2009 Document Number: 323037-001 Contents 4 5 6 7 Three-Way Call Setup ............................................................................................... 18 IP/Media Phone Reference Application Block Diagram.................................................... 19 Basic Endpoint-to-Endpoint Call Setup ........................................................................ 25 Three-Way Call Setup ............................................................................................... 26 Tables 1 2 Acronym List ............................................................................................................. 7 Related Documents .................................................................................................... 7 November 2009 Document Number: 323037-001 Intel® Accelerated DSP Software Package Version 1.1 User Guide 5 Revision History Revision History Date Revision November 2009 001 Description Initial release. §§ Intel® Accelerated DSP Software Package Version 1.1 User Guide 6 November 2009 Document Number: 323037-001 Introduction 1.0 Introduction This document provides basic installation instructions for the Intel® Accelerated DSP Software Package Version 1.1 (ADS 1.1), and presents information about the related PBX and Endpoint reference applications. 1.1 Acronyms Table 1 describes acronyms used in this document. Table 1. Acronym List Acronym Description ® ADS Intel AEC Acoustic Echo Cancellation Accelerated DSP Software ALSA Advanced Linux Sound Architecture DUT Device Under Test IP GNU IP PBX IPP Internet Protocol GNU’s Not Unix Internet Protocol Private Branch Exchange Intel Performance Primitive LPIA Low-Power Intel Architecture MIDI Musical Instrument Digital Interface oRTP OS Open RTP Operating System PCM Pulse-Code Modulation RTCP Real-Time Control Protocol RTP Real-time Transport Protocol USB Universal Serial Bus 1.2 Related Documents Table 2. Related Documents Document Name Intel ® Document Number Accelerated DSP Software Release Notes 323035 Intel® Accelerated DSP Software API Reference Manual 323036 Intel ® Accelerated DSP Software Programmer’s Guide November 2009 Document Number: 323037-001 323038 Intel®Accelerated DSP Software Reference Application User Guide 7 Intel® Accelerated DSP Software Package Version 1.1 Setup Procedure 2.0 Intel® Accelerated DSP Software Package Version 1.1 Setup Procedure The steps in this section are used to set up ADS 1.1, which has been validated on: — Intel® EP80579 Integrated Processor based platform with the Red Hat* Enterprise Linux 5* with Linux* kernel 2.6.18 operating system — Intel® Core™ i7-based platforms with the CentOS* 5.3 (32-bit) operating system — Intel® Atom™ processor-based platforms with the Moblin* v2.0 netbook operating system (Linux kernel 2.6.30.3-4.1.moblin2-netbook) downloaded from http://moblin.org/downloads/netbook 1. Install a supported OS on a supported target. Note: When installing the OS, ensure that no firewall is blocking incoming RTP packets. Some Linux distributions will block by default so it is recommended that SELinux* is disabled and the iptables service is stopped or not installed. a. When using ADS in IP-PBX mode, it may be necessary to increase the Linux limit of number of open file handles when running with a large number of channels. This is due to the implementation of libORTP*. libORTP requires one file handle for each RTCP or RTP port. The current limit can be seen by running the command “ulimit –n”. The ADS IP-PBX reference application requires two file handles per RTP endpoint plus some additional file handles for the ADS framework. You should set this limit to a suitably large number (for example, ulimit –n 4096). You can make this change permanent by editing the file /etc/ security/limits.conf. 2. Ensure that other peripheral drivers for your platform are installed. a. If Ethernet* does not work out of the box, ensure to install Ethernet drivers and configure the device. 3. If they are not already installed, install the other required packages. a. The required packages are ALSA development library and GNU* C++. b. Those packages can be installed via yum by using the following command: yum install alsa-lib-devel gcc-c++ compat-gcc-xx compat-gcc-xx-c++ Note: xx denotes the gcc version number. 4. Install oRTP*. Note: a. Create a work directory; for example, “mkdir /ads_setup”. b. Download the latest oRTP source from http://freshmeat.net/projects/ortp/ c. Extract oRTP source into the work directory. d. Follow the INSTALL document included the package for installation. e. Do not clean or remove the oRTP source before building the ADS reference application. oRTP 0.15.0 was validated for ADS 1.1. Intel®Accelerated DSP Software Reference Application User Guide 8 November 2009 Document Number: 323037-001 Intel® Accelerated DSP Software Package Version 1.1 Setup Procedure 5. Install IPPs. Note: a. The IPP architecture for the Intel Core i7 processor is “ia32”, and for Intel Atom processors is “lp32”. b. Download IPP and IPP samples for the appropriate architecture from http:// software.intel.com/en-us/intel-ipp/ c. Download the installation instructions from the same location. d. Follow the instructions and install IPP. The recommended installation path for IPP is “/opt/intel/ipp”. e. The following two commands need to be executed once to make the dynamic libraries of IPP accessible for all applications even after a reboot. echo "/opt/intel/ipp///sharedlib/" > /etc/ld.so.conf.d/ ipp.conf /sbin/ldconfig where the VERSION should be similar to “6.x.x.xyz” and the ARCH should be either “ia32” or “lp32”. Note: IPP 6.0.1.071 for IA-32 architecture was validated for ADS 1.1. 6. Install IPP samples Note: a. If not previously downloaded, download IPP samples from http:// software.intel.com/en-us/intel-ipp/ b. Extract IPP samples into the IPP install directory selected in Step5.e. The recommended installation path for IPP is “/opt/intel/ipp”. c. The above will create a “ipp-samples” directory parallel to the IPP version directory. d. Source the bash script “< IPP install directory >/< VERSION >/< ARCH >/tools/ env/ippvars32.sh” to set IPP environment variables. e.g. source /opt/intel/6.0.1.071/lp32/tools/env/ippvars.sh Note: e. Go to the directory “speech-codecs” under “ipp-samples”. f. Run the script “build32.sh” to build speech codecs. IPP samples 6.0.0.142 was validated for ADS 1.1. 7. Install ADS. a. Extract the ADS package. b. Set ADS_ENV_DIR to . For example: export ADS_ENV_DIR=//ads c. Set ADS_ORTP_BASE to . For example: export ADS_ORTP_BASE=//ortp- d. Set ADS_IPP_ROOT to . For example: export ADS_IPP_ROOT=/opt/intel/ipp/ e. Set ADS_IPP_SAMPLE_ROOT to . For example: export ADS_IPP_SAMPLE_ROOT=/opt/intel/ipp/ipp-samples f. Set ADS_ARCH to the correct architecture. For the Intel EP80579 Integrated Processor: export ADS_ARCH=ia32 For the Intel Core i7 processor: export ADS_ARCH=ia32 For LPIA processors: export ADS_ARCH=lp32 November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 9 Intel® Accelerated DSP Software Package Version 1.1 Setup Procedure g. Execute the following commands to build an ADS IP/Media Phone application. If you have previously built the IP-PBX application, do a make clean before issuing the following commands. cd $ADS_ENV_DIR/refApp make ADS_REF_APP=endpoint h. Execute the following commands for building an ADS PBX application. If you have previously built the IP/Media Phone application, do a make clean before issuing the following commands. cd $ADS_ENV_DIR/refApp make ADS_REF_APP=pbx i. IP/Media Phone and PBX reference applications are stored in $ADS_ENV_DIR/ refApp/build/linux_2.6/user_space The build folder must be cleaned when switching between building the ADS IP/ Media Phone application and the ADS IP-PBX application. The clean command will clean the entire build folder. Either of the following commands can be used as they both perform the same operation. make clean ADS_REF_APP=endpoint make clean ADS_REF_APP=pbx 8. Run the IP/Media Phone Reference Application. To run the IP/Media Phone Reference Application two wav files must be passed into the application as command line parameters. These wav files are used as the on hold audio for wideband and narrowband calls. These wav files must be signed, 16bit LE, mono files with a sample rate of 8 kHz for the narrowband file and a sample rate of 16 kHz for the wideband file. The steps below give an example of how these files can be generated using Linux arecord. The examples use the plughw:0,0 audio device, but this will be platform-specific. By default, ALSA uses the following format for plug devices: plughw:x,0 where x is the card number. To determine the card number of the device, run "ls -al /proc/asound". This will list the available ALSA devices on your system. Note: If there is no audio card supported on the platform, a USB headset, etc., can be used. a. Change into the build directory. cd $ADS_ENV_DIR/refApp/build/linux_2.6/user_space b. Create the narrowband hold audio file (10 seconds long). arecord -d 10 -t wav -f S16_LE -r 8000 -D plughw:0,0 nb_audio.wav c. Create the wideband hold audio file (10 seconds long). arecord -d 10 -t wav -f S16_LE -r 16000 -D plughw:0,0 wb_audio.wav d. Run the IP/Media Phone Reference Application. ./adsTelEpApp nb_audio.wav wb_audio.wav 9. Run the PBX Reference Application. a. Change into the build directory. cd $ADS_ENV_DIR/refApp/build/linux_2.6/user_space b. Run the IP-PBX Reference Application. ./adsTelPbxApp Intel®Accelerated DSP Software Reference Application User Guide 10 November 2009 Document Number: 323037-001 IP PBX Reference Application 3.0 IP PBX Reference Application 3.1 Overview The IP PBX Reference Application is a Linux* user-space application. It is a sample application only. Its purpose is to demonstrate how an IP PBX application can be constructed using the ADS Framework. Features of the application include transcoding and three-way call hosting. A menu is provided to allow user input to the application. Options are provided to set up and teardown calls. A detailed description of the menu options is provided in Section 3.4. Figure 1 shows the functional block layout of the design. The reference application resides on top of the ADS framework and uses the ADS APIs to configure the ADS framework. The reference application uses a third-party RTP stack to provide all RTP functionality. Figure 1. IP PBX Reference Application Block Diagram 3.1.1 Technology Used • Linux OS Linux is the operating system that this application is supported on. • Intel Performance Primitives The IPPs are an extensive library of multicore-ready, highly optimized software functions for multimedia data processing, and communications applications. • RTP Stack A fully functional Real Time Transport Protocol stack is integrated into the application and used to transmit voice packets over the Internet. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 11 IP PBX Reference Application 3.2 Dependencies The reference application has a dependency on the following: • ADS Framework and IPPs • ORTP RTP Stack • Linux IP Stack 3.3 Functional Description The IP PBX Application demonstrates how an IP PBX application can be developed using the ADS Framework. The application supports up to 10 calls and 20 IP endpoints by default. This can be changed by editing the MAX_IP_LINES_SUPPORTED define in adsTelCommon.h and recompiling the reference application. Individual call connections can be set up and torn down using the application menu. Up to three connections are supported per call. An option is also provided to set up the maximum amount of calls and to tear down all calls. Transcoding between different legs of a call is performed automatically. 3.3.1 Application Features 3.3.1.1 Codec Support The reference application supports all codecs that are supported by the ADS Framework. A option to select the codec is provided when making a call. See Section 3.4 for more details. 3.3.1.2 Three Way Call Hosting The application supports three-way calling hosting. To set up a three-way call simply add three endpoints to a call. 3.3.1.3 Jitter Buffer Support The oRTP jitter buffer is enabled by default in adaptive mode with a 40ms jitter delay. This value can be changed by modifying the RTP_JB_COMPENSATION define in adsTelRTP.c 3.3.2 Hardware Interface The IP PBX application has no hardware interface. Only IP endpoints are currently supported by the application. 3.3.3 RTP Interface The application uses a third-party RTP stack to provide RTP support. oRTP is the only library that is currently supported. For each RTP connection the RTP port is configured to be bidirectional. The RTP stack uses 6000 as the base port. The RTP port number for an IP Endpoint is the (endpoint number*2) + RTP base port, that is, the RTP port number for IP endpoint 2 = (2*2) + 6000 = 6004. If the RTP base port needs to be changed it can be done by editing the RTP_BASE_PORT define in adsTelRTP.c and recompiling the reference application. Intel®Accelerated DSP Software Reference Application User Guide 12 November 2009 Document Number: 323037-001 IP PBX Reference Application 3.4 Application Menu The top-level application menu consists of the following options. 3.4.1 SETUP A CALL This option allows the user to set up a call. 3.4.1.1 Enter the call ID: This option selects the call ID number that will be used. The call ID can be in the range of 0 to ((MAX_IP_LINES_SUPPORTED/2) -1). 3.4.1.2 Enter the endpoint ID: This option selects an IP endpoint to add to the call. The endpoint ID can be in the range of 0 to (MAX_IP_LINES_SUPPORTED -1). The maximum number of endpoints supported can be changed by modifying adsTelPbx.h 3.4.1.3 Enter the IP Address of the remote party: This is the IP address of the remote end of this endpoint connection. 3.4.1.4 Enter the codec to use: This option selects the codec that is used for the call. The available options are: Pass Through Mode: 0 - Not supported in the ADS 1.1 Release G711 U Law: 1 G711 A law: 2 G729A: G723: 3 4 - Not supported in the ADS 1.1 Release G722_64: 5 G722_56: 6 G722_48: 7 G726_40: 8 G726_32: 9 G726_24: 10 G726_16: 11 G729_1: 12 - Not supported in the ADS 1.1 Release G722_1: 13 - Not supported in the ADS 1.1 Release 3.4.1.5 Enter the number of frames per packet: The option selects the number of frames that will be transmitted per packet. This can be used to reduce the network traffic of the call. The allowable range is between 1 and 10. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 13 IP PBX Reference Application 3.4.1.6 Add another endpoint (1=YES 0=NO): Selecting 0 will set up the call based on the current information. Select 1 to add another endpoint to the call. 3.4.2 SETUP MAX IP CALLS This option will set up the maximum amount of two-way calls allowed. The call configuration will be as follows: Call 0: Endpoint 0 and Endpoint 1 Call 1: Endpoint 2 and Endpoint 3 .... ............ ............ Call 9: Endpoint 18 and Endpoint 19 3.4.2.1 Enter the IP Address of the remote party: This is the IP address of the remote end for all endpoint connections. 3.4.2.2 Enter the codec to use: This option selects the codec that will be used for all calls. The available options are: Pass Through Mode: 0 - Not supported in the ADS 1.1 Release G711 U Law: 1 G711 A law: 2 G729A: G723: 3 4 - Not supported in the ADS 1.1 Release G722_64: 5 G722_56: 6 G722_48: 7 G726_40: 8 G726_32: 9 G726_24: 10 G726_16: 11 G729_1: 12 - Not supported in the ADS 1.1 Release G722_1: 13 - Not supported in the ADS 1.1 Release 3.4.2.3 Enter the number of frames per packet: The option selects the number of frames that will be transmitted per packet. This can be used to reduce the network traffic of the calls. the allowable range is 1 to 10. Intel®Accelerated DSP Software Reference Application User Guide 14 November 2009 Document Number: 323037-001 IP PBX Reference Application 3.4.3 TEARDOWN CALL This option tears down a call. 3.4.3.1 Enter the call number to teardown: This option selects the call ID to teardown. 3.4.4 TEARDOWN ALL CALLS This option tears down all connected calls. 3.4.5 SET PARAMETER This option is used to set a component parameter. Figure 2. Component IDs for PCM and IP Pipeline Components 3.4.5.1 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: This option selects the endpoints to set the parameter for. Entering the max value will set the parameter for all endpoints in the range that are configured. A commaseparated list of endpoint numbers can also be selected. 3.4.5.2 Enter the pipeline Direction(Inbound=0, Outbound=1): This option selects either the inbound or outbound pipeline of the endpoint. 3.4.5.3 Enter the component ID(position in pipeline): This option selects the component within the pipeline. The component numbers are zero-based. 3.4.5.4 Enter the parameter number: The parameter number that is to be set. See the Programmers Guide for the parameter table for each component. 3.4.5.5 Enter the parameter value: The value to set the parameter to. See the Programmers Guide for the parameter table for each component. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 15 IP PBX Reference Application 3.4.5.6 Set Parameter Example This example will disable VAD in the Encoder block of the outbound IP pipeline for IP endpoint 10. Note: A call must have been previously set up on endpoint 10. Please select test item - 5 Enter the endpoint numbers(0-19) delimited by comma in the format x,y,z OR enter 20 for all channels: 10 Enter the pipeline Direction(Inbound=0, Outbound=1):1 Enter the component ID(position in pipeline):3 Enter the parameter number:1 Enter the parameter value:0 3.4.6 PRINT COMPONENT PARAMETERS This option prints the parameter settings for a component. See the Programmers Guide for the parameter table for each component. 3.4.6.1 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: Entering the max value will return the parameters for all endpoints in the range that are configured. A comma-separated list of endpoint numbers can also be selected. See the Programmers Guide for the parameter table for each component. 3.4.6.2 Enter the pipeline Direction(Inbound=0, Outbound=1): This option selects either the inbound or outbound pipeline of the endpoint. See Figure 2. 3.4.6.3 Enter the component ID(position in pipeline): This option selects the component within the pipeline. The component numbers are zero-based. See Figure 2. 3.4.6.4 Get Parameters Example This example will display the parameters for the Decoder in the inbound bound IP pipeline for IP endpoint 10. Note: A call must have been previously set up on endpoint 10. Please select test item - 6 Enter the endpoint numbers(0-19) delimited by comma in the format x,y,z OR enter 20 for all channels: 10 Enter the pipeline Direction(Inbound=0, Outbound=1):0 Intel®Accelerated DSP Software Reference Application User Guide 16 November 2009 Document Number: 323037-001 IP PBX Reference Application Enter the component ID(position in pipeline):0 3.4.7 EXIT This option shuts down the application, unconfigures the ADS framework and releases any resources that are being used by the application. 3.5 Usage Scenarios In the following usage scenarios the IP Phones must be able to match the configuration of the DUT. Instances of the ADS IP Endpoint Reference Application may be used as the IP phones. 3.5.1 Basic PBX Call Figure 3 shows the setup required to make a basic PBX call. Figure 3. Basic PBX Call Setup Setting up the DUT to handle a two-way call between the IP Phones requires the following steps. 1. The SETUP CALL command is entered on the DUT using the reference application. 2. The endpoint numbers, IP addresses and MFPP setting of both legs of the call are entered. 3. The IP Phone configurations must match that of the corresponding DUT leg. 4. All RTP traffic passes between the IP Phones via the DUT. 5. The TEARDOWN ALL CALLS command is entered on the DUT using the reference application and the call is disconnected. 3.5.1.1 Basic PBX Call Example 1. Run ./adsTelPbxApp 2. Select 1, for "Setup Call" 3. Enter the call ID: 0 4. Enter the endpoint number: 0 5. Key in remote ip address for "Enter the IP Address of the remote party" 6. Select G.711 ulaw codec, "Enter the codec to use: 1" 7. Key in 1 for "Enter the number of frames per packet:" 8. When prompted to "Add another endpoint (1=Yes 0=No):", select "1" 9. Enter the endpoint number: 1 10. Key in remote ip address for "Enter the IP Address of the remote party" November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 17 IP PBX Reference Application 11. Select G.711 ulaw codec, "Enter the codec to use: 1" 12. Key in 1 for "Enter the number of frames per packet:" 13. When prompted to "Add another endpoint (1=Yes 0=No):", select "0" 14. Set up the IP Phones as in Section 4.5.1.1, using 0 for the remote and local line number in one case and using 1 for the remote and local line number in the other case. At this point a call should be established between IP Phone 1 and IP Phone 2. 3.5.2 Three-Way Call Figure 4 shows the setup required to make a three-way call. Figure 4. Three-Way Call Setup To setup the DUT to handle a three way call between the IP Phones requires the following steps. 1. The SETUP CALL command is entered on the DUT using the reference application. 2. The endpoint numbers, IP addresses and MFPP setting of the three legs of the call are entered. 3. The IP Phone configurations must match that of the corresponding DUT leg. 4. All RTP traffic passes between the IP Phones via the DUT. The TEARDOWN ALL CALLS command is entered on the DUT using the reference application and the call is disconnected. Intel®Accelerated DSP Software Reference Application User Guide 18 November 2009 Document Number: 323037-001 IP/Media Phone Reference Application 4.0 IP/Media Phone Reference Application 4.1 Overview The IP/Media Phone Reference Application is a Linux* user-space application. It is a sample application only. Its purpose is to demonstrate how an IP/Media Phone application can be constructed using the ADS Framework. The application supports all codecs that are supported by the ADS Framework. Other features of the application include three-way calling and echo cancellation. The Linux ALSA library is used as the PCM interface to play and capture audio. A menu is provided to allow user input to the application. Options are provided to simulate phone behavior such as on hook, off hook and the dialing of numbers. A detailed description of the menu options is provided in Section 4.4. Figure 5 shows the functional block layout of the design. The reference application resides on top of the ADS Framework and uses the ADS APIs to configure the ADS Framework. The reference application uses a third-party RTP stack to provide all RTP functionality. Figure 5. IP/Media Phone Reference Application Block Diagram 4.1.1 Technology Used • Linux OS Linux is the operating system that this application is supported on. • Intel Performance Primitives November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 19 IP/Media Phone Reference Application The IPPs are an extensive library of multicore-ready, highly optimized software functions for multimedia data processing and communications applications. • ALSA Library The Advanced Linux Sound Architecture (ALSA) provides audio and MIDI functionality to the Linux OS. • RTP Stack A fully functional Real-time Transport Protocol stack is integrated into the application and used to transmit voice packets over the Internet. 4.2 Dependencies The reference application has a dependency on the following: • ADS Framework and IPPs • ORTP RTP Stack • Linux ALSA Library 4.3 Functional Description The IP/Media Phone Reference Application demonstrates how an IP Phone application can be developed using the ADS Framework. The application supports two external lines (endpoints). This means that the phone can handle two calls simultaneously. One local PCM endpoint is also supported via ALSA. Usage scenarios for the application are provided in Section 4.5. 4.3.1 Application Features 4.3.1.1 Codec Support The reference application supports all codecs that are supported by the ADS Framework. A option to select the codec is provided when making a call. See Section 4.4 for more details. 4.3.1.2 Acoustic Echo Cancellation Acoustic Echo Cancellation (AEC) is supported by the reference application. This is needed for handsfree mode. Echo cancellation is enabled by default and can be configured using the set parameter option. 4.3.1.3 Three-Way Calling The application supports three-way calling between the two external lines and the PCM interface. The steps involved in setting up a three-way call are shown in Section 4.5.2. 4.3.1.4 Jitter Buffer Support The oRTP jitter buffer is enabled by default in adaptive mode with a 40ms jitter delay. This value can be changed by modifying the RTP_JB_COMPENSATION define in adsTelRTP.c 4.3.1.5 Caller ID Caller ID is not supported in the IP/Media Phone Reference Application. Intel®Accelerated DSP Software Reference Application User Guide 20 November 2009 Document Number: 323037-001 IP/Media Phone Reference Application 4.3.1.6 Sidetone Sidetone is the effect of sound that is introduced after being picked up by the user’s mouthpiece, either voluntarily or involuntarily, into the earpiece of the same audio device. A low level of sidetone is desirable as it makes the user confident that the phone is working while excessive sidetone is undesirable and detrimental to the user experience. The ADS framework does not internally introduce sidetone into a call. If the PCM-side ADS audio device does not introduce sidetone via hardware then the ADS reference application can be modified to introduce sidetone. This can be done in the context of the PCM inbound or outbound callback functions. The functions can be modified to add an attenuated and possible delayed version of the input signal to the output data path. 4.3.2 Hardware Interface The reference application uses the Linux ALSA library to interface the ADS Framework PCM interface to the underlying hardware. Any audio hardware that is supported by ALSA (for example, USB headsets and HD Audio cards), can be used as the PCM interface. ALSA is configured to use dmix so the underlying sound cards can be used by other applications at the same time. The ALSA device ID must be provided when the phone is taken off-hook. See Section 4.4 for more details. The default ALSA configuration is 16,000-KHz sampling frequency, big endian, 16-bit, signed samples. If this option is not supported by the hardware then the configuration can be changed by modifying adsTelEp.h and recompiling the reference application. 4.3.2.1 ALSA Buffer Underrun Occasionally when a call is set up, the message “INFO: ALSA recovered from underrun on channel x” may appear on the screen. This means that the ALSA thread is not running fast enough to supply ALSA with audio buffers. The cause of this underrun is another process running on the system and using an excessive amount of CPU time. Linux is not a real-time system and CPU-intensive processes can starve the ADS Framework of CPU time. If this is an issue, terminate any unnecessary processes on the system. 4.3.3 RTP Interface The application uses a third-party RTP stack to provide RTP support. oRTP is the only library that is currently supported. For each RTP connection, the RTP port is configured to be bidirectional. The RTP stack uses 6000 as the base port. The RTP port number for an IP Endpoint is the (endpoint number*2) + RTP base port, that is, the RTP port number for IP endpoint 2 = (2*2) + 6000 = 6004. If the RTP base port needs to be changed, it can be done by editing the RTP_BASE_PORT define in adsTelRTP.c and recompiling the reference application. 4.4 Application Menu The top-level application menu consists of the following options. 4.4.1 OFF HOOK This takes the phone off-hook. In the scenario where the phone is idle, this will cause the user to hear a dial tone. The user can then select the make a call option to dial a number. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 21 IP/Media Phone Reference Application 4.4.1.1 Enter the ALSA hardware ID in the form "plughw:x,x": This option allows the user to the select the ALSA device that will be used as the PCM interface. 4.4.2 ON HOOK This option places the phone on-hook. All calls will be disconnected. 4.4.3 MAKE A CALL This option allows the user to make a call. 4.4.3.1 Enter the local line number to use: This option selects the IP line to use for the current call. The options allowed are (0-1). Call setup will fail if the selected line is already in use. The RTP port number for line 0 is 6000 and the RTP port number for line 1 is 6002. 4.4.3.2 Enter the remote line number to use: This option selects the IP line that is being used at the remote end. The RTP port number for line 0 is 6000 and the RTP port number for line 1 is 6002. 4.4.3.3 Enter the IP address of the remote party: This is the IP address of the remote end of the call. 4.4.3.4 Enter the codec to use: This option selects the codec to use for the call. The available options are: Pass Through Mode: 0 - Not supported in the ADS 1.1 Release G711 U Law: 1 G711 A law: 2 G729A: G723: 3 4 - Not supported in the ADS 1.1 Release G722_64: 5 G722_56: 6 G722_48: 7 G726_40: 8 G726_32: 9 G726_24: 10 G726_16: 11 G729_1: 12 - Not supported in the ADS 1.1 Release G722_1: 13 - Not supported in the ADS 1.1 Release Intel®Accelerated DSP Software Reference Application User Guide 22 November 2009 Document Number: 323037-001 IP/Media Phone Reference Application 4.4.3.5 Enter the number of frames per packet: The option selects the number of frames that will be transmitted per packet. This can be used to reduce the network traffic of the call. This value can be between 1 and 10. 4.4.4 SWITCH LINE This option switches the external line. An option is provided to end the current call if it is connected when switching. 4.4.5 3 WAY CALL This option sets up a three way call between the PCM interface and the two external lines. Both calls must be set up for this option to work. 4.4.6 REVERT TO 2 WAY CALL This option causes the call to revert back to a single connection. The connected line is the one that was connected before 3 way calling was enabled. The second line is not disconnected but is placed on hold and options such as switch line and 3 way call can be used again. The application must be in the 3 way call state for this option to work. 4.4.7 SEND DTMF STRING This option allows the transmission of a DTMF string down the connected IP channel. This option would be used when the phone is being used in a hands free scenario. 4.4.7.1 Enter the line direction: 1 play to PCM side - 0 play to IP side This option selects the direction that the tone will played. 4.4.7.2 Enter the number of tones to be played The options selects the number of tones to play. The allowable range is 1-32. 4.4.7.3 Enter the tone id This option allows the tone IDs to be played to be entered. The tones can be DTMF tones, call progress tones or user defined tones. 4.4.8 SET PARAMETER This option is used to set a component parameter. See the Programmers Guide for the parameter table for each component. 4.4.8.1 Enter the pipeline Type(PCM=0, IP=1): This option selects the type of endpoint. 4.4.8.2 Enter the numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: The range of the endpoints available is dependent on the pipeline type. Entering the max value will set the parameter for all endpoints in the range that are configured. A comma-separated list of endpoint numbers can also be selected. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 23 IP/Media Phone Reference Application 4.4.8.3 Enter the pipeline Direction(Inbound=0, Outbound=1): This option selects either the inbound or outbound pipeline of the endpoint. See Figure 2. 4.4.8.4 Enter the component ID(position in pipeline): This option selects the component within the pipeline. The component numbers are zero-based. See Figure 2. 4.4.8.5 Enter the parameter number: The parameter number that is to be set. See the Programmers Guide for the parameter table for each component. 4.4.8.6 Enter the parameter value: The value to set the parameter to. See the Programmers Guide for the parameter table for each component. 4.4.8.7 Set Parameter Example This example will disable the High Pass Filter in the inbound PCM pipeline Note: The phone must have been previously taken off hook Please select test item - 8 Enter the pipeline Type(PCM=0, IP=1):0 Enter the endpoint numbers(0-0) delimited by comma in the format x,y,z OR enter 1 for all channels: 0 Enter the pipeline Direction(Inbound=0, Outbound=1):0 Enter the component ID(position in pipeline):1 Enter the parameter number:1 Enter the parameter value:0 4.4.9 PRINT COMPONENT PARAMETERS This option returns the parameter settings for a component. See the Programmers Guide for the parameter table for each component. 4.4.9.1 Enter the pipeline Type(PCM=0, IP=1): This option selects the PCM type of the endpoint. 4.4.9.2 Enter the endpoint numbers(0-(max-1)) delimited by comma in the format x,y,z OR enter max for all channels: The range of the endpoints available is dependent on the pipeline type. Entering the max value will set the parameter for all endpoints in the range that are configured. A comma-separated list of endpoint numbers can also be selected. Intel®Accelerated DSP Software Reference Application User Guide 24 November 2009 Document Number: 323037-001 IP/Media Phone Reference Application 4.4.9.3 Enter the pipeline Direction(Inbound=0, Outbound=1): This option selects either the inbound or outbound pipeline of the endpoint. See Figure 2. 4.4.9.4 Enter the component ID(position in pipeline): This option selects the component within the pipeline. The component numbers are zero-based. See Figure 2. 4.4.9.5 Get Parameters Example This example will display the parameters for Tone Detector in outbound IP pipeline for line 1. Note: A call must be set up on Line 1. Please select test item - 9 Enter the pipeline Type(PCM=0, IP=1):1 Enter the endpoint numbers(0-1) delimited by comma in the format x,y,z OR enter 2 for all channels: 1 Enter the pipeline Direction(Inbound=0, Outbound=1):1 Enter the component ID (position in pipeline):0 4.4.10 EXIT This option shuts down the application, unconfigures the ADS Framework and releases any resources that are being used by the application. 4.5 Usage Scenarios In the following usage scenarios, the IP Phone must be able to match the configuration of the DUT. A second instance of the ADS IP/Media Phone Reference Application may be used as the IP phone. 4.5.1 Basic Endpoint-to-Endpoint Call Figure 6 shows the setup required to make a basic endpoint-to-endpoint call. Figure 6. Basic Endpoint-to-Endpoint Call Setup Making a call from the DUT to the IP Phone requires the following steps. November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 25 IP/Media Phone Reference Application 1. The OFF HOOK command is entered on the DUT using the reference application. 2. The local line, remote line, and remote IP address are entered using the Make A CALL option. 3. The IP Phone configuration must match that of the DUT. 4. All RTP traffic passes directly between the DUT and the IP Phone. 5. The ON HOOK command is entered on the DUT using the reference application and the call is disconnected. 4.5.1.1 Basic Endpoint-to-Endpoint Call Example 1. Run ./adsTelEpApp nb_audio.wav wb_audio.wav 2. Select 1, for "Off Hook" 3. When prompted with "Enter the ALSA hardware ID in the form "plughw:x,x":", enter the sound card reference such as "plughw:1,0". A dialtone should be audible. 4. Select 3 to "Make A Call" 5. Key in 0 for "Enter the local line number to use:" 6. Key in 0 for "Enter the remote line number to use:" 7. Key in remote ip address for "Enter the IP Address of the remote party" 8. Select G.711 ulaw codec, "Enter the codec to use: 1" 9. Key in 1 for "Enter the number of frames per packet:" 10. Repeat steps for the remote host. 4.5.2 Three-Way Call Figure 7 shows the setup required to make a three-way call. Figure 7. Three-Way Call Setup To setup a three-way call from the DUT to the IP Phones requires the following steps. 1. The OFF HOOK command is entered on the DUT using the reference application. 2. The MAKE A CALL option is used to call IP Phone 1. 3. The IP Phone 1 configuration must match that of the DUT. 4. Use the SWITCH LINE option to switch to the second external line without disconnecting the first call. Intel®Accelerated DSP Software Reference Application User Guide 26 November 2009 Document Number: 323037-001 IP/Media Phone Reference Application 5. Repeat steps 2-3 for IP Phone 2. 6. Select the 3 WAY CALL option from the menu to establish the 3 way call. 7. The ON HOOK command is entered on the DUT using the reference application to end the call. 4.5.2.1 Three-Way Call Example 1. Set up a Endpoint-to-Endpoint call as in Section 4.5.1.1. 2. Select "4 - Switch Line" 3. When prompted to "Terminate current call (1=Yes 0=No):", select "0" for "No". At this point, a dialtone will be heard on the DUT and hold music will be heard on IP Phone 1. 4. Select 3 to "Make A Call" 5. Key in 1 for "Enter the local line number to use:" 6. Key in 1for "Enter the remote line number to use:" 7. Key in remote ip address for "Enter the IP Address of the remote party" 8. Select G.711 ulaw codec, "Enter the codec to use: 1" 9. Key in 1 for "Enter the number of frames per packet:" 10. On a second remote host, set up another call as in CROSS_REF selecting 1 as the remote line number and 1 as the local line number. This is IP Phone 2. At this point there will be an Endpoint-to-Endpoint call between the DUT and IP Phone 2. Hold music will still be heard on IP Phone 1. 11. On the DUT, select "5 - 3 Way Call". At this point, a 3 Way Call should be established between the DUT, IP Phone 1 and IP Phone 2 November 2009 Document Number: 323037-001 Intel®Accelerated DSP Software Reference Application User Guide 27 IP/Media Phone Reference Application Intel®Accelerated DSP Software Reference Application User Guide 28 November 2009 Document Number: 323037-001