Transcript
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology Programmer’s Guide May 2009
Order Number: 320415-003US
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. Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. Legal Lines and Disclaimers
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. This document contains information on products in the design phase of development. 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. Code Names are only for use by Intel to identify products, platforms, programs, services, etc. (“products”) in development by Intel that have not been made commercially available to the public, i.e., announced, launched or shipped. They are never to be used as “commercial” names for products. Also, they are not intended to function as trademarks. BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap ahead. logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, Itanium, Itanium Inside, MCS, MMX, Oplus, OverDrive, PDCharm, Pentium, Pentium Inside, skoool, Sound Mark, The Journey 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® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 2
May 2009 Order Number: 320415-003US
Contents—IP Telephony Software
Contents 1.0
Introduction ............................................................................................................ 13 1.1 About this Document ......................................................................................... 13 1.2 Related Documents ........................................................................................... 14 1.3 Glossary .......................................................................................................... 14 1.4 Feature List ...................................................................................................... 16 1.4.1 HSS Ports.............................................................................................. 16 1.4.2 Channels............................................................................................... 16 1.4.3 Channel Bypass ..................................................................................... 16 1.4.4 Serial Protocols ...................................................................................... 17 1.4.5 Drivers ................................................................................................. 17
Part 1: Architectural Overview ......................................................19 2.0
Silicon Overview ...................................................................................................... 21 2.1 What’s New in this Chapter................................................................................. 21 2.2 High Level Overview .......................................................................................... 21
3.0
TDM 3.1 3.2 3.3 3.4 3.5 3.6 3.7
4.0
TDM 4.1 4.2 4.3 4.4 4.5 4.6
5.0
HSS Voice Driver Details .......................................................................................... 31 5.1 What’s New in this Chapter................................................................................. 31 5.2 Overview ......................................................................................................... 31 5.3 Functional Description........................................................................................ 31 5.4 Dependencies ................................................................................................... 31 5.5 Memory Buffer Management ............................................................................... 32 5.5.1 Tx Memory Management ......................................................................... 32 5.5.2 Rx Memory Management ......................................................................... 33 5.6 Blocking / Non-Blocking Mode ............................................................................. 35
Software Overview .......................................................................................... 23 What’s New in this Chapter................................................................................. 23 Interrupt Operation ........................................................................................... 23 OS System Support ........................................................................................... 23 Development Tools Information........................................................................... 23 API Documentation............................................................................................ 23 Required Hardware............................................................................................ 23 TDM Overview .................................................................................................. 24
Setup Driver Details......................................................................................... 25 What’s New in this Chapter................................................................................. 25 Functional Description........................................................................................ 25 Dependencies ................................................................................................... 25 Multiple Clients ................................................................................................. 26 Blocking / Non-Blocking Mode ............................................................................. 27 Control Path ..................................................................................................... 27 4.6.1 Command Line Parameters ...................................................................... 27 4.6.2 Open .................................................................................................... 27 4.6.3 Release................................................................................................. 27 4.6.4 Ioctl ..................................................................................................... 28 4.6.5 Write .................................................................................................... 28 4.6.6 Read .................................................................................................... 29 4.7 Data Path......................................................................................................... 29 4.8 Mezzanine Slot Reservation ................................................................................ 29 4.9 Resource Usage ................................................................................................ 29 4.10 Operating System-Specific Issues ........................................................................ 29
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 3
IP Telephony Software—Contents
5.7 5.8 5.9 5.10
5.11
5.12 5.13
Multiple Clients..................................................................................................35 Channel Numbers ..............................................................................................35 Channel Bypass .................................................................................................36 Control Path......................................................................................................36 5.10.1 Open.....................................................................................................36 5.10.2 Release .................................................................................................36 5.10.3 Ioctl......................................................................................................36 Data Path .........................................................................................................38 5.11.1 Packet Formats ......................................................................................38 5.11.2 Poll .......................................................................................................39 5.11.3 Tx ........................................................................................................39 5.11.4 Rx ........................................................................................................39 5.11.5 Single Vs. Multiple Channels per File Descriptor ..........................................40 5.11.6 Overload ...............................................................................................41 Resource Usage.................................................................................................41 Operating System-Specific Issues ........................................................................42
6.0
HSS Data Driver Details ...........................................................................................43 6.1 What’s New in this Chapter .................................................................................43 6.2 Overview ..........................................................................................................43 6.3 Overview of Linux PPP Subsystem ........................................................................43 6.4 Functional Description ........................................................................................45 6.5 HSS Data Driver and Related PPP Components ......................................................45 6.6 Dependencies....................................................................................................46 6.7 Memory Buffer Management................................................................................46 6.7.1 Tx Memory Management..........................................................................47 6.7.2 Rx Memory Management .........................................................................47 6.8 Callback / Polled Mode........................................................................................49 6.9 Multiple Clients..................................................................................................49 6.10 Channel Numbers ..............................................................................................49 6.11 Robbed Bit........................................................................................................49 6.12 Control Path......................................................................................................49 6.12.1 Client Initialization ..................................................................................49 6.12.2 Open.....................................................................................................50 6.12.3 Close ....................................................................................................50 6.12.4 Ioctl......................................................................................................50 6.13 Data Path .........................................................................................................51 6.13.1 Packet Format ........................................................................................51 6.13.2 Tx ........................................................................................................52 6.13.3 Rx ........................................................................................................52 6.13.4 Overload ...............................................................................................52 6.13.5 Enabling and Disabling PPP ......................................................................53 6.13.6 PPP Service Termination ..........................................................................53 6.14 Resource Usage.................................................................................................53 6.15 Operating System-Specific Issues ........................................................................54
7.0
Analog FXO/FXS Driver Details ................................................................................55 7.1 What’s New in this Chapter .................................................................................55 7.2 Overview ..........................................................................................................55 7.3 Functional Description ........................................................................................56 7.4 Dependencies....................................................................................................57 7.5 Memory Buffer Management................................................................................57 7.6 Multiple Clients..................................................................................................58 7.7 Blocking / Non-Blocking Mode .............................................................................58 7.8 Control Path......................................................................................................58 7.8.1 Open.....................................................................................................58
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 4
May 2009 Order Number: 320415-003US
Contents—IP Telephony Software
7.9 7.10 7.11
7.8.2 Release................................................................................................. 58 7.8.3 Ioctl ..................................................................................................... 59 7.8.4 Write .................................................................................................... 61 7.8.5 Read .................................................................................................... 61 7.8.6 Events .................................................................................................. 63 Data Path......................................................................................................... 64 Resource Usage ................................................................................................ 64 7.10.1 Memory Requirements for Event Queue Buffer Pool..................................... 64 Operating System-Specific Issues ........................................................................ 64
8.0
Framer Driver Details ............................................................................................. 65 8.1 What’s New in this Chapter................................................................................. 65 8.2 Overview ......................................................................................................... 65 8.3 Functional Description........................................................................................ 66 8.4 Dependencies ................................................................................................... 66 8.5 Memory Buffer Management ............................................................................... 67 8.6 Multiple Clients ................................................................................................. 67 8.7 Blocking / Non-Blocking Mode ............................................................................. 68 8.8 Control Path ..................................................................................................... 68 8.8.1 Initialization .......................................................................................... 68 8.8.2 Uninitialization ....................................................................................... 68 8.8.3 Configuration......................................................................................... 68 8.8.4 Reset.................................................................................................... 70 8.8.5 Loopback .............................................................................................. 70 8.8.6 Line State ............................................................................................. 71 8.8.7 Register Access...................................................................................... 71 8.8.8 Line Signaling ........................................................................................ 71 8.8.9 Notifications .......................................................................................... 71 8.8.10 Read .................................................................................................... 71 8.8.11 Events .................................................................................................. 73 8.9 Data Path......................................................................................................... 74 8.10 Resource Usage ................................................................................................ 74 8.11 Operating System-Specific Issues ........................................................................ 74
9.0
SRTP 9.1 9.2 9.3 9.4 9.5 9.6 9.7 9.8
Acceleration Overview .................................................................................... 75 What’s New in this Chapter................................................................................. 75 SRTP Sessions, Streams, and Packets .................................................................. 75 Dependencies ................................................................................................... 76 Cryptographic API Initialization/Shutdown ............................................................ 76 Encryption/Decryption ....................................................................................... 76 Authentication .................................................................................................. 77 Key/Random Number Generation ........................................................................ 77 Re-Keying ........................................................................................................ 77
10.0 SRTP 10.1 10.2 10.3 10.4
Acceleration Driver Details ............................................................................. 79 What’s New in this Chapter................................................................................. 79 Overview and Terminology ................................................................................. 79 Memory Buffer Management ............................................................................... 79 Stream Establishment ........................................................................................ 79 10.4.1 Configuring an SRTP Accelerated Stream ................................................... 80 Stream Removal ............................................................................................... 81 Performing an Encrypt/Decrypt Operation............................................................. 82 10.6.1 Commencing an Operation - write() .......................................................... 82 10.6.2 Completing an Operation - read() ............................................................. 82 Key Generation ................................................................................................. 83 Control Path Overview ....................................................................................... 84
10.5 10.6 10.7 10.8
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 5
IP Telephony Software—Contents
10.8.1 Open.....................................................................................................84 10.8.2 Release .................................................................................................84 10.8.3 Ioctl......................................................................................................84 10.9 Data Path .........................................................................................................85 10.9.1 Encrypt/Decrypt Operation.......................................................................85 10.10 Resource Usage.................................................................................................85 10.11 QAT Access Layer (QAT-AL) Configuration .............................................................85 10.11.1Interrupt Coalescing and Synchronous Accelerated SRTP..............................86 10.11.2Interrupt Coalescing and Asynchronous Accelerated SRTP ............................86 11.0 HSS I/O Access Library Details ................................................................................87 11.1 What’s New in this Chapter .................................................................................87 11.2 Overview and Terminology..................................................................................87 11.3 Dependencies....................................................................................................87 11.4 Packet Based Design ..........................................................................................88 11.5 Multiple Client Support .......................................................................................88 11.6 Channel ID Management.....................................................................................89 11.7 Buffer Chaining .................................................................................................89 11.8 Endianness .......................................................................................................89 11.9 Memory Buffer Management................................................................................89 11.10 Main Core – Programmable I/O Unit Communication...............................................89 11.10.1Lockless Software Queue Mechanism.........................................................90 11.10.2Receive-Free Queue (RxFreeQ).................................................................91 11.10.3Receive Queue (RxQ) ..............................................................................92 11.10.4Transmit Queue (TxQ).............................................................................93 11.10.5Queue Counter Shadowing .......................................................................94 11.10.6Buffer Recovery (Tx Done) .......................................................................94 11.11 Access Library Software Rings .............................................................................96 11.12 IX_OSAL_MBUF Programmable I/O Unit Specific Section Format ..............................96 11.13 Queue Entry Format...........................................................................................97 11.14 Polled/Callback Mode..........................................................................................98 11.15 Resource Usage.................................................................................................98 11.15.1Queue Sizes...........................................................................................98 11.15.2Counter Sizes.........................................................................................99 11.15.3Ring Sizes..............................................................................................99 11.16 Operating System-Specific Details........................................................................99 12.0 HSS I/O Access Packet Flow Details ...................................................................... 101 12.1 What’s New in this Chapter ............................................................................... 101 12.2 Data Flow Scenarios......................................................................................... 101 12.2.1 Transmit to Channel.............................................................................. 101 12.2.2 Retrieve Transmit-Done Buffers .............................................................. 103 12.2.3 Receive from Channel............................................................................ 103 12.2.4 Replenish Free Buffers to Receive-Free Queue .......................................... 104 13.0 SSP I/O Access Library Details .............................................................................. 107 13.1 What’s New in this Chapter ............................................................................... 107 13.2 Overview ........................................................................................................ 107 13.3 Functional Description ...................................................................................... 107 13.3.1 Basic................................................................................................... 107 13.3.2 Detailed .............................................................................................. 107 13.4 Dependencies.................................................................................................. 108 13.5 Memory Buffer Management.............................................................................. 109 13.6 Multiple Clients................................................................................................ 109 13.7 Polled / Callback Mode...................................................................................... 109 13.8 Control Path.................................................................................................... 110
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 6
May 2009 Order Number: 320415-003US
Contents—IP Telephony Software
13.9 Data Path....................................................................................................... 110 13.10 Sequence Flow Diagrams.................................................................................. 110 13.10.1Interrupt Sequence Flow ....................................................................... 110 13.10.2Polled Mode Sequence Flow ................................................................... 113 13.11 Resource Usage .............................................................................................. 115 13.11.1Memory Requirements .......................................................................... 115 13.12 Operating System-Specific Issues ...................................................................... 115
Part 2: Using the API................................................................... 117 14.0 Use Cases .............................................................................................................. 119 14.1 What’s New in this Chapter............................................................................... 119 14.2 Voice-Only Application Example......................................................................... 119 14.3 Data-Only Application Example ......................................................................... 121 14.4 Secure Voice over IP using SRTP ....................................................................... 122 15.0 API Overview for HSS Voice Driver ........................................................................ 125 15.1 What’s New in this Chapter............................................................................... 125 15.2 Overview ....................................................................................................... 125 15.3 Control Path ................................................................................................... 125 15.3.1 Setup Sequence ................................................................................... 125 15.3.2 Shut Down Sequence............................................................................ 126 15.4 Data Path....................................................................................................... 127 15.4.1 Poll .................................................................................................... 127 15.4.2 Read .................................................................................................. 127 15.4.3 Write .................................................................................................. 127 15.5 Dependencies ................................................................................................. 128 15.6 Error Handling ................................................................................................ 129 15.7 Key Assumptions............................................................................................. 129 16.0 API Overview for HSS Data Driver ......................................................................... 131 16.1 What’s New in this Chapter............................................................................... 131 16.2 Overview ....................................................................................................... 131 16.3 Control Path ................................................................................................... 131 16.3.1 Setup Sequence ................................................................................... 131 16.3.2 Shut Down Sequence............................................................................ 133 16.4 Data Path....................................................................................................... 134 16.4.1 Write .................................................................................................. 134 16.4.2 Read .................................................................................................. 134 16.5 Dependencies ................................................................................................. 135 16.6 Error Handling ................................................................................................ 136 17.0 API Overview for Analog FXO/FXS Driver .............................................................. 137 17.1 What’s New in this Chapter............................................................................... 137 17.2 Overview ....................................................................................................... 137 17.3 Control Path ................................................................................................... 137 17.3.1 Setup Sequence ................................................................................... 137 17.3.2 Open .................................................................................................. 137 17.3.3 Event Monitoring .................................................................................. 139 17.3.4 FXO/FXS Commands............................................................................. 139 17.3.5 Shutdown Sequence ............................................................................. 139 17.4 Data Path....................................................................................................... 140 17.5 Dependencies ................................................................................................. 140 17.6 Key Assumptions............................................................................................. 140 17.7 Error Handling ................................................................................................ 140
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 7
IP Telephony Software—Contents
18.0 API Overview for Framer Driver ............................................................................. 141 18.1 What’s New in this Chapter ............................................................................... 141 18.2 Overview ........................................................................................................ 141 18.3 Control Path.................................................................................................... 141 18.3.1 Setup Sequence ................................................................................... 141 18.3.2 Device Event Reporting ......................................................................... 142 18.4 Data Path ....................................................................................................... 142 18.5 Dependencies.................................................................................................. 142 18.6 Key Assumptions ............................................................................................. 143 18.7 Error Handling................................................................................................. 143 19.0 API Overview for SRTP Acceleration Driver ............................................................ 145 19.1 What’s New in this Chapter ............................................................................... 145 19.2 Overview ........................................................................................................ 145 19.3 SRTP Stream and Cryptographic API Session Association....................................... 145 19.4 Control Path.................................................................................................... 146 19.4.1 Setup Sequence ................................................................................... 146 19.4.2 Shut Down Sequence ............................................................................ 146 19.5 Data Path ....................................................................................................... 147 19.5.1 Crypto Operation .................................................................................. 147 19.5.2 Random Number Generation .................................................................. 148 19.5.3 Write .................................................................................................. 148 19.5.4 Read ................................................................................................... 148 19.6 High Level API Flow ......................................................................................... 148 19.6.1 Stream Establishment ........................................................................... 149 19.6.2 Removing a Stream .............................................................................. 149 19.6.3 Configuring a SRTP Accelerated Stream ................................................... 149 19.6.4 Performing a Cryptographic Operation ..................................................... 150 19.6.5 Random Number Generation .................................................................. 150 19.7 Error Handling................................................................................................. 151 19.8 Key Assumptions ............................................................................................. 151 20.0 API Overview for HSS I/O Access Library .............................................................. 153 20.1 What’s New in this Chapter ............................................................................... 153 20.2 Control Path.................................................................................................... 153 20.2.1 Setup Sequence ................................................................................... 153 20.2.2 Channel Up .......................................................................................... 154 20.2.3 Channel Down ...................................................................................... 155 20.2.4 Channel Delete..................................................................................... 155 20.2.5 Buffer Retrieval .................................................................................... 155 20.2.6 Channel Bypass .................................................................................... 156 20.2.7 Component Un-Initialize ........................................................................ 156 20.3 Dependencies.................................................................................................. 156 20.4 Error Handling................................................................................................. 157 21.0 API Overview for SSP I/O Access Library............................................................... 159 21.1 What’s New in this Chapter ............................................................................... 159 21.2 Control Path.................................................................................................... 159 21.2.1 Initialization / Un-Initialization................................................................ 159 21.2.2 Configuration ....................................................................................... 159 21.2.3 Interrupt Enabling / Disabling................................................................. 160 21.2.4 Statistics ............................................................................................. 160 21.2.5 FIFO Thresholds ................................................................................... 160 21.2.6 Monitoring ........................................................................................... 160 21.3 Data Path ....................................................................................................... 161 21.3.1 Tx ...................................................................................................... 161
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 8
May 2009 Order Number: 320415-003US
Contents—IP Telephony Software
21.4 21.5 21.6
21.3.2 Rx ...................................................................................................... 162 Dependencies ................................................................................................. 162 Key Assumptions............................................................................................. 163 Error Handling ................................................................................................ 163
Figures 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
Intel® EP80579 Integrated Processor with Intel® QuickAssist Technology Block Diagram ... 22 EP80579 IP Telephony software HSS Component Overview............................................ 24 TDM Setup Driver Dependencies ................................................................................ 26 HSS Voice Driver Dependencies ................................................................................. 32 Tx Memory Buffer Management.................................................................................. 33 Initial Rx Replenishment ........................................................................................... 34 Rx Memory Buffer Management ................................................................................. 34 Read / Write Data Format - One G.711 Channel ........................................................... 38 Read / Write Data Format - One G.711 Channel and One Linear PCM Channel .................. 38 Read and Write - Single Vs. Multiple Channels per File Descriptor ................................... 41 Linux PPP Architecture .............................................................................................. 44 EP80579 IP Telephony software HSS PPP Architecture Overview ..................................... 45 HSS Data Driver Dependencies .................................................................................. 46 Tx Memory Buffer Management.................................................................................. 47 Initial Rx Replenishment ........................................................................................... 48 Rx Memory Buffer Management ................................................................................. 48 Analog FXO/FXS Driver Overview ............................................................................... 56 Analog FXO/FXS Driver Dependencies ......................................................................... 57 Analog FXO/FXS Driver Blocking read() ....................................................................... 62 Analog FXO/FXS Driver Non-Blocking read() ................................................................ 63 Analog FXO/FXS Driver Event Format ......................................................................... 63 Framer Driver Overview ............................................................................................ 66 Framer Driver Dependencies...................................................................................... 67 Digital Loopback ...................................................................................................... 70 Line Loopback ......................................................................................................... 70 Payload Loopback .................................................................................................... 71 Framer Driver Blocking read().................................................................................... 72 Framer Driver Non-Blocking read() ............................................................................. 73 Framer Driver Event Format ...................................................................................... 74 SRTP Session and Stream Concept ............................................................................. 75 SRTP Acceleration Driver Dependencies....................................................................... 76 Overview of Stream Establishment and Configuration.................................................... 81 Overview of SRTP Stream Removal............................................................................. 81 Overview of write() .................................................................................................. 82 Overview of read() ................................................................................................... 83 TDM Interface Component Dependencies..................................................................... 88 Queue Counter Memory Assignments.......................................................................... 91 Receive Free Queues for Voice and HDLC Channels....................................................... 92 Receive Queue Design .............................................................................................. 93 Transmit Software Based Circular Queues ................................................................... 94 Transmit Queue Shadowing ....................................................................................... 95 Packet Transmit Submission .................................................................................... 102 Packet Receive ...................................................................................................... 104 SSP I/O Access Library Dependencies ....................................................................... 109 SSP I/O Access Library Interrupt Mode Sequence Flow ................................................ 111 SSP I/O Access Library Polled Mode Sequence Flow .................................................... 114 Voice-Only Application Architecture .......................................................................... 120
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 9
IP Telephony Software—Contents
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
Data-Only Application Architecture............................................................................ 122 Secure Voice over IP using SRTP Application Architecture............................................. 124 HSS Voice Driver High-Level API Control Path ............................................................ 127 HSS Voice Driver High-Level API Data Path ................................................................ 128 HSS Voice Driver Dependencies................................................................................ 129 HSS Data Driver High-Level API Control Path ............................................................. 134 HSS Data Driver High-Level API Data Path ................................................................. 135 HSS Data Driver Dependencies................................................................................. 136 Analog FXO/FXS Driver Initialization and Configuration Flow......................................... 138 Analog FXO/FXS Driver Event Handling and Command Flow ......................................... 139 Analog FXO/FXS Driver Dependencies ....................................................................... 140 Framer Driver High Level API Control Path ................................................................. 142 Framer Driver Dependencies .................................................................................... 143 SRTP Acceleration Driver High-Level API Control Path.................................................. 147 SRTP Acceleration Driver High-Level API Data Path ..................................................... 148 HSS Port Configuration High-Level API Flow Diagram .................................................. 154 Voice Channel Configuration High-Level API Flow Diagram ........................................... 155 HSS Access Library Dependencies Diagram ................................................................ 157 HSS I/O Error Handling and Notification..................................................................... 158 SSP I/O Access Library Initialization Control Flow........................................................ 161 SSP I/O Access Library Data Flow ............................................................................. 162 SSP I/O Access Library Dependencies........................................................................ 163
Tables 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Related Documents...................................................................................................14 Terms and Definitions ...............................................................................................14 Supported Cryptographic Operations ...........................................................................18 TDM Setup Driver Command Line Parameters...............................................................27 TDM Setup Driver Linux User Space Interface Ioctl Commands .......................................28 Ioctl Command Descriptions.......................................................................................37 Predefined HSS Port Configurations.............................................................................38 Ioctl Command Descriptions.......................................................................................51 Pre-Defined HSS Port Configurations ...........................................................................51 Analog FXO/FXS Driver Linux User Space Interface Ioctl Commands................................59 Analog FXO/FXS Driver Linux User Space Interface Geographic Options ...........................61 Analog FXO/FXS Driver Linux User Space Interface Events .............................................63 Framer Driver Predefined Configurations......................................................................69 Framer Driver Device Events......................................................................................73 Ioctl Command Descriptions.......................................................................................84 Layout of Programmable I/O Unit Specific Section of IX_OSAL_MBUF ..............................96 Service-Specific Sections of the IX_OSAL_MBUF Fields ..................................................97 Queue Entry Format .................................................................................................97 HSS Voice Driver Interface Summary ........................................................................ 125 HSS Data Driver Interface Summary ......................................................................... 131 Analog FXO/FXS Driver Interface Summary................................................................ 137 SRTP Acceleration Driver Interface Summary ............................................................. 145
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 10
May 2009 Order Number: 320415-003US
Revision History—IP Telephony Software
Revision History
Date
Revision
Description
003
Minor revision to remove references to future software releases in Section 2.2. Change bars were not updated; change bars show edits from previous doc version (below).
November 2008
002
The following sections were updated and noted with change bars: • Updated Chapter 9.0, Chapter 10.0, and Chapter 19.0 to describe the new asynchronous API of the SRTP Acceleration driver. • Other updates noted in “What’s New” sections of chapters and with change bars.
September 2008
001
Initial release of this document.
May 2009
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 11
IP Telephony Software—Revision History
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 12
May 2009 Order Number: 320415-003US
Introduction—IP Telephony Software
1.0
Introduction The Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology is comprised of: • Time Division Multiplexing (TDM) interface enabling software which includes: — High Speed Serial (HSS) Voice Driver — HSS Data Driver — HSS I/O Access Library and underlying infrastructure components — TDM Setup Driver • Peripherals enabling Device Drivers (PDD) and Access layers which includes: — Analog FXO/FXS Driver — Framer Device Driver — Synchronous Serial Port (SSP) I/O Access Library • Voice over IP Software which includes: — SRTP Acceleration Driver for secure VoIP
1.1
About this Document The API Reference Manuals listed in Table 1 specify how the user can interface to the EP80579 IP Telephony software. This document provides more information on how the APIs can be effectively used, including an overview of the silicon, an overview of the software architecture, and information on using the API to build an accelerated IP Telephony appliance. The following chapters are included in this document: • Chapter 1.0, “Introduction”, this chapter • Part 1: “Architectural Overview” — Chapter 2.0, “Silicon Overview” — Chapter 3.0, “TDM Software Overview” — Chapter 4.0, “TDM Setup Driver Details” — Chapter 5.0, “HSS Voice Driver Details” — Chapter 6.0, “HSS Data Driver Details” — Chapter 7.0, “Analog FXO/FXS Driver Details” — Chapter 8.0, “Framer Driver Details” — Chapter 9.0, “SRTP Acceleration Overview” — Chapter 10.0, “SRTP Acceleration Driver Details” — Chapter 11.0, “HSS I/O Access Library Details” — Chapter 12.0, “HSS I/O Access Packet Flow Details”
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 13
IP Telephony Software—Introduction
— Chapter 13.0, “SSP I/O Access Library Details” • Part 2: “Using the API” — Chapter 14.0, “Use Cases” — Chapter 15.0, “API Overview for HSS Voice Driver” — Chapter 16.0, “API Overview for HSS Data Driver” — Chapter 17.0, “API Overview for Analog FXO/FXS Driver” — Chapter 18.0, “API Overview for Framer Driver” — Chapter 19.0, “API Overview for SRTP Acceleration Driver” — Chapter 20.0, “API Overview for HSS I/O Access Library” — Chapter 21.0, “API Overview for SSP I/O Access Library”
1.2
Related Documents
Table 1.
Related Documents Ref
1.3
Document Name
Number
[HSS_ACC_API_REF]
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology TDM I/O Access API Reference Manual
320417
[DRIVERS_API_REF]
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology Linux* Device Driver API Reference Manual
320416
[GET_STARTED]
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology for Linux* Getting Started Guide
320414
[SEC_PROG_GD]
Intel® EP80579 Software for Security Applications on Intel® QuickAssist Technology Programmer’s Guide
320183
N/A
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology for Linux* SRTP Acceleration Driver Application Note
320517
N/A
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology Linux* Tuning Guide
320524
N/A
Integrating a Voice Application with the TDM Infrastructure of the Intel® EP80579 Integrated Processor with Intel® QuickAssist Technology White Paper
320053
Glossary Table 2 lists the terms and acronyms used in this document.
Table 2.
Terms and Definitions (Sheet 1 of 3) Term
Description
AES
Advanced Encryption Standard
AMI
Alternate Mark Inversion
ASD
Acceleration System Driver
ATM
Asynchronous Transfer Mode
ATMoS
ATM over Serial
B8ZS
Binary with 8 Zero Substitution
CAS
Channel Associated Signaling
CBC
Cipher Block Chaining
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 14
May 2009 Order Number: 320415-003US
Introduction—IP Telephony Software
Table 2.
Terms and Definitions (Sheet 2 of 3) Term
Description
CCS
Common channel signaling
CRC
Cyclic Redundancy Check
DAA
Direct Access Arrangement
DS0
Digital Signal 0. A single 64 Kbps channel, which is the building block of a T1 transmission line. 24 DS0 channels make up one T1 line.
E1
Euro 1 trunk line (2.048 Mbps)
ESF
Extended Super Frame
FCS
Frame Checksum Sequence
FIFO
First In First Out
FXO
Foreign Exchange Office
FXS
Foreign Exchange Subscriber
GPIO
General Purpose Input Output
HDB3
High Density Bipolar 3 coding
HDLC
High-Level Data Link Control
HMAC
Hashed Message Authentication
H-MVIP
High speed Multi-Vendor Integration Protocol
HSS
High Speed Serial
ICM
Integer Counter Mode, also known as CTR
IMA
Inverse Multiplexing over ATM
IP
Internet Protocol
IRQ
Interrupt Request
LAC
Lookaside Crypto, also called Cryptographic API
MRU
Maximum Receive Unit
MTU
Maximum Transmit Unit
MVIP
Multi-Vendor Integration Protocol
OSAL
Operating Systems Abstraction Layer
PCM
Pulse Code Modulation
PDD
Peripheral Device Driver
PIU
Programmable I/O Unit
PPP
Point-to-Point Protocol
QAT-AL
Intel® QuickAssist Technology Access Layer
Q-MVIP
Quad Multi-Vendor Integration Protocol
RTCP
Real-time Transport Control Protocol
RTP
Real-time Transport Protocol
SF
Super Frame
SHA
Secure Hash Algorithm
SPI
Serial Peripheral Interface
SRTCP
Secure Real-time Transport Control Protocol
SRTP
Secure Real-time Transport Protocol
SSP
Synchronous Serial Port
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 15
IP Telephony Software—Introduction
Table 2.
Terms and Definitions (Sheet 3 of 3) Term
Description
SSRC
Synchronization Source identifier, SRTP identifier found in the SRTP header
T1
Type 1 trunk line (1.544 Mbps)
TCP
Transmission Control Protocol
TDM
Time Division Multiplexing
TTY
A generic term for any computer data terminal or associated serial interface
VoIP
Voice over Internet Protocol
1.4
Feature List
1.4.1
HSS Ports Three HSS ports are supported. Each port can be configured for a single E1, a single T1 or 4 E1s using Quad MVIP. On both Receive and Transmit, clock direction can be configured as an input, an output or be taken from a reference clock. The data and frame clock edges on which to synchronize can also be configured. Each port can be configured separately for external or internal loopback. The frame offset for each HSS port can also be set to a used defined value. In the case of a T1 configuration, the usage of F-Bit and how to drive it is configurable.
1.4.2
Channels The HSS feature supports up to 128 channels for an E1 configuration (96 channels for T1), each of which can be configured as an HDLC channel or a Voice channel. In addition, each channel can be configured for 1 to 32 DS0s within a single E1 trunk (1 to 24 DS0s within a single T1 trunk). DS0 allocation for each channel will be symmetric. Channel interleaving is supported. Channel bit and byte endianness are configurable. HDLC bit robbing (1 bit per byte) usage and position are configurable. For HDLC channels, FCS size can be 2 or 4 bytes; the number of start of frame flags is configurable as well as expected Transmit and Receive Idle patterns. HDLC Channels have a configurable maximum Receive frame size. Voice channels can be configured to repeat the last frame transmitted when idling or repeat a configurable idle pattern. The idle pattern must be configured in all cases to cater for the case where no voice samples have yet been transmitted. Voice sample size is configurable.
1.4.3
Channel Bypass The HSS I/O Access library supports the configuration of up to four unidirectional channel bypasses for narrowband voice channels. Each bypass means that the destination channel will transmit all data received by the source channel. The data received on the source channel will still be passed on to the user application, but transmission on the destination channel is prohibited.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 16
May 2009 Order Number: 320415-003US
Introduction—IP Telephony Software
All channel bypasses must be configured on the same HSS port. The HSS I/O Access library supports the configuration of up to 4 Gain Control Tables. Each table can be associated with any number of channel bypass.
1.4.4
Serial Protocols The SSP I/O Access Library provides the functionality for: • Access to serial protocols: — Motorola* serial peripheral interface (SPI) • Support of serial data rates from 7.2 kHz to 1.84 MHz • Provides one 32 byte FIFO for receive data and one 32 byte FIFO for transmit data. The size of the entries in the FIFO is configurable.
1.4.5
Drivers
1.4.5.1
Voice and Data Driver The Voice and Data drivers provide a user space to kernel space interface for the user application to access all the functionality provided by the Access layers described in Section 1.4.1, Section 1.4.2, and Section 1.4.3.
1.4.5.2
Framer Driver The Framer Driver provides functionality for: • Initialization of an external framer device • Configuration of external line type, signalling, encoding, framing, and backplane mode of this external framer device • Event monitoring of the external framer device
1.4.5.3
SLIC/CODEC Driver The SLIC/CODEC Driver provides functionality for: • Initialization of external SLIC/CODEC and DAA devices • Configuration of PCM characteristics of external SLIC/CODEC and DAA devices • Sending of FXO/FXS commands to external SLIC/CODEC and DAA devices • Event monitoring of external SLIC/CODEC and DAA devices
1.4.5.4
TDM Setup Driver The TDM Setup Driver provides functionality for: • Providing PCI enumeration information to the Programmable I/O Unit (PIU) and SSP hardware • Initialization of the communication infrastructure between PIU and IA • Providing a mechanism to reserve mezzanine slots and retrieve the IRQ level for each mezzanine slot
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 17
IP Telephony Software—Introduction
1.4.5.5
SRTP Acceleration Driver The purpose of the SRTP Acceleration driver is to provide cryptographic acceleration through EP80579 hardware for applications implementing the SRTP protocol. The driver uses the Intel® EP80579 Software for Security Applications on Intel® QuickAssist Technology Cryptographic API (Cryptographic API) to implement the acceleration functions. The SRTP driver supports the default mandatory operations defined in the SRTP protocol as well as AES 128 CBC encryption. A list of these operations can be seen in Table 3.
Table 3.
Supported Cryptographic Operations Operation Type
Algorithm
Encryption/Decryption
NULL
Encryption/Decryption
AES 128 ICM1
Encryption/Decryption
AES 128 CBC
Authentication
HMAC SHA12
Authentication
NULL
Random Number Generation
Random Number Generation
1. Default, Mandatory to implement Cipher operation in RFC3711 2. Default, Mandatory to implement Authentication Algorithm in RFC3711
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 18
May 2009 Order Number: 320415-003US
Part 1: Architectural Overview This section contains the following chapters: • Chapter 2.0, “Silicon Overview” • Chapter 3.0, “TDM Software Overview” • Chapter 4.0, “TDM Setup Driver Details” • Chapter 5.0, “HSS Voice Driver Details” • Chapter 6.0, “HSS Data Driver Details” • Chapter 7.0, “Analog FXO/FXS Driver Details” • Chapter 8.0, “Framer Driver Details” • Chapter 9.0, “SRTP Acceleration Overview” • Chapter 10.0, “SRTP Acceleration Driver Details” • Chapter 11.0, “HSS I/O Access Library Details” • Chapter 12.0, “HSS I/O Access Packet Flow Details” • Chapter 13.0, “SSP I/O Access Library Details”
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 19
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 20
May 2009 Order Number: 320415-003US
Silicon Overview—IP Telephony Software
2.0
Silicon Overview
2.1
What’s New in this Chapter Removed references to future software releases.
2.2
High Level Overview The Intel® EP80579 Integrated Processor is a System On a Chip (SOC), integrating the Intel® Architecture core processor, the Integrated Memory Controller Hub (IMCH) and the Integrated I/O Controller Hub (IICH) all on the same die. In addition, it has integrated Intel® QuickAssist Technology, which provides acceleration of cryptographic and packet processing. It also includes three gigabit Ethernet MACs, TDM interfaces, and PCI Express. See Figure 1 for details. • As an SOC, the EP80579 integrates the processor and chipset as follows: — The IA-32 core is based on the Intel® Pentium® M processor, and runs at 6001200MHz, with a 256 Kilobyte 2-way level 2 (L2) cache. — The IMCH provides the main path to memory for the IA core and all peripherals that perform coherent I/O (for example, the PCI express, the IICH, as well as transactions from the Acceleration and I/O Complex to coherent memory). — The IICH provides a set of PC platform-compatible I/O devices that include two SATA 1.0/2.0, two USB 1.1/2.0 host controller supporting two USB ports, and two serial 16550 compatible UART interfaces. • The Intel® QuickAssist Technology components, housed in the Acceleration and I/O Complex (AIOC), are as follows: — The Security Services Unit (SSU) provides acceleration of cryptographic processing for most common symmetric cryptography (cipher algorithms such as AES, 3DES, DES, (A)RC4, and messages digest/hash functions such as MD5, SHA-1, SHA-2, HMAC, etc.); asymmetric cryptography (modular exponentiation to support public key encryption such as RSA, Diffie-Hellman, DSA); and true random number generation. — The Acceleration Services Unit (ASU) includes packet processing acceleration engines. • Other components within the AIOC include: — Three Gigabit Ethernet (GbE) media access controllers (MACs). — Three High Speed Serial (HSS) interfaces that support up to 12 T1/E1 TDM interfaces. These interfaces are driven by a Programmable I/O Unit (PIU). The PIU is not part of the ASU. In Figure 1 on page 22, the PIU is shown as the TDM Interface block. — Although not shown explicitly in Figure 1, the AIOC also contains logic to allow agents to access on-chip SRAM and external DRAM. Based on registers which can be configured in the BIOS, this logic routes requests to external DRAM either directly to the memory controller (to access non-coherent DRAM, or NCDRAM); or through the IMCH for coherency with the IA processor’s L2 cache (to access Coherent DRAM, or CDRAM). There is also a ring controller, which
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 21
IP Telephony Software—Silicon Overview
provides 64 rings (circular buffers) that can be used for message passing between software running on the IA core and firmware running on the ASU. These features are described in detail in later sections of this document. Figure 1.
Intel® EP80579 Integrated Processor with Intel® QuickAssist Technology Block Diagram
Acceleration ‡ Services Unit
Local Expansion Bus
Security ‡ Services Unit
(16b @ 80 MHz)
(3DES, AES, (A)RC4, MD5, SHA-x, PKE, TRNG)
MDIO (x1) CAN (x2) SSP (x1) IEEE-1588
TDM ‡ Interface
GigE MAC
GigE MAC
GigE MAC
(12 E1/T1)
#2
#1
#0
256 KB ASU SRAM ‡ Enabling software required.
Acceleration and I/O Complex IA Complex
IMCH
(256 KB)
L2 Cache
IA-32 core
Transparent PCI-to-PCI Bridge
FSB
EDMA
Memory Controller Hub
IICH APIC, DMA, Timers, Watch Dog Timer, RTC, HPET (x3) PCI Express Interface
Memory Controller
(x1)
SPI LPC1.1
SATA 2.0
USB 2.0
(x2)
(x2)
UART (x2) GPIO (x36) SMBus (x2)
(Gen1, 1x8, 2x4 or 2x1 root complex)
(DDR-2 400/533/667/800 , 64b with ECC)
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 22
May 2009 Order Number: 320415-003US
TDM Software Overview—IP Telephony Software
3.0
TDM Software Overview
3.1
What’s New in this Chapter No updates in this release.
3.2
Interrupt Operation The TDM interface can be operated in either polled or callback mode.
Note:
The Voice driver will use Polled or Callback mode API depending on the mode provided by the client when opening the driver device file (blocking by default i.e. Callback mode). The Data driver will use the Callback mode API. The HSS I/O Access library does not support any configuration parameter to define the mode used. The mode is implicit depending on the set of APIs that is used by the client driver. In polled mode, there is no use of interrupts. In callback mode, the HSS I/O Access Library Client registers the appropriate HSS I/O Access servicing routine to the TDM I/O Interrupt. The TDM I/O Interrupt will be generated by the Programmable I/O Unit (PIU) when data is received or when it has completed an HDLC packet or Voice sample transmission. In short, the interrupt is used by the PIU to notify the HSS I/O Access library running on the main core that one of the queues used requires servicing.
3.3
OS System Support For the current release, the HSS feature is only supported on Red Hat* Enterprise Linux* 5.0 (RHEL 5.0).
3.4
Development Tools Information For this release, see [GET_STARTED] for details.
3.5
API Documentation Refer to [DRIVERS_API_REF] for more information about the HSS Voice Driver, HSS Data Driver, Framer Driver, Analog FXO/FXS Driver, and SSP I/O Access Library API. Refer to [HSS_ACC_API_REF] for more information about the HSS I/O Access Library API.
3.6
Required Hardware For this release, see [GET_STARTED] for details.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 23
IP Telephony Software—TDM Software Overview
3.7
TDM Overview Figure 2 depicts the subcomponents that enable the TDM functionality of the EP80579 IP Telephony software.
Figure 2.
EP80579 IP Telephony software HSS Component Overview
Intel® EP80579
Application
Framer Driver User Space Kernel Space LSP
OS
HSS Data Driver HSS Voice Driver
TDM Setup Driver
Framer Infrastructure Driver
SLIC/Codec Driver
OSAL
Voi
Access Libraries bufferMgmt
HSS I/O Access Layer
Log irq
PIU Message Handler
memory
PIU Downloader
SSP I/O Access Layer
Thread
PIU QMGR
Programmable I/O Unit (PIU)
SPI Interface (Control) Expansion Bus (Control)
H-MVIP Backplane (Data)
SPI Interface (Control)
SLIC/CODECs
E1/T1 Framer
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 24
May 2009 Order Number: 320415-003US
TDM Setup Driver Details—IP Telephony Software
4.0
TDM Setup Driver Details
4.1
What’s New in this Chapter No updates in this release.
4.2
Functional Description The TDM Setup Driver provides the following services: • Conforms to a standard Linux character device driver interface. • Registers itself upon initialization as a character device driver, providing typical character device operations. • Performs PCI enumeration for the Programmable I/O Unit (PIU). — Retrieves the base address for the PIU. — Registers as the master of the PIU as a PCI device with the OS. • Performs PCI enumeration for the SSP Hardware. — Retrieves the base address for the SSP hardware. — Registers as the master of the SSP hardware as a PCI device with the OS. • Initializes the communication infrastructure between PIU and the IA. • Initializes the HSS I/O Access Library. • Initializes the SSP I/O Access Library. • Provides a mechanism to reserve and unreserve mezzanine slots. • Provides a mechanism to retrieve the IRQ level for each mezzanine slot.
4.3
Dependencies Figure 3 shows the dependencies and external interactions of the TDM Setup Driver.
May 2009 Order Number: 320415003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 25
IP Telephony Software—TDM Setup Driver Details
T
Figure 3.
TDM Setup Driver Dependencies
Client
User Space Kernel Space
TDM Setup Driver
Linux Kernel
Programmable I/O Unit Communications Infrastructure
4.4
SSP I/O Access Library
HSS I/O Access Library
Multiple Clients There is a single instance of the TDM Setup Driver. It may have multiple clients. When a client opens the /dev/tdm-setup device file, it is passed a unique file descriptor. The driver can be initialized only once. If a second call is made to initialize the driver, then the driver returns success without performing any operation. Likewise, the driver can be uninitialized only once. See Section 4.6.4, “Ioctl” on page 28 for more details. The driver keeps track of the number of times that the initialize ioctl has been called. The uninitialize ioctl must be called the same number of times to uninitialize the TDM features. One possible scenario is as follows: 1. Client Voice Application calls the ICP_TDMSETUPDRV_INIT ioctl. a.
Initialization count is equal to zero therefore the driver has not been initialized.
b.
TDM features are initialized.
c.
Initialization count is incremented by one.
2. Client Data Application calls the ICP_TDMSETUPDRV_INIT ioctl. a.
Initialization count is greater than zero therefore the driver is already initialized.
b.
Initialization count is incremented by one.
3. Client Voice Application calls the ICP_TDMSETUPDRV_UNINIT ioctl. a.
Initialization count is decremented by one.
b.
Initialization count is greater than zero therefore the driver is being used by some other client and cannot be uninitialized.
4. Client Data Application calls the ICP_TDMSETUPDRV_UNINIT ioctl. a.
Initialization count is decremented by one.
b.
Initialization count is equal to zero therefore the driver is not being used by some other client and can be uninitialized.
c.
TDM features are uninitialized.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 26
May 2009 Order Number: 320415003US
TDM Setup Driver Details—IP Telephony Software
4.5
Blocking / Non-Blocking Mode There is no read command available for this driver so the driver can be opened in either blocking (O_BLOCK) or non-blocking (O_NONBLOCK) mode. The selected mode has no effect on the operation of the driver.
4.6
Control Path
4.6.1
Command Line Parameters Table 4 lists the command line parameters that can be used when loading the TDM Setup Driver.
Table 4.
TDM Setup Driver Command Line Parameters Parameter autoinit
Possible Values 0 = Driver will not be initialized when loaded 1 = (default) Driver will be initialized when loaded
If autoinit is set to one, then the TDM features are automatically initialized when the driver is loaded. Otherwise, the Init Ioctl must be called once the driver has been loaded. The operations performed on insmod when autoinit is enabled are analogous to calling ICP_SETUPDRV_INIT. If the driver has been loaded with autoinit set to one, then the driver is automatically uninitialized when it is unloaded. Otherwise, the Uninit Ioctl must be called before the driver can be unloaded.The operations performed on rmmod when autoinit is enabled are analogous to calling ICP_SETUPDRV_UNINIT.
4.6.2
Open The open function is the driver interface method called whenever the equivalent libc open() function is called from the client in user space. The client opens the TDM Setup Driver character device driver file (/dev/tdm-setup). Open does not perform any operation in the driver itself. The prototype for the open function is as follows:
int open(struct inode *inode, struct file *file);
4.6.3
Release The release function is the driver interface method called whenever the equivalent libc close() function is called from the client in user space. The client must close, on exit, the TDM Setup Driver character device driver file (/dev/tdm-setup). Similar to Open, the Release command does not perform any operation internally in the driver. The prototype for the release function is as follows:
int release(struct inode *inode, struct file *file);
May 2009 Order Number: 320415003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 27
IP Telephony Software—TDM Setup Driver Details
4.6.4
Ioctl The ioctl function is the driver interface method called whenever the equivalent libc ioctl() function is called from the client in user space. The client can use ioctl in order to initialize or uninitialize the TDM Setup Driver via /dev/tdm-setup, once the character device file has been successfully opened. Ioctl can also be used to reset the TDM features, i.e. it is valid to initialize, uninitialize, and then initialize again. The prototype for the ioctl function is as follows:
int ioctl(struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg); Ioctl is used for initializing the TDM features. The supported commands are listed in Table 5. Table 5.
TDM Setup Driver Linux User Space Interface Ioctl Commands Command
4.6.4.1
Argument
Description
ICP_TDMSETUPDRV_INIT
None
This command initializes all TDM features.
ICP_TDMSETUPDRV_UNINIT
None
This command uninitializes all TDM features.
Initializing the TDM Features When the ICP_TDMSETUPDRV_INIT IOCTL is called, the following operations are performed in sequence and any resources needed are allocated by the system. • Performs PCI enumeration for the Programmable I/O Unit (PIU). • The communications infrastrucure between the Programmable I/O Unit and the IA is initialized. • The HSS I/O Access Library is initialized. • The SSP I/O Access Library is initialized. If the Init Ioctl has already been called or the driver has been loaded with autoinit = 1, then this command increments an internal counter that tracks the number of times the Init Ioctl has been called.
4.6.4.2
Uninitializing TDM Features When the ICP_TDMSETUPDRV_UNINIT IOCTL is called, the following operations are performed in sequence and resources allocated are returned to the system. • The SSP I/O Access Library is uninitialized. • The HSS I/O Access Library is uninitialized. • The communications infrastrucure between the Programmable I/O Unit and the IA is uninitialized. • Unregisters as the master of the Programmable I/O Unit as a PCI device with the OS. If the driver has been loaded with autoinit = 0, then this command must be called before unloading the driver.
4.6.5
Write Write is not implemented in the interface.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 28
May 2009 Order Number: 320415003US
TDM Setup Driver Details—IP Telephony Software
4.6.6
Read Read is not implemented in the interface.
4.7
Data Path The TDM Setup Driver does not implement a data path as it is responsible for initialization only.
4.8
Mezzanine Slot Reservation The TDM Setup Driver provides functionality to reserve and unreserve mezzanine slots. A mechanism to retrieve the base address and IRQ level for each slot is also provided.
4.9
Resource Usage None.
4.10
Operating System-Specific Issues The TDM Setup Driver is a Linux*-only device driver.
§§
May 2009 Order Number: 320415003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 29
IP Telephony Software—TDM Setup Driver Details
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 30
May 2009 Order Number: 320415003US
HSS Voice Driver Details—IP Telephony Software
5.0
HSS Voice Driver Details
5.1
What’s New in this Chapter No updates in this release.
5.2
Overview The HSS Voice Driver is a kernel level driver. It conforms to a Linux* character device driver model. It initializes and manages voice channel communication with the HSS I/O Access Library.
5.3
Functional Description The HSS Voice Driver performs the following activities: • Registers itself upon initialization as a character device driver, providing typical character device driver operations. • Provide a means to initialize and configure the HSS hardware interface by a user space client. • Provide a means to transmit voice samples from a user space client to the HSS I/O Access Library. • Provide a means to receive voice samples from the HSS I/O Access Library and pass to a user space client. • Provide memory management for all kernel space buffers.
5.4
Dependencies Figure 4 shows the dependencies and external interactions of the HSS Voice Driver. The Media Processor is expected to be the most used client to the HSS Voice Driver.
Note:
The HSS Voice Driver has no direct dependency on the TDM Setup Driver, but the TDM setup driver is typically responsible for initializing the HSS I/O Access Library and binding the interrupt.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 31
IP Telephony Software—HSS Voice Driver Details
Figure 4.
HSS Voice Driver Dependencies Client (Media Processor) user space
HSS Voice Driver
HSS I/O Access Library
OSAL kernel space hardware TDM interface
The Media Processor accesses the different voice channels managed by the HSS Voice Driver via the standard Character Driver operations (read, write, ioctl). A single file descriptor is used (/dev/hss-voice), and the different channels are multiplexed within the driver. Clients can access multiple channels per file descriptor if they so wish. For example, a single threaded client may wish to access multiple channels on one file descriptor, whereas a multiple threaded application may wish to access multiple channels by having multiple file descriptors which are each used to access a single channel. More information about client usage models is available in Section 5.11.5, “Single Vs. Multiple Channels per File Descriptor” on page 40 .
5.5
Memory Buffer Management The HSS Voice Driver is responsible for allocating and managing both the OSAL buffers and kernel space data buffers for use by the HSS I/O Access Library voice service and hence the Programmable I/O Unit as well.
5.5.1
Tx Memory Management The driver allocates OSAL buffer and kernel space buffers for copying voice samples for transmission from the user space client, as the client sends voice samples. It also retrieves and recycles used OSAL buffers from the HSS I/O Access Library. The driver allocates Figure 5 shows Tx memory buffer management.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 32
May 2009 Order Number: 320415-003US
HSS Voice Driver Details—IP Telephony Software
Figure 5.
Tx Memory Buffer Management 1. Cl i ent cal l s wri t e()
Headers and Voi ce Sampl es
Li nux User Space Li nux Kernel Space 7. The wri t e() met hod ret urns
2. Read t he embedded HSS Voi ce dri ver chan num and convert t o HSS I/ O Access Li brary chan num 3. Cal l t o HSS I/ O Access Li brary t o ret ri eve any TxDone buf f ers (i . e. OSAL and at t ached char *buf f er).
5. Copy voi ce sampl es f rom cl i ent user space buf f er t o char *buf f er.
OSAL Buf f er
pt r
4. I f no TxDone buf f er ret ri eved, HSS Voi ce dri ver al l ocat es an OSAL buf f er and a char * kernel space buf f er f or t he voi ce sampl es.
Char * buf f er
6. Transmi t OSAL buf f er t o HSS I/ O Access Li brary For multiple channels steps 2-8 are repeated
HSS I/ O Access Li brary I nt erf ace
5.5.2
Rx Memory Management At the first call to open(), the private pool used for replenishing is passed to the HSS I/O Access Library in order to fill the Voice Rx Free Queue. This initial Rx replenishment can be seen in Figure 6.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 33
IP Telephony Software—HSS Voice Driver Details
Figure 6.
Initial Rx Replenishment Linux User Space Linux Kernel Space 2.Allocate char * buffer
1. Allocate OSAL Buffer
OSAL Buffer
4. Replenish the OSAL Buffer back to HSS I/O Access Library. This will be placed in the Rx Free Queue. 5. Repeat until RxFree Queue is full Or max number buffers available are used
ptr
Char * buffer
3. Chain char * buffer to be the Data in an OSAL Buffer
HSS I/O Access Library Interface
When the HSS Voice Driver client (e.g. the Media Processor) reads from the HSS Voice Driver, the HSS Voice driver in turn gets an OSAL buffer from the HSS I/O Access library with an associated char * buffer containing voice samples and copies the data from the char * buffer to the user space buffer. It then replenishes the OSAL buffer and associated char * buffer back to the HSS I/O Access Library RxFree queue. Figure 7 shows Rx memory management. Figure 7.
Rx Memory Buffer Management User Space Buffer 1. Client calls read() Linux User Space Linux Kernel Space
For multiple channels steps 2-6 are repeated For Non-Blocking mode step 2 is skipped.
2. Wait for Callback
4. Insert the HSS Voice driver channel number and data length into the client provided user space buffer 5. Copy voice samples from the char * buffer (pointed to by the OSAL Buffer) to client provided user space buffer
OSAL Buffer
3.Hss I/O Access Library to receive an OSAL buffer with associated voice samples in the char * buffer for the channel
ptr
Char * buffer
6. Replenish the OSAL Buffer and associated char * buffer back to HSS I/O Access Library. This will be placed in the Rx Free Queue 7. The read() method returns
HSS I/O Access Library Interface
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 34
May 2009 Order Number: 320415-003US
HSS Voice Driver Details—IP Telephony Software
In the case of a blocking read, the HSS I/O Access Library calls the Rx callback to indicate that there is data available for a channel, but does not return the data in the callback. The Rx callback sets a flag to indicate that data is available on the channel as indicated by HSS I/O Access Library. The blocking read() call is put to sleep and is only woken up when there is data available for all the channels associated with a file descriptor. This unblocks any blocked read() call in order to retrieve data from the HSS I/O Access Library. The codec interval is the expected time between packet arrival. For G.711 this is typically 10 ms. Sharing a file descriptor for voice channels that have different codec intervals, while in blocking mode is not recommended. It is preferred to use one thread for 10 ms codec channels, and a separate thread for 30 ms codec channels. Otherwise longer codecs (e.g. 30 ms) prevent shorter codecs (e.g. 10 ms) from receiving data at the correct time interval, because the read will be blocked until the longest codec returns data (e.g. in this case every 30 ms).
5.6
Blocking / Non-Blocking Mode When in blocking mode, the voice driver operates the HSS I/O Access Library in callback mode for the channels it has allocated. When in non-blocking mode, the voice driver operates the HSS I/O Access Library in polled mode for the channels it has allocated. In callback mode, the HSS I/O Access Library callback wakes a wait queue for the relevant channel to indicate the callback has occurred.
5.7
Multiple Clients There is a single instance of the HSS Voice Driver. It supports multiple clients. A single device file is used. Multiple file descriptors and channel numbers are used to manage multiple clients. The HSS Voice Driver only supports one mode of operation across all clients at any one time (blocking or non-blocking). Once a client has opened the driver in a particular mode, any attempt to open the driver in the alternative mode will fail (in any client) until such time as no remaining client has the driver open. A client can associate up to 64 channels to a single file descriptor.
5.8
Channel Numbers The HSS Voice Driver API uses channel numbers so that its clients can distinguish channels. The HSS I/O Access Library also provides channel numbers so its clients can distinguish channels. However, it is important to note that these channel numbers are not the same. The HSS Voice Driver maps its clients channel numbers to those used by HSS I/O Access Library and vice versa. The reason a different channel number is used by the HSS I/O Access Library interface is in order to simplify the HSS Voice Driver interface. A HSS Voice Driver client typically starts its channel number assignment at 0, and increments for each channel added. The client may want to use these channel numbers as an array index, and it may be advantageous for them to limit these array sizes to the max amount of channels they will require. If the HSS I/O Access Library channel numbers were exposed, it makes for a more complex assignment of channel numbers, and forces any clients to use array indexes from 0-127. The HSS Voice drivers allow a range of 128 channel numbers per call to open. It is the client’s responsibility to choose which channel number they would like to use when configuring a channel. A unique file descriptor is obtained by the client for every call to
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 35
IP Telephony Software—HSS Voice Driver Details
open(). A HSS Voice Driver client channel number has to be unique per file descriptor. However, different file descriptors can have the same channel number, for example, fd1-chan0, fd1-chan1, fd1-chan2, fd2-chan0, fd2-chan1, fd2-chan2.
5.9
Channel Bypass Channel Bypass is a means of forwarding the receive data from one channel to the transmit data of another channel in the Programmable I/O unit. This is only supported on a voice narrowband channel, that is, one timeslot channel allocated in the context of a voice application. The amount of unidirectional bypasses is limited to a maximum of four. All bypasses must be set up on the same HSS port. The HSS Voice driver is not responsible for the allocation of bypasses, and therefore, it cannot guarantee that the Programmable I/O unit bypasses are not already in use by clients other than the HSS Voice driver. Gain control can be applied to bypasses data before it is transmitted.
5.10
Control Path
5.10.1
Open The open function is the driver interface method called whenever the equivalent libc open() function is called from the client in user space. The client opens the HSS Voice Driver character device driver file (/dev/hss-voice). The prototype for the open function is as follows:
int open(struct inode *inode, struct file *file); The client can specify in the file flags whether they require the driver to operate in blocking (default) or non-blocking (O_NONBLOCK) mode. On the first call to open(), a pool of OSAL buffers is allocated and passed to the HSS I/O Access Library for reception of Rx voice samples.
5.10.2
Release The release function is the driver interface method called when the last close on a file descriptor is called. The client must close, on exit, the HSS Voice Driver character device driver file (/dev/hss-voice). The prototype for the release function is as follows:
int release(struct inode *inode, struct file *file);
5.10.3
Ioctl The ioctl function is the driver interface method called whenever the equivalent libc ioctl() function is called from the client in user space. The client can use ioctl in order to configure the HSS Voice Driver via /dev/hss-voice, once the character device file has been successfully opened.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 36
May 2009 Order Number: 320415-003US
HSS Voice Driver Details—IP Telephony Software
The prototype for the ioctl function is as follows: int ioctl(struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg);
The supported list of commands and their arguments is listed in Table 6. Table 6.
Ioctl Command Descriptions Command
Argument
Description
ICP_HSSVOICEDRV_PORT_UP
The parameter is a pointer to a data structure of type icp_hssdrv_portup_s containing port number, the predefined mezzanine card configuration and loopback mode
ioctl command to bring up a HSS port
ICP_HSSVOICEDRV_PORT_DOWN
The parameter is an integer indicating the port number to bring down (0-3)
ioctl command to bring the port down, i.e. disable services on the port
ICP_HSSVOICEDRV_CHAN_ADD
The parameter is a pointer to data structure of type icp_hssdrv_channeladd_s
ioctl command to add and configure a voice channel - up to 64 channels can be associated to a single file descriptor
ICP_HSSVOICEDRV_CHAN_REMOVE
The parameter is the channel, specified by the channelId
ioctl command to remove (delete) the channel
ICP_HSSVOICEDRV_CHAN_UP
The parameter is the channel, specified by the channelId
ioctl command to enable data flow on a channel
ICP_HSSVOICEDRV_CHAN_DOWN
The parameter is the channel, specified by the channelId
ioctl command to disable data flow for a channel
ICP_HSSVOICEDRV_CHAN_BYPASS_ENABLE
The parameter is a pointer to data structure of type icp_hssvoicedrv_channel_bypass_s
ioctl command to create a channel bypass between two channels
ICP_HSSVOICEDRV_CHAN_BYPASS_DISABLE
The parameter is a pointer to data structure of type icp_hssvoicedrv_channel_bypass_s
ioctl command to remove a channel bypass between two channels
ICP_HSSVOICEDRV_STATS
None
ioctl command to display HSS Voice Driver stats, such as number of clients, channels and their status
For more information in the data structures used in these ioctls, please refer to [DRIVERS_API_REF].
5.10.3.1
Predefined Configurations In order to simplify the setup of a HSS port, the HSS Voice driver provides a set of predefined HSS port configurations. Each predefined configuration contains a combination of HSS port settings. The predefined configuration to be applied to a port can be selected when calling the ioctl() method with the ICP_HSSVOICEDRV_PORT_UP command. At present the following predefined configurations are listed in Table 7. These configurations can easily be modified in the source code at build time. Additional predefined configurations can be added, or existing configurations can be modified at build time.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 37
IP Telephony Software—HSS Voice Driver Details
Table 7.
Predefined HSS Port Configurations Configuration Number
Description
ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Framer Mezzanine card in E1 mode.
ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Framer Mezzanine card in T1 mode.
ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Framer Mezzanine card in H-MVIP mode.
ICP_HSSDRV_PORT_ANALOG_VOICE_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Analog Voice Mezzanine card.
5.11
Data Path
5.11.1
Packet Formats When reading/writing voice data to/from the driver with calls to read() and write(), the user buffer allows for voice samples of several voice channels to be read/written at the same time. In order to facilitate this, each set of voice samples has the associated channel number and the length embedded with it. The payload length is variable depending on the CODEC chosen. An example of a G711 payload format is shown in Figure 8, where the numbers indicate bytes used per section.
Figure 8.
Read / Write Data Format - One G.711 Channel 2
2
8 0
L e n
C h a n
G .7 1 1
P a y lo a d
Voice samples for multiple voice channels can be read simultaneously, and can be written contiguously into the client supplied buffer. Similarly for transmitting, the voice sample can be written contiguously by the client. The format of the buffer passed for a read for two channels, one G711 and one Linear PCM, can be seen in Figure 9, where the numbers indicate bytes used per section. Figure 9.
Read / Write Data Format - One G.711 Channel and One Linear PCM Channel 2
2
80
2
2
160
Len
C han
G .7 1 1 P a y lo a d
Len
C han
L in e a r P C M P a y lo a d
• len (16 bits) is the length in bytes of the voice packet payload. The voice packet payload is a multiple of 4 bytes. 16 bits is used for future-proofing. Additionally, when combined with the 16-bit channelId, len is always 32-bit aligned. • channelId (16 bit) is the channel ID of the voice packet payload. Passing len and channelId in the user buffer for each packet can simplify the client code - it doesn't have to remember fixed offsets for each packet in a buffer. • payload (len bytes) is the voice packet payload for the channelId.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 38
May 2009 Order Number: 320415-003US
HSS Voice Driver Details—IP Telephony Software
This buffer format allows for a flexible interface that single or multiple voice packets transferred in both blocking and non-blocking modes.
5.11.2
Poll The poll function is the driver interface method called when the equivalent libc poll() function is called from the client in user space. When using it with the HSS Voice Driver device file, the poll() function is used to find out whether the blocking read() will block or return with data immediately. The prototype for the poll function is as follows:
int poll(struct pollfd fds[], nfds_t nfds, int timeout);
It can be used by clients that wish to poll() simultaneously on several legs of a call, to know when data is available on one of the legs. The poll() function can only be used when the HSS Voice Driver device file has been opened in blocking mode.
5.11.3
Tx The write function is the driver interface method called whenever the equivalent libc write() function is called from the client in user space. The client can use write in order to send data via /dev/hss-voice, once the character device file has been successfully opened. Also note that no implementations are provided for writev() (I/O vector write) nor for asynchronous writes (via libaio). The prototype for the write function is as follows:
ssize_t write(struct file *file, const char __user *src, size_t count, loff_t *offset);
where ssize_t is a standard Linux* type. The returned length indicates the number of bytes written (including the length and channelId fields). The write() method allows clients the options to: • Submit a single packet for a single channel • Submit multiple packets for a single channel • Submit multiple packets for multiple channels
5.11.4
Rx The read function is the driver interface method called whenever the equivalent libc read() function is called from the client in user space. The client can use read in order to retrieve data from /dev/hss-voice, once the character device file has been successfully opened. Also note that no implementations are provided for readv() (I/O vector read) nor for asynchronous reads (via libaio). The prototype for the read function is as follows:
ssize_t read(struct file *file, char __user *dest, size_t count, loff_t *offset); where ssize_t is a standard Linux* type.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 39
IP Telephony Software—HSS Voice Driver Details
By default the driver operates in blocking mode. Calls to read() blocks until received packets are available for all registered channels. However, if the read() has blocked for two seconds it is assumed an rx datapath error has occurred and the read() will return an error. When configured for non blocking mode (O_NONBLOCK), calls to read() immediately return available received packets (one packet per registered channel). If there are no packets available it returns 0. The read() method returns multiple packets together in the user buffer, one for each registered channel for the file descriptor. The client can choose to open() multiple file descriptors and register a single channel per descriptor, thus receiving a single packet per read() on a descriptor. Alternatively the client can register multiple channels for multiple descriptors, thus receiving multiple packets per read() on a particular descriptor. The voicePacketSize and number of timeslots in the tsMap configured at channel setup defines the read() block rate for a channel. e.g. 1 timeslot for a voicePacketSize of 80 bytes for an E1 @ 2.048MHz corresponds to a packet read() every 10msec. If the client configures multiple channels for the same file descriptor, calls to read() for that file descriptor will block until data is available for the slowest channel. The client is recommended to keep the same voice packet rate for multiple channels processed in a single read().
5.11.5
Single Vs. Multiple Channels per File Descriptor Every call to the open() function creates a new file descriptor for the client. If the client has n channels, where n > 1, it may choose to have one call to open() and access these channels on a single file descriptor, or make several calls to open() and access the n channels on different file descriptors. Accessing all n channels on a single file descriptor may suit a single thread client, whereas accessing an individual channel on n file descriptors may suit a multi-threaded client. The example in Figure 10 show how single and multiple threaded clients might operate two channels. The single threaded client opens a single file descriptor (fd1), adds two channels (0,1) to it. The client accesses these channels together using read() and write() through the fd1. The multi-threaded client opens two file descriptors (fd2,fd3), and adds one channel to each. It accesses each channel separately through read() and write() using fd2 or fd3.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 40
May 2009 Order Number: 320415-003US
HSS Voice Driver Details—IP Telephony Software
Figure 10.
Read and Write - Single Vs. Multiple Channels per File Descriptor
Single threaded client
Multi threaded client
open(fd1,”/dev/hss-voice”) ... ioctl(fd1,ICP_HSSVOICEDRV_CHAN_ADD,0) ioctl(fd1,ICP_HSSVOICEDRV_CHAN_UP,0) ioctl(fd1,ICP_HSSVOICEDRV_CHAN_ADD,1) ioctl(fd1,ICP_HSSVOICEDRV_CHAN_UP,1)
open(fd2,”/dev/hss-voice”) ... ioctl(fd2,ICP_HSSVOICEDRV_CHAN_ADD,0) ioctl(fd2,ICP_HSSVOICEDRV_CHAN_UP,0) open(fd3,”/dev/hss-voice”) ... ioctl(fd3,ICP_HSSVOICEDRV_CHAN_ADD,0) ioctl(fd3,ICP_HSSVOICEDRV_CHAN_UP,0)
Thread 1
Thread 1
read(fd1,...) … write(fd1,...)
read(fd2,...) … write(fd2,...)
Thread 2 read(fd3,...) … write(fd3,...)
Linux User Space Linux Kernel Space
HSS Voice driver
5.11.6
Overload It is possible that the client may send more data than the HSS voice channel can physically transmit. In such situations, the HSS Voice Driver write() method will return the amount of bytes written (0). The steps involved are as follows: 1. HSS Voice Driver receives voice samples for Tx via its write method from the client 2. HSS Voice Driver fails to submit the frame to the HSS I/O Access Library (Tx queue is full) 3. HSS Voice Driver returns 0 from write instead of the number of bytes transmitted 4. The client may continue to try and transmit data. They will continue to get a 0 return from write() until the overload situation has cleared.
5.12
Resource Usage The HSS Voice driver is required to manage the OSAL and kernel space buffers. It replenishes the HSS I/O Access Library RxFree Queue, and provides buffers for passing to the HSS I/O Access Library Tx queues. The maximum amount of buffers that the driver will replenish to the RxFree Queue is configurable at build time.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 41
IP Telephony Software—HSS Voice Driver Details
Performance tuning may be used to identify the best combination of memory usage and performance. Use the following data to compute memory usage and performance tradeoffs: • For the maximum size of the RxFree queue, see Section 11.15.1, “Queue Sizes” on page 98 in Chapter 11.0, “HSS I/O Access Library Details.” • Each OSAL buffer will be 96 bytes. • Each kernel space buffer will be 320 bytes. Depending on the codec and rate, it is possible that not all of the buffer will be used. • There is a maximum of 128 Tx queues in the HSS I/O Access Library. For the maximum size of the Tx queues, see Section 11.15.1, “Queue Sizes” on page 98 in Chapter 11.0, “HSS I/O Access Library Details.”
5.13
Operating System-Specific Issues The HSS Voice Driver is a Linux*-only device driver.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 42
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
6.0
HSS Data Driver Details
6.1
What’s New in this Chapter Section 6.9: clarified explanation of “multiple clients”
6.2
Overview The HSS Data Driver is a kernel level driver. It conforms to a Linux* serial device driver model. It initializes and manages Point-to-Point Protocol (PPP) data channel communication with the HSS I/O Access Library. The HSS Data Driver supports as many HDLC channels as the HSS I/O access library will allow to be allocated (maximum is 128).
6.3
Overview of Linux PPP Subsystem The HSS Data Driver is responsible for transmitting and receiving packetized data between the HSS I/O Access Library and the Linux PPP subsystem. When using PPP links, the Linux kernel sends and receives data on PPP interfaces (called PPP units), which is passed to the PPP subsystem for PPP processing (encapsulation/decapsulation, header compression) and further passed to devicedependent drivers called PPP channels. A PPP channel is an abstraction of a PPP-capable device. PPP channels are connected to the PPP subsystem using a simple interface for Tx, Rx, ioctl, and Tx throttle. A PPP channel driver is used to implement this PPP channel functionality. Each type of PPP-capable hardware interface has its own implementation of a PPP channel. An overview of this architecture is shown in Figure 11. The design of this driver covers the Linux 2.6 kernel family exclusively. The reader should assume the driver is not backward-compatible with 2.4 kernels.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 43
IP Telephony Software—HSS Data Driver Details
Figure 11.
Linux PPP Architecture
kernel
PPP unit
PPP subsystem
/dev/ppp
PPP channel driver
kernel space
pppd
Client
user space
hardware Hardware device
Linux kernels in the 2.6 family provide a generic PPP channel driver usable for hardware interfaces capable of HDLC transmission. This channel driver is the synchronous PPP driver, and acts as a PPP channel, handling channel registration and providing the interface required by the PPP subsystem, at the same time functioning as a serial line discipline which can be attached to a serial interface. The serial interface must be capable of HDLC frame Tx and Rx. Creation of PPP units, PPP channel registration and channel/unit attachment is triggered by pppd (the Linux PPP daemon) from user-space, using ioctl() calls on /dev/ ppp. The Linux PPP subsystem is the registered character device driver for /dev/ppp and will intercept and handle such ioctl() calls. pppd is also responsible for performing PPP link negotiation and authentication (using PAP, CHAP etc). The details of this procedure is outside the scope of this document. In order to reuse as much as possible from the Linux PPP implementation, the driver is implemented as a serial (TTY) driver, using the synchronous PPP serial line discipline for HDLC channels provided by the Linux PPP subsystem. The attachment of this line discipline to the serial HSS Data Driver is done by pppd, once this is started with the HSS data TTY device file (e.g. /dev/hss-data0) and the “sync” command-line options. This attachment, done by pppd by placing the serial device into sync-PPP line discipline, also triggers the creation of a PPP channel and its registration with the PPP subsystem. At the same time, pppd creates a PPP unit (a network interface unit) used by the kernel to send and receive network data. The newly created PPP channel is then attached to the PPP unit by pppd using ioctl() commands on /dev/ppp. This process is transparent to the HSS serial driver, however following this initialization the driver will have an associated synchronous PPP serial line discipline which will be invoked for packet Rx. Transmit operations are originated by the kernel, transmitted via the PPP unit to the PPP subsystem, passed to the sync-PPP module which acts as a serial line discipline and calls the write method implemented by the TTY serial driver (the HSS Data Driver).
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 44
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
6.4
Functional Description The HSS Data Driver performs the following activities: • Registers itself, upon initialization, as a TTY driver, providing a tty_operations structure to the Linux kernel; this structure contains function pointers called by the Linux kernel for handling serial operations; the data driver registers write, ioctl, open and release operation, called by the HDLC synchronous PPP serial line discipline during Tx, as well as during channel configuration and service enabling or disabling • Registers an Rx callback with HSS I/O Access Library in order to receive data • Replenishes the HSS I/O Access Library with free buffers for the HSS RxFree Queue • Converts buffers from char * format to OSAL format during Tx and the reverse direction for Rx
6.5
HSS Data Driver and Related PPP Components Figure 12 shows an architecture overview of where the HSS Data Driver sits with respect to the Linux PPP subsystem on EP80579 IP Telephony software.
Figure 12.
EP80579 IP Telephony software HSS PPP Architecture Overview
kernel
PPP unit
PPP subsystem
PPP Synchronous TTY Line Discipline
HSS data driver
/dev/ppp
pppd
/dev/hss-data
client
HSS I/O Acc kernel space
user space TDM I/O Programmable I/O unit
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 45
IP Telephony Software—HSS Data Driver Details
The component covered by this design document is the HSS Data Driver. It is a serial synchronous TTY HDLC driver. Related components are displayed in a light grey background (for components developed as part of EP80579 IP Telephony software) and dark grey background (for components reused from standard Linux distributions based on the 2.6 kernel family).
6.6
Dependencies The HSS Data Driver depends on the following external components, shown in Figure 13: • HSS I/O Access Library • OSAL (required for the buffer format) • Linux PPP subsystem (requires Linux kernel compiled with PPP support, including the synchronous TTY discipline) • Linux PPPD (it is needed to manage the negotiation to establish the PPP connection)
Figure 13.
HSS Data Driver Dependencies
PPP Daemon PP
user space
Linux PPP subsystem
p
HSS Data Driver
HSS I/O Access Library
OSAL kernel space hardware TDM interface
6.7
Memory Buffer Management The HSS Data Driver uses buffers large enough for holding PPP-encapsulated IP frames. The sizes of the MTU and MRU have to be the same; they are configurable both in the PPPD command line call and by calling the ifconfig command. In both cases, the user must set both MRU and MTU to be equal to the value used in the #define of DEFAULT_MTU_MRU in the HSS Data Driver source file. The HSS Data Driver does not support chaining, as sending buffers to a serial line discipline is done using char * buffers (hence no chaining).
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 46
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
No data alignment is necessary in packets handled between the HSS Data Driver and its associated line discipline, as the synchronous PPP driver performs all the necessary alignments required by the PPP subsystem.
6.7.1
Tx Memory Management Tx requires buffers in OSAL format (as specified by the HSS I/O Access Library interface), while the Linux kernel provides buffers in char * format. To facilitate the conversion, the HSS Data Driver allocates an array of OSAL buffers with pre-allocated payload areas of size max_tx_unit into a ‘backlog’ buffer array. Figure 14 shows Tx memory buffer management.
Figure 14.
Tx Memory Buffer Management
1. Linux PPP subsystem calls write() HSS Data Driver Interface Linux PPP Subsystem
2. Use the file descriptor in the write() call to calculate which HSS I/O Access Library channel this data is to be transmitted on. 3. Call to HSS I/O Access Library to retrieve any TxDone buffers. 4. If no TxDone buffer is retrieved, take a backlog OSAL buffer from the backlog buffer array. If no backlog buffer is available, malloc() a new OSAL buffer and data buffer of size max_tx_unit, then associate the data buffer with the new OSAL buffer.
OSAL Buffer
ptr
Char * buffer
5. memcpy() the char * buffer into the OSAL buffer data area.
6. Transmit OSAL buffer to HSS I/O Access Library.
7. The write() method returns.
HSS I/O Access Library Interface
6.7.2
Rx Memory Management At initialization time, the HSS Data Driver allocates a set of OSAL buffers, allocates data buffers, attaches each OSAL buffer to a data buffer, and replenishes the HSS I/O Access Library RxFree queue, until it is full. Figure 15 shows the initial Rx replenishment.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 47
IP Telephony Software—HSS Data Driver Details
Figure 15.
Initial Rx Replenishment
Linux Kernel Space 1. Allocate OSAL Buffer
OSAL Buffer
4. Replenish the OSAL Buffer to HSS I/O Access Library. This will be placed in the Rx Free Queue.
2.Allocate data buffer
ptr
Char * buffer
3. Chain char * buffer to be the Data in an OSAL Buffer
5. Repeat until RxFree Queue is full Or max number buffers available are used HSS I/O Access Library Interface
When HSS Data Driver receives an OSAL buffer with data from the HSS I/O Access Library and the data pointer of a buffer has been transmitted to the synchronous PPP line discipline during Rx, the data is copied for PPP processing by the synchronous PPP driver. The OSAL and data buffers are reused and attached to the OSAL buffer. This is then replenished back to the HSS I/O Access Library RxFree queue. Figure 16 shows Rx Memory management. Figure 16.
Rx Memory Buffer Management
Linux PPP TTY Synchronous Line Discipline HSS Data Driver Interface
1. Wai t f or r x cal l back
3. The char * buffer is passed to the TTY Synchronous line discipline via the receive_buf() method call. 4. When the r ecei ve_buf () method returns, the char * buffer is deallocated.
OSAL Buffer
2. Call to HSS I/O Access Library receive in task context returns an OSAL buffer with associated data buffer for the channel if available
ptr
Char * buffer
5. When t he recei ve_buf( ) method returns replenish the OSAL buffer back to HSS I/O Access Library. This will be placed in the Rx Free Queue.
HSS I/O Access Library Interface
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 48
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
6.8
Callback / Polled Mode The driver is run in callback mode for processing of Rx. Tx is always executed from the context of the caller, and TxDone replenishment is also done during transmission of data. The HSS I/O Access Library is connected to the interrupt source by the TDM Setup Driver. HSS I/O Access Library calls the HSS Data Driver Rx callback from thread context. This callback uses the HSS I/O Access Library to retrieve data and sends it to the Linux PPP interface.
6.9
Multiple Clients There is a single instance of the HSS Data Driver. It supports multiple clients and multiple channels per client. (In one typical scenario, there are two clients using a single channel: user code to open/close the file descriptor and to enable/disable the channel, and the PPP Daemon to transmit and receive data on that channel independently.)
6.10
Channel Numbers As there is intended to be one channel per file descriptor, the use of channel numbers are of limited value. However they are used to give a consistent configuration look and feel across the HSS Voice and Data drivers.
6.11
Robbed Bit Robbed Bit signalling can be enabled or disabled when a channel is added. The robbed bit value (to be overwritten when signalling is inserted) and the location of the robbed bit are set through the HSS Data Driver interface.
6.12
Control Path
6.12.1
Client Initialization This section describes the functionality implemented by the initialization section of the HSS Data Driver. The initialization consists of the following steps: 1. Loading the module using insmod or modprobe triggers the HSS Data Driver initialization function: a.
allocates the internal OSAL buffer pool for HDLC Rx
b.
registers itself as a TTY driver using tty_register_driver, providing a function pointer for the write method, used for Tx, an ioctl method, used for channel attachment, as well as open and release methods for tracking channel usage; the Tx function is initially disabled internally (it will return –ENODEV), as no HSS channel is connected immediately after initialization
c.
provides the major and minor numbers to be used for the devices.
d.
As soon as the init module calls the tty_register_driver function, the driver registers each device according to major and minor numbers. After insmod is called, all 128 serial devices will be found in /dev/ directory called as hss-dataN, where N goes from 0 to 127.
2. Creating the serial device file and configuring the HSS Port and a channel: a.
user calls the HSS Data Driver to configure the HSS port
b.
user calls the HSS Data Driver to configure an HDLC channel, passing in the port number, timeslot mapping, and some HSS channel options
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 49
IP Telephony Software—HSS Data Driver Details
c.
user enables the HDLC channel
d.
HSS Data Driver connects the Rx callback from the HSS I/O Access Library on the relevant channel
3. User starts the Linux PPP daemon, pppd, using the serial device /dev/hss-dataN, and should specify, at least, the “sync”, “updetach”, “mru” and “mtu” options: a.
pppd attaches the SYNC_PPP serial line discipline to the HSS Data Driver
b.
the synchronous PPP module registers itself as a PPP channel with the Linux PPP subsystem once /dev/hss-dataN is opened
c.
pppd detaches from the controlling terminal when the ppp connection is established - allowing pppd to be brought down later without other HSS Data Driver clients having their line discipline/HSS Data Driver association affected
d.
The Maximum Receive Unit “mru” and Maximum Transmit Unit “mtu” settings should match the max_rx_unit and max_tx_unit settings used in the HSS Data Driver source code (icp_hssdatadrv.c)
Following (3) the system is ready to perform Rx and Tx. It is assumed that detailed pppd configuration (such as authentication services using PAP or CHAP) is persistent and has been provided by the user. Further configuration options for pppd are outside the scope of this document and they can be found using the pppd manpage distributed with most Linux systems.
6.12.2
Open The open function is the driver interface method called whenever the equivalent libc open() function is called with a /dev/hss-dataN file. The client opens the HSS Data Driver character device driver file (/dev/hss-dataN). The prototype for the open function is as follows:
int open(struct tty_struct *tty, struct file *file); On the first call to open(), a pool of OSAL buffers is allocated. Some of these are passed to the HSS I/O Access Library to use for receiving data. The remaining are used for transmitting data to the HSS I/O Access Library.
6.12.3
Close The close function is the driver interface method called whenever the /dev/hss-dataN file is no longer needed. The prototype for the release function is as follows:
int close(struct tty_struct *tty, struct file *file); On the last call to close(), the driver retrieves the buffers it has passed to HSS I/O Access Library, detaches the free data buffers, and frees the OSAL buffer pool.
6.12.4
Ioctl The ioctl function is the driver interface method called whenever the equivalent libc ioctl() function is called from the client in user space. The client can use ioctl in order to configure the HSS Data Driver via a /dev/hss-dataN file, once the device file has been successfully opened.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 50
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
The prototype for the ioctl function is as follows: int ioctl(struct tty_struct *tty, struct file *file, unsigned int cmd, unsigned long arg);
The supported list of commands and their arguments is listed in Table 8. Table 8.
Ioctl Command Descriptions Command
Argument
Description
ICP_HSSDATADRV_PORT_UP
The parameter is a pointer to a data structure of type icp_hssdrv_portup_s containing port number, the predefined mezzanine card configuration and loopback mode
ioctl command to bring up a HSS port
ICP_HSSDATADRV_PORT_DOWN
The parameter is an integer indicating the port number to bring down (0-3).
ioctl command to bring the port down, i.e. disable services on the port.
ICP_HSSDATADRV_CHAN_ADD
The parameter is a pointer to data structure of type icp_hssdrv_channeladd_s.
ioctl command to add and configure a channel
ICP_HSSDATADRV_CHAN_REMOVE
NONE
ioctl command to remove (delete) the channel
ICP_HSSDATADRV_CHAN_UP
NONE
ioctl command to enable data flow on a channel
ICP_HSSDATADRV_CHAN_DOWN
NONE
ioctl command to disable data flow for a channel
For more information on the data structures used in these ioctls, please refer to [DRIVERS_API_REF].
6.12.4.1
Predefined Configurations In order to simplify the setup of a HSS port, the HSS Data Driver provides a set of predefined HSS port configurations. Each predefined configuration contains a combination of HSS port settings. The predefined configuration to be applied to a port can be selected when calling the ioctl() method with the ICP_HSSDATADRV_PORT_UP command. At present the following predefined configurations are listed in Table 9. These configurations can easily be modified in the source code at build time. Additional predefined configurations can be added, or existing configurations can be modified at build time.
Table 9.
Pre-Defined HSS Port Configurations Configuration Number
Description
ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Framer Mezzanine card in E1 mode.
ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG
Configuration to set up the HSS Port to connect to the Framer Mezzanine card in T1 mode.
6.13
Data Path
6.13.1
Packet Format Data is passed through the HSS Data Driver interface in char * format. No channel information is embedded in the data.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 51
IP Telephony Software—HSS Data Driver Details
6.13.2
Tx Tx is performed by a call to the write() function. The prototype for the write function is as follows:
ssize_t write(struct tty_struct *tty, const char __user *src, size_t count);
Frames for Tx originate from the Linux IP stack in sk_buff format. A frame traverses the following blocks during PPP Tx: 1. Kernel IP stack passes the frame to a PPP unit 2. PPP unit passes the frame to the PPP subsystem 3. PPP subsystem performs PPP processing (protocol headers, header compression etc) and searches the appropriate PPP channel for Tx, from the PPP channel bundle of the unit 4. PPP subsystem forwards the frame to the PPP channel – in this case the synchronous PPP driver 5. Synchronous PPP driver, as a serial line discipline for the HSS Data Driver, converts from sk_buff to char * and forwards the data pointer of the frame to its associated TTY (in this case the HSS Data Driver) via the TTY write method 6. HSS Data Driver gets an empty OSAL structure from either a TxDone buffer retrieve or the TxDone buffer pool and attaches the data pointer 7. HSS Data Driver submits the frame for Tx to the HSS I/O Access Library
6.13.3
Rx Rx is performed by way of a callback into the Linux PPP subsystem. Rx frames originate from the Programmable I/O Unit and are forwarded to the HSS I/O Access Library via HSS Rx queues. This section provides the Rx data path beginning with the HSS Data Driver Rx callback being invoked with a callback to indicate that there is Rx data available. 1. In the Rx Callback the HSS Data Driver calls the HSS I/O Access Library in order to receive the data. If successful, the HSS Data Driver passes the data pointer of the received OSAL frame to its registered line discipline via its receive_buf method (ppp_sync_input), where the frame is copied, converted from char * to sk_buff and undergoes PPP processing (unescaping etc) 2. Now that the data has been copied, the HSS driver reuses the OSAL buffer and the associated char *buffer by replenishing them into the HSS I/O Access Library RxFree queue. 3. Synchronous PPP module forwards the frame to the PPP subsystem using ppp_input, the PPP channel Rx function 4. PPP subsystem performs additional protocol processing (for example, header decompression) and forwards the frame to the PPP unit associated with the bundle the PPP channel is member of. 5. PPP unit passes the frame to the Linux IP stack.
6.13.4
Overload It is possible for the Linux kernel to send more data than the HSS HDLC channel can physically transmit. In such situations, the Linux PPP subsystem allows PPP channels to throttle Tx. This is done in the following manner:
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 52
May 2009 Order Number: 320415-003US
HSS Data Driver Details—IP Telephony Software
1. HSS Data Driver receives a new frame for Tx via its write method from the synchronous PPP line discipline 2. HSS Data Driver fails to submit the frame to the HSS I/O Access Library (Tx queue is full) 3. HSS Data Driver returns 0 from write instead of the number of bytes transmitted 4. Synchronous PPP driver recognizes that Tx is blocked and returns a non-success condition from it start_xmit PPP channel function (which is ppp_sync_send) 5. PPP subsystem blocks Tx on the PPP channel 6. HSS Data Driver periodically retries to send the frame When the HSS Data Driver has successfully submitted the frame for transmission, the HSS Data Driver wakes up PPP Tx by calling the write_wakeup of its associated line discipline. The registered write_wakeup function is the ppp_sync_wakeup in the synchronous PPP driver, and this will perform a ppp_output_wakeup on the PPP channel, which notifies the PPP subsystem that Tx is available.
6.13.5
Enabling and Disabling PPP The PPP service is available as long as the HDLC channel that is associated with a certain serial device is enabled. The kernel is not aware of the status of the channel associated with a certain device; it does not know if there is any channel associated with a certain device or not. The kernel itself considers all 128 serial devices as always available. It is the user’s responsibility to associate a physical channel with the desired device and to enable it. All the devices are unregistered and removed only when the HSS Data Driver kernel module is removed.
6.13.6
PPP Service Termination The user can terminate the PPP data service by removing the HSS Data Driver module. Prior to this, however, the user must discontinue the pppd session, which removes the PPP unit using the HSS interface, as well as closes all the open /dev/hss-dataN files. Note that the kernel automatically tracks usage of TTY devices, hence the module is not removable until all its associated /dev/hss-dataN device files have been closed. The error message of rmmod reports “module in use” if not all the device files have been closed. Upon unloading, the HSS Data Driver module_exit function is called, which disables the HSS I/O Access Library data service, retrieves all the data buffers and de-allocates the OSAL buffer pool used for Rx replenish. Since channel disconnection is done during specific disabling of /dev/hss-data channels, which takes place when the device files are closed, no additional cleanup operations are required here.
6.14
Resource Usage The HSS Data driver is required to manage the OSAL buffers and data buffers for receive. It replenishes the HSS I/O Access Library RxFree Queue, with OSAL buffers and attached data buffers. It also provides OSAL buffers to which it attaches the data buffer for transmission to the HSS I/O access Library Tx queues. The amount of buffers it provides is configurable at build time. Performance tuning may be used to identify the optimal trade off between memory usage and performance. Use the following data to compute memory usage and performance tradeoffs: • Each OSAL buffer will be 96 bytes.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 53
IP Telephony Software—HSS Data Driver Details
• The maximum size of each associated data buffer will be equal to the #define of DEFAULT_MTU_MRU in the HSS Data Driver source file. • The maximum size of the RxFree queue is 2048 buffers; see Section 11.15.1, “Queue Sizes” on page 98 in Chapter 11.0, “HSS I/O Access Library Details.” • There is a maximum number of 128 Tx queues in the HSS I/O Access Library. For the maximum size of the Tx queues, see Section 11.15.1, “Queue Sizes” on page 98 in Chapter 11.0, “HSS I/O Access Library Details.”
6.15
Operating System-Specific Issues The HSS Data Driver is a Linux*-only device driver.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 54
May 2009 Order Number: 320415-003US
Analog FXO/FXS Driver Details—IP Telephony Software
7.0
Analog FXO/FXS Driver Details
7.1
What’s New in this Chapter Table 10 on page 59: added new ioctls
7.2
Overview The Analog FXO/FXS Driver is a Linux* device driver. It presents a Linux user space interface. It is not a generic driver, it is a reference driver for the Intel® EPAVM80579 Analog Voice Mezzanine Card. The Analog FXO/FXS Driver is used to initialize, configure and manage the FXO/FXS devices on a development board mezzanine card. It presents an interface that allows the client to send commands to the FXO/FXS devices, for example, ring phone to a SLIC/CODEC. It also provides a mechanism to report device events to the client, for example, phone gone off hook from a SLIC/CODEC. To communicate with the SPI interface on the FXO/FXS devices, the Analog FXO/FXS Driver uses the SSP I/O Access Library. It operates the SSP I/O Unit in SPI mode. All communication is done via the SSP I/O Access API. More information on the SSP I/O Access Library can be found in Section 13.0. Figure 17 shows that the Analog FXO/FXS Driver is used in the control plane only. PCM data is not transmitted to the SLIC/CODEC or the DAA via this device driver. PCM data communication is the responsibility of the HSS Drivers and HSS I/O Access Library.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 55
IP Telephony Software—Analog FXO/FXS Driver Details
Figure 17.
Analog FXO/FXS Driver Overview
IA Client
User Space Kernel Space
Analog FXS/FXO Driver
OSAL
I/O Access Libraries
HSS
SPI Interface = Control Channel PCM Inteface = Data Channel
SSP
SPI Interface
PCM Interface
SLIC/CODEC / DAA
7.3
Functional Description The Analog FXO/FXS provides the following services: • Conform to a standard character device driver interface • Register itself upon initialization as a character device driver, providing typical character device operations • Initialize the analog slot of the board containing the FXO/FXS devices • Initialize the SPI Interface for communication with the FXO/FXS devices • Initialize the FXO/FXS devices • Allow configuration of the FXO/FXS devices PCM formats and timeslots
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 56
May 2009 Order Number: 320415-003US
Analog FXO/FXS Driver Details—IP Telephony Software
• Allow generic FXO/FXS commands to be passed to the FXO/FXS devices • Make available events from the FXO/FXS device to the client • Provide transportation of chip specific messages
7.4
Dependencies The Analog FXO/FXS Device Driver has dependencies on: • Linux kernel - is used for registering as a character device driver and other OS services. • SSP I/O Access Library - is used to send data to the SSP I/O Unit.
Figure 18.
Analog FXO/FXS Driver Dependencies
Client
user space kernel space
Linux kernel
Analog FXS/FXO Driver
SSP I/O Access Library
7.5
Memory Buffer Management The user space client is informed about device events by virtue of calling a blocking read() that waits for an event to occur before returning, or a non-blocking read() that returns immediately with an event if available. The Analog FXO/FXS Driver is required to allocate memory to be used for buffering of FXO/FXS device events. In both blocking and non-blocking modes, this buffering is necessary if the client is not currently calling the read() method when an event occurs. The events for a device are buffered internally in a circular list. As each Analog Voice card may have a different client, a circular list is created for each Analog Voice card device that is initialized. There is one buffer per file descriptor / client.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 57
IP Telephony Software—Analog FXO/FXS Driver Details
In the case of overflow, the oldest events are discarded.
7.6
Multiple Clients There is a single instance of the Analog FXO/FXS Driver. It may have multiple clients. However, each individual Analog Voice card has a maximum of one client. This is necessary as configuration and event reporting is on a per Analog Voice card basis. The mechanism for ensuring that there is a single client per Analog Voice card is as follows. When a client opens the /dev/analog-fxo-fxs device file, it is passed a unique file descriptor. When the ioctl() method is called to initialize the Analog Voice card, the Analog FXO/FXS Driver creates an association between the file descriptor and the Analog Voice card. Only the client using that file descriptor is allowed to configure or receive events for that Analog Voice card.
7.7
Blocking / Non-Blocking Mode The client may choose to have Analog FXO/FXS device events reported to it in a blocking or non-blocking mode. Blocking Callback mode is default and is selected by opening the /dev/analog-fxo-fxs device file without the O_NONBLOCK flag. This makes the read() blocking and a call to read() will return when an device event occurs. The return from read() effectively acts as a callback for a device event. Blocking mode may be more beneficial for a multithreaded client. Non-blocking mode is selected by opening the /dev/analog-fxo-fxs device file with the O_NONBLOCK flag. This makes read() non-blocking and a call to read() will return immediately with a device event if there is one that has not been already reported or alternatively without an event. Non-Blocking mode may be more beneficial for a singlethreaded client.
7.8
Control Path
7.8.1
Open The open function is the driver interface method called whenever the equivalent libc open() function is called from the client in user space. The client opens the Analog FXO/ FXS Driver character device driver file (/dev/analog-fxo-fxs). The prototype for the open function is as follows:
int open(struct inode *inode, struct file *file); The open() flags are used to set whether the read() is to be in blocking or non-blocking mode.
7.8.2
Release The release function is the driver interface method called whenever the equivalent libc close() function is called from the client in user space. The client must close the Analog FXO/FXS Driver character device driver file (/dev/analog-fxo-fxs) on exit. The prototype for the release function is as follows:
int release(struct inode *inode, struct file *file);
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 58
May 2009 Order Number: 320415-003US
Analog FXO/FXS Driver Details—IP Telephony Software
The release function: • Unbinds interrupts for the device events • De-allocates the event queue (after unbinding the interrupts)
7.8.3
Ioctl The ioctl function is the driver interface method called whenever the equivalent libc ioctl() function is called from the client in user space. The client can use ioctl in order to configure the Analog FXO/FXS Driver via /dev/analog-fxo-fxs, once the character device file has been successfully opened. The prototype for the ioctl function is as follows:
int ioctl(struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg);
Ioctl is used for initializing, configuring and event reporting for FXO/FXS lines. The supported commands are listed in Table 10. Table 10.
Analog FXO/FXS Driver Linux User Space Interface Ioctl Commands (Sheet 1 of 2)
Command
Argument
Send to FXO/ FXS device
Description
ICP_ANALOGDRV_DEVICE_INFO
int (in) indicates the line to query. The return value indicates the device on which that line is, where 0=Si3050, 1=Si3210, 2=Si3216, 3=3220.
FXO/ FXS
This command is used to find out the make and manufacturer of the device that is specified in the argument.
ICP_ANALOGDRV_DEVICE_PRESENT
int (in) indicates the line to query. The return value indicates that there is normal communication with the device the line is on (0) or there is an error in communicating with the device (1).
FXO/ FXS
This command is used to verify that normal communications with the device is possible.
ICP_ANALOGDRV_HOOKSTATE_GET
int (in) indicates the line to get the state for. The return value indicates the hook state, either on_hook (0) or off hook (1).
FXS
This command get the current state of the hook on the FXS device.
ICP_ANALOGDRV_INIT
icp_analogdrv_init_s (in). slot is used to indicate the slot on the development board to be initialized. geo_config indicates the predefined configuration.
FXO/ FXS
This command is used to initialize the slot, event queuing, interrupts and set the geo configuration.
ICP_ANALOGDRV_LOOPBACK_DISABLE
int (in) indicates the line to disable loopback on.
FXO/ FXS
This command is used to disable loopback mode on a line.
ICP_ANALOGDRV_LOOPBACK_ENABLE
int (in) indicates the line to enable loopback on.
FXO/ FXS
This command is used to enable loopback mode on a line.
ICP_ANALOGDRV_LOOPBACK_GET
int (in) indicates the line query for its current loopback mode. The return value indicates loopback mode disabled (0) or enabled (1).
FXO/ FXS
This command is used to get the current loopback status of a line.
ICP_ANALOGDRV_OFF_HOOK
int (in) indicates the line to send the offhook message to.
FXO
This command indicates to the FXO device that the FXS device has gone off hook.
ICP_ANALOGDRV_ON_HOOK
int (in) indicates the line to send the on hook message to.
FXO
This command indicates to the FXO device that the FXS device has gone on hook.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 59
IP Telephony Software—Analog FXO/FXS Driver Details
Table 10.
Analog FXO/FXS Driver Linux User Space Interface Ioctl Commands (Sheet 2 of 2)
Command
Argument
Send to FXO/ FXS device
Description
ICP_ANALOGDRV_PCM_CONFIG_GET
icp_analogdrv_pcm_config_s. The lined (in) indicates the line to get the PCM configuration for. The other structure members (out) are filled by the Analog Driver.
FXO/ FXS
This command gets the current PCM configuration of the selected device.
ICP_ANALOGDRV_PCM_CONFIG_SET
icp_analogdrv_pcm_config_s (in). All members of this configuration structure are filled in by the client.
FXO/ FXS
This command configures the PCM characteristics for a FXO/FXS line.
ICP_ANALOGDRV_READ_REG
icp_analogdrv_gen_reg_t. reg (in) indicates the register number that should be read. data (out) gives the data that the register contains.
FXO/ FXS
This is used to read a device register.
ICP_ANALOGDRV_RING_OFF
int (in) indicates the line disable ringing on.
FXS
This command will cause the FXS device to stop ringing.
ICP_ANALOGDRV_RING_ON
int (in) indicates the line enable ringing on.
FXS
This command will cause the FXS device to start ringing.
ICP_ANALOGDRV_TONE_OFF
Argument- int(in)- indicates the line to stop tone transmission on.
Send to - FXS
Description - This command is used to stop the transmission of a tone on a particular FXS line
ICP_ANALOGDRV_TONE_ON
Argument- icp_analogdrv_tone_s(in)indicates the tone, direction and line to start transmission on.
Send to - FXS
Description - This command is used to start the transmission of a tone on a particular FXS line
ICP_ANALOGDRV_WRITE_REG
icp_analogdrv_gen_reg_t (in). reg indicates the register which data should be written to. data is the data to be written.
FXO/ FXS
7.8.3.1
This is used to write to a device register.
FXO/FXS Device Initialization Initialization of the Slot and SPI communications must be performed before configuration of the FXO/FXS lines. The tasks performed during initialization are: • Initialize and configure the interrupt pins, the clock source, and reset logic used by the FXO/FXS devices on a particular slot • Initialize the FXO/FXS devices to communicate using SPI • Set the geo configuration on the lines • Allocate memory for the device event queueing
7.8.3.2
FXO/FXS Device Geographic Configuration Due to different standards per geographic location, the configuration of some device characteristics may differ: • Ringing amplitude, frequency and duration • Constant current loop feed • Ring trip/loop closure thresholds and filtering • 2-wire AC impedance and transhybrid balance Table 11 describes the predefined configurations which are set in the driver.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 60
May 2009 Order Number: 320415-003US
Analog FXO/FXS Driver Details—IP Telephony Software
Table 11.
Analog FXO/FXS Driver Linux User Space Interface Geographic Options Geographic Option
Description
US - FCC
FCC standard used in the US
EU - TBR21
TBR21 standard commonly used in the EU
Japan
Japanese call progress tone settings
These configurations can subsequently be altered dynamically by writing directly to the FXO/FXS device registers.
7.8.3.3
PCM Configuration For each FXO/FXS line, the following PCM characteristics must be configured. • PCM format - A-Law, Mu-Law, Linear • PCM width - 8 or 16 bits • PCM sampling frequency - 8 KHz or 16 KHz • PCM start offset - number of clock cycles that the PCM data starts after the frame pulse
7.8.4
Write Write is not implemented in the interface.
7.8.5
Read The read function is the driver interface method called whenever the equivalent libc read() function is called from the client in user space. The client uses read in order to retrieve data from /dev/analog-fxo-fxs, once the character device file has been successfully opened. The prototype for the read function is as follows:
ssize_t read(struct file *file, char __user *dest, size_t count, loff_t *offset); The read interface is responsible for copying a device event to the client user space memory. Blocking mode is set by using the O_BLOCK flag when opening the /dev/analog-fxo-fxs device file. In blocking mode, the read() method does not return until a device event occurs and the Analog FXO/FXS driver has copied it into the user space buffer provided by the client. The steps in a blocking read() can be seen in Figure 19.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 61
IP Telephony Software—Analog FXO/FXS Driver Details
Figure 19.
Analog FXO/FXS Driver Blocking read()
1. Blocking read() User space Kernel space
2. Check to see if any events to report to the client 3. Wait for an event. 0 1 2 3 4
4. When an event occurs copy it to the client provided user space buffer and return n bytes copied
n
Non-Blocking mode is set by using the O_NONBLOCK flag when opening the /dev/ analog-fxo-fxs device file. When non-blocking read() is called, if there is a device event to be reported to the client, the analog FXO/FXS driver copies it into the user space buffer provided by the client and returns. If there is no device event, the Analog FXO/ FXS Driver returns immediately. The steps in a non-blocking read() can be seen in Figure 20.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 62
May 2009 Order Number: 320415-003US
Analog FXO/FXS Driver Details—IP Telephony Software
Figure 20.
Analog FXO/FXS Driver Non-Blocking read()
1. Non-Blocking read()
User space Kernel space
2. Check to see if any events to report to the client 3. As no events return 0 0 1 2 3 4
n
7.8.6
Events The extensible list of event types is described in Table 12:
Table 12.
Analog FXO/FXS Driver Linux User Space Interface Events Event Type
Generated by
Event Description
ICP_ANALOGDRV_EVENT_ON_HOOK
FXS
This event indicates that the FXS device has gone on hook.
ICP_ANALOGDRV_EVENT_OFF_HOOK
FXS
This event indicates that the FXS device has gone off hook.
ICP_ANALOGDRV_EVENT_RING_ON
FXO
This event indicates that the FXO device is receiving an incoming ring signal.
ICP_ANALOGDRV_EVENT_RING_OFF
FXO
This event indicates that the FXO device has stopped receiving an incoming ring signal.
ICP_ANALOGDRV_EVENT_POL_REV
FXO
This event indicates that the polarity of the FXO device has been reversed. It is used by the far end to indicate a call termination.
Events are copied to the user buffer in the format shown in Figure 21, where: • EventType is the event • LineID is the analog line Figure 21.
Analog FXO/FXS Driver Event Format
May 2009 Order Number: 320415-003US
32-bits
32-bits
EventType
LineID
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 63
IP Telephony Software—Analog FXO/FXS Driver Details
7.9
Data Path The Analog FXO/FXS Driver does not implement a data path. This is handled by the HSS drivers.
7.10
Resource Usage The following sections detail the memory requirements of the Analog FXO/FXS Driver.
7.10.1
Memory Requirements for Event Queue Buffer Pool There is a list for each Analog Voice Card. The maximum number of Analog Voice Cards that can be added to the development board is 3. A buffer size of 32 events for each line is the maximum allowed. Each event data structure uses 2 words = 8 bytes 3 [Analog Voice cards] x 32 [events] x 8 [bytes] = 768 [bytes] Words are needed for monitoring the head and tail of each list 8 [bytes] x 3 [Analog Voice cards] = 24 [bytes] Total Memory needed = 792 [bytes]
7.11
Operating System-Specific Issues The Analog FXO/FXS Driver is a Linux* Device Driver only.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 64
May 2009 Order Number: 320415-003US
Framer Driver Details—IP Telephony Software
8.0
Framer Driver Details
8.1
What’s New in this Chapter No updates in this release.
8.2
Overview The Framer Driver is a Linux* user space device contol application. It is used to initialize, configure, and provide event monitoring for up to 12 E1/T1 interfaces provided by external framer devices. It is not a generic driver. It is a reference driver for the development board Framer mezzanine card, Intel® EPTEM80579 T1/E1 Mezzanine Card. The development board provides support for up to 12 E1/T1 external interfaces through the use of three Framer Mezzanine Modules, each containing one Framer device. The Framer Driver is not responsible for data flow between an external Framer device and the EP80579. Data path communication with the Framer device is done via the HSS drivers. Figure 22 gives an overview of where the Framer Driver fits in the overall system architecture.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 65
IP Telephony Software—Framer Driver Details
Figure 22.
Framer Driver Overview
C lie n t
E 1 /T 1 F ra m e r D r iv e r U ser S pace K e rn e l S p a c e H SS I/O A c c e s s L ib r a r y
F ra m e r In fra s tru c tu re D r iv e r
C o n tro l P a th
D a ta P a th
H o s t P o rt In te rfa c e
T D M In te rfa c e E 1 /T 1 F ra m e r D e v ic e E 1 / T 1 M e z z a n in e c a r d
8.3
Functional Description The Framer Driver performs the following activities: • Provide a means to initialize an external Framer device • Provide a means to configure an external Framer device • Provide a means for reporting Framer device events to the client • Provide a means for reporting Framer device alarms to the client
8.4
Dependencies The Framer Driver has dependencies on the following: • Linux kernel - used for OS services • EP80579 Expansion bus hardware - used for communication with the external Framer device • Framer Infrastructure Driver - used to return framer events to the framer driver and to perform hardware read and writes
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 66
May 2009 Order Number: 320415-003US
Framer Driver Details—IP Telephony Software
Figure 23.
Framer Driver Dependencies
C lie n t
F ra m e r D riv e r user space k e rn e l s p a c e
L in u x k e rn e l F ra m e r In fra s tru c tu re D riv e r
E x p a n s io n B u s H a rd w a re
8.5
Memory Buffer Management The user space client is informed of device events by virtue of calling a blocking icp_FramerDrvRead() that waits for an event to occur before returning, or a nonblocking icp_FramerDrvRead() that returns immediately with an event if available. The Framer driver is required to allocate memory to be used for buffering of Framer device events. In both blocking and non-blocking modes this buffering is necessary if the client is not currently calling the icp_FramerDrvRead() method when an event occurs. The events for a device are buffered internally in a circular list. As each Framer device may have a different client, a circular list is created for each Framer device initialized. There is one circular list per framer device. In the case of overflow, the oldest events are discarded.
8.6
Multiple Clients As previously stated, this driver exists in user space and is effectively a device control application. There is no restriction on access to the API and either a single client or multiple clients can use the API to control the framer devices. Each API takes deviceID
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 67
IP Telephony Software—Framer Driver Details
as a parameter which dictates the framer device to access. There is no protection provided against multiple clients accessing the same device. The client is responsible for ensuring that it is accessing the correct device.
8.7
Blocking / Non-Blocking Mode The client may choose to have Framer device events reported to it in a blocking or nonblocking mode. Blocking mode is selected by calling icp_FramerDrvRead() with the block parameter set to TRUE. In this mode, a call to icp_FramerDrvRead() returns when an device event occurs. The return from icp_FramerDrvRead() effectively acts as a callback for a device event. Blocking mode may be more beneficial for a multi-threaded client. Non-blocking mode is selected by calling icp_FramerDrvRead() with the block parameter set to FALSE. In this mode, a call to icp_FramerDrvRead() returns immediately with a device event (if there is one that has not been already reported) or alternatively without an event. Non-Blocking mode may be more beneficial for a singlethreaded client.
8.8
Control Path
8.8.1
Initialization The Init function initializes a framer device and allocates any memory needed. It must be called before any other framer API for that deviceId. This function: • Initializes the framer device and slot • Allocates the event queue memory
8.8.2
Uninitialization The Uninit function uninitializes all framer devices and deallocates all memory used by the driver. This function must be called before the driver can be removed from the system. This function: • Resets and uninitializes a framer device and slot • De-allocates the event queue memory
8.8.3
Configuration Functions are provided that allow the client to set and to get the current configuration of a framer device. The following options can be configured for the device: • External line type • Signaling • Encoding • Framing • Backplane mode
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 68
May 2009 Order Number: 320415-003US
Framer Driver Details—IP Telephony Software
8.8.3.1
Predefined Configurations In order to simplify the configuration of the Framer device, the Framer Driver provides a set of predefined Framer device configurations. Each predefined configuration contains a combination of the following settings: • External line type, such as E1, T1. • Signalling, such as None, CAS, CCS. • Encoding, such as AMI, B8ZS. • Framing, such as ESF, D4/SF, transparent. • Backplane mode, such as Quad MVIP. These predefined configurations are set using the configuration set API call and are easily extendable. A full list of the predefined configurations and the characteristics can be seen in Table 13.
Table 13.
Framer Driver Predefined Configurations Configuration
Characteristics
ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_SINGLE
T1, CAS (Channel Associated Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_T1_CAS_AMI_D4_SINGLE
T1, CAS (Channel Associated Signaling) signaling, AMI (Alternate Mark Inversion) Encoding, D4/SF (Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_SINGLE
T1, CCS (Common Channel Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_QUAD
T1, CAS (Channel Associated Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_QUAD
T1, CCS (Common Channel Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_SINGLE
E1, CAS (Channel Associated Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) MultiFrame Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_SINGLE
E1, CCS (Common Channel Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) MultiFrame Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_E1_CCS_AMI_BASIC_SINGLE
E1, CCS (Common Channel Signaling) signaling, AMI (Alternate Mark Inversion) Encoding, Basic Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_QUAD
E1, CAS (Channel Associated Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) MultiFrame Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_QUAD
E1, CCS (Common Channel Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) MultiFrame Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 69
IP Telephony Software—Framer Driver Details
8.8.4
Reset The client can use the reset option to clear the configuration from the framer. After a reset, the configuration set command must be called to re-configure the framer device.
8.8.5
Loopback A function is provided to allow the client to enable or disable loopback on a particular line on a device. Three types of loopback are provided: digital loopback, line loopback, and payload loopback.
8.8.5.1
Digital Loopback This is a system (local side) loopback. All data that is transmitted from the framer is looped back to the receive side of the framer.
Figure 24.
Digital Loopback T X T ip B a ckpla ne T X S ystem In te rfa ce
T X E lastic S tore
T X F ram e r
T X Jitte r A tten ua tor
TX T X R in g
D ig ita l L o o p b a c k R X T ip B a ckpla ne R X S ystem In te rfa ce
8.8.5.2
R X E la stic S tore
R X F ra m er
R X Jitter A tten ua tor
C lock & D a ta R eco ve ry
RX
R X R ing
Line Loopback This is a network (remote) loopback that exercises the minimum path through the framer. The output of the Clock and Data Recovery block is connected to the TX Jitter Attenuator Block.
Figure 25.
Line Loopback T X T ip B a ckp la ne T X S yste m In te rfa ce
T X E lastic S to re
T X F ra m er
T X Jitter A tte nua to r
TX T X R in g
L in e L o o p b a c k R X T ip B a ckp la ne R X S yste m In te rfa ce
8.8.5.3
R X E lastic S to re
R X F ra m er
R X Jitter A tte nua to r
C lock & D a ta R e co very
RX
R X R in g
Payload Loopback This is a network (remote) loopback that exercises the maximum path through the framer. The output of the RX Elastic store is connected to the input of the TX Framer Block. In this mode, the transmit and receive are not superframed aligned and any
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 70
May 2009 Order Number: 320415-003US
Framer Driver Details—IP Telephony Software
robbed-bit signaling in the receive stream will not fall in the correct frame once looped back. In addition, the transmit robbed-bit signaling will overwrite the looped back data if signal insertion is enabled. Figure 26.
Payload Loopback T X T ip B ackplane T X S ystem Inte rfa ce
T X E lastic S to re
T X F ram e r
T X Jitte r A tten uator
TX T X R in g
P a y lo a d L o o p b a c k R X T ip B ackplane R X S ystem Inte rfa ce
8.8.6
R X E lastic S to re
R X F ram e r
R X Jitter A tten uator
C lo ck & D ata R ecove ry
RX
R X R in g
Line State Two functions are provided in relation to the line state: a set and a get function. The set function enables or disables the line. The get function returns the current state of the line.
8.8.7
Register Access A register read and a write function are provided. These functions allow the client to directly access the framer device registers.
8.8.8
Line Signaling Two functions are provided that allow the client to set or query the signaling bits on a particular time slot on a line: • The set function allows the client to set the A,B,C, and D signaling bits on TX. • The get function allows the the client to read the same bits on RX.
8.8.9
Notifications The client uses a bitmask to indicate which Framer device events (e.g. Loss of signal, Loss of frame alignment) it wishes to receive notifications for using the notification set command. These notifications are passed back to the client in the form of events. See Section 8.8.11 “Events” for more details. The client can check which notifications are enabled using the notifications get command. The enabled notifications are returned in the form of a bit mask.
8.8.10
Read To retrieve framer events, the client can use the read function. The read interface is responsible for copying device events to the client. The read function only retrieves a buffer for one device at a time. The device ID is passed in as part of the read call. The events that are currently supported are listed in Table 14.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 71
IP Telephony Software—Framer Driver Details
Both blocking and non-blocking reads are supported. In blocking mode, the read function does not return until a device event occurs and the framer driver has copied it into the buffer provided by the client. The steps in a blocking read can be seen in Figure 27. Figure 27.
Framer Driver Blocking read()
1. Blocking Read Client Framer Driver
2. Check to see if any events to report to the client 3. Wait for an event. 0 1 2 3 4
4. When an event occurs copy it to the client provided buffer and return ICP_E_NO_ERROR
n
With a non-blocking read call, if there is a device event to be reported to the client, the Framer driver copies it into the buffer provided by the client and returns. If there is no device event, the Framer Driver returns immediately. The steps in a non-blocking read can be seen in Figure 28.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 72
May 2009 Order Number: 320415-003US
Framer Driver Details—IP Telephony Software
Figure 28.
Framer Driver Non-Blocking read()
1. Non-blocking Read Client Framer Driver
2. Check to see if any events to report to the client 3. As no events return ICP_E_FAIL
0 1 2 3 4
n
8.8.11
Events Device events are events generated by the Framer device. They are typically associated with a particular external E1/T1 line. A bitmask is provided for each supported event, so the client can conveniently register notification for multiple events with one call to the notifications set API. These bitmasks can also be used by the client to identify which event has occurred. A full list of the currently supported event bitmasks can be seen in Table 14.
Table 14.
Framer Driver Device Events (Sheet 1 of 2) Event
Description
ICP_FRAMERDRV_EVENT_AIS
Alarm Indicator Signal
ICP_FRAMERDRV_EVENT_COSS
Change of Signaling State
ICP_FRAMERDRV_EVENT_LOFA
Loss Of Framer Alignment
ICP_FRAMERDRV_EVENT_LOS
Loss Of Signal
ICP_FRAMERDRV_EVENT_LOSCRCMF
Loss Of CRC Multi-Frame
ICP_FRAMERDRV_EVENT_LOSMF
Loss Of Signaling Multi-Frame
ICP_FRAMERDRV_EVENT_OOF
Out Of Frame
ICP_FRAMERDRV_EVENT_PDV
Pulse Density Violation (16 consecutive zeros)
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 73
IP Telephony Software—Framer Driver Details
Table 14.
Framer Driver Device Events (Sheet 2 of 2) Event
Description
ICP_FRAMERDRV_EVENT_RED
Red Alarm. This is generated by the Framer device when an incorrect framing format is being received.
ICP_FRAMERDRV_EVENT_TS16RAI
Timeslot 16 Remote Alarm Indication
ICP_FRAMERDRV_EVENT_YEL
Yellow Alarm. This is an RAI (Remote Alarm Indication). It indicates there is a red alarm condition on the remote device.
Events will be copied to the user buffer in the format shown in Figure 29, where: • LineID is the external E1/T1 line on the Framer device • Event is a bitmask • COSS TS is a bitmask showing the time slot on which the COSS (Change of Signaling State) event occurred Figure 29.
8.9
Framer Driver Event Format
32-bits
32-bits
32-bits
LineID
Event
COSS TS
Data Path The Framer Driver does not implement a data path. This is handled by the HSS drivers.
8.10
Resource Usage The Framer Driver requires circular lists for buffering device events. An entry for an event is shown in Figure 29. Each entry will be 8 bytes in length. There is a max of 3 framer devices. Each framer device has one circular list. As there are a max of 3 external E1/T1 links on each framer device, each list size has a max of 32 entries. 32 [entries] x 12 [bytes/entry] = 384 [bytes] As there are three framer devices: 3 [circular lists] x 384 [bytes] = 1152 [bytes] Words are needed for monitoring the head and tail of each list: 8 [bytes] x 3 [circular lists]= 24 [bytes] Total Memory needed = 1176 [bytes]
8.11
Operating System-Specific Issues The Framer Driver is a Linux* Device Driver only.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 74
May 2009 Order Number: 320415-003US
SRTP Acceleration Overview—IP Telephony Software
9.0
SRTP Acceleration Overview This section describes the functional requirements of the SRTP Acceleration driver.
9.1
What’s New in this Chapter This chapter has been updated to describe the new asynchronous API of the SRTP Acceleration driver.
9.2
SRTP Sessions, Streams, and Packets The basic component and eventual cipher data (data to be encrypted) is a packet. SRTP packets are in two forms: RTP and RTCP packets. The SRTP protocol provides encrypt/ decrypt operations on both packet types. The SRTP protocol follows the structure of RTP: it makes use of Sessions and Streams. An SRTP session is similar to an RTP session. The session defines the path between two communication channels and is a container for the SRTP streams. This can be seen in Figure 30. A stream represents all the traffic flowing from one source address to one destination address. Packets can only flow in one direction in a stream. Each stream has an associated encrypt/decrypt operation, which defines the operation or policy (encrypt, decrypt, authenticate) to be performed on all packets flowing through the stream. RTP and RTCP packets do not flow in the same SRTP Acceleration Driver stream. Each session can contain several streams, each stream can be travelling in separate directions, and have separate policies. The SRTP Acceleration Driver does not keep track of SRTP Sessions. Instead the SRTP Acceleration Driver only keeps track of SRTP Streams, as explained in Section 19.4.1, “Setup Sequence” on page 146. Each stream is represented by an associated file descriptor and every operation within this stream requires a reference to this file descriptor. It is up to the SRTP application to keep track of SRTP sessions and their associated streams.
Figure 30.
SRTP Session and Stream Concept
SRTP STREAM 1
SRTP SESSION
SRTP Stream 2 SRTP Stream 3
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 75
IP Telephony Software—SRTP Acceleration Overview
9.3
Dependencies Figure 31 shows the dependencies and external interactions of the SRTP Acceleration Driver. The main function of the SRTP driver API is to transfer data from user space to kernel space, where the Cryptographic API can perform the accelerated crypto functions on the data and then transfer the data back to user space. The SRTP Acceleration Driver is dependent on the Cryptographic API, and as a result will inherit any dependencies the Cryptographic API may have.
Figure 31.
SRTP Acceleration Driver Dependencies
SRTP Application
User Space Kernel Space
SRTP Driver
Crypto API
CPM
9.4
Cryptographic API Initialization/Shutdown In the current implementation, the Cryptographic API is initialized by the Acceleration System Driver (ASD). As a result, the SRTP Acceleration driver has no responsibility for initializing or shutting down the Cryptographic API. The SRTP Acceleration driver runs a check at the start up of a new session to ensure the Cryptographic API is initialized and running. If it is not, the SRTP driver returns an error message and shuts down.
9.5
Encryption/Decryption All default mandatory to implement encrypt/decrypt operations as defined by the SRTP protocol are supported by the SRTP Acceleration Driver. The default cipher is AES ICM. The acceleration is possible as the cipher is supported by the accelerated features in the Cryptographic API. The SRTP Acceleration driver successfully initiates an accelerated encrypt/decrypt operation when a corresponding operation is initiated in
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 76
May 2009 Order Number: 320415-003US
SRTP Acceleration Overview—IP Telephony Software
the SRTP application, the net result being the encrypt/decrypt process in SRTP application is not actually used. Instead the hardware accelerated operations of the Cryptographic API are used. There is no difference to the end result; that is, an encrypt/decrypt operation in the SRTP application equates to the same operation in the Cryptographic API. All accelerated operations are invisible to the SRTP application, as if they had come from its own crypto engine.
9.6
Authentication All default mandatory to implement authentication algorithms as defined by the SRTP protocol are supported by the SRTP Acceleration Driver. The default authentication algorithm is the HMAC SHA1 algorithm. The Cryptographic API offers other algorithms that are not defined in the SRTP protocol. The Cryptographic API also offers Hash only algorithms; this is not allowed by the SRTP protocol, which requires authentication on all Hash algorithms. For these reasons, only the default HMAC SHA1 algorithm is supported by the SRTP driver at this time. This is supported by the SRTP Driver in a manner that is invisible to the current operation of the SRTP application. The implementation accelerates the authentication algorithm, but also allows the implementation of the other authenticating algorithms supported by the SRTP application, and not by the Cryptographic API. The SRTP Acceleration driver does not affect the operation of the SRTP application, only the supported HMAC SHA1 algorithm.
9.7
Key/Random Number Generation Key generation is basically a random number generation function. The result is a random number that can be used as a cryptographic key. The key generation function is implemented the same as the encryption function. That is, it is completely invisible to the SRTP application. The SRTP Acceleration driver calls the Cryptographic API random number generator, when there is a corresponding call in the SRTP application.
9.8
Re-Keying Re-keying in the form of key management is not supported by the SRTP Acceleration Driver and is out of the scope of this document. Key/random number generation is supported as described in Section 9.7.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 77
IP Telephony Software—SRTP Acceleration Overview
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 78
May 2009 Order Number: 320415-003US
SRTP Acceleration Driver Details—IP Telephony Software
10.0
SRTP Acceleration Driver Details
10.1
What’s New in this Chapter This chapter has been updated to describe the new asynchronous API of the SRTP Acceleration driver.
10.2
Overview and Terminology The SRTP Acceleration Driver is a kernel level driver. It conforms to a Linux* character device driver model. It initializes and manages hardware accelerated functions through the Cryptographic API. The SRTP Acceleration Driver performs the following activities: • Registers itself upon initialization as a character device driver, providing typical character device driver operations • Provides a means to perform accelerated crypto operations on data packets • Provides a means to generate random numbers The SRTP driver interface conforms to a standard character device interface, that is: ioctl(), read(), and write(). A character device can be opened using the system call open(). The file name is "/dev/srtp_acc_drv". The device can be closed using the system call close(). The SRTP driver currently defines several ioctl calls to support the configuration and operation of the driver. These include SRTP stream configuration and key generation (random number generation).
10.3
Memory Buffer Management The SRTP Acceleration Driver is responsible for allocating and managing all kernel space buffers to be used as inputs to the Cryptographic API. It is also responsible for copying memory from user space to kernel space and vice versa. The Cryptographic API requires contiguous memory blocks, as a result, the input data from the SRTP application is stored in flat memory buffers.
10.4
Stream Establishment A new SRTP Accelerated Stream is created by opening the device, using the system call open(). Each file open has a unique file descriptor, and is used to identify a particular SRTP application stream. The file and hence the SRTP Accelerated Stream can be opened in both blocking and non-blocking modes. Note that Blocking is the default operation. These flags dictate the operation of the read() system call. When reading on the stream in Blocking mode, the SRTP Acceleration driver puts the calling process to sleep if there are no packets ready to be read. When a packet becomes available, the read call unblocks and completes the operation. If opened with the Non-Blocking flag set, then the read() call returns immediately if there are no packets to be read. In this case, the return value is 0, indicating no bytes were read.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 79
IP Telephony Software—SRTP Acceleration Driver Details
Figure 32 shows an overview of the stream establishment process, including configuring a new stream. The SRTP Acceleration driver must check to ensure the maximum number of streams has not been exceeded. If this is ok, all the stream structures are allocated and added to the stream list, waiting for configuration. The SRTP application, in this case LibSrtp, uses the unique file descriptor returned from the open() call to distinguish the particular SRTP Accelerated stream. See Section 10.4.1 for details on configuring an SRTP Accelerated stream.
10.4.1
Configuring an SRTP Accelerated Stream An SRTP stream, which carries all the RTP packets from one source to another within the SRTP session, is required to be configured in the SRTP Acceleration Driver as is done in the SRTP application. Once the accelerated stream has been opened via the open() call as described in Section 10.4, the stream can then be configured. The configuration of an SRTP accelerated stream is accomplished via an ioctl() call to the SRTP Acceleration driver, with the file descriptor returned from the open() call used to identify the stream to configure. The ioctl() call used to configure a stream takes the command SRTP_ACC_STREAM_CONFIG and a pointer to an SRTP accelerated stream context structure as a parameter. The input parameter to this ioctl is a structure, which must be allocated and set in the SRTP application. The structure is of type srtp_acc_ctx_t, and contains all relevant information about the stream and all information about the type of operation to be performed including the profile. The SRTP Acceleration driver then initializes the corresponding Cryptographic API Session context structure, and initializes a new session in the Cryptographic API to implement the required operation. The following default modes of operation are supported: • encryption only • authentication only • encryption and authentication • corresponding decrypt operations The file descriptor returned from the open() call is used by the SRTP application to keep track of the corresponding SRTP Accelerated stream. It is this file descriptor that should be used to identify the accelerated stream in all further operations including configuring the stream and reading and writing from the stream. Once the stream is configured, the SRTP Acceleration driver translates a stream creation in the SRTP application to a session creation in the Cryptographic API. Figure 32 shows an overview of the process to create and configure a stream in the SRTP Acceleration driver (corresponding to a Cryptographic API Session).
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 80
May 2009 Order Number: 320415-003US
SRTP Acceleration Driver Details—IP Telephony Software
Figure 32.
Overview of Stream Establishment and Configuration
LibSrtp New Stream
Open()
Allocate and initialize Data Structures
LibSrtp New Stream
Ioctl() call
Initialize Crypto API Session context structure
Type of Operation
Encrypt Only
Encrypt & Auth
Auth Only
Return Session Handle Internal in the Driver Session Handle
10.5
Stream Removal When a stream has completed, either by an end of transmission or the key limit reached or even max number of packets reached, the stream is removed from the session in the SRTP application. In the same way, the corresponding Accelerated stream must be removed from the SRTP Acceleration driver. Again, this corresponds to the Cryptographic API removing a session. Closing a stream in the SRTP Acceleration Driver is done by closing the stream’s corresponding file descriptor. Note if any packets are currently active in the stream and are still in flight within the SRTP Acceleration driver while the stream is closed, the packets will be deleted and an error returned. Figure 33 shows the overview of removing a stream from the SRTP Acceleration Driver.
Figure 33.
Overview of SRTP Stream Removal
Close LibSrtp Stream
close() system call
De allocate structures
Crypto API Deregister the session context structure
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 81
IP Telephony Software—SRTP Acceleration Driver Details
10.6
Performing an Encrypt/Decrypt Operation To perform an encrypt/decrypt operation, there must be a configured SRTP accelerated stream open in the SRTP Acceleration Driver. The configured stream determines the type of operation that is performed on the packet. The following types of operations can be performed: • encrypt • authenticate • encrypt & authenticate • corresponding decrypt operations The SRTP Acceleration driver provides an asynchronous API to perform an operation. This API is in the form of the standard character device functions read() and write(). A user starts an operation by writing an SRTP accelerated packet to the SRTP driver, using the file descriptor to select the stream (and hence the operation to perform) that the packet belongs to. A user completes the operation by reading from the stream. The corresponding SRTP packet is returned via the read call.
10.6.1
Commencing an Operation - write() To start an accelerated SRTP operation, the user writes an SRTP accelerated packet to the SRTP Acceleration driver. The SRTP accelerated packet contains all relevant and necessary information about the data and the actual rtp data buffer itself to be encrypted. There is no need for it to contain any information about the operation, as this has already been set up in the stream initialization. The SRTP accelerated packet is defined as a structure srtp_acc_packet_t. The write call copies the RTP packet to be encrypted to the SRTP Acceleration Driver and subsequently submits the packet for encryption into the Cryptographic API. If successful, the write call returns the size of the SRTP Accelerated packet. If unsuccessful, -1 is returned and errno is set. If an error is returned, the packet will not have been submitted successfully to the Cryptographic API.
Figure 34.
Overview of write()
LibSrtp Commence Packet Encryption
Write()
Return Successful submission
10.6.2
Initialize Crypto API operation request data structure
Submit operation to Crypto API
Completing an Operation - read() To complete an accelerated SRTP operation, the user reads from the SRTP Acceleration driver to retrieve an encrypted (or decrypted) RTP packet. As with normal character device operation, the user provides a pointer to a buffer where to store the new encrypted packet and also the length of the packet to read. Note the SRTP Acceleration Driver expects the new length of the packet, hence if authentication was used and an authentication tag is expected, the length provided in the read call should be the length
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 82
May 2009 Order Number: 320415-003US
SRTP Acceleration Driver Details—IP Telephony Software
of the packet plus the length of the authentication tag. The authentication tag is appended to the end of the packet, therefore the user buffer must be large enough to accommodate this tag. If not, the SRTP Acceleration driver returns an error. If successful, the length of the packet copied to the user buffer is returned. If an error occurs, (-1) is returned and errno is set. In the case of authentication failure, (-1) is returned, however the packet is still copied to the user buffer including the authentication tag. This is to conform with SRTP application behavior. In the case where a read call is executed and there are no packets ready to be read, the SRTP Acceleration Driver either blocks, that is, puts the user space program to sleep until there is a packet available, or it returns immediately. In the non-blocking state, the SRTP Acceleration Driver returns 0, when there are no packets ready to be read (indicating zero bytes read). This operation is totally dependant on the blocking flags chosen when the file (SRTP Acceleration stream) is opened. By using the SRTP Acceleration Driver in Blocking mode, a synchronous SRTP application can easily interface with the SRTP Acceleration Drivers asynchronous API, simply by performing a read operation immediately after a write operation. This way the SRTP application sleeps until the operation has completed. Figure 35 shows the internal workings of the SRTP Acceleration Driver, on the read system call. When an operation is completed by the Cryptographic API, an internal callback function is invoked. This callback function then checks the success of the operation. If successful it places the packet on the stream’s read queue where it is ready to be read. If there was an error in the operation, the packet is added to the queue, however it is marked as failed. When the read operation continues and removes that packet from the queue, it checks to see if it was successful packet or not. If it is marked as failed, then the read call returns an error, indicating the failure. If an undefined error occurs, for example the SRTP Stream is closed before the operation has completed, then the packet buffer is deleted and an error is returned. Each stream has its own individual read queue. It is this queue that the read function checks to see if there are completed packets available to be read on that stream. If not, it eithers blocks or returns zero as described previously. In this way the read operation only returns packets previously written to that stream. Figure 35.
Overview of read() Operation Complete Internal call-back function Add Encrypted Packet to Streams Read Queue LibSrtp Complete Packet Encryption
Read()
Retrieve Packet from queue
Packet 1 Packet 2 Packet 3
10.7
Key Generation Key generation is performed by an ioctl call. The ioctl call SRTP_ACC_RANDNUM_GEN takes a structure of type srtp_acc_rand_num_t which contains a pointer to an output buffer and the length of key to be generated. The Cryptographic API generates the random number and returns it in the structure.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 83
IP Telephony Software—SRTP Acceleration Driver Details
10.8
Control Path Overview
10.8.1
Open The open function is called whenever the equivalent libc open() function is called from the client in user space. The client opens the SRTP Acceleration Driver character device driver file (/dev/srtp_acc_drv). The prototype for the open function is as follows: int open(struct inode *inode, struct file *file);
Upon each call to open, a new stream is established within the SRTP Acceleration Driver.
10.8.2
Release The release function is called whenever the equivalent libc close() function is called from the client in user space. The client must close, on exit, the SRTP Acceleration Driver character device driver file (/dev/srtp_acc_drv). The prototype for the release function is as follows: int release(struct inode *inode, struct file *file);
On each call to release, the driver removes the stream associated with that file.
10.8.3
Ioctl The ioctl function is called whenever the equivalent libc ioctl() function is called from the client in user space. The client can use ioctl in order to configure an SRTP Accelerated stream via /dev/srtp_acc_drv, once the character device file has been successfully opened. The prototype for the ioctl function is as follows: int ioctl (struct inode *inode, struct file *file, unsigned int cmd, unsigned long arg);
The supported list of commands and their arguments is listed in Table 15. Table 15.
Ioctl Command Descriptions Command
Argument
Description
SRTP_ACC_STREAM_CONFIG
The parameter is a pointer to a data structure of type srtp_acc_ctx_t containing all the information required by the Cryptographic API to install a new session. This includes information on the cipher operation, cipher keys.
ioctl command to configure a SRTP Stream within the Cryptographic API.
SRTP_ACC_RANDNUM_GEN
The parameter is a pointer to data structure of type srtp_acc_rand_num_t, which contains a pointer to a data buffer to store the generated number, and an int describing the length of the number to generate.
ioctl command to generate a random number.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 84
May 2009 Order Number: 320415-003US
SRTP Acceleration Driver Details—IP Telephony Software
10.9
Data Path
10.9.1
Encrypt/Decrypt Operation When an encrypt/decrypt operation is required in the SRTP application, the read and write calls are used, as described previously. The prototype for the write function call to start an operation is as follows: size_t write(struct file *filep, srtp_acc_packet_t *packet, size_t sizeof(srtp_acc_packet_t));
Where: • filep is a file pointer to the open file descriptor to the file /dev/srtp_acc_drv representing the SRTP Accelerated stream • packet is a pointer to the SRTP accelerated packet to be encrypted • sizeof(srtp_acc_packet_t) is the size of the accelerated packet to be written The prototype for the read function call to complete an operation is as follows: size_t read(struct file *filep, void * buffer, size_t (packet_len + auth_tag_len));
Where: • filep is a file pointer to the open file descriptor to the file /dev/srtp_acc_drv representing the SRTP Accelerated stream • buffer is a pointer to a user-allocated buffer where the encrypted packet is to be copied • packet_len + auth_tag_len is the expected length of the packet, including the authentication tag length (if used) Note:
The read call will block if the device file was not opened with the O_NONBLOCK flag set.
10.10
Resource Usage The SRTP driver must allocate a block of memory for each data packet to be encrypted. The largest possible payload, when the default encryption transform of AES Counter Mode is used, is at most 216 AES blocks, or 220 bytes (see RFC 3711, pg. 21). Other memory requirements include space for an strp_acc_ctx_t struct per SRTP stream. To increase performance, a buffer pool is allocated upon initialization time, when the SRTP Acceleration driver is first loaded. Only if the size of the packet to be encrypted is greater that the buffer size in the buffer pool, will additional memory be allocated. The current buffer size in the buffer pool is set as 360 bytes, this is to accommodate all voice packet sizes and their additional authentication tag lengths. The current size of the buffer pool is 10,000 buffers (of size 360 bytes).
10.11
QAT Access Layer (QAT-AL) Configuration The QAT-AL specifies the best performance is achieved when it is used in an asynchronous manner. The SRTP Acceleration driver provides an asynchronous API, however it also allows the use of this API in a synchronous manner for its interface with LibSrtp. A configuration parameter of QAT-AL that has a major effect on the performance of synchronous usage is the use of Interrupt coalescing.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 85
IP Telephony Software—SRTP Acceleration Driver Details
Interrupt Coalescing, which is enabled by default, allows the QAT-AL to avoid the necessary overhead in creating and destroying an interrupt for every completed operation. This means it will gather interrupts over a specific period of time. This affects the performance of a synchronous operation because the QAT-AL will not generate an interrupt when the operation has completed, thus causing a delay. The exact delay depends on the interrupt coalescing configuration that the user has selected. The default is 10000 nanoseconds.
10.11.1
Interrupt Coalescing and Synchronous Accelerated SRTP For maximum performance of a synchronous system, it is strongly recommended to turn interrupt coalescing off, or to change the delay period. To turn interrupt coalescing off, you must set ET_RING_LOOKASIDE_INTERRUPT_COALESCING_ENABLE flag to ‘0’ in the icp_asd.conf file located (after QAT-AL installation) in /etc. It is then necessary to restart the QAT-AL before use. The delay period can also be configured within that file, by changing the ET_RING_LOOKASIDE_COALESCE_TIMER_NS variable. For more details, see the Intel® EP80579 Software for Security Applications on Intel® QuickAssist Technology Programmer’s Guide, [SEC_PROG_GD].
10.11.2
Interrupt Coalescing and Asynchronous Accelerated SRTP If the SRTP Acceleration Driver is to be used in an asynchronous manner, then it is recommended to enable interrupt coalescing.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 86
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
11.0
HSS I/O Access Library Details
11.1
What’s New in this Chapter No updates in this release.
11.2
Overview and Terminology The HSS I/O Access Library is the software that runs on the main core which provides an interface to the Programmable I/O Unit to higher level software such as device drivers. The Programmable I/O Unit provides the majority of the TDM data processing (e.g., segmentation, encoding, decoding, reassembly) and contains coprocessors to assist with these functions. The Programmable I/O Unit supports three independent HSS ports and a total of 128 channels across both Voice and HDLC services. The following terms are used in this chapter: • Port: the hardware TDM interface by which EP80579 interfaces to the outside world. EP80579 has three HSS ports. • Timeslot: the basic unit of data within a serial TDM stream (e.g., a framed T1/E1 stream). Each timeslot is one byte in size. A single T1/J1 stream is composed of 24 timeslots and a single E1 stream has 32 timeslots. In addition to the single T1/E1/J1 stream, the HSS port hardware supports configuration for Q-MVIP, which allows for 4 E1 streams on a single port, effectively multiplying by 4 the number of timeslots available on that port. • Timeslot Bit Map: a 32 bit bitmap with each bit indicating if that particular timeslot is selected or not. A bit is set to high to indicate that timeslot is required. A bit is reset to low to indicate that timeslot is not required. The group of timeslots thus selected by a timeslot bit map form a channel. • Channel: a set of timeslots configured together (with the help of timeslot bit map). Dynamic timeslot configuration is supported i.e., changing the timeslot to channel mapping without disturbing traffic for channels on the same TDM interface. Please note that timeslot assignments need to be symmetric for Rx and Tx. • Link: On EP80579, the TDM interface provides connection for up to 12 T1/E1 streams across the ports, each of these streams can also be refered to an E1/T1/J1 link.
11.3
Dependencies The HSS I/O Access library depends on the Programmable I/O Unit (PIU) Message Handler to provide access to the Programmable I/O Unit messaging interface used for configuration of the unit. The library also depends on the Operating System Abstraction Layer for the definition of the MBUF buffer format and general operating system abstraction (mutexes, semaphores, cache handling...). Refer to Figure 36 for a detailed diagram for the entire TDM I/O feature.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 87
IP Telephony Software—HSS I/O Access Library Details
Figure 36.
TDM Interface Component Dependencies
Main Core
Reference Application
Media Processor User Space Kernel Space
BSP
HSS I/O Access Library Client (e.g. Voice Driver)
OS
OSAL
HSS I/O Access Library Client (e.g. Data Driver)
Access Libraries
bufferMgmt Log irq
HSS I/O Access Library
memory Thread
PIU Message Handler
Programmable I/O Unit (PIU)
11.4
Packet Based Design One important aspect of this design is that voice and HDLC data are treated similarly, i.e. both are processed in a packet-based manner. From an HSS I/O Access perspective, each Voice sample is handled like an HDLC packet, the main difference residing in how the packet is processed by the Acceleration service. The packetized approach used by EP80579 IP Telephony software allows for reduced complexity in both the Programmable I/O Unit and the HSS I/O Access Library.
11.5
Multiple Client Support The HSS I/O Access Library supports multiple clients. The limit on the number of clients is the same as the limit on the maximum number of channels. A maximum of one client per channel is supported. The HSS I/O Access library enforces this through the use of appropriate mutexes and locking, this also protects data in the case of clients using multiple threads.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 88
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
11.6
Channel ID Management This component manages the channel ID assignments. It is not possible for a client to request a specific channel ID. Instead, the client requests the exact timeslots it would like to use, and the channel ID is selected by the HSS I/O Access Library, associated with the timeslots, and returned to the client.
11.7
Buffer Chaining The HSS I/O Access Library only supports buffer chaining in one instance. When the client makes a request to recover all buffers for a particular channel, then all the buffers are returned as a single chain. In all other instances where buffer chaining may be possible, it is not supported. In other words, chaining is not supported on any buffers supplied to the HSS I/O Access library. It is the responsibility of the HSS I/O Access Client to enforce this.
11.8
Endianness The Programmable I/O Unit operates in big-endian mode. The main core will run in little-endian mode. Wherever necessary, the HSS I/O Access Library performs endian swaps on data it needs to share with the Programmable I/O Unit. The Operating System Abstraction Library (OSAL) is used to facilitate these swaps.
11.9
Memory Buffer Management The HSS I/O Access Library is not responsible for the management of the memory allocated for the buffers used in the system. This responsibility falls to the HSS I/O Access Library Client.
11.10
Main Core – Programmable I/O Unit Communication This sub-section describes the communication mechanism between the HSS I/O Access Library running on the main core and the Programmable I/O Unit. A software based queuing mechanism will be used for HSS I/O Access Library – Programmable I/O Unit communication. Three queue types are shared between the Programmable I/O Unit and the HSS I/O Access Library: • one for transmitting data • one for receiving data • one for holding free buffers for the Programmable I/O Unit to write received data into Two receive queues exist - one for HDLC data processing and the other for Voice data processing. Separate HDLC and Voice free buffer queues also exist. This allows the HDLC service to stay separate and not interfere with the Voice service which has stricter time constraints for the servicing of the samples received and transmitted. The number of buffers allowed at one time in the internal HSS I/O Access Library Rx datapath (that is, the total buffers in the receive queue and free buffers queue) is limited per service to the size of the free queue per service: currently 2048 for both HDLC and Voice. Each channel supported by the Programmable I/O Unit has its own transmit queue. Each of these queues is implemented in software as circular queues.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 89
IP Telephony Software—HSS I/O Access Library Details
11.10.1
Lockless Software Queue Mechanism In order to avoid locking on the queues for accesses between the HSS I/O Access Library and the Programmable I/O Unit, a mechanism is used whereby the HSS I/O Access Library and the Programmable I/O Unit use different indices into these queues and do not write to the same index. Considering the indices are incremented on each write and read to the corresponding queue, these indices are referred to as counters throughout this document. These counters are stored in cacheable DRAM and are accessible by both the HSS I/O Access Library and the Programmable I/O Unit. In the case of using coherent memory, if the write and read counters were allocated in memory covered by the same cache line, there are potential performance hits, but there would not be a memory corruption issue. Here’s an example scenario: In the case where the HSS I/O Access Library has an updated Read Counter in cache that has not been flushed to memory, the line is described as a dirty cache line. Via the memory controller, the Programmable I/O Unit tries to write a byte to memory which is covered by the same cache line. The memory controller checks the cache, identifies that there is a dirty cache line for this byte, flushes that cache line, and then allows the Programmable I/O Unit write to the memory. Although this is safe in terms of cache coherency, it is an inefficient use of the cache. To avoid the cache inefficiency, the HSS I/O Access Library modifiable counters and the Programmable I/O Unit modifiable counters are always allocated in such a way as to keep them in separate cache lines. See Figure 37 for details.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 90
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
Figure 37.
Queue Counter Memory Assignments
Figure Legend: Written to by the HSS I/O Access Library Read from by the Programmable I/O Unit
Written to by the Programmable I/O Unit Read from by the HSS I/O Access Library
64 Bytes 4 Bytes 2 Bytes 1 Byte TxQ Tail Counter Channel 0 TxQ Tail Counter Channel 64 TxQ Tail Counter Channel 128 TxQ Tail Counter Channel 192
…………..
…………..
…………..
…………..
Voice RxF Tail Counter
Voice RxQ Head Counter
…………..
HDLC RxF Tail Counter
HDLC RxQ Head Counter
…………..
TxQ Head Counter Channel 0 TxQ Head Counter Channel 64 TxQ Head Counter Channel 128 TxQ Head Counter Channel 192
11.10.2
TxQ Tail Counter Channel 63 TxQ Tail Counter Channel 127 TxQ Tail Counter Channel 191 TxQ Tail Counter Channel 255
…………..
…………..
…………..
…………..
TxQ Head Counter Channel 63 TxQ Head Counter Channel 127 TxQ Write Counter Channel 191 TxQ Write Counter Channel 255
Voice RxF Head Counter
Voice RxQ Tail Counter
…………..
HDLC RxF Head Counter
HDLC RxQ Tail Counter
…………..
Receive-Free Queue (RxFreeQ) In order to receive data, buffers are given to the Programmable I/O Unit into which it can write the received data. The receive-free queue (RxFreeQ) is used to transfer these buffers from the HSS I/O Access Library to the Programmable I/O Unit. In order to keep the Voice service independent from the HDLC service and vice-versa, there is one Receive Free Queue per service.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 91
IP Telephony Software—HSS I/O Access Library Details
Figure 38.
Receive Free Queues for Voice and HDLC Channels
Written by Programmable I/O Unit / Read by HSS I/O Access Library (16 bits)
Written by Programmable I/O Unit / Read by HSS I/O Access Library (16 bits)
Read Counter
Read Counter Entry describing the Buffer
Write Counter Written by HSS I/O Access Library Read by Programmable I/O Unit (16 bits)
Entry describing the Buffer
Write Counter Written by HSS I/O Access Library Read by Programmable I/O Unit (16 bits)
HdlcRxFreeQ
VoiceRxFreeQ
Each entry in the receive-free queue contains an entry describing the buffer. Details of this entry are described in Section 11.13. When the HSS I/O Access Library wants to add a new empty buffer to the RxFreeQ, it uses the Programmable I/O Unit (PIU) QMgr queue-write function. This function checks to see if there is a free entry in the queue (by comparing the read and write counters), adds an entry to a free entry, and then updates the write counter which indicates the head of the queue. When the Programmable I/O Unit wants to use a free buffer, it checks to determine if there is a free buffer on the queue (by comparing the read and the write counters), takes one from the queue, and modifies the read counter. If the Programmable I/O Unit fails to find a buffer on the RxFreeQ, the RX_FREE_QUEUE_UNDERFLOW error occurs. See Section 12.2.4.1 for details.
11.10.3
Receive Queue (RxQ) The operation of the receive queue which is shared with the Programmable I/O Unit (PIU) is slightly different from the receive-free queue. Instead of containing a descriptor of the buffer like the Receive Free scenario, each entry in the queue contains a pointer to the PIU service-specific section of the OSAL buffer used. The client software needs to know what channel a buffer has been received from. To facilitate this, the PIU writes the channel ID into the channel ID field in the PIU service-specific section of the OSAL buffer header. See Table 16 for details. This allows for lesser memory usage for the software queues as each entry is only be 4 bytes in size instead of 16 bytes for Receive Free. Similarly to the Receive Free queues, there is one Receive Queue per supported service; hence there are two Receive queues total. The HSS I/O Access Library demuxes entries from the receive queue into FIFO soft rings. See Section 11.11 for details on these rings; there is one ring per supported channel. Refer to Figure 39 for details. This is a necessary step in order to allow a client to poll for data on a particular channel.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 92
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
Figure 39.
Receive Queue Design Receive Rings (Voice & Data)
Ch 0
Ch 1
Ch 2
Ch ...
Ch ...
Ch ...
HDLC RxQ
Ch ...
Ch ...
Ch 127
Software FIFO Rings used by HSS I/O Access Library Only
Voice RxQ Software Queues Shared with the PIU
When the client is operating in polled mode, it requests a received buffer for a specific channel. If the shared queue for the channel type (i.e. HDLC or voice) requested is not empty, it is drained and demuxed into the software rings used by the HSS I/O Access Library only. Then the first buffer in the internal software ring is returned for the requested channel. When the client is operating in interrupt mode, the HSS I/O Access Library receive routine demuxes the entries into the appropriate channel ring(s) and then triggers a callback for each buffer received on each channel.
11.10.4
Transmit Queue (TxQ) The transmit queues are allocated individually at initialization time, as shown in Figure 40. There is one queue allocated for each supported channel.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 93
IP Telephony Software—HSS I/O Access Library Details
Figure 40.
Transmit Software Based Circular Queues
Ch 0
Ch 1
Ch 2
Ch ...
Ch ...
Ch 127
Circular Queues
Transmit Queues
Base Address
For each of these transmit queues, there is a read and a write counter stored in DRAM. The write counter references the last entry to be added to the queue for a specific channel. The read counter references the oldest entry in the queue for that channel. The Programmable I/O Unit and the HSS I/O Access Library both have read and write access to these counters, although a similar convention to that described for the RxFreeQ and RxQ types is imposed on who reads and who writes to each counter. As before, the HSS I/O Access Library uses the Programmable I/O Unit (PIU) QMgr queue-write function to add an entry to these queues. Using the Shadow of the read counter, the queue-write function checks that the queue is not full, adds an entry to the queue, and then modifies the head counter. The Programmable I/O Unit reads the head counter, checks that the queue is not empty, transmits data, and then updates the tail counter to reflect that the data has been sent. The HSS I/O Access Library does not modify the tail counter, and the Programmable I/O Unit does not modify the head counter. To facilitate transmit Done servicing, the HSS I/O Access library will push onto an internal software ring for that channel (see Section 11.11) a pointer to the OSAL buffer that contains the data submitted for transmission. Section 12.2 discusses some subtleties of how the voice and HDLC channels behave in overload and underload scenarios.
11.10.5
Queue Counter Shadowing As described above, the Transmit path is optimized to use a single software queue for each channel. The main advantage of a single queue Transmit mechanism is that the Programmable I/O Unit does not spend valuable processing time transferring queue entries from the Transmit Queue to a Transmit Done queue. To enable this optimization, the Programmable I/O Unit (PIU) QMgr component has been modified to include a feature called Counter Shadowing. The PIU QMgr maintains a local internal copy of the Tail counter and uses this copy instead of the original for all Reads, Writes, and state checking. The shadow should then be synched with the real counter at regular intervals.
11.10.6
Buffer Recovery (Tx Done) Using the PIU QMgr shadowing mechanism, the HSS I/O Access Library tracks how the read counter for each transmit queue is updated by the Programmable I/O Unit. When the read counter changes, it means that the Programmable I/O Unit has finished processing that buffer and it is now possible to free it. Any free buffer(s) will then be returned to the HSS I/O Access Library client.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 94
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
As detailed in Figure 41, a shadow (copy) of the Transmit Queue read counter is maintained by the PIU QMgr component. When the HSS I/O Access library is required to retrieve a Transmit Done Buffer (either upon an interrupt or when polled), it compares the latest version of the Read Counter (value A) to its shadow (value B). If there is a difference, this means that, since the last time a Transmit Done was retrieved, the Programmable I/O Unit has completed Transmission of A-B submitted transmissions. If this was done in the context of an interrupt mode, then the client is notified that there are Transmit Dones; in the context of polling, The least recent Buffer submitted for transmission is returned to the client and the shadow counter is incremented. Transmit Queue Shadowing
5
H e a d C o u n te r
6
7
Figure 41.
3
T a il S h a d o w
2
T a il C o u n te r
0
4
S u b m itte d E n tr ie s y e t to b e p r o c e s s e d b y re a d e r
1
S u b m itte d E n trie s d o n e b y re a d e r , to b e a c k n o w le d g e d b y s h a d o w c o u n te r ow ner
During a Transmit Done Retrieve call, the following sequence of events will free a buffer: • Check to see if the queue read counter has changed since the last transmit call (if this has changed it is because the Programmable I/O Unit has transmitted the data referenced by this queue entry). • Pop from the internal software ring for that channel the pointer to the OSAL buffer containing the data transmitted and update the PIU QMgr shadowing. This minimizes accesses to memory shared with the Programmable I/O Unit and removes the need for converting from a Software Queue Entry to an OSAL buffer pointer usable by the HSS I/O Access client. • Return the buffer to the HSS I/O Access library client.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 95
IP Telephony Software—HSS I/O Access Library Details
11.11
Access Library Software Rings Software rings are used internally by the access library to demux buffers from the shared receive queues into the appropriate channel ring(s). This scheme is necessary to facilitate any clients that wish to poll for receive data. Rings were chosen in preference to queues provided by the PIU QMgr as they require less memory on the heap and can be implemented with less overhead. There is one receive ring per supported channel. One ring per supported channel is implemented for increased performance on the Transmit side. Throughout this document, the term rings always refers to lightweight software rings internal to the component, whereas queues will always refer to Software Queues provided by the PIU QMgr component which are more feature rich.
11.12
IX_OSAL_MBUF Programmable I/O Unit Specific Section Format The IX_OSAL_MBUF (also referred to as MBUF) is an Operating System agnostic memory buffer defined in the Operating Systems Abstraction Layer (OSAL) component. This section will define the format of a region within the IX_OSAL_MBUF which has been reserved for Programmable I/O Unit specific parameters. The IX_OSAL_MBUF contains a reserved area for Programmable I/O Unit specific usage. The OSAL design specification does not define what is in this section of the OSAL buffer, it merely defines that it is eight words of reserved space and that the words are 32-bit aligned. The OSAL component leaves the exact definition of the contents of this section to the component that uses it (in this case the TDM I/O Acceleration) so that multiple features may use the section without OSAL having to maintain multiple definitions of the same section. This Section of the IX_OSAL_MBUF is solely used by the HSS I/O Access library and the underlying acceleration; the HSS I/O Access library client is only required to fill in the standard section of the IX_OSAL_MBUF as documented in the API. Table 16 shows how these eight words are defined for this feature and the field descriptions are shown in Table 17.
Table 16.
Layout of Programmable I/O Unit Specific Section of IX_OSAL_MBUF
0x00
0x00
0x01
channelId
status
0x02
0x03 currBufLength
0x04
pCurrBufData
0x08
packetLength
0x0C
pCurrBuf
0x10
pNextBuf
0x14
notUsed
notUsed
notUsed
notUsed
0x18
notUsed
notUsed
notUsed
notUsed
0x1C
notUsed
notUsed
notUsed
notUsed
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 96
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
Table 17.
Service-Specific Sections of the IX_OSAL_MBUF Fields
Field (Size)
Meaning in RxFree Queue Entry
Meaning in descriptor pointed to by Rx Queue Entry
channelId (byte)
Undefined. May be set to any value.
Set by Programmable I/O Unit with the channel number for the received packet
Set by the HSS I/O Access Library for the transmit packet
Must be set to null (0x0)
Set by Programmable I/O Unit with the valid or error status for the received packet.
Undefined. May be set to any value.
currBufLength (short)
Set by the HSS I/O Access Library. Must be set to the number of bytes in the data buffer portion of this IX_OSAL_MBUF
Set by Programmable I/O Unit to the number of bytes filled in the data buffer portion of this IX_OSAL_MBUF
Set by the HSS I/O Access Library for the transmit packet. Represents the number of bytes in the data buffer portion of this IX_OSAL_MBUF
pCurrBufData (word)
Set by the HSS I/O Access Library using the pointer provided by the client in the standard section of the OSAL Buffer. Points to the start of where data may be written into
packetLength (word)
Must be set to null (0x0)
Not used
Not used
Set by the HSS I/O Access Library. A pointer to the start address of the entire IX_OSAL_MBUF structure containing this firmware service-specific section The Programmable I/O Unit uses this field as the entry written to the Rx Queue on completed reception.
Pointer to the start address of the entire IX_OSAL_MBUF structure containing this firmware service-specific section
Set by the HSS I/O Access Library. Pointer to the start address of the entire IX_OSAL_MBUF structure containing this firmware servicespecific section
status (byte)
pCurrBuf (word)
11.13
Set by the HSS I/O Access Library. Points to the start of data that has been received
Meaning in Tx Queue Entry
Set by the HSS I/O Access Library using the pointer provided by the client in the standard section of the OSAL Buffer. Points to the start of data to be transmitted
Queue Entry Format Each Transmit and Receive Free queue entry is 4 words in size and contains information from the service-specific section of an IX_OSAL_MBUF as defined in Table 16 and Table 17, resulting in the layout shown in Table 18. By writing these values directly into the queue entry, the Programmable I/O Unit will be saved from having to do a pointer de-reference per packet in order to read this information. The HSS I/O Access Library will do a 16-byte write/read of this data to the queues. The PIU QMgr burst read and write functions may be optimized to do 64-byte reads/writes as this is the most optimal memory access on IA.
Table 18.
Queue Entry Format
0x00
0x00
0x01
channelId
status
0x02 currBufLength
0x04
pCurrBufData
0x08
packetLength
0x0C
pCurrBuf
May 2009 Order Number: 320415-003US
0x03
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 97
IP Telephony Software—HSS I/O Access Library Details
11.14
Polled/Callback Mode In this context, the polled/callback mode distinction refers to the model by which the HSS I/O Access Library client intends to use its service. Both callback and polled modes are supported. If the HSS I/O Access Library client wishes to operate in callback mode, the client has to register callback functions with the HSS I/O Access Library via the registration functions. The requirement is on the HSS I/O Access Library to callback its client for receive processing and transmit done processing only; Transmit and Receive Free replenish are outside of the callback mode of operation, these are driven by the client. Each of these callback functions is invoked in the context of the HSS I/O Access Datapath service function. The TDM Setup currently is responsible for registering this service function with the Programmable I/O Unit interrupt; the TDM Setup driver could be modified to use a hardware Timer interrupt or even a polling thread. Each registered callback is called when the appropriate condition is fulfilled (channel X Receive Ring not empty will trigger receive callback for that channel) when the Datapath service function is run. Callbacks are for notification purposes only, it is still responsibility of the client to call the TransmitDoneRetrieve or Receive function when notified. Depending on the client design, the TransmitDoneRetrieve or Receive function can be called within the context on the callback or not. If the HSS I/O Access Library client wishes to operate in polled mode, then it will need to call functions to receive data and to retrieve transmitted buffers. The polled mode API can be seen as a subset of the callback mode API, as the Receive and Retrieve Transmit Done function are the same in both modes.
11.15
Resource Usage
11.15.1
Queue Sizes The HSS I/O Access Library allocates memory for the software queues used when communicating in the Programmable I/O Unit. The following parameters are used for queue sizes: • 128 channels are supported. • Each channel requires the allocation of a transmit Queue. • Each service (HDLC and Voice) requires a Receive Queue and Receive Free Queue allocated. • Each Entry into the Transmit and Receive Free Queues is 16 bytes in size (see Section 11.13). • Each Entry into the Receive Queues is 4 bytes in size. • Each Transmit queue is allocated 128 entries (depending on the service allocated to the channel, not all 128 entries may be used). • Each Receive and Receive Free Queue contains 2048 entries. Transmit Queue 128 [channels] x 128 [entries] x 16 [bytes] = 262 144 [bytes] Receive Queues 2 [services] x 2048 [entries] x 4 [bytes] = 16 384 [bytes] Receive Free Queue 2 [services] x 2048 [entries] x 16 [bytes] = 65 536 [bytes] Total memory usage for queues = 344 064 [bytes]
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 98
May 2009 Order Number: 320415-003US
HSS I/O Access Library Details—IP Telephony Software
11.15.2
Counter Sizes Counters are used for each queue: • Each Transmit Queue uses a byte-sized Head counter, Tail Counter, and Shadow counter. 128 [channels] x 3 [counters] x 1 [byte] = 384 [bytes] • Each Receive and Receive Free Queue uses a 2 byte Head and Tail Counter. 4 [counters] x 2 [bytes] = 8 [bytes] Total memory usage for counters = 392 [bytes]
11.15.3
Ring Sizes As well as allocating memory for the Software Queues, the HSS I/O Access Library also uses memory for internal data such as the software rings. • One ring is allocated for each channel on Transmit (internal use only) and on Receive. • These rings are the same size as the Software Queues on Transmit and contain 256 entries on receive. • Each entry is 4 bytes in size. Transmit Ring 128 [channels] x 128 [entries] x 4 [bytes] = 65 536 [bytes] Receive Ring 128 [channels] x 256 [entries] x 4 [bytes] = 131 072 [bytes] Total memory usage for rings = 196 608 [bytes]
11.16
Operating System-Specific Details The HSS Access Library is specifically designed to be operating system-agnostic through the use of OSAL (Operating System Abstraction Layer) component.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 99
IP Telephony Software—HSS I/O Access Library Details
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 100
May 2009 Order Number: 320415-003US
HSS I/O Access Packet Flow Details—IP Telephony Software
12.0
HSS I/O Access Packet Flow Details Unless stated otherwise throughout this section, the behavior described is applicable to both a Voice and an HDLC channel.
12.1
What’s New in this Chapter No updates in this release.
12.2
Data Flow Scenarios
12.2.1
Transmit to Channel For the client to transmit data on a channel it simply needs to call the HSS transmit function specifying the data for transmission and the channel on which to transmit. The function returns after it has added the packet to the transmit queue for that channel. The data is transmitted by the Programmable I/O Unit at a later time. As the transmit function returns before the data is actually sent, it is assumed that once data gets into the transmit queue it is sent by the Programmable I/O Unit.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 101
IP Telephony Software—HSS I/O Access Packet Flow Details
Figure 42.
Packet Transmit Submission
D r iv e r A p p lic a tio n L e v e l 1 . ic p _ H s s A c c T r a n s m it ( ...)
H S S
A c c e s s
2 . Q u e u e W r ite ( … )
Ix Q M g r A c c e s s L a y e r
S h a re d M e m o ry
P r o g r a m m a b le I/O U n it P h y s ic a l In te r fa c e H S S
12.2.1.1
P o rt
Overload on Transmit to Channel A channel queue overload is symptomatic of one of two scenarios: • The HSS I/O Access client is over-submitting for that channel and the PIU is not able to transmit fast enough. • The HSS I/O Access client is not Retrieving Transmit Done buffers often enough. In both cases, the HSS I/O Library is required to handle Queue overloading as described below.
12.2.1.1.1
Voice Channel In the event of overload on transmit to a voice channel, the ideal solution would be for the HSS I/O Access Library to start freeing packets which have been in the transmit queue the longest, i.e. some of the oldest voice data. However, due to the nature of the HSS I/O Access Library and Programmable I/O Unit queuing mechanism, the oldest data can not be removed without introducing locking (i.e. the Programmable I/O Unit may be accessing the oldest of the data). Also, no matter what data is dropped, it is not recommended to drop consecutive voice packets as this has an adverse affect on voice quality.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 102
May 2009 Order Number: 320415-003US
HSS I/O Access Packet Flow Details—IP Telephony Software
Hence, in this voice overload scenario, the HSS I/O Access Library preemptively prevents every second voice sample from being transmitted once the Transmit Queue goes above an internally configured threshold. If the client’s rate of submission is still sufficient to completely fill the Transmit Queue, all submissions are rejected until the Queue is no longer full, at which point to the mechanism described above resumes. The HSS I/O Access library resumes accepting all submissions when the Queue state goes below the specified threshold.
12.2.1.2
Voice Packet Aging on Receive To prevent packets building up in the Rx Queue for a voice channel, a mechanism is implemented for Rx, similar to the Tx Queue overloading behavior described in Section 12.2.1.1. This mechanism is known as Packet Aging and its purpose is to prevent the build up of Rx latency on the voice channel. Latency build-up would otherwise occur if the HSS I/O Access Library client fails to retrieve Rx packets for periods of time. When the number of Rx packets for a channel reaches an internally configured threshold (2), the HSS I/O Access Library drops every second packet received for that channel until all Rx packets for the channel are retrieved by the HSS I/O Access Library client.
12.2.1.2.1
HDLC Channel For an HDLC Channel, a queue overload is defined as the Transmit Queue being full. In this case, the HSS I/O Access library rejects any packet Transmit submission until the queue state changes.
12.2.1.3
Under-load on Transmit to Channel For HDLC channels, there is no issue if the transmit queue empties. The Programmable I/O Unit just transmits idle cells. For voice channels, if the Programmable I/O Unit has no voice data to transmit, it either transmits a per-channel configurable idle pattern or repeats the last frame transmitted depending on how the channel has been configured.
12.2.2
Retrieve Transmit-Done Buffers For the client to retrieve Transmit-Done buffers for a channel, it either has to poll via the Transmit-Done-Retrieve function (polled mode) or has registered a transmit-done callback which notifies the client that one or more buffers are available for retrieval.
12.2.3
Receive from Channel Two mechanisms are available for clients to receive data from the HSS I/O Access Library.
12.2.3.1
Client Receive Via HSS Receive Function In the polled mode of operation, the client is responsible for calling the HSS receive function. If the client does not call this function frequently enough, data packets are dropped by the Programmable I/O Unit due to overflow on the receive queue. An event notification that packets are being dropped is sent only on the first occurrence of an overflow. Subsequent occurrences do not trigger a notification. However, statistic counters are maintained which may be used to identify this situation. For example, an overflow occurs and the notification is sent. Then a few more overflows occur with no notification. Later, things return to normal with no overflows for some time. In this example, the next overflow will not trigger a notification.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 103
IP Telephony Software—HSS I/O Access Packet Flow Details
Figure 43.
Packet Receive
D r iv e r A p p lic a tio n L e v e l 1 . ic p _ H s s A c c R e c e iv e ( . .. )
H S S A ccess
2 . Q u e u e R e a d (… )
Ix Q M g r A ccess Layer
S h a re d M e m o ry
P r o g r a m m a b le I/O U n it P h y s ic a l In te r fa c e H S S P o rt
12.2.3.2
Client Receive Via HSS Receive Callback If the client registers a receive callback function with the HSS I/O Access Library (via the channel configuration function) then the clients’ registered callback function is invoked by the HSS I/O Access Library in the context of the Programmable I/O Unit interrupt. This callback acts as a notification indicating to the client that the Receive function needs to be called as the Receive Queue is not empty. The condition generating the callback is not available for configuration. Callbacks are always triggered on the not-empty condition.
12.2.3.3
Overload on Receive from Channel The Programmable I/O Unit software drops the data if the HDLC or voice receive queues are full. It also notifies the HSS I/O Access library of this event, but only on its first occurrence as stated previously.
12.2.4
Replenish Free Buffers to Receive-Free Queue In order for the HSS I/O Access Library client to send it an empty (free) buffer, the client must allocate the buffer and then transfer it using the replenish function described in the public header file.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 104
May 2009 Order Number: 320415-003US
HSS I/O Access Packet Flow Details—IP Telephony Software
The HSS I/O Access Library internal Rx datapath (the Rx Free Queue, Rx Queue, and Rx Channel Rings) can contain a maximum of 2048 buffers per service at one time (the limit is the size of the service’s Rx Free Queue).
12.2.4.1
Receive Free Under-Run The Programmable I/O Unit starts dropping received data if the client does not replenish the Receive Free Queue in time. Since there is a Receive Free queue for each service (Voice or HDLC), the Programmable I/O Unit only drops data on channels of the same service type as the receive free queue that is empty. Similarly to the Receive Overrun condition, the client is notified only on the first occurrence of under-run on the receive free queues.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 105
IP Telephony Software—HSS I/O Access Packet Flow Details
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 106
May 2009 Order Number: 320415-003US
SSP I/O Access Library Details—IP Telephony Software
13.0
SSP I/O Access Library Details
13.1
What’s New in this Chapter No updates in this release.
13.2
Overview The SSP I/O Access Library provides the capability to configure the SSP I/O Unit and once the intended configuration is set up, it also handles the data traffic. The transmit FIFO and the receive FIFO are used to facilitate data transfer. Either interrupt or polling mode are supported at a given time. The SSP I/O Access Library executes in kernel space on Linux.* It is the responsibility of the SSP I/O Access Library client to invoke SSP I/O Access APIs to configure and then transport data over the SSP I/O Access API.
13.3
Functional Description
13.3.1
Basic The SSP I/O Access Library software offers services that can be divided into six categories: • Initialization - initialize the SSP I/O Access Library • Send - submit data to the SSP I/O Access Library for transmission over the serial link. A copy from the client supplied memory into the SSP transmit FIFO is required. • Receive - receive data from the SSP I/O Access Library and copy this data into the clients' memory • Polling - check if thresholds have been hit • Configuration • Debugging
13.3.2
Detailed The SSP I/O Access Library provides the capability to configure SSP I/O Unit. The SSP I/O Unit handles the data transfers once the intended configuration is setup. The SSP I/O Access Library provides capabilities to transfer data to the hardware transmit FIFO and from the hardware receive FIFO. Both interrupt and polling modes are supported. SSP I/O Access Library supports only one client at any given time. The SSP I/O Access Library provides configuration capabilities to: • Select frame format- SSP, SPI, or Microwire • Select data sizes - 4 to 16 bits
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 107
IP Telephony Software—SSP I/O Access Library Details
• Select clock source - external or on-chip • Configure serial clock rate - to drive a baud rate of 7.2 Kbps to 1.8432 Mbps (if onchip clock source is selected only) • Enable/disable the receive FIFO level interrupts • Enable/disable the transmit FIFO level interrupts • Set the transmit FIFO threshold - 1 to 16 frames • Set the receive FIFO threshold - 1 to 16 frames • Select operation mode - normal or loop-back operation • Select SPI SCLK polarity - Polarity of SCLK idle state is low or high (only used in SPI format) • Select SPI SCLK phase - Phase of SCLK starts with one inactive cycle and ends with ½ inactive cycle or SCLK starts with ½ inactive cycle and ends with one inactive cycle (only used in SPI format) • Select Microwire control word format - 8 or 16 bits • Enable/disable the SSP I/O Unit The SSP I/O Access Library also provides statuses for: • SSP state - busy or idle • Transmit FIFO level - 0 to 16 frames • Receive FIFO level - 0 to 16 frames • Transmit FIFO hit or below its threshold • Receive FIFO hit or exceeded its threshold • Receive FIFO overrun • Statistics for frames received, frames transmitted, and number of overrun occurrences
13.4
Dependencies The SSP I/O Access Library has dependencies on: • OSAL - SSP I/O Access Library uses OSAL for Operating System calls. OSAL is used primarily for logging in the SSP I/O Access Library. It is also used for getting the base address of the SSP I/O Unit. • SSP I/O Unit - SSP I/O Access Library is dependent on SSP I/O Unit.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 108
May 2009 Order Number: 320415-003US
SSP I/O Access Library Details—IP Telephony Software
Figure 44.
SSP I/O Access Library Dependencies
C lient
OSAL
S S P I/O A ccess Library
S S P I/O U nit
13.5
Memory Buffer Management The SSP I/O Access Library has no buffer management requirements. When the SSP I/O Access Library reads data out of the SSP I/O Unit, it copies the data directly into the memory location supplied by the client (this is either in interrupt or polled mode context). When the SSP I/O Access Library client writes data, the SSP I/O Access Library copies this data out of the client's memory location directly into the SSP I/O Unit.
13.6
Multiple Clients The SSP I/O Access Library can only have one client at any one time.
13.7
Polled / Callback Mode The SSP I/O Access Library can function in either interrupt or polled mode. If interrupt mode is configured, the SSP I/O Access Library client binds an SSP I/O Access Library function to the SSP I/O Unit Receive FIFO interrupt. The threshold is configurable for how many entries need to be in the receive FIFO before the interrupt is triggered. It is recommended that in order to reduce the amount of interrupts at high data rates, that the threshold should be the almost full FIFO. If polling mode is configured, the SSP I/O Access Library client calls an SSP I/O Access API function in order to read from the SSP I/O Unit receive FIFO for data.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 109
IP Telephony Software—SSP I/O Access Library Details
13.8
Control Path Control path in both polled and callback modes for the SSP I/O Access Library are illustrated in the Sequence Flow Diagrams in Section 13.10.
13.9
Data Path Data path in both polled and callback modes for the SSP I/O Access Library are illustrated in the Sequence Flow Diagrams in Section 13.10.
13.10
Sequence Flow Diagrams A Sequence Diagram shows the flow of messages, events and actions between the objects or components of a system. SSP I/O Access Library can be run in either Polled or Interrupt mode (hybrid combinations are not supported). Figure 45, “SSP I/O Access Library Interrupt Mode Sequence Flow” on page 111 and Figure 46, “SSP I/O Access Library Polled Mode Sequence Flow” on page 114 are sequence flow diagrams which demonstrate these modes. Note that the arrow directions indicate which components are calling other components.
13.10.1
Interrupt Sequence Flow The sequence flow for the interrupt mode is shown in Figure 45.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 110
May 2009 Order Number: 320415-003US
SSP I/O Access Library Details—IP Telephony Software
Figure 45.
SSP I/O Access Library Interrupt Mode Sequence Flow
C lie n t
S spA cc
S S P I/O U n it
init
ix_SSssppAAccccI nI nitit ic p s ps A c ccIcnIn it :itr: erteutrunr n icixp S _S pA
in t ia liz a tio n
I n t e r r u p t : R x F IF O H it H ig h T h r e s h o ld
Rx handler
R x F IF O In tr H a n d le r
icS p s_ pSAs cp cAFcIcFFOifD oD aR e iv ix a taatR e ce ec iv ee ic spp_AScscpFAIF c cOFDif o ce ix S aD ta aRt a eR c eeiv e iv : ree:t u r n R e tu rn
D a t a p r o c e s s in g R x F I F O I n t r H a n d le r : r e tu r n I n t e r r u p t: c le a r R x F IF O H it H ig h T h r e s h o ld
In te r r u p t: T x F I F O H it L o w T h r e s h o ld
Tx handler
T x F IF O In tr H a n d le r
ic c cI FFO if oDDa at at aSSu ub bmmitit ix pS_sS p sApcA cF icix p_ sp cF oD aS S Ss p A Ac c F I FifO D a tta Su b m m itit : rree ttuu rrnn
T x F I F O I n t r H a n d le r : r e t u r n
Rx FIFO Overrun handler
I n t e r r u p t: c le a r T x F IF O H it L o w T h r e s h o ld
I n t e r r u p t: R x F I F O O v e r r u n R x F IF O O v e r r u n H a n d le r
F ifo taeRc ee civeeiv e ixicSps_pSA scpc A F cI Fc O D aDt aaR pA e cee: ivr eet:u r n ix Sics pp _ A Sc cs F IFcOc F D ifo a taDRa etacR e iv R e tu rn
D a ta p r o c e s s in g / lo s s d a t a r e c o v e r y R x F I F O O v e r r u n H a n d le r : r e tu r n I n t e r r u p t: c le a r R x F I F O O v e r r u n
Uninit
ic p _ SixsSp sApcAc U c cnI in n itit U n in it ia liz a t io n u tu r nr n ic p _ixSSs sppAAc cc cUI n it in: itr:e rt e
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 111
IP Telephony Software—SSP I/O Access Library Details
1. Initialize SSP with all interrupts enabled, including Rx FIFO, Tx FIFO, and others shown in Figure 45. 2. For a receive: • Interrupt is triggered due to hitting or exceeding of configured Rx FIFO threshold • Due to Rx FIFO, the clients Rx FIFO handler/callback is called • Clients Rx FIFO handler/callback extracts data from the Rx FIFO • Client processes data extracted • Clients Rx FIFO handler/callback returns • Interrupt is cleared by SSP Note: — The Rx FIFO threshold is the number of entries in the Rx FIFO that triggers the Rx interrupt. It is set by the client. — The client must configure the threshold for the Rx FIFO. It is expected that the client reads all the data out of the Rx FIFO when the Rx callback is called. If all of the data is not read, there is a risk that overrun will occur. — The processing the client does with the data is independent from SSP and depends on the client application. 3. For a transmit: • Interrupt is triggered due to hitting or going below of threshold • Due to Tx FIFO, the clients Tx FIFO handler/callback is called • Clients Tx FIFO handler/callback inserts data into the Tx FIFO • Clients Tx FIFO handler/callback returns • Interrupt is cleared by SSP Note: — The client has enabled the Tx FIFO interrupt, therefore indicating that they have data to send. The interrupt indicates to the client that the next piece of data can be sent. When the client has no more data to send, they disable the Tx FIFO interrupt. — SSP I/O Access Library always checks that the amount of data to be sent can fit into the Tx FIFO. If the data cannot fit, the client receives a return fail. This prevents a Tx overrun scenario. 4. For an overrun: • Interrupt is triggered due to an overrun of the Rx FIFO • Due to Rx FIFO Overrun, the client Rx FIFO Overrun handler/callback is called • Clients Rx FIFO Overrun handler/callback extracts data from the Rx FIFO to prevent overrun from triggering again • Clients Rx FIFO Overrun callback may processes data extracted and perform necessary steps to recover data loss if possible. • Clients Rx FIFO Overrun handler/callback returns • Interrupt is cleared by SSP Note: — Overrun is an error condition and should not occur. However, it could occur on the Rx FIFO hardware, so it should be handled. For example, overrun may
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 112
May 2009 Order Number: 320415-003US
SSP I/O Access Library Details—IP Telephony Software
occur if there is a problem in the clients Rx callback, where all the data was not being read from the Rx FIFO. — SSP I/O Access Library does not provide any facilities to recover lost data. The client may have a higher level protocol for sending specific data (using SSP) to the external device that indicates lost data should be resent. 5. Un-initialize SSP.
13.10.2
Polled Mode Sequence Flow The sequence flow for the polling mode is shown in Figure 46. 1. Initialize SSP with SSP interrupts disabled 2. For a transmit: • Check if the Tx FIFO has hit or gone below its threshold • If it has, then insert data into the Tx FIFO 3. For a receive: • Check if the Rx FIFO has hit or exceeded its threshold • If it has, then extract data from the Rx FIFO • Process the data if needed 4. For an overrun: • Check if the Rx FIFO overrun has occurred • If it has, then extract data from the Rx FIFO • Process the data and recover any loss data if needed 5. Un-initialize SSP
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 113
IP Telephony Software—SSP I/O Access Library Details
Figure 46.
SSP I/O Access Library Polled Mode Sequence Flow
Client
SspAcc
init
ixSspAccInit icp_SspAccInit ixSspAccInit: return icp_SspAccInit: return
transmit
ixSspAccTxFIFOHitOrBelowThresholdCheck icp_SspAccTxFifoHitLowThresholdCheck icp_SspAccTxFifoHitLowThresholdCheck: return ixSspAccTxFIFOHitOrBelowThresholdCheck: return
icp_SspAccFifoDataSubm it ixSspAccFIFODataSubmit ixSspAccFIFODataSubmit: return icp_SspAccFifoDataSubmit: return
receive
ixSspAccRxFIFOHitOrAboveThresholdCheck icp_SspAccRxFifoHitHighThresholdCheck icp_SspAccRxFifoHitHighThresholdCheck: return ixSspAccRxFIFOHitOrAboveThresholdCheck : return
icp_SspAccFifoDataReceive ixSspAccFIFODataReceive icp_SspAccFifoDataReceive: Return ixSspAccFIFODataReceive : return
Rx FIFO overrun
Data processing
icp_SspAccRxFifoOverrunCheck ixSspAccRxFIFOOverrunCheck ixSspAccRxFIFOOverrunCheck: icp_SspAccRxFifoO verrunCheckreturn : return
ixSspAccFIFODataReceive icp_SspAccFifoDataReceive ixSspAccFIFODataReceive:Return return icp_SspAccFifoDataReceive:
Uninit
Data processing/ data loss recovery
icp_SspAccUninit ixSspAccInit ixSspAccInit: return icp_SspAccUninit:
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 114
May 2009 Order Number: 320415-003US
SSP I/O Access Library Details—IP Telephony Software
13.11
Resource Usage
13.11.1
Memory Requirements The amount of memory consumed by SSP I/O Access Library is negligible.
13.12
Operating System-Specific Issues The SSP I/O Access Library uses the OSAL component for OS services.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 115
IP Telephony Software—SSP I/O Access Library Details
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 116
May 2009 Order Number: 320415-003US
Part 2: Using the API This part of the document provides an overview of how to use the EP80579 IP Telephony software’s Acceleration APIs to build an application. Individual APIs are described in their corresponding reference manuals, which are listed in Table 1, “Related Documents” on page 14. The reference manuals contain details of the data structures, data types, function signatures, and other detailed constructs to allow you to call individual functions correctly. This part of the document is where you look to understand how to string such calls together to do something useful. The chapters in this part of the document are organized as follows: This section contains an overview of the following APIs: • Chapter 14.0, “Use Cases” • Chapter 15.0, “API Overview for HSS Voice Driver” • Chapter 16.0, “API Overview for HSS Data Driver” • Chapter 17.0, “API Overview for Analog FXO/FXS Driver” • Chapter 18.0, “API Overview for Framer Driver” • Chapter 19.0, “API Overview for SRTP Acceleration Driver” • Chapter 20.0, “API Overview for HSS I/O Access Library” • Chapter 21.0, “API Overview for SSP I/O Access Library”
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 117
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 118
May 2009 Order Number: 320415-003US
Use Cases—IP Telephony Software
14.0
Use Cases This chapter provides valuable insight for a programmer into how to write his/her application using the TDM I/O Interface as a means of passing traffic in and out of the system. The chapter provides details for setting up one of the following: • a Voice application using only the TDM I/O Interface • a PPP data application using only the TDM I/O Interface • an SRTP application using libSRTP and the SRTP acceleration provided on EP80579
14.1
What’s New in this Chapter No updates in this release.
14.2
Voice-Only Application Example In this example, the application is an TDM I/O only voice application. Voice channels are set up to receive and transmit samples over the TDM I/O interface. Received voice samples are passed up to the Media Acceleration library (or customer application) which processes them in any way it chooses. The Media Acceleration Library (or customer application) submits Voice samples for transmission over the TDM I/O via the HSS Voice Driver. The bullet points below illustrate the diagram in Figure 47. • 1.1 TDM Setup Driver The TDM Setup Driver is responsible for initialization of all access components. It must be loaded as the first step of the initialization process. It calls the relevant initialization functions including the HSS I/O Access library initialization as detailed in Section 20.2.1.1, “Component Initialization”. The TDM Setup Driver also downloads the Programmable I/O Unit (PIU) firmware to the unit using the PIU Infrastructure DL. • 2.1 ... 2.3 HSS Voice driver load and TDM I/O Configuration Once the TDM Setup Driver is loaded, the media acceleration library (or customer application) loads the HSS Voice Driver and sets up the appropriate TDM resources it requires as described in Section 15.3.1, “Setup Sequence”. This leads to the HSS I/O Access library being configured with all channels configured for Voice traffic only. See Section 20.2.1.2, “Port Configure Functions”, Section 20.2.1.3, “Channel Configure” and Section 20.2.1.4, “Channel Callback Register” for details. • 3.1 ... 3.3 Peripherals setup Once the TDM I/O resources have been successfully allocated, the peripherals must be configured to match the TDM resources allocated. The Analog FXO/FXS Driver is first loaded, then configured. Details on how to do so are found in Section 17.3.2.1, “Initialization” and Section 17.3.2.2, “PCM Configuration”. • 4.1 Data Flow enable At this point, the flow of data on Transmit and Receive is enabled via the HSS Voice driver (see Section 15.3.1.4, “Channel Enabling”) which waterfalls down to the HSS I/O Access library (see Section 20.2.2, “Channel Up”).
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 119
IP Telephony Software—Use Cases
• Transmitting and receiving Once Flow is enabled, the Media Acceleration library (or customer application) is free to receive and transmit voice samples over the TDM interface using the HSS Voice driver as detailed in Section 15.4.2, “Read” and Section 15.4.3, “Write”. These actions waterfall down the HSS I/O Access library Section 12.2.1, “Transmit to Channel” and Section 12.2.3, “Receive from Channel” scenarios. Figure 47.
Voice-Only Application Architecture
C ustom er A pplication/M edia A cceleration Library
2.1 2.2 2.3 4.1
Load V oice driver Initialize H S S P ort A llocate channels E nable channels
Intel® E P 80579
3.1 Load S LIC /C O D E C driver 3.2 Initialize 3.3 C onfigure P C M
1.1 Load TD M S etup D river
U ser S pace K ernel S pace LSP
OS
TD M S etup D river
H S S V oice D river
O S AL bufferM gm t Log irq
2.1.1 Initialize H S S P ort 2.2.1 A llocate channels 4.1.1 E nable channels
A N A LO G FX O FX S D R IV E R
1.2 Initialize all com ponents 1.3 D ow nload P IU firm w are
A ccess Libraries H SS I/O A ccess Layer
m em ory
PIU M essage H andler
Thread
P IU D ow nloader
S SP I/O A ccess Layer
PIU QMGR
P rogram m able I/O U nit (P IU )
H -M V IP B ackplane (D ata)
S P I Interface (C ontrol)
S LIC /C O D E C s
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 120
May 2009 Order Number: 320415-003US
Use Cases—IP Telephony Software
14.3
Data-Only Application Example In this example, a customer application uses the TDM I/O interface to transmit and receive PPP data. The bullets below provide a detailed overview of Figure 48 which covers the different modules required for such an application to function correctly. • 1.1 TDM Setup Driver The TDM Setup Driver is responsible for initialization of all access components. it must be loaded as a first step of the initialization process. It calls the relevant initialization functions including the HSS I/O Access library initialization as detailed in Section 20.2.1.1, “Component Initialization”. The TDM Setup Driver also downloads the Programmable I/O Unit (PIU) Firmware to the unit using the PIU Infrastructure DL. • 2.1 ... 2.3 HSS Data driver load and TDM I/O Configuration Once the TDM Setup Driver is loaded, the customer data application loads the HSS Data Driver and sets up the TDM resources it requires as detailed in Section 16.3.1, “Setup Sequence” and Section 16.3.1.3, “Channel Adding”. This leads to the HSS I/O Access library being configured with all configured channels allocated for Data traffic only. See Section 20.2.1.2, “Port Configure Functions”, Section 20.2.1.3, “Channel Configure”, and Section 20.2.1.4, “Channel Callback Register” for details. • 3.1 ... 3.3 Peripherals setup Once the TDM I/O resources have been successfully allocated, the peripheral framer is set up to match the TDM resources allocated. First the Framer Driver is loaded, then configured. For details, refer to Section 18.3.1.1, “Initialization” and Section 18.3.1.2, “Configuration”. • 4.1 Data Flow enable At this point, the Flow of data on Transmit and Receive is enabled via the Data driver (see Section 16.3.1.4, “Channel Enabling”) which waterfalls down to the HSS I/O Access library (see Section 20.2.2, “Channel Up”). • Transmitting and receiving Once Flow is enabled, the customer data application is free to receive and transmit PPP packets over the TDM interface using the Data driver as detailed in Section 16.4.1, “Write” and Section 16.4.2, “Read”. These actions waterfall down the HSS I/O Access library Section 12.2.1, “Transmit to Channel” and Section 12.2.3, “Receive from Channel” scenarios.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 121
IP Telephony Software—Use Cases
Figure 48.
Data-Only Application Architecture
Intel® EP80579
Customer Application
2.1 Load Data driver 2.2 Initialize HSS Port 2.3 Allocate channels 4.1 Enable channels
3.1 Initialize 3.3 Configure 1.1 Load TDM Setup Driver
Framer Driver
User Space Kernel Space LSP
OS
OSAL bufferMgmt Log irq
2.1.1 Initialize HSS Port 2.2.1 Allocate channels 4.1.1 Enable channels
Framer Infrastructure Driver
TDM Setup Driver
HSS Data Driver
1.2 Initialize all components 1.3 Download PIU firmware
Access Libraries HSS I/O Access Layer
PIU Downloader
memory
PIU Message Handler
Thread
PIU QMGR
Programmable I/O Unit (PIU)
H-MVIP Backplane (Data)
Expansion Bus (Control)
E1/T1 Framer
14.4
Secure Voice over IP using SRTP In this scenario, the customer application uses the Cryptography services and the SRTP Acceleration functionality provided on EP80579 to enable secure Voice over IP. One possibility is to use the patched version of the open source SRTP library called libSRTP. A patch for libSRTP is provided as part of the Voice package. The customer application uses the libSRTP API to make the RTP packets transporting Voice secure. Details of the cryptography services required for this application are outside of the scope of this document and can be found in the Intel® EP80579 Software for Security Applications on Intel® QuickAssist Technology Programmer’s Guide [SEC_PROG_GD].
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 122
May 2009 Order Number: 320415-003US
Use Cases—IP Telephony Software
The bullet points below illustrate the diagram in Figure 49: • 1.1 Application creates an RTP Session. To protect this session, the application also opens a libSRTP session. libSRTP is responsible for creating an SRTP acceleration session using the Section 19.4.1.1, “Open” functionality. • 2.1 The user application creates an SRTP stream. libSRTP is responsible for creating an SRTP accelerated stream using the API described in Section 19.4.1.2, “Stream Configuration”. • 3.1 For each RTP packet to protect or unprotect, the user application calls the libSRTP which in turn exercises the API described in Section 19.5.1, “Crypto Operation”. • 4.1 The Cryptographic API services notifies the SRTP Acceleration driver when the operation is complete. This notification is passed up the stack to libSRTP and, in turn, to the user application. See Section 19.5.1, “Crypto Operation” for details. • 5.1 When the RTP stream expires (max RTP packets for the stream reached, for example), the user application closes the SRTP stream using libSRTP, which in turn exercises the API described in Section 19.4.2.1, “Release”. • 6.1 When the RTP session expires (call ended, for example), the user application uses libSRTP to close the secure RTP session. This in turn closes the SRTP acceleration driver as described in Section 19.4.2.1, “Release”.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 123
IP Telephony Software—Use Cases
Figure 49.
Secure Voice over IP using SRTP Application Architecture
Intel® EP80579
User Space Application
1.1 Create sRTP Session 2.1 Create sRTP stream 3.1 Protect / Unprotect RTP packet 5.1 Close sRTP Stream 6.1 Close sRTP Session
4.3 Operation Complete
Customer Application (libSRTP)
1.2 Open driver 2.2 Create sRTP stream 3.2 Do Operation 5.2 Close sRTP Stream 6.2 Close driver
4.2 Operation Complete
User Space Kernel Space sRTP Acceleration Driver
2.3 Create Crypto Session 3.3 Do Operation 5.3 Close Crypto Session LSP
4.1 Operation Complete
OS
InfraStructure
Cryptographic API Services
ASU
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 124
May 2009 Order Number: 320415-003US
API Overview for HSS Voice Driver—IP Telephony Software
15.0
API Overview for HSS Voice Driver
15.1
What’s New in this Chapter No updates in this release.
15.2
Overview The HSS Voice Driver is a Linux* device driver. It presents a Linux character device driver interface. The specific Linux character device driver methods that are implemented are listed in Table 19.
Table 19.
HSS Voice Driver Interface Summary Method
Description
open
Initialize the HSS Voice Driver. Allocate resources.
release
Free resources.
ioctl
Used to issue commands such as bringing a port/channel up/down.
poll
Used by the client to know whether read() will block.
read
Used by the client to read data from the device.
write
Used by the client to write data to the device.
An API reference manual for the HSS Voice driver is contained in [DRIVERS_API_REF].
15.3
Control Path The Control Path Setup and Shutdown API sequences are explained in the following sections and can be seen in Figure 50.
15.3.1
Setup Sequence
15.3.1.1
Open open() is called by the client from user space. The file name is "/dev/hss-voice".
15.3.1.2
Port Setup Port setup is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_PORT_UP ioctl command. This sets up the HSS port. The port, predefined port configuration number and loopback mode are specified by the client.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 125
IP Telephony Software—API Overview for HSS Voice Driver
15.3.1.3
Channel Adding Adding a channel is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_CHAN_ADD ioctl command. The new channel number, port, and details of the channel are specified by the client.
15.3.1.4
Channel Enabling Enabling a channel is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_CHAN_UP ioctl command. The channel to enable is specified by the client.
15.3.1.5
Channel Bypass Enabling This optional step routes the receive stream on one channel to the transmit stream on another channel. It is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_CHAN_BYPASS ioctl command.
15.3.2
Shut Down Sequence
15.3.2.1
Channel Disabling Disabling a channel is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_CHAN_DOWN ioctl command. The channel to disable is specified by the client.
15.3.2.2
Channel Removal Removing a channel is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_CHAN_REMOVE ioctl command. The channel number is specified by the client.
15.3.2.3
Port Shutdown Port shutdown is performed by a call to the ioctl() method with the ICP_HSSVOICEDRV_PORT_DOWN ioctl command. This shuts down the HSS port. The port is specified by the client.
15.3.2.4
Release The release() method is called by the client from user space.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 126
May 2009 Order Number: 320415-003US
API Overview for HSS Voice Driver—IP Telephony Software
Figure 50.
HSS Voice Driver High-Level API Control Path
1. open() 14. release()
HSS Voice Client
2. ioctl(...,ICP_HSSVOICEDRV_PORT_UP,...) 4. ioctl(…,ICP_HSSVOICEDRV_CHAN_ADD,...) 6. ioctl(…,ICP_HSSVOICEDRV_CHAN_UP,...) Data Flow 8. ioctl(…,ICP_HSSVOICEDRV_CHAN_DOWN,...) 10. ioctl(…,ICP_HSSVOICEDRV_CHAN_REMOVE,...) 12. ioctl(...,ICP_HSSVOICEDRV_PORT_DOWN,...)
Linux User Space Linux Kernel Space
HSS Voice Driver
3. Configure and enable HSS port 5. Allocate, configure and add a voice channel 7. Bring the voice channel up Data Flow 9. Bring the voice channel down 11. Delete the voice channel 13. Bring the HSS port down
HSS I/O Access Library
15.4
Data Path The Data Path API is explained in the following sections and can be seen in Figure 51.
15.4.1
Poll The poll() method is called by the client from user space. It is used to indicate to the client whether data can be read from the device without blocking. In the HSS Voice Driver, the poll method may only be called in when in blocking mode.
15.4.2
Read The read() method is called by the client from user space. It is used to read voice data from the device. It can operate in either blocking or non-blocking mode. The HSS Voice Driver embeds the voice channel ID with the voice samples.
15.4.3
Write The write() method is called by the client from user space. It is used to write voice data to the device. The client embeds the voice channel ID with the voice samples.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 127
IP Telephony Software—API Overview for HSS Voice Driver
Figure 51.
HSS Voice Driver High-Level API Data Path
H S S V oice C lient
1. read() 3. w rite()
Linux U ser S pace Linux K ernel S pace
H S S V oice D river
2. C all H S S I/O A ccess Library to read from the relevant voice channels 4. C all H S S I/O A ccess Library to w rite to the relevant voice channels
H S S I/O A ccess Library
15.5
Dependencies Figure 52 shows the dependencies and external interactions of the HSS Voice Driver. The Media Processor is expected to be the most used client to the HSS Voice Driver.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 128
May 2009 Order Number: 320415-003US
API Overview for HSS Voice Driver—IP Telephony Software
Figure 52.
HSS Voice Driver Dependencies Client (Media Processor) user space
HSS Voice Driver
HSS I/O Access Library
OSAL kernel space hardware TDM interface
15.6
Error Handling The HSS Voice Driver does not provide a callback mechanism for errors. Instead it returns standard Linux character device driver error codes to the client when it encounters an error.
15.7
Key Assumptions None.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 129
IP Telephony Software—API Overview for HSS Voice Driver
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 130
May 2009 Order Number: 320415-003US
API Overview for HSS Data Driver—IP Telephony Software
16.0
API Overview for HSS Data Driver
16.1
What’s New in this Chapter No updates in this release.
16.2
Overview The HSS Data Driver is a Linux* Serial TTY driver. It presents a Linux synchronous serial device driver interface. The specific Linux TTY device driver methods that are implemented are listed in Table 20.
Table 20.
HSS Data Driver Interface Summary Method
Description
open
Initialize the HSS Data Driver. Allocate resources.
close
Free resources.
ioctl
Used to issue commands such as bringing a port/channel up/down.
write
Used by the client to write data to the device.
An API reference manual for the HSS Data driver is contained in [DRIVERS_API_REF].
16.3
Control Path The Control Path Setup and Shutdown API sequences are explained in the following sections and can be seen in Figure 53.
16.3.1
Setup Sequence
16.3.1.1
Open The open() method is called by the client from user space. The file name “/dev/hssdataN”, is used, where N distinguishes on a per channel basis. On a first call the driver allocates all resources needed.
16.3.1.2
Port Setup Port setup is performed by the first call to the ioctl() method with the ICP_HSSDATADRV_PORT_UP ioctl command. This sets up the HSS port. This is only performed before the first channel is configured. The port, predefined port configuration number, and loopback mode are specified by the client. The client has to pass as ioctl argument the address of the structure where the port configuration has been set (“icp_hssdrv_portup_t“ structure type).
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 131
IP Telephony Software—API Overview for HSS Data Driver
16.3.1.3
Channel Adding Adding a channel is performed by a call to the ioctl() method with the ICP_HSSDATADRV_CHAN_ADD ioctl command. The new channel number, port, and details of the channel are specified by the client. The client has to pass as ioctl argument the address of the structure where the channel configuration has been set (“icp_hssdatadrv_channeladd_t“ structure type).
16.3.1.4
Channel Enabling Enabling a channel is performed by a call to the ioctl() method with the ICP_HSSDATADRV_CHAN_UP ioctl command. The channel to enable is specified by the client. The client is not required to specify any argument in the ioctl call, as there is a one-to-one relationship between the channels and the file descriptor specified for the ioctl (that is, only one channel can be associated to a file descriptor and vice-versa).
16.3.1.5
Connect Channel to Linux PPP Subsystem As soon as the HSS Data Driver kernel module is inserted, 128 serial devices are registered and they appear as device files into the “/dev/” directory. The devices are registered with the names “hss-dataN”, where N can vary from 0 to 127 according to the device it refers to. The kernel is not aware of the status of the devices, that is, every device is registered whether there is any HDLC channel associated with it or not and, if any, regardless of the status of the channel itself. Therefore, it is the user’s responsibility to associate an HDLC channel to the desired serial device and to enable that channel before establishing the PPP connection (before calling the PPP Daemon). The following example assumes that the remote peer is able to reply to the PPPD connection requests by receiving/sending LCP (Link Control Protocol) packets. An example of PPPD command line is the following: pppd /dev/hss_data0 defaultroute mru 1024 mtu 1024 192.168.0.1:192.168.1.1 sync updetach
where the mandatory options are:
Note:
/dev/hss_data0
path specifying the device that has to be used in this PPP connection.
defaultroute
see PPPD man page for details
mru 1024 mtu 1024
specifies the Maximum Receiving Unit and the Maximum Transmitting Unit sizes, respectively. They have to be set to the same value as the one that is defined in the HSS Data Driver C source file (the defined value is “DEFAULT_MTU_MRU“ and in our example is set to 1024).
192.168.0.1:192.168.1.1
two IP addresses which refer to the local peer and the remote one, respectively.
sync
specifies that the serial device used for this connection communicates with the corresponding PPP channel using a synchronous serial line discipline. It makes the PPPD call the synchronous PPP kernel subsystem to register a synchronous PPP channel for this connection to interface with the underlying TTY serial device. This option is critical because, by default, the PPPD expects to communicates with an underlying async TTY device. As a consequence, if not set, the PPP connection will fail.
updetach
this option is needed to avoid that PPPD sets itself as the controlling process for the specified TTY device. If this option is not set, once the PPPD process is killed, the user will not be able to call any ioctl for this device. As a result, the user cannot disable and remove the HDLC channel associated with the device.
Refer to the PPPD man page for details about more features (such as authentication and compression), however, you must not use any option that conflicts with the mandatory options described above.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 132
May 2009 Order Number: 320415-003US
API Overview for HSS Data Driver—IP Telephony Software
16.3.2
Shut Down Sequence
16.3.2.1
Disconnect Channel from Linux PPP Subsystem To close a PPP link, you must kill the PPPD process that is associated with the link itself. Once the process is killed, the HDLC channel associated with the device used by that process will still be enabled. At this stage, you can use this device to bring up another PPP link or choose to bring down the HDLC channel. To disable and remove the channel, you must write your own code and run the corresponding executable according to the following ioctl commands.
16.3.2.2
Channel Disabling Disabling a channel is performed by a call to the ioctl() method with the ICP_HSSDATADRV_CHAN_DOWN ioctl command. The channel to disable is specified by the client. The client is not required to specify any argument in the ioctl call, because there is a one-to-one relationship between the channels and the file descriptor specified for the ioctl (i.e. only one channel can be associated to a file descriptor and vice-versa).
16.3.2.3
Channel Removal Removing a channel is performed by a call to the ioctl() method with the ICP_HSSDATADRV_CHAN_REMOVE ioctl command. The channel number is specified by the client. The client is not required to specify any argument in the ioctl call, because there is a one-to-one relationship between the channels and the file descriptor specified for the ioctl (i.e. only one channel can be associated to a file descriptor and vice-versa).
16.3.2.4
Port Shutdown Port shutdown is performed by a call to the ioctl() method with the ICP_HSSDATADRV_PORT_DOWN ioctl command. This shuts down the HSS port. This is only performed after the all channels have been removed. The port is specified by the client. This is only required if there are no more PPP channels.
16.3.2.5
Close The close() method is called by the client from user space. On a last call, the driver deallocates all resources.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 133
IP Telephony Software—API Overview for HSS Data Driver
Figure 53.
HSS Data Driver High-Level API Control Path 1. open() 17. close() 2. ioctl (ICP_HSSDATADRV_PORT_UP,...) 4. ioctl (ICP_HSSDATADRV_CHAN_ADD,...) 6. ioctl (ICP_HSSDATADRV_CHAN_UP,...) pppd
8. Attach channel to Linux PPP subsystem
HSS Data Client
10. Kill pppd for the channel
11. ioctl (ICP_HSSDATADRV_CHAN_DOWN,...) 13. ioctl (ICP_HSSDATADRV_CHAN_REMOVE,...) 15. ioctl (ICP_HSSDATADRV_PORT_DOWN,...)
Linux User Space Linux Kernel Space 9. Data Flow Linux PPP subsystem
HSS Data Driver
kernel 9. Data Flow
3. Configure and enable HSS port 5. Allocate, configure and add a data channel 7. Bring the data channel up 9. Data Flow
HSS I/O Access Library
16.4
12. Bring the data channel down 14. Delete the data channel 16. Bring the HSS port down
Data Path The HSS Data driver data path is into the Linux PPP subsystem. This is illustrated in Figure 54.
16.4.1
Write A write() method is implemented. The Linux PPP subsystem injects frames for transmission by calling this method.
16.4.2
Read A read() method is not implemented. The HSS Data Driver passes frames from the HSS Access Library to the Linux PPP subsystem by calling the receive_buf() method.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 134
May 2009 Order Number: 320415-003US
API Overview for HSS Data Driver—IP Telephony Software
Figure 54.
HSS Data Driver High-Level API Data Path Li nux Ker nel Space 2. write()
1. wr i t e( ) TTY Sync Di sci pl i ne
Ge n e r i c P P P
HSS Dat a Dr i ver 3. recei ve_buf ()
4. ppp_input()
HSS I / O Access Li brary
16.5
Dependencies The HSS Data Driver depends on the following external components, shown in Figure 55: • HSS I/O Access Library • OSAL (required for the buffer format) • Linux PPP subsystem (requires Linux kernel compiled with PPP support, including the synchronous TTY discipline) • Linux PPPD (required to manage the negotiation to establish the PPP connection)
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 135
IP Telephony Software—API Overview for HSS Data Driver
Figure 55.
HSS Data Driver Dependencies
PPP Daemon PP
user space
p
Linux PPP subsystem
HSS Data Driver
HSS I/O Access Library
OSAL kernel space hardware TDM interface
16.6
Error Handling The HSS Data Driver does not provide a mechanism to return a standard Linux TTY serial device driver error code to the client when it encounters an error. Instead ,it implements a callback mechanism. The user must look into “/var/log/messages” or call “dmesg” to check that no errors have occurred.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 136
May 2009 Order Number: 320415-003US
API Overview for Analog FXO/FXS Driver—IP Telephony Software
17.0
API Overview for Analog FXO/FXS Driver The Analog FXO/FXS Driver Linux* user space interface conforms to the Linux character device driver model. As such it implements a standard Linux character device driver API. The Analog FXO/FXS Driver is used to initialize, configure and facilitate event reporting for external FXO/FXS devices.
17.1
What’s New in this Chapter No updates in this release.
17.2
Overview The development board facilitates connection of an Analog Voice Card through the mezzanine connectors. Each Analog Voice Card has 4 SLIC/CODEC (FXS) devices and 1 DAA (FXO) device. Each FXO/FXS device controls one POTS line. The Analog FXO/FXS Driver implements the interfaces listed in Figure 21.
Table 21.
Analog FXO/FXS Driver Interface Summary Operation
17.3
Description
Open
Opens the device file
Release
De-allocates all resources
Ioctl
Used for initialization and configuring of the FXO/FXS devices
Read
Used for receiving device events from the FXO/FXS devices
Control Path The following sequences show the steps necessary to use the Analog FXO/FXS Driver API to initialize, configure and monitor Analog FXO/FXS devices on an Analog FXO/FXS card.
Note:
This assumes that the Analog FXO/FXS Driver has been successfully loaded into the kernel. The steps shown are for one Analog FXO/FXS card. These steps must be repeated for another Analog FXO/FXS card if required. Figure 56 illustrates the control path API steps.
17.3.1
Setup Sequence
17.3.2
Open The open() method is called by the client from user space. The file name is “/dev/ analog-fxo-fxs”.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 137
IP Telephony Software—API Overview for Analog FXO/FXS Driver
17.3.2.1
Initialization When an ioctl() call is made with the ICP_ANALOGDRV_INIT command, the following tasks are performed: • Initialization of communication with the Analog FXO/FXS card inserted in a mezzanine slot on the development board • Allocation of memory needed for device event buffering • Interrupts for the Analog FXO/FXS cards are bound • SLIC/CODEC devices on the Analog FXO/FXS card have their geo-specific characteristics set, for example, Ring cadence
17.3.2.2
PCM Configuration Configuration of the PCM characteristics of a SLIC/CODEC or DAA device is done using an ioctl() call with the ICP_ANALOGDRV_PCM_CONFIG_SET command. This sets the PCM format etc. for the FXO/FXS device, for example, A-Law.
Figure 56.
Analog FXO/FXS Driver Initialization and Configuration Flow
1 .o p e n ( )
Analog FXO/FXS Client
2. ioctl(...,ICP_ANALOGDRV _INIT,...) 4. ioctl(…,ICP_ANALOGDRV _PCM _CONFIG _SET,...)
Linux User Space Linux Kernel Space
Analog FXO/FXS Device Driver
3. Initialisation of the slot / interrupts 5. Write to the FXO/FXS device to s et the PC M ch a ra c te ristic s.
SSP I/O Access Library
SSP I/O Unit
SLIC/CODEC or DAA on Analog FXO/FXS card
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 138
May 2009 Order Number: 320415-003US
API Overview for Analog FXO/FXS Driver—IP Telephony Software
17.3.3
Event Monitoring In order to monitor events that the SLIC/CODEC or DAA devices generate, the read() method is called by the client to retrieve the events.
17.3.4
FXO/FXS Commands Sending of a signalling command to SLIC/CODEC or DAA devices is done using the appropriate ioctl() call. Several ioctl() commands are provided for generic functionality such as ringing a phone, or indicating to the central office that a phone has gone off hook.
Figure 57.
Analog FXO/FXS Driver Event Handling and Command Flow
Event Handling Analog FXO/FXS Client
1.read(...)
Command 3.ioctl(...,ICP_ANALOGDRV_RING_ON,...)
Linux User Space Linux Kernel Space
Analog FXO/FXS
2.Write to the SLIC/CODEC device register to turn ringing on
Device Driver 4.(Blocking mode) Wait until there is an event and return in the read call
SSP I/O Access Library
SSP I/O Unit
SLIC/CODEC or DAA on Analog FXO/FXS card
17.3.5
Shutdown Sequence
17.3.5.1
Release The client closes the “/dev/analog-fxo-fxs” file. This causes the Analog FXO/FXS Driver to deallocate the memory used for device event monitoring buffers.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 139
IP Telephony Software—API Overview for Analog FXO/FXS Driver
17.4
Data Path There is no data path in the Analog FXO/FXS device driver. Data is transferred directly from the Analog FXO/FXS card to the TDM line.
17.5
Dependencies The Analog FXO/FXS Device Driver has dependencies on: • Linux kernel - used for registering as a character device driver and other OS services • SSP I/O Access Library - used to send data to the SSP I/O Unit
Figure 58.
Analog FXO/FXS Driver Dependencies
Client
user space kernel space
Analog FXS/FXO Driver
Linux kernel
SSP I/O Access Library
17.6
Key Assumptions None.
17.7
Error Handling Error Handling is achieved by return codes from ioctl() calls.
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 140
May 2009 Order Number: 320415-003US
API Overview for Framer Driver—IP Telephony Software
18.0
API Overview for Framer Driver The Framer Driver is used to initialize, configure and facilitate event reporting for an external Framer Device. The Framer Driver is a Linux* user space device control application.
18.1
What’s New in this Chapter No updates in this release.
18.2
Overview The development board facilitates connection of a Framer Card through the mezzanine connectors. Each Framer Card has 1 Framer device that controls 4 external E1/T1 lines.
18.3
Control Path The following sequences show the steps necessary to use the Framer Driver API to initialize, configure and monitor a Framer device. Note, this assumes that the Framer Driver has been successfully loaded into the kernel. The steps shown are for one Framer Device. These steps must be repeated for another Framer device if required. Figure 59 illustrates the control path API steps.
18.3.1
Setup Sequence
18.3.1.1
Initialization Initializes communication with the Framer card inserted in a mezzanine slot on the development board. Any memory need for device event buffering is allocated at this stage.
18.3.1.2
Configuration The client uses the configuration set function to set the following for a framer device: • External line type • Signaling • Encoding • Framing • Backplane mode
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 141
IP Telephony Software—API Overview for Framer Driver
18.3.2
Device Event Reporting The client uses a bitmask to indicate which Framer device events (e.g. Loss of signal, Loss of frame alignment) it wishes to receive notifications for. The device event along with the associated Framer device and external E1/T1 line are passed to the client when the client reads from the driver.
Figure 59.
Framer Driver High Level API Control Path
Framer Driver Client
Framer Driver
1 . I ni t i al i z e f ra me r 3 . Se t t h e co n f i gu r a t i on 6 . Re a d
2. Initialize communication with the Framer Device and allocate memory. 5. Configure the Framer Device. Allocate memory for event reporting. 7. Copy device events to the client provided user space buffer.
Linux User Space Linux Kernel Space Framer Infrastructure Driver
Expansion bus hardware
Framer Device on Framer Mezzanine card
18.4
Data Path The Framer Driver does not implement a data path. Data path communication with the Framer device is done via the HSS drivers.
18.5
Dependencies The Framer Driver has dependencies on the following: • Linux kernel - used for OS services • EP80579 Expansion bus hardware - used for communication with the external Framer device
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 142
May 2009 Order Number: 320415-003US
API Overview for Framer Driver—IP Telephony Software
• Framer Infrastructure Driver - is used to return framer events to the framer driver. Figure 60.
Framer Driver Dependencies
C lie n t
F ra m e r D riv e r user space k e rn e l s p a c e
L in u x k e rn e l F ra m e r In fra s tru c tu re D riv e r
E x p a n s io n B u s H a rd w a re
18.6
Key Assumptions None.
18.7
Error Handling For Initialization and configuration, errors are reported to the client though the return values of the API calls. Events, which can be alarm or error conditions, from the Framer device are returned to the client through the read call. Statistics regarding error conditions are available to the client by using the stats get call.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 143
IP Telephony Software—API Overview for Framer Driver
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 144
May 2009 Order Number: 320415-003US
API Overview for SRTP Acceleration Driver—IP Telephony Software
19.0
API Overview for SRTP Acceleration Driver
19.1
What’s New in this Chapter This chapter has been updated to include the new Asynchronous operation of the SRTP Acceleration Driver.
19.2
Overview The SRTP Acceleration Driver is a Linux* device driver. It presents a Linux character device driver interface. The specific Linux character device driver methods that are implemented are listed in Table 22.
Table 22.
SRTP Acceleration Driver Interface Summary Method
19.3
Description
open
Initialize the SRTP Acceleration Driver. Allocate resources. Allocate a SRTP Session.
release
Free resources. Remove a Session.
ioctl
Used to issue commands such as encryption operations/adding a stream/removing a stream/random number generation.
read
Used to read a packet from the SRTP Acceleration Driver. Used to complete an operation and retrieve an encrypted packet.
write
Used to write a packet to the SRTP Acceleration Driver. Used when submitting a packet for encryption/decryption.
SRTP Stream and Cryptographic API Session Association Chapter 9.0, “SRTP Acceleration Overview” explains that an SRTP session contains many SRTP streams. However, the Cryptographic API does not operate in this manner, it only defines Sessions. These Cryptographic API sessions are in fact equivalent then to SRTP streams. It is the responsibility of the SRTP application to keep track of SRTP sessions. The SRTP Acceleration Driver will only account for SRTP streams. For details, see Section 10.4, “Stream Establishment” on page 79. The link between the SRTP stream and the Cryptographic API session is an internal Stream ID. It is the responsibility of the SRTP Acceleration Driver to supply each stream with a unique stream ID. The SRTP application keeps track of SRTP Accelerated Streams by the file descriptor used when opening a new SRTP Acceleration Stream.
Note:
The Synchronization source identifier (SSRC) is not used to identify streams as there can be a situation where several streams use the same SSRC, as in the case with multicast, and the SRTP Acceleration Driver is required to identify each stream individually.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 145
IP Telephony Software—API Overview for SRTP Acceleration Driver
19.4
Control Path The Control Path Setup and Shutdown API sequences are explained in the following sections and can be seen in Figure 61.
19.4.1
Setup Sequence
19.4.1.1
Open open() is called by the SRTP application from user space. The file name is "/dev/ srtp_acc_drv".
19.4.1.1.1
Session Establishment Stream establishment is automatically done when the SRTP application uses the open() system call. Each stream is identified by its unique file descriptor and a unique identifier number. The identification number is stored in the private member area of the Driver FILE struct. This number is used to keep count of the number of file descriptors and hence the number of streams currently active in the SRTP Acceleration Driver.
19.4.1.2
Stream Configuration Configuring a stream is performed by a call to the ioctl() method with the SRTP_ACC_STREAM_CONFIG ioctl command. The new stream identifier and details of the operation to be performed in that stream (cipher profile) are provided by the SRTP application.
19.4.1.2.1
Cryptographic API Initialization The call to configure the SRTP stream via the ioctl() is used to check and ensure the Cryptographic API is initialized and is ready to process requests. If it is not initialized, then the SRTP driver should not continue.The SRTP Acceleration Driver checks to see if the Cryptographic API is operating by calling it. If the Cryptographic API is not operational, then an error is returned to the SRTP Acceleration Driver. When this occurs, the SRTP Acceleration Driver handles this error and returns gracefully.
19.4.2
Shut Down Sequence
19.4.2.1
Release The release() method is called by the client from user space.
19.4.2.1.1
Stream Removal By passing the unique file descriptor to the release() function, this forces the shutdown of the associated SRTP Stream with that file descriptor. If any packets are currently in flight when the release() call is invoked, they are deleted. See Section 10.5, “Stream Removal” on page 81 for more detail on removing a SRTP stream.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 146
May 2009 Order Number: 320415-003US
API Overview for SRTP Acceleration Driver—IP Telephony Software
Figure 61.
SRTP Acceleration Driver High-Level API Control Path
1. open() 4. Release()
SRTP Application
2. ioctl(…, SRTP_ACC_STREAM_CONFIG, …)
User Space Kernel Space
3. Configure and initiate Crypto API session SRTP Driver
19.5
5. Deregister Crypto API session
Data Path The Data Path API is explained in the following sections and can be seen in Figure 62. The Data path is now an asynchronous path, with two system calls to complete an operation. Note that the SRTP Acceleration Driver provides both a blocking and nonblocking mode of operation.
19.5.1
Crypto Operation Performing an encrypt/decrypt operation is done by two calls. The first is a write call to the device file and the second is a read call on the device file. The crypto operation to perform is supplied by the SRTP application. Valid operations are: • encrypt • decrypt • authenticate • encrypt & authenticate • decrypt & authenticate Figure 62 shows a high-level view of the API data path. The write() call is used to initiate the crypto operation, and the read() call is used to complete the operation. In the write call, the SRTP driver initiates the relevant structures which define all the required information to perform a particular crypto operation. Once this is complete, the SRTP Acceleration Driver then requests the Cryptographic API component to perform the selected operation. The SRTP Acceleration Driver then returns from the write() call immediately. The SRTP application is then free to start other processing, including starting another operation via the write() call. The Cryptographic API performs the requested operation and initiates the associated callback function once complete. The callback function then places the encrypted/ decrypted packet onto the stream’s read queue and wakes up any process waiting on it. The SRTP application must then call the read() system call on the device file. The SRTP Acceleration Driver provides both a blocking and non-blocking mode of operation. The default method is to block. In this way, if there are no packets to be read, the SRTP Acceleration Driver forces the reading application to wait for the operation to be completed. Once there are completed packets on the stream’s read queue, the SRTP
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 147
IP Telephony Software—API Overview for SRTP Acceleration Driver
Acceleration Driver then removes the packet from the read queue and copies the resultant encrypted/decrypted packet along with any additional information (authentication tag placed directly after the packet) to the user space buffer.
19.5.2
Random Number Generation Generating a random number can be performed by the ioctl() method with the SRTP_ACC_RANDNUM_GEN ioctl command. The length of the random number to generate is supplied by the SRTP application. The buffer where the generated random number is to be stored must also be supplied by the SRTP application. Similar to the crypto operation, the Cryptographic API is requested to perform the operation. The ioctl call will then block waiting for the Cryptographic API to complete the operation. Once the Cryptographic API has performed the requested operation, in this case generating a random number, it calls the associated internal callback function. The internal callback function returns the completion. The SRTP Acceleration driver then copies the resultant data back to the SRTP application in user space and unblocks the ioctl call.
19.5.3
Write The write() system call is used to submit an SRTP accelerated packet to the SRTP Acceleration Driver and commence a cryptographic operation.The parameter should be a pointer to a structure of type srtp_acc_packet_t. This structure contains all relevant information about the operation to perform, including the initialization vector. This function will return -1 on error and set errno to the appropriate value.
19.5.4
Read The read() system call is used to complete an operation in the SRTP Acceleration Driver. This call is used to retrieve a previously submitted (via the write system call) SRTP packet from the driver. The parameter must be a pointer to a user-allocated buffer where the returned packet will be copied to. Note that depending on how the Stream was opening in the SRTP Acceleration Driver (blocking or non-blocking flags specified), this call may block if there are no packets available to be read. This function returns the length of the packet upon success, 0 if there are no packets available to be read, or -1 on error.
Figure 62.
SRTP Acceleration Driver High-Level API Data Path
SRTP Application
1. write (filp, srtp_acc_packet, length) 4. read (filp, buffer, packet_len)
User Space Kernel Space
2. Initialize Crypto API Operational Context Structure SRTP Driver
3. Submit Operation to QAT-AL 5. Return ciphered Data
19.6
High Level API Flow The following subsection describes the main usage scenario for the SRTP Acceleration Driver API.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 148
May 2009 Order Number: 320415-003US
API Overview for SRTP Acceleration Driver—IP Telephony Software
Note:
All variables used here are dummy variables created for this example. Also, example code does not employ any error checking.
19.6.1
Stream Establishment To open a new SRTP accelerated stream in blocking mode, open the device file with a new file descriptor. int *srtp_acc_stream; srtp_acc_stream = open(“/dev/srtp_acc_drv”, O_RDWR);
19.6.2
Removing a Stream close(srtp_acc_stream);
19.6.3
Configuring a SRTP Accelerated Stream Once the stream is configured, it may then be used to apply cryptographic functions to SRTP packets.
19.6.3.1
Encrypt/Decrypt Only 1. Initialize the stream context structure. This only needs to be completed once at the start of a new stream. srtp_acc_ctx_t stream_ctx; stream_ctx.cipher = SRTP_ACC_CIPHER_AES_ICM; stream_ctx.cipher_key_len = 16; stream_ctx.cipher_key = pointer_to_cipher_key; stream_ctx.operation = SRTP_ACC_SYM_OP_CIPHER; /*Perform cipher only */ stream_ctx.dir = RTP_ACC_SYM_OP_DIRECTION_ENCRYPT;
2. Configure the stream ioctl(session, SRTP_ACC_STREAM_CONFIG, &stream_ctx);
19.6.3.2
Authentication Only 1. Initialize the stream context structure. This only needs to be completed once at the start of a new stream. srtp_acc_ctx_t stream_ctx; stream_ctx.hash_func = SRTP_ACC_HASH_SHA1; /*type of hash algorithm to apply*/ stream_ctx.auth_key_len = 64; /*auth key length in bits */ stream_ctx.auth_key = pointer_to_auth_key; stream_ctx.auth_tag_len = 10; /*auth output length in bytes */ stream_ctx.operation = SRTP_ACC_SYM_OP_AUTH; /* Perform encryption only */
2. Configure the stream ioctl(session, SRTP_ACC_STREAM_CONFIG, &stream_ctx);
19.6.3.3
Encrypt/Decrypt and Authenticate 1. Initialize the stream context structure. This only needs to be completed once at the start of a new stream. srtp_acc_ctx_t stream_ctx; stream_ctx.cipher = SRTP_ACC_CIPHER_AES_ICM; stream_ctx.cipher_key_len = 16; stream_ctx.cipher_key = pointer_to_cipher_key; stream_ctx.hash_func = SRTP_ACC_HASH_SHA1; /*type of hash algorithm to apply*/ stream_ctx.auth_key_len = 64; /*auth key length in bits */
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 149
IP Telephony Software—API Overview for SRTP Acceleration Driver
stream_ctx.auth_key = 0x f7744d4d0da7881b; stream_ctx.auth_tag_len = 10; /*auth output length in bytes */ stream_ctx.operation = SRTP_ACC_SYM_OP_AUTH_CIPHER; /*cipher and auth */ stream_ctx.dir = RTP_ACC_SYM_OP_DIRECTION_ENCRYPT;
2. Configure the stream ioctl(session, SRTP_ACC_STREAM_CONFIG, stream_ctx);
3. Initialize the Operational Request data structure, must be repeated for each packet. srtp_acc_op_data_t *op_data; op_data->stream_id = stream_ctx->stream_id; op_data->data = *plaintext_data; /* pointer to input data */ op_data->encrypt_start = *start_enc; /* pointer to the start of the data to be *encrypted */ op_data->encrypt_len = 12; /* Length of data to be encrypted in bytes */ op_data->IV = *init_vector; /*pointer to the Initialization Vector */ op_data->auth_offset = 0 ; /* pointer to the start of the authorisation */ op_data->auth_len = 16; /* Length of data to be authenticated in bytes */
4. Add encrypt/decrypt operation to the SRTP Acceleration Driver and wait for ioctl to return. May be repeated for each packet travelling in the stream. ioctl(session, SRTP_ACC_CRYPTO_OP, op_data);
5. Close the stream and remove it from the session. ioctl(session, SRTP_ACC_STREAM_REMOVE, srtp_ctx->stream_id);
19.6.4
Performing a Cryptographic Operation To perform a cryptographic operation, the user must define an SRTP accelerated packet. Once this packet is populated, it may then be written to the SRTP Accelerated Stream. To complete the operation, the user may then read from the SRTP Accelerated Stream. 1. Initialize the SRTP accelerated packet structure. This needs to be completed for each packet to be encrypted. srtp_acc_packet_t packet; packet.stream_id = 0; /* internal data should be initialised to zero */ packet.encrypt_len = 84; packet.iv_len = 16; /* initialisation vector length */ packet.iv = IV; packet.auth_len = packet_len; packet.auth_tag_len = 10; packet.dir = SRTP_ACC_SYM_OP_DIRECTION_ENCRYPT; packet.data = pointer_to_packet_data;
2. Start the cryptographic operation. write(srtp_acc_stream, &packet, sizeof(srtp_acc_packet_t));
3. Complete the cryptographic operation. read(srtp_acc_stream, packet.data, packet_len + auth_tag_len); /* Note: the above will overide the original packet information */
19.6.5
Random Number Generation 1. Initialize the random number data structure. srtp_acc_rand_num_t *random_num; random_num->buffer = data; /*data buffer to store the resulting random num */
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 150
May 2009 Order Number: 320415-003US
API Overview for SRTP Acceleration Driver—IP Telephony Software
random_num->length = 30; /* length of random num to be generated in bytes */
2. Add the operation to the SRTP Acceleration Driver. ioctl(session, SRTP_ACC_RANDNUM_GEN, random_num);
19.7
Error Handling The SRTP Acceleration Driver does not provide a callback mechanism for errors. Instead it returns standard Linux character device driver error codes to the client when it encounters an error.
19.8
Key Assumptions None
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 151
IP Telephony Software—API Overview for SRTP Acceleration Driver
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 152
May 2009 Order Number: 320415-003US
API Overview for HSS I/O Access Library—IP Telephony Software
20.0
API Overview for HSS I/O Access Library
20.1
What’s New in this Chapter No updates in this release.
20.2
Control Path This section covers the sequence of events that are necessary for the various control scenarios.
20.2.1
Setup Sequence
20.2.1.1
Component Initialization The HSS I/O Access Library initialization API is the first entry point into this component. It only needs to be called once. This set of functions starts up the component and sets service-wide (HDLC and/or Voice) parameters.
20.2.1.2
Port Configure Functions This is the second set of functions that is called. They are used to set up the configuration information for a port, enable that port ,and also bring it down if required. There can be no channels enabled when bringing down a port. Figure 63 provides an overview of the configuration of an HSS port in the TDM I/O using the HSS Access Library.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 153
IP Telephony Software—API Overview for HSS I/O Access Library
Figure 63.
HSS Port Configuration High-Level API Flow Diagram
Voice Driver Application Level 1. icp_HssAccPortConfig (...) 3. icp_HssAccPortUp (...)
Access Layer
HSS I/O Access
PIU Message Handler
2. Configure PIU
Programmable I/O Unit (PIU)
4. Enable Port
Physical Interface HSS Port
Once an HSS port has been configured, one or more channels can be allocated with timeslots on that port. Figure 64 provides an overview of the allocation, configuration, and enabling of a channel for the Voice service. The API flow for the HDLC service is similar with the only difference being the use of the function icp_HssAccChannelHdlcServiceConfigure instead of icp_HssAccChannelVoiceServiceConfigure by the PPP driver.
20.2.1.3
Channel Configure This is the third set of functions that is called. It is used to set up the configuration information for the channel. A channel needs to be allocated first, then all of the channel configuration functions must be called before enabling the channel.
20.2.1.4
Channel Callback Register This is an optional set of functions that need only be called when using callback mode. It is used to register the callback function pointers for receive and receive free queue low, and transmit done processing. No data can pass after this call completes as a channel enable is still required. If only a polled mode of operation is being used, this step may be skipped.
20.2.2
Channel Up The enable channel function is used to activate a channel after it has been configured. This function has no effect on an active channel.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 154
May 2009 Order Number: 320415-003US
API Overview for HSS I/O Access Library—IP Telephony Software
Figure 64.
Voice Channel Configuration High-Level API Flow Diagram
Voice D river Application Level 1. 3. 5. 8.
icp_HssAccChannelAllocate (...) icp_HssAccChannelConfigure (...) icp_HssAccChannelVoiceServiceConfigure (...) icp_HssAccChannelUp (...)
H SS I/O Access
PIU M essage H andler
6. Configure Channel Queue
Access Layer
PIU Q M gr
2. Configure PIU 4. Configure PIU 7. Configure PIU 9. Enable TDM data flow
Program m able I/O Unit (PIU ) Physical Interface HSS Port
20.2.3
Channel Down The HSS I/O Access Library client may want to temporarily stop data passing on a channel but maintain its configuration and timeslot bindings. To do so, the channel disable function is used. Any HDLC packet or Voice sample that is in the middle of transmission will be completed before traffic is stopped. All receive data currently in the ring for that channel remains there until Buffer Retrieval is triggered by the client, see “Buffer Retrieval”.
20.2.4
Channel Delete If a channel is no longer required, it may be deleted with the channel delete function. This function requires the channel to be already disabled and removes all configuration info for a channel, including the timeslot to channel mapping (thus freeing up the timeslots for reuse).
20.2.5
Buffer Retrieval If a client wishes to stop all processing on a service, a service being either voice processing or data processing, then it makes a request to retrieve all of the buffers for each channel configured for that service.
Note:
A channel can be disabled and buffers can be retrieved for it without interfering with normal operations on other channels.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 155
IP Telephony Software—API Overview for HSS I/O Access Library
All buffers for each channel, including those in use by the Programmable I/O Unit will be chained together and returned. Retrieval of buffers for the last channel left for a specific service triggers the retrieval of all the buffers in the receive Free Queue for that service. Note:
All buffers for a particular service are only retrieved if all channels for that service are disabled. To handle an error scenario where the Free Queues were populated with buffers but consequently no channels were configured, it is possible to retrieve those buffers by passing in the maximum number of channels (which is an invalid channel ID) as an argument to the retrieve function.
20.2.6
Channel Bypass If a client wishes to set up a channel bypass, the first step is to configure one of the four available Gain control tables for the bypass. Once this is done, the bypass can be configured and enabled with source and destination channels. Channels used for a bypass are required to be enabled first. The HSS I/O Access client can set up up to 4 unidirectional bypasses. Each one can be set up with its own gain control table or can share the table with another bypass.
20.2.7
Component Un-Initialize If the HSS I/O Access Library component is no longer required, then the component un-initialize command is called. This command requires that all bypasses and channels be disabled and deleted, and all ports disabled. The command frees all system resources associated with this component.
20.3
Dependencies The HSS Access library is Operating System-agnostic. To achieve this it relies on the Operating System Abstraction Layer (OSAL) component providing a common set of APIs for OS related functionality such as memory allocation. The HSS Access library also depends on the Programmable I/O Unit (PIU) Message Handler to provide access to configuration messaging for the Programmable I/O Unit, and on the PIU QMgr component for management of the Software Queues used for Datapath communication with the Programmable I/O Unit.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 156
May 2009 Order Number: 320415-003US
API Overview for HSS I/O Access Library—IP Telephony Software
Figure 65.
HSS Access Library Dependencies Diagram
Client (Voice/PPP Driver)
HSS I/O Access Library
OS Services OSAL
PIU Queue Manager
PIU Message Handler
Programmable I/O Unit (PIU) A
20.4
B
Component A depends on Component B .
Error Handling The Programmable I/O Unit is capable of notifying the HSS I/O Access Library of error occurrences. Error notification is done using the PIU MH component. The Programmable I/O Unit sends an unsolicited message to the HSS I/O Access library. This message contains the error code for the error that just occurred. The HSS I/O Access library identifies the error, increments the appropriate counter, and uses the relevant registered callbacks to notify the client. Depending on the error, either both Voice and HDLC client may get notified or only one of them.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 157
IP Telephony Software—API Overview for HSS I/O Access Library
Figure 66.
HSS I/O Error Handling and Notification
Voice D river Application Level Error notification callback is called by Access Library
Access Layer
H SS I/O Access
PIU M essage Handler
Send unsolicited m essage to Access Library
Program m able I/O Unit Physical Interface HSS Port
§§
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 158
May 2009 Order Number: 320415-003US
API Overview for SSP I/O Access Library—IP Telephony Software
21.0
API Overview for SSP I/O Access Library The SSP I/O Access Library presents an API that can be used for both controlling and sending/receiving data on the SSP I/O Unit. In EP80579 IP Telephony software, this component is used by the Analog FXO/FXS Driver. Customers may wish to use this component to operate the SSP I/O Unit for other purposes.
21.1
What’s New in this Chapter No updates in this release.
21.2
Control Path The SSP I/O Unit Control Registers are used to program the baud rate, data length, frame format, data transfer mechanism, and port enabling. In addition, they permit setting the FIFO threshold that triggers an interrupt. The SSP I/O Access Library allows the client to control these registers. The control flow is shown in Figure 67.
21.2.1
Initialization / Un-Initialization
21.2.1.1
icp_SspAccInit() This API initializes the SSP Serial Port hardware to the user specified configuration. Then it enables the SSP I/O Unit. Once interrupt or polling mode is selected, the mode cannot be changed via the interrupt enable/disable function. The init function must be called again to change it.
21.2.1.2
icp_SspAccUnInit() This API disables the SSP Serial Port hardware. The client must call the init function again if they wish to enable the SSP.
21.2.2
Configuration The client initializes and configures SSP with a call to icp_SspAccInit(). The client can subsequently choose to change a configuration item with the API provided for each item. The following APIs are provided: • icp_SspAccFrameFormatSelect() • icp_SspAccDataSizeSelect() • icp_SspAccClockSourceSelect() • icp_SspAccSerialClockRateConfigure() • icp_SspAccRxFifoIntEnable() • icp_SspAccSpiSclkPolaritySet() • icp_SspAccSpiSclkPhaseSet() • icp_SspAccMicrowireControlWordSet()
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 159
IP Telephony Software—API Overview for SSP I/O Access Library
• icp_SspAccSspPortStatusSet()
21.2.3
Interrupt Enabling / Disabling The icp_SspAccInit() enables interrupts. If the client subsequently wants to disable and re-enable interrupts, the following APIs are provided: • icp_SspAccRxFifoIntDisable() • icp_SspAccTxFifoIntEnable() • icp_SspAccTxFifoIntDisable() • icp_SspAccLoopbackEnable()
21.2.4
Statistics Statistics for the SSP I/O Access Library can be retrieved and shown by using the following APIs: • icp_SspAccStatsGet() • icp_SspAccStatsReset() • icp_SspAccShow()
21.2.5
FIFO Thresholds The icp_SspAccInit() API sets the SSP FIFO thresholds. The client can subsequently choose to change these thresholds by using the following APIs: • icp_SspAccTxFifoThresholdSet() • icp_SspAccRxFifoThresholdSet()
21.2.6
Monitoring The client may check the current status of the SSP I/O Unit and the FIFOs by using the following APIs: • icp_SspAccSspIdleCheck() • icp_SspAccTxFifoLevelGet() • icp_SspAccRxFifoLevelGet() • icp_SspAccRxFifoOverrunCheck()
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 160
May 2009 Order Number: 320415-003US
API Overview for SSP I/O Access Library—IP Telephony Software
Figure 67.
SSP I/O Access Library Initialization Control Flow
Client
Application Level
1.
icp_SspAccInit
(...)
2.
icp_SspAccUninit (...)
Access Layer
SSP I/O Access Library
SSP I/O Unit Physical Interface External Interface
21.3
Data Path This section gives an overview of the data flow within the SSP I/O Access Library. Both Polled and Interrupt mode are supported. The APIs icp_SspAccTxFifoHitLowThresholdCheck and icp_SspAccRxFifoHitHighThresholdCheck are used to check FIFO thresholds for polled mode only. In interrupt mode, interrupts are used to indicate the FIFO thresholds. Figure 68 gives a high level view of the SSP I/O Access Library data flow.
21.3.1
Tx
21.3.1.1
icp_SspAccTxFifoHitLowThresholdCheck() This method is only used in polled mode. It returns the following information: either the Tx FIFO threshold is exceeded OR the Tx FIFO threshold is hit/below. This indicates to the client if they should submit data or not.
21.3.1.2
icp_SspAccFifoDataSubmit() This method inserts a specified amount of data from a client supplied buffer into the FIFO to be transmitted by the hardware.
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 161
IP Telephony Software—API Overview for SSP I/O Access Library
21.3.2
Rx
21.3.2.1
icp_SspAccRxFifoHitHighThresholdCheck() This method is only used in polled mode. It returns whether the Rx FIFO level is below the threshold or is hit/above. This indicates to the client if they should receive data or not.
21.3.2.2
icp_SspAccFifoDataReceive() This API extracts a specified amount of data from the FIFO already received by the hardware into a client provided buffer.
Figure 68.
SSP I/O Access Library Data Flow
Client
Application Level Polled only - icp_SspAccTxFifoHitLowThresholdCheck (...) Tx { 2. 1.icp_SspAccFifoDataSubmit (...) 3. Polled only - icp_SspAccRxFifoHitHighThresholdCheck (...)
Rx { 4. icp_SspAccFifoDataReceive (...)
Access Layer
SSP I/O Access Library
SSP Control Registers Physical Interface External Interface
21.4
Dependencies The SSP I/O Access Library has dependencies on: • OSAL - used for Operating System calls. OSAL is used primarily for logging in the SSP I/O Access Library. • SSP I/O Unit - SSP I/O Access Library is dependent on SSP I/O Unit.
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 162
May 2009 Order Number: 320415-003US
API Overview for SSP I/O Access Library—IP Telephony Software
Figure 69.
SSP I/O Access Library Dependencies
C lient
S S P I/O A ccess Library
OSAL
S S P I/O U nit
21.5
Key Assumptions None.
21.6
Error Handling Rx Overrun errors can be checked by using the icp_SspAccRxFifoOverrunCheck() function or registering a callback to be notified when this condition occurs. Other errors are handled by using the return values of functions to indicate the error.
§§
May 2009 Order Number: 320415-003US
Intel® EP80579 Software for IP Telephony Applications on Intel® QuickAssist Technology PG 163
