Signalogic SigMRF User manual

SigMRF Users Guide
Copyright 

2016-2017 Signalogic, Inc.
Revision A2, Apr 2017
Signalogic, Inc.
9617 Wendell @ Skillman
Dallas, TX 75243
Tel: [phone]
Fax: [phone]
http://www.signalogic.com
tech_supp[email protected]

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
ii
TABLE OF CONTENTS
1Overview 1
2SigMRF Architecture 2
2.1 Software Architecture ................................................................................................. 2
2.1.1 Libraries.................................................................................................................. 3
2.1.2 Background Process............................................................................................... 3
2.2 Platform Architecture .................................................................................................. 4
2.2.1 Packet I/O............................................................................................................... 4
2.2.2 DPDK ..................................................................................................................... 4
2.2.3 coCPU™ Option ..................................................................................................... 5
3SigMRF Functionality 9
3.1 Packet Flow................................................................................................................ 9
3.2 Frame Flow ...............................................................................................................13
3.3 Codecs ......................................................................................................................14
3.3.1 Voice Codecs.........................................................................................................14
3.3.2 Video Codecs ........................................................................................................15
3.4 mediaTest Demo, Test, and Measurement Program..................................................16
3.5 APIs...........................................................................................................................21
3.5.1 Pktlib......................................................................................................................21
3.5.2 Voplib ....................................................................................................................25
3.5.3 DirectCore™..........................................................................................................26
3.5.4 Session Data and Session Command Structs........................................................27

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
iii
Revision History
Created Rev A1 Nov 2016 SigMRF Users Guide
Modified Rev A2 Apr 2017 Add pseudocode example for packet and frame
processing

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
1 / 39
1 Overview
SigMRF (Signalogic Media Resource Functions) software provides voice and video transcoding,
transrating, algorithms, packet processing, statistics, logging, resource management, redundancy,
and other media related functionality for the following application areas:
•Telecom infrastructure such as IMS LTE and VoLTE test and simulation equipment
•IT security
•Lawful interception and recording
•Session Border Controllers (SBCs)
•Media Gateways, including extreme capacity systems
•Augmented Reality (AR) systems that require real-time, bidirectional video data flow and
processing
•Data analytics and data streaming applications that require voice and video interfaces
•Content delivery
SigMRF is designed to scale from low capacity, relatively simple systems to high capacity,
complex systems. When high capacity is required, SigMRF supports coCPU™ hardware that
can increase, by a factor of 10x or more, the capacity of cloud servers, as well as small form
factor systems (such as mini-ITX), in which size and power consumption constraints can
severely limit the number of x86 cores. The coCPU hardware option also supports ATCA blade
server systems.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
2 / 39
2 SigMRF Architecture
SigMRF software and hardware consists of:
•Libraries (Linux and Windows)
•Background Process (for example, media and packet tasks)
•Test and demo applications (for example, mediaTest)
•Optional coCPU™ hardware
The SigMRF architecture is designed for both flexibility and high performance, supporting
multiple data flow and packet I/O options, DPDK, and entry points for user defined applications.
User apps can operate and make API calls at several levels, including frame, packet, and session.
2.1 Software Architecture
The SigMRF software architecture includes both libraries and background tasks. Figure 1-1
below shows the SigMRF software architecture.
Figure 1-1, SigMRF software architecture and packet I/O

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
3 / 39
All SigMRF software components are dependent on the DirectCore library for thread-safe access
to information about multiple instances, multiple users, and CPU core allocation in cases when
explicitly specified. In addition, DirectCore provides an interface layer between software and
hardware elements, for example between software and DPDK, software and coCPU™ cores, and
software and coCPU NICs.
2.1.1 Libraries
SigMRF provides several libraries, both in Linux (.so 1) and Windows (DLL 2) formats,
including:
•Pktlib (packet library)
•Voplib (media, or voice / video over packet, library)
•Codec libraries (various voice and video codecs)
Codec libraries are accessed by user applications via Voplib; currently direct access to codec
libraries is not supported.
SigMRF also requires the DirectCore set of libraries. DirectCore is a separate product, used by a
number of Signalogic application areas, including telecom, image analytics, AI (neural
networks), and more. The DirectCore reference guide is located at
ftp://ftp.signalogic.com/documentation/DirectCore/DirectCore_Reference_Guide_v3_1_0.pdf.
For Windows, SigMRF shall support only Win10 and above. Some aspects of SigMRF, such as
the mediaTest program, used for application reference, demo and test purposes, are expected to
require WSL (Windows Subsystem for Linux), which is available only in Win10.
Testing and Development Notes
1Pktlib and Voplib Linux shared objects have been tested with Ubuntu v12.04 thru 16.04 (kernel
v3.2.0- 45 thru v4.4) and CentOS 7, 7.1 and v6.2. In general, Signalogic software for Linux
systems has been tested on tested with Red Hat 9 (Enterprise) 2.6.9- 42 kernel, Ubuntu v12.04
thru 16.04 (kernel v3.2.0- 45 thru v4.4) CentOS 7, 7.1 and v6.2, and Gentoo v2.6.255.
2Resources and priority assigned to development of Win10 Pktlib and Voplib DLLs depends on
customer needs and business case. Development mostly involves porting existing and tested
Linux .so libs to Win10.
2.1.2 Background Process
The SigMRF background process, when needed, runs separately from user applications, and
includes:
•Packet task, which runs at a relatively high rate (typically every 1 msec) and handles
packet I/O, adding packets to the jitter buffer

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
4 / 39
•Media task, which runs at a lower rate (typically every 5 msec) and handles packet and
payload processing, including transcoding, ptime and transrating, DTMF, and more
Typically, the SigMRF background process comes into play when there is a need for higher
performance or user application code must be simplified. Although not all situations require the
SigMRF background process to be running, it cannot be separated from SigMRF from a product
ordering or support standpoint.
2.2 Platform Architecture
SigMRF supports the following platforms:
•Off-the-shelf rack servers. Typical examples include 1U and 2U form-factors with 8 to
24 Xeon x86 cores
•ATCA server blades. Typical examples include ATCA blades with 4 to 16 x86 or
PowerPC cores
•Small form-factor servers. Typical examples include mini-ITX enclosures with 2-4 Atom
x86 cores
2.2.1 Packet I/O
SigMRF supports several platform configurations for packet I/O, including:
•Motherboard embedded NICs
•Add-in PCIe card NICs
•Add-in coCPU PCIe card NICs
•Backplane Ethernet interface (ATCA only)
In addition, SigMRF supports packet flow paths between these NIC options including:
•Standard Linux and Windows sockets
•DPDK “fast path” between add-in cards and user applications (Linux only)
2.2.2 DPDK
SigMRF support for DPDK is currently under background development and not documented
here. It’s worthwhile to note that existing SigMRF customers have implemented DPDK with
coCPU PCIe cards for very high performance server applications.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
5 / 39
2.2.3 coCPU™ Option
SigMRF supports coCPU hardware options to (i) substantially increase platform transcoding
capacity, (ii) enable transcoding in very small-form factors, and (iii) provide reduced packet
latency if needed for certain applications (using NICs located directly on the coCPU hardware,
as shown in Figure 2-1 below).
As one example, 64 to 256 coCPU cores can be added to a 1U server; as another example, a 14-
slot ATCA rack can host 1920 coCPU cores. These high levels of core density are suitable to
address applications constrained in space and power consumption.
From a software architecture perspective, in the diagram in Figure 1-1 above, which uses a
partial 3D representation, DirectCore forms a “dividing layer” between x86 CPUs in front of the
layer and coCPUs behind the layer. If coCPU hardware is in use, the SigMRF background
process, as well as packet and media libraries, exist on both sides of this layer.
The coCPU Users Guide is located at
ftp://ftp.signalogic.com/documentation/Hardware/SigC667x/SigC667x_UserGuide_RevD2.pdf.
coCPU Hardware Options
coCPU hardware options include:
•32-core and 64-core PCIe cards
•160 core ATCA blades
coCPU hardware uses Texas Instruments CPUs (8-core c66x devices) which provide the
following benefits:
•State-of-the-art CPU architecture, including multicore, L2 cache, DDR3 external mem,
onchip PCIe and network I/O, onchip wire-speed packet processor including UDP port
filtering, high clock rate SIMD instruction architecture, and extensive onchip DMA
•Run standard C/C++ software without undue modifications, including open source
packages of various types
•Build tools generate highly optimized, efficient run-time codes, especially for
calculation-intensive applications such as codecs, analytics, neural net convolutions, etc.
Figures 2-1 through 2-4 below show examples of coCPU hardware installed in various off-the-
shelf server platforms.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
6 / 39
Figure 2-1, coCPU full-length PCIe card installed in a Supermicro 1U server.
Note the dual slot PCIe risers on either side of the motherboard
Figure 2-1 above shows a coCPU full-length PCIe card installed in a low-cost Supermicro 1U
server with dual slot PCIe risers on either side of the motherboard. This configuration allows up
to 256 coCPU cores to be added to a single 1U server.
Figure 2-2 below shows dual full-length PCIe cards with 128 total coCPU cores, 32 GB DDR3
mem, and 4x GbE interfaces installed in HP DL380 and Dell R720 2U servers.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
7 / 39
Figure 2-2, coCPU full-length PCIe cards installed in HP DL380 and Dell R720
2U servers
Figure 2-3 below shows a half-length PCIe card with 32 coCPU cores, 8 GB DDR3 mem, and
GbE interface installed in a mini-ITX server on a standard PCIe riser. The mini-ITX
motherboard has a quad-core Atom CPU, 8 GB memory, and 4x GbE interfaces.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
8 / 39
Figure 2-3, coCPU half-length PCIe card installed in a mini-ITX server with
enclosure dimensions approx 8” x 9” x 3”. Note 100 W power supply at left side
of the enclosure
The following links have more information on coCPU hardware and software support:
coCPU HPC Server TI Wiki
Small AI Servers TI Wiki

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
9 / 39
3 SigMRF Functionality
SigMRF software functionality is described in sections below covering data flow, codecs, test
programs, and API definitions. Some general notes apply:
•where applicable to mobile and telecom systems, SigMRF software follows 3GPP
protocols and standard for media codecs, NFV and C-RAN acceleration, and other areas
•all test and demo programs (i) are multithreaded, (ii) support concurrent multiuser
operation, (iii) support KVM + QEMU virtualization, and (iv) support Ubuntu and
CentOS systems
3.1 Packet Flow
The SigMRF software architecture supports the following packet flow options:
•User applications receive and sent packets, which are given in Pktlib APIs
•User applications receive and send packets, which are given to the DSSessionTranscode()
Pktlib API
•The SigMRF background process invokes Pktlib APIs. The background process takes
care of all timing and also calls Voplib APIs
In all cases above, user applications invoke the DSCreateSession() API to specify transcoding
and voice algorithm processing details, including jitter buffer, ptime, sampling rate conversion,
variable bitrate, DTX and CNG, DTMF, and echo can.. In the first two cases, user applications
are responsible for packet I/O and timing. Depending on which Pktlib APIs are called, user
applications may also be responsible for some degree of packet parsing and formatting, ranging
from all to none.
Figure 3-1 below shows packet and frame data flow in cases where user applications are
handling packet I/O and timing, packet parsing and formatting, and not using the SigMRF
background process.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
10 / 39
Figure 3-1, User application packet and frame data flow
Below is a pseudocode representation of the processing performed by a user application
corresponding to Figure 3-1 above.
/* setup code */
#if NONBLOCKING
fcntl(recv_sock_fd, F_SETFL, O_NONBLOCK);
#endif
hDataPlane = DSAssignDataPlane(NULL, “x86”, 0, 0, 0, 0, 0);
/* create as many sessions as needed */
[ fill in voice or video attributes and terminfo structs ]
[ fill in session data struct ]
DSSessionCreate(hDataPlane, “none”, pSessionData, uFlags)
/* Rx packet processing, performed every 1 msec */

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
11 / 39
len = recvfrom(rxpkt)
#if NONBLOCKING
if (len <= 0) continue;
#endif
[ parse packet and get length from packet headers ]
DSBufferPackets(rxpkt) /* add packet to jitter buffer */
/* media processing and Tx packet handling, performed every 5 msec */
DSGetOrderedPackets(pkt)
hCodec = DSGetPktInfo(pkt, DS_GETPKTINFO_TERM, pTermInfo)
hSession = DSGetPktInfo(pkt, DS_GETPKTINFO_SESSION, pSessionInfo)
[ extract RTP payload ]
DSCodecDecode(hCodec, payload)
[ perform voice processing as needed ]
DSCodecEncode(hCodec, payload)
DSFormatPacket(hSession, pTermInfo, payload, txpkt)
sendto(txpkt)
Following are some notes about the above pseudocode:
1. Text marked with [] indicate user defined code.
2. Assumes Linux.
3. The code is divided into three (3) main sections:
• Setup
• Rx packet processing (every 1 msec in the example)
• Tx packet processing (every 5 msec in the example)
The second two sections would typically run in different threads.
4. The setup section creates a data plane handle and as many sessions as needed. In the
example, the data plane handle is created with default parameters (x86 CPUs, no specific
core allocation, no clock rate override, etc). Session handles can be stored if needed but
cannot be used during multithreaded, asynchronous Rx and Tx packet processing. Instead,

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
12 / 39
DSGetPktInfo() must be used to retrieve session handles corresponding to (i) received
packets and (ii) packets pulled from the jitter buffer prior to voice processing and sending.
The above pseudocode example leaves out many details. For specific, working examples refer to
mediaTest source code (see section 3.4 below, mediaTest Demo, Test, and Measurement
Program).
Figure 3-2 below shows packet and frame data flow handled by the DSSessionTranscode() API,
in cases where user applications are handling packet I/O and timing, but not packet parsing and
formatting, and not using the SigMRF background process.
Note that DSSessionTranscode() can also perform packet I/O if a network interface was
specified by the session handle in use (session handles are created by the DSSessionCreate()
API).
Figure 3-2, User application transcoding packet data flow using
DSSessionTranscode()
Figure 3-3 below shows packet I/O, timing, packet parsing and formatting, and packet and frame
data flow handled by the SigMRF background process.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
13 / 39
Figure 3-3, Background process transcoding packet and frame data flow
SigMRF background process timing (i.e. rate at which packet and media tasks run) can be
configured by Pktlib APIs. The background process runs independently of any user applications.
3.2 Frame Flow
In situations where user applications perform all aspects of packet I/O and timing, packet parsing
and formatting, and payload extraction, frames without RTP or other packet headers may be
given to Voplib APIs. In this case, the user application is responsible for all aspects of packet
flow and processing, including jitter buffer, ptime, sampling rate conversion, aspects of variable
bitrate if applicable, CNG and DTX, and DTMF detection and generation.
Figure 3-4 below shows frame data flow.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
14 / 39
Figure 3-4, Frame data flow
Note that in the case of frame data flow, frame means “compressed bitstream” in a particular
codec format for frames being decoded, and “raw audio” (typically in 16-bit PCM format) for
frames being encoded.
3.3 Codecs
SigMRF software includes several voice and video codecs, listed in the following sections.
3.3.1 Voice Codecs
SigMRF software includes a number of voice codecs, listed in Table 3-1 below.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
15 / 39
Codec CPU Support 1More Information / Comments 2
EVS x86, c66x The x86 version of the EVS codec is based on 3GPP 26.443 source
code (floating-point), and coCPU (c66x) is based on 3GPP 26.442,
source code (fixed point)
Compliance with 3GPP TS 26.445 is given in the HPC EVS Codec
Datasheet, located at:
ftp://ftp.signalogic.com/data_sheets/Software/EVS_Codec_Datasheet_
RevA.pdf
The c66x version of EVS is called the HPC EVS codec. More
Information is available on the HPC EVS codec web page and the
NFV Transcoding TI Wiki:
http://signalogic.com/evs_codec.html
http://processors.wiki.ti.com/index.php/NFV_Transcoding
G711u,
G711A
x86, c66x http://processors.wiki.ti.com/index.php/NFV_Transcoding
c66x version includes Appendix I and II
AMR-WB
AMR-NB
Opus
c66x
x86 version planned
http://processors.wiki.ti.com/index.php/NFV_Transcoding
http://processors.wiki.ti.com/index.php/NFV_Transcoding
EVRC
EVRC-B
iLBC
G726
G729
c66x x86 version not planned
http://processors.wiki.ti.com/index.php/NFV_Transcoding
Table 3-1, SigMRF voice codecs
Notes
1CPU support is updated continuously; current status available upon request.
2The links provided contain information about capacity, codec version, CPU and memory usage,
and more.
3.3.2 Video Codecs
SigMRF software includes a number of video codecs, listed in Table 3-2 below.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
16 / 39
Codec CPU Support 1More Information / Comments 2
H.264 c66x http://processors.wiki.ti.com/index.php/NFV_Transcoding
http://www.signalogic.com/index.pl?page=dpdk_media_solution
Network I/O streaming input and YUV file input supported
H.265 c66x c66x beta version available; more information available upon request
VP9 c66x c66x version planned
Table 3-2, SigMRF video codecs
Notes
1CPU support is updated continuously; current status available upon request.
2The links provided contain information about capacity, codec version, CPU and memory usage,
and more.
3.4 mediaTest Demo, Test, and Measurement Program
mediaTest is a Linux command line program that allows demo, test, and measurement for:
•Transcoding
•Network media packet processing
•Codec performance and audio quality
A secondary, but very important, purpose of mediaTest is to provide user application C/C++
source code examples, including Pktlib and Voplib APIs, and coCPU interface. In addition to
API usage, mediaTest source code may be used as a general reference for building user
applications, including packet flow, timing, multithreading, and other areas.
The mediaTest command line supports the following operating mode options:
•Codec testing , including encode only, decode only, encode-decode, media waveform file
formats including .wav, .tim, .cod, and configuration files specifying codec parameters
•Session testing, including multiple concurrent sessions and session configuration files
specifying remote / local IP and UDP info, codec type and flags, ptime, sampling rate,
bitrate, VAD/DTX, and more
•SigMRF testing
•coCPU hardware configuration – core lists, clock rate, NIC ports, etc
To support transcoding, codec and session configuration files use an numerical endpoint syntax,
and session configuration files use a “term info” (termination) syntax.

4/17/17 SigMRF Users Guide, Rev A2 Copyright Signalogic, Inc. 2016-2017
17 / 39
For codec and session testing, concurrent mediaTest instances in multiple user windows and/or
multiple VMs are supported.
Example mediaTest Command Lines
Example mediaTest command lines are shown below.
x86 Motherboard Network I/O and Packet Processing
./mediaTest -cx86 -M0 -Csession_config/frame_test_script_config
x86 Motherboard Network I/O and coCPU Packet Processing
./mediaTest -f1000 -m0xff -cSIGC66XX-8 -e C66xx_RTAF_SYSBIOS_CCSv54.out -M0 -C
session_config/test_config
x86 Codec Testing (Back-to-Back Encode-Decode)
./mediaTest -cx86 -i reference_files/stv8c.INP -o test_script_files/stv8c_5900_8kHz_dtx_sig.COD -
C session_config/codec_test_8kHz_5900bps_config
./mediaTest -cx86 -ireference_files/stv16c.INP -otest_script_files/stv16c_9600_16kHz_sig.COD -
Csession_config/codec_test_16kHz_9600bps_config
./mediaTest -cx86 -ireference_files/stv32c.INP -otest_script_files/stv32c_13200_32kHz_sig.COD -
Csession_config/codec_test_32kHz_13200bps_config
./mediaTest -cx86 -ireference_files/stv16c_7200_16kHz_mime_$SUFFIX.COD -
otest_script_files/stv16c_7200_16kHz_sig_decoded.OUT -
Csession_config/codec_test_16kHz_7200bps_config
./mediaTest -cx86 -ireference_files/stv16c_13200_16kHz_mime_$SUFFIX.COD -
otest_script_files/stv16c_13200_16kHz_sig_decoded.OUT -
Csession_config/codec_test_16kHz_13200bps_config
x86 Codec Testing with Measurement and Logging
./mediaTest -cSIGX86 -itest_files/stv16c.INP -otest_files/c6x16c_j.wav -
Csession_config/codec_test_16kHz_13200bps_config
coCPU Codec Testing with Measurement and Logging
./mediaTest -f1000 -m0xff -cSIGC66XX-8 -etest.out -itest_files/stv8c.INP -otest_files/c6x8c_j.wav
-Csession_config/codec_test_8kHz_13200bps_config
./mediaTest -f1000 -m0xff -cSIGC66XX-8 -etest.out -itest_files/stv16c.INP -
otest_files/c6x16c_j.wav
mediaTest Command Line Entry Notes
1) Operating modes may be given in the command line as shown in Table 3-3 below:
Operating
Mode Entry
Comments
-M0 Use host network interface (e.g. motherboard network I/O). Packets are processed using
x86 or coCPUs, depending on -c cmd line entry