Signalogic SigMRF, User Manual

Page 1: ... Users Guide Copyright 2016 2017 Signalogic Inc Revision A2 Apr 2017 Signalogic Inc 9617 Wendell Skillman Dallas TX 75243 Tel 214 349 5551 Fax 972 598 0806 http www signalogic com tech_support signalogic com ...

Page 2: ...ckground 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 3 SigMRF 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 ...

Page 3: ...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 ...

Page 4: ...ia 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 ...

Page 5: ... 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 s...

Page 6: ...rectCore 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 N...

Page 7: ... 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 Back...

Page 8: ...are 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 dev...

Page 9: ...rboard 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 2...

Page 10: ...gth 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 ...

Page 11: ...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 ...

Page 12: ...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 ...

Page 13: ...rmed 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 ...

Page 14: ...load 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 ...

Page 15: ...e 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 DSSession...

Page 16: ...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 vari...

Page 17: ...me 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 ...

Page 18: ... 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 ve...

Page 19: ...nd 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...

Page 20: ...2c_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_13200...

Page 21: ... and or compressed bitstream files in cod format 3 CPU and or coCPU usage should be given in the command line as shown in Table 3 4 below CPU Entry Comments cSIGC66XX N Specifies coCPU processing using one or more c66x PCIe cards see coCPU User Guide for more information N is the number of coCPU cores to reserve default 8 cx86 Specifies x86 processing cSIGX86 Specifies x86 processing with measurem...

Page 22: ...pe NONE term2 local_ip 10 0 1 211 term2 local_port 10246 term2 remote_ip 10 0 1 71 term2 remote_port 10246 term2 media_type voice term2 codec_type G711_ALAW term2 bitrate 64000 term2 ptime 20 term2 rtp_payload_type 8 term2 dtmf_type NONE term2 dtmf_payload_type NONE end_of_session_data Session 3 start_of_session_data term1 local_ip 10 0 1 211 term1 local_port 10240 term1 remote_ip 10 0 1 71 term1 ...

Page 23: ...type G711_ULAW term2 bitrate 64000 term2 ptime 20 term2 rtp_payload_type 0 term2 dtmf_type NONE term2 dtmf_payload_type NONE end_of_session_data Example Codec Config Files Example codec config file entries are shown below Codec 1 start_of_codec_data media_type voice codec_type EVS bitrate 9600 ptime 20 dtx_enable 0 rf_enable 0 sample_rate 32000 in Hz SWB header_full 1 encoder_file reference_files ...

Page 24: ...y user applications to send and receive packets add packets to the jitter buffer pull ordered sequenced packets from the jitter buffer format payloads into packets prior to sending get information about packets in multithreaded asynchronous data flow for example hash a packet s contents and look up its associated session data in order operate on the packet For jitter buffer related APIs packet for...

Page 25: ...ee section 3 5 4 below Session Data and Session Command Structs a uFlags value a combination of operating modes data flow paths and session attributes Pktlib APIs are implicitly called by the SigMRF background process including both packet and media tasks In this case the background tasks handle all packet I O and timing The following Pktlib header file excerpt definitions for APIs attributes and ...

Page 26: ...ec built in jitter buffer if there is one given by the codec spec Notes if no network interface is given DSFormatPackets DSBufferPackets and DSGetOrderedPackets APIs may be used but not DSSendPackets and DSRecvPackets if a coCPU card DPDK cores or specific Linux cores should be used in either frame or packet flow modes then DSAssignDataPlane must be called first to obtain a data plane handle dpHan...

Page 27: ...r more packets to the SigMRF internal jitter buffer Notes should not be used or used very carefully if DSRecvPackets is called with DS_RECV_PKT_ADDTOJITTERBUFFER if the session handle is NULL then packets are matched to an existing session using IP and UDP info hashing techniques DSGetOrderedPackets get one or more packets from the SigMRF internal jitter buffer Notes if the session handle is NULL ...

Page 28: ...ch all mem allocation occurs at codec creation time and none at run time other than local stack inside functions The following Voplib header file excerpt gives definitions for APIs attributes and flags along with descriptive comments Header root Signalogic DirectCore include voplib h Description API for creating and managing audio transcoding sessions Project DirectCore Copyright Signalogic Inc 20...

Page 29: ...uint32_t in_frameSize uint8_t outData int DSCodecTranscode HCODEC hCodecSrc HCODEC hCodecDst unsigned int uFlags uint8_t inData uint32_t in_frameSize uint8_t outData uint32_t out_frameSize CODEC_INSTANCE accessory functions int DSGetCodecBitRate HCODEC hCodec int DSGetCodecRawFrameSize HCODEC hCodec XDAIS wrapper functions typedef IALG_Handle ALG_Handle ALG_Handle ALG_create IALG_Fxns fxns IALG_Ha...

Page 30: ...dware DirectCore can be used stand alone The DirectCore reference guide is located at ftp ftp signalogic com documentation DirectCore DirectCore_Reference_Guide_v3_1_0 pdf 3 5 4 Session Data and Session Command Structs Key to the DSSessionCreate API are the SESSION_DATA TERMINATION_INFO and voice and video attributes structs which are shown in the session h and session_cmd h header file excerpts b...

Page 31: ... 3 DS_VOICE_CODEC_TYPE_G711_WB_ALAW 4 DS_VOICE_CODEC_TYPE_G726 5 DS_VOICE_CODEC_TYPE_G729AB 6 DS_VOICE_CODEC_TYPE_G723 7 DS_VOICE_CODEC_TYPE_AMR_NB 8 DS_VOICE_CODEC_TYPE_AMR_WB 9 DS_VOICE_CODEC_TYPE_EVRC 10 DS_VOICE_CODEC_TYPE_ILBC 11 DS_VOICE_CODEC_TYPE_ISAC 12 DS_VOICE_CODEC_TYPE_OPUS 13 DS_VOICE_CODEC_TYPE_EVRCB 14 DS_VOICE_CODEC_TYPE_GSMFR 15 DS_VOICE_CODEC_TYPE_GSMHR 16 DS_VOICE_CODEC_TYPE_GS...

Page 32: ...e DS_EVRC_PACKET_FORMAT 0x0000000C 0 Interleave bundled 1 header free 2 compact bundled DS_EVRC_BITRATE 0x00000070 values from 0 7 DS_EVRC_MODE 0x00000700 values from 0 7 DS_EVRC_MAX_INTERLEAVE 0x00007000 values from 0 7 DS_EVRC_DTMF 0x00010000 values from 0 1 DS_EVRC_TTY_MODE 0x00060000 values from 0 3 or 0 1 DS_EVRC_NOISE_SUPP 0x00080000 values from 0 1 DS_EVRC_POST_FILTER 0x00100000 values from...

Page 33: ...EVS_CH_AW_RECV_SEVEN 7 enum evs_bit_rate DS_EVS_BITRATE_5_9_SC_VBR 0 DS_EVS_BITRATE_7_2 1 DS_EVS_BITRATE_8_0 2 DS_EVS_BITRATE_9_6 3 DS_EVS_BITRATE_13_2 4 DS_EVS_BITRATE_13_2_CA 5 DS_EVS_BITRATE_16_4 6 DS_EVS_BITRATE_24_4 7 DS_EVS_BITRATE_32 8 DS_EVS_BITRATE_48 9 DS_EVS_BITRATE_64 10 DS_EVS_BITRATE_96 11 DS_EVS_BITRATE_128 12 EVS codec flags silencesupp is set using VOICE_ATTR_FLAG_VAD enum evs_cod...

Page 34: ...0 endif ATCA blade system EVS mods struct voice_attributes ifdef __BIG_ENDIAN__ uint32_t flag 8 see VOICE_ATTR_FLAG_VAD and VOICE_ATTR_FLAG_CNG uint32_t noise_reduction 8 noise reduction 0 none 1 5 type uint32_t ec 8 see ec_type enum uint32_t ec_tail_len 8 tail length 0 not used otherwise specified in msec else uint32_t ec_tail_len 8 tail length 0 not used otherwise specified in msec uint32_t ec 8...

Page 35: ...ods 20 ms frame b w adaptive mode SID updates 8 50 default 25 uint32_t fixed_sid_update_interval 16 frame periods 20 ms frame b w fixed mode SID updates 3 100 default 8 endif evs else struct uint32_t codec_flags See evs_codec_flags evs endif ATCA blade system EVS mods u struct video_attributes ifdef __BIG_ENDIAN__ uint32_t yres 16 y resolution in pixels uint32_t xres 16 x resolution in pixels uint...

Page 36: ...onfigurable per realm uint16_t payload_framesize bits uint32_t codec_type 8 if media_type is VOICE use voice_codec_type enum else use video_codec_type enum uint32_t media_type 8 see enum media_type definition else uint32_t media_type 8 see enum media_type definition uint32_t codec_type 8 if media_type is VOICE use voice_codec_type enum else use video_codec_type enum uint16_t payload_framesize bits...

Page 37: ...ssrc uint32_t seq_num uint32_t timestamp HOST_REP_TERM_INFO typedef struct uint32_t session_id HOST_REP_TERM_INFO term1 HOST_REP_TERM_INFO term2 HOST_REP_SESSION_DATA endif _SESSION_H_ session_cmd h Header File session_cmd h Session commands and APIs for c66x x86 or combined platforms Copyright C Signalogic Inc 2008 2012 Created for c64x voice platforms Copyright C Mavenir Systems and Signalogic I...

Page 38: ...ON_NOTIFICATION C66x CP for active DS_CMD_CONFIGURE_IP CP C66x DS_CMD_CONFIGURE_IP_ACK C66x CP DS_CMD_LOG_QUERY CP C66x DS_CMD_LOG_RSP C66x CP DS_CMD_GO_ACTIVE CP C66x DS_CMD_GO_ACTIVE_ACK C66x CP DS_CMD_TIME_SYNC CP C66x DS_CMD_TIME_SYNC_ACK C66x CP DS_CMD_MAX enum ack_type DS_ACK_NONE DS_ACK_OK DS_ACK_UNRECOGNIZED_CMD DS_ACK_UNRECOGNIZED_ID DS_ACK_CMD_INTEGRITY_ERR DS_ACK_SESSION_FULL DS_ACK_CHA...

Page 39: ..._term struct cmd_del_session uint32_t session_id ha_index 0 ACTIVE or 1 1 case X 1 N Standby for Active X uint32_t ha_index struct cmd_configuration_ack uint32_t cause_code see ack_type enums above struct cmd_create_session_ack uint32_t cause_code see ack_type enums above struct cmd_modify_session_ack uint32_t cause_code see ack_type enums above struct cmd_del_session_ack uint32_t cause_code see a...

Page 40: ...nchip_heap_avg 16 uint32_t extern_heap_peak 16 uint32_t extern_heap_avg 16 uint32_t extern_heapBuf_peak 16 uint32_t extern_heapBuf_avg 16 endif uint64_t rx_pkts uint64_t tx_pkts uint64_t drop_pkts uint64_t rx_octs uint64_t tx_octs struct cmd_channel_stats_req struct ip_addr remote_ip struct ip_addr local_ip ifdef __BIG_ENDIAN__ uint32_t local_port 16 uint32_t remote_port 16 else uint32_t remote_po...

Page 41: ...d uint32_t priv user application transparent info struct cmd_session_timeout_notification uint32_t session_id uint32_t priv user application transparent info struct cmd_ha_state uint32_t state see ha_state struct cmd_ha_state_ack uint32_t cause_code see ack_type enums above struct cmd_replication uint32_t buffer_index either 0 or 1 struct cmd_replication_notification uint32_t buffer_index struct c...

Page 42: ...ndex struct cmd_go_active_ack uint32_t cause_code struct cmd_NTP_time_sync unsigned long long NTP uint32_t seconds seconds since epoch uint32_t second_fraction seconds fractional value uint64_t TSC TSC value read by user app as close as possible to NTP timestamp time struct cmd_NTP_time_sync_ack uint32_t cause_code ifdef __cplusplus endif endif _SESSION_CMD_H ...